Skip to main content

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