About the Akasha API
How the Akasha REST API is structured — the response envelope, project scoping, asynchronous operations, and your first request.
Everything you can do in the Akasha console — instances, images, networks, storage, managed Kubernetes — is available over a REST API. The console is built entirely on this API, so any action you can perform in the UI can also be automated with plain HTTP.
Base URL
All endpoints live under /1.0 on your Akasha endpoint:
https://<your-akasha-endpoint>/1.0/...
The endpoint address is specific to your deployment — it is typically the same host that serves the console. Ask your administrator if you are unsure.
Your first request
Every request must carry an OIDC access token in the Authorization header (see Authenticate). This example lists the instances in a project:
curl -s \
-H "Authorization: Bearer $ACCESS_TOKEN" \
"https://<your-akasha-endpoint>/1.0/instances?project=dev-team"
{
"type": "sync",
"status": "Success",
"status_code": 200,
"metadata": [
"/1.0/instances/web-01",
"/1.0/instances/web-02"
]
}
Response envelope
Every JSON response uses the same envelope:
| Field | Meaning |
|---|---|
type | sync for a completed request, error for a failure, async when the request started a background operation |
status | Human-readable status text |
status_code | Numeric status code |
metadata | The payload — a resource, a list, an operation, or error details |
Errors from platform endpoints (authentication and project-access checks, managed Kubernetes, billing, identity) carry the message in metadata.error, and some include a stable metadata.error_code you can match on programmatically. Errors from infrastructure endpoints (instances, images, networks, storage) instead carry the message in a top-level error field with a numeric top-level error_code — check both shapes when handling errors:
{
"type": "error",
"status": "Forbidden",
"status_code": 403,
"metadata": {
"error": "no access to project \"finance\"",
"error_code": "project_access_denied"
}
}
Project scoping
Resources belong to projects. Pass ?project=<name> on requests to select the project you are working in. Requests that name a project you do not have access to fail with 403 and error_code: project_access_denied.
Asynchronous operations
Long-running actions do not block. Infrastructure actions (for example starting an instance) return an operation you can poll under /1.0/operations. Managed Kubernetes tasks — cluster creation and deletion, add-on installs — return an operation_id tracked under /1.0/k8s/operations. See the endpoint overview for details.
WebSockets
Interactive features — the instance terminal and console, and the cluster web terminal — upgrade the connection to a WebSocket. These connections authenticate differently from regular HTTP requests: the token is passed through the WebSocket sub-protocol, or the connection uses a one-time operation secret, instead of the Authorization header. The console handles this automatically; it only matters if you build your own client.