AstrBot

English

简体中文

English

简体中文

Toggle dark mode

Intro & DeployMessaging PlatformsAI IntegrationUsageDevelopment

API Scope–Endpoint Reference ​

This page is generated from openspec/openapi-v1.yaml. Each endpoint's base permission comes from x-astrbot-scope; sensitive operations also list the sub-scope that must be granted explicitly.

bot ​

Manage bot and platform configurations.

MethodEndpointConditional sensitive sub-scope
GET/api/v1/bot-types—
GET/api/v1/bots—
POST/api/v1/bots—
GET/api/v1/bots/by-id—
PUT/api/v1/bots/by-id—
DELETE/api/v1/bots/by-id—
PATCH/api/v1/bots/enabled—
GET/api/v1/bots/stats—
POST/api/v1/bots/test—
GET/api/v1/bots/{bot_id}—
PUT/api/v1/bots/{bot_id}—
DELETE/api/v1/bots/{bot_id}—
PATCH/api/v1/bots/{bot_id}/enabled—
POST/api/v1/bots/{bot_id}/test—

provider ​

Manage model providers and provider sources.

MethodEndpointConditional sensitive sub-scope
GET/api/v1/provider-sources—
POST/api/v1/provider-sources—
GET/api/v1/provider-sources/by-id—
PUT/api/v1/provider-sources/by-id—
DELETE/api/v1/provider-sources/by-id—
GET/api/v1/provider-sources/models—
GET/api/v1/provider-sources/providers—
POST/api/v1/provider-sources/providers—
GET/api/v1/provider-sources/{source_id}—
PUT/api/v1/provider-sources/{source_id}—
DELETE/api/v1/provider-sources/{source_id}—
GET/api/v1/provider-sources/{source_id}/models—
GET/api/v1/provider-sources/{source_id}/providers—
POST/api/v1/provider-sources/{source_id}/providers—
GET/api/v1/providers—
POST/api/v1/providers—
GET/api/v1/providers/by-id—
PUT/api/v1/providers/by-id—
DELETE/api/v1/providers/by-id—
POST/api/v1/providers/embedding-dimension—
PATCH/api/v1/providers/enabled—
GET/api/v1/providers/schema—
POST/api/v1/providers/test—
GET/api/v1/providers/{provider_id}—
PUT/api/v1/providers/{provider_id}—
DELETE/api/v1/providers/{provider_id}—
POST/api/v1/providers/{provider_id}/embedding-dimension—
PATCH/api/v1/providers/{provider_id}/enabled—
POST/api/v1/providers/{provider_id}/test—

persona ​

Manage personas and persona folders.

MethodEndpointConditional sensitive sub-scope
GET/api/v1/persona-folders—
POST/api/v1/persona-folders—
PUT/api/v1/persona-folders/{folder_id}—
DELETE/api/v1/persona-folders/{folder_id}—
GET/api/v1/personas—
POST/api/v1/personas—
GET/api/v1/personas/by-id—
PUT/api/v1/personas/by-id—
DELETE/api/v1/personas/by-id—
POST/api/v1/personas/move—
POST/api/v1/personas/reorder—
GET/api/v1/personas/tree—
GET/api/v1/personas/{persona_id}—
PUT/api/v1/personas/{persona_id}—
DELETE/api/v1/personas/{persona_id}—

im ​

Send proactive IM messages and query bot or platform identifiers.

MethodEndpointConditional sensitive sub-scope
GET/api/v1/im/bots—
POST/api/v1/im/messages—

config ​

Manage configuration profiles, system configuration, and shared configuration, excluding changes to admins_id.

  • Includes: bot, provider

  • Sensitive sub-scope config:edit_admin: Allow a config-scoped key to change admins_id. This sub-scope must be granted explicitly.

MethodEndpointConditional sensitive sub-scope
POST/api/v1/bot-types/{bot_type}/registration—
GET/api/v1/config-profiles—
POST/api/v1/config-profilesconfig:edit_admin
GET/api/v1/config-profiles/schema—
GET/api/v1/config-profiles/{config_id}—
PUT/api/v1/config-profiles/{config_id}config:edit_admin
PATCH/api/v1/config-profiles/{config_id}—
DELETE/api/v1/config-profiles/{config_id}—
GET/api/v1/config-routes—
PUT/api/v1/config-routes—
PUT/api/v1/config-routes/{umo}—
DELETE/api/v1/config-routes/{umo}—
GET/api/v1/subagents/available-tools—
GET/api/v1/subagents/config—
PUT/api/v1/subagents/config—
GET/api/v1/system-config—
PUT/api/v1/system-configconfig:edit_admin
GET/api/v1/system-config/runtime—
GET/api/v1/system-config/schema—
GET/api/v1/t2i/templates—
POST/api/v1/t2i/templates—
GET/api/v1/t2i/templates/active—
PUT/api/v1/t2i/templates/active—
POST/api/v1/t2i/templates/default/reset—
GET/api/v1/t2i/templates/{name}—
PUT/api/v1/t2i/templates/{name}—
DELETE/api/v1/t2i/templates/{name}—

chat ​

Use chat capabilities and manage ChatUI sessions and projects.

  • Sensitive sub-scope chat:admin: Allow username to use a configured AstrBot administrator ID. This sub-scope must be granted explicitly.
MethodEndpointConditional sensitive sub-scope
POST/api/v1/chatchat:admin
GET/api/v1/chat/configs—
GET/api/v1/chat/projects—
POST/api/v1/chat/projects—
DELETE/api/v1/chat/projects/sessions/{session_id}—
GET/api/v1/chat/projects/{project_id}—
PATCH/api/v1/chat/projects/{project_id}—
DELETE/api/v1/chat/projects/{project_id}—
GET/api/v1/chat/projects/{project_id}/sessions—
POST/api/v1/chat/projects/{project_id}/sessions/{session_id}—
GET/api/v1/chat/projects/{project_id}/workspace/file—
GET/api/v1/chat/projects/{project_id}/workspace/file/download—
GET/api/v1/chat/projects/{project_id}/workspace/files—
GET/api/v1/chat/runs/{run_id}/stream—
GET/api/v1/chat/sessions—
POST/api/v1/chat/sessions/batch-delete—
GET/api/v1/chat/sessions/new—
GET/api/v1/chat/sessions/{session_id}—
PATCH/api/v1/chat/sessions/{session_id}—
DELETE/api/v1/chat/sessions/{session_id}—
PATCH/api/v1/chat/sessions/{session_id}/messages/{message_id}—
POST/api/v1/chat/sessions/{session_id}/messages/{message_id}/regenerate—
POST/api/v1/chat/sessions/{session_id}/stop—
POST/api/v1/chat/threads—
GET/api/v1/chat/threads/{thread_id}—
DELETE/api/v1/chat/threads/{thread_id}—
POST/api/v1/chat/threads/{thread_id}/messages—
GET/api/v1/chat/wschat:admin

data ​

Manage conversations and platform-session data.

MethodEndpointConditional sensitive sub-scope
GET/api/v1/conversations—
POST/api/v1/conversations/batch-delete—
POST/api/v1/conversations/export—
GET/api/v1/conversations/{conversation_id}—
PATCH/api/v1/conversations/{conversation_id}—
DELETE/api/v1/conversations/{conversation_id}—
PUT/api/v1/conversations/{conversation_id}/messages—
GET/api/v1/session-groups—
POST/api/v1/session-groups—
PUT/api/v1/session-groups/{group_id}—
DELETE/api/v1/session-groups/{group_id}—
GET/api/v1/sessions—
GET/api/v1/sessions/active-umos—
PATCH/api/v1/sessions/provider—
GET/api/v1/sessions/rules—
POST/api/v1/sessions/rules—
POST/api/v1/sessions/rules/delete—
PATCH/api/v1/sessions/service—

file ​

Upload and download chat attachments.

MethodEndpointConditional sensitive sub-scope
GET/api/v1/file—
POST/api/v1/file—
POST/api/v1/files—
GET/api/v1/files/content—
GET/api/v1/files/{attachment_id}—
DELETE/api/v1/files/{attachment_id}—
GET/api/v1/files/{attachment_id}/content—

plugin ​

Manage plugins, plugin configuration, plugin sources, and marketplace data.

MethodEndpointConditional sensitive sub-scope
GET/api/v1/plugin-sources—
POST/api/v1/plugin-sources—
PUT/api/v1/plugin-sources—
DELETE/api/v1/plugin-sources/by-id—
DELETE/api/v1/plugin-sources/{source_id}—
GET/api/v1/plugins—
GET/api/v1/plugins/by-id—
DELETE/api/v1/plugins/by-id—
GET/api/v1/plugins/changelog—
GET/api/v1/plugins/config—
PUT/api/v1/plugins/config—
GET/api/v1/plugins/config-files—
POST/api/v1/plugins/config-files—
DELETE/api/v1/plugins/config-files—
GET/api/v1/plugins/config/schema—
PATCH/api/v1/plugins/enabled—
GET/api/v1/plugins/extensions/{plugin_path}—
POST/api/v1/plugins/extensions/{plugin_path}—
PUT/api/v1/plugins/extensions/{plugin_path}—
PATCH/api/v1/plugins/extensions/{plugin_path}—
DELETE/api/v1/plugins/extensions/{plugin_path}—
GET/api/v1/plugins/failed—
DELETE/api/v1/plugins/failed/{plugin_id}—
POST/api/v1/plugins/failed/{plugin_id}/reload—
POST/api/v1/plugins/install/git—
POST/api/v1/plugins/install/github—
POST/api/v1/plugins/install/upload—
POST/api/v1/plugins/install/url—
GET/api/v1/plugins/market—
GET/api/v1/plugins/market/categories—
GET/api/v1/plugins/page—
GET/api/v1/plugins/page-bridge-sdk.js—
GET/api/v1/plugins/page/assets—
GET/api/v1/plugins/pages—
GET/api/v1/plugins/readme—
POST/api/v1/plugins/reload—
POST/api/v1/plugins/update—
POST/api/v1/plugins/validate/repo—
POST/api/v1/plugins/version-support/check—
GET/api/v1/plugins/{plugin_id}—
DELETE/api/v1/plugins/{plugin_id}—
GET/api/v1/plugins/{plugin_id}/changelog—
GET/api/v1/plugins/{plugin_id}/config—
PUT/api/v1/plugins/{plugin_id}/config—
DELETE/api/v1/plugins/{plugin_id}/config-files—
GET/api/v1/plugins/{plugin_id}/config-files/{config_key}—
POST/api/v1/plugins/{plugin_id}/config-files/{config_key}—
GET/api/v1/plugins/{plugin_id}/config/schema—
PATCH/api/v1/plugins/{plugin_id}/enabled—
PUT/api/v1/plugins/{plugin_id}/log-level—
GET/api/v1/plugins/{plugin_id}/pages—
GET/api/v1/plugins/{plugin_id}/pages/{page_name}—
GET/api/v1/plugins/{plugin_id}/pages/{page_name}/assets/{asset_path}—
GET/api/v1/plugins/{plugin_id}/readme—
POST/api/v1/plugins/{plugin_id}/reload—
POST/api/v1/plugins/{plugin_id}/source—
POST/api/v1/plugins/{plugin_id}/update—

mcp ​

Manage MCP server configuration and provider synchronization.

MethodEndpointConditional sensitive sub-scope
POST/api/v1/mcp/providers/modelscope/sync—
GET/api/v1/mcp/servers—
POST/api/v1/mcp/servers—
PUT/api/v1/mcp/servers/by-name—
DELETE/api/v1/mcp/servers/by-name—
PATCH/api/v1/mcp/servers/enabled—
POST/api/v1/mcp/servers/test—
PUT/api/v1/mcp/servers/{server_name}—
DELETE/api/v1/mcp/servers/{server_name}—
PATCH/api/v1/mcp/servers/{server_name}/enabled—
POST/api/v1/mcp/servers/{server_name}/test—

skill ​

Manage Skills, archives, files, and Shipyard Neo Skill workflows.

MethodEndpointConditional sensitive sub-scope
GET/api/v1/skills—
POST/api/v1/skills—
GET/api/v1/skills/archive—
POST/api/v1/skills/batch—
PATCH/api/v1/skills/by-name—
DELETE/api/v1/skills/by-name—
GET/api/v1/skills/file—
PUT/api/v1/skills/file—
GET/api/v1/skills/files—
GET/api/v1/skills/neo/candidates—
POST/api/v1/skills/neo/candidates/delete—
POST/api/v1/skills/neo/evaluate—
GET/api/v1/skills/neo/payload—
POST/api/v1/skills/neo/promote—
GET/api/v1/skills/neo/releases—
POST/api/v1/skills/neo/releases/delete—
POST/api/v1/skills/neo/rollback—
POST/api/v1/skills/neo/sync—
PATCH/api/v1/skills/{skill_name}—
DELETE/api/v1/skills/{skill_name}—
GET/api/v1/skills/{skill_name}/archive—
GET/api/v1/skills/{skill_name}/files—
GET/api/v1/skills/{skill_name}/files/{file_path}—
PUT/api/v1/skills/{skill_name}/files/{file_path}—

Deployed on Rainyun Logo