Quickstart

You’ll install the SDK, make one call, then run the same call again and watch idem0 return it from cache for zero credits. That last step is the whole point — don’t skip it.

Install

npm i @idem0/sdk

You’ll also need the provider SDK you already use — @anthropic-ai/sdk or openai.

Get your key

Grab an idem0 key from your dashboard and export it. This is your idem0 key (x-idem0-key) — not your provider key.

export IDEM0_KEY="idem0_live_..."

Make your first call

Spread idem0(...) into the provider client once, and drop idempotencyKey(...) into the call. Your provider key rides in the SDK’s own apiKey, untouched (BYOK).

import Anthropic from "@anthropic-ai/sdk";
import { idem0, idempotencyKey } from "@idem0/sdk";

const client = new Anthropic({
  apiKey: process.env.ANTHROPIC_API_KEY,
  ...idem0({ idem0Key: process.env.IDEM0_KEY, provider: "anthropic" }),
});

const message = await client.messages.create(
  {
    model: "claude-haiku-4-5",
    max_tokens: 64,
    messages: [{ role: "user", content: "Say hi in one word." }],
  },
  { headers: idempotencyKey("job-42") },
);

console.log(message.content);

import OpenAI from "openai";
import { idem0, idempotencyKey } from "@idem0/sdk";

const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
  ...idem0({ idem0Key: process.env.IDEM0_KEY, provider: "openai" }),
});

const completion = await client.chat.completions.create(
  {
    model: "gpt-5-nano",
    messages: [{ role: "user", content: "Say hi in one word." }],
  },
  { headers: idempotencyKey("job-42") },
);

console.log(completion.choices[0].message.content);

endpoint defaults to the hosted proxy (https://api.idem0.dev) — you only pass it when self-hosting.

See the replay (the whole point)

Run the exact same request twice and watch the second one come back from cache. Here it is with raw curl -i so you can see the response headers — use an Idempotency-Key you haven’t used yet, then run the command a second time unchanged:

curl -i https://api.idem0.dev/anthropic/v1/messages \
  -H "x-idem0-key: $IDEM0_KEY" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -H "Idempotency-Key: demo-001" \
  -d '{"model":"claude-haiku-4-5","max_tokens":64,"messages":[{"role":"user","content":"Say hi in one word."}]}'

First call — the model runs, you’re billed one call. No replay header:

HTTP/2 200
content-type: application/json

Second call, same Idempotency-Key — idem0 returns the stored response byte-for-byte, and bills you nothing:

HTTP/2 200
content-type: application/json
idem0-idempotent-replayed: true

That idem0-idempotent-replayed: true is the tell: no model ran, no credit spent. Same key, same answer. (OpenAI is identical — POST https://api.idem0.dev/openai/v1/chat/completions with Authorization: Bearer $OPENAI_API_KEY.)

Get started

Reference

What next

Concepts

API reference

​What next

Concepts

API reference

What next