Skip to main content
Version: v5.3

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:

Every request needs an Authorization: Bearer <token> header. The examples use the namespace myapp.

To create individuals and relationships, complete the following steps:

  1. Create the target individual. Note its _id in the response.

    POST /aosvc/api/v1/classes/{roomClassId}/individuals?nsfilter=myapp

    {
    "_name": "Room 101"
    }

    For more information, see Create individuals.

  2. Create the source individual with its relationship inline. Note its _id in 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.

  3. 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.

  4. List the relationships of the source individual to check them.

    GET /aosvc/api/v1/classes/{pumpClassId}/individuals/{individualId}/relationships?nsfilter=myapp

    For more information, see List the relationships of an individual.

  5. 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.

  6. To remove a relationship, delete it by relationship name and target.

    DELETE /aosvc/api/v1/classes/{pumpClassId}/individuals/{individualId}/relationships/locatedAt/{targetIndividualId}?nsfilter=myapp

    For more information, see Remove a relationship.

Note: To replace all of an individual's relationships, update the individual with a complete _relationships array. For more information, see Update an individual. To load many individuals or relationships at once, see Importing individuals.