Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.arcmira.com/llms.txt

Use this file to discover all available pages before exploring further.

Network requests fail. Workers crash. Clients lose their connection mid-call. To make retrying writes safe, Arcmira accepts an Idempotency-Key header on every POST and PATCH request to watchlists and trackers.

​
How it works

  1. Send a POST or PATCH with Idempotency-Key: <unique-string>.
  2. Arcmira processes the request and stores the response body, status, and a hash of the request body keyed by your key for 24 hours.
  3. Any retry with the same Idempotency-Key returns the cached response with Idempotency-Replayed: true set in the response headers.
The cache is scoped to your API key, so collisions between different keys are impossible.

​
Choosing keys

  • Use a fresh, unique key per logical operation. A UUID v4 per call is the safest default.
  • Make the key meaningful to your system — e.g. tracker:create:user_abc:job_42. That makes debugging from X-Request-Id traces easy.
  • Reusing a key with a different request body is treated as a conflict.

​
Example

First attempt
curl -X POST 'https://api.arcmira.com/v1/watchlists' \
  -H "Authorization: Bearer $ARCMIRA_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "name": "AI founders" }'
A retry with the same key returns the same response:
Retry
curl -i -X POST 'https://api.arcmira.com/v1/watchlists' \
  -H "Authorization: Bearer $ARCMIRA_API_KEY" \
  -H "Idempotency-Key: 4a8c5c47-..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "AI founders" }'

HTTP/1.1 201 Created
Idempotency-Replayed: true
X-Request-Id: req_...
...

​
Conflicts

Replaying a key with a different body returns 409 idempotency_conflict: 
{
  "error": {
    "type": "conflict_error",
    "code": "idempotency_conflict",
    "message": "Idempotency-Key was reused with a different request body.",
    "doc_url": "https://docs.arcmira.com/errors#idempotency_conflict",
    "request_id": "req_..."
  }
}
The fix is to mint a new key for the new logical operation.

​
Caveats

  • Cached responses survive for 24 hours and may not survive infrastructure-side cache evictions. If your retry window is longer, mint a new key and accept that the underlying record might already exist (and handle the resulting 409 / 400 accordingly).
  • GET and DELETE requests don’t accept idempotency keys — they’re already idempotent at the HTTP semantics layer.
  • The Idempotency-Replayed: true header is the only way to tell whether a successful response came from a fresh execution or a cached one.