> ## 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 an alias

> Get an alias with the index schema it currently serves, read through to its target: a branch's current version or a tag's pinned version. Retargeting an alias across branches with different schemas is allowed and not checked by the server; this route shows which schema reads through the alias see. A dangling alias (its bound target identity is gone) still returns 200 with dangling true and null indexConfigs. A name that is not an alias returns 404.



## OpenAPI

````yaml get /collections/{collectionName}/aliases/{aliasName}
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}/aliases/{aliasName}:
    get:
      tags:
        - versioning
      summary: Describe an Alias
      description: >-
        Get an alias with the index schema it currently serves, read through to
        its target: a branch's current version or a tag's pinned version.
        Retargeting an alias across branches with different schemas is allowed
        and not checked by the server; this route shows which schema reads
        through the alias see. A dangling alias (its bound target identity is
        gone) still returns 200 with dangling true and null indexConfigs. A name
        that is not an alias returns 404.
      operationId: getAlias
      parameters:
        - $ref: '#/components/parameters/CollectionName'
        - $ref: '#/components/parameters/AliasName'
      responses:
        '200':
          description: Alias with its target's index schema.
          content:
            application/json:
              schema:
                type: object
                properties:
                  alias:
                    $ref: '#/components/schemas/AliasDetails'
                required:
                  - alias
              examples:
                example:
                  value:
                    alias:
                      aliasId: alias-id
                      aliasName: latest
                      targetKind: BRANCH
                      targetName: main
                      targetId: main-branch-id
                      aliasRevision: 1
                      dangling: false
                      indexConfigs:
                        title:
                          type: text
                          analyzers:
                            - english
                          description: Book title as printed on the cover
                        category:
                          type: keyword
                        id:
                          type: keyword
                      createdAt: 1788336000000
        '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
    AliasName:
      in: path
      name: aliasName
      required: true
      schema:
        type: string
        minLength: 3
        maxLength: 52
        pattern: ^[a-zA-Z0-9_-]{3,52}$
  schemas:
    AliasDetails:
      title: AliasDetails
      type: object
      properties:
        aliasId:
          type: string
        aliasName:
          type: string
        targetKind:
          type: string
          enum:
            - BRANCH
            - TAG
        targetName:
          type: string
        targetId:
          type: string
        aliasRevision:
          type: integer
          format: int64
          minimum: 0
        dangling:
          type: boolean
          description: >-
            Whether the bound target identity is missing. Document reads through
            a dangling alias return 400; GET
            /collections/{collectionName}/aliases/{aliasName} still returns the
            alias with null indexConfigs. Deletion of a non-default branch or a
            tag is blocked with 409 while aliases reference it.
        createdAt:
          type: integer
          format: int64
          description: Alias creation time as Unix epoch milliseconds.
        indexConfigs:
          description: Index schema of the target's version; null for a dangling alias.
          anyOf:
            - $ref: '#/components/schemas/IndexConfigs'
            - type: 'null'
      required:
        - aliasId
        - aliasName
        - targetKind
        - targetName
        - targetId
        - aliasRevision
        - dangling
        - 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
    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.