Introduction

Programmatic access to Akua resources for automation, CLI tools, and integrations

The Akua API is a RESTful API that lets you manage workspaces, clusters, products, installations, and repositories programmatically. It powers the Akua CLI and can be used 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, authenticate with the CLI, 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).

Related topics

Authentication

Create tokens and learn about supported auth methods.

OpenAPI specification

Download the spec and generate type-safe clients.

CLI

Install the Akua CLI for terminal-based workflows.

AI and agents

Connect AI tools to Akua docs and infrastructure.