Relations

Relations link entities together, similar to foreign keys in a relational database. A relation connects a source entity to a target entity with a typed relationship. For example, a contact entity can be linked to a company entity via a works_at relation.

Relations can carry optional metadata to store additional context about the link (e.g. a job title on a works_at relation).

GET/core/api/v1/entities/{id}/relations

List entity relations

Retrieve all relations for a given entity. This returns both outgoing relations (where the entity is the source) and incoming relations (where the entity is the target).

Path parameters

Name
id
Type
string
Description
The unique identifier of the entity.

Response fields

Name
id
Type
string
Description
The unique identifier of the relation.
Name
source_entity_id
Type
string
Description
The ID of the source entity in the relation.
Name
target_entity_id
Type
string
Description
The ID of the target entity in the relation.
Name
relation_type
Type
string
Description
The type of relationship (e.g. works_at, belongs_to, parent_of).
Name
metadata
Type
object
Description
Optional metadata attached to the relation.

GET

/core/api/v1/entities/{id}/relations

curl https://your-sphere.example.com/core/api/v1/entities/ent-1a2b3c4d-5e6f-7890-abcd-ef1234567890/relations \
  -H "Authorization: Bearer {token}"

Response

{
  "data": [
    {
      "id": "rel-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "source_entity_id": "ent-1a2b3c4d-5e6f-7890-abcd-ef1234567890",
      "target_entity_id": "ent-9f8e7d6c-5b4a-3210-fedc-ba0987654321",
      "relation_type": "works_at",
      "metadata": {
        "job_title": "Software Engineer",
        "since": "2025-03-01"
      }
    },
    {
      "id": "rel-b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "source_entity_id": "ent-1a2b3c4d-5e6f-7890-abcd-ef1234567890",
      "target_entity_id": "ent-4d5e6f7a-8b9c-0d1e-2f3a-4b5c6d7e8f90",
      "relation_type": "assigned_to",
      "metadata": null
    }
  ]
}

POST/core/api/v1/entities/{id}/relations

Create relation

Create a new relation linking the source entity to a target entity. The relation type defines the nature of the link.

Path parameters

Name
id
Type
string
Description
The unique identifier of the source entity.

Request body

Name
target_entity_id
Type
string
Description
The ID of the entity to link to.
Name
relation_type
Type
string
Description
The type of relationship (e.g. works_at, belongs_to, parent_of).
Name
metadata
Type
object
Description
Optional metadata to attach to the relation. Can be any JSON object.

POST

/core/api/v1/entities/{id}/relations

curl -X POST https://your-sphere.example.com/core/api/v1/entities/ent-1a2b3c4d-5e6f-7890-abcd-ef1234567890/relations \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "target_entity_id": "ent-9f8e7d6c-5b4a-3210-fedc-ba0987654321",
    "relation_type": "works_at",
    "metadata": {
      "job_title": "CTO",
      "since": "2026-01-15"
    }
  }'

Response

{
  "data": {
    "id": "rel-c3d4e5f6-a7b8-9012-cdef-234567890abc",
    "source_entity_id": "ent-1a2b3c4d-5e6f-7890-abcd-ef1234567890",
    "target_entity_id": "ent-9f8e7d6c-5b4a-3210-fedc-ba0987654321",
    "relation_type": "works_at",
    "metadata": {
      "job_title": "CTO",
      "since": "2026-01-15"
    }
  }
}

DELETE/core/api/v1/entities/{id}/relations/{relationId}

Delete relation

Remove a relation (unlink) between two entities. This does not delete either entity -- it only removes the link between them.

Path parameters

Name
id
Type
string
Description
The unique identifier of the source entity.
Name
relationId
Type
string
Description
The unique identifier of the relation to remove.

DELETE

/core/api/v1/entities/{id}/relations/{relationId}

curl -X DELETE https://your-sphere.example.com/core/api/v1/entities/ent-1a2b3c4d-5e6f-7890-abcd-ef1234567890/relations/rel-a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer {token}"

Response

{
  "message": "Relation removed successfully"
}