How-to guidesAgents

Start runs automatically

Run an agent every morning, or whenever your system calls

A trigger starts a durable run with nobody watching. Two kinds:

  • A schedule fires on a cron expression or a fixed interval. A morning digest, an hourly reconciliation.
  • A webhook gives you a URL. Your system POSTs to it and a run starts with your payload.

Both start exactly the run you would have started by hand, so everything in Run an agent asynchronously applies - including the publish gate, which a trigger does not bypass. An agent whose configuration has not passed its gate does not fire.

Triggers are in beta and enabled per workspace alongside durable runs.

A schedule

POST
/v1/agents/:agent_id/triggers
1curl -X POST https://api.speechify.ai/v1/agents/agent_01jqr8x9zg5k2m3n4p5q6r7s8t/triggers \
2     -H "Authorization: Bearer <token>" \
3     -H "Content-Type: application/json" \
4     -d '{
5  "type": "schedule",
6  "name": "string",
7  "run": {
8    "instruction": "string"
9  }
10}'
Try it

Set either schedule.cron or schedule.interval_seconds, not both. A cron takes an optional IANA timezone - Europe/Berlin keeps “9am” at 9am across a daylight-saving change, which UTC does not.

Read next_fire_at and last_fired_at back on the trigger to see whether it is actually firing. A schedule that has quietly stopped looks exactly like one that has not fired yet unless you check.

A webhook

Create it with type: "webhook", and the response carries two things you only get once:

  • fire_path - the URL your system POSTs to.
  • secret - the fire token, returned once. Copy it now; it cannot be read back, only rotated by recreating the trigger.
POST
/v1/agent-triggers/:trigger_id/fire
1curl -X POST https://api.speechify.ai/v1/agent-triggers/trigger_01jqr8x9zg5k2m3n4p5q6r7s8t/fire \
2     -H "Authorization: Bearer <token>" \
3     -H "Content-Type: application/json" \
4     -d '{}'
Try it

Authenticate with the fire token as Authorization: Bearer <secret> - not your API key. The JSON body lands in the run as its payload variable, so the agent’s instruction can refer to it.

Send an Idempotency-Key (or Speechify-Delivery-Id) header. Delivery systems retry, and without a key a retry starts a second run that does the work twice.

Editing rather than recreating

PATCH
/v1/agents/:agent_id/triggers/:trigger_id
1curl -X PATCH https://api.speechify.ai/v1/agents/agent_01jqr8x9zg5k2m3n4p5q6r7s8t/triggers/trigger_01jqr8x9zg5k2m3n4p5q6r7s8t \
2     -H "Authorization: Bearer <token>" \
3     -H "Content-Type: application/json" \
4     -d '{}'
Try it

Change the schedule, the instruction or the name in place. Recreating a webhook trigger mints a new fire token, which breaks whoever is calling the old URL - so retime and reword through a PATCH, and keep delete for triggers you actually want gone.

A PATCH replaces each nested object it carries, so send back the whole run object, not just the field you are changing.

Pause one without deleting it by patching enabled: false.

Next