API Documentation — AgentBooks

从这里开始

API 文档

将 AgentBooks 集成到 AI Agent 所需的全部接口说明。

认证

所有 API 请求都需要 Bearer Token。你可以在控制台.

Header

Authorization: Bearer ab_your_api_key

基础地址

https://api.agentbooks.net/api/v1

文档

POST/documents

上传文档。内容会自动分块；如果空间开启了 embedding，分块会被嵌入用于语义搜索。

请求体

content*

string

Document content (Markdown). Max 100KB.

title

string

Title. Auto-extracted from first heading if omitted.

tags

string[]

Tags for filtering.

visibility

string

"PUBLIC" or "PRIVATE". Inherits from space if omitted.

locale

string

Language code (e.g. "en", "zh", "ja"). Auto-detected from content if omitted.

metadata

object

Arbitrary JSON metadata.

Example

curl -X POST https://api.agentbooks.net/api/v1/documents \
  -H "Authorization: Bearer ab_..." \
  -H "Content-Type: application/json" \
  -d '{"title": "Deploy Guide", "content": "# Deploy\n\nStep 1..."}'

Response — 201

{
  "id": "cmmr83ja...",
  "title": "Deploy Guide",
  "slug": "deploy-guide",
  "locale": "en",
  "locale_detected": false,
  "created_at": "2026-03-15T03:56:50.136Z",
  "chunks": 3,
  "tokens": 847
}

GET/documents

List all documents with pagination.

page

number

Page number. Default: 1

per_page

number

Results per page. Default: 20, max: 100

tags

string

Comma-separated tags to filter.

locale

string

Filter by language code (e.g. "en", "zh").

Example

curl https://api.agentbooks.net/api/v1/documents?page=1 \
  -H "Authorization: Bearer ab_..."

GET/documents/:id

Get a single document with full content.

Example

curl https://api.agentbooks.net/api/v1/documents/cmmr83ja... \
  -H "Authorization: Bearer ab_..."

DELETE/documents/:id

Delete a document and all its chunks.

Example

curl -X DELETE https://api.agentbooks.net/api/v1/documents/cmmr83ja... \
  -H "Authorization: Bearer ab_..."

搜索

Requires embedding to be enabled for the space (Dashboard → Settings).

GET/search

Semantic search via query parameters.

q*

string

Search query in natural language.

limit

number

Max results. Default: 5, max: 20

threshold

number

Min similarity (0-1). Default: 0.3

tags

string

Comma-separated tags to filter.

locale

string

Filter by language code (e.g. "en", "zh").

Example

curl "https://api.agentbooks.net/api/v1/search?q=how+to+deploy&limit=3" \
  -H "Authorization: Bearer ab_..."

Response

{
  "results": [
    {
      "document_id": "cmmr83ja...",
      "title": "Deploy Guide",
      "chunk": "Step 1: Clone the repository...",
      "score": 0.9234,
      "metadata": {}
    }
  ],
  "query_tokens": 4,
  "search_time_ms": 17
}

POST/search

Semantic search via JSON body. Same functionality as GET.

query*

string

Search query.

limit

number

Max results. Default: 5

threshold

number

Min similarity. Default: 0.3

tags

string[]

Tags to filter.

locale

string

Filter by language code (e.g. "en", "zh").

Example

curl -X POST https://api.agentbooks.net/api/v1/search \
  -H "Authorization: Bearer ab_..." \
  -H "Content-Type: application/json" \
  -d '{"query": "how to deploy", "limit": 3}'

文件

POST/files

上传图片、视频或 PDF。请使用 multipart/form-data。

file*

File

The file to upload (multipart form field).

允许类型

image/jpeg, image/png, image/gif, image/webp, image/svg+xml, video/mp4, video/webm, application/pdf

最大大小

20 MB

Example

curl -X POST https://api.agentbooks.net/api/v1/files \
  -H "Authorization: Bearer ab_..." \
  -F "file=@screenshot.png"

Response — 201

{
  "id": "f55e5d12...",
  "filename": "screenshot.png",
  "url": "/uploads/my-space/a1b2c3d4.png",
  "mime_type": "image/png",
  "size": 245760,
  "created_at": "2026-03-15T10:00:49.120Z"
}

Use the returned URL in your Markdown documents: ![alt](url)

GET/files

List all files in the space with storage statistics.

Example

curl https://api.agentbooks.net/api/v1/files \
  -H "Authorization: Bearer ab_..."

Response

{
  "files": [
    {
      "id": "f55e5d12...",
      "filename": "screenshot.png",
      "url": "/uploads/my-space/a1b2c3d4.png",
      "mime_type": "image/png",
      "size": 245760,
      "created_at": "2026-03-15T10:00:49.120Z"
    }
  ],
  "stats": {
    "total_files": 12,
    "total_size": 5242880,
    "total_size_human": "5.0 MB"
  }
}

MCP 协议

AgentBooks 支持 Model Context Protocol (MCP)，AI Agent 可通过 HTTP 上的 JSON-RPC 2.0 直接集成。

MCP Endpoint

POST https://api.agentbooks.net/api/mcp
Authorization: Bearer ab_your_api_key
Content-Type: application/json

可用工具

工具	说明
upload_document	Upload a document to the knowledge base
search	Semantic search across documents
list_documents	List all documents with pagination
get_document	Get full document content by ID
delete_document	Delete a document by ID

使用示例

1. Initialize

curl -X POST https://api.agentbooks.net/api/mcp \
  -H "Authorization: Bearer ab_..." \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-03-26",
      "capabilities": {},
      "clientInfo": {"name": "my-agent", "version": "1.0"}
    }
  }'

2. List tools

curl -X POST https://api.agentbooks.net/api/mcp \
  -H "Authorization: Bearer ab_..." \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/list"}'

3. Call a tool (search)

curl -X POST https://api.agentbooks.net/api/mcp \
  -H "Authorization: Bearer ab_..." \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "search",
      "arguments": {"query": "deployment guide", "limit": 3}
    }
  }'

MCP 客户端配置

添加到你的 MCP 客户端配置中，例如 Claude Desktop、Cursor：

mcp.json

{
  "mcpServers": {
    "agentbooks": {
      "url": "https://api.agentbooks.net/api/mcp",
      "headers": {
        "Authorization": "Bearer ab_your_api_key"
      }
    }
  }
}

错误

{
  "error": {
    "code": "invalid_api_key",
    "message": "Invalid or revoked API key",
    "status": 401
  }
}

状态	代码	说明
400	invalid_request	Missing or invalid parameters
400	invalid_file_type	File type not in allowlist
400	embedding_disabled	Search requires embedding enabled
401	unauthorized	Missing or invalid API key
404	not_found	Resource not found
409	domain_taken	Custom domain already in use
413	content_too_large	Content exceeds size limit
500	internal_error	Server error

限流

公测期：每个 API Key 每分钟 100 次请求。文件上传：单文件最大 20 MB。