Pushing usage
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.
POST /api/v1/usageAuthorization: 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:
{
"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
{ "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.
| Refusal | Status |
|---|---|
| No ingest database on this instance | 503 |
| No key, an unknown key, or a revoked one (named, with "mint another") | 401 |
| A body over 1 MiB (1048576 bytes), counted as it arrives | 413 |
| A malformed window, source or row, each fault listed | 400 |
| A day that has not ended | 400 |
| A workload of another org, or one the record does not hold | 403 |
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.
