Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.qoder.com/llms.txt

Use this file to discover all available pages before exploring further.

The Qoder Cloud Agents API supports idempotency keys for safe retries on write operations. When the network is unstable or a client times out, an idempotency key prevents duplicate resource creation or repeated execution.

​
Header format

Two equivalent header names are supported:
Header nameNotes
Idempotency-KeyStandard form
X-Idempotency-KeyX- prefixed compatibility form
Both are functionally identical; pick either. 
# Standard form
Idempotency-Key: unique-request-id-001

# X-prefixed form
X-Idempotency-Key: unique-request-id-001
Use a UUID v4 as the idempotency key value to ensure global uniqueness.

​
Scope

Idempotency keys apply only to write operations:
HTTP methodSupportedNotes
POSTYesResource creation
PUTYesResource update
DELETEYesResource deletion
GETNoReads are inherently idempotent

​
Examples

​
Create an Agent with an idempotency key

# Use a UUID as the idempotency key
curl -X POST https://openapi.qoder.sh/api/v1/cloud/agents \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "name": "my-agent",
    "model": "qoder-sonnet-latest"
  }'

​
Generate an idempotency key in a script

# Generate a UUID and issue the request
IDEMPOTENCY_KEY=$(uuidgen | tr '[:upper:]' '[:lower:]')

curl -X POST https://openapi.qoder.sh/api/v1/cloud/sessions \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -d '{
    "agent_id": "agent_abc123"
  }'

echo "Idempotency key: $IDEMPOTENCY_KEY"

​
Repeat-request behavior

​
Same key + same body

The server returns the original response and does not re-execute the operation: 
# First request: creates the resource, returns 201
curl -X POST https://openapi.qoder.sh/api/v1/cloud/agents \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-unique-key-001" \
  -d '{"name": "test-agent", "model": "qoder-sonnet-latest"}'

# Second request (same key + same body): returns the original response
curl -X POST https://openapi.qoder.sh/api/v1/cloud/agents \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-unique-key-001" \
  -d '{"name": "test-agent", "model": "qoder-sonnet-latest"}'

​
Same key + different body

The server returns 409 conflict_error and refuses to execute: 
{
  "type": "error",
  "error": {
    "type": "conflict_error",
    "message": "A request with this idempotency key has already been processed with different parameters."
  }
}
Use a unique key for each distinct business operation. Do not reuse keys across different requests.

​
Idempotency key lifecycle

PropertyDescription
RetentionIdempotency keys are retained for 24 hours after first use
After expiryThe same key is treated as a new request
ScopeScoped per PAT (account); the same key on different accounts does not collide

​
Best practices

​
When to use

  • Strongly recommended when creating critical resources (Agents, Sessions)
  • All write operations on unstable networks
  • Bulk operations issued from automation scripts

​
Key generation strategies

StrategyWhen to useExample
UUID v4General purpose550e8400-e29b-41d4-a716-446655440000
Composite business IDBusiness-level deduplicationcreate-agent-project42-env-prod
Timestamp + randomSimple workflows1717200000-abc123

​
Full retry example

#!/bin/bash
# Create a session with an idempotency key and retry logic
IDEMPOTENCY_KEY=$(uuidgen | tr '[:upper:]' '[:lower:]')
MAX_RETRIES=3

for i in $(seq 1 $MAX_RETRIES); do
  response=$(curl -s -w "\n%{http_code}" \
    -X POST https://openapi.qoder.sh/api/v1/cloud/sessions \
    -H "Authorization: Bearer $QODER_PAT" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
    -d '{"agent_id": "agent_abc123"}')

  http_code=$(echo "$response" | tail -1)
  body=$(echo "$response" | sed '$d')

  # Success or client error (no retry)
  if [ "$http_code" -lt 500 ] && [ "$http_code" != "429" ]; then
    echo "$body"
    break
  fi

  # Server error; safe to retry (idempotency key prevents duplicate creation)
  echo "Attempt $i failed ($http_code), retrying..."
  sleep $((i * 2))
done

​
Without an idempotency key

  • Identical requests sent multiple times execute every time, potentially creating duplicate resources.
  • Operations that are non-critical or already deduplicated at the business layer can omit the key.
  • GET requests do not need an idempotency key—they are naturally safe to retry.