Introduction - Ankra Platform

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

Click your profile avatar (bottom‑left) in the Ankra dashboard.
Profile → API Tokens → Add Token.
Name the token, set permissions (if applicable), 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 and may be scoped (if your organisation uses scoped tokens).
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, you can always reach us through the community slack.

​Quickstart

​1) Generate an API token

​2) Make your first request

​Authentication

​Security best practices

​Errors

​Pagination & filtering

​Versioning

​Help & support

Quickstart

1) Generate an API token

2) Make your first request

Authentication

Security best practices

Errors

Pagination & filtering

Versioning

Help & support