> ## Documentation Index
> Fetch the complete documentation index at: https://docs.idem0.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# API reference

> The SDK surface and the HTTP contract.

## SDK

`@idem0/sdk` is two pure functions — a config producer, not a client wrapper.

### `idem0(options)`

Spread the result into your provider SDK constructor, once per client.

| Option     | Type                      | Required | Description                                                                      |
| ---------- | ------------------------- | -------- | -------------------------------------------------------------------------------- |
| `idem0Key` | `string`                  | yes      | Your idem0 key. Sent as `x-idem0-key`. Not your provider token.                  |
| `provider` | `"anthropic" \| "openai"` | yes      | Which upstream to route to.                                                      |
| `endpoint` | `string`                  | no       | Proxy base URL. Defaults to `https://api.idem0.dev`. Set only when self-hosting. |

Returns:

```ts theme={null}
{
  baseURL: string;                          // <endpoint>/anthropic or <endpoint>/openai/v1
  defaultHeaders: { "x-idem0-key": string };
}
```

### `idempotencyKey(key)`

Build the per-call header. Drop it into a request's `headers`.

```ts theme={null}
idempotencyKey("job-42"); // → { "Idempotency-Key": "job-42" }
```

The key is caller-owned and passed through verbatim — idem0 never generates it.

## HTTP contract

No SDK required — any HTTP client works. Point your requests at the idem0 proxy and add two headers.

### Endpoints

| Provider  | Base URL                          | Example path                  |
| --------- | --------------------------------- | ----------------------------- |
| Anthropic | `https://api.idem0.dev/anthropic` | `/anthropic/v1/messages`      |
| OpenAI    | `https://api.idem0.dev/openai/v1` | `/openai/v1/chat/completions` |

The proxy strips the provider prefix and forwards everything else upstream unchanged.

### Request headers

| Header            | Description                                                                                        |
| ----------------- | -------------------------------------------------------------------------------------------------- |
| `x-idem0-key`     | Your idem0 key.                                                                                    |
| `Idempotency-Key` | Stable key for this unit of work. Same key → replay.                                               |
| provider auth     | Your normal provider auth, untouched: `x-api-key` (Anthropic) or `Authorization: Bearer` (OpenAI). |

### Response headers

| Header                      | Description                                                                           |
| --------------------------- | ------------------------------------------------------------------------------------- |
| `idem0-idempotent-replayed` | `true` when the response was replayed from cache (0 credits). Absent on a fresh call. |

### Status codes

| Status              | Meaning                                                                                     |
| ------------------- | ------------------------------------------------------------------------------------------- |
| `200`               | Success — a fresh call, or a replay (check `idem0-idempotent-replayed`).                    |
| `409 Conflict`      | The same key is already in flight. Retry after the first call finishes.                     |
| `422 Unprocessable` | The same key was reused with a different request body. Use a new key, or the original body. |

Keyless requests pass straight through to the provider — no idempotency, no change in behavior.