Skip to main content
The REST API provides comprehensive HTTP endpoints for managing your AI agents, executing tasks, and controlling knowledge bases from any programming language.

​
Overview

The REST API is your control plane for the xpander platform, enabling you to:
  • Manage Agents: Create, update, deploy, and delete AI agents
  • Export & Import: Share agents as templates across organizations
  • Execute Tasks: Invoke agents synchronously, asynchronously, or with streaming
  • Control Knowledge: Manage knowledge bases and documents
  • Access Toolkits: List and invoke tools across integrations

​
Base URL

https://api.xpander.ai

​
Authentication

All API requests require authentication via the x-api-key header: 
curl -X GET "https://api.xpander.ai/v1/agents" \
  -H "x-api-key: YOUR_API_KEY"

​
Quick Start

# List all agents
curl -X GET "https://api.xpander.ai/v1/agents" \
  -H "x-api-key: YOUR_API_KEY"

# Invoke an agent
curl -X POST "https://api.xpander.ai/v1/agents/{agent_id}/invoke" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "text": "Analyze this data"
    }
  }'

​
API Endpoints

Agents

Create, manage, and invoke AI agents

Agent Templates

Export and import agents across organizations

Tasks

Monitor and manage task executions

Knowledge

Manage knowledge bases and documents

Toolkits

Access and invoke tools

​
Key Features

  • 🌐 Universal Access: Works with any programming language that supports HTTP
  • ⚡ Multiple Execution Modes: Sync, async, and streaming invocation
  • 📊 Complete CRUD: Full lifecycle management for all resources
  • 🔒 Secure: API key authentication with organization-level scoping
  • 📖 OpenAPI Spec: Complete OpenAPI 3.1 specification available

​
Response Format

All API responses follow a consistent JSON structure: 
{
  "id": "resource-id",
  "status": "completed",
  "created_at": "2025-11-05T20:00:00Z",
  ...
}

​
Error Handling

The API uses standard HTTP status codes:
  • 200 - Success
  • 201 - Created
  • 400 - Bad Request
  • 401 - Unauthorized
  • 404 - Not Found
  • 422 - Validation Error
  • 500 - Internal Server Error
Error responses include detailed information: 
{
  "detail": [
    {
      "loc": ["body", "input"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

​
Rate Limits

The API implements rate limiting to ensure fair usage:
  • Standard: 100 requests per minute
  • Burst: 1000 requests per hour
Rate limit headers are included in responses: 
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1699200000

​
Next Steps

Agent Endpoints

Explore agent management endpoints

Task Endpoints

Learn about task execution

Examples

View code examples

OpenAPI Spec

Download OpenAPI specification