Add Documents to Knowledge Base

Add Knowledge Base Documents

curl --request POST \
  --url https://api.xpander.ai/v1/knowledge/{kb_id}/documents \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "document_urls": [
    "https://example.com/handbook.pdf"
  ]
}
'

import requests

url = "https://api.xpander.ai/v1/knowledge/{kb_id}/documents"

payload = { "document_urls": ["https://example.com/handbook.pdf"] }
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({document_urls: ['https://example.com/handbook.pdf']})
};

fetch('https://api.xpander.ai/v1/knowledge/{kb_id}/documents', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.xpander.ai/v1/knowledge/{kb_id}/documents",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'document_urls' => [
        'https://example.com/handbook.pdf'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.xpander.ai/v1/knowledge/{kb_id}/documents"

	payload := strings.NewReader("{\n  \"document_urls\": [\n    \"https://example.com/handbook.pdf\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.xpander.ai/v1/knowledge/{kb_id}/documents")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"document_urls\": [\n    \"https://example.com/handbook.pdf\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.xpander.ai/v1/knowledge/{kb_id}/documents")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"document_urls\": [\n    \"https://example.com/handbook.pdf\"\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "items": [
    {
      "id": "d4d4d4d4-e5e5-f6f6-a7a7-b8b8b8b8b8b8",
      "name": "handbook.pdf",
      "url": "https://example.com/handbook.pdf",
      "status": "indexed",
      "created_at": "2026-07-28T20:55:54.042725Z"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20,
  "total_pages": 1
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

POST

knowledge

{kb_id}

documents

Add Knowledge Base Documents

curl --request POST \
  --url https://api.xpander.ai/v1/knowledge/{kb_id}/documents \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "document_urls": [
    "https://example.com/handbook.pdf"
  ]
}
'

import requests

url = "https://api.xpander.ai/v1/knowledge/{kb_id}/documents"

payload = { "document_urls": ["https://example.com/handbook.pdf"] }
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({document_urls: ['https://example.com/handbook.pdf']})
};

fetch('https://api.xpander.ai/v1/knowledge/{kb_id}/documents', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.xpander.ai/v1/knowledge/{kb_id}/documents",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'document_urls' => [
        'https://example.com/handbook.pdf'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.xpander.ai/v1/knowledge/{kb_id}/documents"

	payload := strings.NewReader("{\n  \"document_urls\": [\n    \"https://example.com/handbook.pdf\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.xpander.ai/v1/knowledge/{kb_id}/documents")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"document_urls\": [\n    \"https://example.com/handbook.pdf\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.xpander.ai/v1/knowledge/{kb_id}/documents")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"document_urls\": [\n    \"https://example.com/handbook.pdf\"\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "items": [
    {
      "id": "d4d4d4d4-e5e5-f6f6-a7a7-b8b8b8b8b8b8",
      "name": "handbook.pdf",
      "url": "https://example.com/handbook.pdf",
      "status": "indexed",
      "created_at": "2026-07-28T20:55:54.042725Z"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20,
  "total_pages": 1
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

Upload documents to a knowledge base by providing URLs. The documents will be downloaded, processed, and indexed for semantic search.

Path Parameters

string

required

Unique identifier of the knowledge base (UUID format)

Request Body

array

required

Array of document URLs to add to the knowledge baseSupported formats:

PDF documents
Microsoft Word (.docx, .doc)
Text files (.txt, .md)
Web pages (HTML)
CSV and Excel files
Presentations (PPTX, PPT)
JSON and YAML files

Response

Returns an array of created document objects:

string

Knowledge base ID

string

Unique identifier for the document (UUID) - initially null, assigned after processing completes

string

Document name (initially null)

string

URL of the document

Example Request

curl -X POST -H "x-api-key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "document_urls": [
      "https://example.com/product-guide.pdf",
      "https://example.com/faq-page"
    ]
  }' \
  https://api.xpander.ai/v1/knowledge/<kb-id>/documents

Example Response

[
  {
    "kb_id": "<kb-id>",
    "id": null,
    "name": null,
    "document_url": "https://example.com/product-guide.pdf"
  },
  {
    "kb_id": "<kb-id>",
    "id": null,
    "name": null,
    "document_url": "https://example.com/faq-page"
  }
]

Processing Flow

Upload - Documents are queued for processing
Download - System downloads documents from provided URLs
Extract - Text content is extracted from documents
Chunk - Content is split into searchable chunks
Embed - Chunks are converted to vector embeddings
Index - Embeddings are stored in the vector database

Processing typically takes 10-60 seconds per document depending on size.

Supported File Types

Documents: PDF, DOCX, DOC, TXT, MD, RTF
Spreadsheets: CSV, XLSX, XLS
Presentations: PPTX, PPT
Web: HTML, XML
Code: JSON, YAML, various programming languages

Notes

Documents must be publicly accessible via HTTP/HTTPS
Maximum file size: 50MB per document
The id field is null initially until the document is processed and indexed
The document ID is assigned after processing/indexing completes
Use List Documents to check processing progress
Duplicate URLs will create separate document entries

Authorizations

x-api-key

string

header

required

API Key for authentication

Path Parameters

kb_id

string

required

Body

application/json

Request model for adding documents to a knowledge base.

document_urls

string[]

required

Documents URLs

Response

Successful Response

document_url

string

required

Document URL

kb_id

string | null

KB identifier

string | null

Document unique identifier

name

string | null

Document name

List Knowledge Base Documents

Get Knowledge Base Document

⌘I

Overview

REST API - Agents

REST API - Scheduled Tasks

REST API - Self-Schedules

Agent Workspace

REST API - Agent Gateway

REST API - Tasks

REST API - Knowledge

REST API - Workflows

REST API - Tools

REST API - Custom Functions

REST API - Misc

Add Documents to Knowledge Base

Path Parameters

Request Body

Response

Example Request

Example Response

Processing Flow

Supported File Types

Notes

Authorizations

Path Parameters

Body

Response

​Path Parameters

​Request Body

​Response

​Example Request

​Example Response

​Processing Flow

​Supported File Types

​Notes

Authorizations

Path Parameters

Body

Response

Path Parameters

Request Body

Response

Example Request

Example Response

Processing Flow

Supported File Types

Notes