# 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](/docs/call).

The full contract is [openapi.yaml](/docs/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**.

```sh
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`.

```json
{"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](/docs/errors), and the per minute limits are in [Limits](/docs/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](/docs/openapi.yaml).

## Next steps

- [openapi.yaml](/docs/openapi.yaml): every operation, its inputs and its answers
- [Use Facet from an agent](/docs/agents): the same operations as MCP tools
- [Errors](/docs/errors): every code and what to do