LanceDB Tag API

openapi: 3.1.1
info:
  title: Lance Namespace Specification Data Tag API
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  version: 1.0.0
  description: 'This OpenAPI specification is a part of the Lance namespace specification. It contains 2 parts:


    The `components/schemas`, `components/responses`, `components/examples`, `tags` sections define

    the request and response shape for each operation in a Lance Namespace across all implementations.

    See https://lance.org/format/namespace/operations for more details.


    The `servers`, `security`, `paths`, `components/parameters` sections are for the

    Lance REST Namespace implementation, which defines a complete REST server that can work with Lance datasets.

    See https://lance.org/format/namespace/rest for more details.

    '
servers:
- url: '{scheme}://{host}:{port}/{basePath}'
  description: Generic server URL with all parts configurable
  variables:
    scheme:
      default: http
    host:
      default: localhost
    port:
      default: '2333'
    basePath:
      default: ''
- url: '{scheme}://{host}/{basePath}'
  description: Server URL when the port can be inferred from the scheme
  variables:
    scheme:
      default: http
    host:
      default: localhost
    basePath:
      default: ''
security:
- OAuth2: []
- BearerAuth: []
- ApiKeyAuth: []
tags:
- name: Tag
  description: 'Operations that are related to tags

    '
paths:
  /v1/table/{id}/tags/list:
    parameters:
    - $ref: '#/components/parameters/id'
    - $ref: '#/components/parameters/delimiter'
    - $ref: '#/components/parameters/page_token'
    - $ref: '#/components/parameters/limit'
    post:
      tags:
      - Tag
      summary: List all tags for a table
      operationId: ListTableTags
      description: 'List all tags that have been created for table `id`.

        Returns a map of tag names to their corresponding version numbers and metadata.


        REST NAMESPACE ONLY

        REST namespace does not use a request body for this operation.

        The `ListTableTagsRequest` information is passed in the following way:

        - `id`: pass through path parameter of the same name

        - `page_token`: pass through query parameter of the same name

        - `limit`: pass through query parameter of the same name

        '
      responses:
        200:
          $ref: '#/components/responses/ListTableTagsResponse'
        400:
          $ref: '#/components/responses/BadRequestErrorResponse'
        401:
          $ref: '#/components/responses/UnauthorizedErrorResponse'
        403:
          $ref: '#/components/responses/ForbiddenErrorResponse'
        404:
          $ref: '#/components/responses/NotFoundErrorResponse'
        503:
          $ref: '#/components/responses/ServiceUnavailableErrorResponse'
        5XX:
          $ref: '#/components/responses/ServerErrorResponse'
  /v1/table/{id}/tags/version:
    parameters:
    - $ref: '#/components/parameters/id'
    - $ref: '#/components/parameters/delimiter'
    post:
      tags:
      - Tag
      summary: Get version for a specific tag
      operationId: GetTableTagVersion
      description: 'Get the version number that a specific tag points to for table `id`.

        '
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetTableTagVersionRequest'
      responses:
        200:
          $ref: '#/components/responses/GetTableTagVersionResponse'
        400:
          $ref: '#/components/responses/BadRequestErrorResponse'
        401:
          $ref: '#/components/responses/UnauthorizedErrorResponse'
        403:
          $ref: '#/components/responses/ForbiddenErrorResponse'
        404:
          $ref: '#/components/responses/NotFoundErrorResponse'
        503:
          $ref: '#/components/responses/ServiceUnavailableErrorResponse'
        5XX:
          $ref: '#/components/responses/ServerErrorResponse'
  /v1/table/{id}/tags/create:
    parameters:
    - $ref: '#/components/parameters/id'
    - $ref: '#/components/parameters/delimiter'
    post:
      tags:
      - Tag
      summary: Create a new tag
      operationId: CreateTableTag
      description: 'Create a new tag for table `id` that points to a specific version.

        '
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTableTagRequest'
      responses:
        200:
          $ref: '#/components/responses/CreateTableTagResponse'
        400:
          $ref: '#/components/responses/BadRequestErrorResponse'
        401:
          $ref: '#/components/responses/UnauthorizedErrorResponse'
        403:
          $ref: '#/components/responses/ForbiddenErrorResponse'
        404:
          $ref: '#/components/responses/NotFoundErrorResponse'
        409:
          $ref: '#/components/responses/ConflictErrorResponse'
        503:
          $ref: '#/components/responses/ServiceUnavailableErrorResponse'
        5XX:
          $ref: '#/components/responses/ServerErrorResponse'
  /v1/table/{id}/tags/delete:
    parameters:
    - $ref: '#/components/parameters/id'
    - $ref: '#/components/parameters/delimiter'
    post:
      tags:
      - Tag
      summary: Delete a tag
      operationId: DeleteTableTag
      description: 'Delete an existing tag from table `id`.

        '
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteTableTagRequest'
      responses:
        200:
          $ref: '#/components/responses/DeleteTableTagResponse'
        400:
          $ref: '#/components/responses/BadRequestErrorResponse'
        401:
          $ref: '#/components/responses/UnauthorizedErrorResponse'
        403:
          $ref: '#/components/responses/ForbiddenErrorResponse'
        404:
          $ref: '#/components/responses/NotFoundErrorResponse'
        503:
          $ref: '#/components/responses/ServiceUnavailableErrorResponse'
        5XX:
          $ref: '#/components/responses/ServerErrorResponse'
  /v1/table/{id}/tags/update:
    parameters:
    - $ref: '#/components/parameters/id'
    - $ref: '#/components/parameters/delimiter'
    post:
      tags:
      - Tag
      summary: Update a tag to point to a different version
      operationId: UpdateTableTag
      description: 'Update an existing tag for table `id` to point to a different version.

        '
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateTableTagRequest'
      responses:
        200:
          $ref: '#/components/responses/UpdateTableTagResponse'
        400:
          $ref: '#/components/responses/BadRequestErrorResponse'
        401:
          $ref: '#/components/responses/UnauthorizedErrorResponse'
        403:
          $ref: '#/components/responses/ForbiddenErrorResponse'
        404:
          $ref: '#/components/responses/NotFoundErrorResponse'
        503:
          $ref: '#/components/responses/ServiceUnavailableErrorResponse'
        5XX:
          $ref: '#/components/responses/ServerErrorResponse'
components:
  responses:
    ServerErrorResponse:
      description: A server-side problem that might not be addressable from the client side. Used for server 5xx errors without more specific documentation in individual routes.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            type: /errors/server-error
            title: Internal Server Error
            status: 500
            detail: ''
            instance: /v1/namespaces
    BadRequestErrorResponse:
      description: Indicates a bad request error. It could be caused by an unexpected request body format or other forms of request validation failure, such as invalid json. Usually serves application/json content, although in some cases simple text/plain content might be returned by the server's middleware.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            type: /errors/bad-request
            title: Malformed request
            status: 400
            detail: ''
            instance: /v1/namespaces
    UpdateTableTagResponse:
      description: Update tag response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UpdateTableTagResponse'
    ListTableTagsResponse:
      description: List of table tags
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ListTableTagsResponse'
    ConflictErrorResponse:
      description: The request conflicts with the current state of the target resource.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            type: /errors/conflict
            title: The namespace has been concurrently modified
            status: 409
            detail: ''
            instance: /v1/namespaces/{ns}
    ServiceUnavailableErrorResponse:
      description: The service is not ready to handle the request. The client should wait and retry. The service may additionally send a Retry-After header to indicate when to retry.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            type: /errors/service-unavailable
            title: Slow down
            status: 503
            detail: ''
            instance: /v1/namespaces
    DeleteTableTagResponse:
      description: Delete tag response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DeleteTableTagResponse'
    CreateTableTagResponse:
      description: Create tag response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CreateTableTagResponse'
    ForbiddenErrorResponse:
      description: Forbidden. Authenticated user does not have the necessary permissions.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            type: /errors/forbidden-request
            title: Not authorized to make this request
            status: 403
            detail: ''
            instance: /v1/namespaces
    GetTableTagVersionResponse:
      description: Tag version information
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GetTableTagVersionResponse'
    UnauthorizedErrorResponse:
      description: Unauthorized. The request lacks valid authentication credentials for the operation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            type: /errors/unauthorized-request
            title: No valid authentication credentials for the operation
            status: 401
            detail: ''
            instance: /v1/namespaces
    NotFoundErrorResponse:
      description: A server-side problem that means can not find the specified resource.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            type: /errors/not-found-error
            title: Not found Error
            status: 404
            detail: ''
            instance: /v1/namespaces/{ns}
  schemas:
    ListTableTagsResponse:
      type: object
      description: Response containing table tags
      required:
      - tags
      properties:
        tags:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/TagContents'
          description: Map of tag names to their contents
        page_token:
          $ref: '#/components/schemas/PageToken'
    TagContents:
      type: object
      required:
      - version
      - manifestSize
      properties:
        branch:
          type: string
          description: Branch name that the tag was created on (if any)
        version:
          type: integer
          format: int64
          minimum: 0
          description: Version number that the tag points to
        manifestSize:
          type: integer
          format: int64
          minimum: 0
          description: Size of the manifest file in bytes
    UpdateTableTagResponse:
      type: object
      description: Response for update tag operation
      properties:
        transaction_id:
          type: string
          description: Optional transaction identifier
    GetTableTagVersionRequest:
      type: object
      required:
      - tag
      properties:
        identity:
          $ref: '#/components/schemas/Identity'
        context:
          $ref: '#/components/schemas/Context'
        id:
          type: array
          items:
            type: string
        tag:
          type: string
          description: Name of the tag to get version for
    Identity:
      type: object
      description: 'Identity information of a request.

        '
      properties:
        api_key:
          type: string
          description: 'API key for authentication.


            REST NAMESPACE ONLY

            This is passed via the `x-api-key` header.

            '
        auth_token:
          type: string
          description: 'Bearer token for authentication.


            REST NAMESPACE ONLY

            This is passed via the `Authorization` header

            with the Bearer scheme (e.g., `Bearer <token>`).

            '
    CreateTableTagResponse:
      type: object
      description: Response for create tag operation
      properties:
        transaction_id:
          type: string
          description: Optional transaction identifier
    DeleteTableTagRequest:
      type: object
      required:
      - tag
      properties:
        identity:
          $ref: '#/components/schemas/Identity'
        context:
          $ref: '#/components/schemas/Context'
        id:
          type: array
          items:
            type: string
        tag:
          type: string
          description: Name of the tag to delete
    UpdateTableTagRequest:
      type: object
      required:
      - tag
      - version
      properties:
        identity:
          $ref: '#/components/schemas/Identity'
        context:
          $ref: '#/components/schemas/Context'
        id:
          type: array
          items:
            type: string
        tag:
          type: string
          description: Name of the tag to update
        version:
          type: integer
          format: int64
          minimum: 0
          description: New version number for the tag to point to
    PageToken:
      description: 'An opaque token that allows pagination for list operations (e.g. ListNamespaces).


        For an initial request of a list operation,

        if the implementation cannot return all items in one response,

        or if there are more items than the page limit specified in the request,

        the implementation must return a page token in the response,

        indicating there are more results available.


        After the initial request,

        the value of the page token from each response must be used

        as the page token value for the next request.


        Caller must interpret either `null`,

        missing value or empty string value of the page token from

        the implementation''s response as the end of the listing results.

        '
      type: string
      nullable: true
    ErrorResponse:
      type: object
      description: Common JSON error response model
      required:
      - code
      properties:
        error:
          type: string
          description: A brief, human-readable message about the error.
          example: Table 'users' not found in namespace 'production'
        code:
          type: integer
          minimum: 0
          description: "Lance Namespace error code identifying the error type.\n\nError codes:\n  0 - Unsupported: Operation not supported by this backend\n  1 - NamespaceNotFound: The specified namespace does not exist\n  2 - NamespaceAlreadyExists: A namespace with this name already exists\n  3 - NamespaceNotEmpty: Namespace contains tables or child namespaces\n  4 - TableNotFound: The specified table does not exist\n  5 - TableAlreadyExists: A table with this name already exists\n  6 - TableIndexNotFound: The specified table index does not exist\n  7 - TableIndexAlreadyExists: A table index with this name already exists\n  8 - TableTagNotFound: The specified table tag does not exist\n  9 - TableTagAlreadyExists: A table tag with this name already exists\n  10 - TransactionNotFound: The specified transaction does not exist\n  11 - TableVersionNotFound: The specified table version does not exist\n  12 - TableColumnNotFound: The specified table column does not exist\n  13 - InvalidInput: Malformed request or invalid parameters\n  14 - ConcurrentModification: Optimistic concurrency conflict\n  15 - PermissionDenied: User lacks permission for this operation\n  16 - Unauthenticated: Authentication credentials are missing or invalid\n  17 - ServiceUnavailable: Service is temporarily unavailable\n  18 - Internal: Unexpected server/implementation error\n  19 - InvalidTableState: Table is in an invalid state for the operation\n  20 - TableSchemaValidationError: Table schema validation failed\n"
          example: 4
        detail:
          type: string
          description: 'An optional human-readable explanation of the error.

            This can be used to record additional information such as stack trace.

            '
          example: The table may have been dropped or renamed
        instance:
          type: string
          description: 'A string that identifies the specific occurrence of the error.

            This can be a URI, a request or response ID,

            or anything that the implementation can recognize to trace specific occurrence of the error.

            '
          example: /v1/table/production$users/describe
    Context:
      type: object
      description: 'Arbitrary context for a request as key-value pairs.

        How to use the context is custom to the specific implementation.


        REST NAMESPACE ONLY

        Context entries are passed via HTTP headers using the naming convention

        `x-lance-ctx-<key>: <value>`. For example, a context entry

        `{"trace_id": "abc123"}` would be sent as the header `x-lance-ctx-trace_id: abc123`.

        '
      additionalProperties:
        type: string
    CreateTableTagRequest:
      type: object
      required:
      - tag
      - version
      properties:
        identity:
          $ref: '#/components/schemas/Identity'
        context:
          $ref: '#/components/schemas/Context'
        id:
          type: array
          items:
            type: string
        tag:
          type: string
          description: Name of the tag to create
        version:
          type: integer
          format: int64
          minimum: 0
          description: Version number for the tag to point to
    PageLimit:
      description: 'An inclusive upper bound of the

        number of results that a caller will receive.

        '
      type: integer
      nullable: true
    GetTableTagVersionResponse:
      type: object
      required:
      - version
      properties:
        version:
          type: integer
          format: int64
          minimum: 0
          description: version number that the tag points to
    DeleteTableTagResponse:
      type: object
      description: Response for delete tag operation
      properties:
        transaction_id:
          type: string
          description: Optional transaction identifier
  parameters:
    page_token:
      name: page_token
      description: Pagination token from a previous request
      in: query
      required: false
      schema:
        $ref: '#/components/schemas/PageToken'
    id:
      name: id
      description: '`string identifier` of an object in a namespace, following the Lance Namespace spec.

        When the value is equal to the delimiter, it represents the root namespace.

        For example, `v1/namespace/$/list` performs a `ListNamespace` on the root namespace.

        '
      in: path
      required: true
      schema:
        type: string
    delimiter:
      name: delimiter
      description: 'An optional delimiter of the `string identifier`, following the Lance Namespace spec.

        When not specified, the `$` delimiter must be used.

        '
      in: query
      required: false
      schema:
        type: string
    limit:
      name: limit
      description: Maximum number of items to return
      in: query
      required: false
      schema:
        $ref: '#/components/schemas/PageLimit'
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: /oauth/token
          scopes: {}
    BearerAuth:
      type: http
      scheme: bearer
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key