API overview#

The TimeTriggers API schedules HTTP requests to fire later, once or on a cron schedule. Every endpoint lives under one base URL:

https://api.timetriggers.io

Authentication#

All public endpoints require authentication, normally an API key; only the OpenAPI spec is open. You create keys in the dashboard — see API keys. A key looks like ttr_ followed by 48 hex characters.

Send the key in one of two ways:

• ttr-api-keyheader — accepted by every public endpoint, and the only option for /schedule and /cancel.
• Authorization: Bearer YOUR_API_KEY — accepted by /declare, /bulk and /tag-policies only.

curl -X POST https://api.timetriggers.io/schedule \
  -H "ttr-api-key: YOUR_API_KEY" \
  -H "ttr-url: https://example.com/webhooks/reminder" \
  -H "ttr-scheduled-at: 2030-01-01T09:00:00Z" \
  -H "Content-Type: application/json" \
  -d '{"reminderId": 42}'

curl https://api.timetriggers.io/tag-policies \
  -H "Authorization: Bearer YOUR_API_KEY"

Call the API from your server#

The API is meant for server-to-server calls. It doesn't allow cross-origin requests from your web pages, so browsers block them; the only endpoint a browser on any site can read is the OpenAPI spec. Your API key is a secret: keep it on your backend and never ship it in front-end code. Code examples that use fetch are meant for server-side JavaScript (Node.js, Deno, Bun, edge functions).

Endpoints#

/schedule is configured with ttr- headers; the rest of your request (method, headers, body) is what gets sent to the target. /declare, /bulk and /tag-policies take JSON bodies (send Content-Type: application/json). Successful responses are JSON, except DELETE /cancel, which returns 204 with no body.

One-shot or recurring#

/schedule picks the kind of trigger from ttr-scheduled-atheader: a date such as 2030-01-01T09:00:00Z or now | add 1h creates a one-shot trigger, and cron(...) creates a recurring trigger — see Recurring triggers. Items sent to /declare and /bulk work the same way through their scheduledAt field.

Changing and cancelling triggers#

• Reschedule by calling /schedule again with ttr-trigger-idheader or ttr-custom-keyheader — see Edit a trigger. You can also send an item with the same customKey to /bulk, or include it in the full list you send to /declare for its tag (anything you leave out of that list is cancelled). Rescheduling by trigger ID only works through /schedule.
• Cancel one trigger with /cancel, many at once with the cancels list of /bulk (by ID, custom key or tag), or let /declare cancel the tagged triggers you leave out of its list.

Reading trigger status and results#

No endpoint you can call with an API key returns a trigger's status, its execution history or the response your target sent. You see all of that in the dashboard, on the triggers list, the trigger page and the executions page. TimeTriggers doesn't call you back with the outcome either: if your system needs it, record it in the endpoint that receives the trigger.

• Keep the identifiers. Store the triggerId returned by /schedule (or the id of each operation returned by /declare and /bulk), or use your own custom key. You need one of them to reschedule or cancel later.
• Keep your recurring definitions. The cron expression and time zone of a recurring trigger can't be read back after creation, through the API or in the dashboard.
• Don't probe with /cancel. It cancels every trigger that is still registered, skipped or retrying (see Which triggers can be cancelled), so you can't use it to check a trigger's status.

Dashboard-only endpoints#

The spec also lists the endpoints the dashboard itself uses: /keys, /keys/{id}, /jobs, /jobs/{id}/executions and /executions. They only accept a dashboard session (see Signing in) and return 401 Unauthorized when called with an API key, in either header. They are not part of the public API.

OpenAPI specification#

The full API is described by an OpenAPI 3.1 document:

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

• It is public: no API key needed. It is served with Access-Control-Allow-Origin: *, so you can fetch it from anywhere.
• Use the exact URL: a trailing slash or a query string returns 404.
• A readable version of the same spec is at Full spec.
• The API host also serves an interactive Swagger UI at https://api.timetriggers.io/docs. It doesn't list /schedule yet; use Schedule a trigger or the Full spec for that endpoint.

Notes for code generators and clients such as Postman:

• The spec has no servers entry: set the base URL to https://api.timetriggers.io yourself.
• API keys are described as header parameters (ttr-api-key, plus authorization where Bearer is accepted) on the operations that take them, not as a security scheme.
• /schedule is listed under GET, POST, PUT, PATCH and DELETE, which share the operation ID triggers.schedule. Some validators and generators reject or rename duplicate operation IDs. The endpoint accepts more methods than these five, and its body is not described because it is forwarded as-is.
• The spec includes the dashboard-only endpoints.

Learn more#

• How triggers fire — statuses, success and failure, timeouts, retries and delivery guarantees.
• Errors — the error format and the errors each endpoint returns.
• Quota — how the monthly quota works.