Skip to main content
POST
/
api
/
v1
/
add-file
Upload and index a file
curl --request POST \
  --url https://sync.trychroma.com/api/v1/add-file \
  --header 'Content-Type: multipart/form-data' \
  --header 'x-chroma-token: <api-key>' \
  --header 'x-upload-content-length: <x-upload-content-length>' \
  --form 'database_name=<string>' \
  --form 'collection_name=<string>' \
  --form file='@example-file' \
  --form 'custom_id=<string>' \
  --form 'metadata=<string>' \
  --form 'embedding=<string>' \
  --form 'chunking=<string>' \
  --form 'content_type=<string>'
{
  "invocation_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}

Authorizations

​
x-chroma-token
string
header
required

Headers

​
x-upload-content-length
integer<int64>
required

Declared file size in bytes. Must be greater than 0 and not exceed 200 MiB (209,715,200 bytes).

Required range: 1 <= x <= 209715200

Body

multipart/form-data
​
database_name
string
required

Database in which to index the file. Must appear before the file field.

​
collection_name
string
required

Target collection. Created on first use. Must appear before the file field.

​
file
file
required

File content. Maximum 200 MiB. The filename in the part header is used as the document name.

​
custom_id
string

Optional custom document ID. Chunk IDs become custom_id-{chunk} instead of sha256(filename)-{chunk}.

Maximum string length: 120
​
metadata
string

Optional JSON object of additional metadata to merge with chunk metadata. Maximum 16 KiB. Reserved keys (e.g. chroma_*) are rejected.

​
embedding
string

Optional JSON SourceEmbeddingConfig. Defaults to Qwen3-Embedding-0.6B with generic_retrieval task and Splade sparse embeddings.

​
chunking
string

Optional JSON SourceChunkingConfig. Defaults to tree-sitter syntax-aware chunking with markdown/line-based fallbacks.

​
content_type
string

Optional MIME type override. Otherwise inferred from the file part header (if not application/octet-stream) or the filename extension.

Maximum string length: 512

Response

File accepted and invocation created

​
invocation_id
string<uuid>
required

ID of the newly created invocation.