Quickstart

This walks from nothing to a metered chat completion. On the sandbox route today the whole flow takes a few minutes and costs nothing, because sandbox agreements settle with no charge.

1. Get an allocation

An API key only works against an allocation, and an allocation only exists after an agreement activates. In the Cairva workspace:

1. Sign in and create a buyer organization.
2. Open Requests and send a private request for the model, token volume and delivery window you need. Pick at least one verified supplier, or request terms directly on a lot from the market.
3. When a supplier issues a firm quote, review it in the deal room and accept that version. Only an organization admin can accept.
4. The supplier countersigns. For a live agreement you pay the invoice and Cairva operations confirm it. Sandbox agreements skip payment.
5. Activation checks run and the allocation goes live, or becomes ready if its window hasn't opened yet.

The full sequence is in How Cairva works.

2. Create a key

Open API keys in the workspace, choose the allocation, give the key a name and pick its scopes. Use inference to call models and usage:read to read the allocation and usage. The secret is shown once. Store it as an environment variable on the machine that will make requests:

export CAIRVA_API_KEY="cv_test_XXXXXXXX_..."

Sandbox allocations get cv_test_ keys and live allocations get cv_live_ keys. See API keys.

3. Check what the key can call

GET /v1/models returns the single model your allocation covers. That id is the only value model can take.

curl https://cairva.xyz/v1/models \
  -H "Authorization: Bearer $CAIRVA_API_KEY"

// npm install openai
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.CAIRVA_API_KEY,
  baseURL: "https://cairva.xyz/v1",
});

const { data } = await client.models.list();
console.log(data[0].id); // the one model your allocation covers

# pip install openai
import os
from openai import OpenAI

client = OpenAI(api_key=os.environ["CAIRVA_API_KEY"], base_url="https://cairva.xyz/v1")
print(client.models.list().data[0].id)  # the one model your allocation covers

4. Send a request

curl https://cairva.xyz/v1/chat/completions \
  -H "Authorization: Bearer $CAIRVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemma4:e2b",
    "messages": [{"role": "user", "content": "Name three uses for a token allowance."}],
    "max_tokens": 300
  }'

const completion = await client.chat.completions.create({
  model: "gemma4:e2b",
  messages: [{ role: "user", content: "Name three uses for a token allowance." }],
  max_tokens: 300,
});

console.log(completion.choices[0].message.content);
console.log(completion.usage);
console.log(completion.cairva); // request id, allocation id, remaining allowance

completion = client.chat.completions.create(
    model="gemma4:e2b",
    messages=[{"role": "user", "content": "Name three uses for a token allowance."}],
    max_tokens=300,
)

print(completion.choices[0].message.content)
print(completion.usage)
print(completion.model_extra["cairva"])  # request id, allocation id, remaining allowance

Replace gemma4:e2b with whatever /v1/models returned for your key. Any other value fails with model_not_permitted.

5. Watch the meter

curl https://cairva.xyz/v1/allocations/current \
  -H "Authorization: Bearer $CAIRVA_API_KEY"

remaining drops by the tokens the provider reported for your request. Each request also appears in once its usage is booked.

If something fails

Every code is listed in Errors.