> This page is for Paperwork API, version v2.
> For other versions, use one of these documentation indexes:
> - v1 (default): https://docs.cloudraker.com/paperwork/v1/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.cloudraker.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.cloudraker.com/_mcp/server.

# Idempotency

Send an `Idempotency-Key` header on `POST /v2/{capability}`. A retry with the same key and the same body returns the first job. The API starts no second job.

```bash
curl -s -X POST "https://$CRK_SLUG.cloudraker.run/v2/parse" \
  -H "Authorization: Bearer $CRK_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: inv-2026-11-07-0042" \
  -d '{ "file": { "url": "https://files.example.com/invoice-0042.pdf" } }'
```

## Rules

| Rule         | Value                                                                                          |
| ------------ | ---------------------------------------------------------------------------------------------- |
| Key format   | 1 to 255 visible ASCII characters. Another value gives `400 invalid_request`.                  |
| Lifetime     | 24 hours from the first request.                                                               |
| Scope        | Per credential. Another credential with the same key creates its own job.                      |
| Fingerprint  | The method, the path and the body. The key order and the white space of the JSON do not count. |
| Not included | `Prefer` and `?wait`. A retry can change them.                                                 |

## Answers

| Case                      | Answer                                                         |
| ------------------------- | -------------------------------------------------------------- |
| First request             | The job. The API creates it.                                   |
| Same key and same body    | The first job, with the header `idempotent-replayed: true`.    |
| Same key and another body | `409 idempotency_key_reused`. Use a new key for a new request. |

A replay waits for the first job under the same `Prefer` rules. A replay of a job with stale signed URLs gets new URLs.

If the API fails a job with `503 capability_unavailable`, it deletes the claim of the key. A retry with the same key then creates a new job.

## Retry a failed call

Use the same `Idempotency-Key` after a network error or a `500`. The retry gets the first job and starts no second job. Use a new key when you want a new job.