> ## Documentation Index
> Fetch the complete documentation index at: https://vms.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# API introduction

> Authentication, scopes, errors, and limits of the REST API.

The REST API gives a program access to one workspace. Each request uses an [API key](https://vms.dev/docs/workspace/api-keys.md) of that workspace.

Plan an API integration.

Ask what my program must read or change.
Tell me the endpoints and the scopes that it needs.
Do not ask me to share an API key.

## Base URL

```text theme={null}
https://vms.dev/api
```

Each path in this reference is relative to the base URL. For example, `GET /v1/workspace` is `https://vms.dev/api/v1/workspace`.

## Authentication

Send the key in the `Authorization` header:

```bash theme={null}
Authorization: Bearer <your-api-key>
```

The API also accepts the key in the `x-api-key` header. The key sets the workspace of the request, so a request has no workspace parameter.

## Scopes

Each endpoint needs one scope. See [API key scopes](https://vms.dev/docs/reference/workspace-access.md#api-key-scopes).

## Pagination

A list endpoint, such as `GET /v1/workspace-changes`, returns one page:

```json theme={null}
{
  "data": [],
  "nextCursor": "eyJjcmVhdGVkQXQiOi..."
}
```

Send `limit` (1 to 100, default 50) to set the page size. To get the next page, send the `nextCursor` of the last page as `cursor`. The last page has `"nextCursor": null`.

## Record IDs

Each record ID starts with a prefix that tells its type, such as `wsc_` for a workspace change, `sbx_` for a sandbox, and `op_` for an operation.

## Errors

An error response has a code, a message, and the ID of the request:

```json theme={null}
{
  "error": {
    "code": "unauthenticated",
    "message": "The API key is not correct, or somebody revoked it.",
    "requestId": "19283a6c-8864-483f-8dab-320eec5015e1"
  }
}
```

| Status | Code | Cause |
| - | - | - |
| 400 | `invalid` | The request is not valid. |
| 401 | `unauthenticated` | The key is missing, not correct, revoked, or expired. |
| 403 | `forbidden` | The key does not have the scope of the endpoint. |
| 404 | `not_found` | The resource does not exist. |
| 409 | `conflict` | The request conflicts with the current data, such as an `Idempotency-Key` that you sent with a different request. |
| 429 | `rate_limited` | The key sent more than 1,200 requests in one minute. |
| 500 | `internal_error` | An error occurred on the server. Try again later. |
| 503 | `no_capacity` | No host has room for the size of the sandbox. Wait `retryAfterSeconds`, then try again. |

A sandbox error can have two more fields:

* `retryAfterSeconds`: the time to wait before you try again. The `Retry-After` header has the same value.
* `sandboxId`: the sandbox that the error is about.

Each response has the `x-request-id` header. Give this ID when you ask for help.

The API also serves this reference as an OpenAPI 3.1 document at `https://vms.dev/api/v1/openapi.json`.

Read the [changelog.](https://vms.dev/docs/changelog.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.