> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ankra.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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 → Add Token**.
3. 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.

### 2) Make your first request

**Bash (cURL)**

```bash theme={null}
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**

```python theme={null}
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**

```javascript theme={null}
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:

```http theme={null}
Authorization: Bearer <your-token>
```

* Tokens are created in the dashboard and may be scoped (if your organisation uses scoped tokens).
* Revoke tokens anytime from **Profile → API Tokens**.
* Prefer separate tokens for different use cases (e.g., CLI vs. CI/CD).

### 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).

**CLI example (authenticate once):**

```bash theme={null}
export ANKRA_API_TOKEN="<your-token>"
```

**GitHub Actions example:**

```yaml theme={null}
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.