API 参考

AnythingLLM 提供了完整的 RESTful API，允许开发者通过编程方式与平台进行交互。本文档详细介绍了所有可用的 API 端点、请求格式和响应结构。

基础信息

基础 URL

http://localhost:3001/api

认证

所有 API 请求都需要包含有效的 JWT 令牌：

http

Authorization: Bearer <your-jwt-token>

响应格式

所有 API 响应都遵循统一的格式：

json

{
  "success": true,
  "data": {},
  "error": null,
  "message": "操作成功"
}

认证 API

用户登录

获取访问令牌以进行后续 API 调用。

http

POST /auth/login

请求体：

json

{
  "username": "admin",
  "password": "password"
}

响应：

json

{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "id": 1,
      "username": "admin",
      "role": "admin"
    }
  }
}

验证令牌

验证当前令牌的有效性。

http

GET /auth/verify

响应：

json

{
  "success": true,
  "data": {
    "valid": true,
    "user": {
      "id": 1,
      "username": "admin",
      "role": "admin"
    }
  }
}

工作空间 API

获取所有工作空间

获取用户可访问的所有工作空间列表。

http

GET /workspaces

响应：

json

{
  "success": true,
  "data": {
    "workspaces": [
      {
        "id": 1,
        "name": "默认工作空间",
        "slug": "default-workspace",
        "createdAt": "2024-01-01T00:00:00.000Z",
        "updatedAt": "2024-01-01T00:00:00.000Z"
      }
    ]
  }
}

创建工作空间

创建新的工作空间。

http

POST /workspaces

请求体：

json

{
  "name": "我的工作空间",
  "description": "工作空间描述"
}

响应：

json

{
  "success": true,
  "data": {
    "workspace": {
      "id": 2,
      "name": "我的工作空间",
      "slug": "my-workspace",
      "description": "工作空间描述",
      "createdAt": "2024-01-01T00:00:00.000Z"
    }
  }
}

获取工作空间详情

获取特定工作空间的详细信息。

http

GET /workspaces/:slug

路径参数：

slug - 工作空间的唯一标识符

响应：

json

{
  "success": true,
  "data": {
    "workspace": {
      "id": 1,
      "name": "默认工作空间",
      "slug": "default-workspace",
      "description": "默认工作空间描述",
      "documents": [],
      "threads": []
    }
  }
}

更新工作空间

更新现有工作空间的信息。

http

PUT /workspaces/:slug

请求体：

json

{
  "name": "更新的工作空间名称",
  "description": "更新的描述"
}

删除工作空间

删除指定的工作空间。

http

DELETE /workspaces/:slug

文档 API

上传文档

向工作空间上传新文档。

http

POST /workspaces/:slug/documents

请求体（multipart/form-data）：

file - 要上传的文件
metadata - 文档元数据（JSON 字符串）

响应：

json

{
  "success": true,
  "data": {
    "document": {
      "id": 1,
      "filename": "document.pdf",
      "originalName": "我的文档.pdf",
      "mimeType": "application/pdf",
      "size": 1024000,
      "workspaceId": 1,
      "processed": false,
      "createdAt": "2024-01-01T00:00:00.000Z"
    }
  }
}

获取文档列表

获取工作空间中的所有文档。

http

GET /workspaces/:slug/documents

查询参数：

page - 页码（默认：1）
limit - 每页数量（默认：20）
search - 搜索关键词

响应：

json

{
  "success": true,
  "data": {
    "documents": [
      {
        "id": 1,
        "filename": "document.pdf",
        "originalName": "我的文档.pdf",
        "processed": true,
        "chunks": 15,
        "createdAt": "2024-01-01T00:00:00.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 1,
      "pages": 1
    }
  }
}

删除文档

从工作空间中删除文档。

http

DELETE /workspaces/:slug/documents/:documentId

对话 API

发送消息

向工作空间发送聊天消息。

http

POST /workspaces/:slug/chat

请求体：

json

{
  "message": "你好，请帮我总结一下上传的文档",
  "mode": "chat",
  "threadId": null
}

响应：

json

{
  "success": true,
  "data": {
    "response": "根据您上传的文档，我为您总结如下...",
    "sources": [
      {
        "document": "document.pdf",
        "chunk": "文档片段内容...",
        "score": 0.85
      }
    ],
    "threadId": "thread-123"
  }
}

获取对话历史

获取工作空间的对话历史记录。

http

GET /workspaces/:slug/chats

查询参数：

threadId - 特定对话线程 ID
limit - 返回消息数量限制

响应：

json

{
  "success": true,
  "data": {
    "chats": [
      {
        "id": 1,
        "message": "你好，请帮我总结一下上传的文档",
        "response": "根据您上传的文档，我为您总结如下...",
        "threadId": "thread-123",
        "createdAt": "2024-01-01T00:00:00.000Z"
      }
    ]
  }
}

系统 API

获取系统信息

获取系统状态和配置信息。

http

GET /system/info

响应：

json

{
  "success": true,
  "data": {
    "version": "1.0.0",
    "llmProvider": "openai",
    "vectorDB": "pinecone",
    "embeddingProvider": "openai",
    "storage": {
      "used": "1.2GB",
      "available": "8.8GB"
    }
  }
}

更新系统设置

更新系统配置。

http

PUT /system/settings

请求体：

json

{
  "llmProvider": "anthropic",
  "llmApiKey": "your-api-key",
  "embeddingProvider": "openai",
  "embeddingApiKey": "your-embedding-key"
}

获取支持的模型

获取当前配置下支持的 LLM 模型列表。

http

GET /system/models

响应：

json

{
  "success": true,
  "data": {
    "models": [
      {
        "id": "gpt-4",
        "name": "GPT-4",
        "provider": "openai",
        "maxTokens": 8192
      },
      {
        "id": "claude-3-opus",
        "name": "Claude 3 Opus",
        "provider": "anthropic",
        "maxTokens": 200000
      }
    ]
  }
}

用户管理 API

获取用户列表

获取系统中的所有用户（仅管理员）。

http

GET /users

响应：

json

{
  "success": true,
  "data": {
    "users": [
      {
        "id": 1,
        "username": "admin",
        "role": "admin",
        "createdAt": "2024-01-01T00:00:00.000Z",
        "lastLogin": "2024-01-01T12:00:00.000Z"
      }
    ]
  }
}

创建用户

创建新用户账户（仅管理员）。

http

POST /users

请求体：

json

{
  "username": "newuser",
  "password": "securepassword",
  "role": "user"
}

更新用户

更新用户信息（仅管理员或用户本人）。

http

PUT /users/:userId

请求体：

json

{
  "username": "updateduser",
  "role": "user",
  "password": "newpassword"
}

删除用户

删除用户账户（仅管理员）。

http

DELETE /users/:userId

错误处理

错误响应格式

当 API 请求失败时，会返回以下格式的错误响应：

json

{
  "success": false,
  "data": null,
  "error": "错误详细信息",
  "message": "操作失败"
}

常见错误代码

状态码	错误类型	描述
400	Bad Request	请求参数无效
401	Unauthorized	未提供有效的认证令牌
403	Forbidden	权限不足
404	Not Found	请求的资源不存在
409	Conflict	资源冲突（如重复创建）
422	Unprocessable Entity	请求格式正确但包含语义错误
500	Internal Server Error	服务器内部错误

速率限制

为了保护系统资源，API 实施了速率限制：

认证端点: 每分钟 10 次请求
聊天端点: 每分钟 30 次请求
文档上传: 每分钟 5 次请求
其他端点: 每分钟 100 次请求

当超过速率限制时，API 会返回 429 状态码。

SDK 和示例

JavaScript SDK

javascript

import AnythingLLMClient from '@anythingllm/sdk';

const client = new AnythingLLMClient({
  baseURL: 'http://localhost:3001/api',
  apiKey: 'your-jwt-token'
});

// 获取工作空间列表
const workspaces = await client.workspaces.list();

// 发送聊天消息
const response = await client.chat.send('my-workspace', {
  message: '你好，AnythingLLM！'
});

Python SDK

python

from anythingllm import AnythingLLMClient

client = AnythingLLMClient(
    base_url='http://localhost:3001/api',
    api_key='your-jwt-token'
)

# 获取工作空间列表
workspaces = client.workspaces.list()

# 发送聊天消息
response = client.chat.send('my-workspace', {
    'message': '你好，AnythingLLM！'
})

cURL 示例

bash

# 登录获取令牌
curl -X POST http://localhost:3001/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "password"}'

# 获取工作空间列表
curl -X GET http://localhost:3001/api/workspaces \
  -H "Authorization: Bearer your-jwt-token"

# 发送聊天消息
curl -X POST http://localhost:3001/api/workspaces/my-workspace/chat \
  -H "Authorization: Bearer your-jwt-token" \
  -H "Content-Type: application/json" \
  -d '{"message": "你好，AnythingLLM！"}'

Webhook 支持

AnythingLLM 支持 Webhook，可以在特定事件发生时向您的应用程序发送通知。

配置 Webhook

http

POST /system/webhooks

请求体：

json

{
  "url": "https://your-app.com/webhook",
  "events": ["document.processed", "chat.completed"],
  "secret": "your-webhook-secret"
}

支持的事件

document.uploaded - 文档上传完成
document.processed - 文档处理完成
chat.completed - 聊天响应生成完成
workspace.created - 工作空间创建
user.created - 用户创建

Webhook 负载示例

json

{
  "event": "document.processed",
  "timestamp": "2024-01-01T00:00:00.000Z",
  "data": {
    "documentId": 1,
    "workspaceId": 1,
    "filename": "document.pdf",
    "chunks": 15,
    "processingTime": 30000
  }
}

API 参考 ​

基础信息 ​

基础 URL ​

认证 ​

响应格式 ​

认证 API ​

用户登录 ​

验证令牌 ​

工作空间 API ​

获取所有工作空间 ​

创建工作空间 ​

获取工作空间详情 ​

更新工作空间 ​

删除工作空间 ​

文档 API ​

上传文档 ​

获取文档列表 ​

删除文档 ​

对话 API ​

发送消息 ​

获取对话历史 ​

系统 API ​

获取系统信息 ​

更新系统设置 ​

获取支持的模型 ​

用户管理 API ​

获取用户列表 ​

创建用户 ​

更新用户 ​

删除用户 ​

错误处理 ​

错误响应格式 ​

常见错误代码 ​

速率限制 ​

SDK 和示例 ​

JavaScript SDK ​

Python SDK ​

cURL 示例 ​

Webhook 支持 ​

配置 Webhook ​

支持的事件 ​

Webhook 负载示例 ​

API 参考

基础信息

基础 URL

认证

响应格式

认证 API

用户登录

验证令牌

工作空间 API

获取所有工作空间

创建工作空间

获取工作空间详情

更新工作空间

删除工作空间

文档 API

上传文档

获取文档列表

删除文档

对话 API

发送消息

获取对话历史

系统 API

获取系统信息

更新系统设置

获取支持的模型

用户管理 API

获取用户列表

创建用户

更新用户

删除用户

错误处理

错误响应格式

常见错误代码

速率限制

SDK 和示例

JavaScript SDK

Python SDK

cURL 示例

Webhook 支持

配置 Webhook

支持的事件

Webhook 负载示例