The four faces

kestrel.markets is one API with four equal surfaces. HTTP + SSE is canonical. The TypeScript SDK, the CLI, and MCP are thin projections over the same operations — not separate implementations, and none privileged.

HTTP + SSE
  ├── TypeScript SDK
  ├── CLI
  └── MCP

All four return the same operation IDs, events, receipts, diagnostics, and artifacts. There are no face-only shortcuts and no impoverished MCP wrappers. A session started on one face is inspected and resumed on any other. (The published CLI runs the local runtime and is platform-connected today — sim, prove, certify, and verify all reach api.kestrel.markets; the fuller mode driving arbitrary hosted sessions from every verb lands later. See CLI.)

The elegance test

The whole public surface is seven operations (ADR-0004): discover, browse, check, run, score, prove, continue.

GET  /.well-known/kestrel-markets
GET  /catalog
POST /validate
POST /simulate
POST /grade
GET  /proof/{id}
GET  /offers/{id}

Everything else is a rendering, a meter, or a receipt.

The faces

HTTP + SSE

The canonical face. Every operation is a plain HTTP request; long-running work streams progress and receipts over Server-Sent Events. The other three faces are generated projections of exactly these endpoints — nothing is added or hidden.

TypeScript SDK

A typed client that mirrors the HTTP surface one-to-one: the same operation IDs, events, receipts, and artifacts, with types generated from the same contract. No SDK-only conveniences that the wire protocol lacks.

CLI

npx kestrel.markets runs the open-source local runtime — parse, frame, grade, and replay against the committed regime tapes, entirely on your machine — and is platform-connected today: sim, prove, certify, and verify reach api.kestrel.markets to shareable proof URLs, free and anonymous. The fuller mode — the same seven operations from a terminal, driving arbitrary hosted sessions resumable on any other face — lands later.

MCP

A Model Context Protocol projection so agents drive the platform natively. It is a thin, equal wrapper over the canonical endpoints — never an impoverished subset.

The website is a fifth client

This documentation site is itself a plain client of the same public API — never a privileged face. Agents that prefer markdown can read every docs page, including the home page, as clean markdown on the same URL via Accept: text/markdown content negotiation, fetch the home page directly at /home.md, or start from the llms.txt corpus, which links a pre-built markdown twin of every docs page.