List Agents

List Agents (Minimal)

curl --request GET \
  --url https://api.xpander.ai/v1/agents \
  --header 'x-api-key: <api-key>'

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://api.xpander.ai/v1/agents', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.xpander.ai/v1/agents",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.xpander.ai/v1/agents"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.xpander.ai/v1/agents")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "items": [
    {
      "id": "a1a1a1a1-b2b2-c3c3-d4d4-e5e5e5e5e5e5",
      "name": "Research Assistant",
      "description": "Searches the web and reports findings as JSON.",
      "icon": "🚀",
      "status": "ACTIVE",
      "organization_id": "0a0a0a0a-1b1b-2c2c-3d3d-4e4e4e4e4e4e",
      "deployment_type": "serverless",
      "model_provider": "anthropic",
      "model_name": "claude-sonnet-5",
      "type": "manager",
      "created_at": "2026-07-28T20:55:54.042725Z"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20,
  "total_pages": 1
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

GET

agents

List Agents (Minimal)

curl --request GET \
  --url https://api.xpander.ai/v1/agents \
  --header 'x-api-key: <api-key>'

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://api.xpander.ai/v1/agents', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.xpander.ai/v1/agents",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.xpander.ai/v1/agents"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.xpander.ai/v1/agents")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "items": [
    {
      "id": "a1a1a1a1-b2b2-c3c3-d4d4-e5e5e5e5e5e5",
      "name": "Research Assistant",
      "description": "Searches the web and reports findings as JSON.",
      "icon": "🚀",
      "status": "ACTIVE",
      "organization_id": "0a0a0a0a-1b1b-2c2c-3d3d-4e4e4e4e4e4e",
      "deployment_type": "serverless",
      "model_provider": "anthropic",
      "model_name": "claude-sonnet-5",
      "type": "manager",
      "created_at": "2026-07-28T20:55:54.042725Z"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20,
  "total_pages": 1
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

Retrieve a paginated list of agents for browsing and selection. Although this is the lighter-weight listing endpoint, the payload typically includes core deployment and model metadata and may include additional summary fields such as instructions or compatibility flags.

This endpoint returns standard agents. Workflows (agents of type orchestration) are listed separately by List Workflows, so the count here can be lower than the total number of agents in your organization.

Query Parameters

integer

default:1

Page number (starting from 1)

integer

default:20

Items per page (maximum 50)

Response

Returns a paginated list of agent summaries. Treat unknown fields as forward-compatible metadata.

array

Array of agent objects

Show Agent Object

string

Unique identifier for the agent (UUID format)

string

Display name of the agent

string

Brief description of the agent’s purpose

string

Emoji icon representing the agent

string

Current deployment status: ACTIVE, INACTIVE

string

Organization UUID this agent belongs to

string

Deployment method: serverless, container, or null

string

ISO timestamp of when the agent was created

string | null

UUID of the user who created the agent

object | null

Resolved creator details, one per agent item — no extra request needed. null when created_by is empty or the user cannot be resolved — null-check before reading sub-fields.

Show Created By Details

string

User UUID

string

Display name — first + last name. Falls back to email, then id, when the name is missing. Not guaranteed to be a real first/last name.

string

User email

object

High-level role, goal, and general instructions for the agent (nullable)

string

LLM provider: openai, anthropic, etc.

string

Specific model version (e.g., gpt-4o, gpt-4.1)

string

Agent framework used (e.g., agno)

string

Agent type: manager, regular, a2a, curl, or orchestration

string

Custom LLM base URL when the agent uses a proxied or self-hosted model endpoint (nullable)

boolean

Whether the agent has unpublished configuration changes

integer

Total number of agents across all pages

integer

Current page number

integer

Number of items per page

integer

Total number of pages available

Example Request

curl -X GET -H "x-api-key: <your-api-key>" \
  "https://api.xpander.ai/v1/agents?page=1&per_page=2"

Example Response

{
  "items": [
    {
      "id": "<agent-id>",
      "name": "Product Specialist",
      "description": "Processes queries to provide comprehensive product information",
      "icon": "🚀",
      "status": "ACTIVE",
      "organization_id": "<org-id>",
      "deployment_type": "serverless",
      "created_at": "2026-02-05T18:35:04.724091Z",
      "created_by": "<user-id>",
      "created_by_details": {
        "id": "<user-id>",
        "name": "Jane Doe",
        "email": "jane@acme.com"
      },
      "instructions": {
        "role": [
          "Answer product questions clearly and accurately"
        ],
        "goal": [
          "Help users find the right product quickly"
        ],
        "general": "I am a product specialist focused on concise, accurate answers."
      },
      "model_provider": "openai",
      "model_name": "gpt-5.2",
      "framework": "agno",
      "type": "manager",
      "llm_api_base": null,
      "has_pending_changes": false
    }
  ],
  "total": 12,
  "page": 1,
  "per_page": 20,
  "total_pages": 1
}

Notes

/v1/agents is the lighter-weight listing endpoint, but the response includes more than just id, name, and status
Additional fields may appear over time; client code should ignore unknown keys
The items array is sorted by creation date (newest first)
Use pagination to handle large result sets efficiently
Status values are: ACTIVE (deployed and ready), INACTIVE (not deployed)
See List Agents (Full Details) for complete agent configuration

Authorizations

x-api-key

string

header

required

API Key for authentication

Query Parameters

page

integer

default:1

Page number (starting from 1)

Required range: x >= 1

per_page

integer

default:20

Items per page (max 50)

Required range: 1 <= x <= 50

Response

Successful Response

items

MinimalAIAgentWithCreatedByDetails · object[]

required

Show child attributes

total

integer

required

page

integer

required

per_page

integer

required

total_pages

integer

required

Model Context Protocol

List Agents (Full Details)

⌘I

Overview

REST API - Agents

REST API - Scheduled Tasks

REST API - Self-Schedules

Agent Workspace

REST API - Agent Gateway

REST API - Tasks

REST API - Knowledge

REST API - Workflows

REST API - Tools

REST API - Custom Functions

REST API - Misc

Query Parameters

Response

Example Request

Example Response

Notes

Authorizations

Query Parameters

Response

​Query Parameters

​Response

​Example Request

​Example Response

​Notes

Authorizations

Query Parameters

Response

Query Parameters

Response

Example Request

Example Response

Notes