Overview
Creates a new waitpoint token. Inside a task, callwait.forToken(token) to pause the run until the token is completed. Anyone with the token’s url can complete it via a plain HTTP POST — no API key required.
Use cases:
- Human-in-the-loop approval workflows
- Waiting for a webhook from an external service
- Coordinating multiple services before a run continues
Endpoint
Request body
All fields are optional.Prevents creating duplicate tokens. If you pass the same key again before it expires, the original token is returned. Useful when you want to ensure only one outstanding approval exists per entity.
How long the idempotency key is valid. After expiry, the same key can create a new token. Accepts duration strings:
"30s", "1m", "2h", "3d".How long to wait before the token times out. If the run is still waiting when the timeout elapses,
wait.forToken() returns with ok: false. Accepts an ISO 8601 date string or duration shorthand: "30s", "1m", "2h", "3d", "4w".Up to 10 tags to attach to the waitpoint. Each tag must be under 128 characters. We recommend namespacing:
user:1234567 or org:9876543.Response
The unique waitpoint token ID, prefixed with
waitpoint_. Pass this to wait.forToken() inside your task.An HTTP callback URL. Anyone can
POST to this URL (with an optional JSON body) to complete the waitpoint — no API key required. Ideal for embedding in approval emails or sharing with third-party webhooks.true if an existing token was returned because the same idempotencyKey was used within its TTL window.