Get Entity

POST /agent/entity

Get everything SharedMemory knows about a specific entity — summary, facts, and relationships.

Request

Body:

Field	Type	Required	Description
entity_name	string	Yes	Entity name (1–500 chars)
volume_id	string (UUID)	Yes	Volume ID

Response

{
  "name": "John Smith",
  "type": "person",
  "summary": "CTO of Acme Corp since 2022. Expert in distributed systems.",
  "facts": [
    {
      "content": "John Smith is the CTO of Acme Corp",
      "category": "role",
      "importance": 0.95
    },
    {
      "content": "John joined Acme Corp in 2022",
      "category": "timeline",
      "importance": 0.8
    }
  ],
  "summaries": [
    {
      "content": "CTO of Acme Corp since 2022...",
      "version": 3
    }
  ],
  "relationships": [
    {
      "name": "Acme Corp",
      "type": "organization",
      "rel_type": "WORKS_AT",
      "direction": "outgoing"
    },
    {
      "name": "Engineering Team",
      "type": "team",
      "rel_type": "LEADS",
      "direction": "outgoing"
    }
  ]
}

Example

curl -X POST https://api.sharedmemory.ai/agent/entity \
  -H "Authorization: Bearer sm_agent_..." \
  -H "Content-Type: application/json" \
  -d '{
    "entity_name": "John Smith",
    "volume_id": "a1b2c3d4-..."
  }'

Errors

Status	Error	Description
400	validation_failed	Invalid input
404	entity_not_found	No entity with that name in the volume