vitna.ai/docs/quickstart Machine view
Raw .md llms.txt
> Source: https://vitna.ai/docs/quickstart
> Raw Markdown: https://vitna.ai/docs/quickstart.md
> Corpus index: https://vitna.ai/llms.txt

# Quickstart

Every read endpoint on `vitna.ai` is public and needs no key. There is no
signup, no token, and no rate limit to negotiate. If you can reach the host you
can read the record.

> [!TIP]
> Responses carry an `ETag`. Send it back as `If-None-Match` and an unchanged
> record answers `304` with no body, which is the cheapest way to poll.

## The first request

```bash
curl https://vitna.ai/api/v1/markets
```

That answers the component classes Vitna prices, how many skus and providers
each one carries, and how fresh the freshest and stalest figures in it are.

## The tape for one class

```bash
curl https://vitna.ai/api/v1/markets/model/tape
```

One row per priced cell: a sku, a dimension, an amount in USD, the unit that
amount is quoted in, when the price started, when it was last confirmed, and
the sha256 of the archived document it was read from.

Valid classes are `model`, `tooling`, `retrieval`, `extraction`, `translation`,
`speech` and `compute`. Every declared class is wired as of 2026-09-10. A class
that is registered and not yet read answers an empty tape rather than a 404, and
the [markets](api/v1/prices/markets.md) endpoint keeps it in the answer at
zero.

## One sku over time

```bash
curl "https://vitna.ai/api/v1/skus/gpt-5-pro/history?dimension=input_per_mtok"
```

Price periods, oldest first. A period is a stretch during which the price did
not move.

## The spread on one product

```bash
curl https://vitna.ai/api/v1/spreads/compute/h100-sxm
```

The same product sold by several providers, cheapest first, with the percentage
between the low and the high.

## Subscribe to the log

```bash
curl https://vitna.ai/api/v1/feed.json
```

JSON Feed 1.1. Price moves, launches, policy changes and deprecations, plus the
triggers that fired and the decisions the engine proposed.

## Check a figure yourself

Take an observation id from the record and ask for its proof:

```bash
curl https://vitna.ai/api/v1/observations/1/proof
```

You get the leaf's own fields, its hash, the sibling hashes up the Merkle tree,
and the signed root the walk should arrive at. Rebuild the hash, fold the path,
verify the Ed25519 signature. Nothing in the answer has to be trusted for the
check to mean something: if any of it were wrong, the arithmetic would stop
agreeing.

The full walkthrough, both checks end to end, is in
[Verify a figure yourself](verify-a-figure.md).

## Three-minute gateway quickstart (LiteLLM and OpenRouter)

Teams already running LiteLLM or OpenRouter in production can adopt Vitna's attested market prices, local unit profiles, and signed routing decisions in three steps without swapping out their gateway first.

### Step 1: Load attested Witness prices in LiteLLM (no key, no signup)

```bash
curl -s https://vitna.ai/api/v1/gateways/litellm/model-prices.json | head -c 400
```

```bash
LITELLM_MODEL_COST_MAP_URL=https://vitna.ai/api/v1/gateways/litellm/model-prices.json \
  litellm --config litellm.yaml
```

Every entry translates Witness `input_per_mtok`, `output_per_mtok`, and `embed_per_mtok` figures into per-token USD alongside a `vitna` provenance block (`sku`, `sourceUrl`, `confirmedAt`, `evidenceSha256`, `citationUrl`, and full context `bands`). Responses carry `ETag`, so polling with `If-None-Match` returns `304` when nothing changed. See [LiteLLM cost map](api/v1/prices/litellm-cost-map.md).

### Step 2: Measure your own token unit profile locally

Run sample or mirrored traffic through [Relay](runtime/relay.md) (no policy, no vitna.ai account, nothing leaves your machine), then compute your observed token profile from its append-only JSONL ledger:

```bash
OPENAI_API_KEY=sk-... npx -p vitna-runtime vitna-relay
vitna-runtime-profile --file ~/.vitna/relay/ledger.jsonl
vitna-runtime-profile --file ~/.vitna/relay/ledger.jsonl --json
```

`vitna-runtime-profile` prints `--profile inputTokensPerUnit=... --profile outputTokensPerUnit=...` for each lane, separates refusals and unrouted passthrough rows rather than estimating missing counts, and stays completely offline. Operators recording into an Aperture register can also extract p90 latency and sample counts directly via `npm run aperture:evidence:from-run` ([Measuring your unit profile](runtime/profile.md), [Candidates and evidence](cli/aperture/evidence.md)).

### Step 3: Feed CI evals and render signed policies back to your gateway

Send existing Promptfoo, Braintrust, or UK AISI Inspect AI results directly to the append-only evidence endpoint ([CI evaluation evidence](api/v1/engine/org-evidence.md)) or enter them via `npm run aperture:evidence:add` ([Candidates and evidence](cli/aperture/evidence.md)):

```bash
curl -X POST https://vitna.ai/api/v1/org/evidence \
  -H "authorization: Bearer vitna_key_..." \
  -H "content-type: application/json" \
  -d '{
    "adapter": "promptfoo",
    "workload": "deep-research",
    "sku": "openai/gpt-5.6-luna",
    "label": "pr-412-gpt-5.6-luna",
    "sourceRef": "https://github.com/convexity/app/actions/runs/91823",
    "report": { "results": { "stats": { "successes": 193, "failures": 7, "errors": 0 } } }
  }'
```

Once a workload decision is accepted and signed into `policy.json`, render that same policy into native configuration for your existing proxy (`litellm`, `openrouter`, `cloudflare`, or `portkey`) without changing your serving data plane ([Gateway adapters](routing/adapters.md)):

```bash
VITNA_PUBLIC_KEY=$(cat policy-key.pub) \
  npm run aperture:adapter -- --target litellm --policy policy.json --out litellm.yaml
VITNA_PUBLIC_KEY=$(cat policy-key.pub) \
  npm run aperture:adapter -- --target openrouter --policy policy.json --out presets.json
```

## Conventions worth knowing before you parse anything

- Every response is a JSON object with a `meta` key. See
  [api/v1/overview.md](api/v1/overview.md).
- `meta.source` tells you whether the answer came from the live record
  (`database`) or from the snapshot committed in the repository (`snapshot`).
  The public site answers from the record.
- Money is USD, quoted in the unit the dimension declares, stored to six
  decimal places.
- Timestamps are RFC 3339. Calendar dates are `YYYY-MM-DD` and mean the day.
- Responses carry an `ETag`. Send it back as `If-None-Match` and you will get a
  `304` when the record has not changed.

## What this API will never do

It does not route traffic, hold your keys, proxy inference, or take an action
on your behalf. Vitna reads published prices and records decisions about them.
Changing what your stack runs is a person's job in another system.
Human Machine Shift+M