Skip to main content
GET
/
v1
/
agents
List Agents (Minimal)
curl --request GET \
  --url https://api.xpander.ai/v1/agents \
  --header 'x-api-key: <api-key>'
{
  "items": [
    {
      "id": "93a1cd50-2af0-452a-99a0-6e1f1b14fb29",
      "name": "Product Specialist",
      "description": "Answers product questions using web search and documentation",
      "icon": "🚀",
      "status": "ACTIVE",
      "deployment_type": "serverless",
      "created_at": "2026-02-05T18:54:51.388334Z",
      "model_provider": "anthropic",
      "model_name": "claude-sonnet-4-5-20250929",
      "framework": "agno",
      "organization_id": "91fbe9bc-35b3-41e8-b59d-922fb5a0f031",
      "llm_api_base": null,
      "has_pending_changes": false
    }
  ],
  "total": 12,
  "page": 1,
  "per_page": 20,
  "total_pages": 1
}
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.

​
Query Parameters

​
page
integer
default:1
Page number (starting from 1)
​
per_page
integer
default:20
Items per page (maximum 50)

​
Response

Returns a paginated list of agent summaries. Treat unknown fields as forward-compatible metadata.
​
items
array
Array of agent objects
​
total
integer
Total number of agents across all pages
​
page
integer
Current page number
​
per_page
integer
Number of items per page
​
total_pages
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",
      "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
MinimalAIAgent · object[]
​
total
integer
​
page
integer
​
per_page
integer
​
total_pages
integer