Get started › Quickstart

Quickstart

Make your first grounded request in five minutes. You’ll need an API key and one of the SDKs.

1. Install the SDK

pip install cairn

npm install @cairn/sdk

# nothing to install

2. Authenticate

Create a key in the console. Keys are shown once; store them in an environment variable, never in code.

3. Make a grounded request

Pass sources to restrict retrieval. Every claim in output_text is matched to an entry in citations.

from cairn import Cairn

client = Cairn()
r = client.responses.create(
    model="ridge-2.0",
    input="Summarize our DPA obligations",
    sources=["drive://legal"],
)
print(r.verification, r.citations)

import Cairn from "@cairn/sdk";

const client = new Cairn();
const r = await client.responses.create({
  model: "ridge-2.0",
  input: "Summarize our DPA obligations",
  sources: ["drive://legal"],
});
console.log(r.verification, r.citations);

curl https://api.cairn.example/v1/responses \
  -H "Authorization: Bearer $CAIRN_API_KEY" \
  -d '{
    "model": "ridge-2.0",
    "input": "Summarize our DPA obligations",
    "sources": ["drive://legal"]
  }'

4. Check the verification state

Each response has verification: grounded, needs_review or unsupported. Show it to your users next to the answer, not in a tooltip.

API reference › Responses › Create response

Creates a model response, optionally grounded in your sources. Streams with stream: true.

Body parameters

modelstringrequired

summit-2.1, ridge-2.0 or pebble-1.4.

inputstring | arrayrequired

The prompt, or an array of messages.

sourcesstring[]optional

Connectors or folders to ground on. Omit for no retrieval.

streambooleanoptional

Stream tokens as server-sent events. Default false.

max_cost_usdnumberoptional

Hard cap for this request. The request fails before exceeding it.

Response

{
  "id": "resp_7Hk2…",
  "model": "ridge-2.0",
  "output_text": "Under the DPA you must…",
  "citations": [
    { "n": 1, "source": "drive://legal/dpa.pdf",
      "span": [1204, 1388] }
  ],
  "verification": "grounded",
  "usage": { "input_tokens": 1204, "output_tokens": 318,
             "cost_usd": 0.0074 }
}

Errors

400

Invalid parameters. The message names the field.

401

Missing or revoked API key.

402

max_cost_usd would be exceeded. Nothing was charged.

429

Rate limited. Retry after the seconds in retry-after.