Idempotency

Networks drop responses. If you retry a request whose response was lost, you might run it twice. Send an Idempotency-Key header to make sure an identical request runs at most once.

Supported endpoints

• POST /api/v1/llm/v1/chat/completions
• POST /api/v1/llm/v1/responses
• POST /api/v1/llm/v1/embeddings
• POST /api/v1/llm/v1/rerank
• POST /api/v1/llm/v1/messages (beta, see Anthropic-compatible API)

How it works

Send an idempotency keyCopy

IDEMPOTENCY_KEY=$(uuidgen)   # one fresh key per logical operation; reuse it only for retries

curl https://api.breachline.io/api/v1/llm/v1/chat/completions \
  -H "Authorization: Bearer $BREACHLINE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -d '{"model": "nebula-4.5", "messages": [{"role": "user", "content": "Summarise finding F-12."}]}'

• A request is identified by the key and the exact body, together with your organization, your user and the API key that sent it. The same key with a different body is a different request.
• The first request runs normally.
• An identical request within 24 hours is refused with 409 Conflict before any model is called, so it costs nothing.
• If the first attempt fails, its claim is released and a genuine retry with the same key can run.
• A streaming request keeps its claim once the stream has started.

409 for a replayCopy

{
  "error": {
    "status": 409,
    "message": "Resource conflict",
    "code": "RESOURCE_3003",
    "detail": "This request was already received (same Idempotency-Key and body), so it was not run again. Send a new Idempotency-Key to run it again.",
    "request_id": "6c5d0c9e-0000-4000-8000-000000000000"
  }
}

Note

A replay gets 409, not a copy of the original response. Store the response from the first attempt if you need it again, or retrieve a stored Responses object with GET /v1/responses/{id}.

Choosing keys

• Use a fresh random value, such as a UUID v4, for each logical operation.
• Reuse the same key only for retries of that same operation.
• Generate the key before the first attempt, and keep it with the work item so a restarted worker retries with the same key.

Guarantees and limits

• The guarantee is best effort: it holds while the claim store is healthy. If that store is unavailable, requests are admitted rather than refused.
• The key never affects billing. Every execution is charged under its own server-generated reference, so a gap in replay protection can only ever produce a charged run, never a free one.
• Keys are remembered for 24 hours. After that, the same key and body run again.