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.
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
Data sources	Connect and manage cloud accounts	Data Sources API
Cost & recommendations	Query expenses and optimization findings	Cost & Recommendations API
Chargeback	Allocation rules and chargeback reports	Chargeback API
Modernization	Scans, findings, servers, waves, AI settings	Modernization API

​API Reference

​Base URL

​Conventions

​Authorization model

​Errors

​Endpoint groups

​Related pages