Introduction

Automate cluster operations, integrate with CI/CD, and build on the Ankra platform via REST.

Automate cluster operations, integrate with your CI/CD, and build on top of the Ankra platform.

The Ankra REST API lets you programmatically manage Ankra resources - such as clusters and add-ons - run operations, and retrieve statuses from your own tools, scripts, and pipelines.

---

Quickstart

1) Generate an API token

1. Click your profile avatar (bottom-left) in the Ankra dashboard.
2. Profile → API Tokens → Create.
3. Name the token (choose MCP access only if an MCP client will use it) and copy it somewhere safe.

You won’t be able to view the token again after closing the dialog.

That is a personal token: it acts as you, and it stops working if you leave the organisation. For anything that runs without a person behind it - CI/CD, Terraform, an agent - create a service token instead. It is owned by the organisation, carries a role you pick rather than all of your authority, and survives offboarding.

2) Make your first request

Bash (cURL)

export ANKRA_API_TOKEN="<your-token>"

curl -sS \
  -H "Authorization: Bearer $ANKRA_API_TOKEN" \
  -H "Accept: application/json" \
  https://platform.ankra.app/api/v1/clusters

Python

import requests

headers = {"Authorization": "Bearer <your-token>"}
resp = requests.get("https://platform.ankra.app/api/v1/clusters", headers=headers)
resp.raise_for_status()
print(resp.json())

Node.js

const res = await fetch("https://platform.ankra.app/api/v1/clusters", {
  headers: { Authorization: "Bearer <your-token>" }
});
if (!res.ok) throw new Error(await res.text());
console.log(await res.json());

---

Authentication

Use an API token in the Authorization header:

Authorization: Bearer <your-token>

• Tokens are created in the dashboard or with ankra tokens create. A token acts with its owner’s role (a service token with the role it was given); scopes only add MCP server access.
• Revoke a personal token anytime from Profile → API Tokens, and a service token from Organisation → Service tokens.
• Prefer separate tokens for different use cases (e.g., CLI vs. CI/CD).
• A service token is pinned to its organisation: the X-Ankra-Organisation-Id override that ankra --org uses is refused for it.

Security best practices

• Treat tokens like passwords - never commit them to source control.
• Grant only the minimum required permissions.
• Rotate/revoke tokens regularly and immediately if you suspect compromise.
• Store tokens as secrets in your CI/CD system (e.g., GitHub Actions, GitLab CI, Jenkins).
• Use a service token for automation, so the credential is not tied to one person’s membership and can be reviewed and revoked by any administrator.

CLI example (authenticate once):

export ANKRA_API_TOKEN="<your-token>"

GitHub Actions example:

env:
  ANKRA_API_TOKEN: ${{ secrets.ANKRA_API_TOKEN }}

---

Errors

The API uses standard HTTP status codes. Error responses include a machine-readable body to help diagnose issues.

Code	Meaning
200	Success
400	Bad request / validation
401	Missing or invalid token
403	Insufficient permissions
404	Resource not found
429	Too many requests (rate limit)
5xx	Server errors

---

Pagination & filtering

Endpoints that return collections may support pagination and filters. Refer to the endpoint’s page for available query parameters and response shapes.

---

Versioning

This reference covers the v1 API (/api/v1). Breaking changes are introduced only in new major versions; minor, non-breaking updates may be added to v1.

---

Help & support

• Check the endpoint pages for required parameters and examples.
• Review token permissions if you receive 401/403 errors.
• If you’re stuck, contact support.