Everything writes to the ledger through one envelope. Callers never need to know table layout.

​
Envelope

{
  "project": "slideshow-studio",
  "source": "api",
  "idempotency_key": "run-abc123-image-1",
  "timestamp": "2026-07-06T20:00:00Z",
  "message": { "type": "usage", "...": "..." }
}
FieldTypeRequiredNotes
projectstring✓Project slug; auto-created on first use
sourceenumapi | mcp | manual | import (default api)
idempotency_keystringDedupes within a workspace
timestampISO datetimeOptional event time
messageobject✓Discriminated union on type
Batch: send a JSON array of envelopes (1–100) to POST /api/v1/messages.

​
Message types

​
usage

Code or automation generated cost.
FieldTypeRequired
type"usage"✓
providerstring✓
modelstring
unit_typeUnitType✓
quantitynumber (>0)✓
unit_costnumber (≥0)
estimated_costnumber (≥0)Preferred for amount_usd
featurestring
batch_idstring
environmentstring
external_request_idstring
metadataobject
USD: estimated_cost ?? unit_cost ?? 0

​
expense

One-off purchase or invoice.
FieldTypeRequiredDefault
type"expense"✓
vendorstring✓
amountnumber (>0)✓
currencystringUSD
categorystring
expense_typeenumone_time_purchase
notesstring
metadataobject
expense_type: one_time_purchase | invoice | credit_purchase | refund | reimbursement | manual_adjustment

​
subscription

Recurring tool.
FieldTypeRequiredDefault
type"subscription"✓
vendorstring✓
amountnumber (>0)✓
currencystringUSD
intervalenum✓monthly | yearly | weekly | quarterly
renewal_dateISO datetime
categorystring
project_allocationstring
statusenumactive (active|trial|paused|cancelled)
notesstring

​
allocation

Split a real invoice across projects (never double-count).
FieldTypeRequired
type"allocation"✓
parent_message_idUUID✓
projectstring✓
allocated_amountnumber (>0)✓
currencystringdefault USD
notesstring

​
batch

Group a job run.
FieldTypeRequired
type"batch"✓
namestring✓
total_estimated_costnumber
total_actual_costnumber
outputs_generatedint
usable_outputsint
final_outputsint
providerstring
featurestring
notesstring
USD: total_actual_cost ?? total_estimated_cost ?? 0

​
Unit types

input_tokens, output_tokens, total_tokens, image, video_second,
video_generation, voice_character, voice_byte, voice_minute,
transcription_minute, embedding, api_call, gpu_second,
storage_gb, bandwidth_gb

​
Principles

  1. Project-first — every message needs a project slug
  2. Append-only — no silent deletes; adjust with new rows
  3. Idempotent — retries with the same idempotency_key are safe
  4. Native units exact, USD estimated — match pipeline trackers