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/{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`	—
`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}`	—