Overview
The model-fusion HTTP/service contract.
FusionKit has two API surfaces. The first is the runtime gateway surface that coding agents and OpenAI-compatible clients call locally. The second is the generated model-fusion harness-executor contract used by protocol consumers.
Runtime gateway routes
The neutral routes are implemented by @velum-labs/routekit-gateway and composed with
@fusionkit/gateway when you run fusionkit codex, fusionkit claude,
fusionkit cursor, or fusionkit serve.
| Route | Purpose |
|---|---|
/v1/chat/completions | OpenAI Chat Completions dialect for generic clients, Cursor bridge, and raw endpoint usage. |
/v1/responses | OpenAI Responses dialect used by Codex. |
/v1/messages | Anthropic Messages dialect used by Claude Code. |
/v1/messages/count_tokens | Anthropic token-count helper. |
/v1/models | Model listing in OpenAI or Anthropic shape. |
/v1/cursor/chat/completions | Cursor BYOK hybrid: accepts Cursor's Responses-shaped body posted to a Chat Completions path (set Cursor's base URL override to .../v1/cursor). Plain Chat Completions bodies pass through untranslated. Model ids may be sent as routekit/<served-id>. |
/v1/cursor/models | Mirror of /v1/models for Cursor probing relative to its BYOK base URL. Every id is advertised as routekit/<served-id> so no name starts with claude- or gemini-. |
/v1/embeddings | Embeddings when the backend supports it. |
/health | Unauthenticated health check. |
Use fusion-panel for fused answers. Use a panel member id, such as gpt,
sonnet, or gemini, for direct passthrough behavior.
curl "$FUSION_URL/v1/chat/completions" \
-H 'content-type: application/json' \
-d '{
"model": "fusion-panel",
"messages": [
{ "role": "user", "content": "Explain this repository." }
]
}'If the gateway was started with --auth-token, send
Authorization: Bearer <token> or x-api-key: <token>.
Generated harness-executor contract
The contract describes the HTTP/JSON harness-executor seam: FusionKit calls it to ask the executor to run a coding-harness task and return persisted JSON Schema audit records.
- Execute a model-fusion harness task:
POST /v1/harness-executions
The OpenAPI 3.1 source lives with the protocol package and is the source of truth for generated pages in this section.
Why generated?
- The contract is versioned and validated in CI; copying it into prose would immediately drift.
- The renderer produces request/response schemas, examples, and a try-it panel directly from the spec.
The durable record shapes (rows, receipts, candidates, judge syntheses) are
defined as JSON Schema in the same protocol package; the OpenAPI document
references those records rather than re-declaring them. Regenerate the MDX with
pnpm generate:openapi whenever the contract changes.
Trace and evidence contracts
Runtime observability is OpenTelemetry-native: components emit real spans and
log-based events over OTLP/HTTP, correlated by W3C traceparent/baggage,
using the fusion semantic conventions in spec/fusion-trace/registry.json
(candidate spans and step events, GenAI chat spans, tool execution, judge
thinking, cost). See Observability for the user
workflow.