The REST API reference is generated automatically from the OpenAPI 3.0 specification of Deckhouse Code.
Operations are grouped by resource, one page per group. Each operation lists its parameters, request body, and responses; the schemas of the returned objects follow the operations.
Base URL
Operation paths in the reference start with /api/v4.
Send requests to the Deckhouse Code address followed by the operation path.
If the %s.example.com public domain template is used, the list of projects is available at https://code.example.com/api/v4/projects.
Authentication
A request is authenticated with a token passed in one of the following ways:
- the
Authorization: Bearer <TOKEN>header — for an access token or an OAuth 2.0 token; - the
PRIVATE-TOKEN: <TOKEN>header — for an access token; - the
private_token=<TOKEN>query parameter — for an access token.
Access tokens are personal, group, or project access tokens.
Example of a request with a personal access token:
curl --header "PRIVATE-TOKEN: <TOKEN>" "https://code.example.com/api/v4/projects"OAuth 2.0
An application registered in Deckhouse Code obtains an OAuth 2.0 token with the authorization code flow:
- the user is redirected to
https://code.example.com/oauth/authorize; - the application exchanges the authorization code for a token at
https://code.example.com/oauth/token; - the application refreshes the token at the same address,
https://code.example.com/oauth/token.
The scopes requested by the application limit what the token grants:
| Scope | Access |
|---|---|
api | Read and write access to the API, including all groups and projects, the container registry, the dependency proxy, and the package registry |
read_api | Read access to the API, including all groups and projects, the container registry, and the package registry |
read_user | Read access to the profile of the user through the /user endpoint (username, public email, and full name) and to the read-only endpoints under /users |
create_runner | Creating runners |
manage_runner | Managing runners |
k8s_proxy | Kubernetes API calls through the agent for Kubernetes |
self_rotate | Rotating the token by the token itself |
mcp | Read and write access to the Model Context Protocol (MCP) server for running tools |
mcp_orbit | Access to the Orbit Knowledge Graph MCP server for graph queries and schema retrieval |
Applications are managed with the Applications operations.
Pagination
Operations that return lists accept the page parameter (page number, 1 by default) and the per_page parameter (number of items on a page, 20 by default).
If an operation limits per_page, the limit is given in the parameter table of the operation.
Example of a request for the second page of 50 projects:
curl --header "PRIVATE-TOKEN: <TOKEN>" "https://code.example.com/api/v4/projects?page=2&per_page=50"Specification file
The OpenAPI specification file contains the same operations and schemas in JSON format. Use it to import the operations into an API client such as Postman or to generate a client library with OpenAPI Generator.