Endpoints

This page covers the key endpoints available on the Agent One REST API. For the full interactive spec, see /api/docs on your running instance.

Health

`GET /api/v1/health`

Returns agent health status and component readiness.

{
  "status": "healthy",
  "version": "0.14.0",
  "uptime_seconds": 3600,
  "components": {
    "litellm": "connected",
    "memory": "ready",
    "channels": { "cli": "active", "whatsapp": "active" },
    "mcp_servers": { "github": "ready", "clickup": "ready" }
  }
}

Chat

`WebSocket /api/v1/chat/ws`

Real-time chat with the agent. See API Overview for the WebSocket message format.

`POST /api/v1/chat/message`

Send a message and get a complete response (non-streaming).

// Request
{
  "content": "How much did I spend this week?",
  "channel": "web"
}

// Response
{
  "content": "You spent $245.00 this week across 3 purchases...",
  "model": "cheap",
  "tokens_used": 187
}

Hands

`GET /api/v1/hands`

List all configured Hands.

`GET /api/v1/hands/:name`

Get details for a specific Hand, including recent runs.

`POST /api/v1/hands`

Create a new Hand. Requires owner role.

{
  "name": "weekly-report",
  "schedule": "0 17 * * 5",
  "prompt": "Summarize the week's accomplishments",
  "tools": ["github", "clickup"],
  "budget_cap_usd": 0.30,
  "approval_required": false
}

`PUT /api/v1/hands/:name`

Update an existing Hand. Requires owner role.

`DELETE /api/v1/hands/:name`

Delete a Hand. Requires owner role.

`GET /api/v1/hands/:name/runs`

List run history for a Hand. Returns status, cost, timestamps, and plan details.

`POST /api/v1/hands/:name/runs/:id/approve`

Approve a pending Hand run. Requires owner or admin role.

`POST /api/v1/hands/:name/runs/:id/reject`

Reject a pending Hand run. Requires owner or admin role.

Personas

`GET /api/v1/personas`

List all personas (system defaults + user-defined).

`GET /api/v1/personas/:id`

Get a specific persona with its soul, tools, and bindings.

`POST /api/v1/personas`

Create a new persona. Requires owner role.

{
  "id": "sales-rep",
  "name": "Sales Assistant",
  "soul": "You are a sales assistant focused on lead qualification.",
  "tools": ["clickup", "browser_navigate"],
  "budget_cap_usd": 0.30
}

`PUT /api/v1/personas/:id`

Update a persona. System defaults are read-only.

`DELETE /api/v1/personas/:id`

Delete a user-defined persona. System defaults cannot be deleted.

Channels

`GET /api/v1/channels`

List all channels with their status (active, inactive, error).

`PUT /api/v1/channels/:id`

Update channel configuration. Requires owner role.

Members

`GET /api/v1/members`

List all team members with roles. Requires admin or owner role.

`POST /api/v1/members`

Add a new member. Requires owner role.

{
  "name": "Maria",
  "role": "admin",
  "channels": ["whatsapp", "telegram"]
}

`PUT /api/v1/members/:id`

Update a member’s role or channel access.

`DELETE /api/v1/members/:id`

Remove a member. Requires owner role.

Config

`GET /api/v1/config`

Get the current agent configuration (secrets redacted). Requires owner role.

`PATCH /api/v1/config`

Update specific config fields. Changes are validated and hot-reloaded. Requires owner role.

{
  "budget": {
    "daily_limit_usd": 2.00
  },
  "channels": {
    "default": "telegram"
  }
}

Billing

`GET /api/v1/billing`

Get current billing status, usage, and plan details. Available in SaaS platform mode.

`GET /api/v1/billing/usage`

Get token usage and cost breakdown by model, day, and Hand.

Analytics

`GET /api/v1/analytics/messages`

Message volume over time, grouped by channel.

`GET /api/v1/analytics/costs`

Cost breakdown by model tier, day, and Hand.

`GET /api/v1/analytics/tools`

Tool usage frequency and latency.

Audit

`GET /api/v1/audit`

Query the append-only audit log. Requires owner or admin role.

GET /api/v1/audit?action=config_change&page=1&page_size=20

Returns timestamped entries for all significant actions: config changes, Hand approvals, member management, tool calls, and more.