Introduction

An authenticated GET request reaches the Akua API and branches into three response shapes: a single object, a paginated data list with next cursor, or an error with a code

The Akua API is a RESTful API that lets you manage workspaces, clusters, products, installations, and repositories programmatically. It powers the dashboard, Platform MCP, and Akua CLI preview, and you can use it to build custom integrations.

Base URL

All API requests are made to:

https://api.akua.dev/v1

An illustrative request:

curl https://api.akua.dev/v1/workspaces \
  -H "Authorization: Bearer $AKUA_API_TOKEN"

Workspace-scoped endpoints resolve the workspace from your credential. A workspace API token already belongs to a workspace, so you can omit any workspace header entirely. With a broad credential (dashboard session or multi-workspace token), select the workspace with the optional Akua-Context header:

curl https://api.akua.dev/v1/installs \
  -H "Authorization: Bearer $AKUA_API_TOKEN" \
  -H "Akua-Context: ws_xxx"

Authentication guide

Learn how to create tokens, scope requests, and use JWTs.

Conventions

The API uses snake_case for all field names. This keeps responses consistent regardless of the client language and matches the format you see in curl, logs, and debugging tools.

Response format

Single objects are returned directly (no wrapper):

{
  "id": "j572abc123def456",
  "name": "my-workspace",
  "created_at": 1734567890000
}

List responses return data with flat pagination fields:

{
  "data": [
    { "id": "j572abc123def456", "name": "my-workspace", "created_at": 1734567890000 }
  ],
  "has_more": true,
  "next_cursor": "opaque..."
}

Error responses use an error envelope:

{
  "error": {
    "code": "not_found",
    "message": "Install not found"
  }
}

Pagination

List endpoints support cursor-based pagination with two query parameters:

Parameter	Type	Default	Description
`limit`	integer	50	Items per page (1–100)
`cursor`	string	(none)	Value of `next_cursor` from a previous response

Error codes

HTTP status	Code	Description
400	`bad_request`	Malformed request
401	`unauthorized`	Missing or invalid token
403	`forbidden`	Not a member of the workspace
404	`not_found`	Resource does not exist
409	`conflict`	Resource already exists
422	`validation_error`	Request body failed validation
500	`internal_error`	Unexpected server error

Interactive reference

The API spec is also available as an interactive reference:

Scalar API reference

Interactive API explorer with request builder.

OpenAPI spec

Raw OpenAPI 3.1 specification (JSON).

Authentication

Create tokens and learn about supported auth methods.

OpenAPI specification

Download the spec and generate type-safe clients.

CLI preview

Track Akua CLI status and supported automation alternatives.

AI and agents

Connect AI tools to Akua docs and infrastructure.

Overview

Endpoints

Base URL

Authentication guide

Conventions

Response format

Error codes

Interactive reference

Scalar API reference

OpenAPI spec

Authentication

OpenAPI specification

CLI preview

AI and agents

​Base URL

Authentication guide

​Conventions

​Response format

​Pagination

​Error codes

​Interactive reference

Scalar API reference

OpenAPI spec

​Related topics

Authentication

OpenAPI specification

CLI preview

AI and agents

Base URL

Conventions

Response format

Pagination

Error codes

Interactive reference

Related topics