Skip to main content
Every POST request that creates a resource accepts an Idempotency-Key header. Retry with the same key and Deck returns the original response instead of creating a duplicate.

​
How it works

Include an Idempotency-Key header on any POST request that creates a resource. 
curl -X POST https://api.deck.co/v2/agents \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{ "name": "Hotel Reservations" }'
When Deck receives a request with an idempotency key, it stores the result (status code and response body) and associates it with that key. If the same key is sent again:
  • Same parameters: Deck returns the stored response. No new resource is created.
  • Different parameters: Deck returns a 409 Conflict with an idempotency_error to prevent accidental misuse.
  • After 24 hours: the key expires and can be reused.

​
When to use them

Use idempotency keys on any create operation where a duplicate would cause problems:
OperationWhy
Opening a connectionPrevents duplicate sessions for the same user
Running a taskPrevents the same task from executing twice
Running a workflowPrevents duplicate workflow executions
Creating agents, sources, tasksPrevents duplicate resources
You don’t need idempotency keys for GET, PATCH, or DELETE requests. Reads are naturally idempotent, updates apply the same change regardless of repetition, and deleting an already-deleted resource returns the same confirmation.

​
Key format

Keys can be any string up to 256 characters. UUIDs are recommended because they’re unique by design and easy to generate in any language. 
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

​
Generating keys

const { randomUUID } = require('crypto')
const idempotencyKey = randomUUID()

​
Retry pattern

A typical retry flow with idempotency: 
async function createAgent(name, retries = 3) {
  const idempotencyKey = crypto.randomUUID()

  for (let attempt = 1; attempt <= retries; attempt++) {
    try {
      const res = await fetch('https://api.deck.co/v2/agents', {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${process.env.DECK_API_KEY}`,
          'Content-Type': 'application/json',
          'Idempotency-Key': idempotencyKey,
        },
        body: JSON.stringify({ name }),
      })

      return await res.json()
    } catch (err) {
      if (attempt === retries) throw err
      await new Promise(r => setTimeout(r, 1000 * attempt))
    }
  }
}
The key stays the same across retries. If the first request succeeded but the response was lost, the second request returns the original result. If the first request never reached the server, the second one creates the resource.

​
Error handling

If you reuse a key with different parameters, Deck rejects the request: 
{
  "errors": [
    {
      "type": "idempotency",
      "code": "idempotency_error",
      "message": "Idempotency key has already been used with different parameters."
    }
  ],
  "request_id": "req_a1b2c3d4..."
}
This returns HTTP 409. If you see this error, generate a new key for the new request.