Idempotency
Retry a write safely with an Idempotency-Key, and know when a key is required.
A network error leaves you not knowing whether a write happened. Send an Idempotency-Key header
with any POST, PUT, PATCH or DELETE, and a retry with the same key and the same body gets
the first answer back instead of doing the work twice.
curl -X POST https://api-hq.aiworkforceone.com/v1/sessions/sess_…/messages \
-H "Authorization: Bearer $HQ_API_KEY" \
-H "Idempotency-Key: 6c1f2b0e-run-42" \
-H "Content-Type: application/json" \
-d '{"content":[{"type":"text","text":"Summarise the open pull requests"}]}'- Use a new key for each new action, for example a UUID. Up to 255 printable ASCII characters.
- A key belongs to the key that sent it and lasts 24 hours.
- A replayed answer carries
Idempotent-Replayed: true, the same status and body, and the sameLocationheader for a create. A retriedDELETEanswers its first204again, even though the object is gone. - The same key with a different request (another body, query, path or route) is refused:
422 idempotency_key_reused. - While the first request is still running, a retry is refused with
409 idempotency_in_progressandRetry-After. Wait, then retry with the same key. - Answers that say "try again" are not stored, so a retry runs for real:
409conflicts,421misdirected,429rate limits and5xxerrors.
Where a key is required
These writes start something you cannot take back, so they refuse a request without a key
(400 invalid_request, field Idempotency-Key):
| Request | Why |
|---|---|
POST /teams/{team_id}/sessions | Starts a session. |
POST /sessions/{session_id}/messages | Types into the session. A prompt is typed at most once. |
POST /sessions/{session_id}/actions | Answers a question or a permission request. |
POST /teams/{team_id}/computer/start, stop, update, resize | Changes the machine. |
POST /schedules/{schedule_id}/runs | Runs a schedule now. |
Everywhere else the key is optional and works the same way.
A secret is never replayed
POST /secrets and the other secret writes store their answer for replay like any other write. The
answer never contains the secret's value, so the stored copy does not either. What is stored about
the request itself is a keyed digest, never the value or a plain hash of it.
A webhook endpoint's signing secret is shown once, in the answer to POST /webhook_endpoints and
POST /webhook_endpoints/{webhook_endpoint_id}/rotate_secret, and it is not stored for a replay. A
retry with the same key answers the same endpoint without secret and with
secret_omitted: true. If you lost the first answer, roll the secret to get a new one.