Skip to content

Relationship endpoints

The Atlas dataset contains both class relations (such as Service–Server) and object relations (such as Atlas–web-01). The Server–Location class relation allows at most one location per server and any number of servers per location.

This document summarizes the current class-relation, object-relation, and related-resource endpoints.

For filtering, sorting, and cursor pagination support, see:

Context-free relation endpoints

Class relations

Operation Method Path Description
List GET /api/v1/relations/classes List class relations visible to the caller
Get GET /api/v1/relations/classes/{relation_id} Fetch one class relation
Create POST /api/v1/relations/classes Create a class relation
Delete DELETE /api/v1/relations/classes/{relation_id} Delete a class relation

Class relation create payloads accept from_max_relations and to_max_relations. Each is either a positive integer or null; null means unlimited. A limit applies independently to every object in the class on that side of the relation. For example, this allows each jack to relate to at most one room while allowing a room to contain any number of jacks:

{
  "from_hubuum_class_id": 10,
  "to_hubuum_class_id": 20,
  "forward_template_alias": "room",
  "reverse_template_alias": "jacks",
  "from_max_relations": 1,
  "to_max_relations": null
}

Class relations are stored in canonical class-ID order. If the supplied class IDs are reversed during creation, the aliases and limits are reversed with them, so each setting continues to apply to the class supplied on that side. Creating an object relation beyond either limit returns 409 Conflict.

Object relations

Operation Method Path Description
List GET /api/v1/relations/objects List object relations visible to the caller
Get GET /api/v1/relations/objects/{relation_id} Fetch one object relation
Create POST /api/v1/relations/objects Create an object relation
Delete DELETE /api/v1/relations/objects/{relation_id} Delete an object relation

Contextual class endpoints

These endpoints are scoped by the class in the path.

Operation Method Path Description
List connected classes GET /api/v1/classes/{class_id}/related/classes List classes connected to the class
List direct relations GET /api/v1/classes/{class_id}/related/relations List direct relations touching the class
Get neighborhood graph GET /api/v1/classes/{class_id}/related/graph Return the connected-class neighborhood graph
Create relation POST /api/v1/classes/{class_id}/relations Create a relation involving the class
Delete relation DELETE /api/v1/classes/{class_id}/relations/{relation_id} Delete a relation from the class context

These endpoints are scoped by the class and object in the path.

Operation Method Path Description
List connected objects GET /api/v1/classes/{class_id}/objects/{object_id}/related/objects List objects connected to the object; supports ignore_classes and ignore_self_class result filters
List direct relations GET /api/v1/classes/{class_id}/objects/{object_id}/related/relations List direct relations touching the object
Get neighborhood graph GET /api/v1/classes/{class_id}/objects/{object_id}/related/graph Return the connected-object neighborhood graph
Get relation GET /api/v1/classes/{class_id}/{from_object_id}/relations/{to_class_id}/{to_object_id} Fetch the relation between the source and target objects
Create relation POST /api/v1/classes/{class_id}/{from_object_id}/relations/{to_class_id}/{to_object_id} Create a relation between the source and target objects
Delete relation DELETE /api/v1/classes/{class_id}/{from_object_id}/relations/{to_class_id}/{to_object_id} Delete the relation between the source and target objects

Query behavior

All paginated list endpoints above use the shared query interface:

  • filters are parsed from query parameters
  • sorting is done in SQL
  • cursor pagination is done in SQL
  • the current page is returned as a JSON array
  • the next page cursor, when present, is returned in X-Next-Cursor

Field support

The relation endpoints do not all support the same fields:

  • global relation endpoints support relation-centric fields such as id, from_*, to_*, class_relation, created_at, and updated_at
  • connected-class listings support both descendant class aliases like id, name, class_id, collection_id and explicit closure fields like from_name, to_name, from_classes, to_classes, depth, and path
  • connected-object listings support both descendant object aliases like id, name, class_id, collection_id and explicit closure/object-join fields like from_name, to_name, from_json_data, to_json_data, depth, and path
  • direct relation listings support relation-centric fields such as id, from_*, to_*, class_relation, created_at, and updated_at
  • graph responses return classes/objects plus direct relations for the included neighborhood in one response and do not use cursor pagination; limit is a maximum related-node safety bound rather than a page size, include_total has no effect, and X-Total-Count is never returned

GET /api/v1/classes/{class_id}/objects/{object_id}/related/objects also accepts:

  • ignore_classes=1,2,3 to exclude returned objects in the listed classes
  • ignore_self_class=true|false to exclude returned objects in the same class as the root object; defaults to true

These options filter the returned objects only. They do not change the underlying traversal, so deeper objects can still be returned even when an intermediate class is ignored in the result set.

Use query_support_matrix.md for the endpoint-by-endpoint field list.