AI Assistant API

Overview

The AI Assistant API gives you programmatic access to the same chat assistant that powers the search widget on your documentation site. Send natural language questions and receive streaming responses grounded in your documentation content. The assistant uses agentic RAG with three tools to search, retrieve, and synthesize answers.

Base path: https://api.holydocs.com/api/v1/assistant/:projectId

Send Message

Send a message to the AI assistant and receive a streaming response. The assistant searches your documentation, retrieves relevant pages, and synthesizes an answer.

bash
POST /api/v1/assistant/:projectId/chat

Copy as context

bash
curl -N -X POST "https://api.holydocs.com/api/v1/assistant/$PROJECT_ID/chat" \  -H "Content-Type: application/json" \  -d '{"message":"How do I set up a custom domain?","visitorId":"v_anon_abc"}'

bash
holydocs api post "/assistant/$PROJECT_ID/chat" \  --json '{"message":"How do I set up a custom domain?","visitorId":"cli"}'

ts
import { HolyDocs } from '@holydocs/sdk';const client = new HolyDocs(); // public — no api key neededfor await (const chunk of client.assistant.chat(projectId, {  message: 'How do I set up a custom domain?',  visitorId: 'v_anon_abc',})) {  process.stdout.write(chunk.token ?? '');}

Path Parameters

Request Body

json
{  "message": "How do I set up a custom domain?",  "visitorId": "v_anon_abc123",  "conversationId": "conv_xyz789"}

Response

The response is an SSE (Server-Sent Events) stream. Each event is a newline-delimited message with a data: prefix.

text
HTTP/1.1 200 OKContent-Type: text/event-streamCache-Control: no-cacheConnection: keep-alivedata: {"type":"start","conversationId":"conv_xyz789","messageId":"msg_abc123"}data: {"type":"tool_call","tool":"search_docs","input":{"query":"custom domain setup"}}data: {"type":"tool_result","tool":"search_docs","results":3}data: {"type":"tool_call","tool":"get_page","input":{"path":"/custom-domains"}}data: {"type":"tool_result","tool":"get_page","title":"Custom Domains"}data: {"type":"text","content":"To set up a custom domain"}data: {"type":"text","content":" for your HolyDocs project, follow"}data: {"type":"text","content":" these steps:\n\n1. Go to **Settings"}data: {"type":"text","content":" > Domain** in your dashboard\n2."}data: {"type":"text","content":" Enter your domain (e.g., `docs.yourcompany.com`)\n3."}data: {"type":"text","content":" Add a CNAME record pointing to `proxy.holydocs.com`\n4."}data: {"type":"text","content":" Wait for DNS propagation and SSL provisioning\n\n"}data: {"type":"citations","sources":[{"path":"/custom-domains","title":"Custom Domains"},{"path":"/api/domains","title":"Domains API"}]}data: {"type":"done","tokensUsed":342}

SSE Event Types

javascript
async function askAssistant(projectId, message, visitorId) {  const response = await fetch(    `https://api.holydocs.com/api/v1/assistant/${projectId}/chat`,    {      method: 'POST',      headers: { 'Content-Type': 'application/json' },      body: JSON.stringify({ message, visitorId })    }  );  const reader = response.body.getReader();  const decoder = new TextDecoder();  let fullText = '';  while (true) {    const { done, value } = await reader.read();    if (done) break;    const chunk = decoder.decode(value, { stream: true });    const lines = chunk.split('\n');    for (const line of lines) {      if (!line.startsWith('data: ')) continue;      const event = JSON.parse(line.slice(6));      switch (event.type) {        case 'text':          fullText += event.content;          process.stdout.write(event.content);          break;        case 'citations':          console.log('\nSources:', event.sources.map(s => s.title).join(', '));          break;        case 'error':          throw new Error(event.message);      }    }  }  return fullText;}

python
import requestsimport jsondef ask_assistant(project_id, message, visitor_id):    response = requests.post(        f"https://api.holydocs.com/api/v1/assistant/{project_id}/chat",        json={"message": message, "visitorId": visitor_id},        stream=True    )    full_text = ""    for line in response.iter_lines():        if not line:            continue        decoded = line.decode("utf-8")        if not decoded.startswith("data: "):            continue        event = json.loads(decoded[6:])        if event["type"] == "text":            full_text += event["content"]            print(event["content"], end="", flush=True)        elif event["type"] == "citations":            sources = [s["title"] for s in event["sources"]]            print(f"\nSources: {', '.join(sources)}")        elif event["type"] == "error":            raise Exception(event["message"])    return full_text

bash
curl -N -X POST "https://api.holydocs.com/api/v1/assistant/proj_abc123/chat" \  -H "Content-Type: application/json" \  -d '{    "message": "How do I set up a custom domain?",    "visitorId": "v_anon_test"  }'

Use the -N flag with cURL to disable output buffering, which is required to see SSE events in real time.

Agentic RAG Flow

The assistant does not simply embed the query and return a vector match. It follows an agentic Retrieval-Augmented Generation (RAG) flow, autonomously deciding which tools to call and how many rounds of retrieval to perform before answering.

Assistant Tools

The assistant has access to three tools. These are invoked automatically during the agentic loop -- you do not call them directly.

json
{  "query": "custom domain DNS setup",  "limit": 5}

json
{  "path": "/custom-domains"}

json
{}

List Conversations

Retrieve a list of AI assistant conversations for analytics and review. Requires authentication.

bash
GET /api/v1/assistant/:projectId/conversations

Query Parameters

Response

json
{  "data": [    {      "id": "conv_abc123",      "visitorId": "v_anon_xyz",      "messageCount": 4,      "tokensUsed": 1240,      "firstMessage": "How do I set up a custom domain?",      "satisfied": true,      "createdAt": "2026-04-10T14:23:00Z",      "lastMessageAt": "2026-04-10T14:25:30Z"    },    {      "id": "conv_def456",      "visitorId": "v_anon_abc",      "messageCount": 7,      "tokensUsed": 3100,      "firstMessage": "What authentication methods are supported?",      "satisfied": null,      "createdAt": "2026-04-10T12:10:00Z",      "lastMessageAt": "2026-04-10T12:18:45Z"    }  ],  "meta": {    "total": 1240,    "page": 1,    "perPage": 20,    "totalPages": 62  }}

Usage Statistics

Retrieve aggregated AI assistant usage for billing and monitoring. Requires authentication.

bash
GET /api/v1/assistant/:projectId/usage

Query Parameters

Response

json
{  "data": {    "period": "billing",    "startDate": "2026-04-01T00:00:00Z",    "endDate": "2026-04-30T23:59:59Z",    "totalConversations": 1240,    "totalMessages": 5680,    "totalTokens": 2450000,    "tokensLimit": 5000000,    "tokensRemaining": 2550000,    "usageByDay": [      { "date": "2026-04-10", "conversations": 45, "messages": 198, "tokens": 89000 },      { "date": "2026-04-11", "conversations": 38, "messages": 165, "tokens": 74000 }    ],    "model": "anthropic/claude-sonnet-4",    "avgResponseTime": 2.3,    "satisfactionRate": 0.87  }}

bash
curl "https://api.holydocs.com/api/v1/assistant/proj_abc123/usage?period=billing" \  -H "Authorization: Bearer hd_a1b2c3d4e5f67890a1b2c3d4e5f67890"

javascript
const response = await fetch(  'https://api.holydocs.com/api/v1/assistant/proj_abc123/usage?period=billing',  {    headers: {      'Authorization': 'Bearer hd_a1b2c3d4e5f67890a1b2c3d4e5f67890'    }  });const { data } = await response.json();const pctUsed = ((data.totalTokens / data.tokensLimit) * 100).toFixed(1);console.log(`Token usage: ${pctUsed}% (${data.tokensRemaining.toLocaleString()} remaining)`);

Token Limits by Plan

Token usage is metered on the LLM's input and output tokens combined. Tool calls (search, page retrieval) do not count against your token limit, but the content injected into the LLM context from those tool results does.

Embedding the Assistant

You can embed the AI assistant in your own application using the public chat endpoint:

javascript
const visitorId = `v_${crypto.randomUUID()}`;

javascript
let conversationId = null;async function sendMessage(message) {  const response = await fetch(    `https://api.holydocs.com/api/v1/assistant/${projectId}/chat`,    {      method: 'POST',      headers: { 'Content-Type': 'application/json' },      body: JSON.stringify({ message, visitorId, conversationId })    }  );  // Parse SSE stream, capture conversationId from 'start' event}

Rate Limits

Error Codes