> For the complete documentation index, see [llms.txt](https://developers.chathive.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.chathive.app/triggers/api-trigger.md).

# 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.

<figure><img src="/files/rqusTIYyCio519WkAla0" alt=""><figcaption></figcaption></figure>

### 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`

<div align="left"><figure><img src="/files/jlmdVjs7Tp3FQWTR5uUp" alt="" width="375"><figcaption></figcaption></figure></div>

#### 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.oniroco.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.oniroco.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:

<table><thead><tr><th width="190.47210693359375">Status</th><th width="174.94775390625">Value</th><th>Description</th></tr></thead><tbody><tr><td>instruction<br></td><td>string | object</td><td>Instruction that will be provided to the agent, can be a string or object</td></tr><tr><td>sessionId<br><br><br></td><td>string<br><br><br></td><td>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</td></tr><tr><td>environment<br></td><td>string<br></td><td>Identify in the analytics from where the request came. Default: "api"</td></tr><tr><td>language<br></td><td><a href="https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes">ISO 639-1 language code</a></td><td>The current language of your website visitor. Must be <a href="https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes">ISO 639-1 </a></td></tr><tr><td>timezone<br><br><br></td><td>string<br><br><br></td><td>Accepted but request timed out before agent completed it's task. Is only returned when <code>wait for response</code> has been enabled and request took to long.</td></tr><tr><td>customer</td><td><a href="/pages/mWLnkjQXMREDYDh6K2jy#customer-data">customer data</a></td><td>Data to identify the current customer.</td></tr><tr><td>context<br><br></td><td>record&#x3C;string, Boolean | number | string | undefined></td><td>Extra context that should be used by the agent to provide accurate answers. <br></td></tr></tbody></table>

### Response

<table><thead><tr><th width="190.47210693359375">Status</th><th>Description</th></tr></thead><tbody><tr><td>200<br></td><td>Request has been accepted and agent completed it's task.<br>Body will be included with final response.</td></tr><tr><td>202</td><td>Request has been accepted but agent is stil executing the task. Is only returned when  <code>wait for response</code> has been disabled. /</td></tr><tr><td>400</td><td>Event has been dropped. The body doesn't match the filters</td></tr><tr><td>404<br><br></td><td><ul><li>Trigger does not exist</li><li>Trigger has been paused</li><li>Trigger has been deleted</li></ul></td></tr><tr><td>408<br><br><br></td><td>Accepted but request timed out before agent completed it's task. Is only returned when <code>wait for response</code> has been enabled and request took to long.</td></tr></tbody></table>

## 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_-`.

<figure><img src="/files/tPM47zN7CPFbeVOPy5rt" alt=""><figcaption></figcaption></figure>

### 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.

<figure><img src="/files/UNvmnaVhJjLk7B9WE91k" alt=""><figcaption></figcaption></figure>

### Strict body

When you don't have control on how the [request body](#request-body) is send to the trigger. You can disable the strict body option. This will pass the request body completely to the AI agent. \
We recommend to use strict body as much as possible.

### 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.

<figure><img src="/files/nzejGSkcF4kA8ceDZSHI" alt=""><figcaption></figcaption></figure>