Skip to main content

​
API Triggers

API Triggers empower developers to programmatically activate Relevance AI agents through the Relevance AI API, enabling you to integrate AI agents into your applications, services, and automated workflows.
The Relevance AI API is officially supported for triggering Agents and Tools only. All other API usage is currently unsupported.

​
Key Features

  • Programmatic Control: Initiate agent tasks directly through HTTP requests
  • Flexible Integration: Works with any programming language capable of making HTTP requests
  • Custom Workflows: Build sophisticated systems where agents respond to events in your custom applications
  • Context Management: Send messages to new or existing conversations with full context control

​
How API Triggers Work

API Triggers expose an endpoint that accepts HTTP POST requests. When you send a request with a message and your agent ID, the agent processes the message and executes its configured tasks. The agent can initiate new conversations or continue existing ones based on the context you provide.
When triggering an agent via API, the response is not returned directly. Instead, the result must be sent to a specified destination, such as uploading the final output to Google Sheets.

​
Setting Up API Triggers

  1. Navigate to the Agents page and select the agent you want to configure
  2. In the sidebar on the left, go to “Triggers” and click the “Add trigger” button
  3. Under the “Build your own triggers” section, click the “API” trigger
The API trigger configuration popup displays the endpoint, a button to generate your API key, and a pre-filled request body with your agent_id. Code examples in cURL, JavaScript, and Python are also provided.
Make sure to save your API key somewhere safe - once generated, you won’t be able to view it again. However, you can regenerate one at any time.

​
API Reference

Endpoint: 
POST https://api-f1db6c.stack.tryrelevance.com/latest/agents/trigger
The endpoint URL differs based on your organization’s region. The example above shows the AU region endpoint. When you set up your API trigger in the UI, the correct endpoint for your region will be displayed in the configuration popup.
Request Body: 
{
  "message": {
    "role": "user",
    "content": "Hello"
  },
  "agent_id": "[YOUR_AGENT_ID_GOES_HERE]"
}

​
Code Examples

cURL 
curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: [YOUR_API_KEY]" \
  -d '{"message":{"role":"user","content":"Hello"},"agent_id":"[YOUR_AGENT_ID_GOES_HERE]"}' \
  https://api-f1db6c.stack.tryrelevance.com/latest/agents/trigger
JavaScript (Fetch) 
fetch('https://api-f1db6c.stack.tryrelevance.com/latest/agents/trigger', {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "[YOUR_API_KEY]"
  },
  body: JSON.stringify({
    message: { role: "user", content: "Hello" },
    agent_id: "[YOUR_AGENT_ID_GOES_HERE]"
  })
});
Python (requests) 
import requests
import json

requests.post(
  'https://api-f1db6c.stack.tryrelevance.com/latest/agents/trigger',
  headers={
    "Content-Type": "application/json",
    "Authorization": "[YOUR_API_KEY]"
  },
  data=json.dumps({
    "message": { "role": "user", "content": "Hello" },
    "agent_id": "[YOUR_AGENT_ID_GOES_HERE]"
  })
)

​
Best Practices

  • Error Handling: Implement robust error handling in your API integration code
  • Rate Limiting: Be mindful of API rate limits and implement appropriate throttling
  • Security: Store API keys securely and use environment variables rather than hardcoding them
  • Monitoring: Set up monitoring for your API trigger usage to detect issues early
  • Testing: Thoroughly test your API trigger implementation in a development environment before deploying to production

​
Frequently asked questions (FAQs)

You can use any programming language capable of making HTTP requests - the API is language-agnostic.
Yes, API usage is subject to rate limits based on your subscription plan. Please refer to your plan details for specific limitations.
Absolutely! API Triggers work well with serverless architectures like AWS Lambda, Google Cloud Functions, or Azure Functions.
API Triggers use industry-standard authentication and encryption. All API requests must be authenticated with your API key, and all data is transmitted over HTTPS.