openapi: 3.1.0
info:
  title: Chroma Cloud Collections API
  description: Chroma Cloud is a managed, serverless vector database service that provides fast and scalable vector, full-text, and metadata search across terabytes of data. It is backed by Chroma's Apache 2.0 distributed database and offers usage-based pricing with starter and team plans. The Cloud API extends the Chroma Server API with additional search capabilities including hybrid search with reciprocal rank fusion, custom ranking expressions, and batch search operations.
  version: 2.0.0
  contact:
    name: Chroma Support
    url: https://docs.trychroma.com
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  termsOfService: https://www.trychroma.com/terms
servers:
- url: https://api.trychroma.com
  description: Chroma Cloud Production
security:
- bearerAuth: []
tags:
- name: Collections
  description: Collection management endpoints for creating, listing, retrieving, updating, and deleting collections within a database.
paths:
  /api/v2/tenants/{tenantName}/databases/{databaseName}/collections:
    get:
      operationId: listCollections
      summary: List collections
      description: Returns a list of all collections within the specified database and tenant.
      tags:
      - Collections
      parameters:
      - $ref: '#/components/parameters/tenantName'
      - $ref: '#/components/parameters/databaseName'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/offset'
      responses:
        '200':
          description: List of collections
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Collection'
    post:
      operationId: createCollection
      summary: Create a collection
      description: Creates a new collection within the specified database and tenant.
      tags:
      - Collections
      parameters:
      - $ref: '#/components/parameters/tenantName'
      - $ref: '#/components/parameters/databaseName'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCollectionRequest'
      responses:
        '200':
          description: Collection created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Collection'
        '409':
          description: Collection already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v2/tenants/{tenantName}/databases/{databaseName}/collections/{collectionId}:
    get:
      operationId: getCollection
      summary: Get a collection
      description: Returns an existing collection by its unique identifier.
      tags:
      - Collections
      parameters:
      - $ref: '#/components/parameters/tenantName'
      - $ref: '#/components/parameters/databaseName'
      - $ref: '#/components/parameters/collectionId'
      responses:
        '200':
          description: Collection details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Collection'
        '404':
          description: Collection not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      operationId: updateCollection
      summary: Update a collection
      description: Updates an existing collection's name or metadata.
      tags:
      - Collections
      parameters:
      - $ref: '#/components/parameters/tenantName'
      - $ref: '#/components/parameters/databaseName'
      - $ref: '#/components/parameters/collectionId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCollectionRequest'
      responses:
        '200':
          description: Collection updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Collection'
        '404':
          description: Collection not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      operationId: deleteCollection
      summary: Delete a collection
      description: Deletes an existing collection and all its records.
      tags:
      - Collections
      parameters:
      - $ref: '#/components/parameters/tenantName'
      - $ref: '#/components/parameters/databaseName'
      - $ref: '#/components/parameters/collectionId'
      responses:
        '200':
          description: Collection deleted successfully
        '404':
          description: Collection not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  parameters:
    offset:
      name: offset
      in: query
      required: false
      description: Number of items to skip before returning results
      schema:
        type: integer
        minimum: 0
    tenantName:
      name: tenantName
      in: path
      required: true
      description: The name of the tenant
      schema:
        type: string
    collectionId:
      name: collectionId
      in: path
      required: true
      description: The unique identifier of the collection
      schema:
        type: string
        format: uuid
    databaseName:
      name: databaseName
      in: path
      required: true
      description: The name of the database
      schema:
        type: string
    limit:
      name: limit
      in: query
      required: false
      description: Maximum number of items to return
      schema:
        type: integer
        minimum: 1
  schemas:
    Collection:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the collection
        name:
          type: string
          description: The name of the collection
        metadata:
          type: object
          nullable: true
          additionalProperties: true
          description: Arbitrary metadata associated with the collection
        tenant:
          type: string
          description: The tenant this collection belongs to
        database:
          type: string
          description: The database this collection belongs to
      required:
      - id
      - name
    Error:
      type: object
      properties:
        error:
          type: string
          description: Error message describing what went wrong
        message:
          type: string
          description: Detailed error message
      required:
      - error
    CreateCollectionRequest:
      type: object
      properties:
        name:
          type: string
          description: The name for the new collection
        metadata:
          type: object
          nullable: true
          additionalProperties: true
          description: Optional metadata to associate with the collection
        get_or_create:
          type: boolean
          default: false
          description: If true, return the existing collection if one with the same name already exists
      required:
      - name
    UpdateCollectionRequest:
      type: object
      properties:
        new_name:
          type: string
          description: The new name for the collection
        new_metadata:
          type: object
          nullable: true
          additionalProperties: true
          description: New metadata to replace the existing collection metadata
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer token authentication for Chroma Cloud. Obtain tokens from the Chroma Cloud dashboard.
externalDocs:
  description: Chroma Cloud Documentation
  url: https://docs.trychroma.com/cloud/sync/overview