Triggered Routines via the API

Start a published routine from an external system with an org API key and a JSON payload.

External systems can start a published routine by calling the public API with an org API key. The payload you send is fed verbatim into the agent's starting context — interpretation lives entirely in the routine's authored instructions. There is no platform-side schema, mapping, or configuration.

The trigger call

curl -X POST "https://api.headways.ai/v1/routines/<routineId>/runs" \
  -H "Authorization: Bearer sk_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-8412-sync" \
  -d '{"payload": {"salesforce_contact_id": "0035g000001Xyz"}}'

Returns 201 {runId, status}. The Idempotency-Key is required; retrying with the same key within 24h returns the original run, never a duplicate.

The payload contract

• Any JSON object, ≤ 32 KB serialized. Arrays and scalars are rejected.

• Appended to the run's first message as a fenced JSON block, exactly as you sent it.

• The routine's instructions define what the fields mean. Write instructions like:

  The payload contains a Salesforce contact ID (salesforce_contact_id). Look the contact up and summarize open opportunities.

  The payload names an equipment ID and site. Inspect that pump's maintenance history at that site.

• A payload the instructions never mention is harmless — the run starts normally and ignores it.

• Omitting payload entirely is fine: the run starts with the instruction alone.

Because interpretation is instructions-only, the same routine can accept different payload shapes on different calls. If you change the caller's payload shape, update the routine's instructions to match — nothing else to configure.

Service-account keys

A key assigned to a service-account member (created under Settings → API keys) runs with that account's own monthly budget and only org-level connections. If the routine pins a connector whose org connection is missing, revoked, or not granted to the service account, the trigger is rejected up front with 422 CONNECTOR_NOT_CONFIGURED (the missing connectors are named in the error body).

Error codes