Admin API (Self-hosted)

API reference for self-hosted deployments

Note:

This API is only relevant if you're self-hosting chans. For managed deployments, use the dashboard to manage agents and settings.

Overview

The Admin API provides programmatic control over chans resources for self-hosted deployments.

Base URL: Your self-hosted endpoint (e.g., https://api.your-domain.com)

Authentication

All admin endpoints require an API key via the X-API-Key header:

curl -H "X-API-Key: YOUR_ADMIN_API_KEY" \
  https://api.your-domain.com/admin/v1/agents

Set your API key via the CHANS_ADMIN_API_KEY environment variable.

Admin Panel

Access the web-based Admin Panel at /home for managing presets, agents, and viewing conversations.

Endpoints

Health (Public)

MethodPathDescription
GET/healthBasic health check
GET/health/readyDatabase readiness
GET/health/liveContainer liveness
GET/health/providersProvider status

SDK Session (Public)

MethodPathDescription
POST/sdk/v1/sessionCreate voice session (requires agent token)

Agents

MethodPathDescription
GET/admin/v1/agentsList agents
POST/admin/v1/agentsCreate agent
GET/admin/v1/agents/{id}Get agent
PATCH/admin/v1/agents/{id}Update agent
DELETE/admin/v1/agents/{id}Delete agent
GET/admin/v1/agents/{id}/statsAgent statistics
GET/admin/v1/agents/{id}/sessionsAgent sessions

Presets

MethodPathDescription
GET/admin/v1/presetsList presets
GET/admin/v1/presets/availableList available providers
POST/admin/v1/presetsCreate preset
GET/admin/v1/presets/{id}Get preset
PATCH/admin/v1/presets/{id}Update preset
DELETE/admin/v1/presets/{id}Delete preset

Sessions

MethodPathDescription
GET/admin/v1/sessionsList sessions
GET/admin/v1/sessions/{id}Session details

Conversations

MethodPathDescription
GET/admin/v1/conversationsList conversations
GET/admin/v1/conversations/{id}Conversation messages

Errors

MethodPathDescription
GET/admin/v1/errorsList errors
GET/admin/v1/errors/{id}Get error
GET/admin/v1/errors/stats/summaryError statistics
POST/admin/v1/errors/{id}/resolveResolve error

Rate Limits

Default rate limits (configurable via environment):

VariableDefaultDescription
CHANS_RATE_LIMIT_RPM60Requests per minute
CHANS_RATE_LIMIT_BURST10Burst size

Rate limit headers are included in responses:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 55
X-RateLimit-Reset: 1705315200