Rock8Cloud Docs

Base URL, authentication, versioning, deprecation policy and error format of the Rock8Cloud REST 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

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

Send a token on every request as a Bearer credential:

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

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

Pin the API version with a request header:

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.

Pin the header in scripts and agents. A new version can then never change behavior under a running integration.

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

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

{
  "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

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.

API Keys - create and scope a vhk_... key
MCP Integration - connect an AI coding agent
Teams and Organizations - roles and organization access

REST API