Idempotency Keys

Every POST, PUT, and PATCH endpoint accepts an Idempotency-Key header. If you send the same key twice, the second request returns the cached response from the first — no duplicate side effects.

How It Works

Include a unique string in the Idempotency-Key header. Repull stores the response for 24 hours. If the same key is sent again, the cached response is returned with an Idempotency-Status: cached header.

curl -X POST /v1/reservations \
  -H "Authorization: Bearer sk_test_KEY" \
  -H "X-Workspace-Id: WS_ID" \
  -H "Idempotency-Key: unique-request-id-12345" \
  -H "Content-Type: application/json" \
  -d '{"propertyId": "123", "checkIn": "2026-06-01", ...}'

# If retried with the same Idempotency-Key, returns cached response
# Response header: Idempotency-Status: cached

When to Use

• Retry logic — Network failures, timeouts, or 5xx errors. Retrying with the same key guarantees no duplicate bookings or payments.
• AI agents — LLM-driven tools that may retry tool calls. Idempotency prevents double-actions.
• Webhook handlers — If your webhook processor might receive the same event twice, use the event ID as the idempotency key when calling back into Repull.
• User-facing forms — Prevent double-submit on slow connections.

Python Example

import requests, uuid

response = requests.post(
    "https://api.repull.dev/v1/reservations",
    headers={
        "Authorization": "Bearer sk_test_KEY",
        "X-Workspace-Id": "WS_ID",
        "Idempotency-Key": str(uuid.uuid4()),
        "Content-Type": "application/json",
    },
    json={
        "propertyId": "123",
        "checkIn": "2026-06-01",
        "checkOut": "2026-06-05",
        "guestName": "Jane Doe",
    },
)

# On retry, use the SAME Idempotency-Key value
print(response.headers.get("Idempotency-Status"))  # "cached" on retry

Key Guidelines

• Keys are cached for 24 hours. After that, the same key is treated as a new request.
• Use UUIDs or deterministic keys derived from your business logic (e.g. create-res-guest42-2026-06-01).
• Keys are scoped per workspace — the same key in different workspaces is treated independently.
• GET and DELETE requests do not support idempotency keys (they are already idempotent by nature).