---
title: "Create Document"
method: POST
path: "/v2/documents"
tags: ["Documents"]
---

# Create Document

`POST /v2/documents`

Upload documents to your knowledge base for PALs to reference during conversations.

## Request body

- object
  - `document_url` string, required — Direct URL to a file or a website for your [Knowledge Base](/sections/conversational-video-interface/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. <Note> 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. </Note> 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.
  - `document_name` string — Optional name for the document. If not provided, a default name will be generated.
  - `callback_url` string — Optional URL that receives status updates while the document processes asynchronously (e.g. started, processing, ready, error).
  - `tags` string[] — 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](/api-reference/pals/create-pal) or [Create Conversation](/api-reference/conversations/create-conversation).
  - `crawl` object — 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 **100** 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](/api-reference/documents/recrawl-document).
    - `depth` integer — How many levels deep to follow links from the starting URL (1-10). A depth of 1 means only pages directly linked from the starting URL.
    - `max_pages` integer — Maximum number of pages to crawl (1-100). Processing stops once this limit is reached.

## Response `200`

Document created successfully

- object
  - `document_id` string — Unique identifier for the created document
  - `document_name` string — Name of the document
  - `document_url` string — URL of the document or website
  - `status` 'started' | 'processing' | 'ready' | 'error' | 'recrawling' — Current status of the document processing. Possible values: `started`, `processing`, `ready`, `error`, `recrawling`.
  - `progress` integer, nullable — Processing progress as a percentage (0-100). Null when processing has not started or is complete.
  - `error_message` string, nullable — 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`.
  - `created_at` string — ISO 8601 timestamp of when the document was created
  - `updated_at` string — ISO 8601 timestamp of when the document was last updated
  - `callback_url` string — URL that will receive status updates
  - `tags` string[] — Array of document tags
  - `crawl_config` object, nullable — The crawl configuration used for this document (only present for crawled websites)
    - `depth` integer — Crawl depth setting
    - `max_pages` integer — Maximum pages setting
  - `crawled_urls` string[], nullable — List of URLs that were crawled (only present for crawled websites after processing completes)
  - `last_crawled_at` string, nullable — ISO 8601 timestamp of when the document was last crawled
  - `crawl_count` integer, nullable — Number of times the document has been crawled

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `429` — Too Many Requests - Crawl rate limit exceeded

---

[API](https://skmtc.dev/tavus/apis/tavus-developer-api-collection.md) · [All operations](https://skmtc.dev/tavus/apis/tavus-developer-api-collection/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/tavus/tavus-developer-api-collection/revisions/c878e2f6508d/schema)