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

# Retarget an alias

> Retarget an alias to a branch or tag.



## OpenAPI

````yaml patch /collections/{collectionName}/aliases/{aliasName}
openapi: 3.1.1
info:
  title: LambdaDB API
  summary: LambdaDB Open API Spec
  version: 1.1.1
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}:
    patch:
      tags:
        - versioning
      summary: Retarget an Alias
      description: Retarget an alias to a branch or tag.
      operationId: retargetAlias
      parameters:
        - $ref: '#/components/parameters/CollectionName'
        - $ref: '#/components/parameters/AliasName'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                target:
                  type: object
                  additionalProperties: false
                  properties:
                    kind:
                      type: string
                      enum:
                        - branch
                        - tag
                    name:
                      type: string
                      minLength: 3
                      maxLength: 52
                      pattern: ^[a-zA-Z0-9_-]{3,52}$
                  required:
                    - kind
                    - name
              required:
                - target
            examples:
              example:
                value:
                  target:
                    kind: branch
                    name: main
      responses:
        '200':
          description: Alias retargeted.
          content:
            application/json:
              schema:
                type: object
                properties:
                  alias:
                    $ref: '#/components/schemas/AliasDetails'
                required:
                  - alias
              examples:
                example:
                  value:
                    alias:
                      aliasId: alias-id
                      aliasName: production-read
                      targetKind: BRANCH
                      targetName: main
                      targetId: branch-id
                      aliasRevision: 1
                      dangling: false
                      createdAt: 1788336000000
        '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
    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. Reads of a dangling
            alias return 400. 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.
      required:
        - aliasId
        - aliasName
        - targetKind
        - targetName
        - targetId
        - aliasRevision
        - dangling
        - 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
    ResourceNotFound:
      title: ResourceNotFound
      type: object
      properties:
        message:
          type: string
    MessageResponse:
      type: object
      properties:
        message:
          type: string
      required:
        - message
  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>

````