Create Actor

POST /openapi/memorylake/api/v3/actors

Creates a new actor. Actors represent participants in conversations — typically end users or system identities whose interactions generate memories. After creating an actor, you can bind it to a workspace so it can participate in conversations within that workspace’s projects.

Permission required: actor:create

Request Body

string

required

Caller-defined external identifier. Must be unique across your account. Use this to map actors to identities in your own system.

string

Actor type. Accepted values: HUMAN (default, an end user) or ASSISTANT (an AI agent — typically auto-created when you create an Agent).

string

required

Human-readable name shown in the console and returned in API responses.

string

Free-text description of the actor’s role or purpose.

string[]

Labels used to group and filter actors, for example vip or cn. Duplicates are removed and surrounding whitespace is trimmed. Matching is exact and case-sensitive, so VIP and vip are two different tags. Up to 20 tags per actor, each at most 64 characters, and a tag may not contain a comma.

object

Arbitrary key-value pairs for caller-defined metadata, such as tier, region, or department. Metadata cannot be filtered on — use tags for attributes you want to search by.

curl -X POST 'https://app.memorylake.ai/openapi/memorylake/api/v3/actors' \
  -H 'Authorization: Bearer sk_xxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "custom_id": "user-ext-001",
    "actor_type": "HUMAN",
    "display_name": "Alice Chen",
    "description": "Primary end user for the mobile app",
    "tags": ["vip", "cn"],
    "metadata": {
      "tier": "premium",
      "region": "us-west"
    }
  }'

Response

object

Show Actor

string

Actor ID

string

Caller-defined external identifier

string

Actor type: HUMAN or ASSISTANT

string

Human-readable display name

string

Actor description

string[]

Labels attached to the actor. Empty when the actor has none

object

Caller-defined metadata

string

Creation timestamp

string

Last update timestamp

{
  "success": true,
  "data": {
    "id": "act-a1b2c3d4e5f6",
    "custom_id": "user-ext-001",
    "actor_type": "HUMAN",
    "display_name": "Alice Chen",
    "description": "Primary end user for the mobile app",
    "tags": ["vip", "cn"],
    "metadata": {
      "tier": "premium",
      "region": "us-west"
    },
    "created_at": "2025-03-10T08:00:00Z",
    "updated_at": "2025-03-10T08:00:00Z"
  }
}

MemoryLake API

Management API

Request Body

Response

​Request Body

​Response

Request Body

Response