API reference · 4 endpoints

Entities

Entities extracted from memories and the graph that connects them.

GET/v1/default/namespaces/{namespace_id}/entities

List entities

List all entities (people, organizations, etc.) known by the namespace, ordered by mention count. Supports pagination.

Parameters

namespace_idstringpathrequired
limitintegerquery

Maximum number of entities to return

offsetintegerquery

Offset for pagination

classstring | nullquery

Keep only entities assigned to this ontology class (case-insensitive).

relationstring | nullquery

Keep only entities on either end of this ontology relation (case-insensitive).

curl -X GET "https://api.illumina.sh/v1/default/namespaces/demo/entities" \
  -H "Authorization: Bearer $ILLUMINA_API_KEY"
Response · 200
{
  "items": [
    {
      "canonical_name": "John",
      "first_seen": "2024-01-15T10:30:00Z",
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "last_seen": "2024-02-01T14:00:00Z",
      "mention_count": 15
    }
  ],
  "limit": 100,
  "offset": 0,
  "total": 150
}

400 · 401 · 402 · 403 · 404 · 405 · 409 · 410 · 422see error reference

GET/v1/default/namespaces/{namespace_id}/entities/graph

Get entity co-occurrence graph

Return a graph of entities (nodes) and their co-occurrences (edges) for visualization.

Parameters

namespace_idstringpathrequired
limitintegerquery

Maximum number of co-occurrence edges to return

min_countintegerquery

Minimum cooccurrence_count to include an edge

curl -X GET "https://api.illumina.sh/v1/default/namespaces/demo/entities/graph" \
  -H "Authorization: Bearer $ILLUMINA_API_KEY"
Response · 200
{
  "edges": [
    {
      "data": {
        "color": "#ffd700",
        "id": "uuid-1-uuid-2",
        "lastCooccurred": "2024-02-01T14:00:00Z",
        "lineStyle": "solid",
        "linkType": "cooccurrence",
        "source": "uuid-1",
        "target": "uuid-2",
        "weight": 5
      }
    }
  ],
  "limit": 1000,
  "nodes": [
    {
      "data": {
        "color": "#42a5f5",
        "id": "uuid-1",
        "label": "Alice",
        "mentionCount": 12
      }
    },
    {
      "data": {
        "color": "#42a5f5",
        "id": "uuid-2",
        "label": "Google",
        "mentionCount": 8
      }
    }
  ],
  "total_edges": 1,
  "total_entities": 2
}

400 · 401 · 402 · 403 · 404 · 405 · 409 · 410 · 422see error reference

GET/v1/default/namespaces/{namespace_id}/entities/{entity_id}

Get entity details

Get detailed information about an entity including signals (automation).

Parameters

namespace_idstringpathrequired
entity_idstringpathrequired
curl -X GET "https://api.illumina.sh/v1/default/namespaces/demo/entities/ent_123" \
  -H "Authorization: Bearer $ILLUMINA_API_KEY"
Response · 200
{
  "canonical_name": "John",
  "first_seen": "2024-01-15T10:30:00Z",
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "last_seen": "2024-02-01T14:00:00Z",
  "mention_count": 15,
  "signals": [
    {
      "mentioned_at": "2024-01-15T10:30:00Z",
      "text": "John works at Google"
    }
  ]
}

400 · 401 · 402 · 403 · 404 · 405 · 409 · 410 · 422see error reference

POST/v1/default/namespaces/{namespace_id}/entities/{entity_id}/regeneratedeprecated

Regenerate entity signals (deprecated)

This endpoint is deprecated. Entity signals have been replaced by automations.

Parameters

namespace_idstringpathrequired
entity_idstringpathrequired
curl -X POST "https://api.illumina.sh/v1/default/namespaces/demo/entities/ent_123/regenerate" \
  -H "Authorization: Bearer $ILLUMINA_API_KEY"
Response · 200
{
  "canonical_name": "John",
  "first_seen": "2024-01-15T10:30:00Z",
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "last_seen": "2024-02-01T14:00:00Z",
  "mention_count": 15,
  "signals": [
    {
      "mentioned_at": "2024-01-15T10:30:00Z",
      "text": "John works at Google"
    }
  ]
}

400 · 401 · 402 · 403 · 404 · 405 · 409 · 410 · 422see error reference

Search docs

Search the documentation