API.md

API Reference

Proxy Endpoints

Anthropic Messages API

POST /v1/messages
Content-Type: application/json

{
  "model": "claude-sonnet-4-6",
  "max_tokens": 4096,
  "system": "You are helpful.",
  "messages": [{"role": "user", "content": "Hello"}],
  "stream": true
}

Used by: Claude Code, OpenClaw

OpenAI Chat Completions API

POST /v1/chat/completions
Content-Type: application/json

{
  "model": "gpt-5.2",
  "messages": [{"role": "user", "content": "Hello"}]
}

Used by: Codex CLI, OpenClaw

OpenAI Responses API

POST /v1/responses

Used by: Codex CLI (WebSocket upgrade returns 426, then uses HTTPS)

Codex Internal API

POST /backend-api/codex/responses
GET  /backend-api/codex/models

Gemini API

POST /v1beta/models/{model}:generateContent
POST /v1beta/models/{model}:streamGenerateContent
GET  /v1beta/models

Token Counting

POST /v1/messages/count_tokens
Content-Type: application/json

{
  "messages": [...],
  "tools": [...]
}

Models

GET /v1/models
GET /models

Health

GET /health

# Response
{
  "status": "ok",
  "total": 2,
  "active": "user@example.com",
  "accounts": [...]
}

---

ChatGPT Account Management

Endpoint	Method	Description
/accounts	GET	List all accounts
/accounts/status	GET	Account status summary
/accounts/quota	GET	Get active account quota
/accounts/quota/all	GET	Get all account quotas
/accounts/add	POST	Start OAuth flow
/accounts/add/manual	POST	Manual OAuth code input
/accounts/switch	POST	Switch active account
/accounts/import	POST	Import from Codex CLI
/accounts/refresh	POST	Refresh active account token
/accounts/refresh/all	POST	Refresh all tokens
/accounts/:email/refresh	POST	Refresh specific account
/accounts/:email/toggle	PUT	Enable/disable account
/accounts/:email	DELETE	Remove account
/accounts/oauth/cleanup	POST	Clean up OAuth servers

Claude Account Management

Endpoint	Method	Description
/claude-accounts	GET	List all Claude accounts
/claude-accounts/status	GET	Account status summary
/claude-accounts/add	POST	Start Claude OAuth flow
/claude-accounts/add/manual	POST	Manual OAuth code input
/claude-accounts/switch	POST	Switch active account
/claude-accounts/import	POST	Import from Claude Code
/claude-accounts/refresh	POST	Refresh active account token
/claude-accounts/refresh/all	POST	Refresh all tokens
/claude-accounts/:email/refresh	POST	Refresh specific account
/claude-accounts/:email/toggle	PUT	Enable/disable account
/claude-accounts/:email	DELETE	Remove account
/claude-accounts/oauth/cleanup	POST	Clean up OAuth servers

---

CLI Configuration

Claude Code

Endpoint	Method	Description
/claude/config	GET	View current config
/claude/config/proxy	POST	Configure proxy mode
/claude/config/direct	POST	Restore direct API
/claude/config/set	POST	Set custom API endpoint

Codex CLI

Endpoint	Method	Description
/codex/config	GET	View current config
/codex/config/proxy	POST	Configure proxy mode
/codex/config/direct	POST	Restore direct connection

Gemini CLI

Endpoint	Method	Description
/gemini-cli/config	GET	View current config
/gemini-cli/config/proxy	POST	Patch Gemini CLI for proxy
/gemini-cli/config/direct	POST	Remove proxy patch

OpenClaw

Endpoint	Method	Description
/openclaw/config	GET	View current config
/openclaw/config/proxy	POST	Configure proxy provider
/openclaw/config/direct	POST	Remove proxy provider

---

Settings

Endpoint	Method	Description
/settings/haiku-model	GET	Get current haiku/free model
/settings/haiku-model	POST	Set haiku/free model target
/settings/kilo-models	GET	List available free models
/settings/account-strategy	GET	Get account rotation strategy
/settings/account-strategy	POST	Set strategy (random/sequential)
/settings/routing-priority	GET	Get routing priority
/settings/routing-priority	POST	Set priority (account-first/apikey-first)

API Key Management

Endpoint	Method	Description
/api/keys	GET	List all API keys
/api/keys	POST	Add new API key
/api/keys/:id	PUT	Update API key
/api/keys/:id	DELETE	Remove API key
/api/keys/:id/validate	POST	Validate API key
/api/keys/stats	GET	Get key usage stats

Usage & Analytics

Endpoint	Method	Description
/api/usage/overview	GET	Usage overview
/api/usage/history	GET	Usage history
/api/usage/daily	GET	Daily stats
/api/usage/monthly	GET	Monthly stats
/api/usage/providers	GET	Per-provider stats
/api/usage/models	GET	Per-model stats
/api/usage/accounts	GET	Per-account stats

Pricing

Endpoint	Method	Description
/api/pricing	GET	List pricing summary and effective pricing entries
/api/pricing	PUT	Update a pricing override
/api/pricing/reset	POST	Reset one pricing override to defaults

Request Logs

Endpoint	Method	Description
/api/request-logs	GET	Get request logs
/api/request-logs/dates	GET	Get available log dates
/api/request-logs/settings	GET	Get log settings
/api/request-logs/settings	PUT	Update log settings

Model Mapping

Endpoint	Method	Description
/api/model-mappings	GET	Get all model mappings
/api/model-mappings/provider/:provider	PUT	Set provider mapping
/api/model-mappings/reset	POST	Reset to defaults
/api/model-mappings/resolve	GET	Resolve a model name

Resources Catalog

Endpoint	Method	Description
/api/resources	GET	List curated resource entries with filters
/api/resources/summary	GET	Get resource catalog summary
/api/resources/:id	GET	Get one resource entry

Local Runtime Management

Endpoint	Method	Description
/api/local-runtimes	GET	Get local runtime status and configured runtimes
/api/local-runtimes/ollama-local	PUT	Update the built-in Ollama runtime config
/api/local-runtimes/enabled	POST	Enable or disable local model routing
/api/local-runtimes/check	POST	Check local runtime health
/api/local-runtimes/refresh-models	POST	Refresh discovered local models and routing targets

Image Generation

Independent of the chat API-key pool — image models have their own store (~/.cligate/image-gen/), parameters and per-image billing. The assistant calls them through a single generate_image tool; this surface manages the model entries and a test/playground generate. See docs/assistant-image-generation-design.zh-CN.md.

Endpoint	Method	Description
/api/image-gen/status	GET	Settings, model entries (secrets masked), available backend kinds (openai-images, volcengine-images for 即梦/Seedream, wanxiang for 通义万相), configured flag
/api/image-gen/models	GET	List image model entries
/api/image-gen/models	POST	Add an image model entry
/api/image-gen/models/:id	PUT	Update an image model entry (apiKey preserved if omitted/masked)
/api/image-gen/models/:id	DELETE	Remove an image model entry
/api/image-gen/models/:id/enabled	POST	Enable/disable an entry ({ enabled: boolean })
/api/image-gen/settings	GET	Get image-gen settings (requireApproval, defaultModelId, maxImagesPerCall)
/api/image-gen/settings	PUT	Update image-gen settings
/api/image-gen/generate	POST	Manual generation (dashboard test); returns artifact download URLs
/api/artifacts/:id	GET	Stream a generated/captured artifact file by id (path restricted to the config dir)

Desktop Mascot

Powers the optional desktop-assistant character window in the Electron build (not applicable to plain server/web mode). See docs/assistant-desktop-mascot-design.zh-CN.md.

Endpoint	Method	Description
/api/mascot/config	GET	Mascot config (enabled, character, clickAction, position)
/api/mascot/config	PUT	Update mascot config (persisted in server-settings.mascot)
/api/mascot/state	GET	Current mascot state (idle/listening/thinking/talking/notify)
/api/mascot/state	POST	Set mascot state ({ state, text }) — for demo / incremental wiring
/api/mascot/events	GET	SSE stream of mascot state changes + a {directive:'reload'} frame when the character switches
/api/mascot/characters	GET	List available character packs (built-in + ~/.cligate/mascot-characters/) + the active one
/api/mascot/character	POST	Switch active character ({ character }); broadcasts a reload to the live window
/api/mascot/characters/import	POST	Import a local character-pack folder ({ path }) into the user characters dir

Agent Runtime Orchestrator

Endpoint	Method	Description
/api/agent-runtimes/providers	GET	List runtime providers available to the dashboard and channels
/api/agent-runtimes/sessions	GET	List runtime sessions
/api/agent-runtimes/sessions	POST	Create a runtime session
/api/agent-runtimes/sessions/:id	GET	Get runtime session detail
/api/agent-runtimes/sessions/:id/stream	GET	Stream runtime session events
/api/agent-runtimes/sessions/:id/input	POST	Send follow-up input to a runtime session
/api/agent-runtimes/sessions/:id/approval	POST	Resolve an approval request
/api/agent-runtimes/sessions/:id/question	POST	Answer a runtime question
/api/agent-runtimes/sessions/:id/cancel	POST	Cancel a runtime session

Agent Channel Gateway

Feishu supports two connection models:

• websocket for local desktop deployments without a public callback URL
• webhook for server deployments with a public HTTPS callback endpoint

Endpoint	Method	Description
/api/agent-channels/providers	GET	List channel provider status
/api/agent-channels/catalog	GET	List channel provider metadata used by future dynamic channel configuration UIs
/api/agent-channels/settings	GET	Get channel settings
/api/agent-channels/settings/:channel	PUT	Update channel settings
/api/agent-channels/refresh	POST	Refresh channel providers
/api/agent-channels/feishu/webhook	POST	Receive Feishu webhook events
/api/agent-channels/dingtalk/webhook	POST	Receive DingTalk webhook events
/api/agent-channels/session-records	GET	List channel-linked runtime session records used by Conversation Records
/api/agent-channels/session-records/:id	GET	Get one channel-linked runtime session record
/api/agent-channels/conversations	GET	List stored channel conversation threads
/api/agent-channels/conversations/:id	GET	Get one stored channel conversation with deliveries
/api/agent-channels/conversations/:id/reset	POST	Detach the active runtime session from a conversation
/api/agent-channels/pairing/:channel/:conversationId/approve	POST	Approve channel pairing
/api/agent-channels/pairing/:channel/:conversationId/deny	POST	Deny channel pairing

Tool Installer

Endpoint	Method	Description
/api/tools/status	GET	Get tool installation and version status
/api/tools/node-info	GET	Get Node.js installation info
/api/tools/install/:toolId	POST	Install one CLI tool
/api/tools/install-node	POST	Install Node.js for the current platform
/api/tools/launch/:toolId	POST	Launch an installed tool

API Gateway

Endpoint	Method	Description
/api/gateway/chat	POST	External chat via API key
/api/gateway/messages	POST	External messages via API key
/api/gateway/providers	GET	List available providers

---

Error Responses

Authentication Error

{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "No active account with valid credentials"
  }
}

Rate Limit Error

{
  "type": "error",
  "error": {
    "type": "rate_limit_error",
    "message": "Rate limited: retry after 30s"
  }
}

Streaming (Anthropic SSE Format)

event: message_start
data: {"type":"message_start","message":{...}}

event: content_block_start
data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Hello"}}

event: content_block_stop
data: {"type":"content_block_stop","index":0}

event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"end_turn"},"usage":{...}}

event: message_stop
data: {"type":"message_stop"}