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:

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