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

# Create a waitpoint token

`POST /api/v1/waitpoints/tokens`

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

---

[API](https://skmtc.net/winsenlabs/apis/trigger-dev-v3-rest-api.md) · [All operations](https://skmtc.net/winsenlabs/apis/trigger-dev-v3-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/winsenlabs/trigger-dev-v3-rest-api/versions/737c498e605b/schema)