Entities API

Extract, manage, and query named entities from your memories to build a knowledge graph.

Updated Oct 6, 2026

Overview

Entities are named things (people, organizations, places, etc.) automatically extracted from your memories. They form the nodes of a knowledge graph that connects related information across your entire memory store.

Automatic Extraction: Entities are extracted automatically when memories are created. You can also manually trigger extraction or add custom entities.

List Entities

Endpoint

GET /knowledge/entities

Returns entities extracted from your memories, optionally filtered by type.

Query Parameters

Field	Type	Description
space_id	string	Space UUID (for hub-scoped accounts).
type	string	Filter by entity type (see the entity-types table below).
limit	integer	Maximum entities to return. Default: 100, Max: 200.
offset	integer	Offset for pagination. Default: 0.

Response (200)

Example Response

{
  "entities": [
    {
      "id": "<uuid>",
      "name": "John Smith",
      "type": "person",
      "created_at": "2026-04-05T09:00:00Z"
    },
    {
      "id": "<uuid>",
      "name": "Sarah Johnson",
      "type": "person",
      "created_at": "2026-04-07T14:00:00Z"
    }
  ],
  "total": 2,
  "limit": 10,
  "offset": 0,
  "has_more": false
}

Count entities by countable category

Endpoint

GET /knowledge/entities/count

Returns the number of entities in a countable category, optionally within a time window.

Query Parameters

Field	Type	Description
countable_category	string (required)	Countable category (e.g. `person`).
time_start	string	Optional ISO 8601 lower bound.
time_end	string	Optional ISO 8601 upper bound.

List entities valid at a point in time

Endpoint

GET /knowledge/entities/at-time

Bi-temporal query: returns entities that were valid at the given point in time.

Query Parameters

Field	Type	Description
as_of	string	ISO 8601 timestamp. Defaults to now.
type	string	Filter by entity type.
limit	integer	Maximum entities to return. Default: 100, Max: 200.

Get Entity

Endpoint

GET /knowledge/entities/:id

Retrieves an entity along with its relationship and fact counts.

Path Parameters

Field	Type	Description
id	string (required)	The entity UUID.

Response (200)

Example Response

{
  "entity": {
    "id": "<uuid>",
    "name": "John Smith",
    "type": "person",
    "relationship_count": 5,
    "fact_count": 12,
    "created_at": "2026-04-05T09:00:00Z",
    "updated_at": "2026-04-12T16:30:00Z"
  },
  "relationships": [],
  "facts": []
}

Get bi-temporal entity history

Endpoint

GET /knowledge/entities/:id/timeline

Returns a timeline of changes for the entity.

Get Entity Relationships

Endpoint

GET /knowledge/entities/:id/relationships

Returns all relationships for a specific entity.

Path Parameters

Field	Type	Description
id	string (required)	The entity UUID.

Query Parameters

Field	Type	Description
direction	string	Relationship direction: `outgoing`, `incoming`, or `both` (default).
session_id	string	Filter relationships by session UUID.

Response (200)

Example Response

{
  "entity_id": "<uuid>",
  "relationships": [
    {
      "target_entity_id": "<uuid>",
      "target_name": "Acme Corp",
      "target_type": "organization",
      "relationship_type": "works_at",
      "weight": 0.95
    }
  ],
  "total": 1
}

Get Entity Facts

Endpoint

GET /knowledge/entities/:id/facts

Returns facts that reference the entity.

Path Parameters

Field	Type	Description
id	string (required)	The entity UUID.

Query Parameters

Field	Type	Description
limit	integer	Maximum facts to return. Default: 50, Max: 200.

Merge Entities

Endpoint

POST /knowledge/entities/merge

Merges a source entity into a target entity. The source is invalidated; the target absorbs its relationships and facts.

Body Parameters

Field	Type	Description
source_id	string (required)	Entity UUID to merge from (will be invalidated).
target_id	string (required)	Entity UUID to merge into (will be updated).
space_id	string	Space UUID (for hub-scoped accounts).

Response (200)

Example Response

{
  "merged": true,
  "target_id": "<uuid>",
  "source_id": "<uuid>"
}

Warning: Merging invalidates the source entity. This cannot be undone.

Entity Subgraph & Path

N-hop subgraph around an entity

Endpoint

GET /knowledge/graph/subgraph/:entityId

Returns the neighborhood around an entity up to hops hops.

Path Parameters

Field	Type	Description
entityId	string (required)	Center entity UUID.

Query Parameters

Field	Type	Description
hops	integer	Number of hops. Default: 2, Max: 5.
includeRelationships	boolean	Include relationship edges. Default: true.

Shortest path between two entities

Endpoint

GET /knowledge/graph/path

Finds the shortest path between two entities in the knowledge graph.

Query Parameters

Field	Type	Description
from	string (required)	Starting entity UUID.
to	string (required)	Target entity UUID.
maxHops	integer	Max path length. Default: 5, Max: 10.

Entity Object

The entity object contains the following fields:

Field	Type	Description
id	string	UUID identifier for the entity.
name	string	The primary name of the entity.
type	string	Entity type (see the enum below).
relationship_count	integer	Number of active relationships on this entity. Populated by `GET /knowledge/entities/:id`.
fact_count	integer	Number of active facts that reference this entity. Populated by `GET /knowledge/entities/:id`.
created_at	string	ISO 8601 timestamp of when the entity was first extracted.
updated_at	string	ISO 8601 timestamp of when the entity was last updated.

Entity Types

Trix recognizes the following entity types:

Type	Description	Examples
`person`	Individual people	Colleagues, friends, contacts
`organization`	Companies, teams, groups	Acme Corp, Engineering Team
`location`	Places and addresses	San Francisco, Office Building A
`product`	Products, tools, software	Slack, PostgreSQL, iPhone
`concept`	Abstract concepts and topics	Machine Learning, Agile
`event`	Meetings, conferences, milestones	Q4 Planning, Product Launch
`skill`	Technologies, abilities	Python, Project Management
`date`	Dates and time periods	January 2024, Last Quarter

Relationship Types

Common relationship types between entities:

Type	Description
`works_at`	Person works at an organization
`reports_to`	Person reports to another person
`collaborates_with`	Two entities work together
`located_in`	Entity is located at a location
`uses`	Entity uses a product or skill
`knows`	Person knows another person
`part_of`	Entity is part of another entity
`related_to`	General relationship