# REST API (/docs/api)



The Rock8Cloud REST API lets scripts, CI jobs and agents do what the dashboard does. Every operation has an `operationId`, a summary and a description that names the required scopes.

## Base URL and OpenAPI [#base-url-and-openapi]

```text
https://app.rock8.cloud/api
```

The OpenAPI 3 document is public at `https://app.rock8.cloud/api/openapi.json`. No token is needed to read it.

## Authentication [#authentication]

Send a token on every request as a Bearer credential:

```http
Authorization: Bearer <token>
```

Two token types are accepted:

* **API key** - a `vhk_...` token tied to one organization. Create it under **Settings** → **API Keys**, see [API Keys](/docs/guides/api-keys).
* **OAuth 2.0** - authorization code flow with PKCE. An OAuth token is not bound to one organization, so also send `X-Organization-Id: <organizationId>` to choose the organization the call acts on.

### Scopes [#scopes]

* Reads need `read:<resource>`.
* Mutations need both `read:<resource>` and `write:<resource>`, including previews served over POST.
* Nested resources can need extra parent-resource scopes.
* Each operation's description lists its scopes and any role restrictions.

## Versioning [#versioning]

Pin the API version with a request header:

```http
Rock8cloud-Version: 2026-10-01
```

* `2026-10-01` is the only version today.
* Without the header you get the latest version.
* An unknown value returns `400` with code `UNSUPPORTED_API_VERSION`.
* Every API response echoes the version it was served with in its `Rock8cloud-Version` header.

<Callout type="info">
  Pin the header in scripts and agents. A new version can then never change behavior under a running integration.
</Callout>

## Deprecation policy [#deprecation-policy]

Breaking changes ship only as a new dated version. A version stays supported for at least 6 months after its successor is released. Deprecated operations send `Deprecation` and `Sunset` response headers before they are removed.

These changes are not breaking and can ship without a new version:

* New endpoints
* New optional request parameters
* New response fields
* New enum values in responses
* New error codes

Clients should ignore response fields they do not know.

## Errors [#errors]

Application errors return JSON and are documented in the OpenAPI document as the `Error` schema:

```json
{
  "error": "insufficient_scope",
  "code": "INSUFFICIENT_SCOPE",
  "required": "write:projects",
  "hint": "Request a token/API key with scope `write:projects`."
}
```

Errors can carry extra fields such as `required` here.

| Field     | Type             | Meaning                                  |
| --------- | ---------------- | ---------------------------------------- |
| `error`   | string           | Human-readable message                   |
| `code`    | string           | Stable machine-readable code             |
| `hint`    | string, optional | What to do about it                      |
| `details` | array, optional  | Per-field problems for validation errors |

Branch on `code`, never on the message text. Legacy handlers and authentication-provider endpoints can use other response shapes, so check the HTTP status and the operation's documented payload too.

| Status | Meaning                       |
| ------ | ----------------------------- |
| 400    | Bad input                     |
| 401    | Missing or invalid credential |
| 402    | Usage limit exceeded          |
| 403    | Insufficient scope or role    |
| 404    | Not found                     |
| 409    | Conflict                      |
| 422    | Validation failed             |
| 429    | Rate limited                  |
| 500    | Internal error                |
| 502    | Upstream integration error    |
| 503    | Integration unavailable       |

## MCP for agents [#mcp-for-agents]

Agents can drive the platform over the Model Context Protocol instead of raw HTTP. The MCP server is at `https://app.rock8.cloud/mcp` and uses OAuth. See [MCP Integration](/docs/guides/mcp-integration).

## Related [#related]

* [API Keys](/docs/guides/api-keys) - create and scope a `vhk_...` key
* [MCP Integration](/docs/guides/mcp-integration) - connect an AI coding agent
* [Teams and Organizations](/docs/guides/teams-and-organizations) - roles and organization access