Platform / Platform

Idempotent API operations and retry safety

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

01 Agent commands (correlation_id)

example

Deduplication via correlation_id

POST /api/v1/operator/agent_commands accepts an optional correlation_id. When provided, if a command with the same correlation_id already exists within the deduplication window, the existing command is returned (HTTP 200) instead of creating a duplicate. The correlation_id must be unique per workspace.

python

# Retry-safe command submission
correlation_id = str(uuid.uuid4())

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

POST /api/v1/operator/agent_commands
Authorization: Bearer {token}
{
  "service_agent_id": "...",
  "command_type": "deploy.workflow",
  "payload": {...},
  "correlation_id": correlation_id
}

02 SCIM provisioning (externalId)

details

Idempotent upsert

POST /scim/v2/Users: if a user with the same externalId exists, returns the existing user (HTTP 200) instead of creating a duplicate (HTTP 201). Same for POST /scim/v2/Groups. Identity providers (Okta, Azure AD) automatically set externalId for safe retry.

03 Policy template installs

details

Version-based idempotency

POST /api/v1/operator/gateway/policy_template_packs/:id/install: installs are idempotent per pack version. Reinstalling the same version updates existing resources without creating duplicates.

04 Endpoints without idempotency

details

Not safe to retry

POST /api/v1/register (creates a new account each time), POST /api/v1/agent_tokens (creates a 30-day token), POST /api/v1/socket_tokens (creates a 10-minute token), and POST /api/v1/operator/webhook_subscriptions (creates a new subscription each time).

Related docs