REFERENCE
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.
Machine-readable
/openapi.jsonOpenAPI 3.1The complete schema: every endpoint, request body, response, and error type. Import it into Postman, Bruno, or a code generator.
/docs/<page>.mdMarkdownAny docs page as plain markdown for agents and terminals, for example /docs/cad-extract.md.
/llms.txt, /llms-full.txtIndexThe docs index and the full text of every page for LLM context.
/api/mcpMCPModel Context Protocol server: the same calls as tools, prompts, and resources.
/.well-known/skills/index.jsonAgent SkillsSKILL.md files an agent loads on demand: npx skills add https://fourechelon.com.
Authentication
Send Authorization: Bearer fe_live_.... Keys come from the dashboard and are hashed at rest. GET /api/v1/models and GET /api/health need no key. Non-2xx responses are never billed; every response carries X-Request-ID.
/api/v1/modelsModelsList models and runtime availability
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.
200successModel list
/api/v1/responsesRoweRun Rowe over a scene
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.
200successTyped spatial output
400errorinvalid_request_error: bad body, model, or Idempotency-Key
401errorauthentication_error: missing, revoked, or invalid API key
402errorpayment_required: an active or trialing paid API subscription is required
409erroridempotency_conflict / idempotency_in_progress
422errorinvalid_request_error: the Rowe worker rejected the input (for example a task that needs an image, or a point cloud kind outside unknown/box/surface/container)
429errorrate_limit_exceeded (per-minute or billing-period ceiling; see Retry-After)
503errordesktop_inference_unavailable / billing_unavailable / usage_finalization_unavailable
/api/v1/responses/batchRoweRun up to 32 Rowe requests in one call
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.
200successEvery item succeeded
207successAt least one item failed
400errorinvalid_request_error
401errorauthentication_error
413errorrequest_too_large
/api/v1/cad/extractFour CadExtract a CAD, drawing, or draw.io file
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.
200successfour-cad.extraction.v1
400errorinvalid_request_error: missing file_name, bad base64, refused content_url, or invalid target_contract
401errorauthentication_error
402errorpayment_required
413errorrequest_too_large: body over the ~6 MB platform limit or file over 25 MB
415errorunsupported_file_type (SolidWorks native files: export STEP)
422errorparse_error / timeout_error passed through from the converter
503errorconverter_unavailable
/api/v1/cad/extract/batchFour CadSubmit up to 32 files for asynchronous extraction
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.
202successBatch accepted
400errorinvalid_request_error (details name the offending item)
401errorauthentication_error
413errorrequest_too_large
415errorunsupported_file_type (the whole batch is rejected before anything is staged)
429errorrate_limit_exceeded: more than 5 batches in flight or 10 submitted per minute on one key
/api/v1/cad/extract/batch/{id}Four CadPoll a batch
200successBatch status and per-item results
401errorauthentication_error
404errornot_found: unknown id or another account's batch
/api/v1/cad/import-feature-treePartnersImport a partner feature tree as a cad_scene
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.
200successImported scene
400errorinvalid_request_error
401errorauthentication_error
402errorpayment_required
/api/v1/cad/partner-webhookPartnersReceive a signed partner feature-tree event
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.
200successAccepted
401errorinvalid or missing signature
/api/mcpMCPModel Context Protocol server (Streamable HTTP, stateless JSON)
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.
200successJSON-RPC response or batch
202successNotification accepted (no body)
401errorBilled tool called without Authorization
/api/healthOperationsAggregate health
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).
200successhealthy or degraded
503errordown