Create a waitpoint token

Creates a new waitpoint token that can be used to pause a run until an external event completes it. The token includes a url which can be called via HTTP POST to complete the waitpoint. Use the token ID with wait.forToken() inside a task to pause execution until the token is completed.

POST /api/v1/waitpoints/tokens

TypeScript

TypeScript

import { wait } from "@trigger.dev/sdk";

const token = await wait.createToken({
  timeout: "1h",
  tags: ["user:1234567"],
});

console.log(token.id);  // e.g. "waitpoint_abc123"
console.log(token.url); // HTTP callback URL to complete externally

200

{
  "id": "waitpoint_abc123",
  "isCached": true,
  "url": "https://api.trigger.dev/api/v1/waitpoints/tokens/waitpoint_abc123/callback/abc123hash"
}

Authorizations

Authorization · string · header · required

Use your project-specific Secret API key. Will start with tr_dev_, tr_prod, tr_stg, etc.

You can find your Secret API key in the API Keys section of your Trigger.dev project dashboard.

Our TypeScript SDK will default to using the value of the TRIGGER_SECRET_KEY environment variable if it is set. If you are using the SDK in a different environment, you can set the key using the configure function.

import { configure } from "@trigger.dev/sdk";

configure({ accessToken: "tr_dev_1234" });

Body

application/json

idempotencyKey · string

An optional idempotency key. If you pass the same key twice before it expires, you will receive the original token back. The returned token may already be completed, in which case wait.forToken() will continue immediately.

Example:

"approval-user-1234567"

idempotencyKeyTTL · string

How long the idempotency key is valid, after which passing the same key creates a new waitpoint. Accepts durations like "30s", "1m", "2h", "3d".

Example:

"1h"

timeout · string

How long to wait before the token times out. When a run is waiting for a timed-out token, wait.forToken() returns with ok: false. Accepts an ISO 8601 date string or duration shorthand like "30s", "1m", "2h", "3d", "4w".

Example:

"1h"

tags · string string[]

Tags to attach to the waitpoint. You can set up to 10 tags, each under 128 characters. We recommend namespacing tags with a prefix like user:1234567 or org_9876543.

Example:

["user:1234567", "org:9876543"]

Response

200

application/json

Waitpoint token created successfully

id · string · required

The unique ID of the waitpoint token.

Example:

"waitpoint_abc123"

isCached · boolean · required

true if an existing token was returned because the same idempotencyKey was used within its TTL window.

url · string · required

An HTTP callback URL. A POST request to this URL (with an optional JSON body) will complete the waitpoint without needing an API key.

Example:

"https://api.trigger.dev/api/v1/waitpoints/tokens/waitpoint_abc123/callback/abc123hash"