> ## 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.

# Describe a branch

> Get a branch with its index schema and data statistics. A branch owns its indexConfigs: a new branch inherits the source branch's current version, the tag's pinned version, or the origin snapshot's version for an asOf branch, and later schema updates of other branches, including main, do not change it. A name that is not a branch returns 404.



## OpenAPI

````yaml get /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}:
    get:
      tags:
        - versioning
      summary: Describe a Branch
      description: >-
        Get a branch with its index schema and data statistics. A branch owns
        its indexConfigs: a new branch inherits the source branch's current
        version, the tag's pinned version, or the origin snapshot's version for
        an asOf branch, and later schema updates of other branches, including
        main, do not change it. A name that is not a branch returns 404.
      operationId: getBranch
      parameters:
        - $ref: '#/components/parameters/CollectionName'
        - $ref: '#/components/parameters/BranchName'
      responses:
        '200':
          description: 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
        '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'
        '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:
    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
    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
    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
    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.
    ResourceNotFound:
      title: ResourceNotFound
      type: object
      properties:
        message:
          type: string
    MessageResponse:
      type: object
      properties:
        message:
          type: string
      required:
        - message
    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
    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
    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.