Use the Classes API to create and manage the classes of an application ontology, such as Pump or Floor, and to read a class's effective schema. Every class extends a base platform class or another class in the same ontology version. Every request needs an Authorization: Bearer <token> header. For background, see Classes.
Reads use the live version unless you name another version in the X-Ontology-Draft header. Writes must name a draft in X-Ontology-Draft. For more information, see Versions and drafts.
Writes require EDIT permission on the ontology. If the ontology uses the edit lock, writes also require you to hold the lock. Writes accept an If-Match header with the ontology revision, and return 412 if it's stale. Each successful write returns the new revision in the ETag header. To get _name and _description in a particular language, send an Accept-Language header.
Every ontology contains the platform-managed lifecycle classes State, Event, Action, and StateTransition, marked "_platformManaged": true. You can't update or delete them, or use them as a parent class.
This section contains the following API calls:
List classes
Lists the classes in the version you read. Requires READ permission on the ontology. Fields with no value are left out.
Endpoints
GET /aosvc/api/v1/ontologies/{ontologyId}/classes
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": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f",
"_ontologyId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"_name": "Pump",
"_parentClass": {
"_id": "d3a3f38d-5371-3600-9bec-e49697d8bf39",
"_name": "Entity"
},
"_pluralName": "Pumps",
"_externalKeyFields": ["_sourceKey"],
"_createdAt": "2026-10-01T10:14:02Z",
"_createdBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc"
}
]
| Field | Description |
|---|
_id | The class ID. It's the same in every version. |
_name, _description | The name and description in the language your Accept-Language header selects. |
_parentClass | The ID and name of the class this class extends. To find out whether it's a base class, compare it with List base ontology classes. |
_pluralName | The plural display name. |
_canvasX, _canvasY | The class's position on a diagram canvas. Stored but not interpreted. |
_externalKeyFields | The fields whose values identify an individual in its source system. |
_platformManaged | true for the lifecycle classes. |
Codes
| Code | Description |
|---|
200 | Success |
403 | Forbidden |
404 | Not Found |
Create classes
Creates one class or several classes in a draft. Send an object to create one class, and get an object back. Send an array to create several, and get an array back in the same order. An array is all or nothing: if one class fails, the call creates none of them. A class in the array can extend a class that comes earlier in the same array, so list parent classes before their subclasses.
Endpoints
POST /aosvc/api/v1/ontologies/{ontologyId}/classes
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 draft version number to write to. | Required |
Body
| Parameter | Type | Description | Required |
|---|
_name | String or Object | A name, or a map of language codes to names. It must have an English (en) value that starts with a letter and contains only letters, digits, and underscores. The English name must be unique in the version. Each value has a maximum of 255 characters. | Required |
_parentClass | Object | The class to extend, as { "_id": "<classId>" }. Use a base class or a class in the same version. You can't use a lifecycle class. | Required |
_description | String or Object | A description, or a map of language codes to descriptions. Maximum 10000 characters for each language. Can't be empty: "", {}, or an empty value for any language returns 400. | Optional |
_pluralName | String | The plural display name. Same character rules as the English name. Can't be empty. | Optional |
_canvasX, _canvasY | Number | The class's position on a diagram canvas. An empty string returns 400. | Optional |
_externalKeyFields | String[] | The fields whose values identify an individual in its source system. Must contain at least one non-blank value. | Optional |
Example:
{
"_name": "Pump",
"_parentClass": { "_id": "d3a3f38d-5371-3600-9bec-e49697d8bf39" },
"_pluralName": "Pumps",
"_externalKeyFields": ["_sourceKey"]
}
Response
{
"_id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f",
"_ontologyId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"_name": "Pump",
"_parentClass": {
"_id": "d3a3f38d-5371-3600-9bec-e49697d8bf39",
"_name": "Entity"
},
"_pluralName": "Pumps",
"_externalKeyFields": ["_sourceKey"],
"_createdAt": "2026-10-01T10:14:02Z",
"_createdBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc"
}
Codes
| Code | Description |
|---|
200 | Success |
400 | Bad Request. A field is missing or invalid, or the parent class is unknown or a lifecycle class. |
403 | Forbidden |
404 | Not Found |
409 | Conflict. No draft is named, the English name is already used, or someone else holds the edit lock. |
412 | Precondition Failed. The If-Match revision is stale. |
422 | Unprocessable Entity. The parent creates a cycle, or a chain across mutually exclusive classes. |
423 | Locked. The ontology uses the edit lock and nobody holds it. |
Get a class
Requires READ permission on the ontology.
Endpoints
GET /aosvc/api/v1/ontologies/{ontologyId}/classes/{classId}
Parameters
Path
| Parameter | Type | Description | Required |
|---|
ontologyId | String | The ontology ID. | Required |
classId | String | The class 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
The fields are described in List classes.
{
"_id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f",
"_ontologyId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"_name": "Pump",
"_description": "A mechanical pump",
"_parentClass": {
"_id": "d3a3f38d-5371-3600-9bec-e49697d8bf39",
"_name": "Entity"
},
"_pluralName": "Pumps",
"_externalKeyFields": ["_sourceKey"],
"_createdAt": "2026-10-01T10:14:02Z",
"_updatedAt": "2026-10-01T10:30:00Z",
"_createdBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc",
"_updatedBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc"
}
Codes
| Code | Description |
|---|
200 | Success |
403 | Forbidden |
404 | Not Found. The class isn't in the version you read. |
Update a class
Updates a class in a draft. Omitted fields keep their values.
To move the class under another parent, send _parentClass. Changing the parent changes the effective schema of the class and all its subclasses, including the constraints that existing individuals must meet once the version is live. Afterward, check Get the effective schema of a class.
Endpoints
PUT /aosvc/api/v1/ontologies/{ontologyId}/classes/{classId}
Parameters
Path
| Parameter | Type | Description | Required |
|---|
ontologyId | String | The ontology ID. | Required |
classId | String | The class 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 draft version number to write 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 rules as on create. | Optional |
_description | String or Object | A description, or a map of language codes to descriptions. Same rules as on create. You can replace a description, but you can't clear it. | Optional |
_parentClass | Object | The new parent, as { "_id": "<classId>" }. Same rules as on create. | Optional |
_externalKeyFields | String[] | Replaces the list. | Optional |
_pluralName | String | The plural display name. Same rules as on create. You can't clear it. | Optional |
_canvasX, _canvasY | Number | The class's position on a diagram canvas. An empty string returns 400. | Optional |
Example:
{
"_description": { "en": "A mechanical pump", "de": "Eine mechanische Pumpe" },
"_parentClass": { "_id": "0b9e7c1a-2d3e-4f5a-8b6c-7d8e9f0a1b2c" }
}
Response
The fields are described in List classes.
{
"_id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f",
"_ontologyId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"_name": "Pump",
"_description": "A mechanical pump",
"_parentClass": {
"_id": "0b9e7c1a-2d3e-4f5a-8b6c-7d8e9f0a1b2c",
"_name": "Equipment"
},
"_pluralName": "Pumps",
"_externalKeyFields": ["_sourceKey"],
"_createdAt": "2026-10-01T10:14:02Z",
"_updatedAt": "2026-10-02T08:00:00Z",
"_createdBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc",
"_updatedBy": "c9daff7e-b55b-41ec-aa46-d0150f3199dc"
}
Codes
| Code | Description |
|---|
200 | Success |
400 | Bad Request. A field is invalid, or _parentClass has no _id. |
403 | Forbidden |
404 | Not Found |
409 | Conflict. No draft is named, the English name is already used, the class is platform-managed, or someone else holds the edit lock. |
412 | Precondition Failed. The If-Match revision is stale. |
422 | Unprocessable Entity. The new parent creates a cycle, or a chain across mutually exclusive classes. The chain includes the superclasses that the class's own subClassOf rules give it. |
423 | Locked. The ontology uses the edit lock and nobody holds it. |
Delete a class
Deletes a class from a draft. The call also deletes, in the same version, the relationships declared to or from the class and its collection and property mappings. The Item Service collection and its data are not deleted. You can't delete a class that has subclasses. Delete or move the subclasses first.
Endpoints
DELETE /aosvc/api/v1/ontologies/{ontologyId}/classes/{classId}
Parameters
Path
| Parameter | Type | Description | Required |
|---|
ontologyId | String | The ontology ID. | Required |
classId | String | The class 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 draft version number to write to. | Required |
Response
None.
Codes
| Code | Description |
|---|
204 | No Content |
403 | Forbidden |
404 | Not Found |
409 | Conflict. No draft is named, the class has subclasses, the class is platform-managed, or someone else holds the edit lock. |
412 | Precondition Failed. The If-Match revision is stale. |
423 | Locked. The ontology uses the edit lock and nobody holds it. |
Get the effective schema of a class
Returns a class's schema with inheritance resolved: every property, constraint, and state machine that applies to an individual of the class. Requires READ permission on the ontology.
To read a base class schema, use base as the ontologyId. Any authenticated caller can read a base class schema.
Endpoints
GET /aosvc/api/v1/ontologies/{ontologyId}/classes/{classId}/schema
Parameters
Path
| Parameter | Type | Description | Required |
|---|
ontologyId | String | The ontology ID, or base for a base class. | Required |
classId | String | The class ID. | Required |
Query
| Parameter | Type | Description | Required |
|---|
nsfilter | String | The namespace the ontology belongs to. | Required |
inherited | Boolean | Set to false to return only what the class declares itself. Default is true. | Optional |
baseVersion | String | For a base class, the base ontology version. Default is the latest version. | Optional |
| Parameter | Type | Description | Required |
|---|
X-Ontology-Draft | Integer | The version number to read. Default is the live version. | Optional |
Response
{
"_ontologyId": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"_classId": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f",
"_className": "Pump",
"_ancestors": [
{ "_id": "d3a3f38d-5371-3600-9bec-e49697d8bf39", "_name": "Entity", "_base": true }
],
"_properties": [
{
"_name": "entityName",
"_propertyType": "datatype",
"_range": "string",
"_inherited": true,
"_sourceClassName": "Entity",
"_queryPath": "entityName"
},
{
"_name": "nominalFlowRate",
"_propertyType": "datatype",
"_range": "number",
"_inherited": false,
"_sourceClassName": "Pump",
"_itemsvcField": "properties.flowRate",
"_transform": "number",
"_constraints": [ { "path": "nominalFlowRate", "minInclusive": 0 } ]
},
{
"_name": "locatedIn",
"_propertyType": "relationship",
"_range": "Space",
"_rangeClassId": "4e5f6a7b-8c9d-4e0f-a1b2-c3d4e5f6a7b8",
"_inherited": false,
"_relationshipId": "9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d"
}
],
"_constraints": [
{
"targetClass": "Pump",
"properties": [ { "path": "nominalFlowRate", "minInclusive": 0 } ],
"_id": "Pump:nominalFlowRate",
"_targetClass": "Pump"
}
],
"_stateMachines": []
}
| Field | Description |
|---|
_ontologyId | The ontology ID, or base for a base class. |
_ancestors | The parent chain. Each entry has _id, _name, and _base, which is true for a base class. Empty for a base class. |
_properties | Data properties and relationships in one list. If a subclass declares a property with the same name as an ancestor, the subclass's declaration replaces it. |
_properties[]._propertyType | datatype or relationship. |
_properties[]._range, _rangeClassId | The value type, or the target class of a relationship. |
_properties[]._inherited, _sourceClassId, _sourceClassName | Whether the property comes from an ancestor, and which class declares it. |
_properties[]._queryPath | How to reference the property in a query. |
_properties[]._itemsvcField, _transform, _scripted | How the property maps from item data, when it's mapped. |
_properties[]._relationshipId | The ID of the relationship that declares the property. |
_properties[]._constraints | The constraint rules for the property, taken from the properties array of each entry in _constraints. |
_constraints | The constraints that apply to the class: those that target the class and, unless inherited is false, those that target its ancestors, including base classes such as Entity. Each entry is the constraint's shape, with _id set to its _constraintId label and _targetClass set to the class name. |
_stateMachines | The state machines that apply to the class. Each has _machineId, _machineName, _sourceClassId, _inherited, _states, and _transitions. Empty for a base class. |
Keys with no value are left out. Constraints you declare apply to subclasses too. The base ontology's own constraints apply only to the exact base class.
Codes
| Code | Description |
|---|
200 | Success |
400 | Bad Request. The baseVersion is unknown. |
403 | Forbidden |
404 | Not Found |