# API reference

> The REST API by area: what every call shares, then one page per area with an example request and its answer.

Base URL: https://maindesk.smaverk.com. Send your key as `Authorization: Bearer <key>`. JSON in and out. The whole reference is machine-readable at [/openapi.json](https://maindesk.smaverk.com/openapi.json), and as one Markdown page at [/api.md](https://maindesk.smaverk.com/api.md).

## What every call shares

- Every answer ends with a `cost_line`: the machine's desk minutes and today's against the daily stop.
- An error is JSON: `{"error": {"code", "what_happened", "fix"}}` with a 4xx or 5xx status. The `fix` names the call to make next. The common ones are in [Errors and fixes](/docs/errors).
- A machine that is still starting answers `409 machine_starting` with a `Retry-After` header. Add `"wait": true` (or `?wait=1`) to wait instead.
- Common query parameters: `on` (linux, windows or mac), `wait` (1 or seconds), `offset`, `raw` (1 for bytes).

## Areas

| Area | What it covers |
| --- | --- |
| [Commands and jobs](/docs/api/commands) | Run one command on a machine and get its exit code and output, or start it in the background and follow it as a job. |
| [Machines](/docs/api/machines) | See each machine's state, wake it, put it to sleep, change the Linux size, and open an HTTPS preview of a server on a port. |
| [Files](/docs/api/files) | List, read, write, move and delete files on any machine, copy folders between machines, and send or fetch a whole folder. |
| [Tasks](/docs/api/tasks) | Hand long work to an agent on the desk, follow it, send it follow-ups, wait for it to end, and read its result, files and screenshots. |
| [Asks, the Inbox and pushes](/docs/api/asks) | An agent asks its human for a login, a code, an approval or a choice, and waits for the answer. |
| [The Mac](/docs/api/mac) | Run one command on a clean Mac with a folder from your desk, and get the files you name back on the desk. |
| [Agents and sign-in](/docs/api/agents) | The agents on your desk (Claude Code, Codex and others), setting them up and signing them in, your own agent commands, and the sign-in browser your agents use for websites. |
| [Account, keys and plans](/docs/api/account) | Sign up and get a key, see who a key belongs to, the account's plan, desk minutes and prices. |
| [Web page calls](/docs/api/web) | The calls the web page makes with a person's sign-in (a session cookie, not an agent key): settings, keys, sessions and push devices. |

## Next steps

- [Connect: CLI, MCP and API](/docs/connect): the three ways in, with the same key
- [Errors and fixes](/docs/errors): what an error says and what to do