Chroma

Chroma Records API

Embeddings (with documents, metadata, URIs) inside a collection.

Documentation GitHub OpenAPI

OpenAPI Specification

openapi: 3.0.3
info:
  title: Chroma Server API (v2) Collections Records API
  description: 'Chroma is an open-source, AI-native vector (embedding) database for LLM, RAG, and semantic-search applications. This OpenAPI describes Chroma''s HTTP/REST v2 API, which is the same interface used by the Python, JavaScript/TypeScript, Rust, and other client libraries. The API is organized around a multi-tenancy hierarchy: tenants contain databases, databases contain collections, and collections contain records (embeddings with documents, metadata, and URIs). The core write and read operations are add, upsert, update, get, query (nearest-neighbor similarity search), and delete.

    ENDPOINTS MODELED: Path structure and the query-collection contract are grounded in the official Chroma reference docs (docs.trychroma.com) and the chroma-core sources. The exact request/response JSON SCHEMAS in this document are MODELED by API Evangelist from the documented client behavior and may differ in field-level detail from Chroma''s own generated openapi.json served at `/openapi.json` on a running server. Treat schemas as representative, not authoritative; verify against your server''s `/openapi.json`.'
  version: '2.0'
  contact:
    name: Chroma
    url: https://www.trychroma.com
  license:
    name: Apache 2.0
    url: https://github.com/chroma-core/chroma/blob/main/LICENSE
servers:
- url: https://api.trychroma.com
  description: Chroma Cloud (managed, serverless)
- url: http://localhost:8000
  description: Local development / self-hosted Chroma server (default port 8000)
security:
- chromaToken: []
tags:
- name: Records
  description: Embeddings (with documents, metadata, URIs) inside a collection.
paths:
  /api/v2/tenants/{tenant}/databases/{database}/collections/{collection_id}/count:
    parameters:
    - $ref: '#/components/parameters/Tenant'
    - $ref: '#/components/parameters/Database'
    - $ref: '#/components/parameters/CollectionId'
    get:
      operationId: countRecords
      tags:
      - Records
      summary: Count records
      description: Returns the number of records (embeddings) in a collection.
      responses:
        '200':
          description: Record count.
          content:
            application/json:
              schema:
                type: integer
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v2/tenants/{tenant}/databases/{database}/collections/{collection_id}/add:
    parameters:
    - $ref: '#/components/parameters/Tenant'
    - $ref: '#/components/parameters/Database'
    - $ref: '#/components/parameters/CollectionId'
    post:
      operationId: addRecords
      tags:
      - Records
      summary: Add records
      description: Adds records to a collection. Each record has an id and, optionally, an embedding, document, metadata, and URI. If embeddings are omitted, the collection's embedding function generates them from documents.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddRecords'
      responses:
        '201':
          description: Records added.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v2/tenants/{tenant}/databases/{database}/collections/{collection_id}/upsert:
    parameters:
    - $ref: '#/components/parameters/Tenant'
    - $ref: '#/components/parameters/Database'
    - $ref: '#/components/parameters/CollectionId'
    post:
      operationId: upsertRecords
      tags:
      - Records
      summary: Upsert records
      description: Inserts new records or updates existing records matched by id.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddRecords'
      responses:
        '200':
          description: Records upserted.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v2/tenants/{tenant}/databases/{database}/collections/{collection_id}/update:
    parameters:
    - $ref: '#/components/parameters/Tenant'
    - $ref: '#/components/parameters/Database'
    - $ref: '#/components/parameters/CollectionId'
    post:
      operationId: updateRecords
      tags:
      - Records
      summary: Update records
      description: Updates the embeddings, documents, metadata, or URIs of existing records by id.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddRecords'
      responses:
        '200':
          description: Records updated.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v2/tenants/{tenant}/databases/{database}/collections/{collection_id}/get:
    parameters:
    - $ref: '#/components/parameters/Tenant'
    - $ref: '#/components/parameters/Database'
    - $ref: '#/components/parameters/CollectionId'
    post:
      operationId: getRecords
      tags:
      - Records
      summary: Get records
      description: Retrieves records by id and/or by metadata (`where`) and document (`where_document`) filters, returning the included fields.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetRecords'
      responses:
        '200':
          description: Matching records.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetResult'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v2/tenants/{tenant}/databases/{database}/collections/{collection_id}/delete:
    parameters:
    - $ref: '#/components/parameters/Tenant'
    - $ref: '#/components/parameters/Database'
    - $ref: '#/components/parameters/CollectionId'
    post:
      operationId: deleteRecords
      tags:
      - Records
      summary: Delete records
      description: Deletes records by id and/or by metadata and document filters.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteRecords'
      responses:
        '200':
          description: Records deleted.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  responses:
    Unauthorized:
      description: Missing or invalid API token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    CollectionId:
      name: collection_id
      in: path
      required: true
      description: The collection UUID.
      schema:
        type: string
    Database:
      name: database
      in: path
      required: true
      description: The database name.
      schema:
        type: string
    Tenant:
      name: tenant
      in: path
      required: true
      description: The tenant name or UUID.
      schema:
        type: string
  schemas:
    AddRecords:
      type: object
      required:
      - ids
      properties:
        ids:
          type: array
          items:
            type: string
        embeddings:
          type: array
          description: One embedding vector per id. Optional when documents are supplied and the collection has an embedding function.
          items:
            type: array
            items:
              type: number
              format: float
        documents:
          type: array
          items:
            type: string
            nullable: true
        metadatas:
          type: array
          items:
            type: object
            nullable: true
            additionalProperties: true
        uris:
          type: array
          items:
            type: string
            nullable: true
    GetResult:
      type: object
      properties:
        ids:
          type: array
          items:
            type: string
        documents:
          type: array
          items:
            type: string
            nullable: true
        metadatas:
          type: array
          items:
            type: object
            nullable: true
            additionalProperties: true
        embeddings:
          type: array
          items:
            type: array
            items:
              type: number
              format: float
        uris:
          type: array
          items:
            type: string
            nullable: true
    DeleteRecords:
      type: object
      properties:
        ids:
          type: array
          items:
            type: string
        where:
          type: object
          additionalProperties: true
        where_document:
          type: object
          additionalProperties: true
    GetRecords:
      type: object
      properties:
        ids:
          type: array
          items:
            type: string
        where:
          type: object
          description: Metadata filter clause.
          additionalProperties: true
        where_document:
          type: object
          description: Full-text / document filter clause.
          additionalProperties: true
        limit:
          type: integer
        offset:
          type: integer
        include:
          $ref: '#/components/schemas/Include'
    Include:
      type: array
      description: Which fields to return in results.
      items:
        type: string
        enum:
        - distances
        - documents
        - embeddings
        - metadatas
        - uris
    Error:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
  securitySchemes:
    chromaToken:
      type: apiKey
      in: header
      name: x-chroma-token
      description: Chroma Cloud API key passed in the `x-chroma-token` header. Self-hosted servers can be run open (no auth) or configured with static-token or basic authentication; Chroma Cloud always requires a token.

Where this information came from

This is an independent, third-party profile of Chroma Records API, published by API Evangelist. We do not operate, host, resell, or support these APIs, and we are not affiliated with or endorsed by the company unless stated above. Everything here is built from publicly available information — the company's own site, developer portal, documentation, public repositories, and the specifications it publishes for public use. Nothing is obtained by breaching a system, defeating an access control, or using credentials.

The Kin Score and Agent Readiness rating are independently calculated assessments of a company's public API artifacts, scored against a published rubric. They are not certifications, endorsements, security assessments, or audits.

Corrections, re-scores, and removal are free — no partnership or purchase required, and you do not need to justify the request. A removed company is recorded as unrated, never scored zero for having asked. Acknowledgement within one business day; removal within two.

info@apievangelist.com · Read the full data-sourcing policy →
On a security or compliance team? Put security in the subject line and you will get a person, not a form — we will tell you exactly which public URLs this profile was built from.

Chroma Records API

Documentation

Specifications

Other Resources

OpenAPI Specification