​
API Triggers for Agents

API Triggers empower developers to programmatically activate Relevance AI agents, creating powerful automation workflows that integrate seamlessly with your existing systems and applications.

​
Overview

API Triggers allow you to initiate agent tasks directly through the Relevance AI API, enabling programmatic control over when and how your agents are activated. This capability is particularly valuable for developers and technical teams who want to incorporate AI agents into their applications, services, or automated workflows. With API Triggers, you can build sophisticated systems where your agents respond to events in your custom applications, process data from proprietary systems, or execute tasks based on complex business logic that you define.

​
How API Triggers Work

API Triggers function by exposing endpoints in the Relevance AI API that allow you to:
  1. Initiate a new conversation with an agent
  2. Send messages to an existing conversation
  3. Provide context and data for the agent to process
  4. Receive responses and actions taken by the agent
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 in your Agent

To set up and use API Triggers for your agents:
  1. Navigate to the Agents page and choose the specific agent you want to setup the custom API trigger for.
  2. In the Build tab, click on “Triggers”
  3. Select “API Trigger” from the available trigger options
  4. Configure the API Trigger settings according to your requirements
  5. Save your configuration

​
Setting up your API trigger in your Codebase

POST https://api-f1db6c.stack.tryrelevance.com/latest/agents/trigger

​
Save your API key somewhere safe

You’ll need to generate an API key (Authorization Token) to authenticate your requests. 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.
To find your Agent ID, you can ask your agent directly in the chat (“What is your agent ID?”). Or, you can check the URL. When your agent is open, look at the URL in your browser. The agent ID is the second long code after the region code in the URL structure: Example: https://app.relevanceai.com/agents/{region}/{project_id}/{agent_id}/edit

​
Request Body

{
  "message": {
    "role": "user",
    "content": "Hello"
  },
  "agent_id": "[YOUR_AGENT_ID_GOES_HERE]"
}

​
Example Usage (Choose a method your prefer)

​
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 for API Triggers

  1. Error Handling: Implement robust error handling in your API integration code
  2. Rate Limiting: Be mindful of API rate limits and implement appropriate throttling
  3. Security: Store API keys securely and use environment variables rather than hardcoding them
  4. Monitoring: Set up monitoring for your API trigger usage to detect issues early
  5. Testing: Thoroughly test your API trigger implementation in a development environment before deploying to production
Webhook Triggers - Use webhooks to trigger your agents from third-party services that support outbound webhooks. Integration Triggers - Connect your agents to popular third-party services using our prebuilt integration triggers.

​
Frequently Asked Questions