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} | — |