Skip to main content

Actors Commands

See Actors module docs for permissions and data model.

soat list-actors​

List actors

  • Method: GET
  • Path: /api/v1/actors

Usage​

soat list-actors

Options​

--project-id​

Project ID (optional)

  • Source: query
  • Required: no
  • Type: string
  • Example: proj_V1StGXR8Z5jdHi6B
--external-id​

External ID to filter by (e.g. WhatsApp phone number)

  • Source: query
  • Required: no
  • Type: string
  • Example: +15551234567
--agent-id​

Return only actors linked to this agent

  • Source: query
  • Required: no
  • Type: string
  • Example: agent_V1StGXR8Z5jdHi6B
--chat-id​

Return only actors linked to this chat

  • Source: query
  • Required: no
  • Type: string
  • Example: chat_V1StGXR8Z5jdHi6B
--conversation-id​

Return only actors that participate in this conversation (derived from the conversation's messages).

  • Source: query
  • Required: no
  • Type: string
  • Example: conv_V1StGXR8Z5jdHi6B
--limit​

Maximum number of results to return

  • Source: query
  • Required: no
  • Type: integer
  • Default: 50
--offset​

Number of results to skip

  • Source: query
  • Required: no
  • Type: integer
  • Default: 0

soat create-actor​

Create an actor

  • Method: POST
  • Path: /api/v1/actors

Usage​

soat create-actor --name <string>

Options​

--project-id​

Project ID. Required for JWT auth; omit when using an project key.

  • Source: body
  • Required: no
  • Type: string
  • Example: proj_V1StGXR8Z5jdHi6B
--name​

—

  • Source: body
  • Required: yes
  • Type: string
  • Example: Alice
--external-id​

Optional external identifier (e.g. WhatsApp phone number). If provided and an actor with this externalId already exists in the project, the existing actor is returned (idempotent — 200 OK).

  • Source: body
  • Required: no
  • Type: string
  • Example: +15551234567
--instructions​

Persona-specific instructions composed into the effective system prompt during conversation generation.

  • Source: body
  • Required: no
  • Type: string \| null
--agent-id​

Agent to link this actor to. Mutually exclusive with chat_id.

  • Source: body
  • Required: no
  • Type: string
  • Example: agent_V1StGXR8Z5jdHi6B
--chat-id​

Chat to link this actor to. Mutually exclusive with agent_id.

  • Source: body
  • Required: no
  • Type: string
  • Example: chat_V1StGXR8Z5jdHi6B
--memory-id​

Memory ID to link to this actor. Mutually exclusive with auto_create_memory.

  • Source: body
  • Required: no
  • Type: string \| null
  • Example: mem_V1StGXR8Z5jdHi6B
--auto-create-memory​

When true, automatically creates a new memory container for this actor and links it. Ignored if memory_id is set. With external_id (idempotent), memory is only created on first creation.

  • Source: body
  • Required: no
  • Type: boolean
  • Default: false

soat get-actor​

Get an actor by ID

  • Method: GET
  • Path: /api/v1/actors/{actor_id}

Usage​

soat get-actor --actor-id <string>

Options​

--actor-id​

Actor ID

  • Source: path
  • Required: yes
  • Type: string
  • Example: actor_V1StGXR8Z5jdHi6B

soat delete-actor​

Delete an actor

  • Method: DELETE
  • Path: /api/v1/actors/{actor_id}

Usage​

soat delete-actor --actor-id <string>

Options​

--actor-id​

Actor ID

  • Source: path
  • Required: yes
  • Type: string
  • Example: actor_V1StGXR8Z5jdHi6B

soat update-actor​

Update an actor

  • Method: PATCH
  • Path: /api/v1/actors/{actor_id}

Usage​

soat update-actor --actor-id <string>

Options​

--actor-id​

Actor ID

  • Source: path
  • Required: yes
  • Type: string
  • Example: actor_V1StGXR8Z5jdHi6B
--name​

—

  • Source: body
  • Required: no
  • Type: string
  • Example: Alice Smith
--external-id​

External identifier (e.g. WhatsApp phone number)

  • Source: body
  • Required: no
  • Type: string
  • Example: +15551234567
--instructions​

Persona-specific instructions

  • Source: body
  • Required: no
  • Type: string
--agent-id​

Agent to link this actor to. Mutually exclusive with chat_id.

  • Source: body
  • Required: no
  • Type: string \| null
--chat-id​

Chat to link this actor to. Mutually exclusive with agent_id.

  • Source: body
  • Required: no
  • Type: string \| null
--memory-id​

Memory ID to link to this actor. Set to null to unlink.

  • Source: body
  • Required: no
  • Type: string \| null
  • Example: mem_V1StGXR8Z5jdHi6B
--tags​

—

  • Source: body
  • Required: no
  • Type: object<string, string>

soat get-actor-tags​

Get actor tags

  • Method: GET
  • Path: /api/v1/actors/{actor_id}/tags

Usage​

soat get-actor-tags --actor-id <string>

Options​

--actor-id​

Actor ID

  • Source: path
  • Required: yes
  • Type: string
  • Example: actor_V1StGXR8Z5jdHi6B

soat replace-actor-tags​

Replace actor tags

  • Method: PUT
  • Path: /api/v1/actors/{actor_id}/tags

Usage​

soat replace-actor-tags --actor-id <string>

Options​

--actor-id​

Actor ID

  • Source: path
  • Required: yes
  • Type: string
  • Example: actor_V1StGXR8Z5jdHi6B

soat merge-actor-tags​

Merge actor tags

  • Method: PATCH
  • Path: /api/v1/actors/{actor_id}/tags

Usage​

soat merge-actor-tags --actor-id <string>

Options​

--actor-id​

Actor ID

  • Source: path
  • Required: yes
  • Type: string
  • Example: actor_V1StGXR8Z5jdHi6B