Get started

API v1

Source

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

text
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

ValueMeaning
databaseThe live record
snapshotThe JSON committed in the repository
archiveThe 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:

HeaderUsed by
public, max-age=60, stale-while-revalidate=3600Most 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:

CodeStatusCause
unknown_route404Not a v1 route; GET /api/v1 lists them
method_not_allowed405The route does not answer that method; the message names the ones it does
unknown_class404Not a registered component class
unknown_product404No such product in that class
unknown_dimension404Product or sku exists, not metered that way
unknown_sku404No sku with that slug
unknown_provider404No registered or priced provider with that id
unknown_kind404Not one of the five event kinds
unknown_evidence404Nothing archived under that hash
unknown_observation404Not an observation id
unknown_model404No catalog model matches that slug
unknown_board404No mirrored benchmark board matches that id
unknown_manifest404No verified Anchor DMA manifest matches that slug
unknown_dataset404Not one of the five export datasets
unknown_feed404Not a live address for an organisation's feed, for any reason
not_found404No decision of a public feed has that id, for any reason
no_policy_key404No key is registered to sign policies, so there is no .pub file to serve
bad_since400since is not an ISO date
bad_term_kind400Not zero_retention, no_training, regions or byok
missing_challenge400GET /router-challenge called with no POST challenge body
bad_challenge400Router challenge payload missing required workload, incumbent, router, or evidence fields
missing_decision_input400GET /decide called with no POST decision payload
bad_decision_input400Stateless decision check missing workload, candidates, or evidence fields
missing_reconciliation400GET /reconcile called with no POST reconciliation payload
bad_reconciliation400Stateless reconciliation missing window, unitProfile, or valid readings
missing_watchdog_input400GET /watchdog called with no POST rollout watchdog payload
bad_watchdog_input400Stateless rollout watchdog missing workload or valid rule/telemetry fields
missing_pipeline_input400GET /pipeline called with no POST compound pipeline payload
bad_pipeline_input400Stateless compound pipeline missing stages or valid profile/ledger fields
missing_audit_pack_input400GET /audit-pack called with no POST audit pack or inline Stackfile payload
bad_audit_pack_input400Stateless audit pack request missing valid pack or stackfile fields
bad_status400Not proposed, accepted or superseded
bad_state400Not armed or spent
unauthorized401Evidence body requested without a valid token, or an artifact without an org key
record_unavailable503The record could not be read
no_record503Serving the snapshot, and this needs the record
not_configured503This 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:

PageEndpoint
MarketsGET /markets
TapeGET /markets/{class}/tape
SpreadsGET /spreads/{class}/{product}
Sku historyGET /skus/{slug}/history
SnapshotGET /snapshot
Reference ratesGET /rates
ProvidersGET /providers, GET /providers/{id}
Provider termsGET /terms, GET /providers/{id}/terms
LiteLLM cost mapGET /gateways/litellm/model-prices.json
Quote checkPOST /quote-check
Catalog, benchmarks and capabilityGET /catalog/models, GET /catalog/models/{slug}, GET /catalog/models/{slug}/sellers, GET /catalog/skus/{slug}/capabilities, GET /catalog/benchmarks, GET /catalog/capability
Historical data exportsGET /exports/{dataset}, Deploy

The log, what happened and when:

PageEndpoint
EventsGET /events
FeedGET /feed.json

Verification, checking a figure without taking anyone's word for it:

PageEndpoint
AttestationsGET /attestations
Observation proofGET /observations/{id}/proof
CitationsGET /citations/{id}
EvidenceGET /evidence/{sha256}
Signing keysGET /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:

PageEndpoint
ProposalsGET /proposals
WatchesGET /watches
Decision packGET /decisions/{id}/pack
Router challengePOST /router-challenge
Stateless decision checkPOST /decide
Stateless invoice reconciliationPOST /reconcile
Stateless rollout watchdogPOST /watchdog
Stateless compound pipeline analysisPOST /pipeline
Stateless audit attestation packPOST /audit-pack
Relay spreads and Anchor manifestsGET /relay/spreads, GET /anchor/manifests, GET /anchor/manifests/{slug}
Model Context Protocol (MCP)GET /mcp, POST /mcp
Your organisation's feedGET /feeds/{capability}/feed.json, GET /feeds/{capability}/rss.xml, private
Collecting a signed artifactGET /artifacts, GET /artifacts/{id}, with the organisation's push key
Pushing usagePOST /usage, with the organisation's push key
Organisation workloadsGET /org/workloads, POST /org/workloads, POST /org/workloads/{slug}, key-scoped
Organisation StackfileGET /org/stackfile, POST /org/stackfile, key-scoped
Workload counterfactual costGET /org/workloads/{slug}/counterfactual, key-scoped
Organisation dependency exposureGET /org/exposure, key-scoped
Organisation rollout watchdogGET /org/watchdog, key-scoped
Organisation compound pipelineGET /org/pipeline, key-scoped
Organisation audit attestation packGET /org/audit-pack, key-scoped
CI evaluation evidenceGET /org/evidence, POST /org/evidence, key-scoped
Headless artifact signing requestsGET /org/artifact-requests, POST /org/artifact-requests, GET /org/artifact-requests/{id}, key-scoped
Policy drift webhooksGET /org/webhooks, POST /org/webhooks, POST /org/webhooks/{id}/test, POST /org/webhooks/{id}/disable, Deploy
Organisation membersGET /org/members, POST /org/members, POST /org/members/remove, Deploy
Organisation API keysGET /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:

PageEndpoint
UnblockerPOST /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:

PageEndpoint
One key for the hosted APIsPOST /keys/verify, with a hosted API's service token
One key for the hosted APIsPOST /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:

PageEndpoint
HealthGET /health
Source healthGET /sources/health