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

# API Reference

> How to authenticate and call the KOSTRA REST API: base URL, conventions, errors, and endpoint groups.

# API Reference

KOSTRA exposes a REST API so you can automate onboarding, pull cost data, drive chargeback, and integrate modernization into your own tooling. This reference covers the integrator-facing endpoints. The API is served from your KOSTRA host, whether you use the managed SaaS or a self-hosted deployment.

This reference is curated for the endpoints you are most likely to integrate against. KOSTRA also serves a machine-readable OpenAPI (Swagger) specification from your instance, which is the authoritative source for the full request and response schemas of every field.

## Base URL

All API calls target your KOSTRA instance. For a deployment served at `app.example.com`, the REST API base is:

```
https://app.example.com/restapi/v2
```

Authentication tokens are issued by a companion path on the same host:

```
https://app.example.com/auth/v2
```

Most resources are scoped to an organization, so paths commonly take the form:

```
/restapi/v2/organizations/{organization_id}/{resource}
```

## Conventions

* **Format.** Requests and responses use JSON. Send `Content-Type: application/json` on requests with a body.
* **Authentication.** Every call to the REST API carries an authentication token in the `x-optscale-token` header. See [Authentication](/api/authentication).
* **Identifiers.** Path parameters such as `{organization_id}`, `{cloud_account_id}`, and `{finding_id}` are string identifiers returned by the API.
* **Query parameters.** List and report endpoints accept filters and date ranges as query parameters; dates are typically Unix timestamps.
* **Versioning.** This reference documents the `v2` API.

## Authorization model

Access is governed by role-based permissions tied to your organization and its pool structure. A token represents a user, and each endpoint checks that the user's role permits the action. Read endpoints require visibility of the organization; write endpoints require the corresponding management permission. If a token lacks permission for a call, the API returns an authorization error rather than partial data.

## Errors

The API uses standard HTTP status codes:

| Status        | Meaning                                                  |
| ------------- | -------------------------------------------------------- |
| `200` / `201` | Success                                                  |
| `400`         | Invalid request — a parameter is missing or malformed    |
| `401`         | Missing or invalid authentication token                  |
| `403`         | Authenticated, but not permitted to perform the action   |
| `404`         | The requested resource does not exist                    |
| `424` / `5xx` | A dependency or the server failed to process the request |

Error responses include a machine-readable error code and a human-readable message so you can handle failures programmatically.

## Endpoint groups

| Group                  | Purpose                                      | Reference                                                   |
| ---------------------- | -------------------------------------------- | ----------------------------------------------------------- |
| Authentication         | Obtain and use a token                       | [Authentication](/api/authentication)                       |
| Data sources           | Connect and manage cloud accounts            | [Data Sources API](/api/data-sources)                       |
| Cost & recommendations | Query expenses and optimization findings     | [Cost & Recommendations API](/api/cost-and-recommendations) |
| Chargeback             | Allocation rules and chargeback reports      | [Chargeback API](/api/chargeback)                           |
| Modernization          | Scans, findings, servers, waves, AI settings | [Modernization API](/api/modernization)                     |

## Related pages

* [Authentication](/api/authentication)
* [Architecture Overview](/architecture)
* [Product Overview](/product-overview)