# API reference

> Every public endpoint with its request and response shapes, generated from the same constants the routes use. The full OpenAPI 3.1 document is at /openapi.json; every docs page is also available as markdown by appending .md, and /llms.txt indexes them for agents.

Source: https://fourechelon.com/docs/api-reference · Machine-readable: https://fourechelon.com/openapi.json · Index: https://fourechelon.com/llms.txt

## Endpoints

- **GET `/api/v1/models`** — List models and runtime availability (Models)
  Public. Returns the model cards with pricing, supported tasks, and input modalities, plus whether the desktop inference runtime is available right now (runtime_available). Never billed.
- **POST `/api/v1/responses`** — Run Rowe over a scene (Rowe)
  Send a cad_scene (from /api/v1/cad/extract, ideally target_contract both) or a point_cloud_scene with a task_type. Returns typed spatial output, usage, and a request_id. Worker validation failures are 422 invalid_request_error; an unavailable runtime is 503 desktop_inference_unavailable. Requests wait up to 18 s for the desktop worker.
- **POST `/api/v1/responses/batch`** — Run up to 32 Rowe requests in one call (Rowe)
  Each item has the same shape as POST /api/v1/responses. The envelope returns 200 when every item succeeded and 207 when any item failed; data[] is in request order and every entry carries its own status.
- **POST `/api/v1/cad/extract`** — Extract a CAD, drawing, or draw.io file (Four Cad)
  Accepts STEP, STP, IGES, IGS, DXF, PDF, SVG, DRAWIO, XML, PNG (xml and png only when they carry a draw.io diagram). Send the file as multipart/form-data, as JSON with content_base64, or as JSON with content_url for the server to download. The hosting platform caps request bodies at about 6 MB, so inline uploads work up to roughly 4 MB; larger files (up to 26214400 bytes) must use content_url. Returns four-cad.extraction.v1. Billed as input tokens = ceil(bytes / 4) and output tokens = ceil(response JSON / 4); non-2xx is never billed.
- **POST `/api/v1/cad/extract/batch`** — Submit up to 32 files for asynchronous extraction (Four Cad)
  Multipart (repeat the files part) or JSON items[]. Returns 202 with a batch id and status_url; poll GET /api/v1/cad/extract/batch/{id}. Results and staged files are deleted 24 hours after submission. Only 2xx items are billed.
- **GET `/api/v1/cad/extract/batch/{id}`** — Poll a batch (Four Cad)
  
- **POST `/api/v1/cad/import-feature-tree`** — Import a partner feature tree as a cad_scene (Partners)
  For CAD partners (Adam, Onshape-style feature trees). Authenticated with the caller's API key; the feature tree becomes a scene Rowe can reason over.
- **POST `/api/v1/cad/partner-webhook`** — Receive a signed partner feature-tree event (Partners)
  Signed with HMAC-SHA256 over the raw body using the partner webhook secret, sent in X-Four-Echelon-Signature. Unsigned or badly signed posts are 401.
- **POST `/api/mcp`** — Model Context Protocol server (Streamable HTTP, stateless JSON) (MCP)
  JSON-RPC 2.0. Methods: initialize, ping, tools/list, tools/call, prompts/list, prompts/get, resources/list, resources/read. Tools: extract_cad, extract_cad_from_url, rowe_respond, list_models, list_supported_formats. Billed tools forward to the REST routes they mirror under the same Authorization header. A missing key on a billed tool is HTTP 401 with a JSON-RPC error.
- **GET `/api/health`** — Aggregate health (Operations)
  Public. 200 with status healthy or degraded, 503 when down. Checks Convex, the Four Cad converter, the Rowe runtime, and desktop inference availability (rowe_availability).

Full OpenAPI 3.1 document: https://fourechelon.com/openapi.json