System API

The system API covers core server operations that don't belong to a specific domain: health checks, runtime debugging, AI provider switching, process restart, configuration CRUD, and the ElevenLabs TTS proxy.

Endpoints

GET /api/status

Returns the agent's current state, name, model, uptime, cloud connection status, and whether a restart is pending.

Response

{
  "state": "running",
  "agentName": "Eliza",
  "model": "@elizaos/plugin-anthropic",
  "startedAt": 1718000000000,
  "uptime": 3600000,
  "startup": {
    "phase": "ready",
    "attempt": 1
  },
  "cloud": {
    "connectionStatus": "disconnected",
    "activeAgentId": null,
    "cloudProvisioned": false,
    "hasApiKey": false
  },
  "pendingRestart": false,
  "pendingRestartReasons": []
}

GET /api/health

Structured health check endpoint that returns the status of each subsystem. The ready field indicates whether the agent has finished starting and is available to serve requests.

Response

{
  "ready": true,
  "runtime": "ok",
  "database": "ok",
  "plugins": {
    "loaded": 12,
    "failed": 0
  },
  "coordinator": "ok",
  "connectors": {
    "discord": "connected",
    "telegram": "configured"
  },
  "uptime": 3600,
  "agentState": "running",
  "startup": {
    "phase": "ready",
    "attempt": 1
  }
}

GET /api/runtime

Deep runtime introspection endpoint for advanced debugging. Returns detailed information about plugins, actions, providers, evaluators, and services registered in the runtime.

Query Parameters

Response

{
  "runtimeAvailable": true,
  "generatedAt": 1718000000000,
  "settings": { "maxDepth": 3, "..." : "..." },
  "meta": {
    "agentId": "uuid",
    "agentState": "running",
    "agentName": "Eliza",
    "model": "@elizaos/plugin-anthropic",
    "pluginCount": 12,
    "actionCount": 45,
    "providerCount": 8,
    "evaluatorCount": 3,
    "serviceTypeCount": 6,
    "serviceCount": 10
  },
  "order": {
    "plugins": ["@elizaos/plugin-example", "..."],
    "actions": ["CHAT", "..."],
    "providers": ["..."],
    "evaluators": ["..."],
    "services": { "MODEL": ["..."] }
  },
  "sections": {
    "runtime": { "..." : "..." },
    "plugins": [ "..." ],
    "actions": [ "..." ],
    "providers": [ "..." ],
    "evaluators": [ "..." ],
    "services": { "..." : "..." }
  }
}

POST /api/provider/switch

Atomically switch the active AI provider selection. The server persists the selection into canonical runtime config, primarily serviceRouting.llmText, updates linked-account state when needed, and triggers a restart after the switch.

Request Body

Canonical providers: elizacloud, openai-subscription, anthropic-subscription, openai, anthropic, deepseek, gemini, groq, grok, openrouter, ollama, mistral, together, zai.

Compatibility aliases are still accepted on input and normalized before persistence, including google, google-genai, xai, and openai-codex.

When switching to elizacloud, text inference is routed through the Eliza Cloud proxy. Switching away from elizacloud changes only the active text route; linked cloud accounts and other routed cloud services can remain available independently.

Response

{
  "success": true,
  "provider": "anthropic",
  "restarting": true
}

Errors

POST /api/restart

Restart the server process. Sets the agent state to restarting, broadcasts a status update, and responds immediately. The process exits after a short delay.

Response

{
  "ok": true
}

GET /api/config

Returns the full Eliza configuration with secret values redacted.

Response

The full config object — structure varies based on what has been configured. Secrets are replaced with redacted placeholders.

GET /api/config/schema

Returns the JSON schema for the Eliza configuration file. Useful for building dynamic configuration UIs.

Response

A JSON Schema object describing all config keys, types, and defaults.

PUT /api/config

Update one or more configuration keys. Uses a deep-merge strategy — provided keys are merged recursively without wiping sibling keys. Protected against prototype pollution.

Canonical runtime routing and hosting live in these top-level config fields:

• deploymentTarget
• linkedAccounts
• serviceRouting

The server resolves runtime behavior from those canonical fields. Client flows should update hosting and routing there instead of sending legacy onboarding mirrors or provider-specific compatibility blobs. Initial onboarding secrets belong on POST /api/onboarding under credentialInputs; PUT /api/config is for persisted canonical config, not for replaying old onboarding payloads.

Request Body

Partial config object. Only provided keys are updated:

{
  "ui": {
    "theme": "haxor"
  },
  "models": {
    "small": "openai/gpt-5-mini"
  }
}

Response

Returns the updated redacted config snapshot.

POST /api/tts/elevenlabs

Proxy endpoint for ElevenLabs text-to-speech. Forwards the request to the ElevenLabs API and returns the audio stream. Resolves the API key from the request body, config, or ELEVENLABS_API_KEY env var.

Request Body

Response

Binary audio stream with Content-Type: audio/mpeg.

Errors

POST /api/tts/cloud

Proxy endpoint for Eliza Cloud text-to-speech. Sends the request to the Eliza Cloud TTS service and returns the audio stream. Requires an active Eliza Cloud connection with a valid API key.

The endpoint resolves the cloud API key from (in order): ELIZAOS_CLOUD_API_KEY environment variable, cloud.apiKey in the config file, or the sealed secret store.

Request Body

Response

Binary audio stream with Content-Type: audio/mpeg.

Errors

POST /api/terminal/run

Execute a shell command on the server and stream output via WebSocket. Responds immediately — output is broadcast as terminal-output WebSocket events.

Request Body

The clientId can alternatively be sent via the X-Eliza-Client-Id header.

Constraints

• Max 4096 characters
• Single line only (no newlines or control characters)
• Concurrent runs are rate-limited

Response

{
  "ok": true
}

Output is streamed via WebSocket:

{ "type": "terminal-output", "runId": "run-...", "event": "stdout", "data": "..." }
{ "type": "terminal-output", "runId": "run-...", "event": "exit", "code": 0 }

Errors

POST /api/ingest/share

Submit external content (URLs, text, articles) to the agent's share ingest queue for processing.

Request Body

Response

{
  "ok": true,
  "item": {
    "id": "uuid",
    "source": "chrome-extension",
    "title": "Article Title",
    "url": "https://example.com/article",
    "suggestedPrompt": "What do you think about \"Article Title\"?",
    "receivedAt": 1718000000000
  }
}

GET /api/ingest/share

Retrieve the share ingest queue.

Query Parameters

Response

{
  "items": [
    {
      "id": "uuid",
      "source": "chrome-extension",
      "title": "...",
      "receivedAt": 1718000000000
    }
  ]
}