Use the Ontologies API to create and manage the application ontology for a namespace, read the base platform ontology, control the edit lock, and move an ontology through its versions. Each namespace has at most one application ontology. The nsfilter query parameter selects the namespace, and every request needs an Authorization: Bearer <token> header. For background, see Ontologies.
Ontology schema, that is, classes, relationships, rules, constraints, and mappings, belongs to one version of the ontology:
- Reads use the live version by default. To read another version, send its number in the
X-Ontology-Draft header. Until you promote a first version, nothing is live and reads return empty results.
- Schema writes must name a draft in the
X-Ontology-Draft header. A write without the header, or one that names a published or promoted version, returns 409.
- A header that names a version the ontology doesn't have returns
404. A header that isn't a positive whole number returns 400.
- A version moves from
DRAFT to PUBLISHED when you publish it, and to PROMOTED, which makes it live, when you confirm a promotion request.
For more information, see Versions and drafts.
Successful reads of an ontology return an ETag header with the ontology's _revision. To make a schema write fail if someone else changed the ontology first, send that value in an If-Match header. A stale value returns 412. To get _name and _description in a particular language, send an Accept-Language header.
This section contains the following API calls:
List ontologies
Returns the base platform ontology first, then the namespace's application ontology if it exists and you have READ permission on it. If you lack permission, the application ontology is left out of the list.
Endpoints
GET /aosvc/api/v1/ontologies
Parameters
Query
| Parameter | Type | Description | Required |
|---|
nsfilter | String | The namespace whose application ontology to list. | Required |
Response
[
{
"_id": "_base",
"_namespaces": null,
"_name": "Digital Twin Base Ontology",
"_description": "Core platform entity definitions",
"_baseVersion": "1.0.0",
"_editLockTimeoutSeconds": 0,
"_version": 0,
"_revision": 0,
"_createdAt": null,
"_updatedAt": null,
"_createdBy": null,
"_updatedBy": null
},
{
"_id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"_namespaces": ["myapp_Xw6AQru7"],
"_name": "Facilities Ontology",
"_description": "Equipment and spaces",
"_baseVersion": "1.0.0",
"_editLockTimeoutSeconds": -1,
"_version": 1,
"_revision": 12,
"_createdAt": "2026-09-01T09:00:00Z",
"_updatedAt": "2026-09-15T14:22:00Z",
"_createdBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc",
"_updatedBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc"
}
]
| Field | Description |
|---|
_id | The ontology ID, or _base for the base ontology. |
_namespaces | The namespaces the ontology belongs to. null for the base ontology. |
_name, _description | The name and description in the language your Accept-Language header selects. |
_baseVersion | The base ontology version the ontology builds on. |
_editLockTimeoutSeconds | The edit lock lease in seconds. -1 means the ontology doesn't use the edit lock. |
_revision | Increases with every schema change and every promotion. Matches the ETag header. |
Codes
| Code | Description |
|---|
200 | Success |
400 | Bad Request |
401 | Unauthorized |
Create an ontology
Creates the application ontology for the namespace. Requires CREATE permission on aosvc:ontology:*. You get all permissions on the new ontology.
The new ontology starts with version 1 as a draft and no live version. Version 1 already contains the platform-managed lifecycle classes State, Event, Action, and StateTransition.
Endpoints
POST /aosvc/api/v1/ontologies
Parameters
Query
| Parameter | Type | Description | Required |
|---|
nsfilter | String | The namespace to create the ontology in. A namespace can have only one ontology. | Required |
Body
| Parameter | Type | Description | Required |
|---|
_name | String or Object | A name, or a map of language codes to names such as {"en": "Pumps", "de": "Pumpen"}. Each value can't be blank and has a maximum of 255 characters. You can't use Digital Twin Base Ontology. | Required |
_description | String or Object | A description, or a map of language codes to descriptions. Maximum 10000 characters for each language. To leave it empty, send "", not {}. | Optional |
_baseVersion | String | A base ontology version from List base ontology versions. Default is the latest version. | Optional |
_editLockTimeoutSeconds | Integer | To protect the ontology with the edit lock, enter the lease in seconds, between 60 and 86400 by default. Default is -1, which turns the edit lock off. | Optional |
Example:
{
"_name": "Facilities Ontology",
"_description": "Equipment and spaces"
}
Response
{
"_id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"_namespaces": ["myapp_Xw6AQru7"],
"_name": "Facilities Ontology",
"_description": "Equipment and spaces",
"_baseVersion": "1.0.0",
"_editLockTimeoutSeconds": -1,
"_version": 1,
"_revision": 1,
"_createdAt": "2026-09-01T09:00:00Z",
"_updatedAt": "2026-09-01T09:00:00Z",
"_createdBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc",
"_updatedBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc"
}
Codes
| Code | Description |
|---|
201 | Created |
400 | Bad Request. A field value is invalid, or the base version is unknown. |
403 | Forbidden |
409 | Conflict. The namespace already has an ontology, or the name is reserved. |
502 | Bad Gateway. The ontology couldn't be set up and was removed again. |
Get an ontology
Requires READ permission on the ontology.
Endpoints
GET /aosvc/api/v1/ontologies/{ontologyId}
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 |
Response
{
"_id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"_namespaces": ["myapp_Xw6AQru7"],
"_name": "Facilities Ontology",
"_description": "Equipment and spaces",
"_baseVersion": "1.0.0",
"_editLockTimeoutSeconds": -1,
"_version": 1,
"_revision": 12,
"_createdAt": "2026-09-01T09:00:00Z",
"_updatedAt": "2026-09-15T14:22:00Z",
"_createdBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc",
"_updatedBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc"
}
Codes
| Code | Description |
|---|
200 | Success |
304 | Not Modified. Your If-None-Match header matches the current revision. |
403 | Forbidden |
404 | Not Found |
Update an ontology
Updates the ontology's name, description, or edit lock setting. Omitted fields keep their values. Requires EDIT permission on the ontology and, if the ontology uses the edit lock, the lock. You don't need the X-Ontology-Draft header.
Endpoints
PUT /aosvc/api/v1/ontologies/{ontologyId}
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 |
|---|
_name | String or Object | A name, or a map of language codes to names. A map replaces all stored languages, so include every language you want to keep. Same limits as on create. | Optional |
_description | String or Object | A description, or a map of language codes to descriptions. A map replaces all stored languages. | Optional |
_editLockTimeoutSeconds | Integer | The edit lock lease in seconds, between 60 and 86400 by default. -1 turns the edit lock off and releases any held lock. | Optional |
Example:
{
"_name": { "en": "Facilities Ontology", "de": "Gebäudeontologie" },
"_editLockTimeoutSeconds": 1800
}
Response
{
"_id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"_namespaces": ["myapp_Xw6AQru7"],
"_name": "Facilities Ontology",
"_description": "Equipment and spaces",
"_baseVersion": "1.0.0",
"_editLockTimeoutSeconds": 1800,
"_version": 1,
"_revision": 13,
"_createdAt": "2026-09-01T09:00:00Z",
"_updatedAt": "2026-09-16T08:10:00Z",
"_createdBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc",
"_updatedBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc"
}
Codes
| Code | Description |
|---|
200 | Success |
400 | Bad Request |
403 | Forbidden |
404 | Not Found |
409 | Conflict. Someone else holds the edit lock, or the name is reserved. |
412 | Precondition Failed. The If-Match revision is stale. |
423 | Locked. The ontology uses the edit lock and nobody holds it. |
Delete an ontology
Deletes the ontology with all its versions, schema, promotion requests, and impact reports. Requires DELETE permission on the ontology and, if the ontology uses the edit lock, the lock. Item Service collections and their data are not deleted. To delete only one draft, see Discard a draft.
Endpoints
DELETE /aosvc/api/v1/ontologies/{ontologyId}
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 |
Response
None.
Codes
| Code | Description |
|---|
204 | No Content |
403 | Forbidden |
404 | Not Found |
409 | Conflict. Someone else holds the edit lock. |
423 | Locked. The ontology uses the edit lock and nobody holds it. |
Validate data against an ontology
Checks the instances you send against the ontology's constraints combined with the base ontology's constraints. Stored individuals aren't checked. Requires READ permission on the ontology. The call validates the live version, or the version you name in X-Ontology-Draft. If the version you name doesn't exist, the call returns 404.
Data that doesn't conform still returns 200. Check the _conforms field.
Endpoints
POST /aosvc/api/v1/ontologies/{ontologyId}/validation
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 |
|---|
dataJson | String | The array of instances to validate, encoded as a JSON string. This field has no _ prefix. | Required |
Example:
{
"dataJson": "[{\"type\":\"Pump\",\"entityId\":\"pump-001\",\"entityName\":\"Chiller Pump\"}]"
}
Response
{
"_conforms": false,
"_violations": [
{
"_focusNode": "Pump",
"_resultPath": "entityName",
"_message": "minCount violation: expected at least 1 value(s) for 'entityName' but found 0",
"_severity": "Violation"
}
]
}
Codes
| Code | Description |
|---|
200 | Success |
400 | Bad Request |
403 | Forbidden |
404 | Not Found. The ontology, or the version you name in X-Ontology-Draft, doesn't exist. |
List collection mappings
Lists every class-to-collection mapping in the live version, or in the version you name in X-Ontology-Draft. Mappings of the platform-managed lifecycle classes aren't listed. Requires READ permission on the ontology.
A mapping made by collection name has a null _collectionId until you promote its version. Promotion creates the collection and sets _collectionId to the collection's _userItemId.
Endpoints
GET /aosvc/api/v1/ontologies/{ontologyId}/mappings
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 |
| Parameter | Type | Description | Required |
|---|
X-Ontology-Draft | Integer | The version number to read. Default is the live version. | Optional |
Response
[
{
"_id": "6b1f0c2e-3d4a-4b5c-9d8e-7f6a5b4c3d2e",
"_classId": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f",
"_collectionId": "5cf129f3213fc97f7dbf24fb",
"_collectionName": "Pumps",
"_userType": "Pump",
"_createdAt": "2026-10-01T10:20:00Z",
"_updatedAt": "2026-10-01T10:20:00Z",
"_createdBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc",
"_updatedBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc"
}
]
Codes
| Code | Description |
|---|
200 | Success |
403 | Forbidden |
404 | Not Found |
Get the base ontology
Returns the three documents of the latest base platform ontology: its classes and properties, its rules, and its constraints. Any authenticated caller can read the base ontology.
Endpoints
GET /aosvc/api/v1/ontologies/base
Parameters
Query
| Parameter | Type | Description | Required |
|---|
nsfilter | String | Your namespace. | Required |
Response
{
"_ontology": {
"classes": {
"Entity": {
"id": "d3a3f38d-5371-3600-9bec-e49697d8bf39",
"label": "Entity",
"comment": "Base class for all digital twin entities."
}
},
"properties": {}
},
"_rules": [
{
"type": "relationship_rule",
"property": "fromState",
"fromClass": "StateTransition",
"toClass": "State",
"required": true
}
],
"_constraints": {
"Entity": {
"targetClass": "Entity",
"properties": [
{ "path": "entityId", "minCount": 1, "maxCount": 1, "datatype": "string" }
]
}
}
}
The example is shortened. Each document is returned in full.
Codes
| Code | Description |
|---|
200 | Success |
401 | Unauthorized |
List base ontology versions
Lists the available base ontology versions, newest first.
Endpoints
GET /aosvc/api/v1/ontologies/base/versions
Parameters
Query
| Parameter | Type | Description | Required |
|---|
nsfilter | String | Your namespace. | Required |
Response
[
{ "_version": "1.0.0", "_latest": true }
]
Codes
| Code | Description |
|---|
200 | Success |
401 | Unauthorized |
List base ontology classes
Lists the core classes of the base ontology. Your application classes extend these classes. To get the full schema of a base class, see Get the effective schema of a class.
Endpoints
GET /aosvc/api/v1/ontologies/base/classes
Parameters
Query
| Parameter | Type | Description | Required |
|---|
nsfilter | String | Your namespace. | Required |
Response
[
{
"_id": "d3a3f38d-5371-3600-9bec-e49697d8bf39",
"_name": "Entity",
"_description": "Base class for all digital twin entities.",
"_parentClass": null,
"_extendable": true
}
]
| Field | Description |
|---|
_id | The class ID. It's the same in every environment. |
_parentClass | Always null. Base classes have no parent. |
_extendable | false for the lifecycle classes State, StateTransition, Event, and Action, which you can't extend. |
Codes
| Code | Description |
|---|
200 | Success |
401 | Unauthorized |
Validate data against the base ontology
Checks the instances you send against the latest base ontology constraints only. The request and response are the same as for Validate data against an ontology.
Endpoints
POST /aosvc/api/v1/ontologies/base/validation
Parameters
Query
| Parameter | Type | Description | Required |
|---|
nsfilter | String | Your namespace. | Required |
Body
| Parameter | Type | Description | Required |
|---|
dataJson | String | The array of instances to validate, encoded as a JSON string. | Required |
Example:
{
"dataJson": "[{\"type\":\"Entity\",\"entityId\":\"e-001\",\"entityName\":\"Boiler\"}]"
}
Response
{
"_conforms": true,
"_violations": []
}
Codes
| Code | Description |
|---|
200 | Success |
400 | Bad Request |
Get the edit lock
Returns who holds the ontology's edit lock and until when. Requires READ permission on the ontology.
The edit lock is off unless the ontology's _editLockTimeoutSeconds is set. When it's on, you must hold the lock to change the ontology, its classes, relationships, rules, constraints, actions, or state machines. Writing individuals and other data never needs the lock. The lease runs from your last activity, and your schema writes extend it.
Endpoints
GET /aosvc/api/v1/ontologies/{ontologyId}/lock
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 |
Response
{
"_ontologyId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"_locked": true,
"_holder": "c9daff7e-b55b-41ec-aa46-d0150f3199dc",
"_holderName": "Jane Smith",
"_acquiredAt": "2026-10-01T09:00:00Z",
"_lastActivityAt": "2026-10-01T09:12:00Z",
"_expiresAt": "2026-10-01T09:42:00Z",
"_heldByMe": true,
"_lastWriteBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc",
"_changedByAnother": false,
"_lockingEnabled": true,
"_leaseSeconds": 1800
}
| Field | Description |
|---|
_lockingEnabled | Whether the ontology uses the edit lock. If false, the response contains only _ontologyId, _lockingEnabled, _locked, and _leaseSeconds (-1). |
_locked | Whether someone holds the lock. |
_holder, _holderName | The ID and display name of the lock holder. |
_heldByMe | Whether you hold the lock. |
_lastWriteBy, _changedByAnother | Who made the last schema change, and whether it was someone other than you. |
_leaseSeconds | The lease length in seconds. |
Codes
| Code | Description |
|---|
200 | Success |
403 | Forbidden |
404 | Not Found |
Acquire the edit lock
Takes the edit lock. If you already hold it, the call extends the lease. Requires EDIT permission on the ontology. There's no queue: if someone else holds the lock, the call fails.
Endpoints
POST /aosvc/api/v1/ontologies/{ontologyId}/lock
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 |
Response
The response has the same fields as Get the edit lock.
{
"_ontologyId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"_locked": true,
"_holder": "c9daff7e-b55b-41ec-aa46-d0150f3199dc",
"_holderName": "Jane Smith",
"_acquiredAt": "2026-10-01T09:00:00Z",
"_lastActivityAt": "2026-10-01T09:00:00Z",
"_expiresAt": "2026-10-01T09:30:00Z",
"_heldByMe": true,
"_lastWriteBy": null,
"_changedByAnother": false,
"_lockingEnabled": true,
"_leaseSeconds": 1800
}
Codes
| Code | Description |
|---|
200 | Success |
403 | Forbidden |
404 | Not Found |
409 | Conflict. Someone else holds the lock. |
Release the edit lock
Releases the edit lock if you hold it. Releasing a lock you don't hold isn't an error. To break another user's lock, set force to true.
Endpoints
DELETE /aosvc/api/v1/ontologies/{ontologyId}/lock
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 |
force | Boolean | Set to true to release the lock whoever holds it. Requires SHARE permission on the ontology. Without it, the call requires EDIT permission. Default is false. | Optional |
Response
{
"_ontologyId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"_locked": false,
"_lastWriteBy": null,
"_changedByAnother": false
}
Codes
| Code | Description |
|---|
200 | Success |
403 | Forbidden |
404 | Not Found |
Extend the edit lock
Extends the lease of a lock you hold without making a change. Use it to keep the lock through a long session with no saves. Requires EDIT permission on the ontology.
Endpoints
POST /aosvc/api/v1/ontologies/{ontologyId}/lock/heartbeat
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 |
Response
The response is the same as for Acquire the edit lock.
{
"_ontologyId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"_locked": true,
"_holder": "c9daff7e-b55b-41ec-aa46-d0150f3199dc",
"_holderName": "Jane Smith",
"_acquiredAt": "2026-10-01T09:00:00Z",
"_lastActivityAt": "2026-10-01T09:25:00Z",
"_expiresAt": "2026-10-01T09:55:00Z",
"_heldByMe": true,
"_lastWriteBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc",
"_changedByAnother": false,
"_lockingEnabled": true,
"_leaseSeconds": 1800
}
Codes
| Code | Description |
|---|
200 | Success |
403 | Forbidden |
404 | Not Found |
409 | Conflict. Someone else holds the lock. |
List versions
Lists every version of the ontology, oldest first. Requires READ permission on the ontology.
Endpoints
GET /aosvc/api/v1/ontologies/{ontologyId}/versions
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 |
Response
[
{
"_versionNumber": 1,
"_versionId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d:v1",
"_status": "PROMOTED",
"_live": true,
"_label": "Initial release",
"_createdAt": "2026-09-01T09:00:00Z",
"_createdBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc",
"_updatedAt": "2026-09-10T11:00:00Z",
"_updatedBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc",
"_publishedAt": "2026-09-10T11:00:00Z",
"_promotedAt": "2026-09-10T11:05:00Z"
},
{
"_versionNumber": 2,
"_versionId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d:v2",
"_status": "DRAFT",
"_live": false,
"_baseVersionNumber": 1,
"_createdAt": "2026-10-01T08:00:00Z",
"_createdBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc",
"_updatedAt": "2026-10-01T10:14:02Z",
"_updatedBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc"
}
]
| Field | Description |
|---|
_versionNumber | The version number. Use it in the X-Ontology-Draft header and in version paths. |
_status | COPYING, DRAFT, PUBLISHED, or PROMOTED. Earlier promoted versions keep PROMOTED. |
_live | Whether this is the live version. |
_baseVersionNumber | The version a draft was copied from. |
_label | The label set when the version was published. |
_updatedAt | Changes on every write into a draft. |
Codes
| Code | Description |
|---|
200 | Success |
403 | Forbidden |
404 | Not Found |
Get a version
Returns one version and the number of schema records it holds of each kind. Requires READ permission on the ontology.
Endpoints
GET /aosvc/api/v1/ontologies/{ontologyId}/versions/{versionNumber}
Parameters
Path
| Parameter | Type | Description | Required |
|---|
ontologyId | String | The ontology ID. | Required |
versionNumber | Integer | The version number. | Required |
Query
| Parameter | Type | Description | Required |
|---|
nsfilter | String | The namespace the ontology belongs to. | Required |
Response
{
"_versionNumber": 2,
"_versionId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d:v2",
"_status": "DRAFT",
"_live": false,
"_baseVersionNumber": 1,
"_createdAt": "2026-10-01T08:00:00Z",
"_createdBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc",
"_updatedAt": "2026-10-01T10:14:02Z",
"_updatedBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc",
"_contents": {
"entity_classes": 7,
"entity_relationships": 5,
"ontology_axioms": 2,
"ontology_shapes": 1,
"entity_collection_mappings": 5
}
}
_contents has one entry for each kind of schema record. The example is shortened.
Codes
| Code | Description |
|---|
200 | Success |
403 | Forbidden |
404 | Not Found |
Create a draft
Copies a published or promoted version into a new draft with the next free version number. By default, the call copies the live version. Requires EDIT permission on the ontology.
If nothing is live and you don't name a version, the call returns the newest version if it's still a draft.
Endpoints
POST /aosvc/api/v1/ontologies/{ontologyId}/drafts
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
The body is optional.
| Parameter | Type | Description | Required |
|---|
_baseVersionNumber | Integer | The version to copy. It must be PUBLISHED or PROMOTED. Default is the live version. | Optional |
Example:
{
"_baseVersionNumber": 1
}
Response
{
"_versionNumber": 2,
"_versionId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d:v2",
"_status": "DRAFT",
"_live": false,
"_baseVersionNumber": 1,
"_createdAt": "2026-10-01T08:00:00Z",
"_createdBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc",
"_updatedAt": "2026-10-01T08:00:00Z",
"_updatedBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc"
}
Codes
| Code | Description |
|---|
200 | Success |
400 | Bad Request. _baseVersionNumber is below 1 or doesn't exist. |
403 | Forbidden |
404 | Not Found |
409 | Conflict. The base version isn't published or promoted, nothing is live and no base was named, or another draft was created at the same time. Retry the last case. |
Discard a draft
Deletes a draft and all its schema. Requires EDIT permission on the ontology. You can't discard a published, promoted, or live version. You also can't discard version 1, the draft the ontology starts with. To remove it, publish it or delete the ontology.
Endpoints
DELETE /aosvc/api/v1/ontologies/{ontologyId}/drafts/{versionNumber}
Parameters
Path
| Parameter | Type | Description | Required |
|---|
ontologyId | String | The ontology ID. | Required |
versionNumber | Integer | The draft's version number. | Required |
Query
| Parameter | Type | Description | Required |
|---|
nsfilter | String | The namespace the ontology belongs to. | Required |
Response
None.
Codes
| Code | Description |
|---|
204 | No Content |
403 | Forbidden |
404 | Not Found |
409 | Conflict. The version isn't a draft, or it's version 1. |
Publish a version
Freezes a draft as PUBLISHED so its schema can't change. Requires EDIT permission on the ontology. Publishing doesn't run any checks.
Endpoints
POST /aosvc/api/v1/ontologies/{ontologyId}/versions/{versionNumber}/publish
Parameters
Path
| Parameter | Type | Description | Required |
|---|
ontologyId | String | The ontology ID. | Required |
versionNumber | Integer | The draft's version number. | Required |
Query
| Parameter | Type | Description | Required |
|---|
nsfilter | String | The namespace the ontology belongs to. | Required |
Body
The body is optional.
| Parameter | Type | Description | Required |
|---|
_label | String | A label for the version. | Optional |
Example:
{
"_label": "2026-10 release"
}
Response
{
"_versionNumber": 2,
"_versionId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d:v2",
"_status": "PUBLISHED",
"_live": false,
"_baseVersionNumber": 1,
"_label": "2026-10 release",
"_createdAt": "2026-10-01T08:00:00Z",
"_createdBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc",
"_updatedAt": "2026-10-02T15:00:00Z",
"_updatedBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc",
"_publishedAt": "2026-10-02T15:00:00Z"
}
Codes
| Code | Description |
|---|
200 | Success |
403 | Forbidden |
404 | Not Found |
409 | Conflict. The version isn't a draft. |
Starts promoting a published version so it becomes the live version. Requires EDIT permission on the ontology.
If a version is already live, the call also requests an impact report that compares this version with the live one, and returns its ID in _reportId. A first promotion has no report. An ontology can have only one open promotion request.
Endpoints
POST /aosvc/api/v1/ontologies/{ontologyId}/promotion-requests
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 |
|---|
_versionNumber | Integer | The published version to promote. Must be a positive whole number. | Required |
Example:
Response
{
"_requestId": "7c1e9a20-4b3d-4e2f-8a1b-9c0d1e2f3a4b",
"_ontologyId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"_versionNumber": 2,
"_fromVersionNumber": 1,
"_reportId": "5f0b6c11-2a3b-4c5d-8e9f-0a1b2c3d4e5f",
"_status": "REPORT_READY",
"_canConfirm": true,
"_findings": [],
"_rollbackErrors": [],
"_requestedAt": "2026-10-01T09:00:00Z",
"_requestedBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc"
}
| Field | Description |
|---|
_fromVersionNumber | The live version when you raised the request. Absent for a first promotion. |
_reportId | The impact report raised with the request. Absent for a first promotion. |
_status | REPORT_READY (waiting for you to confirm), CONFIRMING (a confirmation is being applied), PROMOTED, FAILED (the live version didn't change), or ABANDONED. REPORT_READY, CONFIRMING, and FAILED requests are open. |
_canConfirm | Whether you can confirm the request now. It doesn't mean the impact report is ready. |
_findings | What stopped the last attempt before it changed anything. Each finding has _check, _severity, and _message. An empty list doesn't mean the version passed other checks. |
_taskId | The background task that applies the promotion, after you confirm it. |
_failureReason, _failedAt | Why and when the last attempt failed. Only for FAILED requests. |
_rollbackErrors | Changes in Item Service that a failed or abandoned attempt couldn't undo. Fix these by hand. Usually empty. |
Codes
| Code | Description |
|---|
200 | Success |
400 | Bad Request. _versionNumber is missing or invalid. |
403 | Forbidden |
404 | Not Found |
409 | Conflict. The version isn't published, is already live, or another request is open. |
503 | Service Unavailable. The impact report couldn't be queued. Nothing was recorded, so try again. |
Lists the ontology's promotion requests, newest first. Requires READ permission on the ontology.
Endpoints
GET /aosvc/api/v1/ontologies/{ontologyId}/promotion-requests
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 |
Response
The fields are described in Request a promotion.
[
{
"_requestId": "7c1e9a20-4b3d-4e2f-8a1b-9c0d1e2f3a4b",
"_ontologyId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"_versionNumber": 2,
"_fromVersionNumber": 1,
"_reportId": "5f0b6c11-2a3b-4c5d-8e9f-0a1b2c3d4e5f",
"_status": "PROMOTED",
"_canConfirm": false,
"_findings": [],
"_rollbackErrors": [],
"_taskId": "d2a4e8f0-1b2c-4d3e-9f8a-7b6c5d4e3f2a",
"_requestedAt": "2026-10-01T09:00:00Z",
"_requestedBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc",
"_confirmedAt": "2026-10-01T09:20:00Z",
"_confirmedBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc"
}
]
Codes
| Code | Description |
|---|
200 | Success |
403 | Forbidden |
404 | Not Found |
Returns one promotion request. After you confirm a promotion, poll this endpoint while _status is CONFIRMING. The request ends as PROMOTED, or as FAILED with _failureReason, _failedAt, and any _rollbackErrors. Requires READ permission on the ontology.
Endpoints
GET /aosvc/api/v1/ontologies/{ontologyId}/promotion-requests/{requestId}
Parameters
Path
| Parameter | Type | Description | Required |
|---|
ontologyId | String | The ontology ID. | Required |
requestId | String | The promotion request ID. | Required |
Query
| Parameter | Type | Description | Required |
|---|
nsfilter | String | The namespace the ontology belongs to. | Required |
Response
The fields are described in Request a promotion.
{
"_requestId": "7c1e9a20-4b3d-4e2f-8a1b-9c0d1e2f3a4b",
"_ontologyId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"_versionNumber": 2,
"_fromVersionNumber": 1,
"_reportId": "5f0b6c11-2a3b-4c5d-8e9f-0a1b2c3d4e5f",
"_status": "CONFIRMING",
"_canConfirm": false,
"_findings": [],
"_taskId": "d2a4e8f0-1b2c-4d3e-9f8a-7b6c5d4e3f2a",
"_rollbackErrors": [],
"_requestedAt": "2026-10-01T09:00:00Z",
"_requestedBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc",
"_confirmedAt": "2026-10-01T09:20:00Z",
"_confirmedBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc"
}
Codes
| Code | Description |
|---|
200 | Success |
403 | Forbidden |
404 | Not Found. The request is unknown or belongs to another ontology. |
Applies a promotion request and makes its version live. Requires EDIT permission on the ontology. The promotion runs in the background as you, so the call needs your Authorization header.
The background task registers the version's item types and schemas in Item Service and creates the collections that mappings ask for by name. It then makes the version live. Changes are additive: the promotion never removes an item type or deletes data it didn't create. If the task fails, it undoes its Item Service changes and sets the request to FAILED.
When the new version replaces a live one, the service then updates the class permissions in Item Service to match the new version. Until that update finishes, access granted for the previous version's classes and mappings can remain.
Because the task runs as you, Item Service checks each of its calls against your own Item Service permissions in the namespace. EDIT permission on the ontology lets you confirm, but the task also needs these permissions:
READ and EDIT on itemsvc:schemadefinition:*, to read and register item types.
CREATE on itemsvc:nameduseritem:*, if a mapping asks for a collection by name.
READ and EDIT on each existing collection that a mapping binds to.
DELETE on the collections the promotion creates, so it can undo them if it fails.
If you lack one, the request ends as FAILED, and _failureReason quotes the Item Service refusal. Grant the missing permission, then confirm the same request again.
The call returns 202 with no body. Poll the URL in the Location header, which is Get a promotion request, until the request is PROMOTED or FAILED. A FAILED request can be confirmed again to retry, or abandoned. If you confirm a CONFIRMING request again, the call returns 202 and changes nothing.
Some deployments make the version live at once. In that case, the call returns 200 with the promotion request in PROMOTED status. The call also returns 200 with the request if the background task already ended before the call returned. Check _status, which is then PROMOTED or FAILED.
Endpoints
POST /aosvc/api/v1/ontologies/{ontologyId}/promotion-requests/{requestId}/confirm
Parameters
Path
| Parameter | Type | Description | Required |
|---|
ontologyId | String | The ontology ID. | Required |
requestId | String | The promotion request ID. | Required |
Query
| Parameter | Type | Description | Required |
|---|
nsfilter | String | The namespace the ontology belongs to. | Required |
Body
| Parameter | Type | Description | Required |
|---|
_reportId | String | The ID of the request's impact report, which you reviewed. The report must be READY. Required if the request has a report. A first promotion has none. | Optional |
Example:
{
"_reportId": "5f0b6c11-2a3b-4c5d-8e9f-0a1b2c3d4e5f"
}
Response
None. The response has these headers:
| Header | Description |
|---|
Location | The URL of the promotion request to poll. |
X-AOSVC-Reconciliation-Task-Id | The ID of the background task. You can poll it at GET /aosvc/api/v1/async-tasks/{id}, but the outcome of the promotion is on the promotion request. |
Codes
| Code | Description |
|---|
200 | Success. The promotion already ended. Check _status in the response. |
202 | Accepted. The promotion is running in the background. |
400 | Bad Request. _reportId is missing for a request that has a report. |
401 | Unauthorized |
403 | Forbidden |
404 | Not Found. The request is unknown or belongs to another ontology. |
409 | Conflict. The request isn't REPORT_READY or FAILED, the version is no longer published, _reportId isn't this request's report, the report isn't READY, the live version changed since the request, or someone else changed the request. |
503 | Service Unavailable. The promotion couldn't be queued. Nothing changed, so try again. |
Closes an open promotion request so you can promote a different version. Sets a REPORT_READY or FAILED request to ABANDONED and returns it. You can abandon a CONFIRMING request only after its background task has ended without finishing. Requires EDIT permission on the ontology.
Endpoints
POST /aosvc/api/v1/ontologies/{ontologyId}/promotion-requests/{requestId}/abandon
Parameters
Path
| Parameter | Type | Description | Required |
|---|
ontologyId | String | The ontology ID. | Required |
requestId | String | The promotion request ID. | Required |
Query
| Parameter | Type | Description | Required |
|---|
nsfilter | String | The namespace the ontology belongs to. | Required |
Response
The fields are described in Request a promotion.
{
"_requestId": "7c1e9a20-4b3d-4e2f-8a1b-9c0d1e2f3a4b",
"_ontologyId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"_versionNumber": 2,
"_fromVersionNumber": 1,
"_reportId": "5f0b6c11-2a3b-4c5d-8e9f-0a1b2c3d4e5f",
"_status": "ABANDONED",
"_canConfirm": false,
"_findings": [],
"_rollbackErrors": [],
"_requestedAt": "2026-10-01T09:00:00Z",
"_requestedBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc"
}
Codes
| Code | Description |
|---|
200 | Success |
403 | Forbidden |
404 | Not Found |
409 | Conflict. The request isn't open, or its background task can still run. |