Skip to main content
Version: 2.0

Upload a file to the corpus

POST 
/v2/corpora/:corpus_key/upload_file

Uploads a file to a corpus for automatic text extraction, chunking, and indexing. Use this endpoint for unstructured documents when you want the platform to parse the file for you. Each uploaded file can be up to 10 MB.

Supported file types include:

  • Markdown (.md)
  • PDF/A (.pdf)
  • OpenOffice documents (.odt)
  • Microsoft Word (.doc, .docx)
  • Microsoft PowerPoint (.ppt, .pptx)
  • Plain text (.txt)
  • HTML (.html)
  • LXML (.lxml)
  • RTF (.rtf)
  • EPUB (.epub)
  • Email files (RFC 822)
note

For semi-structured documents that require more control over fields or metadata, use the Create Corpus Document API instead.

Additional format support through Vectara Ingest​

If you need to ingest additional file types or data sources, you can use the open-source Vectara Ingest Python framework. It supports connectors for websites, RSS feeds, CSV, Confluence, HubSpot, ServiceNow, Jira, Notion, Slack, MediaWiki, GitHub, SharePoint, Twitter/X, YouTube, and more.

caution

Vectara Ingest is provided as an open-source example and is not officially supported.

Multipart form fields​

This endpoint expects a multipart/form-data request with the following fields:

  • metadata (optional): JSON metadata to attach to the parsed document.
    Example: metadata={"key":"value"}
  • chunking_strategy (optional): Controls how extracted text is chunked.
    Defaults to sentence-based chunking (one chunk per sentence).
    Example: {"type":"sentence_chunking_strategy"}. Example for max character chunking: {"type":"max_chars_chunking_strategy","max_chars_per_chunk":512}
  • table_extraction_config (optional): Enables extraction of tables from supported file types such as PDFs.
    Example: {"extract_tables": true}
  • file (required): The file to upload.
  • filename (required): The desired document ID, specified within the file upload field.

Authenticate the request with the x-api-key header or an OAuth bearer token:

\$ curl -L -X POST 'https://api.vectara.io/v2/corpora/:corpus_key/upload_file' \
-H 'Content-Type: multipart/form-data' \
-H 'Accept: application/json' \
-H 'x-api-key: zwt_123456' \
-F 'metadata=\{"key": "value"\};type=application/json' \
-F 'file=@/path/to/file/file.pdf;filename=desired_filename.pdf'

Filenames with non-ASCII characters​

URL encode filenames that contain non-ASCII (non-English) characters, such as Russian or Chinese. The REST API follows web standards, which require URL-encoded file names.

Set the document ID​

To set a custom Document ID, pass it as the filename in the Content-Disposition header:

Content-Disposition: form-data; name="file"; filename="your_document_id"

For more information about Content-Disposition, see the Mozilla documentation on headers.

Attach additional metadata​

To attach additional metadata to the file, specify a metadata form field that contains a JSON string:

{ "filesize": 1234 }

Tabular data extraction and summarization​

Set table_extraction_config.extract_tables = true to extract tabular data, such as financial filings (10-K, 10-Q, S-1). You can also apply custom prompt templates to summarize table content during upload.

caution

Table extraction does not support scanned images of tables.

Custom table summarization with prompt templates​

The platform supports table summarization using custom prompt templates during document upload. Custom prompt templates control how the LLM interprets and summarizes table data during extraction. Customize the prompt_template to tailor summaries for domain-specific language, analytical perspectives, or formatting preferences.

Image support​

To include images in structured documents, use the Indexing API with Base64 encoding. You cannot send images directly with individual query requests. To retrieve a specific image that is embedded within a document, use the Retrieve image API

Request​

Responses​

The platform parsed the file and added the extracted document to the corpus.

Last updated on by Ayesha Saddiqua