Individuals
An individual is one instance of an entity class, such as a specific pump or a specific floor. The Application Ontology Service stores each individual as an item in the Item Service collection that its class is mapped to. Use the Individuals API to create, read, search, update, and delete individuals, to read their state transition history, and to traverse the relationships between them. For more information, see Individuals.
This section contains the following API calls:
- Create individuals
- List individuals
- Search individuals
- Get an individual
- Update an individual
- Delete an individual
- Get the transition history of an individual
- Traverse relationships between individuals
To add or remove relationships between individuals, see Individual relationships. To load many individuals across classes in one request, see Import individuals.
Before you start
Every call needs an Authorization: Bearer <token> header and the nsfilter query parameter.
- Live version only. Individuals always use the ontology's live version. Until you promote the first version, every call returns
409. A class that exists only in a draft returns404. - Collection mapping. The class needs a collection mapping in the live version, or the call returns
404. If the live mapping has no collection yet, the call returns409. Promote the version again, or bind an existing collection. If the collection was deleted in the Item Service, the call also returns409. To fix it, bind the class to an existing collection in a draft and promote the draft. - Lifecycle classes are read-only. Creating, updating, or deleting individuals of the
State,StateTransition,Event, andActionclasses returns403. The state machine API writes those individuals. - Class scoping. Several classes can share a collection, so every read is limited to the class and its subclasses. Reading a parent class returns its subclasses' individuals too. An individual of a sibling class returns
404.
Permissions
Each call checks an INDIVIDUALS_* action on the class or one of its ancestors. A grant on Equipment also covers Pump. A class-level READ, CREATE, EDIT, or DELETE grant also satisfies the matching INDIVIDUALS_* action.
Actions are exact-match, so EDIT does not imply READ. To update or delete an individual, you also need READ, because the service reads the individual as you before it writes. If the Item Service refuses a call made with your token, the response is 403, or 404 if the Item Service returns 404.
For the full permission model, see Permissions.
Create individuals
Creates one or more individuals of a class. The service validates every individual against the class's constraints before it stores anything. If any individual fails validation, nothing is stored and the call returns 422 with the validation result.
Send a single object to create one individual, or an array to create several. The response matches: an object for an object, an array for an array.
Endpoints
POST /aosvc/api/v1/classes/{classId}/individuals
Parameters
Path
| Parameter | Type | Description | Required |
|---|---|---|---|
classId | String | The ID of the entity class. | Required |
Query
| Parameter | Type | Description | Required |
|---|---|---|---|
nsfilter | String | The namespace filter. Must name only namespaces the class's ontology belongs to. | Required |
Body
A JSON object, or an array of JSON objects, in the Item Service item shape.
| Parameter | Type | Description | Required |
|---|---|---|---|
_name | String | The display name of the individual. Must be a non-empty string or null. An empty or blank name fails validation. | Optional |
properties | Object | The individual's domain data. The service stamps properties._classId with the class ID. | Optional |
_typeName | String | The item type. Defaults to the user type of the class's collection mapping. | Optional |
_sourceId | String | The source ID. Required when the class is mapped to a telemetry collection. If you don't send it, the service keeps the stored _sourceId. On an import, it defaults to the individual's external key. | Optional |
_relationships | Array | Relationships from this individual to existing individuals. Each entry is an object with _userType, a non-empty _relatedToIds array, and optional _customAttributes. Any other value returns 400. The service writes them as separate relationship records and does not store them on the item. For more information, see Individual relationships. | Optional |
Any other field is stored as sent. Only the class's constraints and required relationships can reject a field. The _aostates, _transitionId, _transitionCorrelationId, and _transitionSeq fields are managed by the service. Sending one of them returns 400.
Example:
{
"_name": "Pump-A1",
"properties": {
"flowRate": 42.5,
"installDate": "2025-06-01T00:00:00Z"
},
"_relationships": [
{
"_userType": "locatedAt",
"_relatedToIds": ["6702a9f3c1e4b2001f9a1d40"]
}
]
}
Response
{
"_id": "6702a9f3c1e4b2001f9a1c21",
"_name": "Pump-A1",
"_typeName": "pump",
"properties": {
"_classId": "3f6c1a52-8d0e-4b7a-9c4f-2e1d5b8a7c90",
"flowRate": 42.5,
"installDate": "2025-06-01T00:00:00Z"
},
"_metadata": {
"_createdAt": 1760947200000,
"_createdById": "c9daff7e-b55b-41ec-aa46-d0150f3199dc",
"_updatedAt": 1760947200000,
"_updatedById": "c9daff7e-b55b-41ec-aa46-d0150f3199dc"
}
}
If validation fails, the 422 body is the validation result. _focusNode names the class, not the individual, so it doesn't identify which element of an array failed.
{
"_conforms": false,
"_violations": [
{
"_focusNode": "Pump",
"_resultPath": "flowRate",
"_message": "datatype violation: 'flowRate' expected decimal but found \"fast\"",
"_severity": "Violation"
}
]
}
Note: The service validates
_relationshipsbefore it writes the individual, but writes the relationships after. If the relationship write fails at that point, the individual is stored without its relationships. Check with List the relationships of an individual before you retry.
Codes
| Code | Description |
|---|---|
201 | Created |
400 | Bad Request. The body is missing or isn't an object or array, a service-managed field is set, _sourceId is missing for a telemetry collection, _relationships isn't an array of objects, an inline relationship is invalid, or nsfilter is missing. |
401 | Unauthorized |
403 | Forbidden. No INDIVIDUALS_CREATE grant, the class is a lifecycle class, or the Item Service refused the call. |
404 | Not Found. The class isn't in the live version, has no collection mapping, or nsfilter names a namespace outside the ontology. |
409 | Conflict. The ontology has no live version, the live mapping has no collection, or the collection no longer exists in the Item Service. |
422 | Unprocessable Entity. Validation failed, for example because _name is empty or a required relationship is missing. Nothing was stored. |
502 | Bad Gateway. The Item Service failed or was unreachable. |
List individuals
Lists the individuals of a class and its subclasses. The response is a flat array with no total or paging. To count or page through individuals, use Search individuals.
Endpoints
GET /aosvc/api/v1/classes/{classId}/individuals
Parameters
Path
| Parameter | Type | Description | Required |
|---|---|---|---|
classId | String | The ID of the entity class. | Required |
Query
| Parameter | Type | Description | Required |
|---|---|---|---|
nsfilter | String | The namespace filter. Must name only namespaces the class's ontology belongs to. | Required |
limit | Integer | The maximum number of individuals to return. | Optional, default is 1000 |
Response
[
{
"_id": "6702a9f3c1e4b2001f9a1c21",
"_name": "Pump-A1",
"_typeName": "pump",
"properties": {
"_classId": "3f6c1a52-8d0e-4b7a-9c4f-2e1d5b8a7c90",
"flowRate": 42.5
},
"_metadata": {
"_createdAt": 1760947200000,
"_createdById": "c9daff7e-b55b-41ec-aa46-d0150f3199dc",
"_updatedAt": 1760947200000,
"_updatedById": "c9daff7e-b55b-41ec-aa46-d0150f3199dc"
}
}
]
Codes
| Code | Description |
|---|---|
200 | Success |
400 | Bad Request. nsfilter is missing. |
401 | Unauthorized |
403 | Forbidden. No INDIVIDUALS_READ grant, or the Item Service refused the call. |
404 | Not Found. The class isn't in the live version, has no collection mapping, or nsfilter names a namespace outside the ontology. |
409 | Conflict. The ontology has no live version, the live mapping has no collection, or the collection no longer exists in the Item Service. |
502 | Bad Gateway. The Item Service failed or was unreachable. |
Search individuals
Filters, sorts, projects, and pages the individuals of a class and its subclasses. An empty body returns the first 100 individuals. The filter can't select individuals by their relationships. To do that, use Traverse relationships between individuals.
Endpoints
POST /aosvc/api/v1/classes/{classId}/individuals/search
Parameters
Path
| Parameter | Type | Description | Required |
|---|---|---|---|
classId | String | The ID of the entity class. | Required |
Query
| Parameter | Type | Description | Required |
|---|---|---|---|
nsfilter | String | The namespace filter. Must name only namespaces the class's ontology belongs to. | Required |
Body
| Parameter | Type | Description | Required |
|---|---|---|---|
_filter | Object | An Item Service query on the item. The service combines it with the class scope. | Optional |
_includeSubclasses | Boolean | Set to false to return only individuals of this exact class. | Optional, default is true |
_offset | Integer | The position to start from. A negative value is treated as 0. | Optional, default is 0 |
_pageSize | Integer | The number of individuals per page. Values outside 1 to 200 are clamped to that range. | Optional, default is 100 |
_sort | Object | Field paths mapped to 1 (ascending) or -1 (descending). | Optional |
_projection | Array | The field paths to return. | Optional |
Example:
{
"_filter": { "properties.flowRate": { "$gte": 40 } },
"_sort": { "properties.installDate": -1 },
"_projection": ["_id", "_name", "properties.flowRate"],
"_pageSize": 50
}
Response
_pageSize is the page size the service applied.
{
"_list": [
{
"_id": "6702a9f3c1e4b2001f9a1c21",
"_name": "Pump-A1",
"properties": { "flowRate": 42.5 }
}
],
"_offset": 0,
"_pageSize": 50,
"_total": 1,
"_hasMore": false
}
Codes
| Code | Description |
|---|---|
200 | Success |
400 | Bad Request. nsfilter is missing. |
401 | Unauthorized |
403 | Forbidden. No INDIVIDUALS_READ grant, or the Item Service refused the call. |
404 | Not Found. The class isn't in the live version, has no collection mapping, or nsfilter names a namespace outside the ontology. |
409 | Conflict. The ontology has no live version, the live mapping has no collection, or the collection no longer exists in the Item Service. |
502 | Bad Gateway. The Item Service failed or was unreachable. |
Get an individual
Gets one individual by ID. The response doesn't include its relationships. To read them, use List the relationships of an individual.
Endpoints
GET /aosvc/api/v1/classes/{classId}/individuals/{individualId}
Parameters
Path
| Parameter | Type | Description | Required |
|---|---|---|---|
classId | String | The ID of the entity class. | Required |
individualId | String | The _id of the individual. | Required |
Query
| Parameter | Type | Description | Required |
|---|---|---|---|
nsfilter | String | The namespace filter. Must name only namespaces the class's ontology belongs to. | Required |
Response
_uri is the Item Service route to the item. It appears only on this call, not in list or search results.
{
"_id": "6702a9f3c1e4b2001f9a1c21",
"_name": "Pump-A1",
"_typeName": "pump",
"_uri": "/nameduseritems/6702a8e1c1e4b2001f9a1b10/relateditems/6702a9f3c1e4b2001f9a1c21",
"properties": {
"_classId": "3f6c1a52-8d0e-4b7a-9c4f-2e1d5b8a7c90",
"flowRate": 42.5
},
"_aostates": [
{ "stateMachineId": "a81c4f20-5b3e-4d71-9e02-6c7f8d9a0b13", "state": "Installed" }
],
"_metadata": {
"_createdAt": 1760947200000,
"_createdById": "c9daff7e-b55b-41ec-aa46-d0150f3199dc",
"_updatedAt": 1760947200000,
"_updatedById": "c9daff7e-b55b-41ec-aa46-d0150f3199dc"
}
}
Codes
| Code | Description |
|---|---|
200 | Success |
400 | Bad Request. nsfilter is missing. |
401 | Unauthorized |
403 | Forbidden. No INDIVIDUALS_READ grant, or the Item Service refused the call. |
404 | Not Found. The individual doesn't exist or belongs to a class outside this class's subtree, the class isn't in the live version, or nsfilter names a namespace outside the ontology. |
409 | Conflict. The ontology has no live version, the live mapping has no collection, or the collection no longer exists in the Item Service. |
502 | Bad Gateway. The Item Service failed or was unreachable. |
Update an individual
Replaces one individual. The service validates the body as it does for Create individuals. The stored _aostates value is kept, whatever you send.
To replace the individual's relationships, include _relationships. It becomes the individual's complete set of outgoing relationships: the service removes every stored relationship from the individual and writes the ones you send. Send [] to remove them all. Leave _relationships out to keep the stored relationships. The kept relationships then count toward the class's required relationships. To add or remove one relationship, use Individual relationships.
You need READ as well as INDIVIDUALS_EDIT, because the service reads the stored individual before it writes.
Endpoints
PUT /aosvc/api/v1/classes/{classId}/individuals/{individualId}
Parameters
Path
| Parameter | Type | Description | Required |
|---|---|---|---|
classId | String | The ID of the entity class. | Required |
individualId | String | The _id of the individual. | Required |
Query
| Parameter | Type | Description | Required |
|---|---|---|---|
nsfilter | String | The namespace filter. Must name only namespaces the class's ontology belongs to. | Required |
Body
A single JSON object with the same fields as Create individuals. An array returns 400.
Example:
{
"_name": "Pump-A1",
"properties": {
"flowRate": 47.0,
"installDate": "2025-06-01T00:00:00Z"
}
}
Response
{
"_id": "6702a9f3c1e4b2001f9a1c21",
"_name": "Pump-A1",
"_typeName": "pump",
"properties": {
"_classId": "3f6c1a52-8d0e-4b7a-9c4f-2e1d5b8a7c90",
"flowRate": 47.0,
"installDate": "2025-06-01T00:00:00Z"
},
"_metadata": {
"_createdAt": 1760947200000,
"_createdById": "c9daff7e-b55b-41ec-aa46-d0150f3199dc",
"_updatedAt": 1760950800000,
"_updatedById": "c9daff7e-b55b-41ec-aa46-d0150f3199dc"
}
}
Codes
| Code | Description |
|---|---|
200 | Success |
400 | Bad Request. The body isn't a single object, _sourceId is missing for a telemetry collection, _relationships isn't an array of objects, an inline relationship is invalid, or nsfilter is missing. |
401 | Unauthorized |
403 | Forbidden. No INDIVIDUALS_EDIT grant, the class is a lifecycle class, or the Item Service refused the call, usually because you lack READ. |
404 | Not Found. The individual doesn't exist or belongs to a class outside this class's subtree, the class isn't in the live version, or nsfilter names a namespace outside the ontology. |
409 | Conflict. The ontology has no live version, the live mapping has no collection, or the collection no longer exists in the Item Service. |
422 | Unprocessable Entity. Validation failed, or a functional relationship has more than one target. Nothing was stored. |
502 | Bad Gateway. The Item Service failed or was unreachable. |
Delete an individual
Deletes one individual. The Item Service also deletes the relationships the individual takes part in, from either end.
You need READ as well as INDIVIDUALS_DELETE, because the service reads the individual before it deletes it.
Endpoints
DELETE /aosvc/api/v1/classes/{classId}/individuals/{individualId}
Parameters
Path
| Parameter | Type | Description | Required |
|---|---|---|---|
classId | String | The ID of the entity class. | Required |
individualId | String | The _id of the individual. | Required |
Query
| Parameter | Type | Description | Required |
|---|---|---|---|
nsfilter | String | The namespace filter. Must name only namespaces the class's ontology belongs to. | Required |
Response
A successful call returns 204 with no body.
Codes
| Code | Description |
|---|---|
204 | No Content |
400 | Bad Request. nsfilter is missing. |
401 | Unauthorized |
403 | Forbidden. No INDIVIDUALS_DELETE grant, the class is a lifecycle class, or the Item Service refused the call, usually because you lack READ. |
404 | Not Found. The individual doesn't exist or belongs to a class outside this class's subtree, the class isn't in the live version, or nsfilter names a namespace outside the ontology. |
409 | Conflict. The ontology has no live version, the live mapping has no collection, or the collection no longer exists in the Item Service. |
502 | Bad Gateway. The Item Service failed or was unreachable. |
Get the transition history of an individual
Lists every attempted state machine transition for an individual, committed and rejected, newest first. A transition that is still queued doesn't appear yet.
Endpoints
GET /aosvc/api/v1/classes/{classId}/individuals/{individualId}/transition-history
Parameters
Path
| Parameter | Type | Description | Required |
|---|---|---|---|
classId | String | The ID of the entity class. | Required |
individualId | String | The _id of the individual. | Required |
Query
| Parameter | Type | Description | Required |
|---|---|---|---|
nsfilter | String | The namespace filter. Must name only namespaces the class's ontology belongs to. | Required |
Response
_success is true when the transition committed. _currentState is the state before the attempt, or null. _eventTriggerId identifies the triggering request and is shared by every individual in a batch.
[
{
"_id": "e4b1c9a0-2f7d-4c3e-8a15-9d6b0f2e7c41",
"_eventTriggerId": "7c2e9f14-0a3b-4d58-b6e1-3f9a8c5d2b70",
"_stateMachineId": "a81c4f20-5b3e-4d71-9e02-6c7f8d9a0b13",
"_classId": "3f6c1a52-8d0e-4b7a-9c4f-2e1d5b8a7c90",
"_individualId": "6702a9f3c1e4b2001f9a1c21",
"_eventId": "b5d0e3f7-6c1a-4e29-8f4b-0a7c3d9e2f16",
"_eventName": "install",
"_eventSourceType": "MANUAL",
"_transitionId": "d2f8a6c4-1e3b-4970-a5c8-7b0e9f1d3a52",
"_fromStateId": "f0a9c7e5-3d1b-4f82-b6a4-2c8e0d7f5b39",
"_toStateId": "c3e1b9d7-5f2a-4c60-8e4d-1b9f7a3c5e28",
"_fromStateValue": "Ordered",
"_toStateValue": "Installed",
"_success": true,
"_currentState": "Ordered",
"_actorUserId": "c9daff7e-b55b-41ec-aa46-d0150f3199dc",
"_occurredAt": "2026-10-20T09:15:00Z",
"_committedAt": "2026-10-20T09:15:01Z"
}
]
Codes
| Code | Description |
|---|---|
200 | Success |
400 | Bad Request. nsfilter is missing. |
401 | Unauthorized |
403 | Forbidden. No INDIVIDUALS_READ grant, or the Item Service refused the call. |
404 | Not Found. The individual doesn't exist or belongs to a class outside this class's subtree, the class isn't in the live version, or nsfilter names a namespace outside the ontology. |
409 | Conflict. The ontology has no live version, the live mapping has no collection, or the collection no longer exists in the Item Service. |
502 | Bad Gateway. The Item Service failed or was unreachable. |
Traverse relationships between individuals
Starts from individuals of a class and follows relationships hop by hop, then returns a page of the individuals the last hop reaches. Use it to select individuals by what they are related to. For more information, see Individual relationships.
Each hop must be a relationship declared on the current class or one of its ancestors. If the relationship is declared to several target classes, the hop follows all of them. An empty page means no individuals have those relationships. _breadcrumbs shows which hop found none.
Endpoints
POST /aosvc/api/v1/classes/{classId}/individuals/traverse
Parameters
Path
| Parameter | Type | Description | Required |
|---|---|---|---|
classId | String | The ID of the class the traversal starts from. | Required |
Query
| Parameter | Type | Description | Required |
|---|---|---|---|
nsfilter | String | The namespace filter. Must name only namespaces the class's ontology belongs to. | Required |
Body
| Parameter | Type | Description | Required |
|---|---|---|---|
_startIndividualIds | Array | The IDs of the individuals to start from, in this class or its subclasses. Up to 1000. | Required |
_hops | Array | The ordered relationships to follow, each as { "_relationship": "<name>" }. Each hop starts from the individuals the previous hop reached. | Required |
_filter | Object | A filter on the individuals the last hop reaches. It works the same way as in Search individuals and uses the stored field names. | Optional |
_offset | Integer | The position to start from. | Optional, default is 0 |
_pageSize | Integer | The number of individuals per page, up to 200. | Optional, default is 100 |
_sort | Object | Field paths mapped to 1 (ascending) or -1 (descending). Numbers sort by value. Individuals without the field come first in ascending order and last in descending order. | Optional |
_projection | Array | The field paths to return. The response always includes _id. | Optional |
Example:
{
"_startIndividualIds": ["6702a9f3c1e4b2001f9a1c21"],
"_hops": [
{ "_relationship": "locatedAt" },
{ "_relationship": "partOf" }
],
"_pageSize": 20
}
Response
_page uses the same envelope as Search individuals and holds whole individuals, as stored. The first breadcrumb is the start class.
{
"_startClassId": "3f6c1a52-8d0e-4b7a-9c4f-2e1d5b8a7c90",
"_terminalClassId": "9b2d4e6f-8a1c-4b3d-9e5f-7a6b8c0d1e23",
"_path": [
{
"_relationship": "locatedAt",
"_sourceClassId": "3f6c1a52-8d0e-4b7a-9c4f-2e1d5b8a7c90",
"_targetClassId": "5e7f9a1b-3c2d-4e6f-8a0b-1c3d5e7f9a20"
},
{
"_relationship": "partOf",
"_sourceClassId": "5e7f9a1b-3c2d-4e6f-8a0b-1c3d5e7f9a20",
"_targetClassId": "9b2d4e6f-8a1c-4b3d-9e5f-7a6b8c0d1e23"
}
],
"_breadcrumbs": [
{
"_classId": "3f6c1a52-8d0e-4b7a-9c4f-2e1d5b8a7c90",
"_individualIds": ["6702a9f3c1e4b2001f9a1c21"],
"_viaRelationship": null,
"_count": 1
},
{
"_classId": "5e7f9a1b-3c2d-4e6f-8a0b-1c3d5e7f9a20",
"_individualIds": ["6702a9f3c1e4b2001f9a1d40"],
"_viaRelationship": "locatedAt",
"_count": 1
},
{
"_classId": "9b2d4e6f-8a1c-4b3d-9e5f-7a6b8c0d1e23",
"_individualIds": ["6702a9f3c1e4b2001f9a1e55"],
"_viaRelationship": "partOf",
"_count": 1
}
],
"_page": {
"_list": [
{
"_id": "6702a9f3c1e4b2001f9a1e55",
"_name": "Level 2",
"properties": { "_classId": "9b2d4e6f-8a1c-4b3d-9e5f-7a6b8c0d1e23" }
}
],
"_offset": 0,
"_pageSize": 20,
"_total": 1,
"_hasMore": false
}
}
Codes
| Code | Description |
|---|---|
200 | Success |
400 | Bad Request. _startIndividualIds or _hops is empty, a _relationship is blank or not declared, a class on the path has no collection mapping, or nsfilter is missing. |
401 | Unauthorized |
403 | Forbidden. No INDIVIDUALS_READ grant, or the Item Service refused the call. |
404 | Not Found. A start individual doesn't exist, the class isn't in the live version, or nsfilter names a namespace outside the ontology. |
409 | Conflict. The ontology has no live version, or the live mapping has no collection. |
413 | Payload Too Large. A hop reached more than 1000 individuals. |
502 | Bad Gateway. The Item Service failed or was unreachable. |