#Relationships

---

#GET /{o}/{p}/relationships

List relationships

Keyset-paged page of stored relationship rows in this project (origin: "explicit"), including edges whose endpoints come from different import sources. Derived edges are computed rather than stored and cannot be ordered by an immutable key, so they are served whole by GET /relationships/derived.

Auth: Bearer token required · Permission: data:read

Path parameters

Name	Type	Description
o	string
p	string

Query parameters

Name	Type	Description
relationshipType	string	Filter by relationship type
state	string	Filter by state
fromEntity	string(uuid)	Filter by from-entity ID
toEntity	string(uuid)	Filter by to-entity ID
fromEntityCell	string	Filter by from-entity cell membership
toEntityCell	string	Filter by to-entity cell membership
limit	integer	Max results (1-2000)
cursor	string	Keyset cursor from the previous page

Responses

Status	Description	Schema
200	OK	RelationshipPage
401	Unauthorized	Error
403	Forbidden	Error

---

#GET /{o}/{p}/relationships/derived

List derived relationship edges

All derived edges in this project (origin: "derived"), computed from entity properties. Unpaged — derived edges have no immutable ordering key.

Auth: Bearer token required · Permission: data:read

Path parameters

Name	Type	Description
o	string
p	string

Query parameters

Name	Type	Description
relationshipType	string	Filter by relationship type
fromEntity	string(uuid)	Filter by from-entity ID
toEntity	string(uuid)	Filter by to-entity ID

Responses

Status	Description	Schema
200	OK	ResolvedRelationshipList
401	Unauthorized	Error
403	Forbidden	Error

---

#GET /{o}/{p}/relationships/{id}

Get a relationship by id

Auth: Bearer token required · Permission: data:read

Path parameters

Name	Type	Description
id	string(uuid)	Relationship ID
o	string
p	string

Responses

Status	Description	Schema
200	OK	Relationship
401	Unauthorized	Error
403	Forbidden	Error
404	Not Found	Error

---

#POST /{o}/{p}/relationships/{id}/finalize-deletion

Force-finalize a relationship deletion

Skip the remaining grace period and immediately finalize a relationship scheduled for deletion.

Auth: Bearer token required · Permission: relationships:finalize

Path parameters

Name	Type	Description
id	string(uuid)	Relationship ID
o	string
p	string

Request body (application/json)

Field	Type	Description
finalState	string	State to finalize into

Responses

Status	Description	Schema
200	OK	Relationship
401	Unauthorized	Error
403	Forbidden	Error
404	Not Found	Error
409	Conflict	Error

#Schemas

#Error

Field	Type	Description
error	string	(required)
code	string

#Relationship

Field	Type	Description
state	string	(required)
labels	object	(required)
id	string(uuid)	(required)
relationshipTypeName	string	(required)
fromEntityId	string	(required)
toEntityId	string	(required)
orgId	string	(required)
projectId	string	(required)
createdAt	string | string	(required)
updatedAt	string | string	(required)
deletionScheduledAt	string | string | null	(required)
deletionGracePeriodSeconds	integer | null	(required)

#RelationshipPage

Field	Type	Description
items	RelationshipPageRow[]	(required)
nextCursor	string | null	Cursor for the next page; null on the final page (required)

#RelationshipPageRow

Field	Type	Description
state	string	(required)
labels	object	(required)
id	string(uuid)	(required)
relationshipTypeName	string	(required)
fromEntityId	string	(required)
toEntityId	string	(required)
orgId	string	(required)
projectId	string	(required)
createdAt	string | string	(required)
updatedAt	string | string	(required)
deletionScheduledAt	string | string | null	(required)
deletionGracePeriodSeconds	integer | null	(required)
fromEntityName	string	(required)
toEntityName	string	(required)
origin	explicit | derived	(required)

#ResolvedRelationshipList

Type: ResolvedRelationshipListRow[]

#ResolvedRelationshipListRow

Field	Type	Description
id	string(uuid) | null	(required)
relationshipTypeName	string	(required)
fromEntityName	string	(required)
toEntityName	string	(required)
origin	explicit | derived	(required)
state	string | null	(required)
labels	object	(required)
fromEntityId	string | null	(required)
toEntityId	string | null	(required)
orgId	string | null	(required)
projectId	string | null	(required)
createdAt	string | string | null	(required)
updatedAt	string | string | null	(required)
deletionScheduledAt	string | string | null	(required)
deletionGracePeriodSeconds	integer | null	(required)