DoubleX AgentesDocs

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#

JSON
{
  "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"
}
typeType-specific fields
scheduleschedule, timezone
oncerunAt, timezone
webhookwebhookSecret (only for whoever created the trigger or can edit the agent)
appapp: { event, connectorId, params }

GET/api/triggers#

Lists the triggers of the agents you can see.

QueryDescription
agentIdOnly one agent's triggers.

Response: { "triggers": [Trigger, ...] }.

POST/api/triggers#

FieldTypeDescription
agentIdstringRequired.
typeschedule, once, webhook, appRequired.
namestring, 1 to 80Required.
promptstring, up to 4,000What the agent should do. Required, except with passRawData. Can reference event fields: {{email}}, {{customer.name}}.
modelstring or nullA model just for this trigger (openrouter/auto is DoubleX Auto). Without it, the agent's model is used.
timezonestringIANA time zone for schedule and once. Default America/Sao_Paulo.
passRawDatabooleanwebhook and app: the agent receives only the event JSON, with no prompt.
scheduleobjectFor schedule. See below.
runAtISO 8601 dateFor once. Must be in the future.
appobjectFor app: { "event", "connectorId", "params" }.

Scheduled#

schedule accepts one of these forms:

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

JSON
{ "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#

JSON
{
  "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" } }
}
eventParametersFields for the prompt
gmail.new_emailqueryfrom, to, subject, date, snippet, body, attachments, labels
google-calendar.new_eventcalendar_idtitle, start, end, location, description, organizer, attendees, link
google-calendar.event_startingcalendar_id, minutes_beforethe calendar fields and minutes_until
google-drive.new_filefoldername, mime_type, link, created_time, owner
google-sheets.new_rowspreadsheet (required), sheetrow_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:

JSON
{
  "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.

FieldType
descriptionstring, 2 to 300. For example, "every Friday at 5:30pm".
timezonestring, optional
JSON
{ "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.

Terminal
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, once and webhook triggers: response 202 { "started": true }. Follow the run in GET /api/tasks?agentId=....
  • app triggers: checks the app right away and responds 200 { "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.