opensource/AstrBot
3
0
Fork 0
mirror of https://github.com/AstrBotDevs/AstrBot.git synced 2026-10-16 15:06:04 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
8831d9502575f0aa6fbe5a2f77339b3e94954819
AstrBot/docs/en/dev/openapi-scopes.md
T
Soulter 8831d95025 feat(dashboard): scoped path-token auth for plugin views and complete the views rename (#10415) 
* refactor(dashboard): complete the plugin pages to views rename

Finish the remaining Pages -> Views rename on the dashboard:

- Fix the plugin card "Open View" button crash by pointing
  openPluginWebui at the renamed PluginView route
- Rename PluginPagePage.vue to PluginViewPage.vue and update its
  internals (loadPluginView, pluginViewTitle, .plugin-view-* classes)
- Rename openPluginWebui -> openPluginView and the open-webui emit to
  open-view; pluginPageTitle/Description -> pluginViewTitle/Description;
  isPluginPageRoute -> isPluginViewRoute
- Rename i18n keys (pluginWebui -> pluginView, openWebui -> openView,
  pluginPageType -> pluginViewType, messages) across en/zh/ja/ru locales

The postMessage bridge channel name (astrbot-plugin-page) is kept
unchanged because it is part of the wire protocol shared with
plugin_page_bridge.js.

* feat(dashboard): authenticate plugin view assets with scoped path tokens

Serve plugin view assets from
/api/v1/plugins/{id}/views/{page}/_t/{token}/... so the scoped token
travels in the URL path. Relative URLs inside the view then inherit the
token through normal path resolution, which removes the need for
server-side HTML/CSS/JS URL rewriting on this route.

- Add the _t routes with a require_plugin_view_token dependency
  (v1 paths bypass the dashboard auth middleware)
- Extend the plugin page asset token to a session-length TTL (7 days,
  aligned with the dashboard session) with a page_session purpose claim,
  still scoped to a single plugin and page
- Serialize the view entry content_path as the _t URL, keeping the
  asset_token query for plugins that parse location.search
- Keep the legacy /api/plugin/page/content/...?asset_token= form working
  during the transition
- Rename the OpenAPI tag Plugin Pages -> Plugin Views, document the new
  route, regenerate the frontend API client, and update the zh/en
  plugin-pages docs

* refactor(dashboard): remove the legacy plugin page content route and URL rewriting

The path-token view route makes the compatibility surface unnecessary:

- Drop /api/plugin/page/content/... (query asset_token form)
- Drop the redundant authenticated asset routes /plugins/page/assets,
  /plugins/view/assets, and /plugins/{id}/(pages|views)/{page}/assets/...
  which had no callers outside the generated client
- Remove the HTML/CSS/JS URL rewriting helpers; view assets are always
  served raw and only HTML gets bridge SDK injection plus theme handling
- Slim PluginPageAuth down to the bridge SDK endpoint, the only
  non-v1 path still authenticating scoped query tokens
- serialize_plugin_page no longer falls back to the legacy content path
- Update the plugin-pages docs (zh/en) and the OpenAPI spec, and
  regenerate the frontend API client

* refactor(dashboard): drop legacy plugin page API aliases

Remove the page-named plugin view API aliases now that the views rename
is complete and legacy compatibility is intentionally dropped:

- DELETE /api/v1/plugins/page(s) and /plugins/{plugin_id}/pages{,/{page_name}}
  aliases; /plugins/view(s) and /plugins/{plugin_id}/views{,/{page_name}}
  are the only entry config routes
- Remove the unused /api/v1/plugins/page-bridge-sdk.js route; the live
  bridge SDK stays at /api/plugin/page/bridge-sdk.js
- Dashboard calls the view-named endpoints; regenerate the API client
  and the OpenAPI scopes docs

* refactor(dashboard): keep plugin page APIs as deprecated view aliases

Restore the page-named plugin view routes removed in the previous commit
and keep them for a transition period, with view as the canonical API:

- /plugins/page(s) and /plugins/{plugin_id}/pages{,/{page_name}} serve as
  aliases of the corresponding /views routes (same handlers)
- The OpenAPI spec marks the page operations deprecated and points new
  clients at the view routes; the v1 page-bridge-sdk.js route is restored
- The dashboard keeps calling the view endpoints by default

* refactor(dashboard): rename the plugin view path parameter to view_name

The view entry and path-token asset routes now use {view_name} instead of
{page_name} in the OpenAPI-visible path, and the service layer renames its
internal page_name variables to match. Wire-compatible surfaces stay
unchanged: the page_name JWT claim, the pageName JSON field, query
parameters, and the deprecated /pages aliases. Error messages and the
plugin view docs (zh/en) complete the Page to View rename.
2026-10-06 18:18:22 +08:00

14 KiB
Raw Blame History

outline
outline
deep

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/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/view —
GET /api/v1/plugins/views —
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/{view_name} —
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 —
GET /api/v1/plugins/{plugin_id}/views —
GET /api/v1/plugins/{plugin_id}/views/{view_name} —

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} —
Reference in New Issue View Git Blame Copy Permalink