Settings API

Base path: /api/settings

All endpoints require authentication. See API Overview for auth details.

The Settings API manages runtime configuration for user profile, browser, memory, security, and more. Changes take effect immediately without restarting the daemon.

All settings

GET /api/settings

Returns all settings across all categories.

AI providers

AI provider management uses a separate base path: /api/providers (not /api/settings/providers).

List providers

GET /api/providers

Returns all configured AI providers with their status.

Set provider API key

PUT /api/providers/{id}/key

{
  "api_key": "sk-ant-api03-..."
}

Delete provider API key

DELETE /api/providers/{id}/key

Test provider connection

POST /api/providers/{id}/test

Supported provider IDs: anthropic, openai, openrouter, gemini, deepseek, grok, groq, mistral

Backup providers

Where each provider’s work goes when it nears its plan usage limit (see Settings → Backup providers). Admin only.

GET /api/providers/backup
PUT /api/providers/backup

{
  "rules": {
    "claude-native": { "provider": "codex-native", "model": "gpt-5.5" },
    "anthropic": null
  },
  "five_hour_threshold_pct": 80,
  "seven_day_threshold_pct": 90,
  "return_below_pct": 60,
  "auto_return": true,
  "both_out": "pause"
}

PUT takes any subset of these fields; rules merges per provider (null removes a provider’s backup). both_out is pause or keep_going; return_below_pct must be below both thresholds. GET also returns the shipped defaults.

GET /api/providers/usage

Per provider: the latest 5-hour and 7-day utilization (0–1) with reset times, how close it is to its limit (heat.level: cool, near, out), whether it is failed over, and its backup.

POST /api/providers/backup/{id}/return

Moves a failed-over provider back to primary by hand (for when auto-return is off). Returns 409 while the provider is still near its limit.

Browser settings

GET /api/settings/browser
PUT /api/settings/browser

{
  "backend": "managed",
  "headless": true,
  "auto_snapshot": false,
  "snapshot_interval_ms": 500,
  "stream_fps": 2,
  "stream_quality": 75,
  "ssrf_allowlist": [],
  "ssrf_blocklist": []
}

Sandbox settings

Sandbox configuration uses the Sandbox API:

GET /api/sandbox/config
PUT /api/sandbox/config

See Sandbox API for details.

Channel settings

Channel settings are under the Channels API:

GET /api/channels/settings
PUT /api/channels/settings

See Channels API for full channel settings documentation.

Memory settings

GET /api/settings/memory
PUT /api/settings/memory

See Memory API for details.

User profile

Get profile

GET /api/settings/profile

{
  "display_name": "Alex Johnson",
  "email": "[email protected]",
  "avatar_url": null,
  "timezone": "America/New_York",
  "theme": "aurora-dark"
}

Update profile

PUT /api/settings/profile

{
  "display_name": "Alex",
  "timezone": "America/Los_Angeles"
}

Upload avatar

POST /api/settings/avatar
Content-Type: multipart/form-data

Returns:

{"avatar_url": "/api/avatars/user_123.jpg"}

Agent settings

GET /api/settings/agent
PUT /api/settings/agent

Interface settings

GET /api/settings/interface
PUT /api/settings/interface

Security settings

GET /api/settings/security
PUT /api/settings/security

Strategy settings

GET /api/settings/strategy
PUT /api/settings/strategy

Proactive settings

GET /api/settings/proactive
PUT /api/settings/proactive

Email settings

GET  /api/settings/email
PUT  /api/settings/email
POST /api/settings/email/test

Skills / Tools settings

GET  /api/settings/skills
GET  /api/settings/skills/builtin
POST /api/settings/skills/builtin/{name}/toggle

Custom tools:

GET    /api/settings/skills/custom
POST   /api/settings/skills/custom
GET    /api/settings/skills/custom/{id}
PUT    /api/settings/skills/custom/{id}
DELETE /api/settings/skills/custom/{id}
POST   /api/settings/skills/custom/{id}/toggle

MCP servers:

GET    /api/settings/skills/mcp
POST   /api/settings/skills/mcp
GET    /api/settings/skills/mcp/{id}
PUT    /api/settings/skills/mcp/{id}
DELETE /api/settings/skills/mcp/{id}
POST   /api/settings/skills/mcp/{id}/test
POST   /api/settings/skills/mcp/{id}/discover
POST   /api/settings/skills/mcp/{id}/connect
POST   /api/settings/skills/mcp/{id}/disconnect
GET    /api/settings/skills/mcp/{id}/status
GET    /api/settings/skills/mcp/catalog
POST   /api/settings/skills/mcp/catalog/{entry_id}/install

Reset settings

Reset general settings

POST /api/settings/reset

Resets general settings to defaults.

Reset security settings

POST /api/settings/security/reset

Resets security settings to defaults.

Export / Import

Export settings

GET /api/settings/export

Returns a JSON file with all settings (API keys are excluded for security).

Import settings

POST /api/settings/import
Content-Type: application/json

Applies settings from a previously exported configuration. API keys are not imported — re-enter them manually.