API Reference#

Authentication#

We use API keys to authenticate requests. Pass your key in the ttr-api-keyheader header (or as Authorization: Bearer ttr_…). Every endpoint below accepts it, scoped to the key's project; the dashboard uses a session cookie for the same endpoints.

The API is available at https://api.timetriggers.io/

Endpoints#

Triggers#

• {ANY METHOD} /schedule — schedule a trigger
• DELETE /cancel — cancel a trigger
• POST /declare — declare the desired set of triggers for a tag; the server adds, updates and cancels to converge
• POST /bulk — transactional batch of upserts (by custom key) and cancels

Both one-shot triggers and recurring triggers (CRON generators) go through the same /schedule endpoint — the ttr-scheduled-atheader header decides which kind. See Recurring triggers.

Rescheduling is done by calling /schedule again with a ttr-trigger-idheader or ttr-custom-keyheader header. See Edit a trigger.

Reading back triggers and executions#

• GET /jobs — list triggers (filters: status, id, title, customKey, tag)
• GET /jobs/{id}/executions — every attempt of one trigger
• GET /executions — executions across triggers (filters: jobId, customKey, jobStatus, executionStatus, httpStatus, deadLetterOnly)
• POST /jobs/{id}/executions — replay a trigger now

See Retries & timeouts for the reconciler pattern: find executions that gave up, replay them.

Policies#

• GET | POST /tag-policies, PUT | DELETE /tag-policies/{id} — per-tag throughput, concurrency, request timeout and retry policy
• GET | PUT /project/retry-policy — the project's default retry policy for triggers no tag policy covers

Retries#

Triggers without a tag policy follow the project's default retry policy — out of the box, three attempts with exponential backoff from 30 seconds, on network errors only. Before September 2026 such triggers were never retried: one transient network error was final. A tag policy or per-trigger ttr-retry-*header headers take precedence. Everything about retries, timeouts and failure diagnostics is on Retries & timeouts.

OpenAPI#

The full specification, generated from the server's own route definitions, is available as a rendered page at /docs/api-spec and as JSON at two stable URLs:

• https://timetriggers.io/openapi.json
• https://api.timetriggers.io/openapi/json

Swagger UI for the live API is at https://api.timetriggers.io/docs.