AI Workforce OneHQDocs

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 same Location header for a create. A retried DELETE answers its first 204 again, 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_progress and Retry-After. Wait, then retry with the same key.
  • Answers that say "try again" are not stored, so a retry runs for real: 409 conflicts, 421 misdirected, 429 rate limits and 5xx errors.

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):

RequestWhy
POST /teams/{team_id}/sessionsStarts a session.
POST /sessions/{session_id}/messagesTypes into the session. A prompt is typed at most once.
POST /sessions/{session_id}/actionsAnswers a question or a permission request.
POST /teams/{team_id}/computer/start, stop, update, resizeChanges the machine.
POST /schedules/{schedule_id}/runsRuns 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.