Reference

Developer API

Every AI Box exposes a local REST API on your own network. Base URL is your appliance address, e.g. http://aibox.local.

Authentication

Send the key as a bearer token. Folder keys scope queries to one folder; developer keys unlock the global chat endpoint. Keys are stored hashed — copy them when created.

Authorization: Bearer aib_live_lgl_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

Endpoints

POST/api/queryAsk a question. Body: { q, top_k, folder_id? }. Returns { answer, citations[] }.
POST/api/query/streamSame as /api/query but streams tokens as SSE 'delta' events, then 'done' with citations.
POST/v1/chat/completionsOpenAI-compatible chat endpoint. Requires a developer key.
GET/api/foldersList folders with document counts and masked key hints.
GET/api/documentsList indexed documents.
GET/api/documents/{id}/chunksPage-level indexed text for a document.
POST/api/uploadUpload a file (multipart form field 'file'). Auto-sorted by the Librarian.
GET/api/statusAppliance health, version, storage and uptime.
POST/api/ai/summarizeSummarise one document with citations.
POST/api/ai/analyzeContract/meeting analysis: parties, dates, obligations, risks.
POST/api/ai/compareSide-by-side comparison of two or more documents.
POST/api/ai/extractExtract structured rows/tables from documents.
POST/api/ai/reportDraft an executive report in Markdown.

Query a folder

curl -X POST http://aibox.local/api/query \
  -H "Authorization: Bearer <FOLDER_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"q":"What is the termination clause?","top_k":3,"folder_id":"fld_legal"}'

Response shape

{
  "answer": "The agreement may be terminated with 30 days notice…",
  "citations": [
    { "documentId": "doc_02", "documentName": "NDA — Acme Corp.pdf",
      "page": 4, "snippet": "…either party may terminate…", "score": 0.82 }
  ]
}

Streaming (SSE)

curl -N -X POST http://aibox.local/api/query/stream \
  -H "Authorization: Bearer <FOLDER_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"q":"Summarize the handbook","top_k":4}'

event: delta
data: {"text":"The handbook"}

event: done
data: {"citations":[...]}

OpenAI-compatible chat

curl -X POST http://aibox.local/v1/chat/completions \
  -H "Authorization: Bearer <DEVELOPER_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"model":"aibox","messages":[{"role":"user","content":"Hello"}]}'

Python (requests)

import requests

r = requests.post(
    "http://aibox.local/api/query",
    headers={"Authorization": "Bearer <FOLDER_API_KEY>"},
    json={"q": "What is the termination clause?", "top_k": 3},
)
print(r.json()["answer"])

Python (OpenAI SDK)

from openai import OpenAI

client = OpenAI(base_url="http://aibox.local/v1", api_key="<DEVELOPER_KEY>")
reply = client.chat.completions.create(
    model="aibox",
    messages=[{"role": "user", "content": "Summarise our leave policy"}],
)
print(reply.choices[0].message.content)

JavaScript / TypeScript (fetch)

const res = await fetch("http://aibox.local/api/query", {
  method: "POST",
  headers: {
    Authorization: "Bearer <FOLDER_API_KEY>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ q: "What is the termination clause?", top_k: 3 }),
});
const { answer, citations } = await res.json();

JavaScript (OpenAI SDK)

import OpenAI from "openai";

const client = new OpenAI({ baseURL: "http://aibox.local/v1", apiKey: "<DEVELOPER_KEY>" });
const reply = await client.chat.completions.create({
  model: "aibox",
  messages: [{ role: "user", content: "Hello" }],
});
console.log(reply.choices[0].message.content);

Document intelligence

Signed-in session required. Each returns structured JSON plus citations.

POST /api/ai/summarize  { "document_id": "doc_01" }
POST /api/ai/analyze    { "document_ids": ["doc_01"], "kind": "contract" }
POST /api/ai/compare    { "document_ids": ["doc_01", "doc_02"] }
POST /api/ai/extract    { "instruction": "Vendor names and prices", "document_ids": ["doc_01"] }
POST /api/ai/report     { "instruction": "Board summary for Q3", "folder_id": "fld_finance" }

Errors & limits