Idempotency

All POST endpoints accept an Idempotency-Key header. If two requests share the same key, the second returns the cached response from the first instead of creating a duplicate resource. This is critical for Vision API operations that consume credits. A network timeout during POST /compare shouldn’t cost you twice.

Usage

Pass a unique key (we recommend UUIDv4) in the Idempotency-Key header:

curl -X POST https://api.bedrock.cv/compare \
  -H "Authorization: Bearer sk_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7c4a8d09-ca72-4053-98b2-6a76c3b4e8f1" \
  -d '{"old_id": "blk_01JABCD100", "new_id": "blk_01JABCD200", "type": "Block"}'

If the request succeeds, any subsequent request with the same key returns the original 202 response — no new job is created and no credits are charged.

Behavior

Scenario	Result
First request with key	Processed normally
Duplicate key, original succeeded	Returns cached response (same status, same body)
Duplicate key, original still processing	Returns cached `202` with the original `job_id`
Duplicate key, original failed with `4xx`	Returns cached error (no retry)
Duplicate key, original failed with `5xx`	Allows retry (key is released)

Key Rules

Keys are scoped to your organization. Two different organizations can use the same key.
Keys expire after 24 hours. After expiry, the same key can be reused.
Keys must be between 1 and 256 characters (alphanumeric, hyphens, and underscores).
Sending a different request body with an existing key returns a 409 Conflict error.

Response Headers

When a cached response is returned, the response includes:

Idempotency-Status: hit

On the first request:

Idempotency-Status: miss

When to Use

Use idempotency keys on any POST that creates resources or starts jobs:

POST /drawings — prevent duplicate drawing processing
POST /drawings/{id}/compare — prevent duplicate comparisons
POST /compare — prevent duplicate analysis
POST /parse — prevent duplicate parsing

You don’t need idempotency keys on GET, PATCH, or DELETE — these are naturally idempotent.

Example: Retry with Idempotency

import requests
import uuid

key = str(uuid.uuid4())

def create_comparison():
    return requests.post(
        "https://api.bedrock.cv/drawings/drw_01JABCD123/compare",
        headers={
            "Authorization": "Bearer sk_xxx",
            "Idempotency-Key": key,
        },
        json={"compare_to": "drw_01JABCD456"},
        timeout=10,
    )

# First attempt — may timeout
try:
    response = create_comparison()
except requests.Timeout:
    # Safe to retry with the same key
    response = create_comparison()

# Guaranteed: only one comparison job was created
print(response.json()["job_id"])

Getting Started

CMS API

Vision API

Errors

Usage

Behavior

Key Rules

Response Headers

When to Use

Example: Retry with Idempotency

​Usage

​Behavior

​Key Rules

​Response Headers

​When to Use

​Example: Retry with Idempotency

Usage

Behavior

Key Rules

Response Headers

When to Use

Example: Retry with Idempotency