Skip to content

en dev openapi scopes

Jump to bottom
github-actions[bot] edited this page Sep 18, 2026 · 3 revisions

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.

Method Endpoint Conditional 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.

Method Endpoint Conditional 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.

Method Endpoint Conditional 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.

Method Endpoint Conditional 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.

Method Endpoint Conditional sensitive sub-scope
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

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.
Method Endpoint Conditional sensitive sub-scope
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

Manage conversations and platform-session data.

Method Endpoint Conditional sensitive sub-scope
GET /api/v1/conversations —
POST /api/v1/conversations/batch-delete —
POST /api/v1/conversations/export —
GET /api/v1/conversations/filter-options —
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.

Method Endpoint Conditional sensitive sub-scope
GET /api/v1/file —
POST /api/v1/file —
POST /api/v1/files —
GET /api/v1/files/content —
POST /api/v1/files/upload/abort —
POST /api/v1/files/upload/chunk —
POST /api/v1/files/upload/complete —
POST /api/v1/files/upload/init —
POST /api/v1/files/upload/status —
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.

Method Endpoint Conditional 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.

Method Endpoint Conditional 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.

Method Endpoint Conditional 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} —

Chinese

English

Clone this wiki locally