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, whose address is the credential and which an owner gets from /console, and, with the organisation's push key, its signed artifacts and the usage it pushes, 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/v1curl https://vitna.ai/api/v1Every 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).
{
"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.
curl --compressed -H 'If-None-Match: "a1b2c3..."' https://vitna.ai/api/v1/marketsA 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
{
"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 | GET /markets |
| Tape | GET /markets/{class}/tape |
| Spreads | GET /spreads/{class}/{product} |
| Sku history | GET /skus/{slug}/history |
| Snapshot | GET /snapshot |
| Reference rates | GET /rates |
| Providers | GET /providers, GET /providers/{id} |
| Provider terms | GET /terms, GET /providers/{id}/terms |
| LiteLLM cost map | GET /gateways/litellm/model-prices.json |
| Quote check | POST /quote-check |
| Catalog, benchmarks and capability | 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 | GET /exports/{dataset}, Deploy |
The log, what happened and when:
Verification, checking a figure without taking anyone's word for it:
| Page | Endpoint |
|---|---|
| Attestations | GET /attestations |
| Observation proof | GET /observations/{id}/proof |
| Citations | GET /citations/{id} |
| Evidence | GET /evidence/{sha256} |
| Signing keys | 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 | GET /proposals |
| Watches | GET /watches |
| Decision pack | GET /decisions/{id}/pack |
| Router challenge | POST /router-challenge |
| Stateless decision check | POST /decide |
| Stateless invoice reconciliation | POST /reconcile |
| Stateless rollout watchdog | POST /watchdog |
| Stateless compound pipeline analysis | POST /pipeline |
| Stateless audit attestation pack | POST /audit-pack |
| Relay spreads and Anchor manifests | GET /relay/spreads, GET /anchor/manifests, GET /anchor/manifests/{slug} |
| Model Context Protocol (MCP) | GET /mcp, POST /mcp |
| Your organisation's feed | GET /feeds/{capability}/feed.json, GET /feeds/{capability}/rss.xml, private |
| Collecting a signed artifact | GET /artifacts, GET /artifacts/{id}, with the organisation's push key |
| Pushing usage | POST /usage, with the organisation's push key |
| Organisation workloads | GET /org/workloads, POST /org/workloads, POST /org/workloads/{slug}, key-scoped |
| Organisation Stackfile | GET /org/stackfile, POST /org/stackfile, key-scoped |
| Workload counterfactual cost | GET /org/workloads/{slug}/counterfactual, key-scoped |
| Organisation dependency exposure | GET /org/exposure, key-scoped |
| Organisation rollout watchdog | GET /org/watchdog, key-scoped |
| Organisation compound pipeline | GET /org/pipeline, key-scoped |
| Organisation audit attestation pack | GET /org/audit-pack, key-scoped |
| CI evaluation evidence | GET /org/evidence, POST /org/evidence, key-scoped |
| Headless artifact signing requests | GET /org/artifact-requests, POST /org/artifact-requests, GET /org/artifact-requests/{id}, key-scoped |
| Policy drift webhooks | GET /org/webhooks, POST /org/webhooks, POST /org/webhooks/{id}/test, POST /org/webhooks/{id}/disable, Deploy |
| Organisation members | GET /org/members, POST /org/members, POST /org/members/remove, Deploy |
| Organisation API keys | 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 | 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 | POST /keys/verify, with a hosted API's service token |
| One key for the hosted APIs | 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 | GET /health |
| Source health | GET /sources/health |
