> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trychroma.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Upload and index a file

> Uploads a file and creates an invocation to index it into the specified collection.

The first time this endpoint is called for a database, a `file_upload` source is created automatically; subsequent calls reuse that source. The collection is created on the first invocation if it does not already exist.

**Multipart field ordering:** `database_name` and `collection_name` MUST appear before `file`. The server uses these to authorize the request before streaming file bytes to storage.

**Size limits:** maximum 200 MiB per file. The declared size in `x-upload-content-length` is enforced.



## OpenAPI

````yaml /sync.openapi.json post /api/v1/add-file
openapi: 3.1.0
info:
  title: Chroma Sync Service
  description: >-
    Chroma Sync Service provides APIs for managing data synchronization sources
    and invocations. The service supports syncing content from GitHub
    repositories, web scrape targets, and S3 buckets to Chroma collections.
  license:
    name: ''
  version: 0.1.0
servers:
  - url: https://sync.trychroma.com
security: []
paths:
  /api/v1/add-file:
    post:
      tags:
        - File Upload
      summary: Upload and index a file
      description: >-
        Uploads a file and creates an invocation to index it into the specified
        collection.


        The first time this endpoint is called for a database, a `file_upload`
        source is created automatically; subsequent calls reuse that source. The
        collection is created on the first invocation if it does not already
        exist.


        **Multipart field ordering:** `database_name` and `collection_name` MUST
        appear before `file`. The server uses these to authorize the request
        before streaming file bytes to storage.


        **Size limits:** maximum 200 MiB per file. The declared size in
        `x-upload-content-length` is enforced.
      operationId: add_file
      parameters:
        - name: x-upload-content-length
          in: header
          description: >-
            Declared file size in bytes. Must be greater than 0 and not exceed
            200 MiB (209,715,200 bytes).
          required: true
          schema:
            type: integer
            format: int64
            minimum: 1
            maximum: 209715200
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - database_name
                - collection_name
                - file
              properties:
                database_name:
                  type: string
                  description: >-
                    Database in which to index the file. Must appear before the
                    `file` field.
                collection_name:
                  type: string
                  description: >-
                    Target collection. Created on first use. Must appear before
                    the `file` field.
                file:
                  type: string
                  format: binary
                  description: >-
                    File content. Maximum 200 MiB. The filename in the part
                    header is used as the document name.
                custom_id:
                  type: string
                  maxLength: 120
                  description: >-
                    Optional custom document ID. Chunk IDs become
                    `custom_id-{chunk}` instead of `sha256(filename)-{chunk}`.
                metadata:
                  type: string
                  description: >-
                    Optional JSON object of additional metadata to merge with
                    chunk metadata. Maximum 16 KiB. Reserved keys (e.g.
                    `chroma_*`) are rejected.
                embedding:
                  type: string
                  description: >-
                    Optional JSON `SourceEmbeddingConfig`. Defaults to
                    Qwen3-Embedding-0.6B with `generic_retrieval` task and
                    Splade sparse embeddings.
                chunking:
                  type: string
                  description: >-
                    Optional JSON `SourceChunkingConfig`. Defaults to
                    tree-sitter syntax-aware chunking with markdown/line-based
                    fallbacks.
                content_type:
                  type: string
                  maxLength: 512
                  description: >-
                    Optional MIME type override. Otherwise inferred from the
                    file part header (if not `application/octet-stream`) or the
                    filename extension.
            encoding:
              file:
                contentType: application/octet-stream
      responses:
        '201':
          description: File accepted and invocation created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddFileResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Database not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too many concurrent uploads
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - x-chroma-token: []
components:
  schemas:
    AddFileResponse:
      type: object
      required:
        - invocation_id
      properties:
        invocation_id:
          type: string
          format: uuid
          description: ID of the newly created invocation.
    ErrorResponse:
      type: object
      required:
        - error
        - message
      properties:
        error:
          type: string
        message:
          type: string
  securitySchemes:
    x-chroma-token:
      type: apiKey
      in: header
      name: x-chroma-token

````