Skip to main content
Early pricing is live. Start free for up to 3 AI systems — no card, no time limit.Early pricing is live. Free for up to 3 AI systems.
All docs
Reference

Ingestion API reference

Authentication, usage batches, spend, evidence records, responses and limits on /api/v1.

10 minFor: Engineer

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

CredentialHeaderAccepted 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.
SituationResponse
No key, malformed key, forged signature404
Revoked key, or a key for a deleted source404
Valid key, wrong receiver for its kind403, naming the right door
Valid key, bad payload422 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.

request body
{
  "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"
    }
  ]
}
FieldTypeNotes
dayYYYY-MM-DDRequired. UTC.
harnessenumRequired. claude_code, hermes, ai_gateway, other. Keeps two feeds watching the same traffic from overwriting each other.
modelstring <= 255Required. As the provider names it.
providerenumRequired. anthropic, openai, google, bedrock, vertex, self_hosted, other.
billing_modeenumapi (default), subscription, local.
input_tokens ... cache_write_1h_tokensint >= 0Default 0.
sessions_countint >= 0Sessions on this day. Sums across days; there is no session id to deduplicate on.
reported_host, reported_userstring <= 64Reported 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) and equivalent (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.

request body
{
  "provider": "openai",
  "amount_cents": 412300,
  "period_month": "2026-07",
  "source": "measured",
  "business_unit": "Finance",
  "description": "July invoice",
  "idempotency_key": "openai-invoice-2026-07"
}
FieldNotes
providerRequired, from the provider enum.
amount_centsRequired, whole cents, >= 0. 12345 is $123.45.
period_monthRequired, YYYY-MM.
sourcemeasured 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_idOptional.

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.

ResponseMeaning
409 provider_month_authoritativeA committed provider report already owns actual spend for that month.
409 idempotency_key_conflictThat key was used for a different figure.
429The 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.

request body
{ "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, output and similar keys) is refused whole and names the path. Unknown keys are refused. prompt_hash must be a SHA-256 hex digest.
  • Exactly one of tokens or decision. ai_system needs weights_sha256 or provider_version. ts needs a timezone. org and workspace must 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 in conflicts.
  • cost is the runtime's own estimate with its basis, stored as raw evidence and not added to recorded cost or usage. Read back with GET /api/v1/scorecard/evidence?use_case_id=&limit=.

Responses

POST /usage/gateway/collector/events and submit_usage_events
{
  "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_id is the single attributed system when there is exactly one, else null; use attributed_agent_ids.
  • POST /usage/ingest returns a different shape: it carries verified and not unattributed_records or attributed_agent_ids, because it registers instead of pooling.
  • demo_retired is 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.

Previous

Connections reference

Last documented 2026-11-18 against master fb17e1c5. Live release 0.3.1.