Create source ↗

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/sources:
    post:
      tags:
        - Source
      summary: Create source
      description: Creates a new sync source.
      operationId: create_source
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSourcePayload'
        required: true
      responses:
        '201':
          description: Source creation successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateSourceResponse'
        '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: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Source exists
          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:
    CreateSourcePayload:
      allOf:
        - $ref: '#/components/schemas/SourceType'
        - type: object
          required:
            - database_name
          properties:
            chunking:
              $ref: '#/components/schemas/SourceChunkingConfig'
              description: Optional chunking configuration for this source.
            database_name:
              type: string
            embedding:
              $ref: '#/components/schemas/SourceEmbeddingConfig'
            embedding_model:
              oneOf:
                - type: 'null'
                - $ref: '#/components/schemas/DenseEmbeddingModel'
    CreateSourceResponse:
      type: object
      required:
        - source_id
      properties:
        source_id:
          $ref: '#/components/schemas/SourceId'
          description: Source ID
    ErrorResponse:
      type: object
      required:
        - error
        - message
      properties:
        error:
          type: string
        message:
          type: string
    SourceType:
      oneOf:
        - type: object
          required:
            - github
          properties:
            github:
              type: object
              required:
                - repository
              properties:
                app_id:
                  type:
                    - string
                    - 'null'
                include_globs:
                  type:
                    - array
                    - 'null'
                  items:
                    type: string
                  uniqueItems: true
                repository:
                  type: string
        - type: object
          required:
            - web_scrape
          properties:
            web_scrape:
              type: object
              required:
                - starting_url
              properties:
                exclude_path_regexes:
                  type:
                    - array
                    - 'null'
                  items:
                    type: string
                  uniqueItems: true
                include_path_regexes:
                  type:
                    - array
                    - 'null'
                  items:
                    type: string
                  uniqueItems: true
                max_depth:
                  type:
                    - integer
                    - 'null'
                  format: int32
                  minimum: 0
                page_limit:
                  type:
                    - integer
                    - 'null'
                  format: int32
                  minimum: 0
                starting_url:
                  type: string
        - type: object
          required:
            - s3
          properties:
            s3:
              type: object
              required:
                - bucket_name
                - region
                - collection_name
                - aws_credential_id
              properties:
                aws_credential_id:
                  type: integer
                  format: int32
                  description: |-
                    AWS credential ID for accessing the bucket.
                    Credentials must be created in Dashboard API first.
                bucket_name:
                  type: string
                collection_name:
                  type: string
                path_prefix:
                  type:
                    - string
                    - 'null'
                region:
                  type: string
                trigger_mode:
                  oneOf:
                    - type: 'null'
                    - $ref: '#/components/schemas/S3TriggerMode'
                      description: |-
                        Trigger mode for S3 source (default: none)
                        Only 'none' is supported initially
    SourceChunkingConfig:
      oneOf:
        - type: object
          required:
            - type
          properties:
            max_size_bytes:
              type: integer
              minimum: 0
            type:
              type: string
              enum:
                - tree_sitter
        - type: object
          required:
            - type
          properties:
            max_lines:
              type: integer
              minimum: 0
            max_size_bytes:
              type: integer
              minimum: 0
            type:
              type: string
              enum:
                - lines
    SourceEmbeddingConfig:
      type: object
      properties:
        dense:
          $ref: '#/components/schemas/DenseEmbeddingConfig'
        sparse:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/SparseEmbeddingConfig'
    DenseEmbeddingModel:
      oneOf:
        - type: object
          required:
            - model
          properties:
            model:
              type: string
              enum:
                - Qwen/Qwen3-Embedding-0.6B
            task:
              oneOf:
                - type: 'null'
                - $ref: '#/components/schemas/Qwen3EmbeddingTask'
    SourceId:
      type: string
      format: uuid
    S3TriggerMode:
      type: string
      description: >-
        Trigger mode for S3 sources

        - `none`: Manual invocations only (default, only supported mode
        initially)

        - `direct`: Triggered by S3 events (future)

        - `metadata`: Triggered by S3 events with custom metadata support
        (future)
      enum:
        - none
        - direct
        - metadata
    DenseEmbeddingConfig:
      allOf:
        - $ref: '#/components/schemas/DenseEmbeddingModel'
    SparseEmbeddingConfig:
      type: object
      properties:
        key:
          type: string
        model:
          $ref: '#/components/schemas/SparseEmbeddingModel'
    Qwen3EmbeddingTask:
      type: object
      required:
        - task_name
      properties:
        document_prompt:
          type:
            - string
            - 'null'
        query_prompt:
          type:
            - string
            - 'null'
        task_name:
          type: string
    SparseEmbeddingModel:
      type: string
      enum:
        - Chroma/BM25
        - prithivida/Splade_PP_en_v1
  securitySchemes:
    x-chroma-token:
      type: apiKey
      in: header
      name: x-chroma-token