Pricing API | AgentMargin

What it does

Each workspace keeps its own price versions. Identity comes only from the bearer key, so a caller-supplied workspace ID can't widen scope.
Versions are append-only: a PostgreSQL trigger rejects UPDATE and DELETE.
Each version records a source note, a server-generated ID and the creator's key digest, never the plaintext key.
A new version supersedes older ones from its effective timestamp for future ingestion. Stored costs don't change.
The dashboard's Model pricing view accepts dollars per million tokens and converts to exact integer microdollars.

POST /v1/prices

All amounts are USD microdollars per million tokens, as decimal strings.

http

POST /v1/prices HTTP/1.1
Authorization: Bearer am_YOUR_LOCAL_WORKSPACE_KEY
Content-Type: application/json

json

{
  "model": "example-model",
  "effectiveFrom": "2026-10-22T00:00:00.000Z",
  "effectiveTo": null,
  "inputMicrosPerMillion": "1000000",
  "outputMicrosPerMillion": "4000000",
  "cachedInputMicrosPerMillion": null,
  "sourceNote": "Synthetic test rate; NOT a provider price quote"
}

Status	Meaning
`201`	Created. Returns the id, model, effective dates, rates, sourceNote and server-side createdAt.
`400`	Malformed input.
`401`	Unknown key.
`409`	The same model and effectiveFrom already exist in this workspace.
`429`	Per-workspace rate limit.

GET /v1/prices

Lists the newest 100 price rows your workspace created, plus a truncated flag. No other workspace's rows are returned, and legacy global operator prices aren't included.

Effective-dated semantics

For each model and event timestamp:

Find the latest workspace price with effectiveFrom <= event time. It applies if effectiveTo is absent or later than the event.
If a workspace version exists but has expired, the cost is unknown. There's no silent fallback to another tenant or global version.
If no workspace row exists before the event, the legacy operator-managed global catalog can be used as a fallback.
A provider-reported cost overrides estimates, including a valid reported zero.
The resolved price version ID is stored with the immutable usage cost. There's no background recalculation.

Backdated versions affect only future ingestion attempts for past timestamps, never events already stored. Choose accurate rates and dates, and put your evidence in sourceNote.

Migrating a v0.2 database

Only for a disposable development database that already has migrations 001–003:

bash

psql "$DATABASE_URL" -v ON_ERROR_STOP=1 -f db/004_workspace_pricing.sql
npm ci
npm run build:web
npm run start -w @agentmargin/api

Security notes

Only the authenticated workspace can create and list its prices, enforced by SQL filters and a composite foreign key.
The key digest records who added a price, but it's not a user or role system. Any valid workspace key can add future versions.
A compromised database role bypasses application authorization. No RLS, RBAC, public TLS ingress or backups are supplied.

Unknown costs Full spec on GitHub