{ "openapi": "3.0.3", "info": { "title": "LangBot API with API Key Authentication", "description": "LangBot External Service API Documentation. These interfaces support API key authentication for external systems to programmatically access LangBot resources.\n\n**Authentication Methods:**\n- User Token (via `Authorization: Bearer `)\n- API Key (via `X-API-Key: ` or `Authorization: Bearer `)\n\nAll interfaces in this documentation support both authentication methods.\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": "Local development server" } ], "tags": [ { "name": "Models - LLM", "description": "Large Language Model management operations" }, { "name": "Models - Embeddings", "description": "Embedding model management operations" }, { "name": "Bots", "description": "Bot instance management operations" }, { "name": "Pipelines", "description": "Pipeline configuration management operations" }, { "name": "Knowledge Bases", "description": "Built-in knowledge base management operations" }, { "name": "Files", "description": "File upload and management operations" }, { "name": "Plugins", "description": "Plugin installation and management operations" } ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "paths": { "/api/v1/provider/models/llm": { "get": { "tags": [ "Models - LLM" ], "summary": "List all LLM models", "description": "Retrieve a list of all configured LLM models", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "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": [ "Models - LLM" ], "summary": "Create a new LLM model", "description": "Create and configure a new LLM model", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LLMModelCreate" } } } }, "responses": { "200": { "description": "Model created successfully", "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": [ "Models - LLM" ], "summary": "Get a specific LLM model", "description": "Retrieve details of a specific LLM model by UUID", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/ModelUUID" } ], "responses": { "200": { "description": "Successful response", "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": [ "Models - LLM" ], "summary": "Update an LLM model", "description": "Update the configuration of an existing LLM model", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/ModelUUID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LLMModelUpdate" } } } }, "responses": { "200": { "description": "Model updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" } } }, "delete": { "tags": [ "Models - LLM" ], "summary": "Delete an LLM model", "description": "Remove an LLM model from the system", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/ModelUUID" } ], "responses": { "200": { "description": "Model deleted successfully", "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": [ "Models - LLM" ], "summary": "Test an LLM model", "description": "Test the connectivity and functionality of an LLM model", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/ModelUUID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Model configuration to test" } } } }, "responses": { "200": { "description": "Model test successful", "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": [ "Models - Embedding" ], "summary": "List all embedding models", "description": "Retrieve a list of all configured embedding models", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "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": [ "Models - Embedding" ], "summary": "Create a new embedding model", "description": "Create and configure a new embedding model", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbeddingModelCreate" } } } }, "responses": { "200": { "description": "Model created successfully", "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": [ "Models - Embedding" ], "summary": "Get a specific embedding model", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/ModelUUID" } ], "responses": { "200": { "description": "Successful response", "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": [ "Models - Embedding" ], "summary": "Update an embedding model", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/ModelUUID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmbeddingModelUpdate" } } } }, "responses": { "200": { "description": "Model updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" } } }, "delete": { "tags": [ "Models - Embedding" ], "summary": "Delete an embedding model", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/ModelUUID" } ], "responses": { "200": { "description": "Model deleted successfully", "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": [ "Models - Embedding" ], "summary": "Test an embedding model", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/ModelUUID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Model test successful", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" } } } }, "/api/v1/platform/bots": { "get": { "tags": [ "Bots" ], "summary": "List all bots", "description": "Retrieve a list of all configured bot instances", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "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": [ "Bots" ], "summary": "Create a new bot", "description": "Create and configure a new bot instance", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BotCreate" } } } }, "responses": { "200": { "description": "Bot created successfully", "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": [ "Bots" ], "summary": "Get a specific bot", "description": "Retrieve details of a specific bot instance", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "bot_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Bot UUID" } ], "responses": { "200": { "description": "Successful response", "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": [ "Bots" ], "summary": "Update a bot", "description": "Update the configuration of an existing bot instance", "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": "Bot updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" } } }, "delete": { "tags": [ "Bots" ], "summary": "Delete a bot", "description": "Remove a bot instance from the system", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "bot_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Bot deleted successfully", "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": [ "Bots" ], "summary": "Get bot event logs", "description": "Retrieve event logs for a specific bot", "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": "Starting index for logs (-1 for latest)" }, "max_count": { "type": "integer", "default": 10, "description": "Maximum number of logs to retrieve" } } } } } }, "responses": { "200": { "description": "Successful response", "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": [ "Pipelines" ], "summary": "List all pipelines", "description": "Retrieve a list of all configured pipelines", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "sort_by", "in": "query", "schema": { "type": "string", "default": "created_at" }, "description": "Field to sort by" }, { "name": "sort_order", "in": "query", "schema": { "type": "string", "enum": [ "ASC", "DESC" ], "default": "DESC" }, "description": "Sort order" } ], "responses": { "200": { "description": "Successful response", "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": [ "Pipelines" ], "summary": "Create a new pipeline", "description": "Create and configure a new pipeline", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PipelineCreate" } } } }, "responses": { "200": { "description": "Pipeline created successfully", "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": [ "Pipelines" ], "summary": "Get pipeline metadata", "description": "Retrieve metadata and configuration options for pipelines", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "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": [ "Pipelines" ], "summary": "Get a specific pipeline", "description": "Retrieve details of a specific pipeline", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "pipeline_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful response", "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": [ "Pipelines" ], "summary": "Update a pipeline", "description": "Update the configuration of an existing pipeline", "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": "Pipeline updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" } } }, "delete": { "tags": [ "Pipelines" ], "summary": "Delete a pipeline", "description": "Remove a pipeline from the system", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "pipeline_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Pipeline deleted successfully", "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": [ "Pipelines" ], "summary": "Get pipeline extensions", "description": "Retrieve extensions and plugins configured for a pipeline", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "parameters": [ { "name": "pipeline_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful response", "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": [ "Pipelines" ], "summary": "Update pipeline extensions", "description": "Update the extensions configuration for a pipeline", "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": "Extensions updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" } } } }, "/api/v1/files/images": { "post": { "tags": [ "Files" ], "summary": "Upload Image", "description": "Upload image file (supports jpg, jpeg, png, gif, webp, max 10MB)", "operationId": "uploadImage", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "Image file" } } } } } }, "responses": { "200": { "description": "Upload successful", "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": "File key" } } } } } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/api/v1/files/documents": { "post": { "tags": [ "Files" ], "summary": "Upload Document", "description": "Upload document file (max 10MB)", "operationId": "uploadDocument", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "Document file" } } } } } }, "responses": { "200": { "description": "Upload successful", "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": "File ID" } } } } } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/api/v1/plugins": { "get": { "tags": [ "Plugins" ], "summary": "List All Plugins", "description": "Get list of all installed plugins", "operationId": "listPlugins", "responses": { "200": { "description": "Success", "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": [ "Plugins" ], "summary": "Get Plugin Details", "description": "Get details of a specific plugin", "operationId": "getPlugin", "parameters": [ { "name": "author", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Plugin author" }, { "name": "plugin_name", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Plugin name" } ], "responses": { "200": { "description": "Success", "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": [ "Plugins" ], "summary": "Delete Plugin", "description": "Uninstall the specified plugin", "operationId": "deletePlugin", "parameters": [ { "name": "author", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Plugin author" }, { "name": "plugin_name", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Plugin name" }, { "name": "delete_data", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "Whether to delete plugin data" } ], "responses": { "200": { "description": "Deletion task created", "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": [ "Plugins" ], "summary": "Install Plugin from Local File", "description": "Upload and install plugin package file", "operationId": "installPluginLocal", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "Plugin package file (.lbpkg format)" } } } } } }, "responses": { "200": { "description": "Installation task created", "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": [ "Plugins" ], "summary": "Install Plugin from GitHub", "description": "Install plugin from GitHub Release", "operationId": "installPluginGitHub", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "asset_url" ], "properties": { "asset_url": { "type": "string", "description": "GitHub Release asset download URL" }, "owner": { "type": "string", "description": "Repository owner" }, "repo": { "type": "string", "description": "Repository name" }, "release_tag": { "type": "string", "description": "Release tag" } } } } } }, "responses": { "200": { "description": "Installation task created", "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": [ "Plugins" ], "summary": "Install from Marketplace", "description": "Install plugin from LangBot plugin marketplace", "operationId": "installPluginMarketplace", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "plugin_id": { "type": "string", "description": "Plugin ID" } } } } } }, "responses": { "200": { "description": "Installation task created", "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/platform/bots/{bot_uuid}/send_message": { "post": { "tags": [ "Bots" ], "summary": "Send Message", "description": "Send a message to a specific target via the specified bot", "operationId": "sendMessage", "parameters": [ { "name": "bot_uuid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Bot 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 type" }, "target_id": { "type": "string", "description": "Target ID (user ID or group ID)" }, "message_chain": { "type": "array", "items": { "type": "object" }, "description": "Message chain (array of MessageComponent)" } } }, "examples": { "Text Message": { "value": { "target_type": "group", "target_id": "123456789", "message_chain": [ { "type": "Plain", "text": "Hello, World!" } ] } }, "Text and Image": { "value": { "target_type": "person", "target_id": "987654321", "message_chain": [ { "type": "Plain", "text": "Check out this image:" }, { "type": "Image", "url": "https://example.com/image.jpg" } ] } } } } } }, "responses": { "200": { "description": "Message sent successfully", "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": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": -1 }, "msg": { "type": "string", "example": "target_type is required" } } } } } }, "500": { "description": "Failed to send", "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": [ "Knowledge Bases" ], "summary": "Get All Knowledge Bases", "description": "Get all builtin knowledge bases", "operationId": "listKnowledgeBases", "responses": { "200": { "description": "Success", "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": [ "Knowledge Bases" ], "summary": "Create Knowledge Base", "description": "Create a new knowledge base", "operationId": "createKnowledgeBase", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "embedding_model_uuid" ], "properties": { "name": { "type": "string", "description": "name" }, "description": { "type": "string", "description": "description" }, "embedding_model_uuid": { "type": "string", "description": "Embedding model UUID" } } }, "example": { "name": "技术文档库", "description": "存储技术文档和API参考", "embedding_model_uuid": "uuid-of-embedding-model" } } } }, "responses": { "200": { "description": "Knowledge base created successfully", "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": [ "Knowledge Bases" ], "summary": "Get Knowledge Base Details", "description": "Get details info of specified knowledge base", "operationId": "getKnowledgeBase", "parameters": [ { "name": "kb_uuid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Knowledge Base UUID" } ], "responses": { "200": { "description": "Success", "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": "Knowledge base not found", "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": [ "Knowledge Bases" ], "summary": "Update Knowledge Base Info", "description": "Update knowledge base information", "operationId": "updateKnowledgeBase", "parameters": [ { "name": "kb_uuid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Knowledge Base UUID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" } } } } } }, "responses": { "200": { "description": "Update successful", "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": [ "Knowledge Bases" ], "summary": "Delete Knowledge Base", "description": "Delete a specified knowledge base", "operationId": "deleteKnowledgeBase", "parameters": [ { "name": "kb_uuid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Knowledge Base UUID" } ], "responses": { "200": { "description": "Deletion successful", "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": [ "Knowledge Bases" ], "summary": "List Knowledge Base Files", "description": "Get all files in the specified knowledge base", "operationId": "listKnowledgeBaseFiles", "parameters": [ { "name": "kb_uuid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Knowledge Base 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": [ "Knowledge Bases" ], "summary": "Add File to Knowledge Base", "description": "Add uploaded file to knowledge base for processing", "operationId": "addFileToKnowledgeBase", "parameters": [ { "name": "kb_uuid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Knowledge Base UUID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "file_id" ], "properties": { "file_id": { "type": "string", "description": "File ID（从文件上传接口获取）" } } }, "example": { "file_id": "document_abc123.pdf" } } } }, "responses": { "200": { "description": "Addition successful", "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": "Processing task ID" } } } } } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ] } }, "/api/v1/knowledge/bases/{kb_uuid}/files/{file_id}": { "delete": { "tags": [ "Knowledge Bases" ], "summary": "Delete File from Knowledge Base", "description": "Delete file from the specified knowledge base", "operationId": "deleteFileFromKnowledgeBase", "parameters": [ { "name": "kb_uuid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Knowledge Base UUID" }, { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "File ID" } ], "responses": { "200": { "description": "Deletion successful", "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": [ "Knowledge Bases" ], "summary": "Retrieve Knowledge", "description": "Search for relevant knowledge in the knowledge base", "operationId": "retrieveKnowledge", "parameters": [ { "name": "kb_uuid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Knowledge Base UUID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "query" ], "properties": { "query": { "type": "string", "description": "Query text" } } }, "example": { "query": "如何使用 LangBot 创建机器人？" } } } }, "responses": { "200": { "description": "Retrieval successful", "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": [] } ] } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "API Key authentication using X-API-Key header.\nExample: `X-API-Key: lbk_your_api_key_here`\n" }, "BearerAuth": { "type": "http", "scheme": "bearer", "description": "Bearer token authentication. Can be either a user JWT token or an API key.\nExample: `Authorization: Bearer `\n" } }, "parameters": { "ModelUUID": { "name": "model_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Model 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": "Error message" } } } }, "responses": { "UnauthorizedError": { "description": "Authentication required or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "no_auth": { "value": { "code": -1, "msg": "No valid authentication provided (user token or API key required)" } }, "invalid_key": { "value": { "code": -1, "msg": "Invalid API key" } } } } } }, "NotFoundError": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": -1, "msg": "Resource not found" } } } }, "InternalServerError": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": -2, "msg": "Internal server error" } } } } } } }