Entities API

The Entities API allows you to create, list, and manage entities extracted from memories. Entities represent people, places, organizations, and other named concepts.

Entity Object

Field	Type	Description
`id`	string	Unique entity identifier
`name`	string	Entity name
`type`	string	Entity type (PERSON, ORGANIZATION, LOCATION, etc.)
`description`	string	Optional description
`metadata`	object	Custom metadata
`createdAt`	string	ISO 8601 timestamp
`updatedAt`	string	ISO 8601 timestamp

Entity Types

Type	Description
`PERSON`	A human individual
`ORGANIZATION`	A company, institution, or group
`LOCATION`	A place or geographic location
`PRODUCT`	A product or service
`EVENT`	An event or occurrence
`CONCEPT`	An abstract concept or idea
`OTHER`	Other entity types

Create Entity

Create a new entity.

POST /v1/entities

Request Body

Field	Type	Required	Description
`name`	string	Yes	Entity name
`type`	string	Yes	Entity type
`description`	string	No	Entity description
`metadata`	object	No	Custom metadata

Example Request

curl -X POST https://api.memokit.dev/v1/entities \
  -H "Authorization: Bearer mk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Smith",
    "type": "PERSON",
    "description": "Software engineer and TypeScript enthusiast",
    "metadata": {
      "department": "Engineering",
      "role": "Senior Developer"
    }
  }'

Response

{
  "id": "ent_abc123",
  "name": "John Smith",
  "type": "PERSON",
  "description": "Software engineer and TypeScript enthusiast",
  "metadata": {
    "department": "Engineering",
    "role": "Senior Developer"
  },
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}

List Entities

Retrieve a paginated list of entities.

GET /v1/entities

Query Parameters

Parameter	Type	Required	Description
`type`	string	No	Filter by entity type
`search`	string	No	Search by name
`page`	number	No	Page number (default: 1)
`limit`	number	No	Items per page (default: 20, max: 100)

Example Request

curl -X GET "https://api.memokit.dev/v1/entities?type=PERSON&limit=10" \
  -H "Authorization: Bearer mk_your_api_key"

Response

{
  "items": [
    {
      "id": "ent_abc123",
      "name": "John Smith",
      "type": "PERSON",
      "description": "Software engineer and TypeScript enthusiast",
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    },
    {
      "id": "ent_def456",
      "name": "Jane Doe",
      "type": "PERSON",
      "description": "Product manager",
      "createdAt": "2024-01-14T09:00:00Z",
      "updatedAt": "2024-01-14T09:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 25,
    "totalPages": 3
  }
}

Get Entity

Retrieve a specific entity by ID.

GET /v1/entities/:id

Path Parameters

Parameter	Type	Description
`id`	string	Entity ID

Example Request

curl -X GET https://api.memokit.dev/v1/entities/ent_abc123 \
  -H "Authorization: Bearer mk_your_api_key"

Response

{
  "id": "ent_abc123",
  "name": "John Smith",
  "type": "PERSON",
  "description": "Software engineer and TypeScript enthusiast",
  "metadata": {
    "department": "Engineering",
    "role": "Senior Developer"
  },
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}

Delete Entity

Delete an entity permanently.

DELETE /v1/entities/:id

Path Parameters

Parameter	Type	Description
`id`	string	Entity ID

Example Request

curl -X DELETE https://api.memokit.dev/v1/entities/ent_abc123 \
  -H "Authorization: Bearer mk_your_api_key"

Response

{
  "success": true,
  "id": "ent_abc123"
}

Error Codes

Code	Description
`ENTITY_NOT_FOUND`	The specified entity does not exist
`INVALID_ENTITY_TYPE`	The entity type is not valid
`NAME_REQUIRED`	Entity name is required

Entities API

On this page