Soulter
fc33b3eb68
* docs: transfer AstrBotDevs/AstrBot-docs to AstrBotDevs/AstrBot * refactor: reorder imports and improve type hints in sync_docs_to_wiki.py and upload_doc_images_to_r2.py * feat: add GitHub Actions workflow to sync wiki with documentation Co-authored-by: Soulter <37870767+Soulter@users.noreply.github.com> Co-authored-by: anka-afk <110004162+anka-afk@users.noreply.github.com> Co-authored-by: zouyonghe <62183434+zouyonghe@users.noreply.github.com> Co-authored-by: shuiping233 <49360196+shuiping233@users.noreply.github.com> Co-authored-by: LIghtJUNction <106986785+LIghtJUNction@users.noreply.github.com> Co-authored-by: Sjshi763 <179909421+Sjshi763@users.noreply.github.com> Co-authored-by: xiewoc <70128845+xiewoc@users.noreply.github.com> Co-authored-by: QingFeng-awa <151742581+QingFeng-awa@users.noreply.github.com> Co-authored-by: PaloMiku <96452465+PaloMiku@users.noreply.github.com> Co-authored-by: shangxueink <138397030+shangxueink@users.noreply.github.com> Co-authored-by: IGCrystal-A <244300990+IGCrystal-A@users.noreply.github.com> Co-authored-by: RC-CHN <67079377+RC-CHN@users.noreply.github.com> Co-authored-by: MC090610 <113341105+MC090610@users.noreply.github.com> Co-authored-by: Waterwzy <196913419+Waterwzy@users.noreply.github.com> Co-authored-by: Lanhuace-Wan <186303160+Lanhuace-Wan@users.noreply.github.com> Co-authored-by: LiAlH4qwq <61769640+LiAlH4qwq@users.noreply.github.com> Co-authored-by: HSOS6 <209910899+HSOS6@users.noreply.github.com> Co-authored-by: th-dd <162813557+th-dd@users.noreply.github.com> Co-authored-by: miaoxutao123 <81676466+miaoxutao123@users.noreply.github.com> Co-authored-by: nuomicici <143102889+nuomicici@users.noreply.github.com> Co-authored-by: nasyt233 <210103278+nasyt233@users.noreply.github.com> Co-authored-by: jlugjb <7426462+jlugjb@users.noreply.github.com> Co-authored-by: Raven95676 <176760093+Raven95676@users.noreply.github.com> Co-authored-by: Futureppo <180109455+Futureppo@users.noreply.github.com> Co-authored-by: MliKiowa <61873808+MliKiowa@users.noreply.github.com> Co-authored-by: Fridemn <150212937+Fridemn@users.noreply.github.com> Co-authored-by: BakaCookie520 <138355736+BakaCookie520@users.noreply.github.com> Co-authored-by: YumeYuka <125112916+YumeYuka@users.noreply.github.com> Co-authored-by: xming521 <32786500+xming521@users.noreply.github.com> Co-authored-by: ywh555hhh <121592812+ywh555hhh@users.noreply.github.com> Co-authored-by: stevessr <89645372+stevessr@users.noreply.github.com> Co-authored-by: roeseth <41995115+roeseth@users.noreply.github.com> Co-authored-by: ikun-1145141 <265925499+ikun-1145141@users.noreply.github.com> Co-authored-by: evpeople <54983536+evpeople@users.noreply.github.com> Co-authored-by: Yue-bin <60509781+Yue-bin@users.noreply.github.com> Co-authored-by: W1ndys <109416673+W1ndys@users.noreply.github.com> Co-authored-by: TheFurina <218887821+TheFurina@users.noreply.github.com> Co-authored-by: Seayon <12275933+Seayon@users.noreply.github.com> Co-authored-by: OnlyblackTea <38585636+OnlyblackTea@users.noreply.github.com> Co-authored-by: ocetars <74854972+ocetars@users.noreply.github.com> Co-authored-by: railgun19457 <117180744+railgun19457@users.noreply.github.com> Co-authored-by: JunieXD <107397009+JunieXD@users.noreply.github.com> Co-authored-by: advent259141 <197440256+advent259141@users.noreply.github.com> Co-authored-by: Doge2077 <91442300+Doge2077@users.noreply.github.com> Co-authored-by: Bocity <23430545+Bocity@users.noreply.github.com> Co-authored-by: Aurora-xk <192227833+Aurora-xk@users.noreply.github.com>
686 lines
17 KiB
JSON
686 lines
17 KiB
JSON
{
|
|
"openapi": "3.1.0",
|
|
"info": {
|
|
"title": "AstrBot Open API",
|
|
"version": "1.0.0",
|
|
"description": "Developer HTTP APIs for AstrBot. Use API Key authentication for /api/v1/* endpoints."
|
|
},
|
|
"servers": [
|
|
{
|
|
"url": "http://localhost:6185"
|
|
}
|
|
],
|
|
"tags": [
|
|
{
|
|
"name": "Open API",
|
|
"description": "Developer APIs authenticated by API Key"
|
|
}
|
|
],
|
|
"paths": {
|
|
"/api/v1/im/bots": {
|
|
"get": {
|
|
"tags": [
|
|
"Open API"
|
|
],
|
|
"summary": "List bot IDs",
|
|
"description": "Returns configured bot/platform IDs.",
|
|
"security": [
|
|
{
|
|
"ApiKeyHeader": []
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "OK",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ApiResponseBotList"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"401": {
|
|
"$ref": "#/components/responses/Unauthorized"
|
|
},
|
|
"403": {
|
|
"$ref": "#/components/responses/Forbidden"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/api/v1/file": {
|
|
"post": {
|
|
"tags": [
|
|
"Open API"
|
|
],
|
|
"summary": "Upload attachment file",
|
|
"description": "Upload a file and get attachment_id for later use in chat/message APIs.",
|
|
"security": [
|
|
{
|
|
"ApiKeyHeader": []
|
|
}
|
|
],
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"multipart/form-data": {
|
|
"schema": {
|
|
"type": "object",
|
|
"required": [
|
|
"file"
|
|
],
|
|
"properties": {
|
|
"file": {
|
|
"type": "string",
|
|
"format": "binary"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "OK",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ApiResponseUpload"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"401": {
|
|
"$ref": "#/components/responses/Unauthorized"
|
|
},
|
|
"403": {
|
|
"$ref": "#/components/responses/Forbidden"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/api/v1/chat": {
|
|
"post": {
|
|
"tags": [
|
|
"Open API"
|
|
],
|
|
"summary": "Send chat message (SSE)",
|
|
"description": "Send message to AstrBot chat pipeline and receive streaming SSE response. Reuses /api/chat/send behavior. If session_id/conversation_id is omitted, server will create a new UUID session_id.",
|
|
"security": [
|
|
{
|
|
"ApiKeyHeader": []
|
|
}
|
|
],
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ChatSendRequest"
|
|
},
|
|
"examples": {
|
|
"plain": {
|
|
"value": {
|
|
"message": "Hello",
|
|
"username": "alice",
|
|
"session_id": "my_session_001",
|
|
"enable_streaming": true
|
|
}
|
|
},
|
|
"multipartMessage": {
|
|
"value": {
|
|
"message": [
|
|
{
|
|
"type": "plain",
|
|
"text": "Please analyze this file"
|
|
},
|
|
{
|
|
"type": "file",
|
|
"attachment_id": "9a2f8c72-e7af-4c0e-b352-111111111111"
|
|
}
|
|
],
|
|
"username": "alice",
|
|
"session_id": "my_session_001",
|
|
"selected_provider": "openai_chat_completion",
|
|
"selected_model": "gpt-4.1-mini",
|
|
"enable_streaming": true
|
|
}
|
|
},
|
|
"withConfig": {
|
|
"value": {
|
|
"message": "Use a specific config for this session",
|
|
"username": "alice",
|
|
"session_id": "my_session_001",
|
|
"config_id": "default",
|
|
"enable_streaming": true
|
|
}
|
|
},
|
|
"autoSessionWithUsername": {
|
|
"value": {
|
|
"message": "hello",
|
|
"username": "alice",
|
|
"enable_streaming": true
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "SSE stream",
|
|
"content": {
|
|
"text/event-stream": {
|
|
"schema": {
|
|
"type": "string"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"401": {
|
|
"$ref": "#/components/responses/Unauthorized"
|
|
},
|
|
"403": {
|
|
"$ref": "#/components/responses/Forbidden"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/api/v1/chat/sessions": {
|
|
"get": {
|
|
"tags": [
|
|
"Open API"
|
|
],
|
|
"summary": "List chat sessions with pagination",
|
|
"description": "List chat sessions for the specified username.",
|
|
"security": [
|
|
{
|
|
"ApiKeyHeader": []
|
|
}
|
|
],
|
|
"parameters": [
|
|
{
|
|
"name": "page",
|
|
"in": "query",
|
|
"schema": {
|
|
"type": "integer",
|
|
"default": 1,
|
|
"minimum": 1
|
|
}
|
|
},
|
|
{
|
|
"name": "page_size",
|
|
"in": "query",
|
|
"schema": {
|
|
"type": "integer",
|
|
"default": 20,
|
|
"minimum": 1,
|
|
"maximum": 100
|
|
}
|
|
},
|
|
{
|
|
"name": "platform_id",
|
|
"in": "query",
|
|
"schema": {
|
|
"type": "string"
|
|
},
|
|
"description": "Optional platform filter"
|
|
},
|
|
{
|
|
"name": "username",
|
|
"in": "query",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string"
|
|
},
|
|
"description": "Target username."
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "OK",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ApiResponseChatSessions"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"401": {
|
|
"$ref": "#/components/responses/Unauthorized"
|
|
},
|
|
"403": {
|
|
"$ref": "#/components/responses/Forbidden"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/api/v1/im/message": {
|
|
"post": {
|
|
"tags": [
|
|
"Open API"
|
|
],
|
|
"summary": "Send proactive message to a platform bot",
|
|
"description": "Send message directly to platform bot by umo + message chain payload.",
|
|
"security": [
|
|
{
|
|
"ApiKeyHeader": []
|
|
}
|
|
],
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/SendMessageRequest"
|
|
},
|
|
"examples": {
|
|
"plain": {
|
|
"value": {
|
|
"umo": "webchat:FriendMessage:openapi_probe",
|
|
"message": "ping from api key"
|
|
}
|
|
},
|
|
"chain": {
|
|
"value": {
|
|
"umo": "webchat:FriendMessage:openapi_probe",
|
|
"message": [
|
|
{
|
|
"type": "plain",
|
|
"text": "hello"
|
|
},
|
|
{
|
|
"type": "image",
|
|
"attachment_id": "9a2f8c72-e7af-4c0e-b352-111111111111"
|
|
}
|
|
]
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "OK",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ApiResponseEmpty"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"401": {
|
|
"$ref": "#/components/responses/Unauthorized"
|
|
},
|
|
"403": {
|
|
"$ref": "#/components/responses/Forbidden"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/api/v1/configs": {
|
|
"get": {
|
|
"tags": [
|
|
"Open API"
|
|
],
|
|
"summary": "List available chat config files",
|
|
"description": "Returns all available AstrBot config files that can be selected by Chat API using config_id/config_name.",
|
|
"security": [
|
|
{
|
|
"ApiKeyHeader": []
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "OK",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ApiResponseChatConfigList"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"401": {
|
|
"$ref": "#/components/responses/Unauthorized"
|
|
},
|
|
"403": {
|
|
"$ref": "#/components/responses/Forbidden"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"components": {
|
|
"securitySchemes": {
|
|
"ApiKeyHeader": {
|
|
"type": "apiKey",
|
|
"in": "header",
|
|
"name": "X-API-Key",
|
|
"description": "Open API key. Authorization: Bearer <api_key> is also accepted."
|
|
}
|
|
},
|
|
"responses": {
|
|
"Unauthorized": {
|
|
"description": "Unauthorized"
|
|
},
|
|
"Forbidden": {
|
|
"description": "Forbidden"
|
|
}
|
|
},
|
|
"schemas": {
|
|
"ApiResponseEmpty": {
|
|
"type": "object",
|
|
"properties": {
|
|
"status": {
|
|
"type": "string",
|
|
"example": "ok"
|
|
},
|
|
"message": {
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
]
|
|
},
|
|
"data": {
|
|
"type": "object",
|
|
"additionalProperties": true
|
|
}
|
|
}
|
|
},
|
|
"ApiResponseBotList": {
|
|
"type": "object",
|
|
"properties": {
|
|
"status": {
|
|
"type": "string",
|
|
"example": "ok"
|
|
},
|
|
"message": {
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
]
|
|
},
|
|
"data": {
|
|
"type": "object",
|
|
"properties": {
|
|
"bot_ids": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "string"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"ApiResponseUpload": {
|
|
"type": "object",
|
|
"properties": {
|
|
"status": {
|
|
"type": "string",
|
|
"example": "ok"
|
|
},
|
|
"message": {
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
]
|
|
},
|
|
"data": {
|
|
"type": "object",
|
|
"properties": {
|
|
"attachment_id": {
|
|
"type": "string"
|
|
},
|
|
"filename": {
|
|
"type": "string"
|
|
},
|
|
"type": {
|
|
"type": "string"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"ApiResponseChatSessions": {
|
|
"type": "object",
|
|
"properties": {
|
|
"status": {
|
|
"type": "string",
|
|
"example": "ok"
|
|
},
|
|
"message": {
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
]
|
|
},
|
|
"data": {
|
|
"type": "object",
|
|
"properties": {
|
|
"sessions": {
|
|
"type": "array",
|
|
"items": {
|
|
"$ref": "#/components/schemas/ChatSessionItem"
|
|
}
|
|
},
|
|
"page": {
|
|
"type": "integer"
|
|
},
|
|
"page_size": {
|
|
"type": "integer"
|
|
},
|
|
"total": {
|
|
"type": "integer"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"ChatSessionItem": {
|
|
"type": "object",
|
|
"properties": {
|
|
"session_id": {
|
|
"type": "string"
|
|
},
|
|
"platform_id": {
|
|
"type": "string"
|
|
},
|
|
"creator": {
|
|
"type": "string"
|
|
},
|
|
"display_name": {
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
]
|
|
},
|
|
"is_group": {
|
|
"type": "integer"
|
|
},
|
|
"created_at": {
|
|
"type": "string",
|
|
"format": "date-time"
|
|
},
|
|
"updated_at": {
|
|
"type": "string",
|
|
"format": "date-time"
|
|
}
|
|
}
|
|
},
|
|
"MessagePart": {
|
|
"type": "object",
|
|
"properties": {
|
|
"type": {
|
|
"type": "string",
|
|
"enum": [
|
|
"plain",
|
|
"reply",
|
|
"image",
|
|
"record",
|
|
"file",
|
|
"video"
|
|
]
|
|
},
|
|
"text": {
|
|
"type": "string"
|
|
},
|
|
"message_id": {
|
|
"type": [
|
|
"string",
|
|
"integer"
|
|
]
|
|
},
|
|
"selected_text": {
|
|
"type": "string"
|
|
},
|
|
"attachment_id": {
|
|
"type": "string"
|
|
},
|
|
"filename": {
|
|
"type": "string"
|
|
},
|
|
"path": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
"required": [
|
|
"type"
|
|
]
|
|
},
|
|
"ChatSendRequest": {
|
|
"type": "object",
|
|
"required": [
|
|
"message",
|
|
"username"
|
|
],
|
|
"properties": {
|
|
"message": {
|
|
"oneOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "array",
|
|
"items": {
|
|
"$ref": "#/components/schemas/MessagePart"
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"session_id": {
|
|
"type": "string",
|
|
"description": "Optional chat session ID. If omitted (and conversation_id is also omitted), server creates a UUID automatically."
|
|
},
|
|
"conversation_id": {
|
|
"type": "string",
|
|
"description": "Alias of session_id."
|
|
},
|
|
"username": {
|
|
"type": "string",
|
|
"description": "Target username."
|
|
},
|
|
"selected_provider": {
|
|
"type": "string"
|
|
},
|
|
"selected_model": {
|
|
"type": "string"
|
|
},
|
|
"enable_streaming": {
|
|
"type": "boolean",
|
|
"default": true
|
|
},
|
|
"config_id": {
|
|
"type": "string",
|
|
"description": "Optional AstrBot config file ID. If provided, the chat session will use this config file. Use \"default\" to reset to default config."
|
|
},
|
|
"config_name": {
|
|
"type": "string",
|
|
"description": "Optional AstrBot config file name. Used only when config_id is not provided."
|
|
}
|
|
}
|
|
},
|
|
"SendMessageRequest": {
|
|
"type": "object",
|
|
"required": [
|
|
"umo",
|
|
"message"
|
|
],
|
|
"properties": {
|
|
"umo": {
|
|
"type": "string",
|
|
"description": "Unified message origin. Format: platform:message_type:session_id"
|
|
},
|
|
"message": {
|
|
"oneOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "array",
|
|
"items": {
|
|
"$ref": "#/components/schemas/MessagePart"
|
|
}
|
|
}
|
|
]
|
|
}
|
|
}
|
|
},
|
|
"ChatConfigFile": {
|
|
"type": "object",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string"
|
|
},
|
|
"name": {
|
|
"type": "string"
|
|
},
|
|
"path": {
|
|
"type": "string"
|
|
},
|
|
"is_default": {
|
|
"type": "boolean"
|
|
}
|
|
},
|
|
"required": [
|
|
"id",
|
|
"name",
|
|
"path",
|
|
"is_default"
|
|
]
|
|
},
|
|
"ApiResponseChatConfigList": {
|
|
"type": "object",
|
|
"properties": {
|
|
"status": {
|
|
"type": "string",
|
|
"example": "ok"
|
|
},
|
|
"message": {
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
]
|
|
},
|
|
"data": {
|
|
"type": "object",
|
|
"properties": {
|
|
"configs": {
|
|
"type": "array",
|
|
"items": {
|
|
"$ref": "#/components/schemas/ChatConfigFile"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|