OpenBotX API Reference

OpenBotX API Reference

Complete REST API and WebSocket reference for OpenBotX.

Authentication

All endpoints (except /api/auth/login) require a valid JWT token passed in the Authorization header:

Authorization: Bearer <token>

REST API

All endpoints are prefixed with /api/.

Auth

POST /api/auth/login

No authentication required.

Request body:

{
  "username": "string",
  "password": "string"
}

Response:

{
  "token": "string"
}

System

GET /api/health

Response:

{
  "status": "ok",
  "version": "string"
}

GET /api/version

Response:

{
  "version": "string"
}

GET /api/system/info

Response:

{
  "os": { "system": "string", "release": "string", "version": "string", "machine": "string" },
  "cpu": { "processor": "string", "cores": 0 },
  "memory": { "total_gb": 0.0 },
  "disk": { "total_gb": 0.0, "used_gb": 0.0, "free_gb": 0.0, "percent": 0.0 },
  "gpu": [{ "name": "string" }],
  "python": "string",
  "version": "string"
}

Chat

POST /api/chat

Sends a message asynchronously. The response is delivered via WebSocket events.

Request body:

{
  "message": "string",
  "session_id": "string (optional)",
  "media": ["string (optional)"]
}

The media field accepts an array of storage paths (e.g., from /api/chat/upload). Images are sent to the LLM as data URIs. Audio files are transcribed via faster-whisper and the transcript is prepended to the message content.

The message is persisted to the session immediately (before the async agent loop processes it). This means a page refresh always shows the session and the user's message, even if the agent hasn't responded yet.

Response:

{
  "task_id": "string",
  "session_id": "string"
}

POST /api/chat/upload

Upload media files (images, audio). Accepts multipart form data. Files are stored in date-organized subdirectories under public/media/ (e.g., public/media/2026/02/26/) with a generated filename.

Request: multipart/form-data with one or more file fields.

Response:

{
  "paths": ["public/media/2026/02/26/abc123def456.jpg"]
}

The returned paths can be passed in the media field of POST /api/chat.

GET /api/chat/sessions

Response:

[
  {
    "key": "string",
    "created_at": "string",
    "updated_at": "string"
  }
]

GET /api/chat/sessions/{session_id}

The session_id is resolved using key resolution:

• If it contains :, used as the session key directly (e.g., web:abc123, heartbeat:heartbeat)
• Otherwise, prefixed with web: (standard user sessions)

Response:

{
  "key": "string",
  "messages": [],
  "created_at": "string",
  "updated_at": "string"
}

DELETE /api/chat/sessions/{session_id}

Uses the same key resolution as GET.

Response:

{
  "status": "deleted"
}

Tasks

GET /api/tasks

Returns all TODO and DOING tasks, plus DONE and ERROR tasks from the last 24 hours.

PATCH /api/tasks/{task_id}

Request body:

{
  "state": "TODO | DOING | DONE | ERROR"
}

Files

GET /api/files

Returns a recursive tree of the workspace directory (excluding hidden files, system files, and protected files like config.yml).

GET /api/files/{path}

Returns file info. The response format depends on the file type:

For text files (.md, .txt, .json, .yaml, .py, .js, .html, etc.):

{
  "path": "string",
  "type": "text",
  "content": "string"
}

For media and binary files (image, video, audio, binary):

{
  "path": "string",
  "type": "image | video | audio | binary",
  "mime": "string",
  "size": 0,
  "url": "string"
}

The url field points to /public/{path} for files under the public/ directory (no auth required, suitable for <img>, <video>, <audio> tags), or /api/files/download/{path} for other files.

POST /api/files/create/{path}

Creates an empty file at the specified path. Parent directories are created automatically.

Response:

{
  "status": "created"
}

POST /api/files/mkdir/{path}

Creates a directory at the specified path. Parent directories are created automatically.

Response:

{
  "status": "created"
}

POST /api/files/upload/{path}

Upload files to the specified directory. Accepts multipart form data. POST /api/files/upload uploads to the root directory.

Request: multipart/form-data with one or more file fields.

Response:

{
  "status": "ok",
  "paths": ["path/to/uploaded_file.txt"]
}

GET /api/files/download/{path}

Returns the raw file as a binary download. Requires authentication.

PUT /api/files/{path}

Request body:

{
  "content": "string"
}

DELETE /api/files/{path}

Deletes a file or directory. Directories are deleted recursively.

Response:

{
  "status": "deleted"
}

Public Files

No authentication required. Files under the project's public/ directory are served directly. This allows media files (images, video, audio) to be rendered in HTML5 tags without needing auth headers.

Skills

GET /api/skills

Response:

[
  {
    "name": "string",
    "description": "string",
    "always": "boolean",
    "requires": "string[]"
  }
]

GET /api/skills/{name}

Response:

{
  "name": "string",
  "content": "string"
}

Channels

GET /api/channels

Response:

{
  "web": {
    "running": "boolean"
  },
  "telegram": {
    "running": "boolean",
    "type": "string",
    "enabled": "boolean"
  }
}

PUT /api/channels/{name}

Request body:

{
  "config": {
    "credential": "string",
    "allowed_users": ["string"],
    "...": "..."
  }
}

POST /api/channels/{name}/start

Starts the channel. For Telegram, also persists enabled: true to config.yml so the channel auto-starts on the next server boot.

Response:

{
  "status": "started"
}

POST /api/channels/{name}/stop

Stops the channel. For Telegram, also persists enabled: false to config.yml so the channel stays stopped on the next server boot.

Response:

{
  "status": "stopped"
}

Credentials

GET /api/credentials

Response:

[
  {
    "name": "string",
    "type": "string",
    "...": "type-specific fields (sensitive values masked)"
  }
]

POST /api/credentials

Request body:

{
  "name": "string",
  "type": "string",
  "...": "type-specific fields"
}

PUT /api/credentials/{name}

Request body:

{
  "type": "string",
  "...": "type-specific fields"
}

DELETE /api/credentials/{name}

Response:

{
  "status": "deleted"
}

Providers

GET /api/providers

Response:

[
  {
    "name": "string",
    "configured": "boolean",
    "credential": "string",
    "has_key": "boolean",
    "base_url": "string",
    "request_headers": {},
    "request_options": {},
    "model_params": {}
  }
]

PUT /api/providers/{name}

Request body:

{
  "credential": "string",
  "base_url": "string",
  "request_headers": {},
  "request_options": {},
  "model_params": {}
}

Agents

GET /api/agents

Response:

[
  {
    "name": "string",
    "description": "string",
    "model": "string"
  }
]

Tools

GET /api/tools

Response:

[
  {
    "name": "string",
    "description": "string",
    "parameters": {}
  }
]

Forms

GET /api/forms

Returns form schema definitions used by the frontend's DynamicForm component to render configuration forms dynamically.

Each field in the schema has name, type, label, and optional required, placeholder, options (for select), and visible_when (conditional visibility).

Supported field types:

Response:

{
  "form_name": [
    { "name": "field_name", "type": "text", "label": "Field Label", "required": true }
  ]
}

Scheduler

POST /api/scheduler/jobs

Request body:

{
  "name": "string",
  "message": "string",
  "cron_expr": "string (optional)",
  "every_seconds": "number (optional)",
  "at": "string (optional)",
  "timezone": "string (optional)",
  "channel": "string (optional)",
  "to": "string (optional)"
}

Provide exactly one scheduling strategy: cron_expr, every_seconds, or at.

Config

GET /api/config/yaml

Returns the full configuration as a YAML string with sensitive values masked.

Response:

{
  "yaml": "string"
}

POST /api/config/validate

Validates a YAML configuration string against the Config schema.

Request body:

{
  "yaml": "string"
}

Response (valid):

{
  "valid": true
}

Response (invalid):

{
  "valid": false,
  "error": "string",
  "line": "number (optional)"
}

PATCH /api/config

Update multiple sections in a single call (one disk write).

Request body:

{
  "sections": {
    "bot": { "name": "MyBot" },
    "server": { "port": 9000 }
  }
}

PUT /api/config/{section}

Valid sections: bot, server, agents, image, web_client, tools, storage, cron, credentials, providers, advanced.

Request body:

{
  "data": {}
}

For the advanced section, the data field can contain a yaml key with the full YAML configuration string:

{
  "data": {
    "yaml": "bot:\n  name: MyBot\n..."
  }
}

POST /api/config/restart

Restarts the agent loop, channels, and cron scheduler. No request body required.

WebSocket

Connection

Connect to the WebSocket endpoint with a valid JWT token as a query parameter:

ws://host:port/ws?token=JWT_TOKEN

Events

Server to Client

chat:message

{
  "event": "chat:message",
  "data": {
    "content": "string",
    "chat_id": "string",
    "task_id": "string"
  }
}

chat:thinking

{
  "event": "chat:thinking",
  "data": {
    "task_id": "string",
    "chat_id": "string",
    "content": "string"
  }
}

chat:tool_use

{
  "event": "chat:tool_use",
  "data": {
    "task_id": "string",
    "chat_id": "string",
    "tool": "string",
    "description": "string"
  }
}

All chat:* events include chat_id so the frontend can filter messages by session. Only messages matching the active session should be displayed — others are silently ignored until the user switches to that session.

Client to Server

chat:send

Alternative to POST /api/chat. Sends a message through the WebSocket connection.

{
  "event": "chat:send",
  "data": {
    "message": "string",
    "session_id": "string (optional)",
    "metadata": {}
  }
}