Get Multiple AI Agents

Used to retrieve a list of AI agents based on specified query parameters, such as pagination (limit and offset) and filtering criteria. This endpoint uses a POST request for queries to allow for more complex body structures.

API Endpoint

Property	Value
Request Method	POST
Request URL	https://api.seliseblocks.com/agents/queries

Request

Request Example

curl -X POST 'https://api.seliseblocks.com/agents/queries' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "agent_type": "customer_support",
    "name": "Support Agent",
    "organization_ids": ["org_123", "org_456"],
    "widget_id": "widget_789",
    "languages": "en-US",
    "tags": ["support", "customer-service"],
    "role": "assistant",
    "is_disabled": false,
    "is_archived": false,
    "limit": 50,
    "offset": 0,
    "project_key": "YOUR_PROJECT_KEY"
  }'

Request Headers

Field	Type	Required	Description
accept	string	Yes	Accepted response format. Use application/json
Content-Type	application/json	Yes	Data type, must be application/json.

Request Body

Request Body Schema

{
  "agent_type": "string",
  "name": "string",
  "organization_ids": ["string"],
  "widget_id": "string",
  "languages": "string",
  "tags": ["string"],
  "role": "string",
  "is_disabled": true,
  "is_archived": true,
  "limit": 100,
  "offset": 0,
  "project_key": "string"
}

Request Body Parameters

Field	Type	Required	Description
agent_type	string	No	Filter by agent type (e.g., customer_support, sales).
name	string	No	Filter by agent name (partial match supported).
organization_ids	array	No	Filter by organization identifiers.
widget_id	string	No	Filter by widget identifier.
languages	string	No	Filter by supported languages (e.g., en-US, de-DE).
tags	array	No	Filter by tags associated with agents.
role	string	No	Filter by agent role (e.g., assistant, specialist).
is_disabled	boolean	No	Filter by disabled status. true returns only disabled agents, false returns only active agents.
is_archived	boolean	No	Filter by archived status. true returns only archived agents, false returns only non-archived agents.
limit	integer	No	Maximum number of agents to return. Default: 100.
offset	integer	No	Number of agents to skip for pagination. Default: 0.
project_key	string	Yes	The project key for your project.

note

All filter parameters are optional. If no filters are provided, the endpoint returns all agents within the specified project, subject to pagination limits.

Response

Success Response (200 OK)

Returns an object containing an array of agents and the total count.

{
  "agents": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Customer Support Agent",
      "tags": ["support", "customer-service", "chatbot"],
      "role": "assistant",
      "description": "An AI agent specialized in handling customer support inquiries",
      "logo_url": "https://example.com/logo.png",
      "logo_id": "logo_123456",
      "is_disabled": false,
      "is_archived": false,
      "widget_id": "widget_789"
    },
    {
      "id": "b2c3d4e5-f6g7-8901-bcde-fg2345678901",
      "name": "Sales Assistant",
      "tags": ["sales", "lead-generation"],
      "role": "specialist",
      "description": "An AI agent focused on sales and lead qualification",
      "logo_url": "https://example.com/sales-logo.png",
      "logo_id": "logo_654321",
      "is_disabled": false,
      "is_archived": false,
      "widget_id": "widget_101"
    }
  ],
  "total_count": 2
}

Response Fields

Field	Type	Description
agents	array	Array of agent objects matching the query criteria.
total_count	integer	Total number of agents matching the query (before pagination).

Agent Object Fields

Field	Type	Description
id	string	Unique identifier of the agent.
name	string	Name of the agent.
tags	array	Array of tags associated with the agent.
role	string	Role of the agent (e.g., assistant, specialist).
description	string	Description of the agent's purpose and functionality.
logo_url	string	URL of the agent's logo image.
logo_id	string	Unique identifier for the logo asset.
is_disabled	boolean	Whether the agent is currently disabled.
is_archived	boolean	Whether the agent is archived.
widget_id	string	Identifier of the associated widget.

Error Response (422 Unprocessable Entity)

Returns validation error details when the request body is invalid.

{
  "detail": [
    {
      "loc": [
        "body",
        "limit"
      ],
      "msg": "ensure this value is less than or equal to 1000",
      "type": "value_error.number.not_le"
    }
  ]
}

Error Response Fields

Field	Type	Description
detail	array	Array of validation error objects.
loc	array	Location of the error in the request (e.g., body field).
msg	string	Human-readable error message.
type	string	Error type identifier.

Error Codes

Status Code	Description	Response Type
200	Successful Response	Success
422	Validation Error - Invalid request parameters	Unprocessable Entity