Skip to main content
The file upload API lets you upload a single file directly to sync. You send a POST to https://sync.trychroma.com/api/v1/add-file with the file and a target collection; Chroma chunks, embeds, and indexes it just like any other Sync source. File uploads can name a target collection, which sync will get or create.

​
Walkthrough

​
Uploading via the Dashboard

There are two ways to upload files from the dashboard:
  • From the Add data page. Open a database, choose Add data, and select File upload. Drop or pick one or more files; Chroma chunks and embeds them into a collection named file_upload (created on the first upload).
  • From a collection page. On a collection page, if the Schema is compatible with sync — an “Upload files” button will be visible. Select this button to upload files into that collection.
Both flows accept the same file types: PDFs, Office documents, spreadsheets, presentations, HTML, ebooks, images, and any UTF-8 text or markdown file. The 200 MB-per-file limit is enforced in the browser before the upload starts.

​
Uploading via the API

The endpoint is multipart POST /api/v1/add-file. Two rules to be aware of:
  • The header x-upload-content-length (file size in bytes) is required.
  • database_name and collection_name must appear before the file part.
curl -X POST https://sync.trychroma.com/api/v1/add-file \
  -H "x-chroma-token: $CHROMA_API_KEY" \
  -H "x-upload-content-length: $(stat -f%z report.pdf)" \
  -F "database_name=my-db" \
  -F "collection_name=my-collection" \
  -F "custom_id=report-2024-q4" \
  -F 'metadata={"author":"Jane Doe","year":2024}' \
  -F "file=@report.pdf"
A successful request returns 201 Created with the invocation ID: 
{
  "invocation_id": "9c8c1d1e-..."
}
You can then poll GET /api/v1/invocations/{invocation_id} to track progress.

​
Multipart Fields

FieldRequiredDescription
database_nameYesDatabase in which to index the file. Must come before file.
collection_nameYesTarget collection. Created on first use, otherwise appended to. Must come before file.
fileYesFile content. Maximum 200 MiB. The filename in the part header is used as the document name.
custom_idNoCustom document ID (max 120 bytes). Chunk IDs become custom_id-{chunk} instead of sha256(filename)-{chunk}.
metadataNoJSON object of additional metadata merged with chunk metadata. Maximum 16 KiB. Keys reserved by Chroma (e.g. chroma_*) are rejected.
embeddingNoJSON SourceEmbeddingConfig. Defaults to Qwen3-Embedding-0.6B with generic_retrieval task plus Splade sparse embeddings.
chunkingNoJSON SourceChunkingConfig. Defaults to tree-sitter syntax-aware chunking with markdown/line-based fallbacks.
content_typeNoMIME type override. Otherwise inferred from the file part header (if not application/octet-stream) or the filename extension.

​
Limits

  • Maximum file size: 200 MiB per file (enforced via x-upload-content-length).
  • Concurrency: Each team has a per-tenant cap on simultaneous in-flight uploads. Excess requests return 429 Too Many Requests.
  • Database region: Only available for Chroma databases hosted in aws-us-east-1. See Regions.
Supported file types and the chunking pipeline are the same as S3 Sync — see Supported File Types and Chunking.