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
- openapi.yaml: every operation, its inputs and its answers
- Use Facet from an agent: the same operations as MCP tools
- Errors: every code and what to do