API Reference

Everything you need to integrate AgentBooks into your AI agent.

Authentication

All API requests require a Bearer token. Get your API key from the Dashboard.

Header

Authorization: Bearer ab_your_api_key

Base URL

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

Documents

POST/documents

Upload a document. Content is automatically chunked. If embedding is enabled for the space, chunks are embedded for semantic search.

Request Body

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.

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",
  "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.

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_..."

Search

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.

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.

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}'

Files

POST/files

Upload an image, video, or PDF. Use multipart/form-data.

file*

File

The file to upload (multipart form field).

Allowed types

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

Max size

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 Protocol

AgentBooks supports the Model Context Protocol (MCP) for direct AI agent integration via JSON-RPC 2.0 over HTTP.

MCP Endpoint

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

Available Tools

Tool	Description
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

Usage Examples

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 Client Config

Add to your MCP client configuration (e.g. Claude Desktop, Cursor):

mcp.json

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

Errors

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

Status	Code	Description
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

Rate Limits

During beta: 100 requests/minute per API key. File uploads: 20 MB max per file.