REST API

Idempotency

Retry safely without creating duplicate logical jobs.

An idempotency key identifies one logical execution. Use it whenever a caller might retry after a timeout, connection reset, process restart, or uncertain response.

## Send a key

```http
Idempotency-Key: tenant-42-profile-refresh-2026-08-06
```

Keys may be up to 255 characters. Generate them from a stable operation identity or store a random UUID alongside your application job.

## Replay behavior

Reusing a key with the same request resolves to the same logical job. It does not start another worker execution and does not add another capability charge.

Reusing the key with a different capability or input returns HTTP `409`:

```json
{
  "error": {
    "code": "idempotency_conflict",
    "message": "idempotency key has already been used for a different request"
  }
}
```

Do not recover from a conflict by silently discarding the key. A conflict normally means the caller's operation identity is ambiguous.

## Retry pattern

1. Create or load the logical operation's idempotency key.
2. Submit `POST /execute` with that key.
3. If the transport outcome is unknown, repeat the same request and key.
4. If a job ID was returned, poll that job rather than creating a new operation.

MCP derives transport idempotency from the authenticated subject, JSON-RPC request ID, and tool arguments, so clients should preserve JSON-RPC IDs when retrying an uncertain transport attempt.

An idempotency key identifies one logical execution. Use it whenever a caller might retry after a timeout, connection reset, process restart, or uncertain response.

Send a key

Idempotency-Key: tenant-42-profile-refresh-2026-08-06

Keys may be up to 255 characters. Generate them from a stable operation identity or store a random UUID alongside your application job.

Replay behavior

Reusing a key with the same request resolves to the same logical job. It does not start another worker execution and does not add another capability charge.

Reusing the key with a different capability or input returns HTTP 409:

{
  "error": {
    "code": "idempotency_conflict",
    "message": "idempotency key has already been used for a different request"
  }
}

Do not recover from a conflict by silently discarding the key. A conflict normally means the caller's operation identity is ambiguous.

Retry pattern

Create or load the logical operation's idempotency key.
Submit POST /execute with that key.
If the transport outcome is unknown, repeat the same request and key.
If a job ID was returned, poll that job rather than creating a new operation.

MCP derives transport idempotency from the authenticated subject, JSON-RPC request ID, and tool arguments, so clients should preserve JSON-RPC IDs when retrying an uncertain transport attempt.