> Source: https://vitna.ai/docs/api/v1/overview
> Raw Markdown: https://vitna.ai/docs/api/v1/overview.md
> Corpus index: https://vitna.ai/llms.txt
# API v1
JSON over HTTP. Reading the public record takes no key, no signup and no
quota. Base URL `https://vitna.ai/api/v1`.
Everything public here stays that way. What belongs to one organisation is
reached with a credential of its own: its [own feed](engine/org-feed.md), whose
address is the credential and which an owner gets from `/console`, and, with the
organisation's push key, its [signed artifacts](engine/artifacts.md) and the
[usage it pushes](engine/usage.md), the one write this API mounts. The console
itself is behind sign-in, and it is not part of this API.
## The index
```
GET /api/v1
```
```bash
curl https://vitna.ai/api/v1
```
Every route, each with its method, its path, the page documenting it and one
address that answers as it stands. A route that needs a value another answer
gives, such as an evidence hash, names where to take it from in `from` instead.
Any other path under `/api/v1` answers `404 unknown_route` in the error shape
below, never an HTML page. A route asked with a method it does not answer, such
as a `GET` on a `POST` route, refuses with `405 method_not_allowed` in the same
shape, naming the methods it does answer.
## The envelope
Every response is a JSON object carrying a `meta` key alongside its payload.
There is no single `data` wrapper: the payload key is named for what it is
(`classes`, `tape`, `events`, `periods`, `proposals`).
```json
{
"class": "model",
"tape": [ ... ],
"meta": {
"generatedAt": "2026-08-23T09:14:02.881Z",
"source": "database",
"count": 918
}
}
```
`meta.generatedAt` is always present. Everything else in `meta` is per-endpoint.
**Changes are additive.** A key can join a response. A key a caller already
reads is not renamed, retyped or dropped within v1.
Response examples are checked against a body the endpoint serves, so an example
names no key that is not there, on every page except five: watches, proposals,
evidence, artifacts and usage. Those read the engine's register, an on-disk
archive or a key, or answer a write, and no test can serve them, so their
examples are kept by hand.
Bodies are pretty-printed with two-space indentation and end with a newline, so
the API is readable in a terminal without piping it through a formatter.
## `meta.source`
| Value | Meaning |
|---|---|
| `database` | The live record |
| `snapshot` | The JSON committed in the repository |
| `archive` | The on-disk evidence store |
`vitna.ai` answers from the record. A checkout with no `DATABASE_URL` answers
from the snapshot, and says so rather than pretending.
## Caching and ETags
Four policies:
| Header | Used by |
|---|---|
| `public, max-age=60, stale-while-revalidate=3600` | Most endpoints |
| `public, max-age=60` | `/keys`, `/keys/policy-key.pub` |
| `no-store` | `/health`, `/evidence/{sha256}`, `/sources/health`, `/proposals`, `/watches` |
| `private, no-store` | `/feeds/{capability}/*`, refusals included |
The uncached set is uncached on purpose. A proposal is accepted by a person and
a watch is spent by a collector run, so a minute of staleness there reports that
nobody has acted when somebody has. Source health has the same problem in
reverse: a cached green is a claim about the past.
An organisation's own feed is `private` as well as `no-store`, so that no shared
cache keeps one organisation's activity even if a rule in front of the site is
ever set to store what `no-store` alone would let it.
The key register keeps its minute and gives up the stale window, because a key
retired after a compromise must stop being offered to pin within that minute
rather than within the hour.
Every response carries an `ETag`, computed as a sha256 over the body **with
`meta.generatedAt` removed**, truncated to 32 hex characters. Hashing the
timestamp too would make every response a fresh entity and the header useless.
What a caller wants to know is whether the record changed, not whether time
passed.
```bash
curl --compressed -H 'If-None-Match: "a1b2c3..."' https://vitna.ai/api/v1/markets
```
A match answers `304` with no body.
Send back the tag you were given, whichever form it took. The proxy in front of
the site may hand you `"a1b2c3..."` or `W/"a1b2c3..."`, depending on the
encoding it chose for the response, and which request gets which is its choice
rather than the API's. Both forms match, and so does a comma-separated list of
tags or `*`.
Only a read that would succeed is weighed against the tag. An error answers as
an error whatever `If-None-Match` says, so `*` on an unknown class is still a
`404`, never a `304`.
## Reading from a browser
Every keyless response carries `Access-Control-Allow-Origin: *` and exposes
`ETag` and `Age`, so a page on any origin can read the record and revalidate
what it read. A preflight `OPTIONS` to any other `/api/v1` path answers `204`,
allowing `GET` and the `If-None-Match` header. It allows no `Authorization`
header, so the two routes that take a key cannot be called from another origin's
page.
The one prefix outside that is `/api/v1/feeds/`, an organisation's own feed. Its
answers carry no `Access-Control-Allow-Origin`, and its preflight answers `204`
granting no origin and no method, so a page on another origin cannot read it.
## Errors
```json
{
"error": { "code": "unknown_class", "message": "no component class named \"models\"" },
"meta": { "generatedAt": "2026-08-23T09:14:02.881Z" }
}
```
Errors are always `no-store`. Codes in use:
| Code | Status | Cause |
|---|---|---|
| `unknown_route` | 404 | Not a v1 route; `GET /api/v1` lists them |
| `method_not_allowed` | 405 | The route does not answer that method; the message names the ones it does |
| `unknown_class` | 404 | Not a registered component class |
| `unknown_product` | 404 | No such product in that class |
| `unknown_dimension` | 404 | Product or sku exists, not metered that way |
| `unknown_sku` | 404 | No sku with that slug |
| `unknown_provider` | 404 | No registered or priced provider with that id |
| `unknown_kind` | 404 | Not one of the five event kinds |
| `unknown_evidence` | 404 | Nothing archived under that hash |
| `unknown_observation` | 404 | Not an observation id |
| `unknown_model` | 404 | No catalog model matches that slug |
| `unknown_board` | 404 | No mirrored benchmark board matches that id |
| `unknown_manifest` | 404 | No verified Anchor DMA manifest matches that slug |
| `unknown_dataset` | 404 | Not one of the five export datasets |
| `unknown_feed` | 404 | Not a live address for an organisation's feed, for any reason |
| `not_found` | 404 | No decision of a public feed has that id, for any reason |
| `no_policy_key` | 404 | No key is registered to sign policies, so there is no `.pub` file to serve |
| `bad_since` | 400 | `since` is not an ISO date |
| `bad_term_kind` | 400 | Not `zero_retention`, `no_training`, `regions` or `byok` |
| `missing_challenge` | 400 | `GET /router-challenge` called with no POST challenge body |
| `bad_challenge` | 400 | Router challenge payload missing required workload, incumbent, router, or evidence fields |
| `missing_decision_input` | 400 | `GET /decide` called with no POST decision payload |
| `bad_decision_input` | 400 | Stateless decision check missing workload, candidates, or evidence fields |
| `missing_reconciliation` | 400 | `GET /reconcile` called with no POST reconciliation payload |
| `bad_reconciliation` | 400 | Stateless reconciliation missing window, unitProfile, or valid readings |
| `missing_watchdog_input` | 400 | `GET /watchdog` called with no POST rollout watchdog payload |
| `bad_watchdog_input` | 400 | Stateless rollout watchdog missing workload or valid rule/telemetry fields |
| `missing_pipeline_input` | 400 | `GET /pipeline` called with no POST compound pipeline payload |
| `bad_pipeline_input` | 400 | Stateless compound pipeline missing stages or valid profile/ledger fields |
| `missing_audit_pack_input` | 400 | `GET /audit-pack` called with no POST audit pack or inline Stackfile payload |
| `bad_audit_pack_input` | 400 | Stateless audit pack request missing valid `pack` or `stackfile` fields |
| `bad_status` | 400 | Not `proposed`, `accepted` or `superseded` |
| `bad_state` | 400 | Not `armed` or `spent` |
| `unauthorized` | 401 | Evidence body requested without a valid token, or an artifact without an org key |
| `record_unavailable` | 503 | The record could not be read |
| `no_record` | 503 | Serving the snapshot, and this needs the record |
| `not_configured` | 503 | This instance holds no key to check an organisation's feed address with |
## 503 rather than an empty list
The rule the whole API keeps: an endpoint that cannot reach the record answers
`503`, never `[]`.
An empty list reads as "nothing is there". When the truth is "I could not look",
that is a lie, and it is exactly the lie a record like this exists to prevent.
It matters most on `/sources/health`, `/proposals` and `/watches`, where an
empty answer would report a healthy quiet system.
The same principle shapes partial answers. `/feed.json` reports its engine half
as **absent** rather than empty when it cannot read it, in `_vitna.engineActivity`.
## Types
- Money: USD, decimal, in the unit named alongside it. Six decimal places.
- Timestamps: RFC 3339, UTC.
- Dates: `YYYY-MM-DD`, meaning the whole day. In the feed a day is rendered as
its own midnight UTC, since RFC 3339 requires an instant.
- Hashes: 64 lowercase hex characters.
## Endpoints
Grouped by what they answer about, which is how the navigation lists them too.
**Prices**, the boards as data:
| Page | Endpoint |
|---|---|
| [Markets](prices/markets.md) | `GET /markets` |
| [Tape](prices/tape.md) | `GET /markets/{class}/tape` |
| [Spreads](prices/spreads.md) | `GET /spreads/{class}/{product}` |
| [Sku history](prices/sku-history.md) | `GET /skus/{slug}/history` |
| [Snapshot](prices/snapshot.md) | `GET /snapshot` |
| [Reference rates](prices/rates.md) | `GET /rates` |
| [Providers](prices/providers.md) | `GET /providers`, `GET /providers/{id}` |
| [Provider terms](prices/terms.md) | `GET /terms`, `GET /providers/{id}/terms` |
| [LiteLLM cost map](prices/litellm-cost-map.md) | `GET /gateways/litellm/model-prices.json` |
| [Quote check](prices/quote-check.md) | `POST /quote-check` |
| [Catalog, benchmarks and capability](prices/catalog.md) | `GET /catalog/models`, `GET /catalog/models/{slug}`, `GET /catalog/models/{slug}/sellers`, `GET /catalog/skus/{slug}/capabilities`, `GET /catalog/benchmarks`, `GET /catalog/capability` |
| [Historical data exports](prices/exports.md) | `GET /exports/{dataset}`, Deploy |
**The log**, what happened and when:
| Page | Endpoint |
|---|---|
| [Events](log/events.md) | `GET /events` |
| [Feed](log/feed.md) | `GET /feed.json` |
**Verification**, checking a figure without taking anyone's word for it:
| Page | Endpoint |
|---|---|
| [Attestations](verification/attestations.md) | `GET /attestations` |
| [Observation proof](verification/proof.md) | `GET /observations/{id}/proof` |
| [Citations](verification/citations.md) | `GET /citations/{id}` |
| [Evidence](verification/evidence.md) | `GET /evidence/{sha256}` |
| [Signing keys](verification/keys.md) | `GET /keys`, `GET /keys/policy-key.pub` |
**The engine**, what was decided and what is being watched, and the routes an
organisation's own credential reaches:
| Page | Endpoint |
|---|---|
| [Proposals](engine/proposals.md) | `GET /proposals` |
| [Watches](engine/watches.md) | `GET /watches` |
| [Decision pack](engine/decision-pack.md) | `GET /decisions/{id}/pack` |
| [Router challenge](engine/router-challenge.md) | `POST /router-challenge` |
| [Stateless decision check](engine/decide.md) | `POST /decide` |
| [Stateless invoice reconciliation](engine/reconcile.md) | `POST /reconcile` |
| [Stateless rollout watchdog](engine/watchdog.md) | `POST /watchdog` |
| [Stateless compound pipeline analysis](engine/pipeline.md) | `POST /pipeline` |
| [Stateless audit attestation pack](engine/audit-pack.md) | `POST /audit-pack` |
| [Relay spreads and Anchor manifests](engine/relay-anchor.md) | `GET /relay/spreads`, `GET /anchor/manifests`, `GET /anchor/manifests/{slug}` |
| [Model Context Protocol (MCP)](engine/mcp.md) | `GET /mcp`, `POST /mcp` |
| [Your organisation's feed](engine/org-feed.md) | `GET /feeds/{capability}/feed.json`, `GET /feeds/{capability}/rss.xml`, private |
| [Collecting a signed artifact](engine/artifacts.md) | `GET /artifacts`, `GET /artifacts/{id}`, with the organisation's push key |
| [Pushing usage](engine/usage.md) | `POST /usage`, with the organisation's push key |
| [Organisation workloads](engine/org-workloads.md) | `GET /org/workloads`, `POST /org/workloads`, `POST /org/workloads/{slug}`, key-scoped |
| [Organisation Stackfile](engine/org-stackfile.md) | `GET /org/stackfile`, `POST /org/stackfile`, key-scoped |
| [Workload counterfactual cost](engine/org-counterfactual.md) | `GET /org/workloads/{slug}/counterfactual`, key-scoped |
| [Organisation dependency exposure](engine/org-exposure.md) | `GET /org/exposure`, key-scoped |
| [Organisation rollout watchdog](engine/org-watchdog.md) | `GET /org/watchdog`, key-scoped |
| [Organisation compound pipeline](engine/org-pipeline.md) | `GET /org/pipeline`, key-scoped |
| [Organisation audit attestation pack](engine/org-audit-pack.md) | `GET /org/audit-pack`, key-scoped |
| [CI evaluation evidence](engine/org-evidence.md) | `GET /org/evidence`, `POST /org/evidence`, key-scoped |
| [Headless artifact signing requests](engine/org-artifact-requests.md) | `GET /org/artifact-requests`, `POST /org/artifact-requests`, `GET /org/artifact-requests/{id}`, key-scoped |
| [Policy drift webhooks](engine/org-webhooks.md) | `GET /org/webhooks`, `POST /org/webhooks`, `POST /org/webhooks/{id}/test`, `POST /org/webhooks/{id}/disable`, Deploy |
| [Organisation members](engine/org-members.md) | `GET /org/members`, `POST /org/members`, `POST /org/members/remove`, Deploy |
| [Organisation API keys](engine/org-keys.md) | `GET /org/keys`, `POST /org/keys`, `POST /org/keys/{id}/revoke`, Deploy |
**The Unblocker**, the browser-backed web access alpha, which reads no part of
the record:
| Page | Endpoint |
|---|---|
| [Unblocker](../../unblocker/overview.md) | `POST /unblock`, with an Unblocker client key, relayed to the hosted service at https://unblock.vitna.ai, `503` only where the relay is not configured |
**One key**, the question the hosted APIs ask about an org's platform key,
which only their services may ask:
| Page | Endpoint |
|---|---|
| [One key for the hosted APIs](../../one-key.md) | `POST /keys/verify`, with a hosted API's service token |
| [One key for the hosted APIs](../../one-key.md) | `POST /receipts`, with a hosted API's service token: the receipts for an org's requests, for its console |
**Status**, whether the record and its sources are answering:
| Page | Endpoint |
|---|---|
| [Health](status/health.md) | `GET /health` |
| [Source health](status/sources.md) | `GET /sources/health` |