Ingestion API reference
Authentication, usage batches, spend, evidence records, responses and limits on /api/v1.
Everything is on /api/v1. The prefix is the compatibility promise: fields may be added to a response, and an existing field will not change type or meaning without a /api/v2. Rule of thumb: if you have token counts, send them; never send a cost you computed yourself. Oabo prices tokens against published and negotiated rates and reports both.
Authentication
| Credential | Header | Accepted at |
|---|---|---|
| Source ingest key (machines) | Authorization: Bearer <ingest-key> | The one receiver its kind opens, and /mcp for an mcp_client key. Org-scoped by construction; never expires; revoke instead. |
| User session (people) | Authorization: Bearer <session token> | POST /usage/ingest and POST /spend/ingest, with role and persona scope. An out-of-scope system answers 404. |
| Situation | Response |
|---|---|
| No key, malformed key, forged signature | 404 |
| Revoked key, or a key for a deleted source | 404 |
| Valid key, wrong receiver for its kind | 403, naming the right door |
| Valid key, bad payload | 422 with the offending field |
Usage batches
Three doors take the same batch: POST /usage/ingest (session), POST /usage/gateway/collector/events (collector key) and the submit_usage_events MCP tool. Over HTTP the system is named by the X-Oabo-Fingerprint header; over MCP it is the fingerprint argument. Batch limit 1000 records.
{
"records": [
{
"day": "2026-08-14",
"harness": "claude_code",
"model": "claude-fable-5",
"provider": "anthropic",
"billing_mode": "subscription",
"input_tokens": 1200,
"output_tokens": 3400,
"cache_read_tokens": 0,
"cache_write_tokens": 0,
"cache_write_1h_tokens": 0,
"sessions_count": 1,
"reported_host": "laptop-14",
"reported_user": "ana"
}
]
}| Field | Type | Notes |
|---|---|---|
| day | YYYY-MM-DD | Required. UTC. |
| harness | enum | Required. claude_code, hermes, ai_gateway, other. Keeps two feeds watching the same traffic from overwriting each other. |
| model | string <= 255 | Required. As the provider names it. |
| provider | enum | Required. anthropic, openai, google, bedrock, vertex, self_hosted, other. |
| billing_mode | enum | api (default), subscription, local. |
| input_tokens ... cache_write_1h_tokens | int >= 0 | Default 0. |
| sessions_count | int >= 0 | Sessions on this day. Sums across days; there is no session id to deduplicate on. |
| reported_host, reported_user | string <= 64 | Reported by the caller, not verified. |
- Idempotent by natural key: (organization, system, day, harness, model, provider). Sending a batch again replaces those rows; three deliveries of one day produce the same totals as one, across doors.
- Priced twice:
actual(zero for subscription and local, because a flat seat costs the same whether used or not) andequivalent(what the tokens would cost at metered rates, always priced). - Unknown fingerprint: machine doors register nothing; the records land in the unattributed pool with fingerprint, host and user kept. The session door auto-registers, provisionally, and says so with
auto_registered.
Spend
POST /spend/ingest, or submit_spend over MCP. The system must already be registered; an unknown fingerprint is 404.
{
"provider": "openai",
"amount_cents": 412300,
"period_month": "2026-07",
"source": "measured",
"business_unit": "Finance",
"description": "July invoice",
"idempotency_key": "openai-invoice-2026-07"
}| Field | Notes |
|---|---|
| provider | Required, from the provider enum. |
| amount_cents | Required, whole cents, >= 0. 12345 is $123.45. |
| period_month | Required, YYYY-MM. |
| source | measured or declared. Defaults to declared, the weaker claim; only measured flips a system’s verified badge. |
| idempotency_key | <= 128 chars. Same key, same figure: the original receipt with replayed: true. Same key, different figure or source: 409. Matched within (system, provider, month). |
| business_unit, description, model, request_id | Optional. |
Caution
Spend inserts. Two identical pushes without an idempotency key are two invoices. Any automated caller should always send one, because retry-on-timeout is the default of nearly every client.
| Response | Meaning |
|---|---|
| 409 provider_month_authoritative | A committed provider report already owns actual spend for that month. |
| 409 idempotency_key_conflict | That key was used for a different figure. |
| 429 | The organization is on a trial and this would exceed its connected-provider cap. |
Evidence records
submit_evidence_records over MCP takes ModelDeck runtime evidence: one metadata-only record per request or decision, schema modeldeck.evidence.v1. Live in release 0.3.0.
{ "schema_version": "modeldeck.evidence.v1",
"records": [ { "record_id": "md-node-a1:000001",
"org": "<org slug or id>", "workspace": "<org slug or id>", "use_case": "Invoice triage",
"caller": {"id": "svc-ap-inbox", "kind": "service"},
"ai_system": {"id": "qwen3-8b-q4", "kind": "model", "provider": "local",
"model": "Qwen3-8B-Instruct-Q4_K_M", "weights_sha256": "<64 hex>"},
"ts": "2026-11-10T14:03:21Z", "latency_ms": 842, "ttft_ms": 118,
"tokens": {"in": 1840, "out": 212, "cached": 1024},
"cost": {"amount": "0.000412", "basis": "node_amortized", "assumption_id": "node-a1-2026q4"},
"policy": {"data_class": "internal", "route": "local", "retention": "30d"},
"human_review": {"required": false, "overridden": false},
"prompt_hash": "sha256:<64 hex>",
"runtime": {"version": "0.9.4", "node_id": "md-node-a1"} } ] }- Metadata only. A batch with prompt or completion text anywhere (
prompt,completion,messages,content,text,input,outputand similar keys) is refused whole and names the path. Unknown keys are refused.prompt_hashmust be a SHA-256 hex digest. - Exactly one of
tokensordecision.ai_systemneedsweights_sha256orprovider_version.tsneeds a timezone.organdworkspacemust name the credential's own organization. - Lands once: keyed on
record_id, otherwise on (runtime.node_id,ts,caller.id). A replay writes nothing; a different record under a used key comes back inconflicts. costis the runtime's own estimate with its basis, stored as raw evidence and not added to recorded cost or usage. Read back withGET /api/v1/scorecard/evidence?use_case_id=&limit=.
Responses
{
"fingerprint": "invoice-bot",
"ai_system_id": 42,
"auto_registered": false,
"records_upserted": 1,
"unattributed_records": 0,
"attributed_agent_ids": [42],
"months_rolled": 1,
"demo_retired": false
}ai_system_idis the single attributed system when there is exactly one, else null; useattributed_agent_ids.POST /usage/ingestreturns a different shape: it carriesverifiedand notunattributed_recordsorattributed_agent_ids, because it registers instead of pooling.demo_retiredis true exactly once per organization: the moment real attributed cost arrives, the seeded illustrative figures stop.- Evidence reply:
{received, accepted, replayed, conflicts, unattributed_use_case}, and one audit entry per batch that stored anything.
Check delivery from the feed, not from a 2xx alone: GET /usage/gateway/sources, GET /usage/summary, GET /usage/summary/by-model and GET /usage/gateway/coverage.
Limits
- Unpriced models get a null equivalent cost and are reported as
unpriced_models, never priced at zero. - No bulk delete or amend. A usage day is corrected by re-pushing it; a spend row is corrected in the product.
- No webhooks. Ingestion is push-only.
- No OAuth on the MCP endpoint; authentication is an issued key.
- No discovery. Oabo never finds a client and enrolls it.
The repository copy of this contract is docs/api/INGEST.md, with the evidence JSON Schema under docs/api/schemas/. The receivers per kind are in Connections reference.