# REST API

Base URL: `https://api.volae.net`

## Authentication

Create an access token in **Settings → Access tokens** and send it as a bearer token:

```bash
curl https://api.volae.net/api/v1/products -H "Authorization: Bearer vol_…"
```

Tokens have one of three permissions: **Read** (`read`), **Read & write** (`write`) or **Approve & send** (`act`). A token can't create other tokens. Treat tokens like passwords; Volae only stores a hash.

## Calling actions

Every action is available as:

```
POST /api/v1/actions/{name}
Content-Type: application/json

{ ...input }
```

A field the action doesn't have is refused with `invalid_input` and `details.unknown` lists it, rather than being ignored. Lists take `limit` where the list can get long.

The input and output schemas are in the [action reference](actions.md); `GET /api/v1/actions` lists the actions your token can call, and `GET /api/v1/schema` returns the workspace's custom fields.

A few read actions also have short GET routes: `GET /api/v1/products`, `GET /api/v1/products/{product}/memory`, `GET /api/v1/people?…`, `GET /api/v1/people/{person}`.

## Errors

Errors use one shape and a stable `code`:

```json
{ "error": { "code": "not_found", "message": "Conversation not found", "details": { }, "requestId": "…" } }
```

| Code | HTTP | Meaning |
|---|---|---|
| `invalid_input` | 400 | The input didn't match the schema, or a value isn't allowed. `details` says which. |
| `invalid_token` | 401 | Missing, expired or revoked token. |
| `insufficient_credits` | 402 | Not enough credits for this. `details.needed` and `details.available` say how many. Top up or wait for next month's credits. |
| `read_only` | 402 | The workspace is read-only (trial ended, payment failed for 14 days, or subscription ended). `details.reason` says which. |
| `tier_required` | 402 | Your plan doesn't include this. `details.needed` says which plan does. |
| `forbidden` | 403 | Your token's permission doesn't allow this action. `details.need` says which one it needs (`read`, `write` or `act`). |
| `needs_web_confirmation` | 403 | Destructive actions must be confirmed in the web app. |
| `not_found` | 404 | The thing doesn't exist in your workspace. |
| `conflict` | 409 | It clashes with the current state (already running, already exists). `details.reason` says why. |
| `needs_product` | 409 | This follow-up needs a product and the workspace has none yet (lookup-only accounts). Add a product first. |
| `rate_limited` | 429 | Slow down; see `Retry-After`. |
| `upstream_error` | 502 | A service Volae depends on failed. Safe to retry. |
| `internal` | 500 | Volae's fault. Quote the `requestId` if you contact us. |

## Commits, proposals, goals and works

The workbench objects (commits, proposals, goals, stages, works, findings, profile blocks, decisions, files, source events, preferences) are all actions. [Commits, proposals, goals and works](workbench.md) lists them and shows how to export the commit log to git with `export_changes_git`.

## Real-time streams

`GET /api/v1/inbox/stream` and `GET /api/v1/runs/{id}/stream` are Server-Sent Events streams for new inbox activity and agent run progress.

The run stream sends the run's step-by-step events. Each event has a `seq` that counts up within the run, in order. A number can be missing in rare cases (an event that could not be saved even after a retry), so don't wait for one that hasn't arrived: compare with the last `seq` you have. Pass `?after=<seq>` with the last one you have to pick up where you left off after a dropped connection; you get every saved event after it, once. The stream sends:

| Event | Data | When |
| --- | --- | --- |
| `ready` | `{}` | Connected |
| `events` | `{ "events": [...] }` | New steps, oldest first: tool calls (`t: "tool"`, with `id`) and their results (`t: "tool_result"`, same `id`), what the agent said, `think` start and end, documents it wrote (`t: "doc"`), the check run on a document before it is saved (`t: "doc_check"`) and so on |
| `delta` | `{ "text": "...", "truncated"?: true }` | The sentence the agent is writing right now, in full so far. A very long one is cut to its last part and comes with `truncated: true`. Not stored; the finished sentence arrives as an event |
| `tool_delta` | `{ "id", "text", "path"?, "truncated"?: true }` | The document the agent is writing right now, in full so far, while the `write_path` call is still being composed. `id` is the tool call's id (the `tool` event with the same `id` follows once the document is complete) and `path` is where it is being written, when known. A very long one is cut to its last part and comes with `truncated: true`. Not stored; read the finished document from the file once the `tool_result` arrives |
| `run` | `{ "id", "status" }` | The run's status. When it ends, the remaining events come first, then this, then the stream closes |
| `ping` | `{}` | Every 25 seconds |

A run from another workspace returns 404. If the stream can't connect, read the same events with the `get_run_events` action (`after`, `limit`).

## Events

Product events use a separate, public **ingest key** (find it in **Settings → Connections → Send your own events**), not your access token — see [Track events](events.md).
