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

# Update a branch index schema

> Update the index schema of one branch. The change applies to this branch only; updating main also updates the collection's indexConfigs, which mirror main. The same additive rule as the collection route applies within the branch: indexConfigs must preserve the branch's complete existing schema (the server-managed id field may be included as returned or omitted), new fields may be added at any object depth, and a field description may be set, replaced, or cleared without reindexing. Concurrent additive updates of the same branch are merged. Only a branch can be updated: naming a tag or an alias returns 400 BadRequest. Promoting a branch's schema to main is a manual step: apply the same additive change to main.



## OpenAPI

````yaml patch /collections/{collectionName}/branches/{branchName}
openapi: 3.1.1
info:
  title: LambdaDB API
  summary: LambdaDB Open API Spec
  version: 1.3.0
servers:
  - url: https://{projectHost}
    description: LambdaDB API endpoints
    variables:
      projectHost:
        description: The project-scoped URL of the API
        default: api.lambdadb.ai/projects/example-project
security: []
tags:
  - name: collections
    description: Create, describe, configure, list, and delete collections.
  - name: versioning
    description: Manage branches, tags, and aliases within a collection.
  - name: collections.docs
    description: Write, fetch, list, and bulk upload documents.
paths:
  /collections/{collectionName}/branches/{branchName}:
    patch:
      tags:
        - versioning
      summary: Update a Branch's Index Schema
      description: >-
        Update the index schema of one branch. The change applies to this branch
        only; updating main also updates the collection's indexConfigs, which
        mirror main. The same additive rule as the collection route applies
        within the branch: indexConfigs must preserve the branch's complete
        existing schema (the server-managed id field may be included as returned
        or omitted), new fields may be added at any object depth, and a field
        description may be set, replaced, or cleared without reindexing.
        Concurrent additive updates of the same branch are merged. Only a branch
        can be updated: naming a tag or an alias returns 400 BadRequest.
        Promoting a branch's schema to main is a manual step: apply the same
        additive change to main.
      operationId: updateBranch
      parameters:
        - $ref: '#/components/parameters/CollectionName'
        - $ref: '#/components/parameters/BranchName'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              description: >-
                A branch owns its indexConfigs only. Description, tags and
                snapshot retention stay on the collection route.
              properties:
                indexConfigs:
                  $ref: '#/components/schemas/IndexConfigs'
                  minProperties: 1
              required:
                - indexConfigs
            examples:
              example:
                value:
                  indexConfigs:
                    title:
                      type: text
                      analyzers:
                        - english
                      description: Book title as printed on the cover
                    category:
                      type: keyword
                    author:
                      type: keyword
      responses:
        '200':
          description: Updated branch with its index schema.
          content:
            application/json:
              schema:
                type: object
                properties:
                  branch:
                    $ref: '#/components/schemas/BranchDetails'
                required:
                  - branch
              examples:
                example:
                  value:
                    branch:
                      name: candidate
                      parentBranch:
                        branchId: main-branch-id
                        name: main
                      createdAt: 1788336000000
                      headSnapshot:
                        snapshotId: snapshot-id
                        snapshotCommittedAt: 1788335940000
                      parentSnapshot:
                        snapshotId: snapshot-id
                        snapshotCommittedAt: 1788335940000
                      numDocs: 1000
                      dataUpdatedAt: 1788335940000
                      indexConfigs:
                        title:
                          type: text
                          analyzers:
                            - english
                          description: Book title as printed on the cover
                        category:
                          type: keyword
                        id:
                          type: keyword
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequest'
              examples:
                example:
                  summary: Example response for bad request
                  value:
                    message: Invalid request
        '401':
          description: Unauthenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthenticated'
              examples:
                example:
                  summary: Example response for authentication failure
                  value:
                    message: Authentication failed
        '404':
          $ref: '#/components/responses/ResourceNotFound'
        '409':
          $ref: '#/components/responses/CatalogConflict'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TooManyRequests'
              examples:
                example:
                  summary: Example response for too many requests
                  value:
                    message: Too many requests
          headers:
            Retry-After:
              description: >-
                Optional retry delay in seconds. Not present on every 429
                response.
              schema:
                type: string
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerError'
              examples:
                example:
                  summary: Example response for internal server error
                  value:
                    message: Internal server error
        '502':
          $ref: '#/components/responses/BadGateway'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
      security:
        - ProjectApiKey: []
components:
  parameters:
    CollectionName:
      in: path
      name: collectionName
      description: Collection name.
      required: true
      schema:
        type: string
    BranchName:
      in: path
      name: branchName
      required: true
      schema:
        type: string
        minLength: 3
        maxLength: 52
        pattern: ^[a-zA-Z0-9_-]{3,52}$
  schemas:
    IndexConfigs:
      title: IndexConfigs
      type: object
      additionalProperties:
        type: object
        oneOf:
          - properties:
              type:
                type: string
                enum:
                  - text
              analyzers:
                type: array
                uniqueItems: true
                description: >-
                  Fixed analyzer presets for text fields; custom pipelines and
                  analyzer options are not supported. The keyword analyzer does
                  not change a text field into a keyword field. All 49 preset
                  names are supported. See the Choose text analyzers guide for
                  compatible SDK and tool versions. Use the lowercase names
                  listed below. Duplicate names, including case variants, are
                  rejected with HTTP 400. Defaults to ["standard"] when omitted.
                  Each selected analyzer indexes the field separately; language
                  detection is not automatic. An empty array does not use the
                  default. See the Choose text analyzers guide for language
                  selection, configuration examples, and the tradeoffs of
                  combining analyzers.
                items:
                  type: string
                  enum:
                    - standard
                    - english
                    - korean
                    - japanese
                    - chinese
                    - cjk
                    - arabic
                    - french
                    - german
                    - hindi
                    - indonesian
                    - italian
                    - portuguese
                    - russian
                    - spanish
                    - turkish
                    - armenian
                    - basque
                    - bengali
                    - brazilian
                    - bulgarian
                    - catalan
                    - czech
                    - danish
                    - dutch
                    - estonian
                    - finnish
                    - galician
                    - greek
                    - hungarian
                    - irish
                    - latvian
                    - lithuanian
                    - norwegian
                    - persian
                    - romanian
                    - serbian
                    - sorani
                    - swedish
                    - thai
                    - simple
                    - whitespace
                    - stop
                    - keyword
                    - pattern
                    - fingerprint
                    - nepali
                    - tamil
                    - telugu
                default:
                  - standard
              description:
                $ref: '#/components/schemas/FieldDescription'
            additionalProperties: false
            required:
              - type
          - properties:
              type:
                type: string
                enum:
                  - vector
              managedEmbedding:
                type: boolean
                description: >-
                  Set to false or omit for vector fields with caller-provided
                  values.
                enum:
                  - false
              dimensions:
                type: integer
                description: >-
                  Vector dimensions for vector fields with caller-provided
                  values.
                minimum: 64
                maximum: 4096
              similarity:
                type: string
                description: >-
                  Vector similarity metric for vector fields with
                  caller-provided values.
                enum:
                  - cosine
                  - euclidean
                default: cosine
              description:
                $ref: '#/components/schemas/FieldDescription'
            additionalProperties: false
            required:
              - type
              - dimensions
          - properties:
              type:
                type: string
                enum:
                  - vector
              managedEmbedding:
                type: boolean
                description: >-
                  An embedding block enables native embeddings when this flag is
                  omitted; explicit false is invalid. Normalized collection
                  responses retain true.
                enum:
                  - true
              embedding:
                $ref: '#/components/schemas/EmbeddingConfig'
              description:
                $ref: '#/components/schemas/FieldDescription'
            additionalProperties: false
            required:
              - type
              - embedding
          - properties:
              type:
                type: string
                enum:
                  - keyword
                  - long
                  - double
                  - datetime
                  - boolean
                  - sparseVector
              description:
                $ref: '#/components/schemas/FieldDescription'
            description: Types that do not need additional parameters.
            additionalProperties: false
            required:
              - type
          - properties:
              type:
                type: string
                enum:
                  - object
              objectIndexConfigs:
                type: object
                additionalProperties: true
              description:
                $ref: '#/components/schemas/FieldDescription'
            additionalProperties: false
            required:
              - type
              - objectIndexConfigs
      minProperties: 1
      description: >-
        Nonempty full schema. Collection updates preserve all existing fields
        and their settings while allowing new top-level fields and nested
        children at any depth. Removing or changing an existing field is
        rejected; only the optional description of a field may change.
        Collection responses include the server-managed top-level id field as
        {"type":"keyword"}. Requests may omit it or send exactly that
        configuration, so returned indexConfigs can be sent back unchanged; any
        other id configuration, id inside an object field, or other reserved
        internal field name is rejected.
    BranchDetails:
      title: BranchDetails
      type: object
      properties:
        name:
          type: string
        parentBranch:
          description: >-
            Fixed identity and name of the direct source branch, even when its
            selected snapshot originated on an ancestor or its head was empty.
            Explicitly null for main, branches created from tags, or when no
            parent was recorded. Historical metadata only: it does not prevent
            parent deletion, and recreating the parent's name does not change
            this identity.
          anyOf:
            - $ref: '#/components/schemas/ParentBranchDetails'
            - type: 'null'
        headSnapshot:
          description: Current committed head. Explicitly null for an empty branch.
          anyOf:
            - $ref: '#/components/schemas/SnapshotDetails'
            - type: 'null'
        parentSnapshot:
          description: >-
            Fixed snapshot from which the branch was created, not the previous
            head. Explicitly null for main and branches created from an empty
            source, even after their head advances. This metadata does not
            extend snapshot retention.
          anyOf:
            - $ref: '#/components/schemas/SnapshotDetails'
            - type: 'null'
        createdAt:
          type: integer
          format: int64
          description: Branch creation time as Unix epoch milliseconds.
        indexConfigs:
          $ref: '#/components/schemas/IndexConfigs'
          description: The branch's index schema.
        numDocs:
          type: integer
          description: >-
            Document count in this branch's committed head; 0 for an empty
            branch.
        dataUpdatedAt:
          description: >-
            Last data update of this branch's committed head as Unix epoch
            milliseconds. Explicitly null for an empty branch.
          anyOf:
            - type: integer
              format: int64
            - type: 'null'
      required:
        - name
        - parentBranch
        - headSnapshot
        - parentSnapshot
        - numDocs
        - dataUpdatedAt
        - indexConfigs
        - createdAt
    BadRequest:
      title: BadRequest
      type: object
      properties:
        message:
          type: string
    Unauthenticated:
      title: Unauthenticated
      type: object
      properties:
        message:
          type: string
    TooManyRequests:
      title: TooManyRequests
      type: object
      properties:
        message:
          type: string
    InternalServerError:
      title: InternalServerError
      type: object
      properties:
        message:
          type: string
    FieldDescription:
      title: FieldDescription
      type:
        - string
        - 'null'
      maxLength: 255
      description: >-
        Optional free-form explanation of what the field holds, returned in
        collection reads so agents and SDK users can discover field meanings. It
        never affects indexing and can be added, changed, or cleared on an
        existing field without reindexing. On PATCH, omitting it or sending null
        keeps the stored description, an empty string clears it, and any other
        value replaces it. Not accepted on the server-managed id field.
    EmbeddingConfig:
      title: EmbeddingConfig
      type: object
      description: Native embedding configuration for vector fields.
      properties:
        provider:
          type: string
          description: Embedding provider.
          enum:
            - openai
            - cohere
        model:
          type: string
          description: >-
            Embedding model name. See /guides/collections/native-embeddings for
            the current supported providers and models.
        sourceField:
          type:
            - string
            - 'null'
          description: >-
            Legacy single-text source path in the original JSON. Use exactly one
            non-null sourceField or sources. Missing text is skipped; invalid
            values fail when inference is needed. An explicitly supplied vector
            takes precedence over inference.
          minLength: 1
          pattern: .*\S.*
        dimensions:
          type: integer
          description: >-
            Optional model dimensions, resolved in stored metadata. OpenAI
            limits depend on the model. Cohere accepts 256, 512, 768, 1024, 1536
            or 2048 and defaults to 2048.
          minimum: 64
          maximum: 4096
        similarity:
          type: string
          description: >-
            Resolved vector similarity metric. Optional in requests and resolved
            in stored collection metadata.
          enum:
            - cosine
            - euclidean
          default: cosine
        sources:
          type:
            - array
            - 'null'
          minItems: 1
          maxItems: 16
          items:
            $ref: '#/components/schemas/EmbeddingSource'
          description: >-
            Ordered source mappings; field paths must be unique. Text sources
            are scalar strings. Cohere image sources are strings or flat string
            arrays, expanded in place to create one combined vector. Missing
            sources and empty image arrays are skipped. At most 16 effective
            parts, 8 images and 1 MiB decoded image bytes per input; each image
            is limited to 4,194,304 pixels. Images must be supported data URIs
            or public HTTPS URLs. URL, field-path, duplicate-path, format and
            byte/pixel validation remain server checks. OpenAI requires exactly
            one text source.
      required:
        - provider
        - model
      additionalProperties: false
      oneOf:
        - required:
            - sourceField
          properties:
            sourceField:
              type: string
            sources:
              type: 'null'
        - required:
            - sources
          properties:
            sources:
              type: array
            sourceField:
              type: 'null'
      allOf:
        - if:
            properties:
              provider:
                const: cohere
          then:
            properties:
              model:
                enum:
                  - embed-v5.0-pro
                  - embed-v5.0-fast
              dimensions:
                enum:
                  - 256
                  - 512
                  - 768
                  - 1024
                  - 1536
                  - 2048
        - if:
            properties:
              provider:
                const: openai
          then:
            properties:
              model:
                enum:
                  - text-embedding-3-small
                  - text-embedding-3-large
                  - text-embedding-ada-002
              sources:
                maxItems: 1
                items:
                  properties:
                    type:
                      const: text
    ParentBranchDetails:
      title: ParentBranchDetails
      type: object
      properties:
        branchId:
          type: string
          description: Identity of the direct source branch at creation time.
        name:
          type: string
          description: Name of the direct source branch at creation time.
      required:
        - branchId
        - name
    SnapshotDetails:
      title: SnapshotDetails
      type: object
      properties:
        snapshotId:
          type: string
          description: Immutable snapshot identity.
        snapshotCommittedAt:
          type: integer
          format: int64
          description: >-
            Snapshot commit time as Unix epoch milliseconds, distinct from ref
            creation time and collection dataUpdatedAt.
      required:
        - snapshotId
        - snapshotCommittedAt
    ResourceNotFound:
      title: ResourceNotFound
      type: object
      properties:
        message:
          type: string
    MessageResponse:
      type: object
      properties:
        message:
          type: string
      required:
        - message
    EmbeddingSource:
      type: object
      properties:
        field:
          type: string
          minLength: 1
          pattern: .*\S.*
          description: >-
            Unique dotted path in the original stored JSON; no index declaration
            is required.
        type:
          type: string
          enum:
            - text
            - image
      required:
        - field
        - type
      additionalProperties: false
  responses:
    ResourceNotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResourceNotFound'
          examples:
            example:
              summary: Example response for resource not found
              value:
                message: Resource not found
    CatalogConflict:
      description: >-
        Conditional catalog conflict. Refresh the resource state before deciding
        whether to retry.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/MessageResponse'
    PayloadTooLarge:
      description: >-
        Request exceeds the Gateway transport limit. Reduce the request size or
        use bulk upsert when supported.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/MessageResponse'
    BadGateway:
      description: >-
        Unexpected downstream failure. A failed write response may leave its
        outcome uncertain.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/MessageResponse'
    ServiceUnavailable:
      description: >-
        Transient catalog or storage dependency failure. Use bounded retries
        where the operation permits.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/MessageResponse'
    GatewayTimeout:
      description: >-
        Gateway request deadline exceeded. A write may have been applied; verify
        its outcome before retrying.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/MessageResponse'
  securitySchemes:
    ProjectApiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: Project API Key.
      x-speakeasy-example: <YOUR_PROJECT_API_KEY>

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.