Sign in

v1

latestOpenAPI 3.0.32026-07-267015229.9 KB
Documents

Create Document

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

post/v2/documents

Request body

document_urlstring required

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.

<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_namestring

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

callback_urlstring

Optional URL that receives status updates while the document processes asynchronously (e.g. started, processing, ready, error).

tagsstring[]

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.

Example request

{
  "document_url": "https://docs.example.com/",
  "document_name": "Example Docs",
  "callback_url": "https://your-server.com/webhook",
  "tags": [
    "docs",
    "website"
  ],
  "crawl": {
    "depth": 2,
    "max_pages": 10
  }
}

Response

Document created successfully

document_idstring

Unique identifier for the created document

document_namestring

Name of the document

document_urlstring

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.

progressinteger nullable

Processing progress as a percentage (0-100). Null when processing has not started or is complete.

error_messagestring 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_atstring

ISO 8601 timestamp of when the document was created

updated_atstring

ISO 8601 timestamp of when the document was last updated

callback_urlstring

URL that will receive status updates

tagsstring[]

Array of document tags

crawled_urlsstring[] nullable

List of URLs that were crawled (only present for crawled websites after processing completes)

last_crawled_atstring nullable

ISO 8601 timestamp of when the document was last crawled

crawl_countinteger nullable

Number of times the document has been crawled

Example response

{
  "document_id": "d8-5c71baca86fc",
  "document_name": "Example Docs",
  "document_url": "https://docs.example.com/",
  "status": "started",
  "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
}