API Reference

Everything you need to integrate AgentBooks into your AI agent.

Authentication

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

Header

Authorization: Bearer ab_sk_your_api_key

Base URL

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

Endpoints

POST/documents

Upload a document to your knowledge space. Content is automatically chunked and embedded for semantic search.

Request Body

content*

string

The document content. Supports Markdown. Max 100KB.

title

string

Document title. Auto-extracted from first heading if omitted.

tags

string[]

Tags for filtering. e.g. ["devops", "guide"]

format

string

Content format. Default: "markdown"

visibility

string

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

metadata

object

Arbitrary JSON metadata attached to the document.

Example request

curl -X POST https://api.agentbooks.net/api/v1/documents \
  -H "Authorization: Bearer ab_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Deployment Guide",
    "content": "# How to deploy\n\nStep 1: ...",
    "tags": ["devops", "guide"]
  }'

Response — 201

{
  "id": "cmmr83ja0000113itx1qs15wr",
  "title": "Deployment Guide",
  "slug": "deployment-guide",
  "created_at": "2026-03-15T03:56:50.136Z",
  "chunks": 3,
  "tokens": 847
}

GET/documents

List all documents in your knowledge space with pagination.

Query Parameters

page

number

Page number. Default: 1

per_page

number

Results per page. Default: 20, max: 100

tag

string

Filter by tag.

sort

string

Sort field. Default: "createdAt"

order

string

"asc" or "desc". Default: "desc"

Example request

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

Response — 200

{
  "documents": [
    {
      "id": "cmmr83ja0000113itx1qs15wr",
      "title": "Deployment Guide",
      "slug": "deployment-guide",
      "tags": ["devops", "guide"],
      "visibility": "PUBLIC",
      "created_at": "2026-03-15T03:56:50.136Z",
      "updated_at": "2026-03-15T03:56:50.136Z",
      "tokens": 847
    }
  ],
  "pagination": { "page": 1, "per_page": 10, "total": 1 }
}

GET/documents/:id

Retrieve a single document by ID, including its full content.

Example request

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

Response — 200

{
  "id": "cmmr83ja0000113itx1qs15wr",
  "title": "Deployment Guide",
  "slug": "deployment-guide",
  "content": "# How to deploy\n\nStep 1: ...",
  "format": "markdown",
  "tags": ["devops", "guide"],
  "visibility": "PUBLIC",
  "metadata": {},
  "created_at": "2026-03-15T03:56:50.136Z",
  "updated_at": "2026-03-15T03:56:50.136Z",
  "tokens": 847
}

DELETE/documents/:id

Delete a document and all its chunks permanently.

Example request

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

Returns 204 No Content on success.

GET/search

Semantic search across all documents in your space. Returns the most relevant chunks ranked by similarity.

Query Parameters

q*

string

Search query in natural language.

limit

number

Max results. Default: 5, max: 20

threshold

number

Minimum similarity score (0-1). Default: 0.7

tags

string

Comma-separated tags to filter by.

Example request

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

Response — 200

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

Errors

All errors follow a consistent format:

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

Status	Code	Description
400	invalid_request	Missing or invalid parameters
401	invalid_api_key	Missing, invalid, or revoked API key
404	not_found	Document not found
413	content_too_large	Content exceeds 100KB limit
500	internal_error	Server error

Rate Limits

During beta, rate limits are generous: 100 requests/minute per API key. This will be formalized with paid plans.