POST /v1/tenants/{tenant_id}/data/relationships/readThe Read Relationships endpoint queries the stored relationship graph and returns matching tuples. Use filters to narrow results by entity type, entity IDs, relation name, and/or subject. Results are paginated.
Path Parameters The tenant identifier. Use t1 for single-tenant deployments. Must match ^([a-zA-Z0-9_\-@\.:+]{1,128}|\*)$.
Request Body Snap token for consistent reads. Leave empty to read the latest state.
Criteria for selecting which tuples to return. Filter by entity type and/or IDs. Entity type to filter on (e.g. organization).
List of entity IDs to include.
Relation name to filter on (e.g. member).
Filter by subject type, IDs, and/or relation. List of subject IDs to include.
Number of tuples to return per page. Must be >= 1.
Pagination token from a previous response. Omit for the first page.
Response The list of relationship tuples matching the filter. The resource entity (type and id).
The subject (type, id, optional relation).
Pagination token for the next page. Empty when there are no more results.
Example curl --location --request POST 'localhost:3476/v1/tenants/{tenant_id}/data/relationships/read' \ --header 'Content-Type: application/json' \ --data-raw '{ "metadata": { "snap_token": "" }, "filter": { "entity": { "type": "organization", "ids": ["1"] }, "relation": "member", "subject": { "type": "", "ids": [], "relation": "" } } }'
Request body { "metadata" : { "snap_token" : "" }, "filter" : { "entity" : { "type" : "organization" , "ids" : [ "1" ] }, "relation" : "member" , "subject" : { "type" : "" , "ids" : [], "relation" : "" } } }
Response { "tuples" : [ { "entity" : { "type" : "organization" , "id" : "1" }, "relation" : "member" , "subject" : { "type" : "user" , "id" : "3" , "relation" : "" } }, { "entity" : { "type" : "organization" , "id" : "1" }, "relation" : "member" , "subject" : { "type" : "user" , "id" : "7" , "relation" : "" } } ], "continuous_token" : "" }
Error Codes HTTP Status Description 400Bad request — invalid filter fields 401Unauthorized 404Tenant not found 429Rate limit exceeded 500Internal server error
