> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xpander.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Add Documents to Knowledge Base
> Add one or more documents to a knowledge base
Upload documents to a knowledge base by providing URLs. The documents will be downloaded, processed, and indexed for semantic search.
## Path Parameters
Unique identifier of the knowledge base (UUID format)
## Request Body
Array of document URLs to add to the knowledge base
**Supported 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:
Knowledge base ID
Unique identifier for the document (UUID) - initially null, assigned after processing completes
Document name (initially null)
URL of the document
## Example Request
```bash theme={"dark"}
curl -X POST -H "x-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//documents
```
## Example Response
```json theme={"dark"}
[
{
"kb_id": "",
"id": null,
"name": null,
"document_url": "https://example.com/product-guide.pdf"
},
{
"kb_id": "",
"id": null,
"name": null,
"document_url": "https://example.com/faq-page"
}
]
```
## Processing Flow
1. **Upload** - Documents are queued for processing
2. **Download** - System downloads documents from provided URLs
3. **Extract** - Text content is extracted from documents
4. **Chunk** - Content is split into searchable chunks
5. **Embed** - Chunks are converted to vector embeddings
6. **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](/api-reference/v1/knowledge/list-documents) to check processing progress
* Duplicate URLs will create separate document entries
## OpenAPI
````yaml POST /v1/knowledge/{kb_id}/documents
openapi: 3.1.0
info:
title: xpander.ai API Service
description: |2-
The xpander.ai API Service provides a unified REST API for managing AI agents,
executing tasks, managing knowledge bases, and integrating with external systems.
Features:
- Agent Management: Create, update, deploy, and delete AI agents
- Task Execution: Invoke agents with support for sync, async, and streaming modes
- Knowledge Bases: Manage knowledge bases and documents for RAG workflows
- Tools: Discover, connect, and attach tools (connectors, custom functions, MCP servers, sub-agents, workflows) to agents and workflows
- MCP Integration: Model Context Protocol support for standardized AI interactions
Authentication: All endpoints require authentication via either an API key (`x-api-key`) or an OAuth2 JWT (`Authorization: Bearer `).
version: '0.001'
servers:
- url: https://api.xpander.ai
security: []
paths:
/v1/knowledge/{kb_id}/documents:
post:
tags:
- API v1
- Knowledge
- Knowledge CRUD
- Knowledge Documents
summary: Add Knowledge Base Documents
description: Add knowledge base documents
operationId: Add_knowledge_base_documents_v1_knowledge__kb_id__documents_post
parameters:
- name: kb_id
in: path
required: true
schema:
type: string
title: Kb Id
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AddDocumentsRequest'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: array
items:
$ref: >-
#/components/schemas/src__models__knowledge__documents__KnowledgeBaseDocumentItem
title: >-
Response Add Knowledge Base Documents V1 Knowledge Kb Id
Documents Post
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- APIKeyHeader: []
components:
schemas:
AddDocumentsRequest:
properties:
document_urls:
items:
type: string
type: array
title: Document Urls
description: Documents URLs
type: object
required:
- document_urls
title: AddDocumentsRequest
description: Request model for adding documents to a knowledge base.
src__models__knowledge__documents__KnowledgeBaseDocumentItem:
properties:
kb_id:
anyOf:
- type: string
- type: 'null'
title: Kb Id
description: KB identifier
id:
anyOf:
- type: string
- type: 'null'
title: Id
description: Document unique identifier
name:
anyOf:
- type: string
- type: 'null'
title: Name
description: Document name
document_url:
type: string
title: Document Url
description: Document URL
type: object
required:
- document_url
title: KnowledgeBaseDocumentItem
description: Knowledge base document metadata model.
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
type: object
required:
- loc
- msg
- type
title: ValidationError
securitySchemes:
APIKeyHeader:
type: apiKey
description: API Key for authentication
in: header
name: x-api-key
````