Skip to main content
Version: v5.3

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:

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 returns 404.
  • 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 returns 409. Promote the version again, or bind an existing collection. If the collection was deleted in the Item Service, the call also returns 409. 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, and Action classes returns 403. 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​

ParameterTypeDescriptionRequired
classIdStringThe ID of the entity class.Required

Query​

ParameterTypeDescriptionRequired
nsfilterStringThe 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.

ParameterTypeDescriptionRequired
_nameStringThe display name of the individual. Must be a non-empty string or null. An empty or blank name fails validation.Optional
propertiesObjectThe individual's domain data. The service stamps properties._classId with the class ID.Optional
_typeNameStringThe item type. Defaults to the user type of the class's collection mapping.Optional
_sourceIdStringThe 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
_relationshipsArrayRelationships 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 _relationships before 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​

CodeDescription
201Created
400Bad 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.
401Unauthorized
403Forbidden. No INDIVIDUALS_CREATE grant, the class is a lifecycle class, or the Item Service refused the call.
404Not Found. The class isn't in the live version, has no collection mapping, or nsfilter names a namespace outside the ontology.
409Conflict. The ontology has no live version, the live mapping has no collection, or the collection no longer exists in the Item Service.
422Unprocessable Entity. Validation failed, for example because _name is empty or a required relationship is missing. Nothing was stored.
502Bad 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​

ParameterTypeDescriptionRequired
classIdStringThe ID of the entity class.Required

Query​

ParameterTypeDescriptionRequired
nsfilterStringThe namespace filter. Must name only namespaces the class's ontology belongs to.Required
limitIntegerThe 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​

CodeDescription
200Success
400Bad Request. nsfilter is missing.
401Unauthorized
403Forbidden. No INDIVIDUALS_READ grant, or the Item Service refused the call.
404Not Found. The class isn't in the live version, has no collection mapping, or nsfilter names a namespace outside the ontology.
409Conflict. The ontology has no live version, the live mapping has no collection, or the collection no longer exists in the Item Service.
502Bad 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​

ParameterTypeDescriptionRequired
classIdStringThe ID of the entity class.Required

Query​

ParameterTypeDescriptionRequired
nsfilterStringThe namespace filter. Must name only namespaces the class's ontology belongs to.Required

Body​

ParameterTypeDescriptionRequired
_filterObjectAn Item Service query on the item. The service combines it with the class scope.Optional
_includeSubclassesBooleanSet to false to return only individuals of this exact class.Optional, default is true
_offsetIntegerThe position to start from. A negative value is treated as 0.Optional, default is 0
_pageSizeIntegerThe number of individuals per page. Values outside 1 to 200 are clamped to that range.Optional, default is 100
_sortObjectField paths mapped to 1 (ascending) or -1 (descending).Optional
_projectionArrayThe 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​

CodeDescription
200Success
400Bad Request. nsfilter is missing.
401Unauthorized
403Forbidden. No INDIVIDUALS_READ grant, or the Item Service refused the call.
404Not Found. The class isn't in the live version, has no collection mapping, or nsfilter names a namespace outside the ontology.
409Conflict. The ontology has no live version, the live mapping has no collection, or the collection no longer exists in the Item Service.
502Bad 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​

ParameterTypeDescriptionRequired
classIdStringThe ID of the entity class.Required
individualIdStringThe _id of the individual.Required

Query​

ParameterTypeDescriptionRequired
nsfilterStringThe 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​

CodeDescription
200Success
400Bad Request. nsfilter is missing.
401Unauthorized
403Forbidden. No INDIVIDUALS_READ grant, or the Item Service refused the call.
404Not 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.
409Conflict. The ontology has no live version, the live mapping has no collection, or the collection no longer exists in the Item Service.
502Bad 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​

ParameterTypeDescriptionRequired
classIdStringThe ID of the entity class.Required
individualIdStringThe _id of the individual.Required

Query​

ParameterTypeDescriptionRequired
nsfilterStringThe 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​

CodeDescription
200Success
400Bad 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.
401Unauthorized
403Forbidden. No INDIVIDUALS_EDIT grant, the class is a lifecycle class, or the Item Service refused the call, usually because you lack READ.
404Not 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.
409Conflict. The ontology has no live version, the live mapping has no collection, or the collection no longer exists in the Item Service.
422Unprocessable Entity. Validation failed, or a functional relationship has more than one target. Nothing was stored.
502Bad 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​

ParameterTypeDescriptionRequired
classIdStringThe ID of the entity class.Required
individualIdStringThe _id of the individual.Required

Query​

ParameterTypeDescriptionRequired
nsfilterStringThe namespace filter. Must name only namespaces the class's ontology belongs to.Required

Response​

A successful call returns 204 with no body.

Codes​

CodeDescription
204No Content
400Bad Request. nsfilter is missing.
401Unauthorized
403Forbidden. No INDIVIDUALS_DELETE grant, the class is a lifecycle class, or the Item Service refused the call, usually because you lack READ.
404Not 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.
409Conflict. The ontology has no live version, the live mapping has no collection, or the collection no longer exists in the Item Service.
502Bad 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​

ParameterTypeDescriptionRequired
classIdStringThe ID of the entity class.Required
individualIdStringThe _id of the individual.Required

Query​

ParameterTypeDescriptionRequired
nsfilterStringThe 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​

CodeDescription
200Success
400Bad Request. nsfilter is missing.
401Unauthorized
403Forbidden. No INDIVIDUALS_READ grant, or the Item Service refused the call.
404Not 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.
409Conflict. The ontology has no live version, the live mapping has no collection, or the collection no longer exists in the Item Service.
502Bad 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​

ParameterTypeDescriptionRequired
classIdStringThe ID of the class the traversal starts from.Required

Query​

ParameterTypeDescriptionRequired
nsfilterStringThe namespace filter. Must name only namespaces the class's ontology belongs to.Required

Body​

ParameterTypeDescriptionRequired
_startIndividualIdsArrayThe IDs of the individuals to start from, in this class or its subclasses. Up to 1000.Required
_hopsArrayThe ordered relationships to follow, each as { "_relationship": "<name>" }. Each hop starts from the individuals the previous hop reached.Required
_filterObjectA filter on the individuals the last hop reaches. It works the same way as in Search individuals and uses the stored field names.Optional
_offsetIntegerThe position to start from.Optional, default is 0
_pageSizeIntegerThe number of individuals per page, up to 200.Optional, default is 100
_sortObjectField 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
_projectionArrayThe 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​

CodeDescription
200Success
400Bad 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.
401Unauthorized
403Forbidden. No INDIVIDUALS_READ grant, or the Item Service refused the call.
404Not Found. A start individual doesn't exist, the class isn't in the live version, or nsfilter names a namespace outside the ontology.
409Conflict. The ontology has no live version, or the live mapping has no collection.
413Payload Too Large. A hop reached more than 1000 individuals.
502Bad Gateway. The Item Service failed or was unreachable.