API reference

Endpoint and scope matrix

Only the public cached price feed is available today. Scope names are proposed. Validation endpoints are designed to check contracts without publishing or running them.

Method / path	Purpose	Planned scope
GET /v1/models	List eligible models	catalog:read
POST /v1/chat/completions	OpenAI-format inference	inference:write
POST /v1/policies	Create a versioned policy	policy:write
POST /v1/policies/validate	Validate a policy without publishing	policy:validate
GET /v1/policies/{policy_id}	Read a policy revision	policy:read
POST /v1/grammars/validate	Validate a grammar contract	grammar:validate
POST /v1/action-graphs/validate	Validate a context action DAG	actions:validate
POST /v1/action-graphs	Publish a versioned action DAG	actions:write
GET /v1/traces/{trace_id}	Read a redacted inference trace	trace:read
GET /v1/usage	Read scoped usage and costs	usage:read
POST /v1/reports/sovereignty	Request a scoped provenance and sovereignty report	reports:read
GET /api/model-rates	Read the public cached model-rate snapshot	Public read
POST /v1/policies/{policy_id}/activate	Activate or roll back an authorized policy revision	policy:activate
GET /v1/reports/{report_id}	Read a scoped report job	reports:read
POST /v1/grammars	Publish a versioned grammar	grammar:write
GET /v1/grammars/{grammar_id}	Read a grammar revision	grammar:read
GET /v1/action-graphs/{graph_id}	Read an action graph revision	actions:read
POST /v1/reports/provenance	Request a scoped provenance report	reports:read

Request and response conventions

Use JSON with UTF-8 and bearer authorization for the planned platform APIs. Server-issued IDs identify requests, traces and immutable policy/action revisions. Mutation requests will require an Idempotency-Key scoped to the tenant, operation and canonical payload; reusing a key with different content returns a conflict. Validate APIs have no publication side effect.

Proposed policy validation response

A schema check is not a capability certification. Validation also resolves tenant ownership, grammar/tool references, cycles, placement support and required joins. Unknown fields and unsupported controls fail validation.

json

{
  "valid": false,
  "errors": [
    {
      "path": "/routing/regions",
      "code": "region_capability_unverified",
      "message": "The route cannot satisfy the required processing boundary."
    }
  ]
}

Protocol support

The first proposed production slice is a certified OpenAI-format chat-completions route. Responses API, Anthropic-format messages, Gemini native, realtime/audio and other formats remain separate future compatibility work. Do not infer support from a logo or an endpoint pattern.

Public model snapshot

GET /api/model-rates reads a persisted snapshot. Upstream refresh runs on a two-minute schedule, independently of page requests. Rates are USD per million input/output tokens. Weekly popularity is the source catalog ordering by tokens processed in the last week. It is not global adoption or model quality. Missing benchmark scores remain missing. Base token prices do not include every tier or non-token charge.