Create Actor - MemoryLake AI

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",
    "metadata": {
      "tier": "premium",
      "region": "us-west"
    }
  }'

{
  "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",
    "metadata": {
      "tier": "premium",
      "region": "us-west"
    },
    "created_at": "2025-03-10T08:00:00Z",
    "updated_at": "2025-03-10T08:00:00Z"
  }
}

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

custom_id

string

required

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

actor_type

string

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

display_name

string

required

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

description

string

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

metadata

object

Arbitrary key-value pairs for caller-defined metadata. Useful for tagging actors with attributes such as tier, region, or department.

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",
    "metadata": {
      "tier": "premium",
      "region": "us-west"
    }
  }'

Response

data

object

Show Actor

string

Actor ID

custom_id

string

Caller-defined external identifier

actor_type

string

Actor type: HUMAN or ASSISTANT

display_name

string

Human-readable display name

description

string

Actor description

metadata

object

Caller-defined metadata

created_at

string

Creation timestamp

updated_at

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",
    "metadata": {
      "tier": "premium",
      "region": "us-west"
    },
    "created_at": "2025-03-10T08:00:00Z",
    "updated_at": "2025-03-10T08:00:00Z"
  }
}

List Actors Get Actor

​Request Body

​Response

Request Body

Response