openapi: 3.1.0
info:
  title: Chroma Cloud Collections Databases 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: Databases
  description: Database management endpoints for creating, listing, retrieving, and deleting databases within a tenant.
paths:
  /api/v2/tenants/{tenantName}/databases:
    get:
      operationId: listDatabases
      summary: List databases
      description: Returns a list of all databases within the specified tenant.
      tags:
      - Databases
      parameters:
      - $ref: '#/components/parameters/tenantName'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/offset'
      responses:
        '200':
          description: List of databases
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Database'
    post:
      operationId: createDatabase
      summary: Create a database
      description: Creates a new database within the specified tenant.
      tags:
      - Databases
      parameters:
      - $ref: '#/components/parameters/tenantName'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDatabaseRequest'
      responses:
        '200':
          description: Database created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Database'
        '409':
          description: Database already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v2/tenants/{tenantName}/databases/{databaseName}:
    get:
      operationId: getDatabase
      summary: Get a database
      description: Returns an existing database by name within the specified tenant.
      tags:
      - Databases
      parameters:
      - $ref: '#/components/parameters/tenantName'
      - $ref: '#/components/parameters/databaseName'
      responses:
        '200':
          description: Database details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Database'
        '404':
          description: Database or tenant not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      operationId: deleteDatabase
      summary: Delete a database
      description: Deletes an existing database and all its collections.
      tags:
      - Databases
      parameters:
      - $ref: '#/components/parameters/tenantName'
      - $ref: '#/components/parameters/databaseName'
      responses:
        '200':
          description: Database deleted successfully
        '404':
          description: Database or tenant 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
    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:
    CreateDatabaseRequest:
      type: object
      properties:
        name:
          type: string
          description: The name for the new database
      required:
      - name
    Error:
      type: object
      properties:
        error:
          type: string
          description: Error message describing what went wrong
        message:
          type: string
          description: Detailed error message
      required:
      - error
    Database:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the database
        name:
          type: string
          description: The name of the database
        tenant:
          type: string
          description: The tenant this database belongs to
      required:
      - id
      - name
      - tenant
  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