POST
/
v2
/
documents
Create Document
curl --request POST \
  --url https://tavusapi.com/v2/documents \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
  "document_url": "https://example.com/document.pdf",
  "document_name": "Important Document",
  "callback_url": "https://your-server.com/webhook",
  "properties": {
    "department": "sales",
    "priority": "high"
  },
  "tags": [
    "important",
    "meeting"
  ]
}'
{
  "uuid": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "document_name": "Important Document",
  "document_url": "https://example.com/document.pdf",
  "status": "processing",
  "created_at": "2024-01-01T12:00:00Z",
  "updated_at": "2024-01-01T12:00:00Z",
  "callback_url": "https://your-server.com/webhook",
  "tags": [
    "important",
    "meeting"
  ],
  "properties": {
    "department": "sales",
    "priority": "high"
  }
}
For now, our Knowledge Base only supports documents written in English and works best for conversations in English.We’ll be expanding our Knowledge Base language support soon!
Create a new document in your Knowledge Base. When you hit this endpoint, Tavus kicks off the processing of the document, so it can be used as part of your knowledge base in conversations once processing is complete. The file size limit is 50MB. The processing can take up to a few minutes depending on file size. Currently, we support the following file formats: .pdf, .txt, .docx, .doc, .png, .jpg, .pptx, .csv, and .xlsx. Website URLs are also supported, where a website snapshot will be processed and transformed into a document. You can manage documents by adding tags using the document_tags entry in the request body. Once created, you can add the document to your personas (see Create Persona) and your conversations (see Create Conversation).

Authorizations

​
x-api-key
string
header
required

Body

application/json
​
document_url
string
required

The URL of the document to be processed

Example:

"https://example.com/document.pdf"

​
document_name
string

Optional name for the document. If not provided, a default name will be generated.

Example:

"Important Document"

​
callback_url
string

Optional URL that will receive status updates about the document processing

Example:

"https://your-server.com/webhook"

​
properties
object

Optional key-value pairs for additional document properties

Example:
{ "department": "sales", "priority": "high" }
​
tags
string[]

Optional array of tags to categorize the document

Example:
["important", "meeting"]

Response

Document created successfully

​
uuid
string

Unique identifier for the created document

Example:

"d290f1ee-6c54-4b01-90e6-d701748f0851"

​
document_name
string

Name of the document

Example:

"Important Document"

​
document_url
string

URL of the document

Example:

"https://example.com/document.pdf"

​
status
string

Current status of the document processing

Example:

"processing"

​
created_at
string

ISO 8601 timestamp of when the document was created

Example:

"2024-01-01T12:00:00Z"

​
updated_at
string

ISO 8601 timestamp of when the document was last updated

Example:

"2024-01-01T12:00:00Z"

​
callback_url
string

URL that will receive status updates

Example:

"https://your-server.com/webhook"

​
tags
string[]

Array of document tags

Example:
["important", "meeting"]
​
properties
object

Additional document properties

Example:
{ "department": "sales", "priority": "high" }