Client API

The xpander.ai Client API provides a comprehensive interface for interacting with the xpander.ai platform. This documentation covers the core API methods, request/response formats, and authentication mechanisms.

Authentication

All API requests require authentication using an API key. You can obtain an API key from the xpander.ai console.

from xpander_sdk import XpanderClient

# Initialize with API key
client = XpanderClient(api_key="your-xpander-api-key")

Core Methods

Agents

List Agents

# List all agents
agents = client.list_agents()

# Filter agents by type
regular_agents = client.list_agents(type="regular")

Get Agent

# Get agent by ID
agent = client.get_agent("agent-id")

Create Agent

# Create a new agent
new_agent = client.create_agent(
    name="My New Agent",
    type="regular",
    description="This agent helps with customer service tasks"
)

Update Agent

# Update an existing agent
updated_agent = client.update_agent(
    "agent-id",
    name="Updated Agent Name",
    description="New description"
)

Delete Agent

# Delete an agent
client.delete_agent("agent-id")

Operations

List Operations

# List all operations for an agent
operations = client.list_operations(agent_id="agent-id")

Get Operation

# Get operation by ID
operation = client.get_operation("operation-id")

Create Operation

# Create a new operation
new_operation = client.create_operation(
    agent_id="agent-id",
    name="My Operation",
    type="function",
    prompt="You are a helpful assistant that...",
    input_schema={
        "type": "object",
        "properties": {
            "query": {"type": "string"}
        },
        "required": ["query"]
    },
    output_schema={
        "type": "object",
        "properties": {
            "answer": {"type": "string"}
        },
        "required": ["answer"]
    }
)

Update Operation

# Update an existing operation
updated_operation = client.update_operation(
    "operation-id",
    name="Updated Operation",
    prompt="New prompt content"
)

Delete Operation

# Delete an operation
client.delete_operation("operation-id")

Execution

Execute Operation

# Execute an operation
result = client.execute_operation(
    "operation-id",
    input={
        "query": "What is the capital of France?"
    }
)

Stream Operation Results

# Stream operation results
for chunk in client.stream_operation("operation-id", input={"query": "Tell me a story"}):
    print(chunk.content, end="", flush=True)

Error Handling

The API uses standard HTTP status codes to indicate success or failure:

  • 200: Success
  • 400: Bad request (invalid parameters)
  • 401: Unauthorized (invalid API key)
  • 404: Resource not found
  • 429: Rate limit exceeded
  • 500: Server error
try:
    result = client.execute_operation("operation-id", input={"query": "Hello"})
except xpander_sdk.APIError as e:
    if e.status_code == 401:
        print("Authentication error. Check your API key.")
    elif e.status_code == 404:
        print("Operation not found.")
    else:
        print(f"API error: {e}")

Rate Limits

The API has rate limits to ensure fair usage. Current limits are:

  • 100 requests per minute
  • 5,000 requests per day

If you exceed these limits, you’ll receive a 429 status code.