# API trigger Trigger your agent directly from you apps or websites with the API trigger. ## Create trigger * API triggers are created inside **agent projects**. * Each API trigger must have a **unique name** and **unique key** within the project. * The trigger key is **case-insensitive** and can be customised to match an identifier meaningful for your application. > **Note:** Make sure the key is something easy to reference when making API calls.

### Create API key API triggers are secured by [API keys](https://chathive.app/api_key) that are managed by your organization. * The API key must have at least the permission `project.trigger`

#### Best practices * Only grant the API key access to the specific projects it needs. * Limit the permissions to only what’s required. ## Send a request To call your trigger, send a **POST** request to its unique URL. ``` https://api.chathive.app/api/v1.0/project/:projectId/trigger/:key ``` This URL can be found in the trigger settings, or construct it using your project ID and trigger key. Optionally, include a JSON body with instruction and configuration. The body will be passed to your filters. * Be processed by the trigger’s filters. * Be passed to your agent as input. The api key you created must be included in the headers of the post request. ```url curl -X POST "https://api.chathive.app/api/v1.0/project/:projectId/trigger/:key" \ -H "Content-Type: application/json" \ -H "x-api-key: YOUR_API_KEY" \ -d '{ "key": "value" }' ``` ### Request body You can include a body with the trigger to give your AI agent more context when executing your request. The following fields are supported:

Status	Value	Description
instruction	string \| object	Instruction that will be provided to the agent, can be a string or object
sessionId	string	Unique string generated by you to distinguished conversations. When sessionId changes all previous conversation context will be lost and it will be like a new conversation has started
environment	string	Identify in the analytics from where the request came. Default: "api"
language	ISO 639-1 language code	The current language of your website visitor. Must be ISO 639-1
timezone	string	Accepted but request timed out before agent completed it's task. Is only returned when `wait for response` has been enabled and request took to long.
customer	customer data	Data to identify the current customer.
context	record<string, Boolean \| number \| string \| undefined>	Extra context that should be used by the agent to provide accurate answers.

### Response

Status	Description
200	Request has been accepted and agent completed it's task. Body will be included with final response.
202	Request has been accepted but agent is stil executing the task. Is only returned when `wait for response` has been disabled. /
400	Event has been dropped. The body doesn't match the filters
404	Trigger does not exist Trigger has been paused Trigger has been deleted
408	Accepted but request timed out before agent completed it's task. Is only returned when `wait for response` has been enabled and request took to long.

## Advanced Settings ### Customize trigger key Customize the trigger key used in the API to clearly indicate which trigger is being executed in your code. Some key guidelines: * Must be unique within your organization. * Can only contain the following characters: `a-zA-Z0-9_-`.

### Ignore duplicate triggers To prevent executing the same trigger multiple times and waisting AI credits, you can enforce it to only execute triggers with a unique body. Once this is turned on, every trigger that is executed with the same body will be dropped. This will only check triggers that are executed with a body.

### Wait for response For tasks that take a long time (minutes, hours, or days), you can configure the trigger to immediately return a $$(202)$$ success response once the task is accepted. This way, your server doesn't have to wait for the task to finish.

--- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://developers.chathive.app/triggers/api-trigger.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.