API Reference

Base URL

http://127.0.0.1:7432

Endpoints

Method	Endpoint	Description
`POST`	`/index`	Index a documentation site
`POST`	`/retrieve`	Search for relevant snippets
`GET`	`/status`	Get indexing status
`POST`	`/refresh`	Refresh a docset (by id or baseUrl)
`POST`	`/refresh-all`	Refresh all docsets
`GET`	`/docset/:id`	Get a docset and its index status
`GET`	`/docset/:id/pages`	List pages in a docset
`DELETE`	`/docset/:id`	Delete a docset
`POST`	`/session/register`	Register a client session
`POST`	`/session/unregister`	Unregister a client session
`GET`	`/sessions`	List active sessions
`GET`	`/health`	Health check

POST /index

Index a documentation website.

Request

Request Body

{
  "baseUrl": "https://nextjs.org",
  "seedSlug": "/docs/getting-started",
  "name": "Next.js Docs",
  "allowedPaths": ["/docs"],
  "waitForSeed": true
}

Parameters

Field	Type	Required	Description
`baseUrl`	string	Yes	Base URL of the documentation site
`seedSlug`	string	Yes	Starting path to begin crawling
`name`	string	No	Custom name for the docset
`allowedPaths`	string[]	No	Allowed path prefixes to crawl
`waitForSeed`	boolean	No	Wait for seed page to be indexed before returning

Response

{
  "docsetId": "abc123",
  "status": "indexing",
  "seedIndexed": true
}

Example

Terminal

curl -X POST http://localhost:7432/index \
  -H "Content-Type: application/json" \
  -d '{
    "baseUrl": "https://nextjs.org",
    "seedSlug": "/docs/getting-started",
    "name": "Next.js Docs",
    "allowedPaths": ["/docs"],
    "waitForSeed": true
  }'

POST /retrieve

Search for relevant documentation snippets with diversity filtering and character budget control.

Request

Request Body

{
  "query": "how to use server components",
  "topK": 5,
  "docsetIds": ["abc123"],
  "maxChunksPerPage": 2,
  "maxTotalChars": 16000,
  "formatSnippets": true
}

Parameters

Field	Type	Required	Default	Description
`query`	string	Yes	-	Search query
`topK`	number	No	`5`	Number of results (clamped 1-100)
`docsetIds`	string[]	No	All	Filter by specific docsets
`maxChunksPerPage`	number	No	`3`	Max chunks from same page (diversity)
`maxTotalChars`	number	No	`32000`	Total character budget for results
`formatSnippets`	boolean	No	`true`	Include formatted snippets

Response

{
  "query": "how to use server components",
  "results": [
    {
      "chunkId": "chunk-123",
      "pageId": "page-456",
      "docsetId": "abc123",
      "content": "Server Components allow you to write UI that can be rendered...",
      "url": "https://nextjs.org/docs/app/building-your-application/rendering/server-components",
      "title": "Server Components",
      "heading": "Introduction",
      "score": 0.89,
      "snippet": {
        "formatted": "## Server Components\nSource: https://nextjs.org/docs/.../server-components\nSection: Rendering > Server Components > Introduction\n\nServer Components allow you to write UI that can be rendered...",
        "title": "Server Components",
        "url": "https://nextjs.org/docs/app/building-your-application/rendering/server-components",
        "breadcrumb": "Rendering > Server Components > Introduction",
        "content": "Server Components allow you to write UI that can be rendered...",
        "charCount": 245
      }
    }
  ],
  "totalChars": 1250,
  "truncated": false
}

Response Fields

Field	Type	Description
`results`	array	Array of search results with optional snippets
`totalChars`	number	Total characters across all results
`truncated`	boolean	Whether results were truncated due to budget

Snippet Object

When formatSnippets is enabled, each result includes a snippet object:

Field	Type	Description
`formatted`	string	Ready-to-use formatted text for context injection
`title`	string	Page title
`url`	string	Source URL
`breadcrumb`	string	Heading path (e.g., "Api > Auth > OAuth")
`content`	string	The content text (may be truncated)
`charCount`	number	Character count of formatted snippet

Example

Terminal

curl -X POST http://localhost:7432/retrieve \
  -H "Content-Type: application/json" \
  -d '{
    "query": "how to use server components",
    "topK": 5,
    "maxChunksPerPage": 2,
    "maxTotalChars": 16000,
    "formatSnippets": true
  }'

Diversity Filtering

The maxChunksPerPage parameter prevents results from being dominated by chunks from a single page:

Diverse Results

# Get at most 2 chunks from each page
curl -X POST http://localhost:7432/retrieve \
  -H "Content-Type: application/json" \
  -d '{
    "query": "authentication",
    "topK": 10,
    "maxChunksPerPage": 2
  }'

Character Budget

Control the total size of returned content for predictable context injection:

Limited Budget

# Limit total response to ~8000 characters
curl -X POST http://localhost:7432/retrieve \
  -H "Content-Type: application/json" \
  -d '{
    "query": "getting started",
    "topK": 10,
    "maxTotalChars": 8000
  }'

GET /status

Get the status of all indexed documentation.

Query Parameters

Parameter	Type	Description
`docsetId`	string	Filter to a specific docset
`includeStuck`	boolean	Include `stuckPages` details

Response

{
  "docsets": [
    {
      "id": "abc123",
      "name": "Next.js Docs",
      "baseUrl": "https://nextjs.org",
      "seedSlug": "/docs/getting-started",
      "allowedPaths": ["/docs"],
      "createdAt": 1705318800000,
      "updatedAt": 1705320600000,
      "status": "ready",
      "indexStatus": {
        "docsetId": "abc123",
        "totalPages": 245,
        "indexedPages": 245,
        "pendingPages": 0,
        "errorPages": 0,
        "skippedPages": 0,
        "totalChunks": 4120,
        "status": "ready",
        "stuckPages": 0,
        "retriedPages": 0
      }
    }
  ]
}

stuckPages is included when includeStuck=true or when stuck pages exist.

Example

Terminal

curl http://localhost:7432/status

POST /refresh

Refresh a specific docset by docsetId or baseUrl.

Request

Request Body

{
  "docsetId": "abc123",
  "force": false,
  "maxAge": 24,
  "fullReindex": false
}

Parameters

Field	Type	Required	Description
`docsetId`	string	No	Docset ID to refresh
`baseUrl`	string	No	Docset base URL to refresh
`force`	boolean	No	Refresh even if docset is fresh
`maxAge`	number	No	Max age in hours before refresh is needed
`fullReindex`	boolean	No	Clear hashes and re-embed all pages

Response

{
  "docsetId": "abc123",
  "status": "pending",
  "refreshed": true,
  "message": "Refreshing 245 pages from Next.js Docs (incremental mode)",
  "incremental": {
    "preservedHashes": 240,
    "clearedHashes": 5
  }
}

POST /refresh-all

Refresh all docsets that are stale (or all, if force is true).

Request

Request Body

{
  "force": false,
  "maxAge": 24,
  "fullReindex": false
}

Response

{
  "total": 2,
  "refreshed": 1,
  "results": [
    {
      "docsetId": "abc123",
      "status": "pending",
      "refreshed": true,
      "message": "Queued 245 pages for refresh (incremental)",
      "incremental": {
        "preservedHashes": 240,
        "clearedHashes": 5
      }
    }
  ]
}

GET /docset/:id

Get a single docset and its index status.

Response

{
  "id": "abc123",
  "name": "Next.js Docs",
  "baseUrl": "https://nextjs.org",
  "seedSlug": "/docs/getting-started",
  "allowedPaths": ["/docs"],
  "createdAt": 1705318800000,
  "updatedAt": 1705320600000,
  "status": "ready",
  "indexStatus": {
    "docsetId": "abc123",
    "totalPages": 245,
    "indexedPages": 245,
    "pendingPages": 0,
    "errorPages": 0,
    "skippedPages": 0,
    "totalChunks": 4120,
    "status": "ready",
    "stuckPages": 0,
    "retriedPages": 0
  }
}

GET /docset/:id/pages

List pages in a docset with pagination.

Query Parameters

Parameter	Type	Description
`status`	string	Filter by page status
`limit`	number	Max pages to return (default: 100, max: 500)
`offset`	number	Offset for pagination (default: 0)

Response

{
  "pages": [
    {
      "id": "page-123",
      "url": "https://nextjs.org/docs/app",
      "path": "/docs/app",
      "title": "App Router",
      "status": "indexed",
      "errorMessage": null,
      "fetchedAt": 1705320400000,
      "indexedAt": 1705320410000
    }
  ],
  "total": 245,
  "limit": 100,
  "offset": 0
}

DELETE /docset/:id

Delete a docset and all its indexed content.

Parameters

Parameter	Type	Description
`id`	string	The docset ID to delete

Response

{
  "success": true,
  "docsetId": "abc123"
}

Example

Terminal

curl -X DELETE http://localhost:7432/docset/abc123

POST /session/register

Request

Request Body

{
  "sessionId": "session-123",
  "clientType": "claude-code"
}

Response

{
  "success": true,
  "session": {
    "id": "session-123",
    "clientType": "claude-code",
    "connectedAt": 1705320400000,
    "lastHeartbeat": 1705320400000
  },
  "totalSessions": 1
}

POST /session/unregister

Unregister a client session.

Request

Request Body

{
  "sessionId": "session-123"
}

Response

{
  "success": true,
  "existed": true,
  "remainingSessions": 0,
  "shouldStop": true
}

GET /sessions

List active sessions.

Response

{
  "sessions": [
    {
      "id": "session-123",
      "clientType": "claude-code",
      "connectedAt": 1705320400000,
      "lastHeartbeat": 1705320400000
    }
  ],
  "count": 1
}

GET /health

Health check endpoint.

Response

{
  "status": "ok",
  "timestamp": 1705320400000,
  "version": "1.4.0"
}

Example

Terminal

curl http://localhost:7432/health

Error Responses

All endpoints return errors in this format:

Error Response

{
  "error": "Error message here"
}

API Reference

On this page