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

# Modernization API

> Trigger scans, read findings and servers, plan waves, and configure AI narration via the KOSTRA REST API.

# Modernization API

The modernization endpoints let you drive the workload modernization engine programmatically — trigger scans, read the evidence-backed findings, plan migration waves, and configure AI narration. All calls require the `x-optscale-token` header (see [Authentication](/api/authentication)) and are scoped to an organization.

## Scans

### List scans

```
GET /restapi/v2/organizations/{organization_id}/modernization/scans
```

Returns the modernization scans for the organization and their status.

### Trigger a scan

```
POST /restapi/v2/organizations/{organization_id}/modernization/scans
```

Starts a scan for a supported account. A scan discovers what runs inside the account's virtual machines, analyzes it, and — if AI narration is enabled — narrates the findings. Triggering a scan requires the appropriate management permission.

### Get a scan

```
GET /restapi/v2/organizations/{organization_id}/modernization/scans/{scan_id}
```

Returns a single scan's status and result summary.

## Findings

### List findings

```
GET /restapi/v2/organizations/{organization_id}/modernization/findings
```

Returns findings, filterable by query parameters such as `cloud_account_id`, `pattern`, `effort`, `risk`, and `scan_id`, with `limit` and `offset` for pagination. By default, findings reflect the latest completed scan per account.

### Get a finding

```
GET /restapi/v2/organizations/{organization_id}/modernization/findings/{finding_id}
```

Returns one finding, including its 6 R's options, recommended strategy, and the evidence behind it. Pass `?priority=` (cost, performance, security, or resilience) to retrieve the options ranked for that priority.

### Select a strategy

```
PATCH /restapi/v2/organizations/{organization_id}/modernization/findings/{finding_id}
Content-Type: application/json

{ "selected_strategy": "replatform" }
```

Commits your chosen strategy for the finding. The selection drives the savings rollups, so summaries reflect your actual plan. The value must be one of the finding's viable options.

### Generate Terraform for a finding

```
GET /restapi/v2/organizations/{organization_id}/modernization/findings/{finding_id}/terraform
```

Returns starter Terraform for the finding's target architecture — a scaffold with TODOs to complete in your own IaC process.

## Servers and summary

```
GET /restapi/v2/organizations/{organization_id}/modernization/servers
GET /restapi/v2/organizations/{organization_id}/modernization/servers/{resource_id}/workloads
GET /restapi/v2/organizations/{organization_id}/modernization/summary
GET /restapi/v2/organizations/{organization_id}/modernization/quadrant
```

The `servers` endpoints return the Server → Workload hierarchy with rollups; `summary` returns the KPI figures and scan status; `quadrant` returns the effort-versus-impact data used to prioritize.

## Migration waves

```
GET  /restapi/v2/organizations/{organization_id}/modernization/waves
POST /restapi/v2/organizations/{organization_id}/modernization/waves
GET  /restapi/v2/organizations/{organization_id}/modernization/waves/{wave_id}
```

Create and read migration waves, then assign servers to a wave to sequence the program. The wave view rolls up the workloads and expected saving per phase.

## AI narration settings

```
GET   /restapi/v2/organizations/{organization_id}/modernization/llm_settings
PATCH /restapi/v2/organizations/{organization_id}/modernization/llm_settings
POST  /restapi/v2/organizations/{organization_id}/modernization/llm_settings/test
```

Read and update the AI narration configuration — provider, model, and API key — and test the connection before enabling it. The API key is write-only and stored encrypted; it is never returned. AI narration only explains the deterministic findings and never alters the engine's numbers.

## Related pages

* [Chargeback API](/api/chargeback)
* [Run a Workload Modernization Scan](/guides/run-a-modernization-scan)
* [Configure the Modernization AI](/guides/configure-modernization-ai)