# API

> How to authenticate, and the conventions every route follows

> Nevia is in beta and open to selected teams. Public launch in Dec 2026. The CLI installs with `curl -fsSL https://get.nevia.cloud | sh`, and the MCP server is at https://api.nevia.cloud/mcp. A person signs in once in the browser.
> Setup, sign-in and requesting access: [SKILL.md](https://nevia.cloud/SKILL.md). When Nevia fits and when it doesn't: [why.md](https://nevia.cloud/why.md).

> For the complete documentation index, see [llms.txt](https://nevia.cloud/llms.txt). This page's HTML version: https://nevia.cloud/docs/reference/api

Base URL: `https://api.nevia.cloud/v1`. Every route except `/health` needs a Bearer token.

## Authenticate

The API accepts the same access token the CLI uses. Sign in once, then print the token for your request:

```bash
nevia login
export TOKEN=$(nevia auth access-token)
curl https://api.nevia.cloud/v1/me -H "Authorization: Bearer $TOKEN"
```

Tokens are short-lived JWTs. Run `nevia auth access-token` again when one expires; the CLI refreshes the session for you. For scripts, CI and agents, [give it access with a private key](https://nevia.cloud/docs/workspaces/private-key-auth.md) and set `NEVIA_KEY_FILE` to its key file: `nevia auth access-token` then prints a token for that principal, and `POST /v1/auth/token` is the route your own code can call with a signed assertion.

`/v1/me` returns who you are and your workspaces with your role in each. Permissions are checked per resource on every request.

## Conventions

* Ids are 27 lowercase letters and digits, such as `01d4cnjk3xg90y576w8y6t4gdwm`, and sort by creation time. Use them as returned.
* Responses are wrapped in the resource noun, `{computer}` for one, `{computers, next_cursor, has_more}` for a list.
* Errors are always `{error: {code, message, details, request_id}}`.
* Mutations accept an `Idempotency-Key` header. Creates require it.
* Long-running calls return `202` with `operations[]`. Poll them under Operations.

## Ids and names

Every resource has an id, minted by Nevia, and most also have a name you choose. Routes and tools that take a resource accept its id; many also accept a name within a workspace. A name is a DNS label: lowercase letters, digits and hyphens, not starting or ending with a hyphen, at most 63 characters.