Skip to main content
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

ScenarioResult
First request with keyProcessed normally
Duplicate key, original succeededReturns cached response (same status, same body)
Duplicate key, original still processingReturns cached 202 with the original job_id
Duplicate key, original failed with 4xxReturns cached error (no retry)
Duplicate key, original failed with 5xxAllows 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"])