Skip to content
Trazum

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/capabilities

GET /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.

EndpointResult
GET /health200, { "ok": true, "schemaVersion": 1 }
GET /openapi.json200, the complete OpenAPI contract
GET /capabilities200, static harness import and access-channel metadata
POST /usage/import200, normalized native usage and conversion diagnostics; since 2.6.0
POST /savings/plan200, ranked savings plan with coverage evidence
POST /savings/verify200, saved-plan outcomes with later usage evidence
POST /cost200, estimated call, measured budget, verdict and scoped policy
Any other path or method404, 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 IDNative importNormalized usage
claude-codefrom-claude-code, Claude Code transcript JSONLbill
codexfrom-codex, Codex session JSONLbill
gemini-clifrom-gemini-cli, Gemini CLI session JSONL (and the older single-document .json)bill
cursornull: no native importerbill
mcp-clientnull: no native importerbill

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.

FieldAccepted valuesWhen omitted
modelString catalogue IDNo call estimate
inputTokens, outputTokensFinite non-negative numbers; fractional counts remain acceptedZero
basistoken-count or heuristictoken-count
label, sessionStrings; an empty string means absentNo 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.

  • call is a catalogue-priced estimate, or null when absent/unpriced.
  • budget is the measured position, or null without configured budget or measurement. Its window identifies the measured period; a snapshot is not a guarantee of live accounting.
  • verdict is within, over, or cannot-tell. All three return HTTP 200: transport success is not spending permission.
  • reason distinguishes no-budget-configured, nothing-measured, and model-unpriced. It is null for a judged budget. afterCall carries the measured and estimated halves separately.
  • policy independently judges day, session and label ceilings. no-policy means 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 fieldMeaning
schemaVersion1
plan or verificationThe core plan document or verification result
evidencePriced/unpriced calls, skipped line numbers, period and catalogue provenance
limitationsAssumptions 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.