> ## Documentation Index
> Fetch the complete documentation index at: https://docs.akua.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# 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 dashboard, Platform MCP, and [Akua CLI preview](/cli), 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:
```bash theme={null}
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:
```bash theme={null}
curl https://api.akua.dev/v1/installs \
-H "Authorization: Bearer $AKUA_API_TOKEN" \
-H "Akua-Context: ws_xxx"
```
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):
```json theme={null}
{
"id": "j572abc123def456",
"name": "my-workspace",
"created_at": 1734567890000
}
```
**List responses** return `data` with flat pagination fields:
```json theme={null}
{
"data": [
{ "id": "j572abc123def456", "name": "my-workspace", "created_at": 1734567890000 }
],
"has_more": true,
"next_cursor": "opaque..."
}
```
**Error responses** use an `error` envelope:
```json theme={null}
{
"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:
Interactive API explorer with request builder.
Raw OpenAPI 3.1 specification (JSON).
## Related topics
Create tokens and learn about supported auth methods.
Download the spec and generate type-safe clients.
Track Akua CLI status and supported automation alternatives.
Connect AI tools to Akua docs and infrastructure.