{ "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:7860" } ], "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 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" } } } } } } } } }