Entities

GET

/v1/entities

Get all extracted entities from your memories. Entities are named things like people, companies, products, and concepts.

Query Parameters

Parameter	Type	Required	Description
`limit`	number	No	Max entities to return (default: 50)
`offset`	number	No	Pagination offset
`type`	string	No	Filter by entity type
`search`	string	No	Search entity names
`sortBy`	string	No	Sort field: `mentions`, `name`, `recent`

Examples

Get All Entities

curl https://api.hypersave.io/v1/entities \
  -H "Authorization: Bearer YOUR_API_KEY"

Filter by Type

curl "https://api.hypersave.io/v1/entities?type=person&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

Search Entities

curl "https://api.hypersave.io/v1/entities?search=acme" \
  -H "Authorization: Bearer YOUR_API_KEY"

Sort by Mentions

curl "https://api.hypersave.io/v1/entities?sortBy=mentions&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "success": true,
  "entities": [
    {
      "id": "entity_abc123",
      "name": "John Smith",
      "type": "person",
      "aliases": ["J. Smith", "John S."],
      "properties": {
        "title": "CEO",
        "company": "Acme Corp",
        "email": "john@acme.com"
      },
      "mentions": 45,
      "firstSeen": "2024-01-05T09:00:00Z",
      "lastSeen": "2024-01-20T14:30:00Z",
      "relatedDocuments": ["doc_abc", "doc_xyz", "doc_def"]
    },
    {
      "id": "entity_xyz789",
      "name": "Acme Corp",
      "type": "company",
      "aliases": ["Acme", "Acme Corporation"],
      "properties": {
        "industry": "Technology",
        "founded": "2010",
        "location": "San Francisco"
      },
      "mentions": 67,
      "firstSeen": "2024-01-03T10:15:00Z",
      "lastSeen": "2024-01-20T16:00:00Z"
    }
  ],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "total": 156
  },
  "stats": {
    "person": 45,
    "company": 23,
    "product": 34,
    "concept": 54
  }
}

Entity Fields

Field	Type	Description
`id`	string	Unique entity identifier
`name`	string	Primary entity name
`type`	string	Entity type
`aliases`	string[]	Alternative names
`properties`	object	Extracted properties
`mentions`	number	Total mention count
`firstSeen`	string	First appearance timestamp
`lastSeen`	string	Most recent mention
`relatedDocuments`	string[]	Document IDs mentioning this entity

Entity Types

Type	Description
`person`	Individual people
`company`	Organizations and businesses
`product`	Products and services
`concept`	Ideas, topics, technologies
`location`	Places and addresses
`event`	Events and meetings
`date`	Specific dates and times

Entities are automatically merged when aliases are detected. For example, "J. Smith" and "John Smith" will be recognized as the same entity.

Error Responses

Invalid Type

{
  "success": false,
  "error": "VALIDATION_ERROR",
  "message": "Invalid entity type: unknown"
}

Invalid Sort Field

{
  "success": false,
  "error": "VALIDATION_ERROR",
  "message": "Invalid sortBy value. Must be: mentions, name, or recent"
}

Facts Ingest