{ "openapi": "3.0.3", "info": { "title": "LangBot API 与 API 密钥认证", "description": "LangBot 外部服务 API 文档。这些接口支持 API 密钥认证，\n供外部系统以编程方式访问 LangBot 资源。\n\n**认证方式：**\n- 用户令牌（通过 `Authorization: Bearer `）\n- API 密钥（通过 `X-API-Key: ` 或 `Authorization: Bearer `）\n\n本文档中的所有接口都同时支持这两种认证方式。\n", "version": "4.4.1", "contact": { "name": "LangBot", "url": "https://langbot.app" }, "license": { "name": "AGPL-3.0", "url": "https://github.com/langbot-app/LangBot/blob/master/LICENSE" } }, "servers": [ { "url": "http://localhost:5300", "description": "本地开发服务器" } ], "tags": [ { "name": "模型 - 大语言模型", "description": "大语言模型管理操作" }, { "name": "模型 - 向量模型", "description": "向量模型管理操作" }, { "name": "机器人", "description": "机器人实例管理操作" }, { "name": "流水线", "description": "流水线配置管理操作" }, { "name": "知识库", "description": "内置知识库管理操作" }, { "name": "文件", "description": "文件上传和管理操作" }, { "name": "插件", "description": "插件安装和管理操作" } ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "paths": { "/api/v1/provider/models/llm": { "get": { "tags": [ "模型 - 大语言模型" ], "summary": "列出所有大语言模型", "description": "获取所有已配置的大语言模型列表", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "成功响应", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "msg": { "type": "string", "example": "ok" }, "data": { "type": "object", "properties": { "models": { "type": "array", "items": { "$ref": "#/components/schemas/LLMModel" } } } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" } } }, "post": { "tags": [ "模型 - 大语言模型" ], "summary": "创建新的大语言模型", "description": "创建并配置一个新的大语言模型", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LLMModelCreate" } } } }, "responses": { "200": { "description": "模型创建成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "msg": { "type": "string", "example": "ok" }, "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000" } } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/provider/models/llm/{model_uuid}": { "get": { "tags": [ "模型 - 大语言模型" ], "summary": "获取指定的大语言模型", "description": "通过 UUID 获取指定大语言模型的详细信息", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/ModelUUID" } ], "responses": { "200": { "description": "成功响应", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "msg": { "type": "string", "example": "ok" }, "data": { "type": "object", "properties": { "model": { "$ref": "#/components/schemas/LLMModel" } } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" } } }, "put": { "tags": [ "模型 - 大语言模型" ], "summary": "更新大语言模型", "description": "更新现有大语言模型的配置", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/ModelUUID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LLMModelUpdate" } } } }, "responses": { "200": { "description": "模型更新成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" } } }, "delete": { "tags": [ "模型 - 大语言模型" ], "summary": "删除大语言模型", "description": "从系统中删除一个大语言模型", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/ModelUUID" } ], "responses": { "200": { "description": "模型删除成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" } } } }, "/api/v1/provider/models/llm/{model_uuid}/test": { "post": { "tags": [ "模型 - 大语言模型" ], "summary": "测试大语言模型", "description": "测试大语言模型的连接性和功能", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/ModelUUID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "要测试的模型配置" } } } }, "responses": { "200": { "description": "模型测试成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v1/provider/models/embedding": { "get": { "tags": [ "模型 - 向量模型" ], "summary": "列出所有向量模型", "description": "获取所有已配置的向量模型列表", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "成功响应", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "msg": { "type": "string", "example": "ok" }, "data": { "type": "object", "properties": { "models": { "type": "array", "items": { "$ref": "#/components/schemas/EmbeddingModel" } } } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" } } }, "post": { "tags": [ "模型 - 向量模型" ], "summary": "创建新的向量模型", "description": "创建并配置一个新的向量模型", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbeddingModelCreate" } } } }, "responses": { "200": { "description": "模型创建成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "msg": { "type": "string", "example": "ok" }, "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" } } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" } } } }, "/api/v1/provider/models/embedding/{model_uuid}": { "get": { "tags": [ "模型 - 向量模型" ], "summary": "获取指定的向量模型", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/ModelUUID" } ], "responses": { "200": { "description": "成功响应", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "msg": { "type": "string", "example": "ok" }, "data": { "type": "object", "properties": { "model": { "$ref": "#/components/schemas/EmbeddingModel" } } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" } } }, "put": { "tags": [ "模型 - 向量模型" ], "summary": "更新向量模型", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/ModelUUID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbeddingModelUpdate" } } } }, "responses": { "200": { "description": "模型更新成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" } } }, "delete": { "tags": [ "模型 - 向量模型" ], "summary": "删除向量模型", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/ModelUUID" } ], "responses": { "200": { "description": "模型删除成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" } } } }, "/api/v1/provider/models/embedding/{model_uuid}/test": { "post": { "tags": [ "模型 - 向量模型" ], "summary": "测试向量模型", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/ModelUUID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "模型测试成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" } } } }, "/api/v1/platform/bots": { "get": { "tags": [ "机器人" ], "summary": "列出所有机器人", "description": "获取所有已配置的机器人实例列表", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "成功响应", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "msg": { "type": "string", "example": "ok" }, "data": { "type": "object", "properties": { "bots": { "type": "array", "items": { "$ref": "#/components/schemas/Bot" } } } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" } } }, "post": { "tags": [ "机器人" ], "summary": "创建新的机器人", "description": "创建并配置一个新的机器人实例", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BotCreate" } } } }, "responses": { "200": { "description": "机器人创建成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "msg": { "type": "string", "example": "ok" }, "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" } } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" } } } }, "/api/v1/platform/bots/{bot_uuid}": { "get": { "tags": [ "机器人" ], "summary": "获取指定的机器人", "description": "获取指定机器人实例的详细信息", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "bot_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "机器人 UUID" } ], "responses": { "200": { "description": "成功响应", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "msg": { "type": "string", "example": "ok" }, "data": { "type": "object", "properties": { "bot": { "$ref": "#/components/schemas/Bot" } } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" } } }, "put": { "tags": [ "机器人" ], "summary": "更新机器人", "description": "更新现有机器人实例的配置", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "bot_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BotUpdate" } } } }, "responses": { "200": { "description": "机器人更新成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" } } }, "delete": { "tags": [ "机器人" ], "summary": "删除机器人", "description": "从系统中删除一个机器人实例", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "bot_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "机器人删除成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" } } } }, "/api/v1/platform/bots/{bot_uuid}/logs": { "post": { "tags": [ "机器人" ], "summary": "获取机器人事件日志", "description": "获取指定机器人的事件日志", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "bot_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "from_index": { "type": "integer", "default": -1, "description": "日志起始索引（-1 表示最新）" }, "max_count": { "type": "integer", "default": 10, "description": "要获取的最大日志数量" } } } } } }, "responses": { "200": { "description": "成功响应", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "msg": { "type": "string", "example": "ok" }, "data": { "type": "object", "properties": { "logs": { "type": "array", "items": { "type": "object" } }, "total_count": { "type": "integer" } } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" } } } }, "/api/v1/pipelines": { "get": { "tags": [ "流水线" ], "summary": "列出所有流水线", "description": "获取所有已配置的流水线列表", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "sort_by", "in": "query", "schema": { "type": "string", "default": "created_at" }, "description": "排序字段" }, { "name": "sort_order", "in": "query", "schema": { "type": "string", "enum": [ "ASC", "DESC" ], "default": "DESC" }, "description": "排序顺序" } ], "responses": { "200": { "description": "成功响应", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "msg": { "type": "string", "example": "ok" }, "data": { "type": "object", "properties": { "pipelines": { "type": "array", "items": { "$ref": "#/components/schemas/Pipeline" } } } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" } } }, "post": { "tags": [ "流水线" ], "summary": "创建新的流水线", "description": "创建并配置一个新的流水线", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PipelineCreate" } } } }, "responses": { "200": { "description": "流水线创建成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "msg": { "type": "string", "example": "ok" }, "data": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" } } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" } } } }, "/api/v1/pipelines/_/metadata": { "get": { "tags": [ "流水线" ], "summary": "获取流水线元数据", "description": "获取流水线的元数据和配置选项", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "成功响应", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "msg": { "type": "string", "example": "ok" }, "data": { "type": "object", "properties": { "configs": { "type": "object" } } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" } } } }, "/api/v1/pipelines/{pipeline_uuid}": { "get": { "tags": [ "流水线" ], "summary": "获取指定的流水线", "description": "获取指定流水线的详细信息", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "pipeline_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "成功响应", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "msg": { "type": "string", "example": "ok" }, "data": { "type": "object", "properties": { "pipeline": { "$ref": "#/components/schemas/Pipeline" } } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" } } }, "put": { "tags": [ "流水线" ], "summary": "更新流水线", "description": "更新现有流水线的配置", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "pipeline_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PipelineUpdate" } } } }, "responses": { "200": { "description": "流水线更新成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" } } }, "delete": { "tags": [ "流水线" ], "summary": "删除流水线", "description": "从系统中删除一个流水线", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "pipeline_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "流水线删除成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" } } } }, "/api/v1/pipelines/{pipeline_uuid}/extensions": { "get": { "tags": [ "流水线" ], "summary": "获取流水线扩展", "description": "获取流水线配置的扩展和插件", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "pipeline_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "成功响应", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "msg": { "type": "string", "example": "ok" }, "data": { "type": "object" } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" } } }, "put": { "tags": [ "流水线" ], "summary": "更新流水线扩展", "description": "更新流水线的扩展配置", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "pipeline_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "扩展更新成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" } } } }, "/api/v1/platform/bots/{bot_uuid}/send_message": { "post": { "tags": [ "机器人" ], "summary": "发送消息", "description": "通过指定机器人向指定目标发送消息", "operationId": "sendMessage", "parameters": [ { "name": "bot_uuid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "机器人 UUID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "target_type", "target_id", "message_chain" ], "properties": { "target_type": { "type": "string", "enum": [ "person", "group" ], "description": "目标类型" }, "target_id": { "type": "string", "description": "目标 ID（用户 ID 或群组 ID）" }, "message_chain": { "type": "array", "items": { "type": "object" }, "description": "消息链（MessageComponent 数组）" } } }, "examples": { "文本消息": { "value": { "target_type": "group", "target_id": "123456789", "message_chain": [ { "type": "Plain", "text": "Hello, World!" } ] } }, "图文消息": { "value": { "target_type": "person", "target_id": "987654321", "message_chain": [ { "type": "Plain", "text": "查看这张图片：" }, { "type": "Image", "url": "https://example.com/image.jpg" } ] } } } } } }, "responses": { "200": { "description": "发送成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "msg": { "type": "string", "example": "ok" }, "data": { "type": "object", "properties": { "sent": { "type": "boolean", "example": true } } } } } } } }, "400": { "description": "请求参数错误", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": -1 }, "msg": { "type": "string", "example": "target_type is required" } } } } } }, "500": { "description": "发送失败", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": -1 }, "msg": { "type": "string", "example": "Failed to send message: Bot not found" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/knowledge/bases": { "get": { "tags": [ "知识库" ], "summary": "获取所有知识库", "description": "获取所有内置知识库列表", "operationId": "listKnowledgeBases", "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "msg": { "type": "string", "example": "ok" }, "data": { "type": "object", "properties": { "bases": { "type": "array", "items": { "type": "object" } } } } } } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ] }, "post": { "tags": [ "知识库" ], "summary": "创建知识库", "description": "创建新的内置知识库", "operationId": "createKnowledgeBase", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "embedding_model_uuid" ], "properties": { "name": { "type": "string", "description": "知识库名称" }, "description": { "type": "string", "description": "知识库描述" }, "embedding_model_uuid": { "type": "string", "description": "向量模型 UUID" } } }, "example": { "name": "技术文档库", "description": "存储技术文档和API参考", "embedding_model_uuid": "uuid-of-embedding-model" } } } }, "responses": { "200": { "description": "创建成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "msg": { "type": "string", "example": "ok" }, "data": { "type": "object", "properties": { "uuid": { "type": "string" } } } } } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ] } }, "/api/v1/knowledge/bases/{kb_uuid}": { "get": { "tags": [ "知识库" ], "summary": "获取知识库详情", "description": "获取指定知识库的详细信息", "operationId": "getKnowledgeBase", "parameters": [ { "name": "kb_uuid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "知识库 UUID" } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "msg": { "type": "string", "example": "ok" }, "data": { "type": "object", "properties": { "base": { "type": "object" } } } } } } } }, "404": { "description": "知识库不存在", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": -1 }, "msg": { "type": "string", "example": "knowledge base not found" } } } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ] }, "put": { "tags": [ "知识库" ], "summary": "更新知识库", "description": "更新知识库信息", "operationId": "updateKnowledgeBase", "parameters": [ { "name": "kb_uuid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "知识库 UUID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" } } } } } }, "responses": { "200": { "description": "更新成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "msg": { "type": "string", "example": "ok" }, "data": { "type": "object" } } } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ] }, "delete": { "tags": [ "知识库" ], "summary": "删除知识库", "description": "删除指定的知识库", "operationId": "deleteKnowledgeBase", "parameters": [ { "name": "kb_uuid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "知识库 UUID" } ], "responses": { "200": { "description": "删除成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "msg": { "type": "string", "example": "ok" }, "data": { "type": "object" } } } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ] } }, "/api/v1/knowledge/bases/{kb_uuid}/files": { "get": { "tags": [ "知识库" ], "summary": "获取知识库文件列表", "description": "获取指定知识库中的所有文件", "operationId": "listKnowledgeBaseFiles", "parameters": [ { "name": "kb_uuid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "知识库 UUID" } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "msg": { "type": "string", "example": "ok" }, "data": { "type": "object", "properties": { "files": { "type": "array", "items": { "type": "object" } } } } } } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ] }, "post": { "tags": [ "知识库" ], "summary": "添加文件到知识库", "description": "将已上传的文件添加到知识库进行处理", "operationId": "addFileToKnowledgeBase", "parameters": [ { "name": "kb_uuid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "知识库 UUID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "file_id" ], "properties": { "file_id": { "type": "string", "description": "文件 ID（从文件上传接口获取）" } } }, "example": { "file_id": "document_abc123.pdf" } } } }, "responses": { "200": { "description": "添加成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "msg": { "type": "string", "example": "ok" }, "data": { "type": "object", "properties": { "task_id": { "type": "string", "description": "处理任务 ID" } } } } } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ] } }, "/api/v1/knowledge/bases/{kb_uuid}/files/{file_id}": { "delete": { "tags": [ "知识库" ], "summary": "从知识库删除文件", "description": "从指定知识库中删除文件", "operationId": "deleteFileFromKnowledgeBase", "parameters": [ { "name": "kb_uuid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "知识库 UUID" }, { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "文件 ID" } ], "responses": { "200": { "description": "删除成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "msg": { "type": "string", "example": "ok" }, "data": { "type": "object" } } } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ] } }, "/api/v1/knowledge/bases/{kb_uuid}/retrieve": { "post": { "tags": [ "知识库" ], "summary": "检索知识库", "description": "在知识库中搜索相关知识", "operationId": "retrieveKnowledge", "parameters": [ { "name": "kb_uuid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "知识库 UUID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "query" ], "properties": { "query": { "type": "string", "description": "查询文本" } } }, "example": { "query": "如何使用 LangBot 创建机器人？" } } } }, "responses": { "200": { "description": "检索成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "msg": { "type": "string", "example": "ok" }, "data": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object" } } } } } } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ] } }, "/api/v1/files/images": { "post": { "tags": [ "文件" ], "summary": "上传图片", "description": "上传图片文件（支持 jpg, jpeg, png, gif, webp 格式，最大 10MB）", "operationId": "uploadImage", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "图片文件" } } } } } }, "responses": { "200": { "description": "上传成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "msg": { "type": "string", "example": "ok" }, "data": { "type": "object", "properties": { "file_key": { "type": "string", "description": "文件密钥" } } } } } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/api/v1/files/documents": { "post": { "tags": [ "文件" ], "summary": "上传文档", "description": "上传文档文件（最大 10MB）", "operationId": "uploadDocument", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "文档文件" } } } } } }, "responses": { "200": { "description": "上传成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "msg": { "type": "string", "example": "ok" }, "data": { "type": "object", "properties": { "file_id": { "type": "string", "description": "文件 ID" } } } } } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/api/v1/plugins": { "get": { "tags": [ "插件" ], "summary": "获取所有插件", "description": "获取已安装的所有插件列表", "operationId": "listPlugins", "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "msg": { "type": "string", "example": "ok" }, "data": { "type": "object", "properties": { "plugins": { "type": "array", "items": { "type": "object" } } } } } } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/api/v1/plugins/{author}/{plugin_name}": { "get": { "tags": [ "插件" ], "summary": "获取插件详情", "description": "获取指定插件的详细信息", "operationId": "getPlugin", "parameters": [ { "name": "author", "in": "path", "required": true, "schema": { "type": "string" }, "description": "插件作者" }, { "name": "plugin_name", "in": "path", "required": true, "schema": { "type": "string" }, "description": "插件名称" } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "msg": { "type": "string", "example": "ok" }, "data": { "type": "object", "properties": { "plugin": { "type": "object" } } } } } } } } }, "security": [ { "BearerAuth": [] } ] }, "delete": { "tags": [ "插件" ], "summary": "删除插件", "description": "卸载指定的插件", "operationId": "deletePlugin", "parameters": [ { "name": "author", "in": "path", "required": true, "schema": { "type": "string" }, "description": "插件作者" }, { "name": "plugin_name", "in": "path", "required": true, "schema": { "type": "string" }, "description": "插件名称" }, { "name": "delete_data", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "是否删除插件数据" } ], "responses": { "200": { "description": "删除任务已创建", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "msg": { "type": "string", "example": "ok" }, "data": { "type": "object", "properties": { "task_id": { "type": "string" } } } } } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/api/v1/plugins/install/local": { "post": { "tags": [ "插件" ], "summary": "从本地文件安装插件", "description": "上传并安装插件包文件", "operationId": "installPluginLocal", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "插件包文件（.lbpkg 格式）" } } } } } }, "responses": { "200": { "description": "安装任务已创建", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "msg": { "type": "string", "example": "ok" }, "data": { "type": "object", "properties": { "task_id": { "type": "string" } } } } } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/api/v1/plugins/install/github": { "post": { "tags": [ "插件" ], "summary": "从 GitHub 安装插件", "description": "从 GitHub Release 安装插件", "operationId": "installPluginGitHub", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "asset_url" ], "properties": { "asset_url": { "type": "string", "description": "GitHub Release 资源下载 URL" }, "owner": { "type": "string", "description": "仓库所有者" }, "repo": { "type": "string", "description": "仓库名称" }, "release_tag": { "type": "string", "description": "Release 标签" } } } } } }, "responses": { "200": { "description": "安装任务已创建", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "msg": { "type": "string", "example": "ok" }, "data": { "type": "object", "properties": { "task_id": { "type": "string" } } } } } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/api/v1/plugins/install/marketplace": { "post": { "tags": [ "插件" ], "summary": "从插件市场安装", "description": "从 LangBot 插件市场安装插件", "operationId": "installPluginMarketplace", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "plugin_id": { "type": "string", "description": "插件 ID" } } } } } }, "responses": { "200": { "description": "安装任务已创建", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "msg": { "type": "string", "example": "ok" }, "data": { "type": "object", "properties": { "task_id": { "type": "string" } } } } } } } } }, "security": [ { "BearerAuth": [] } ] } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "使用 X-API-Key 请求头进行 API 密钥认证。\n示例：`X-API-Key: lbk_your_api_key_here`\n" }, "BearerAuth": { "type": "http", "scheme": "bearer", "description": "Bearer 令牌认证。可以是用户 JWT 令牌或 API 密钥。\n示例：`Authorization: Bearer `\n" } }, "parameters": { "ModelUUID": { "name": "model_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "模型 UUID" } }, "schemas": { "LLMModel": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string", "example": "GPT-4" }, "description": { "type": "string", "example": "OpenAI GPT-4 model" }, "requester": { "type": "string", "example": "openai-chat-completions" }, "requester_config": { "type": "object", "properties": { "model": { "type": "string", "example": "gpt-4" }, "args": { "type": "object" } } }, "api_keys": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "keys": { "type": "array", "items": { "type": "string" } } } } }, "abilities": { "type": "array", "items": { "type": "string" }, "example": [ "chat", "vision" ] }, "extra_args": { "type": "object" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "LLMModelCreate": { "type": "object", "required": [ "name", "requester", "requester_config", "api_keys" ], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "requester": { "type": "string" }, "requester_config": { "type": "object" }, "api_keys": { "type": "array", "items": { "type": "object" } }, "abilities": { "type": "array", "items": { "type": "string" } }, "extra_args": { "type": "object" } } }, "LLMModelUpdate": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "requester_config": { "type": "object" }, "api_keys": { "type": "array", "items": { "type": "object" } }, "abilities": { "type": "array", "items": { "type": "string" } }, "extra_args": { "type": "object" } } }, "EmbeddingModel": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": "string" }, "requester": { "type": "string" }, "requester_config": { "type": "object" }, "api_keys": { "type": "array", "items": { "type": "object" } }, "extra_args": { "type": "object" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "EmbeddingModelCreate": { "type": "object", "required": [ "name", "requester", "requester_config", "api_keys" ], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "requester": { "type": "string" }, "requester_config": { "type": "object" }, "api_keys": { "type": "array", "items": { "type": "object" } }, "extra_args": { "type": "object" } } }, "EmbeddingModelUpdate": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "requester_config": { "type": "object" }, "api_keys": { "type": "array", "items": { "type": "object" } }, "extra_args": { "type": "object" } } }, "Bot": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "adapter": { "type": "string", "example": "telegram" }, "config": { "type": "object" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "BotCreate": { "type": "object", "required": [ "name", "adapter", "config" ], "properties": { "name": { "type": "string" }, "adapter": { "type": "string" }, "config": { "type": "object" } } }, "BotUpdate": { "type": "object", "properties": { "name": { "type": "string" }, "config": { "type": "object" } } }, "Pipeline": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "config": { "type": "object" }, "is_default": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "PipelineCreate": { "type": "object", "required": [ "name", "config" ], "properties": { "name": { "type": "string" }, "config": { "type": "object" } } }, "PipelineUpdate": { "type": "object", "properties": { "name": { "type": "string" }, "config": { "type": "object" } } }, "SuccessResponse": { "type": "object", "properties": { "code": { "type": "integer", "example": 0 }, "msg": { "type": "string", "example": "ok" }, "data": { "type": "object", "nullable": true } } }, "ErrorResponse": { "type": "object", "properties": { "code": { "type": "integer", "example": -1 }, "msg": { "type": "string", "example": "错误消息" } } } }, "responses": { "UnauthorizedError": { "description": "需要认证或凭据无效", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_auth": { "value": { "code": -1, "msg": "未提供有效认证（需要用户令牌或 API 密钥）" } }, "invalid_key": { "value": { "code": -1, "msg": "无效的 API 密钥" } } } } } }, "NotFoundError": { "description": "资源未找到", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": -1, "msg": "资源未找到" } } } }, "InternalServerError": { "description": "内部服务器错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": -2, "msg": "内部服务器错误" } } } } } } }