Creating individuals and relationships
Creating individuals and relationships
This page shows how to create individuals of a class, relate them to each other, and find individuals by their relationships. For background, see Individuals and Individual relationships.
The examples use a Pump class with a declared locatedAt relationship to a Room class, and a Room class with a partOf relationship to a Floor class.
Before you start, make sure you have the following:
- A live ontology with the classes and their declared relationships. For more information, see Creating an ontology.
- A live collection mapping for each class. For more information, see Mapping a class to a collection.
INDIVIDUALS_CREATE,INDIVIDUALS_READ, andINDIVIDUALS_EDITon the classes. For more information, see Granting permissions.
Every request needs an Authorization: Bearer <token> header. The examples use the namespace myapp.
To create individuals and relationships, complete the following steps:
-
Create the target individual. Note its
_idin the response.POST /aosvc/api/v1/classes/{roomClassId}/individuals?nsfilter=myapp{"_name": "Room 101"}For more information, see Create individuals.
-
Create the source individual with its relationship inline. Note its
_idin the response.POST /aosvc/api/v1/classes/{pumpClassId}/individuals?nsfilter=myapp{"_name": "Pump-A1","properties": {"flowRate": 42.5,"installDate": "2025-06-01T00:00:00Z"},"_relationships": [{"_userType": "locatedAt","_relatedToIds": ["<Room 101 ID>"]}]}Note: If the response is
422, the body lists the constraint violations. Nothing was stored. Fix the data and send it again. -
To relate an existing individual, add a relationship from it.
POST /aosvc/api/v1/classes/{pumpClassId}/individuals/{individualId}/relationships?nsfilter=myapp{"_userType": "locatedAt","_relatedToIds": ["<Room ID>"],"_customAttributes": { "installedBy": "crew-7" }}For more information, see Add relationships from an individual.
-
List the relationships of the source individual to check them.
GET /aosvc/api/v1/classes/{pumpClassId}/individuals/{individualId}/relationships?nsfilter=myappFor more information, see List the relationships of an individual.
-
To find individuals by their relationships, traverse from a start individual.
POST /aosvc/api/v1/classes/{pumpClassId}/individuals/traverse?nsfilter=myapp{"_startIndividualIds": ["<Pump-A1 ID>"],"_hops": [{ "_relationship": "locatedAt" },{ "_relationship": "partOf" }],"_pageSize": 20}For more information, see Traverse relationships between individuals.
-
To remove a relationship, delete it by relationship name and target.
DELETE /aosvc/api/v1/classes/{pumpClassId}/individuals/{individualId}/relationships/locatedAt/{targetIndividualId}?nsfilter=myappFor more information, see Remove a relationship.
Note: To replace all of an individual's relationships, update the individual with a complete
_relationshipsarray. For more information, see Update an individual. To load many individuals or relationships at once, see Importing individuals.