Docs
Sign inJoin the waitlist

The /v1 API

The web app and every MCP tool use the same HTTP API. Use it to make Models, ask for Changes and manage a workspace from your own code. To call a Model, use its OpenAI-compatible endpoint instead; see Call a Model.

The full contract is openapi.yaml (OpenAPI 3.1): every operation, its inputs and its answers.

Base URL

Every path below is under https://facet.halfspacelabs.com/v1. The API only ever adds fields; it never removes or renames one, so ignore fields you don’t know.

Authentication

Send an API key as a bearer token. Make one under Settings, Keys.

curl https://facet.halfspacelabs.com/v1/models \
  -H "Authorization: Bearer $FACET_API_KEY"

A key acts with its role (collaborator or viewer) and, if it has one, its Model scope. Keys never approve a quote, merge a Change or edit policy: a person does that in the web app or through an MCP client, which signs them in.

Errors

Every error has one shape. Branch on code; show or log message.

{"error": {"code": "strict_merge", "message": "merge protection is Strict: a Model owner approves each Ready Change", "approvers": [{"id": "usr_...", "name": "Dana", "email": "dana@example.com"}]}}

A 409 with approvers means the action waits for one of those people. Every code is in Errors, and the per minute limits are in Limits.

Endpoints

{model} is a Model’s name. {change} is a Change’s number, or its ID before it starts.

Models

Method Path What it does
GET /models List the workspace’s Models
GET /models/{model} One Model: what it takes and returns, its Latest version and how many evals pass
GET /models/{model}/activity What happened to it, newest first
GET /models/{model}/settings Its settings, such as Approve each merge
PUT /models/{model}/settings Change its settings; Model owners only
POST /models/{model}/rollback Move Latest back to an earlier Version, or undo the last rollback
POST /models/{model}/try Call a Version once, as a caller would
POST /models/{model}/archive Take it out of service; nothing is deleted
GET /models/{model}/export Latest as data: Instructions, evals and examples
GET /models/{model}/export.zip Latest as a zip, with its adapter

Drafts

Method Path What it does
POST /model-drafts Start a draft from a description and sample inputs
GET /model-drafts/{draft_id} The draft as it stands
POST /model-drafts/{draft_id}/redraft Redo it with your changes, in plain words
POST /model-drafts/{draft_id}/create Make the Model, with a Planned Change to build v1
DELETE /model-drafts/{draft_id} Scrap it

Changes

Method Path What it does
POST /models/{model}/changes Ask for a change in plain words. It plans and quotes; nothing is spent
GET /models/{model}/changes List the Model’s Changes
GET /models/{model}/changes/{change} One Change: its state, plan, quote, steps and evals
POST /models/{model}/changes/{change}/start Start a Planned Change, accepting its quote
POST /models/{model}/changes/{change}/answer Answer a question the Change’s agent asked
POST /models/{model}/changes/{change}/raise Continue a Change that stopped at its quote, with a higher one
POST /models/{model}/changes/{change}/stop Stop it; you pay only for what ran
POST /models/{model}/changes/{change}/merge Approve and merge a Ready Change
POST /models/{model}/changes/{change}/close Close it without merging
POST /models/{model}/train-again Train v1 again after its Change failed

Versions

Method Path What it does
GET /models/{model}/versions List the Model’s Versions
GET /models/{model}/versions/{version} One Version and its scores
GET /models/{model}/versions/{version}/comparisons Its comparisons with frontier models
POST /models/{model}/versions/{version}/comparisons Quote a comparison, or start one with confirm: true
GET /models/{model}/versions/{version}/export.zip One Version as a zip

Evals

Method Path What it does
GET /models/{model}/evals List the Model’s evals
POST /models/{model}/evals Add an eval
GET /models/{model}/evals/{eval_id} One eval, with its grader, bar and score
PUT /models/{model}/evals/{eval_id} Edit or rename it; loosening it waits for a Model owner
POST /models/{model}/evals/{eval_id}/examples Add examples to it

Data

Method Path What it does
POST /uploads Start an upload of training data or hidden eval data
POST /uploads/{upload_id}/rows Add up to 1,000 rows to an open upload
GET /uploads/{upload_id} Where an upload stands
POST /datasets Start a workspace dataset that every Model can draw on
GET /datasets List the workspace’s datasets
POST /datasets/{dataset_id}/uploads Start sending a CSV or JSONL file of up to 5 GB
POST /models/{model}/corrections Send the right answer to a call

Workspace

Method Path What it does
GET /me Who is signed in, where, and what waits for them
GET /approvals What waits for your approval
GET /members List the workspace’s members
POST /invites Invite someone, with a role
GET /keys List API keys
POST /keys Make an API key
DELETE /keys/{key_id} Revoke a key
GET /usage A period’s calls and spend, by day, Model, key and Change
GET /billing The plan, card, free credit and invoices
GET /events Server-sent events, resumed with Last-Event-ID

A few endpoints work only for a signed-in person in the web app, never for a key: deleting data, viewing hidden rows and connecting outside data. Each one says so in openapi.yaml.

Next steps

Esc