API reference › Resources
Triggers
Schedule agents, create webhooks and react to app events.
A trigger runs an agent without anyone sending a message. Each run creates a conversation with the source trigger or webhook. To create, change, run or delete triggers, you need to be able to edit the agent. The trigger runs with the account of whoever created it.
The Trigger object#
{
"id": "trg_6a2c4e8b1d3f",
"agentId": "agt_8f3a2b1c9d0e",
"name": "8 a.m. briefing",
"type": "schedule",
"schedule": { "kind": "cron", "expression": "0 8 * * 1-5" },
"timezone": "America/Sao_Paulo",
"prompt": "Write the daily briefing for today and email it to me.",
"model": null,
"enabled": true,
"lastRunAt": "2026-10-27T11:00:04.000Z",
"nextRunAt": "2026-10-28T11:00:00.000Z",
"mine": true,
"createdAt": "2026-10-20T15:00:00.000Z"
}type | Type-specific fields |
|---|---|
schedule | schedule, timezone |
once | runAt, timezone |
webhook | webhookSecret (only for whoever created the trigger or can edit the agent) |
app | app: { event, connectorId, params } |
GET/api/triggers#
Lists the triggers of the agents you can see.
| Query | Description |
|---|---|
agentId | Only one agent's triggers. |
Response: { "triggers": [Trigger, ...] }.
POST/api/triggers#
| Field | Type | Description |
|---|---|---|
agentId | string | Required. |
type | schedule, once, webhook, app | Required. |
name | string, 1 to 80 | Required. |
prompt | string, up to 4,000 | What the agent should do. Required, except with passRawData. Can reference event fields: {{email}}, {{customer.name}}. |
model | string or null | A model just for this trigger (openrouter/auto is DoubleX Auto). Without it, the agent's model is used. |
timezone | string | IANA time zone for schedule and once. Default America/Sao_Paulo. |
passRawData | boolean | webhook and app: the agent receives only the event JSON, with no prompt. |
schedule | object | For schedule. See below. |
runAt | ISO 8601 date | For once. Must be in the future. |
app | object | For app: { "event", "connectorId", "params" }. |
Scheduled#
schedule accepts one of these forms:
| Form | Example |
|---|---|
| Cron (5 fields, minimum interval of 5 minutes) | { "kind": "cron", "expression": "0 8 * * 1-5" } |
| Interval in minutes (5 to 10,080) | { "kind": "interval", "minutes": 30 } |
| Daily | { "kind": "daily", "time": "08:00" } |
Weekly (weekday from 0, Sunday, to 6) | { "kind": "weekly", "weekday": 1, "time": "09:30" } |
curl -X POST https://doublex.ai/api/triggers \
-H "Authorization: Bearer $DOUBLEX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"agentId": "agt_8f3a2b1c9d0e",
"type": "schedule",
"name": "8 a.m. briefing",
"prompt": "Write the daily briefing for today and email it to me.",
"schedule": { "kind": "cron", "expression": "0 8 * * 1-5" },
"timezone": "America/Sao_Paulo"
}'Webhook#
{ "agentId": "agt_8f3a2b1c9d0e", "type": "webhook", "name": "New lead", "prompt": "Qualify the lead {{name}} ({{email}})." }The response includes the webhookSecret. The URL is https://doublex.ai/api/webhooks/<trigger id>. See how to call it in Webhooks.
App event#
{
"agentId": "agt_2b7e4c6a1f3d",
"type": "app",
"name": "Order by email",
"prompt": "New order from {{from}}: {{subject}}. Log it in the orders spreadsheet.",
"app": { "event": "gmail.new_email", "connectorId": "con_7a9b1c3d5e2f", "params": { "query": "subject:order" } }
}event | Parameters | Fields for the prompt |
|---|---|---|
gmail.new_email | query | from, to, subject, date, snippet, body, attachments, labels |
google-calendar.new_event | calendar_id | title, start, end, location, description, organizer, attendees, link |
google-calendar.event_starting | calendar_id, minutes_before | the calendar fields and minutes_until |
google-drive.new_file | folder | name, mime_type, link, created_time, owner |
google-sheets.new_row | spreadsheet (required), sheet | row_number, row, sheet |
The connector must be for the same service as the event, and you must be able to use it. The platform checks the app every two minutes; the first check only sets the starting point.
Response 201: { "trigger": Trigger }. 400 errors explain the problem: invalid or too-frequent cron, a date in the past, an invalid time zone, an unknown event or parameter, the wrong connector.
GET/api/triggers/apps#
The available app events, with their parameters and fields, and your Google accounts that can be used:
{
"events": [{ "id": "gmail.new_email", "service": "gmail", "params": [{ "name": "query", "type": "text" }], "fields": ["from", "subject", "..."] }],
"accounts": [{ "id": "con_7a9b1c3d5e2f", "service": "gmail", "label": "[email protected]", "status": "connected", "mine": true }]
}POST/api/triggers/generate-cron#
Converts a phrase into cron.
| Field | Type |
|---|---|
description | string, 2 to 300. For example, "every Friday at 5:30pm". |
timezone | string, optional |
{ "cron": "30 17 * * 5", "description": "Every Friday at 5:30 PM" }If description is already a valid cron, it comes straight back. Otherwise, an AI model does the conversion and consumes credits. Errors: 422 if the phrase doesn't turn into a valid schedule, 402 with no credits.
PATCH/api/triggers/{id}#
Changes name, prompt, model (null goes back to the agent's model), passRawData, timezone, enabled, schedule, runAt or app. The type can't change: to switch it, delete the trigger and create a new one.
curl -X PATCH https://doublex.ai/api/triggers/trg_6a2c4e8b1d3f \
-H "Authorization: Bearer $DOUBLEX_API_KEY" \
-H "Content-Type: application/json" \
-d '{"enabled": false}'Response: { "trigger": Trigger }.
POST/api/triggers/{id}/run#
Runs the trigger now, in the background.
schedule,onceandwebhooktriggers: response202{ "started": true }. Follow the run inGET /api/tasks?agentId=....apptriggers: checks the app right away and responds200{ "checked": true, "found": 2 }.
Errors: 402 with no active plan (plan_required), no credits (no_credits) or the agent out of monthly budget (agent_budget); 409 if the previous run hasn't finished yet; 503 if the agent has no model available.
DELETE/api/triggers/{id}#
Response: { "ok": true }.
POST/api/webhooks/{id}#
The public URL for webhook triggers. It doesn't use an API key: the secret goes in the x-webhook-secret header. Responds 202 { "accepted": true }. See Webhooks.