Skip to content

zh dev openapi scopes

Jump to bottom
github-actions[bot] edited this page Aug 2, 2026 · 1 revision

API Scope 与接口对照

本页由 openspec/openapi-v1.yaml 自动生成。每个接口的基础权限来自 x-astrbot-scope；敏感操作还会列出需要显式授予的子权限。

bot

管理机器人及平台配置。

方法 接口 条件性敏感子权限
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

管理模型服务提供商和提供商源。

方法 接口 条件性敏感子权限
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

管理人格设定和人格文件夹。

方法 接口 条件性敏感子权限
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

主动发送 IM 消息，并查询机器人或平台标识。

方法 接口 条件性敏感子权限
GET /api/v1/im/bots —
POST /api/v1/im/messages —

config

管理配置文件、系统配置和通用配置，但不包含修改 admins_id 的能力。

  • 包含权限: bot、provider

  • 敏感子权限 config:edit_admin: 允许具有 config 权限的 Key 修改 admins_id。该子权限必须显式授予。

方法 接口 条件性敏感子权限
POST /api/v1/bot-types/{bot_type}/registration —
GET /api/v1/config-profiles —
POST /api/v1/config-profiles config: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-config config: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

调用对话能力，并管理 ChatUI 会话和项目。

  • 敏感子权限 chat:admin: 允许 username 使用 AstrBot 中已配置的管理员 ID。该子权限必须显式授予。
方法 接口 条件性敏感子权限
POST /api/v1/chat chat: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/ws chat:admin

data

管理对话记录和平台会话数据。

方法 接口 条件性敏感子权限
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

上传和下载对话附件。

方法 接口 条件性敏感子权限
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

管理插件、插件配置、插件源和插件市场数据。

方法 接口 条件性敏感子权限
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

管理 MCP 服务器配置和服务端同步。

方法 接口 条件性敏感子权限
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

管理 Skills、Skill 压缩包、Skill 文件和 Shipyard Neo Skill 流程。

方法 接口 条件性敏感子权限
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} —

Chinese

English

Clone this wiki locally