Actors

List actors

Returns all actors in the project named in the path.

get/v1/projects/{project_id}/actors

Request

  • Base URL: https://api.naturali.ai
  • URL: https://api.naturali.ai/v1/projects/{project_id}/actors
  • Auth: one of:
    • HTTP bearer
    • OAuth 2 (authorization code, authorization URL https://api.naturali.ai/authorize, token URL https://api.naturali.ai/token, scopes: mcp:access)

Query parameters

external_idstring
Example:+15551234567

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

namestring
Example:Ada

Case-insensitive substring match on the actor name

agent_idstring
Example:agent_V1StGXR8Z5jdHi6B

Return only actors linked to this agent

chat_idstring
Example:chat_V1StGXR8Z5jdHi6B

Return only actors linked to this chat

conversation_idstring
Example:conv_V1StGXR8Z5jdHi6B

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

tagsstring[]

Filter by tag pairs, written key:value (split on the first colon, so a value may contain colons). Repeat the parameter for several pairs; all must be present with exactly that value.

limitinteger

Results per page, 1 to 100 (default 50). Above 100 it is clamped; below 1 or not an integer it is 400.

offsetinteger

Results to skip. Negative or not an integer it is 400.

Response

List of actors

totalinteger
limitinteger
offsetinteger

Example response

{
  "data": [
    {
      "id": "actor_V1StGXR8Z5jdHi6B",
      "project_id": "proj_V1StGXR8Z5jdHi6B",
      "name": "Alice",
      "external_id": "+15551234567",
      "tags": {
        "team": "finance",
        "env": "prod"
      }
    }
  ]
}

Changes

No recorded changes to this operation across all 1 revision of this API.