Local HTTP API
Documentation index · Setup · JSON contracts · Gateway
trazum serve exposes read-only cost and savings analysis on 127.0.0.1, or a Unix socket.
It estimates a proposed call against the configured budget and scoped limits. It
does not invoke a model, reserve money, update spending, or enforce a provider
request. Use the gateway when the decision must sit in the call path.
Start and discover#
npx @trazum/cli serve --port 7317
curl http://127.0.0.1:7317/health
curl http://127.0.0.1:7317/openapi.json
curl http://127.0.0.1:7317/capabilitiesGET /openapi.json returns the OpenAPI 3.1 contract generated by the same CLI
package. Its default server URL uses port 7317; replace the port when starting
with --port. The Unix-socket transport exposes the same paths.
| Endpoint | Result |
|---|---|
GET /health | 200, { "ok": true, "schemaVersion": 1 } |
GET /openapi.json | 200, the complete OpenAPI contract |
GET /capabilities | 200, static harness import and access-channel metadata |
POST /usage/import | 200, normalized native usage and conversion diagnostics; since 2.6.0 |
POST /savings/plan | 200, ranked savings plan with coverage evidence |
POST /savings/verify | 200, saved-plan outcomes with later usage evidence |
POST /cost | 200, estimated call, measured budget, verdict and scoped policy |
| Any other path or method | 404, error: "not-found" with a detail string |
All responses are JSON with Cache-Control: no-store. No authentication or CORS
headers are added. The listener remains loopback-only; there is no configurable
network bind address. Do not expose it through a public reverse proxy.
A request whose Host header is not localhost, 127.0.0.1 or [::1] on the
port the server is bound to gets 403 with error: "forbidden-host", on every
path. A web page that points its own hostname at 127.0.0.1 (DNS rebinding)
sends its own hostname, and text/plain is the one body type it can send
without a preflight, so the two checks together keep it from reading the answer.
The Unix-socket transport has no port and skips the Host check. A client behind
a reverse proxy that rewrites Host is refused; that setup is unsupported.
Discover integration capabilities#
GET /capabilities returns schemaVersion: 1, accessChannels, taskQuality
and harnesses. It reads no files, environment variables, sessions or network
services. This is a support registry, not an installation detector.
| Harness ID | Native import | Normalized usage |
|---|---|---|
claude-code | from-claude-code, Claude Code transcript JSONL | bill |
codex | from-codex, Codex session JSONL | bill |
gemini-cli | from-gemini-cli, Gemini CLI session JSONL (and the older single-document .json) | bill |
cursor | null: no native importer | bill |
mcp-client | null: no native importer | bill |
accessChannels: ["cli", "mcp", "http"] names Trazum entry points. It does not
claim that a harness automatically exposes, installs or calls all three.
normalizedUsage refers to the Trazum usage JSONL format; it is not a promise
that an arbitrary harness export is already compatible.
Every harness has billingMode: "unknown" and automaticInterception: false.
A harness name does not establish whether a user pays a subscription or API
charges. The gateway is opt-in, not an automatically installed hook. Likewise,
taskQuality: "not-measured" makes no cross-harness answer-quality claim.
The browser-safe core exports HARNESS_CAPABILITIES and
getHarnessCapability(id). Lookup uses exact IDs and returns null for unknown
clients, rather than borrowing a different client's importer.
Ask before a call#
curl http://127.0.0.1:7317/cost \
-H 'Content-Type: application/json' \
--data '{"model":"claude-opus-5","inputTokens":1200,"outputTokens":300,"basis":"token-count","label":"synthetic-demo"}'All fields are optional. An absent or whitespace-only body is {}. The body
must otherwise be a JSON object, at most 1,000,000 bytes.
| Field | Accepted values | When omitted |
|---|---|---|
model | String catalogue ID | No call estimate |
inputTokens, outputTokens | Finite non-negative numbers; fractional counts remain accepted | Zero |
basis | token-count or heuristic | token-count |
label, session | Strings; an empty string means absent | No scope key |
Unknown properties are ignored. Invalid JSON, arrays, null, invalid field
types, negative/non-finite counts, unsupported basis, or oversized bodies
return 400 with { "error": "bad-request", "detail": "..." }. A POST must send
content-type: application/json (parameters such as charset are fine);
anything else, or none, returns 415 with error: "unsupported-media-type".
The server used to accept JSON whatever the Content-Type; it no longer does. It
does not accept raw prompt text or count tokens here.
Interpret the answer#
Every successful response contains schemaVersion, call, budget, verdict,
restsOn, reason, afterCall, and policy. The OpenAPI schema spells out
nullable fields and discriminated combinations.
callis a catalogue-priced estimate, ornullwhen absent/unpriced.budgetis the measured position, ornullwithout configured budget or measurement. Its window identifies the measured period; a snapshot is not a guarantee of live accounting.verdictiswithin,over, orcannot-tell. All three return HTTP200: transport success is not spending permission.reasondistinguishesno-budget-configured,nothing-measured, andmodel-unpriced. It isnullfor a judged budget.afterCallcarries the measured and estimated halves separately.policyindependently judges day, session and label ceilings.no-policymeans no applicable ceiling was judged; it does not grant unlimited budget. Inspect waivers and all judgements. Session identifiers are never echoed.
For fail-closed integration, require both the budget and applicable policy judgements needed by your application to be acceptable. Do not turn unknown measurements into zero, or treat an unknown model as free.
The endpoint evaluates snapshots supplied by the CLI. Concurrent callers can receive the same answer; this API has no reservation ledger. See the gateway for enforcement semantics and its limits.
Import native usage#
POST /usage/import is available in 2.6.0 and later.
Build this checkout and run
node packages/cli/dist/index.js serve --port 7317 from the repository root.
Check GET /openapi.json for the route before using it.
The request has required format (claude-code, codex or gemini-cli,
the last since 2.7.0) and nonblank text containing the native session text. Optional label is nonblank text
of at most 200 characters, supplied explicitly; it is never inferred from a
path. Unknown properties, invalid types and unsupported formats return
400 bad-request. The endpoint receives content, never a filename: no files,
network services, models or provider APIs are accessed.
A successful response has schemaVersion: 1, format, normalized JSONL
log, numeric records, converter diagnostics, evidence and limitations.
Evidence reports billingMode: "unknown", valuation: "api-equivalent" and
completeness: "not-established". Prompts, tool content, working directories
and paths are not copied; session IDs and explicit labels remain. Inspect
those identifiers before sharing the normalized output.
Pass the returned log to /savings/plan or /savings/verify and retain
import diagnostics alongside their results. Zero output means no convertible
records, not zero usage or free work. A successful conversion cannot establish
that the supplied source is complete. Deduplication is limited to each request;
do not concatenate overlapping imports.
Both the whole JSON request and the complete JSON response are capped at
1,000,000 UTF-8 bytes. This includes labels, diagnostics and JSON escaping,
so an accepted input can still produce an oversized response. Overflow returns
400, without a partial result. Reduce the source or shorten the label; do not
blindly split and recombine Codex snapshots, whose interpretation depends on
counter and model context. For verification, normalized log and serialized
plan together must fit the separate savings request's 1,000,000-byte cap.
Plan and verify savings#
POST /savings/plan takes { "log": "normalized JSONL text" }.
POST /savings/verify takes { "log": "later normalized JSONL text", "plan": "serialized plan JSON" }.
These endpoints receive text, never file paths. They do not read files, persist
plans, invoke models, reserve funds or access provider services. Import native
sessions first with HTTP /usage/import, CLI
from-claude-code / from-codex or MCP import_usage,
and retain their conversion diagnostics separately. A session sent as log
directly is refused with 400, naming its format and the /usage/import
request that converts it; a provider report is named with its CLI converter. The HTTP endpoints cannot recover excluded source records.
Use the same server configuration for both requests. Its selected catalogue,
including any configured price overlay, prices all supplied logs. Request-level
pricing overrides are refused. GET /openapi.json is the runtime contract;
check it before using endpoints from a local development build with an older release.
The savings routes are included in release 2.5.2. The native import route above requires 2.6.0 or later; inspect runtime OpenAPI rather than assuming all servers expose the same routes.
This complete example uses synthetic normalized records and Node.js 20+:
const base = 'http://127.0.0.1:7317';
const log = JSON.stringify({
model: 'claude-opus-5', label: 'synthetic-work',
usage: { input_tokens: 400000, output_tokens: 1000 },
});
async function post(path, payload) {
const response = await fetch(base + path, {
method: 'POST', headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(payload),
});
const result = await response.json();
if (!response.ok) throw new Error(result.detail);
return result;
}
const planned = await post('/savings/plan', { log });
const checked = await post('/savings/verify', {
plan: JSON.stringify(planned.plan), log,
});
console.log(checked.verification, checked.evidence);For real verification, replace the second log with later comparable usage.
Save only the response's plan field as a plan document; the complete response
also contains evidence and limitations worth retaining. The plan is compatible
with CLI verify --against and MCP verify_savings.
| Response field | Meaning |
|---|---|
schemaVersion | 1 |
plan or verification | The core plan document or verification result |
evidence | Priced/unpriced calls, skipped line numbers, period and catalogue provenance |
limitations | Assumptions and limits that the arithmetic cannot establish |
Projected savings and measured stakes remain separate. Verification retains
arrived, not-arrived, cannot-tell, attribution and gate failures. An arrived
action does not prove equal answer quality or net savings. A vanished workload
remains unknown. evidence.complete only means no unpriced calls or skipped
lines were detected; it does not prove complete billing or comparable periods.
Pricing review dates alone do not establish identical custom rates.
Both endpoints reject unknown request properties, missing/whitespace text,
invalid JSON, paths with no readable records and malformed nested plan fields.
Plan fields are validated defensively, including unknown properties. Empty or
entirely unreadable logs return 400 bad-request; a log with recognized but
unpriced records returns 200 with explicit incomplete evidence and no invented
priced usage. Mixed malformed lines remain numbered evidence gaps.
The 1,000,000-byte cap covers the entire UTF-8 request, including both text
fields and JSON escaping. Oversized bodies return 400, not a partial result.
The /cost endpoint keeps its older permissive unknown-property behavior.