List, inspect, create, and update relationships

Use list_relationships for bounded summaries and get_relationship for one selected owned record. create_relationship validates that both endpoint IDs belong to the connected account and requires an idempotency key. update_relationship accepts a partial patch but revalidates the complete relationship before saving. No relationship deletion tool is registered in this non-destructive slice.

Request and response shapes

Input shape

{ entity?: { kind: 'person' | 'place' | 'event'; id: string }; limit?: number } | { relationshipId: string } | { idempotencyKey: string; leftEntity: EntityRef; rightEntity: EntityRef; relationshipType: string }

Output shape

{ relationships: RelationshipSummary[] } | { relationship: SafeRelationship; created?: boolean }

Examples

Request example

{
  "idempotencyKey": "relationship-ada-grace-2026",
  "leftEntity": {
    "kind": "person",
    "id": "person_ada"
  },
  "rightEntity": {
    "kind": "person",
    "id": "person_grace"
  },
  "relationshipType": "collaborator"
}

Response example

{
  "relationship": {
    "relationshipLabel": "collaborator"
  },
  "created": true
}

Common validation errors

Relationship reads and writes require their matching minimum OAuth scope.
Both relationship endpoints must be owned by the connected account.

List, inspect, create, and update relationships

Request and response shapes

Input shape

{ entity?: { kind: 'person' | 'place' | 'event'; id: string }; limit?: number } | { relationshipId: string } | { idempotencyKey: string; leftEntity: EntityRef; rightEntity: EntityRef; relationshipType: string }

Output shape

{ relationships: RelationshipSummary[] } | { relationship: SafeRelationship; created?: boolean }

Examples

Request example

{
  "idempotencyKey": "relationship-ada-grace-2026",
  "leftEntity": {
    "kind": "person",
    "id": "person_ada"
  },
  "rightEntity": {
    "kind": "person",
    "id": "person_grace"
  },
  "relationshipType": "collaborator"
}

Response example

{
  "relationship": {
    "relationshipLabel": "collaborator"
  },
  "created": true
}

Common validation errors

Relationship reads and writes require their matching minimum OAuth scope.
Both relationship endpoints must be owned by the connected account.

List, inspect, create, and update relationships

Request and response shapes

Input shape

Output shape

Examples

Request example

Response example

Common validation errors

Related questions

List, inspect, create, and update relationships

Request and response shapes

Input shape

Output shape

Examples

Request example

Response example

Common validation errors

Related questions