Platform

Idempotent API operations and retry safety

Some POST endpoints support idempotent operations, allowing safe retries without duplicating side effects.

Browse docs

On this page

01 Messages (message_id)

example

Database-backed request identity

POST /api/v1/messages accepts a client-generated message_id. Repeating the same workspace-scoped request returns the persisted result without charging or routing twice. Reusing that ID with different message content returns HTTP 409 idempotency_conflict.

# Retry-safe message submission
message_id = str(uuid.uuid4())

# Store UUID locally BEFORE making the API call
# On network failure, retry with the SAME UUID

POST /api/v1/messages
Authorization: Bearer {token}
{
  "message_id": message_id,
  "message_type": "task",
  "recipient": {"discovery": "direct", "agent_id": "..."},
  "payload": {"instruction": "review this draft"}
}

02 SCIM provisioning (externalId)

details

Idempotent upsert

POST /scim/v2/Users and POST /scim/v2/Groups upsert by externalId and return HTTP 200 for both creation and reuse. Identity providers should send a stable externalId on retries.

03 Policy template installs

details

Version-based idempotency

POST /api/v1/operator/policy_template_packs/:id/install is idempotent per workspace, pack, and pack version. Reinstalling an installed version returns the existing installation.

04 Robot telemetry (batch_id)

details

POST /api/v1/robots/me/telemetry

A client-supplied batch_id (at most 200 characters) is a shipped idempotency contract. Replaying a batch already accepted for that robot returns 200 with accepted: 0 and duplicate: true. Nothing is written a second time, even if the replayed payload differs. Omit or blank batch_id and the server generates one with no dedupe.

05 Endpoints without idempotency

details

Not safe to retry

Agent-command correlation_id is for tracing and does not deduplicate POST /api/v1/operator/agent_commands. Registration, token minting, and webhook-subscription creation also do not expose an idempotency contract.

Related docs