---
title: "Create a waitpoint token"
method: POST
path: "/api/v1/waitpoints/tokens"
tags: ["waitpoints"]
---

# Create a waitpoint token

`POST /api/v1/waitpoints/tokens`

## Request

- Base URL: `https://api.trigger.dev`
- URL: `https://api.trigger.dev/api/v1/waitpoints/tokens`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/triggerdotdev/apis/trigger-dev-v3-rest-api/docs/api/v1/waitpoints/tokens/post.ts> (a function with typed inputs; its response is checked against the schema)

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.

## Request body

- CreateWaitpointTokenRequest
  - `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.
  - `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".
  - `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".
  - `tags` union: 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`.
    - string
    - string[]

## Response `200`

Waitpoint token created successfully

- CreateWaitpointTokenResponse
  - `id` string, required: The unique ID of the waitpoint token.
  - `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.

## Other responses

- `401`: Unauthorized
- `422`: Unprocessable Entity
- `500`: Internal Server Error

## Changes

- **2026-02-25** `38d6514341ed`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/triggerdotdev/apis/trigger-dev-v3-rest-api/changes/api/v1/waitpoints/tokens/post.md)

---

[API](https://skmtc.dev/triggerdotdev/apis/trigger-dev-v3-rest-api.md) - [All operations](https://skmtc.dev/triggerdotdev/apis/trigger-dev-v3-rest-api/llms.txt) - [OpenAPI document](https://skmtc.dev/triggerdotdev/apis/trigger-dev-v3-rest-api/revisions/441161111493?raw)