openapi: 3.1.1
info:
  title: Lance Namespace Specification Data Index 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: Index
  description: 'Operations that are related to an index

    '
paths:
  /v1/table/{id}/create_index:
    parameters:
    - $ref: '#/components/parameters/id'
    - $ref: '#/components/parameters/delimiter'
    post:
      tags:
      - Index
      summary: Create an index on a table
      operationId: CreateTableIndex
      description: 'Create an index on a table column for faster search operations.

        Supports vector indexes (IVF_FLAT, IVF_HNSW_SQ, IVF_PQ, etc.) and scalar indexes (BTREE, BITMAP, FTS, etc.).

        Index creation is handled asynchronously.

        Use the `ListTableIndices` and `DescribeTableIndexStats` operations to monitor index creation progress.

        '
      requestBody:
        description: Index creation request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTableIndexRequest'
        required: true
      responses:
        200:
          $ref: '#/components/responses/CreateTableIndexResponse'
        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}/create_scalar_index:
    parameters:
    - $ref: '#/components/parameters/id'
    - $ref: '#/components/parameters/delimiter'
    post:
      tags:
      - Index
      summary: Create a scalar index on a table
      operationId: CreateTableScalarIndex
      description: 'Create a scalar index on a table column for faster filtering operations.

        Supports scalar indexes (BTREE, BITMAP, LABEL_LIST, FTS, etc.).

        This is an alias for CreateTableIndex specifically for scalar indexes.

        Index creation is handled asynchronously.

        Use the `ListTableIndices` and `DescribeTableIndexStats` operations to monitor index creation progress.

        '
      requestBody:
        description: Scalar index creation request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTableIndexRequest'
        required: true
      responses:
        200:
          $ref: '#/components/responses/CreateTableScalarIndexResponse'
        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}/index/list:
    parameters:
    - $ref: '#/components/parameters/id'
    - $ref: '#/components/parameters/delimiter'
    post:
      tags:
      - Index
      summary: List indexes on a table
      operationId: ListTableIndices
      description: 'List all indices created on a table. Returns information about each index

        including name, columns, status, and UUID.

        '
      requestBody:
        description: Index list request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListTableIndicesRequest'
        required: true
      responses:
        200:
          $ref: '#/components/responses/ListTableIndicesResponse'
        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}/index/{index_name}/stats:
    parameters:
    - $ref: '#/components/parameters/id'
    - $ref: '#/components/parameters/delimiter'
    - name: index_name
      in: path
      description: Name of the index to get stats for
      required: true
      schema:
        type: string
    post:
      tags:
      - Index
      summary: Get table index statistics
      operationId: DescribeTableIndexStats
      description: 'Get statistics for a specific index on a table. Returns information about

        the index type, distance type (for vector indices), and row counts.

        '
      requestBody:
        description: Index stats request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DescribeTableIndexStatsRequest'
        required: true
      responses:
        200:
          $ref: '#/components/responses/DescribeTableIndexStatsResponse'
        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}/index/{index_name}/drop:
    parameters:
    - $ref: '#/components/parameters/id'
    - $ref: '#/components/parameters/delimiter'
    - name: index_name
      in: path
      description: Name of the index to drop
      required: true
      schema:
        type: string
    post:
      tags:
      - Index
      summary: Drop a specific index
      operationId: DropTableIndex
      description: 'Drop the specified index from table `id`.


        REST NAMESPACE ONLY

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

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

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

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

        '
      responses:
        200:
          $ref: '#/components/responses/DropTableIndexResponse'
        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:
  schemas:
    DropTableIndexResponse:
      type: object
      description: Response for drop index operation
      properties:
        transaction_id:
          type: string
          description: Optional transaction identifier
    CreateTableIndexRequest:
      type: object
      required:
      - column
      - index_type
      properties:
        identity:
          $ref: '#/components/schemas/Identity'
        context:
          $ref: '#/components/schemas/Context'
        id:
          type: array
          items:
            type: string
        column:
          type: string
          description: Name of the column to create index on
        index_type:
          type: string
          description: Type of index to create (e.g., BTREE, BITMAP, LABEL_LIST, IVF_FLAT, IVF_PQ, IVF_HNSW_SQ, FTS)
        name:
          type: string
          nullable: true
          description: Optional name for the index. If not provided, a name will be auto-generated.
        distance_type:
          type: string
          description: Distance metric type for vector indexes (e.g., l2, cosine, dot)
        with_position:
          type: boolean
          nullable: true
          description: Optional FTS parameter for position tracking
        base_tokenizer:
          type: string
          nullable: true
          description: Optional FTS parameter for base tokenizer
        language:
          type: string
          nullable: true
          description: Optional FTS parameter for language
        max_token_length:
          type: integer
          nullable: true
          minimum: 0
          description: Optional FTS parameter for maximum token length
        lower_case:
          type: boolean
          nullable: true
          description: Optional FTS parameter for lowercase conversion
        stem:
          type: boolean
          nullable: true
          description: Optional FTS parameter for stemming
        remove_stop_words:
          type: boolean
          nullable: true
          description: Optional FTS parameter for stop word removal
        ascii_folding:
          type: boolean
          nullable: true
          description: Optional FTS parameter for ASCII folding
    ListTableIndicesRequest:
      type: object
      properties:
        identity:
          $ref: '#/components/schemas/Identity'
        context:
          $ref: '#/components/schemas/Context'
        id:
          type: array
          items:
            type: string
          description: The namespace identifier
        version:
          type: integer
          format: int64
          minimum: 0
          nullable: true
          description: Optional table version to list indexes from
        page_token:
          $ref: '#/components/schemas/PageToken'
        limit:
          $ref: '#/components/schemas/PageLimit'
    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>`).

            '
    IndexContent:
      type: object
      required:
      - index_name
      - index_uuid
      - columns
      - status
      properties:
        index_name:
          type: string
          description: Name of the index
        index_uuid:
          type: string
          description: Unique identifier for the index
        columns:
          type: array
          items:
            type: string
          description: Columns covered by this index
        status:
          type: string
          description: Current status of the index
    DescribeTableIndexStatsResponse:
      type: object
      properties:
        distance_type:
          type: string
          nullable: true
          description: Distance type for vector indexes
        index_type:
          type: string
          nullable: true
          description: Type of the index
        num_indexed_rows:
          type: integer
          format: int64
          minimum: 0
          nullable: true
          description: Number of indexed rows
        num_unindexed_rows:
          type: integer
          format: int64
          minimum: 0
          nullable: true
          description: Number of unindexed rows
        num_indices:
          type: integer
          format: int32
          minimum: 0
          nullable: true
          description: Number of indices
    DescribeTableIndexStatsRequest:
      type: object
      properties:
        identity:
          $ref: '#/components/schemas/Identity'
        context:
          $ref: '#/components/schemas/Context'
        id:
          type: array
          items:
            type: string
        version:
          type: integer
          format: int64
          minimum: 0
          nullable: true
          description: Optional table version to get stats for
        index_name:
          type: string
          description: Name of the index
    PageLimit:
      description: 'An inclusive upper bound of the

        number of results that a caller will receive.

        '
      type: integer
      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
    CreateTableIndexResponse:
      type: object
      description: Response for create index operation
      properties:
        transaction_id:
          type: string
          description: Optional transaction identifier
    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
    CreateTableScalarIndexResponse:
      type: object
      description: Response for create scalar index operation
      properties:
        transaction_id:
          type: string
          description: Optional transaction identifier
    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
    ListTableIndicesResponse:
      type: object
      required:
      - indexes
      properties:
        indexes:
          type: array
          items:
            $ref: '#/components/schemas/IndexContent'
          description: List of indexes on the table
        page_token:
          $ref: '#/components/schemas/PageToken'
  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
    ListTableIndicesResponse:
      description: List of indices on the table
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ListTableIndicesResponse'
    DropTableIndexResponse:
      description: Index drop operation result
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DropTableIndexResponse'
    CreateTableIndexResponse:
      description: Index created successfully
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CreateTableIndexResponse'
    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
    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
    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}
    CreateTableScalarIndexResponse:
      description: Scalar index created successfully
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CreateTableScalarIndexResponse'
    DescribeTableIndexStatsResponse:
      description: Index statistics
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DescribeTableIndexStatsResponse'
  parameters:
    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
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: /oauth/token
          scopes: {}
    BearerAuth:
      type: http
      scheme: bearer
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key