Cancel a trigger#

To cancel a trigger, send DELETE /cancel with its ID or its custom key:

curl -X DELETE https://api.timetriggers.io/cancel \
  -H "ttr-api-key: YOUR_API_KEY" \
  -H "ttr-trigger-id: 3f2b8c1e-7d4a-4e5b-9c2f-1a2b3c4d5e6f"

A 204 No Content with an empty body means the trigger is cancelled. A one-shot trigger then won't fire. A recurring trigger creates no new runs, but runs that are already due still fire.

Request headers#

Send exactly one of ttr-trigger-idheader and ttr-custom-keyheader. An empty value counts as missing.

Only triggers in your project are looked up. The ID or key is checked against recurring triggers first, then against one-shot triggers.

Which triggers can be cancelled#

Whether a one-shot trigger can be cancelled depends on its status:

A queued trigger can't be cancelled with /cancel. If it carries a tag, a /bulk cancel by tag ({"cancels": [{"tag": "billing"}]}) stops it, along with every other trigger that carries that tag.

Cancelling a recurring trigger#

Send the recurring trigger's ID (the triggerId that /schedule returned when you created it) or its custom key. A 204 means:

• The recurring trigger creates no new instances.
• Its upcoming instance, the one that isn't due yet, is cancelled too.
• Instances whose time has already come are not cancelled and still fire:
  • Queued instances, for example ones held back by a tag policy, are sent once the policy lets them through. You can't cancel them one by one (410).
  • Retrying instances keep retrying until an attempt succeeds or the retries run out. To stop one, cancel it with its own ID in ttr-trigger-idheader.
  • Running instances finish their request, and retry if it fails and a retry policy applies. Finished instances are kept as they are.

To cancel the recurring trigger together with its queued and retrying instances, give it a tag of its own and cancel by that tag with /bulk instead.

Each run of a recurring trigger (an instance) has its own ID, which you see in the dashboard. /schedule only returns the recurring trigger's ID.

Cancelling by custom key#

curl -X DELETE https://api.timetriggers.io/cancel \
  -H "ttr-api-key: YOUR_API_KEY" \
  -H "ttr-custom-key: appointment-42-reminder"

A custom key matches an active recurring trigger with that key or, if there's none, a one-shot trigger with that key that isn't cancelled.

Cancelling by key is reliable as long as the key has only been used for one trigger. In these cases, cancel by ttr-trigger-idheader instead:

• You've reused the key. You scheduled the key again after an earlier trigger with it was already queued, running or completed, so /schedule answered "operation": "schedule" with a new triggerId. Cancel the new trigger by that triggerId.
• A recurring and a one-shot trigger share the key. This can happen with /declare and /bulk. A cancel by key cancels the recurring trigger; cancel the one-shot trigger by its ID.

Cancelling again#

/cancel isn't idempotent. Once a trigger is cancelled, repeating the call no longer returns 204:

• By ID: 410, with Job is no longer cancellable (status=cancelled) or Generator already cancelled.
• By custom key: 404, with Job not found, because cancelled triggers are ignored. You get 410 instead if an older trigger with the same key is queued, running or completed.

If your client retries cancels, for example after a timeout, treat 404 and 410 on a retry as "nothing left to cancel".

Status codes#

Errors with a message have a JSON body such as {"_tag": "NotFound", "message": "Job not found"}. See Errors.