Impact reports
Use the Impact reports API to see what would change if a version of an ontology replaced the live version. A report compares a draft or published version with the live version and marks each change SAFE, ATTENTION, or BREAKING. Every request needs an Authorization: Bearer <token> header and READ permission on the ontology. For background, see Versions and drafts.
A new report starts as PENDING. A background task fills it in and sets it to READY, or to FAILED with a _failureReason. When you request a promotion, the service requests a report for you.
This section contains the following API calls:
Request an impact report
Requests a report that compares a version with the live version. Name the version by number or by version ID. If you send both, they must name the same version.
If a PENDING or READY report for the same pair of versions already exists, the call returns it with 200 instead of creating a new one. A report on a draft is reused only while the draft is unchanged. A report on a published or promoted version is reused only if it was created after the version was published. A FAILED report is never reused, so to retry, request again.
Endpoints
POST /aosvc/api/v1/ontologies/{ontologyId}/impact-analysis-reports
Parameters
Path
| Parameter | Type | Description | Required |
|---|---|---|---|
ontologyId | String | The ontology ID. | Required |
Query
| Parameter | Type | Description | Required |
|---|---|---|---|
nsfilter | String | The namespace the ontology belongs to. | Required |
Body
| Parameter | Type | Description | Required |
|---|---|---|---|
_versionFrom | Integer | The number of the version to compare. Required unless you send _versionFromId. | Optional |
_versionFromId | String | The ID of the version to compare, in the form <ontologyId>:v<number>. Required unless you send _versionFrom. | Optional |
Example:
{
"_versionFrom": 3
}
Response
{
"_id": "7e2b4f19-6c8a-4d05-9e31-2a8f6c1d9b47",
"_ontologyId": "d4721098-9c7f-4e7d-84f4-84bea8f21ca2",
"_name": "Ontology Impact Analysis Report — v3 to live v2",
"_status": "PENDING",
"_versionFrom": 3,
"_versionFromId": "d4721098-9c7f-4e7d-84f4-84bea8f21ca2:v3",
"_versionTo": 2,
"_versionToId": "d4721098-9c7f-4e7d-84f4-84bea8f21ca2:v2",
"_createdAt": "2026-09-22T14:00:00Z",
"_createdBy": "b0a30681-e719-486c-8f03-56091e590940",
"_updatedAt": "2026-09-22T14:00:00Z",
"_updatedBy": "b0a30681-e719-486c-8f03-56091e590940"
}
| Field | Description |
|---|---|
_status | PENDING, READY, or FAILED. |
_versionFrom, _versionFromId | The version being compared. |
_versionTo, _versionToId | The version that was live when you requested the report. |
_report | The report content. Present only when the report is READY, and only from Get an impact report. |
_failureReason | Why the report failed. Present only when the report is FAILED. |
Codes
| Code | Description |
|---|---|
200 | Success. An existing report is returned. |
201 | Created. A new PENDING report is returned. |
400 | Bad Request. No version is named, _versionFrom is below 1, the two fields name different versions, the version is the live one or is still being copied, or nothing is live. |
403 | Forbidden |
404 | Not Found. The ontology or version is unknown, or the version ID belongs to another ontology. |
503 | Service Unavailable. The report couldn't be queued and is saved as FAILED. Request again. |
List impact reports
Lists the ontology's reports, newest first. The entries don't include _report.
Endpoints
GET /aosvc/api/v1/ontologies/{ontologyId}/impact-analysis-reports
Parameters
Path
| Parameter | Type | Description | Required |
|---|---|---|---|
ontologyId | String | The ontology ID. | Required |
Query
| Parameter | Type | Description | Required |
|---|---|---|---|
nsfilter | String | The namespace the ontology belongs to. | Required |
query | Object | A JSON filter on report fields, raw or URL-encoded. Name fields as the API returns them, including fields inside the report such as _report._verdict._breaking. Use a bare value for equality, or the operators $eq, $ne, $gt, $gte, $lt, $lte, $in, and $nin. _createdAt and _updatedAt take ISO 8601 timestamps. Other operators return 400. | Optional |
_offset | Integer | The position to start listing from. Default is 0. | Optional |
_pageSize | Integer | The number of reports per page. Default and maximum is 50. | Optional |
Example request:
GET /aosvc/api/v1/ontologies/d4721098-9c7f-4e7d-84f4-84bea8f21ca2/impact-analysis-reports?nsfilter=myapp_Xw6AQru7&query={"_report._verdict._breaking":{"$gt":0}}
Response
_pageSize in the response is the number of reports on this page.
{
"_list": [
{
"_id": "7e2b4f19-6c8a-4d05-9e31-2a8f6c1d9b47",
"_ontologyId": "d4721098-9c7f-4e7d-84f4-84bea8f21ca2",
"_name": "Ontology Impact Analysis Report — v3 to live v2",
"_status": "READY",
"_versionFrom": 3,
"_versionFromId": "d4721098-9c7f-4e7d-84f4-84bea8f21ca2:v3",
"_versionTo": 2,
"_versionToId": "d4721098-9c7f-4e7d-84f4-84bea8f21ca2:v2",
"_createdAt": "2026-09-22T14:00:00Z",
"_createdBy": "b0a30681-e719-486c-8f03-56091e590940",
"_updatedAt": "2026-09-22T14:04:00Z",
"_updatedBy": "b0a30681-e719-486c-8f03-56091e590940"
}
],
"_offset": 0,
"_pageSize": 1,
"_total": 1,
"_hasMore": false
}
Codes
| Code | Description |
|---|---|
200 | Success |
400 | Bad Request. The filter isn't valid. |
403 | Forbidden |
404 | Not Found |
Get an impact report
Returns one report. Poll it until _status is READY, when _report is present. In every change entry, _before is the live version and _after is the version being compared.
_report has three parts:
_verdicthas the totals._needAttentionis_breakingplus_attention._diffhas one array of changes for each kind of schema:_classes,_relationships,_rules,_checks,_collectionMappings,_propertyMappings, and_aiTools._stateMachineChangeshas one array for each part of a state machine:_stateMachines,_states,_events,_transitions,_transitionEvents,_transitionActions, and_actions.
A part with no changes is left out. Each change entry can have these fields:
| Field | Description |
|---|---|
_defId | The ID of the changed item. It's the same in every version. |
_name | The item's name. |
_op | added, removed, or changed. |
_severity | SAFE, ATTENTION, or BREAKING. |
_cosmetic | true when the change can't affect data, for example a new description. |
_before, _after | For a changed item, only the fields that changed. For a removed item, _before is the live item. |
_affectedRecords, _affectedLinks | The number of stored records and links the change affects. A missing count means the count is unknown, not zero. |
_affectedGrants | Permission grants whose meaning changes. |
_referencedBy | What in the compared version still refers to a removed or renamed item. |
_conflictsWith | Another item with the same English name. The service refuses duplicate class names, so you don't normally see this field. |
Endpoints
GET /aosvc/api/v1/ontologies/{ontologyId}/impact-analysis-reports/{reportId}
Parameters
Path
| Parameter | Type | Description | Required |
|---|---|---|---|
ontologyId | String | The ontology ID. | Required |
reportId | String | The report ID. | Required |
Query
| Parameter | Type | Description | Required |
|---|---|---|---|
nsfilter | String | The namespace the ontology belongs to. | Required |
Response
{
"_id": "7e2b4f19-6c8a-4d05-9e31-2a8f6c1d9b47",
"_ontologyId": "d4721098-9c7f-4e7d-84f4-84bea8f21ca2",
"_name": "Ontology Impact Analysis Report — v3 to live v2",
"_status": "READY",
"_versionFrom": 3,
"_versionFromId": "d4721098-9c7f-4e7d-84f4-84bea8f21ca2:v3",
"_versionTo": 2,
"_versionToId": "d4721098-9c7f-4e7d-84f4-84bea8f21ca2:v2",
"_report": {
"_verdict": {
"_totalChanges": 14,
"_needAttention": 10,
"_breaking": 6,
"_attention": 4,
"_safe": 4,
"_affectedRecords": 4508
},
"_diff": {
"_classes": [
{
"_defId": "a1c93f02-4b7d-4a11-9e6a-0c2f1d5b8a90",
"_name": "Pump",
"_op": "removed",
"_severity": "BREAKING",
"_affectedRecords": 312,
"_affectedLinks": 58,
"_before": { "_name": { "en": "Pump" } },
"_after": null
}
]
},
"_stateMachineChanges": {
"_states": [
{
"_defId": "43cdc4fc-be08-4a6e-a9b6-8aecd056f4d5",
"_name": "under-repair",
"_op": "removed",
"_severity": "BREAKING",
"_affectedRecords": 2,
"_before": { "_name": "under-repair", "_value": "under-repair" },
"_after": null
}
]
}
},
"_createdAt": "2026-09-22T14:00:00Z",
"_createdBy": "b0a30681-e719-486c-8f03-56091e590940",
"_updatedAt": "2026-09-22T14:04:00Z",
"_updatedBy": "b0a30681-e719-486c-8f03-56091e590940"
}
Codes
| Code | Description |
|---|---|
200 | Success |
403 | Forbidden |
404 | Not Found. The report is unknown or belongs to another ontology. |