API
The endpoint contract
Served planes
| Plane | Wire | Specified by |
|---|---|---|
| · | · | · |
/v1 | OpenAI-compatible chat completions and model listing | OpenAI's API, served verbatim |
/v1/messages | Anthropic-compatible messages and count_tokens | Anthropic's Messages API, served verbatim |
/api, /infill | Ollama-compatible chat, generate, and infill | Ollama's API, served verbatim |
/agent/v1 | Agent tasks, approvals, the tool catalog, sessions: 12 routes | The frozen OpenAPI document |
/host/v1 | Host identity, health, telemetry: 8 routes | The frozen OpenAPI document |
/recorder/v1 | Flight Recorder (per-rack grants, write-token ingest, purge, and the transcript read face): 8 routes | The frozen OpenAPI document |
Contract version 5.0.0. The governed planes are specified by the machine-readable document below; the compatible facades are specified upstream and served verbatim. Conifer semantics ride only in the x-conifer-* header family, never in bespoke body fields.
Additive-only evolution
That rule, quoted verbatim from the canonical contract, governs every plane above. Fixtures are normative: when code and contract disagree, the code is wrong. A client may therefore ignore anything it does not recognize: an unknown field, header, or code is never an error.
The routing slot
A client submits an ask; the host executes within it; a receipt discloses what actually ran.
The ask
| Model field | Meaning |
|---|---|
<concrete-id> | Serve exactly this model, or refuse with a typed error. A named model is never silently substituted. |
Credit-spending calls carry a client-minted idempotency-key header, stable per turn, so a retry never bills twice.
The receipt
Response headers on a settled completion disclose the execution:
| Header | Meaning |
|---|---|
x-conifer-requested-model | The ask, verbatim. |
x-conifer-effective-model | The model that executed. |
x-conifer-receipt-reason | Opaque execution detail from the deciding native hop. |
x-conifer-endpoint | The venue that served it, e.g. credits or byok:<provider>. |
x-conifer-cost-nanousd | Settled cost in nano-USD when the call was metered. Absent when unmetered; absent is never zero. |
A hop that decides emits its own receipt; a hop that relays forwards the upstream receipt unchanged. The header family versions add-only: a v2 may add headers, never remove or rename them.
Changelog
| Version | Date | Change |
|---|---|---|
4.0.0 | 2026-08-04 | Selection is explicit per invocation: choose one exact model or one daemon-owned logical model alias. The ambient session-wire override was removed, and session registration carries no inference-selection state, so a named model can never be silently replaced by global routing state. |
2.0.0 | 2026-07-22 | Baseline reset — the only breaking change this contract has taken. The host withdrew six plane families it no longer serves: /lab/v1 (the kernel lab as an API), /observe/v1 (the queryable observability surface), /canopy/v1 (the metaharness read slice), and the /agent/v1 sub-planes for workflows, runs, and agent-spec CRUD. What remains is what the host mounts: agent tasks, approvals, the tool catalog, sessions, host identity and health, and the Flight Recorder. Every entry below this line describes surface that a 2.x host may no longer serve; they are kept as the record of how the wire got here, not as a description of it. |
2.2.0 | 2026-07-29 | The Flight Recorder's read face mounts, so the family that owns the tape can finally answer for it: GET /recorder/v1/transcript/schema (the surface's discovery document, plus cross-store freshness), POST /recorder/v1/transcript/query (the observe DSL over surface transcript), and POST /recorder/v1/transcript/questions/{name} (the three verified questions — rack timeline, turn drill-in, and search). Reads were originally handed to /observe/v1 surface transcript, but the 2.0.0 baseline withdrew that plane and nothing re-mounted it, so the recorder had a write half and no read half while the prose named a plane this host does not serve. The read half joins the write half: one family, one prefix, one fail-closed bearer arm, and read-only by construction — every store opens read-only, so no route here can arm, ingest, or purge. A query must name its rack (an unscoped cross-store merge is refused, not widened). |
2.1.0 | 2026-07-29 | Token binding let a session registration bind a harness correlation token to the row it minted and returned the D8 fingerprint and grants actually honored. The same release added recorder attribution and turn route/outcome disclosure. Its inference-selection extension was retired by 4.0.0. |
1.4.0 | 2026-07-09 | Flight Recorder Phase 1: the /recorder/v1 write/control family mounts — arm/disarm a rack's recording grant (PUT /recorder/v1/racks/{rack_id}), review grants (GET /recorder/v1/racks), write-token-gated capture ingest (POST /recorder/v1/ingest), and purge with crypto-shred (DELETE /recorder/v1/racks/{rack_id}/history) — every response the one RecorderEnvelope, bearer required even on loopback. Recorder reads mount no new noun; they ride /observe/v1 as surface transcript. The same window mounted the /canopy/v1 read slice (instances, tasks, task events, placement dry-run) additively, consuming no version slot of its own. |
1.3.0 | 2026-07-09 | Team Pulse: the /observe/v1 plane lands — the queryable observability surface. Four read-only routes (GET /observe/v1/surfaces, GET /observe/v1/surfaces/{surface}/schema, POST /observe/v1/query, POST /observe/v1/questions/{name}) over the ObserveEnvelope schema; bearer required even on loopback; the async query door stays reserved, not mounted. |
1.2.0 | 2026-07-06 | Session state adds cancelled and waiting; suspend_kind and wrapper_cycle; run inputs and verified retry provenance (retried_from); external session registration (POST /agent/v1/sessions, heartbeat, end) and the session work receipt (GET /agent/v1/sessions/{id}/receipt); pause, resume, and run-now on runs; task journaling (GET /agent/v1/tasks/{id}); SubstrateInfo adds contract_version, the capability probe. |
1.1.0 | 2026-07-05 | One host: the OpenAI and Ollama facades and the observation plane ride the managed endpoint. Session adds waiting_on, cwd, tokens, and route; GET /agent/v1/runs/{id}; the bearer security scheme for non-loopback binds. |
1.0.0 | 2026-06-13 | The native-plane document freezes (x-status: final), reconciled with the host's route table in both directions: every documented path is mounted, every mounted native path is documented. |
Every entry except the 2.0.0 baseline reset is additive: no other version has removed, renamed, or retyped a member. Upstream, 2.0.0 withdrew whole plane families from the host's own document. This document keeps them, because the surfaces built against them still project them, so it is a superset of the upstream contract rather than a copy of it.
Machine-readable
The normative artifact is the OpenAPI 3.1 document the native planes are generated from: openapi-native-planes.yaml. The copy served here is byte-identical to the contract this site is built against.
A live host discloses its own contract version at GET /host/v1/info (contract_version), so a client can probe capability before relying on it.