API Reference

Knowledge Base

Manage the AI knowledge base that powers automated responses across your channels.

Overview

The Knowledge Base stores information your AI agent uses when answering contact questions. The API supports all five content types - text, documents, voice transcriptions, product catalogs, and website scraping.

Type	Description	Processing
`text`	Structured text (FAQs, policies, instructions)	Synchronous
`document`	PDF, Word, Excel, TXT, CSV - AI extracts content	Synchronous
`voice`	Audio file — transcribed automatically	Synchronous
`product_catalog`	Products via JSON array or CSV	Synchronous
`website`	Website crawl - async job, poll `/status`	Async

How the AI uses this in chat

Active entries of all types help AI agent replies on WhatsApp, Telegram, Instagram, and web chat. Document and website entries contribute searchable text; voice entries store transcripts; product catalogs supply structured fields and can reference linked media.

Together with the Media library, agents can attach images, videos, and files to outbound messages when your setup calls for it (for example catalog-linked assets or items you uploaded under Media). On inbound messages, audio is typically transcribed to text for the model, and images are analyzed so the assistant can reason about what the customer sent (channel and configuration dependent).

The KnowledgeBase object

{
  "id": 88,
  "title": "Return Policy",
  "type": "text",
  "description": "Customer return and refund policy",
  "business_description": "Used by the sales AI to answer returns-related questions",
  "status": "active",
  "embedding_updated_at": "2026-03-07T10:00:00.000000Z",
  "created_at": "2026-02-15T08:00:00.000000Z",
  "updated_at": "2026-03-07T10:00:00.000000Z"
}

Field	Type	Description
`id`	integer	Unique entry ID
`title`	string	Display name
`type`	string	`text`, `document`, `voice`, `product_catalog`, `website`
`description`	string\|null	Brief summary of the entry
`business_description`	string\|null	Context for how the AI should use this entry
`status`	string	`active` or `inactive`
`embedding_updated_at`	string\|null	When this entry was last prepared for AI search

List knowledge base entries

GET /api/v1/knowledge-base

Parameter	Type	Description
`type`	string	Filter by `text`, `document`, `voice`, `product_catalog`, `website`
`status`	string	`active`, `inactive`
`per_page`	integer	Max 100 (default 25)

Create a text entry

POST /api/v1/knowledge-base
Content-Type: application/json

Field	Type	Required	Notes
`title`	string	✓
`content`	string	✓	The knowledge text (the AI reads this)
`description`	string	No	Brief summary
`business_description`	string	No	Context for AI usage
`status`	string	No	`active` or `inactive` (default: `active`)

curl -X POST https://dashboard.skylightchat.com/api/v1/knowledge-base \
  -H "X-Api-Key: ••••••••••••" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "30-Day Return Policy",
    "content": "We offer a full refund for any item returned within 30 days of purchase.",
    "description": "Customer return and refund policy",
    "business_description": "Used by the customer support AI to answer returns questions."
  }'

Returns 201 Created. Embeddings are generated asynchronously.

Upload a document

POST /api/v1/knowledge-base/document
Content-Type: multipart/form-data

Upload one or more files. The AI automatically extracts and structures the content. Supports PDF, DOCX, DOC, XLSX, CSV, and TXT up to 20 MB each.

Field	Type	Required	Notes
`title`	string	✓
`files[]`	file	✓	One or more files (PDF, DOCX, XLSX, CSV, TXT)
`description`	string	No
`business_description`	string	No
`status`	string	No	`active` or `inactive`

curl -X POST https://dashboard.skylightchat.com/api/v1/knowledge-base/document \
  -H "X-Api-Key: ••••••••••••" \
  -F "title=Product Manual" \
  -F "files[]=@/path/to/manual.pdf" \
  -F "business_description=Used to answer product-specific questions."

Response (201 Created)

{
  "success": true,
  "data": {
    "knowledge_base": { "id": 91, "title": "Product Manual", "type": "document" },
    "documents": [
      {
        "id": 12,
        "original_name": "manual.pdf",
        "file_type": "pdf",
        "processing_status": "completed",
        "extracted_content": "Chapter 1: Getting Started..."
      }
    ]
  }
}

Document processing statuses

Status	Meaning
`pending`	Queued
`processing`	AI is extracting content
`completed`	Content extracted successfully
`failed`	Extraction failed - see `processing_error`

Upload a voice note

POST /api/v1/knowledge-base/voice
Content-Type: multipart/form-data

Upload an audio file. Transcription is performed synchronously. Max 10 MB. Supports MP3, WAV, M4A, OGG, WEBM.

Field	Type	Required	Notes
`title`	string	✓
`audio_file`	file	✓	MP3, WAV, M4A, OGG, WEBM
`language`	string	No	ISO 639-1 code e.g. `ar`, `en` (default: auto-detect)
`description`	string	No
`business_description`	string	No
`status`	string	No	`active` or `inactive`

curl -X POST https://dashboard.skylightchat.com/api/v1/knowledge-base/voice \
  -H "X-Api-Key: ••••••••••••" \
  -F "title=CEO Welcome Message" \
  -F "audio_file=@/path/to/welcome.mp3" \
  -F "language=en"

Response (201 Created)

{
  "success": true,
  "data": {
    "knowledge_base": { "id": 92, "title": "CEO Welcome Message", "type": "voice" },
    "voice_note": {
      "id": 5,
      "transcription_status": "completed",
      "transcription": "مرحباً بك في نخيل. We are committed to delivering..."
    }
  }
}

Create a product catalog

POST /api/v1/knowledge-base/product-catalog
Content-Type: application/json  (or multipart/form-data for CSV)

Create a product catalog with products via a JSON array, a CSV file upload, or both.

Field	Type	Required	Notes
`title`	string	✓
`products`	array	*	JSON array of product objects
`csv_file`	file	*	CSV file (see columns below)
`description`	string	No
`business_description`	string	No
`status`	string	No	`active` or `inactive`

* At least one of products or csv_file is required.

Product object fields

Field	Type	Required	Notes
`product_name`	string	✓
`product_description`	string	No
`sku`	string	No
`price`	number	No
`currency`	string	No	Default: `USD`
`category`	string	No
`stock_quantity`	integer	No
`image_url`	string	No
`is_available`	boolean	No	Default: `true`
`product_attributes`	object	No	Extra metadata (source, purchase link, integration fields)

CSV column names: product_name (or name), description, sku, price, currency, category, stock (or stock_quantity), image_url

Product response fields

When you list or get a product_catalog entry, each product includes the create fields above plus:

Field	Type	Description
`id`	integer	Product ID
`media_files`	array	Linked media library items (when present)
`product_attributes`	object	Source metadata (e.g. `source`, `purchase_url`, integration IDs)
`purchase_url`	string\|null	Convenience field — checkout/product page URL from `product_attributes.purchase_url` when set

purchase_url is populated for products synced from Salla, website crawls (when a product page URL was extracted), and any catalog that stores a purchase link in product_attributes.

# JSON array
curl -X POST https://dashboard.skylightchat.com/api/v1/knowledge-base/product-catalog \
  -H "X-Api-Key: ••••••••••••" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Summer 2026 Collection",
    "products": [
      {
        "product_name": "Linen Shirt",
        "product_description": "Breathable linen shirt for warm weather",
        "sku": "LS-001",
        "price": 49.99,
        "currency": "USD",
        "category": "Shirts",
        "stock_quantity": 120,
        "is_available": true
      }
    ]
  }'

# CSV upload
curl -X POST https://dashboard.skylightchat.com/api/v1/knowledge-base/product-catalog \
  -H "X-Api-Key: ••••••••••••" \
  -F "title=Summer 2026 Collection" \
  -F "csv_file=@/path/to/products.csv"

Response (201 Created)

{
  "success": true,
  "data": {
    "knowledge_base": { "id": 93, "title": "Summer 2026 Collection", "type": "product_catalog" },
    "products_created": 1,
    "products": [
      {
        "id": 41,
        "product_name": "Linen Shirt",
        "sku": "LS-001",
        "price": 49.99,
        "currency": "USD",
        "stock_quantity": 120,
        "is_available": true,
        "product_attributes": {},
        "purchase_url": null
      }
    ]
  }
}

Example product from a synced store or website crawl:

{
  "id": 912,
  "product_name": "فستان صيفي",
  "sku": "DRS-42",
  "price": 199,
  "currency": "SAR",
  "is_available": true,
  "product_attributes": {
    "source": "salla",
    "purchase_url": "https://store.salla.sa/product/912"
  },
  "purchase_url": "https://store.salla.sa/product/912"
}

Add products to an existing catalog

POST /api/v1/knowledge-base/{id}/products

Accepts the same products array and/or csv_file as above. Appends to the existing catalog.

Remove a product

DELETE /api/v1/knowledge-base/{id}/products/{product_id}

Returns 204 No Content.

Crawl a website

POST /api/v1/knowledge-base/website
Content-Type: application/json

Submit a website URL for crawling. The job is dispatched asynchronously - you receive a 202 Accepted immediately, then poll GET /knowledge-base/{id}/status to track progress.

Products found while crawling are synced into a dedicated product_catalog knowledge base (titled like Website Products — example.com), not left only as website prose. Each product can include price, SKU, image, and purchase_url when available. Company/help content stays on the website entry. List catalogs with GET /api/v1/knowledge-base?type=product_catalog.

Field	Type	Required	Notes
`title`	string	✓
`website_url`	string	✓	Valid URL
`sitemap_url`	string	No	Provide sitemap for faster discovery
`crawl_entire_site`	boolean	No	Default: `false`
`max_pages`	integer	No	1-100, default 10
`max_depth`	integer	No	1-5, default 2
`allowed_paths`	string	No	Comma-separated path prefixes to include e.g. `/docs,/help`
`excluded_paths`	string	No	Comma-separated path prefixes to skip e.g. `/blog,/careers`
`description`	string	No
`business_description`	string	No
`status`	string	No	`active` or `inactive`

curl -X POST https://dashboard.skylightchat.com/api/v1/knowledge-base/website \
  -H "X-Api-Key: ••••••••••••" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "مركز مساعدة نخيل",
    "website_url": "https://help.nakheel.sa",
    "crawl_entire_site": true,
    "max_pages": 50,
    "excluded_paths": "/status,/login"
  }'

Response (202 Accepted)

{
  "success": true,
  "data": {
    "knowledge_base": { "id": 94, "title": "مركز مساعدة نخيل", "type": "website" },
    "website": {
      "id": 8,
      "website_url": "https://help.nakheel.sa",
      "crawl_status": "pending",
      "pages_crawled": 0,
      "total_pages_found": 0
    }
  }
}

Crawl status values

Status	Meaning
`pending`	Job is queued
`crawling`	Actively crawling pages
`completed`	All pages extracted
`partial`	Some pages extracted, some failed
`failed`	Crawl failed entirely - see `crawl_error`

After completed, if the crawl extracted sellable products, a related product_catalog entry is created or updated automatically. Poll until the website status is complete, then fetch GET /api/v1/knowledge-base?type=product_catalog (or open the catalog in the dashboard) to read structured products with purchase_url / product_attributes.

Poll processing status

GET /api/v1/knowledge-base/{id}/status

Returns real-time progress for any entry type. Especially useful for website (async) and to verify document/voice processing completed.

Website status example

{
  "success": true,
  "data": {
    "id": 94,
    "title": "مركز مساعدة نخيل",
    "type": "website",
    "crawl_status": "crawling",
    "pages_crawled": 12,
    "total_pages": 50,
    "progress_pct": 24,
    "crawl_error": null,
    "last_crawled_at": null,
    "completed": false
  }
}

Document status example

{
  "success": true,
  "data": {
    "id": 91,
    "type": "document",
    "completed": true,
    "total": 2,
    "pending_count": 0,
    "failed_count": 0,
    "documents": [
      { "id": 12, "original_name": "manual.pdf", "processing_status": "completed" },
      { "id": 13, "original_name": "warranty.pdf", "processing_status": "completed" }
    ]
  }
}

Get an entry

GET /api/v1/knowledge-base/{id}

Returns the full entry with all associated content (documents, voice notes, products, or website details) depending on the type.

For product_catalog, the products array includes product_attributes and purchase_url (see Product response fields).

Update an entry

PUT /api/v1/knowledge-base/{id}

Field	Type	Notes
`title`	string
`content`	string	Only for `text` type. Changing content refreshes how the entry is used for AI answers
`description`	string
`business_description`	string
`status`	string	`active` or `inactive`

Delete an entry

DELETE /api/v1/knowledge-base/{id}

Permanently removes the entry and all associated files. Returns 204 No Content.

Deleting an active knowledge base entry may affect AI response quality immediately.

Chunks

Chunks are text segments the AI can use when answering questions. Entries are usually split automatically when content is processed; you can also list, create, update, or delete individual chunks via the API.

Create and update require the chunk to be ready for AI search before they succeed. Delete permanently removes the chunk from the knowledge base.

The Chunk object

{
  "id": 412,
  "knowledge_base_id": 88,
  "content": "We offer a full refund for any item returned within 30 days of purchase.",
  "char_count": 72,
  "chunk_index": 0,
  "total_chunks": 3,
  "context_header": null,
  "keywords": null,
  "has_embedding": true,
  "created_at": "2026-03-07T10:00:00+00:00",
  "updated_at": "2026-03-07T10:00:00+00:00"
}

Field	Type	Description
`id`	integer	Unique chunk ID
`knowledge_base_id`	integer	Parent knowledge base entry
`content`	string	Chunk text available to the AI
`char_count`	integer	Length of `content`
`chunk_index`	integer	Zero-based order within the entry
`total_chunks`	integer	Total chunks on this entry
`context_header`	string\|null	Optional context prefix
`keywords`	array\|null	Optional keywords
`has_embedding`	boolean	Whether the chunk is ready for AI search

List chunks

GET /api/v1/knowledge-base/{id}/chunks

Returns chunks ordered by chunk_index.

{
  "success": true,
  "data": {
    "knowledge_base_id": 88,
    "chunks": [ { "id": 412, "chunk_index": 0, "content": "..." } ],
    "count": 1
  }
}

Get a chunk

GET /api/v1/knowledge-base/{id}/chunks/{chunk_id}

Create a chunk

POST /api/v1/knowledge-base/{id}/chunks
Content-Type: application/json

Field	Type	Required	Notes
`content`	string	✓	Max 65,000 characters. Must be processable for AI search — if processing fails, the chunk is not created.

Returns 201 Created with the chunk object.

curl -X POST https://dashboard.skylightchat.com/api/v1/knowledge-base/88/chunks \
  -H "X-Api-Key: ••••••••••••" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Refunds are issued to the original payment method within 5–7 business days."
  }'

Update a chunk

PUT /api/v1/knowledge-base/{id}/chunks/{chunk_id}

Field	Type	Required	Notes
`content`	string	✓	Max 65,000 characters. Updates this chunk and refreshes it for AI search.

Delete a chunk

DELETE /api/v1/knowledge-base/{id}/chunks/{chunk_id}

Permanently removes the chunk from the knowledge base. Returns 204 No Content.

curl -X DELETE https://dashboard.skylightchat.com/api/v1/knowledge-base/88/chunks/412 \
  -H "X-Api-Key: ••••••••••••"

Deleting a chunk immediately removes it from AI retrieval for that entry.

Web Chat

Monitor and manage live chat sessions from the embedded web widget.

Voice

Generate natural Arabic speech with SkyLight Talk — use a built-in preset voice, or clone a custom brand voice.