Get started

Pushing usage

Source

The one write route this API mounts, and the only route a machine authenticates to. A runtime pushes what its own ledger says served each lane on a day that has ended, and each batch lands as readings on /console.

text
POST /api/v1/usage
text
Authorization: Bearer vitna_push_...

The key is org-scoped, minted by an operator with `org:key:create`, shown once, and held as a hash: a push may only name workloads of the org the key belongs to.

The body

One payload is one closed UTC day:

json
{
  "window": "2026-08-24",
  "source": "policy ecb93b2a5c50...",
  "rows": [
    { "workload": "convexity/deep-research", "sku": "anthropic/claude-opus-4-8", "units": 3, "windowUnits": 4 },
    { "workload": "convexity/deep-research", "sku": "openai/gpt-5.6-luna", "units": 1, "windowUnits": 4 }
  ]
}

source is where the readings trace to, normally the policy digest that was routing when the requests ran; it is carried onto every reading's source_ref beside the key's id. windowUnits is the workload's own total for the day, stored on every row so a share stays a share.

What a push is, and is not

A push is a reading, origin: runtime, append-only. It never adopts: confirms_decision_id stays null and no workload's incumbent moves, because a machine that pushed enough traffic being able to move what the register says a lane runs would be the register taking dictation. Adoption stays an operator act through `aperture:usage:import`.

A batch is atomic. Any refused row refuses the whole batch and nothing lands, for the reason a partial config is refused.

A replay is one fact. The record keeps one reading per workload per window per sku, so re-pushing a day it already holds answers with alreadyStood rather than landing twice. That is also why only closed days are accepted: a reading of today would be a total that is wrong by midnight, standing permanently.

The answer

json
{ "landed": 2, "alreadyStood": 0, "refusals": [] }

201 when anything landed, 200 when everything already stood, and on any refusal a 4xx whose refusals array names every fault at once rather than one per round trip.

RefusalStatus
No ingest database on this instance503
No key, an unknown key, or a revoked one (named, with "mint another")401
A body over 1 MiB (1048576 bytes), counted as it arrives413
A malformed window, source or row, each fault listed400
A day that has not ended400
A workload of another org, or one the record does not hold403

Who can read what lands

Not this route, and not the role behind it: vitna_ingest may insert a reading and may never select one back, which deploy/provision-usage-ingest.sh proves against the live role. Readings reach people on `/console`, scoped by org membership, on the volume line and the confirmation under each value.