curl --request POST \
--url https://tavusapi.com/v2/documents \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"document_url": "https://docs.example.com/"
}
'{
"document_id": "d8-5c71baca86fc",
"document_name": "Example Docs",
"document_url": "https://docs.example.com/",
"status": "started",
"progress": null,
"error_message": "<string>",
"created_at": "2024-01-01T12:00:00Z",
"updated_at": "2024-01-01T12:00:00Z",
"callback_url": "https://your-server.com/webhook",
"tags": [
"docs",
"website"
],
"crawl_config": {
"depth": 2,
"max_pages": 10
},
"crawled_urls": [
"https://docs.example.com/",
"https://docs.example.com/getting-started",
"https://docs.example.com/api"
],
"last_crawled_at": "2024-01-01T12:00:00Z",
"crawl_count": 1
}{
"error": "Invalid request: document_url is required"
}{
"message": "Invalid access token"
}{
"error": "Crawl document limit reached (100). Contact support@tavus.io to increase your limit."
}Create Document
Upload documents to your knowledge base for PALs to reference during conversations.
curl --request POST \
--url https://tavusapi.com/v2/documents \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"document_url": "https://docs.example.com/"
}
'{
"document_id": "d8-5c71baca86fc",
"document_name": "Example Docs",
"document_url": "https://docs.example.com/",
"status": "started",
"progress": null,
"error_message": "<string>",
"created_at": "2024-01-01T12:00:00Z",
"updated_at": "2024-01-01T12:00:00Z",
"callback_url": "https://your-server.com/webhook",
"tags": [
"docs",
"website"
],
"crawl_config": {
"depth": 2,
"max_pages": 10
},
"crawled_urls": [
"https://docs.example.com/",
"https://docs.example.com/getting-started",
"https://docs.example.com/api"
],
"last_crawled_at": "2024-01-01T12:00:00Z",
"crawl_count": 1
}{
"error": "Invalid request: document_url is required"
}{
"message": "Invalid access token"
}{
"error": "Crawl document limit reached (100). Contact support@tavus.io to increase your limit."
}https://docs.tavus.io/openapi.yaml for the full HTTP API contract.Body
Direct URL to a file or a website for your Knowledge Base. Submitting this URL starts processing asynchronously; the document can be used in conversations once processing completes, which may take a few minutes depending on file size.
For now, our Knowledge Base only supports documents written in English and works best for conversations in English. We will be expanding our Knowledge Base language support soon.Maximum file size 50MB. Supported file formats: .pdf, .txt, .docx, .doc, .png, .jpg, .pptx, .csv, and .xlsx. Website URLs are supported: a snapshot of the page is processed into document content; use the crawl object for multi-page crawling from a starting URL.
"https://docs.example.com/"
Optional tags to categorize the document for management and for use with document-based access in conversations. After the document is ready, attach it via document_ids on Create PAL or Create Conversation.
["docs", "website"]
Optional configuration for website crawling. When provided with a website URL, the system follows links from the starting URL and processes multiple pages into a single document. Without this parameter, only the single page at the URL is scraped.
Rate limits: at most 10,000 crawl documents per user, at most 5 concurrent crawls at any time, and a 1-hour cooldown between recrawls of the same document.
To fetch fresh content after a crawled document exists, use Recrawl Document.
Show child attributes
Show child attributes
Response
Document created successfully
Error code indicating why processing failed. Only present when status is error. Possible values include: file_download_failed, file_format_unsupported, file_size_too_large, file_empty, invalid_file_url, document_processing_failed, website_processing_failed, chunking_failed, embedding_failed, vector_store_failed, contact_support.

