Documents

Upload documents to knowledge bases for indexing, manage document lifecycle, and configure URL/feed sources for automatic content ingestion.

All API requests require a valid JWT token in the Authorization: Bearer <token> header. The API Gateway decodes the JWT and forwards auth context (user-id, organization-id, user-email, x-platform-role, x-org-role) as headers to downstream services.

This endpoint incurs provider cost and records a billing event via record_external_cost_event(). Credits are deducted from the organization’s wallet based on the configured margin multiplier.

Upload Document

Upload a file to a knowledge base. The document is stored and queued for asynchronous processing (text extraction, chunking, embedding, and optional graph extraction).

Path Parameters

string

required

KB UUID.

Request Body

Multipart file upload. Send the file as a multipart/form-data request.

Supported File Types

Type	Extensions
PDF	`.pdf`
Word	`.docx`, `.doc`
Text	`.txt`, `.md`, `.csv`
Web	`.html`, `.htm`
Images	`.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`
Audio	`.mp3`, `.wav`, `.m4a`, `.ogg`
Video	`.mp4`, `.webm`, `.mov`

Response (201)

object

The created document record.

Show Document object

string

Document UUID.

string

Parent KB UUID.

string

Document title (filename).

string

File MIME type.

number

File size in bytes.

string

Current status (see below).

string

ISO 8601 timestamp.

string

BullMQ job ID for tracking processing progress.

string

Confirmation message.

curl -X POST https://your-domain.com/api/knowledge/kb/KB_ID/documents \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@/path/to/document.pdf"

const formData = new FormData();
formData.append("file", fileBlob, "document.pdf");

const response = await fetch(
  `https://your-domain.com/api/knowledge/kb/${kbId}/documents`,
  {
    method: "POST",
    headers: { Authorization: `Bearer ${token}` },
    body: formData,
  }
);

const { document, jobId } = await response.json();

Processing Pipeline

After upload, documents go through this async pipeline:

Load: LlamaParse (for PDF/DOCX) or LangChain fallback loaders
Chunk: Split into chunks (1000 characters, 200 overlap)
Embed: Generate multimodal embeddings via Gemini Embedding 2 (3072 dimensions)
Store: Upsert vectors to Pinecone (production) or ChromaDB (local)
Graph (optional): Extract entities and relationships
Summarize (optional): Generate document summary for KB map

Processing Statuses

Status	Description
`pending`	Queued for processing
`processing`	Currently being processed
`completed`	Successfully indexed
`failed`	Processing failed (can be retried)

List Documents

List all documents in a knowledge base.

Path Parameters

string

required

KB UUID.

Query Parameters

number

default:"50"

Maximum results.

number

default:"0"

Pagination offset.

string

Filter to one processing status: pending, processing, completed, failed. Applied server-side — an unrecognized value is ignored (treated as no filter), matching the “All” tab in the UI.

string

Case-insensitive substring match on document title. Applied server-side.

string

default:"published"

Result ordering: recent (created_at DESC, id DESC — fresh uploads first, even on feed-fed KBs whose other rows all carry publish dates) or published (legacy published_at DESC NULLS LAST, created_at DESC feed order). An unrecognized value is ignored and falls back to published. The Documents tab requests recent explicitly so new uploads always land on page 1.

Response (200)

object[]

Array of document objects.

number

Total count for the applied filters — not the unfiltered KB total and not the current page size. ?status=failed on a KB with 1,809 documents and 4 failed returns total: 4, regardless of limit/offset.

number

Applied limit.

number

Applied offset.

curl

curl "https://your-domain.com/api/knowledge/kb/KB_ID/documents?status=failed&search=report" \
  -H "Authorization: Bearer $TOKEN"

Get Document Chunks

Paginated list of a document’s indexed chunks. Powers the document detail page’s chunk viewer.

Path Parameters

string

required

KB UUID.

string

required

Document UUID.

Query Parameters

number

default:"50"

Maximum results.

number

default:"0"

Pagination offset.

Response (200)

object[]

Array of chunk objects.

number

Total chunk count for this document.

number

Applied limit.

number

Applied offset.

curl

curl https://your-domain.com/api/knowledge/kb/KB_ID/documents/DOC_ID/chunks?limit=20 \
  -H "Authorization: Bearer $TOKEN"

Delete Document

Delete a document and its associated chunks and embeddings from a knowledge base.

Path Parameters

string

required

KB UUID.

string

required

Document UUID.

Response (200)

{
  "message": "Document deleted successfully",
  "documentId": "doc-uuid",
  "chunksDeleted": 12
}

string

Confirmation.

string

Deleted document UUID.

number

Number of chunk/vector rows removed.

Retry Failed Document

Re-queue a failed document for processing. Resets the status to pending and creates a new processing job.

Path Parameters

string

required

KB UUID.

string

required

Document UUID.

Response (200)

string

Confirmation.

string

Document UUID.

string

New processing job ID.

URL Sources

Add URL Source

Add a URL or feed source to a knowledge base. Content is fetched, processed, and indexed. Supports single URLs, RSS feeds, and web crawling.

Path Parameters

string

required

KB UUID.

Request Body

string

required

Source URL (webpage, RSS feed, or social media profile).

string

default:"url"

Source type: url, rss, linkedin, twitter, medium.

boolean

default:"false"

Enable automatic periodic re-sync.

number

default:"60"

Sync interval in minutes (when syncEnabled is true).

number

Maximum items to fetch from feeds.

number

Maximum pages to crawl.

number

Link crawl depth (0 = single page only).

string

Strategy for media content: native (embed directly) or transcription (convert to text first).

boolean

Enable visual entity extraction from images.

curl -X POST https://your-domain.com/api/knowledge/kb/KB_ID/sources/url \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://blog.example.com/feed",
    "sourceType": "rss",
    "syncEnabled": true,
    "syncFrequencyMinutes": 120
  }'

await fetch(
  `https://your-domain.com/api/knowledge/kb/${kbId}/sources/url`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      url: "https://blog.example.com/feed",
      sourceType: "rss",
      syncEnabled: true,
      syncFrequencyMinutes: 120,
    }),
  }
);

Light Scrape

Quick URL scrape for content preview. Fetches and extracts text from up to 10 URLs without full KB indexing. Used by the Creator Wizard for AI profile generation.

Request Body

object[]

required

Array of URLs to scrape (max 10).

Show URL object

string

required

URL to scrape.

string

required

Source type label.

Response (200)

object[]

Scrape results for each URL.

Show Result object

string

The scraped URL.

string

Source type.

string

Page title.

string

Extracted text (max 2000 chars per URL).

string

Author if detected.

string

Page excerpt if available.

string

Error message if scrape failed for this URL.

curl

curl -X POST https://your-domain.com/api/knowledge/light-scrape \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": [
      {"url": "https://example.com/about", "sourceType": "website"},
      {"url": "https://blog.example.com/post-1", "sourceType": "blog"}
    ]
  }'

Light scrape has a 10-second timeout per URL and returns a maximum of 2000 characters of text per URL. For full content indexing, use the document upload or URL source endpoints.

Text Extraction

Extract text and images from an uploaded file without indexing it into a knowledge base. Useful for previewing content or processing attachments.

Request Body

Multipart file upload.

Response (200)

Returns extracted text content and any images found in the document.

Getting Started

Agent Provisioning

Bot Service

Auth Service

Knowledge Service

Documents

Documents

Upload Document

Path Parameters

Request Body

Supported File Types

Response (201)

Processing Pipeline

Processing Statuses

List Documents

Path Parameters

Query Parameters

Response (200)

Get Document Chunks

Path Parameters

Query Parameters

Response (200)

Delete Document

Path Parameters

Response (200)

Retry Failed Document

Path Parameters

Response (200)

URL Sources

Add URL Source

Path Parameters

Request Body

Light Scrape

Request Body

Response (200)

Text Extraction

Request Body

Response (200)

​Documents

​Upload Document

​Path Parameters

​Request Body

​Supported File Types

​Response (201)

​Processing Pipeline

​Processing Statuses

​List Documents

​Path Parameters

​Query Parameters

​Response (200)

​Get Document Chunks

​Path Parameters

​Query Parameters

​Response (200)

​Delete Document

​Path Parameters

​Response (200)

​Retry Failed Document

​Path Parameters

​Response (200)

​URL Sources

​Add URL Source

​Path Parameters

​Request Body

​Light Scrape

​Request Body

​Response (200)

​Text Extraction

​Request Body

​Response (200)

Documents

Upload Document

Path Parameters

Request Body

Supported File Types

Response (201)

Processing Pipeline

Processing Statuses

List Documents

Path Parameters

Query Parameters

Response (200)

Get Document Chunks

Path Parameters

Query Parameters

Response (200)

Delete Document

Path Parameters

Response (200)

Retry Failed Document

Path Parameters

Response (200)

URL Sources

Add URL Source

Path Parameters

Request Body

Light Scrape

Request Body

Response (200)

Text Extraction

Request Body

Response (200)