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
--name​

Case-insensitive substring match on the actor name

  • Source: query
  • Required: no
  • Type: string
  • Example: Ada
--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

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

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
--tags​

—

  • Source: body
  • Required: no
  • Type: unknown

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> --tags <object>

Options​

--actor-id​

Actor ID

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

Key-value labels on a resource. A flat object of string values — an array, a nested object or a number is rejected with 400 VALIDATION_FAILED, never coerced. Keys are opaque and stored verbatim, so cost_center and costCenter are two different tags. Matched by JSONB containment wherever tags are read: the ?tags= filter, knowledge search, and the IAM soat:ResourceTag/<key> condition. Keys beginning system. are reserved: the platform writes them to record which conversation, actor, agent and role a row came from, and a write naming one is refused with 400 RESERVED_TAG_KEY. They are read and filtered like any other tag. The bag is bounded, because every pair reaches the IAM context of every access check on the resource: at most 50 keys, each key at most 128 characters and each value at most 256. A write past a bound — including a merge that would grow the stored bag past the key count — is 400 VALIDATION_FAILED with meta.limit naming the bound it crossed. system.* keys are the platform's and do not count against the 50.

  • Source: body
  • Required: yes
  • Type: object

soat merge-actor-tags​

Merge actor tags

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

Usage​

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

Options​

--actor-id​

Actor ID

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

Key-value labels on a resource. A flat object of string values — an array, a nested object or a number is rejected with 400 VALIDATION_FAILED, never coerced. Keys are opaque and stored verbatim, so cost_center and costCenter are two different tags. Matched by JSONB containment wherever tags are read: the ?tags= filter, knowledge search, and the IAM soat:ResourceTag/<key> condition. Keys beginning system. are reserved: the platform writes them to record which conversation, actor, agent and role a row came from, and a write naming one is refused with 400 RESERVED_TAG_KEY. They are read and filtered like any other tag. The bag is bounded, because every pair reaches the IAM context of every access check on the resource: at most 50 keys, each key at most 128 characters and each value at most 256. A write past a bound — including a merge that would grow the stored bag past the key count — is 400 VALIDATION_FAILED with meta.limit naming the bound it crossed. system.* keys are the platform's and do not count against the 50.

  • Source: body
  • Required: yes
  • Type: object