Entities API

Query and list entities extracted from memories.

Overview

When you create memories with extract_entities: true, the API automatically extracts structured entities like people, organizations, locations, skills, and products. The Entities API lets you query and browse these entities.

Entity Types

Type	Description	Examples
PERSON	People's names	Alice, John Smith
ORG	Organizations and companies	Google, Acme Corp, MIT
LOCATION	Places and locations	San Francisco, Japan, NYC
SKILL	Skills and technologies	Python, Machine Learning, React
PRODUCT	Products and tools	iPhone, AWS, PostgreSQL

---

List All Entities

Get all unique entities across your memories.

GET /v1/entities

Query Parameters

Parameter	Type	Description
type	string	Filter by entity type (PERSON, ORG, etc.)

Example

curl https://memoryapi.tensorheart.com/v1/entities \
  -H "Authorization: Bearer $API_KEY"

Response

{
  "success": true,
  "data": {
    "entities": [
      {"name": "Alice", "type": "PERSON", "memory_count": 5},
      {"name": "Python", "type": "SKILL", "memory_count": 8},
      {"name": "Acme Corp", "type": "ORG", "memory_count": 3}
    ],
    "total": 3
  }
}

---

List Entities by Type

Get all entities of a specific type.

GET /v1/entities/{type}

Path Parameters

Parameter	Type	Description
type	string	Entity type: PERSON, ORG, LOCATION, SKILL, or PRODUCT

Example

curl https://memoryapi.tensorheart.com/v1/entities/SKILL \
  -H "Authorization: Bearer $API_KEY"

Response

{
  "success": true,
  "data": {
    "entities": [
      {"name": "Python", "type": "SKILL", "memory_count": 8},
      {"name": "JavaScript", "type": "SKILL", "memory_count": 4},
      {"name": "Machine Learning", "type": "SKILL", "memory_count": 2}
    ],
    "total": 3
  }
}

---

Get Memories for Entity

Get all memories containing a specific entity.

GET /v1/entities/{type}/{name}/memories

Path Parameters

Parameter	Type	Description
type	string	Entity type
name	string	Entity name (case-insensitive)

Example

curl https://memoryapi.tensorheart.com/v1/entities/PERSON/Alice/memories \
  -H "Authorization: Bearer $API_KEY"

Response

{
  "success": true,
  "data": [
    {
      "id": "mem_abc123",
      "text": "Alice works at Acme Corp as a senior engineer",
      "entities": {
        "PERSON": ["Alice"],
        "ORG": ["Acme Corp"]
      },
      "created_at": "2024-01-15T10:30:00Z"
    },
    {
      "id": "mem_def456",
      "text": "Alice has 6 years of Python experience",
      "entities": {
        "PERSON": ["Alice"],
        "SKILL": ["Python"]
      },
      "created_at": "2024-01-16T14:00:00Z"
    }
  ]
}

---

Use Cases

Building a Contact Graph

Use the entities API to understand relationships:

# Get all people mentioned in memories
curl https://memoryapi.tensorheart.com/v1/entities/PERSON

# Get all memories about a specific person
curl https://memoryapi.tensorheart.com/v1/entities/PERSON/Alice/memories

Skills Inventory

Track skills and technologies:

# List all skills
curl https://memoryapi.tensorheart.com/v1/entities/SKILL

# Find memories about Python
curl https://memoryapi.tensorheart.com/v1/entities/SKILL/Python/memories

Organization Mapping

Understand organizational relationships:

# List all organizations
curl https://memoryapi.tensorheart.com/v1/entities/ORG

# Find memories about a specific company
curl https://memoryapi.tensorheart.com/v1/entities/ORG/Acme%20Corp/memories