Lakekeeper Catalog API

openapi: 3.2.0
info:
  title: Apache Iceberg REST Catalog Catalog API
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  version: 0.0.1
  description: Defines the specification for the first version of the REST Catalog API. Implementations should ideally support all Iceberg table spec versions.
servers:
- url: '{scheme}://{host}/{basePath}'
  description: Server URL when the port can be inferred from the scheme
  variables:
    scheme:
      description: The scheme of the URI, either http or https.
      default: https
    host:
      description: The host address for the specified server
      default: localhost
    basePath:
      description: Optional prefix to be appended to all routes
      default: ''
- url: '{scheme}://{host}:{port}/{basePath}'
  description: Generic base server URL, with all parts configurable
  variables:
    scheme:
      description: The scheme of the URI, either http or https.
      default: https
    host:
      description: The host address for the specified server
      default: localhost
    port:
      description: The port used when addressing the host
      default: '443'
    basePath:
      description: Optional prefix to be appended to all routes
      default: ''
security:
- OAuth2:
  - catalog
- BearerAuth: []
tags:
- name: Catalog API
paths:
  /v1/{prefix}/namespaces:
    parameters:
    - $ref: '#/components/parameters/prefix'
    get:
      tags:
      - Catalog API
      summary: List namespaces, optionally providing a parent namespace to list underneath
      description: List all namespaces at a certain level, optionally starting from a given parent namespace. If table accounting.tax.paid.info exists, using 'SELECT NAMESPACE IN accounting' would translate into `GET /namespaces?parent=accounting` and must return a namespace, ["accounting", "tax"] only. Using 'SELECT NAMESPACE IN accounting.tax' would translate into `GET /namespaces?parent=accounting%1Ftax` and must return a namespace, ["accounting", "tax", "paid"]. If `parent` is not provided, all top-level namespaces should be listed.
      operationId: listNamespaces
      parameters:
      - $ref: '#/components/parameters/page-token'
      - $ref: '#/components/parameters/page-size'
      - name: parent
        in: query
        description: An optional namespace, underneath which to list namespaces. If not provided, all top-level namespaces should be listed. For backward compatibility, empty string is treated as absent for now. If parent is a multipart namespace, the parts must be separated by the namespace separator as indicated via the /config override `namespace-separator`, which defaults to the unit separator `0x1F` byte (url encoded `%1F`). To be compatible with older clients, servers must use both the advertised separator and `0x1F` as valid separators when decoding namespaces. The `namespace-separator` should be provided in a url encoded form.
        required: false
        schema:
          type: string
        example: accounting%1Ftax
      - name: returnUuids
        in: query
        description: If true, include the `namespace-uuids` field in the response
        required: false
        schema:
          type: boolean
          default: false
      - name: returnProtectionStatus
        in: query
        description: If true, include the `protection-status` field in the response
        required: false
        schema:
          type: boolean
          default: false
      responses:
        200:
          $ref: '#/components/responses/ListNamespacesResponse'
        400:
          $ref: '#/components/responses/BadRequestErrorResponse'
        401:
          $ref: '#/components/responses/UnauthorizedResponse'
        403:
          $ref: '#/components/responses/ForbiddenResponse'
        404:
          description: Not Found - Namespace provided in the `parent` query parameter is not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IcebergErrorResponse'
              examples:
                NoSuchNamespaceExample:
                  $ref: '#/components/examples/NoSuchNamespaceError'
        419:
          $ref: '#/components/responses/AuthenticationTimeoutResponse'
        503:
          $ref: '#/components/responses/ServiceUnavailableResponse'
        5XX:
          $ref: '#/components/responses/ServerErrorResponse'
    post:
      tags:
      - Catalog API
      summary: Create a namespace
      parameters:
      - $ref: '#/components/parameters/idempotency-key'
      description: Create a namespace, with an optional set of properties. The server might also add properties, such as `last_modified_time` etc.
      operationId: createNamespace
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateNamespaceRequest'
      responses:
        200:
          $ref: '#/components/responses/CreateNamespaceResponse'
        400:
          $ref: '#/components/responses/BadRequestErrorResponse'
        401:
          $ref: '#/components/responses/UnauthorizedResponse'
        403:
          $ref: '#/components/responses/ForbiddenResponse'
        406:
          $ref: '#/components/responses/UnsupportedOperationResponse'
        409:
          description: Conflict - The namespace already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IcebergErrorResponse'
              examples:
                NamespaceAlreadyExists:
                  $ref: '#/components/examples/NamespaceAlreadyExistsError'
        419:
          $ref: '#/components/responses/AuthenticationTimeoutResponse'
        503:
          $ref: '#/components/responses/ServiceUnavailableResponse'
        5XX:
          $ref: '#/components/responses/ServerErrorResponse'
  /v1/{prefix}/namespaces/{namespace}:
    parameters:
    - $ref: '#/components/parameters/prefix'
    - $ref: '#/components/parameters/namespace'
    get:
      tags:
      - Catalog API
      summary: Load the metadata properties for a namespace
      operationId: loadNamespaceMetadata
      description: Return all stored metadata properties for a given namespace
      responses:
        200:
          $ref: '#/components/responses/GetNamespaceResponse'
        400:
          $ref: '#/components/responses/BadRequestErrorResponse'
        401:
          $ref: '#/components/responses/UnauthorizedResponse'
        403:
          $ref: '#/components/responses/ForbiddenResponse'
        404:
          description: Not Found - Namespace not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IcebergErrorResponse'
              examples:
                NoSuchNamespaceExample:
                  $ref: '#/components/examples/NoSuchNamespaceError'
        419:
          $ref: '#/components/responses/AuthenticationTimeoutResponse'
        503:
          $ref: '#/components/responses/ServiceUnavailableResponse'
        5XX:
          $ref: '#/components/responses/ServerErrorResponse'
      parameters:
      - name: returnUuid
        in: query
        description: If true, include the `namespace-uuid` field in the response
        required: false
        schema:
          type: boolean
          default: false
    head:
      tags:
      - Catalog API
      summary: Check if a namespace exists
      operationId: namespaceExists
      description: Check if a namespace exists. The response does not contain a body.
      responses:
        204:
          description: Success, no content
        400:
          $ref: '#/components/responses/BadRequestErrorResponse'
        401:
          $ref: '#/components/responses/UnauthorizedResponse'
        403:
          $ref: '#/components/responses/ForbiddenResponse'
        404:
          description: Not Found - Namespace not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IcebergErrorResponse'
              examples:
                NoSuchNamespaceExample:
                  $ref: '#/components/examples/NoSuchNamespaceError'
        419:
          $ref: '#/components/responses/AuthenticationTimeoutResponse'
        503:
          $ref: '#/components/responses/ServiceUnavailableResponse'
        5XX:
          $ref: '#/components/responses/ServerErrorResponse'
    delete:
      tags:
      - Catalog API
      summary: Drop a namespace from the catalog.
      operationId: dropNamespace
      parameters:
      - $ref: '#/components/parameters/idempotency-key'
      - name: force
        in: query
        description: If force and recursive are set to true, immediately delete all contents of the namespace without considering soft-delete policies. Force has no effect without recursive=true.
        required: false
        schema:
          type: boolean
          default: false
      - name: recursive
        in: query
        description: Delete a namespace and its contents. This means all tables, views, and namespaces under this namespace will be deleted. The namespace itself will also be deleted. If the warehouse containing the namespace is configured with a soft-deletion profile, the `force` flag has to be provided. The deletion will not be a soft-deletion. Every table, view and namespace will be gone as soon as this call returns. Depending on whether the `purge` flag was set to true, the data will be queued for deletion too. Any pending `tabular_expiration` will be cancelled. If there is a running `tabular_expiration`, this call will fail with a `409 Conflict` error.
        required: false
        schema:
          type: boolean
          default: false
      - name: purge
        in: query
        description: If recursive is true, also deletes table and view data. If false, only metadata is dropped from the catalog, table location remains untouched. Defaults to true for all tables managed by Lakekeeper.
        required: false
        schema:
          type: boolean
          default: true
      responses:
        204:
          description: Success, no content
        400:
          $ref: '#/components/responses/BadRequestErrorResponse'
        401:
          $ref: '#/components/responses/UnauthorizedResponse'
        403:
          $ref: '#/components/responses/ForbiddenResponse'
        404:
          description: Not Found - Namespace to delete does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IcebergErrorResponse'
              examples:
                NoSuchNamespaceExample:
                  $ref: '#/components/examples/NoSuchNamespaceError'
        409:
          description: Not Empty - Namespace to delete is not empty.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IcebergErrorResponse'
              examples:
                NamespaceNotEmptyExample:
                  $ref: '#/components/examples/NamespaceNotEmptyError'
        419:
          $ref: '#/components/responses/AuthenticationTimeoutResponse'
        503:
          $ref: '#/components/responses/ServiceUnavailableResponse'
        5XX:
          $ref: '#/components/responses/ServerErrorResponse'
      description: Drop a namespace from the catalog. By default, the namespace needs to be empty. You can however set `recursive=true` which will delete all tables, views and namespaces under this namespace. The namespace itself will also be deleted. If the warehouse containing the namespace is configured with a soft-deletion profile, the `force` flag has to be provided. The deletion will not be a soft-deletion. Every table, view and namespace will be gone as soon as this call returns. Depending on whether the `purge` flag was set to true, the data will be queued for deletion too. Any pending `tabular_expiration` will be cancelled. If there is a running `tabular_expiration`, this call will fail with a `409 Conflict` error.
  /v1/{prefix}/namespaces/{namespace}/properties:
    parameters:
    - $ref: '#/components/parameters/prefix'
    - $ref: '#/components/parameters/namespace'
    post:
      tags:
      - Catalog API
      summary: Set or remove properties on a namespace
      operationId: updateProperties
      parameters:
      - $ref: '#/components/parameters/idempotency-key'
      description: 'Set and/or remove properties on a namespace. The request body specifies a list of properties to remove and a map of key value pairs to update.

        Properties that are not in the request are not modified or removed by this call.

        Server implementations are not required to support namespace properties.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateNamespacePropertiesRequest'
            examples:
              UpdateAndRemoveProperties:
                $ref: '#/components/examples/UpdateAndRemoveNamespacePropertiesRequest'
      responses:
        200:
          $ref: '#/components/responses/UpdateNamespacePropertiesResponse'
        400:
          $ref: '#/components/responses/BadRequestErrorResponse'
        401:
          $ref: '#/components/responses/UnauthorizedResponse'
        403:
          $ref: '#/components/responses/ForbiddenResponse'
        404:
          description: Not Found - Namespace not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IcebergErrorResponse'
              examples:
                NamespaceNotFound:
                  $ref: '#/components/examples/NoSuchNamespaceError'
        406:
          $ref: '#/components/responses/UnsupportedOperationResponse'
        422:
          description: Unprocessable Entity - A property key was included in both `removals` and `updates`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IcebergErrorResponse'
              examples:
                UnprocessableEntityDuplicateKey:
                  $ref: '#/components/examples/UnprocessableEntityDuplicateKey'
        419:
          $ref: '#/components/responses/AuthenticationTimeoutResponse'
        503:
          $ref: '#/components/responses/ServiceUnavailableResponse'
        5XX:
          $ref: '#/components/responses/ServerErrorResponse'
  /v1/{prefix}/namespaces/{namespace}/tables:
    parameters:
    - $ref: '#/components/parameters/prefix'
    - $ref: '#/components/parameters/namespace'
    get:
      tags:
      - Catalog API
      summary: List all table identifiers underneath a given namespace
      description: Return all table identifiers under this namespace
      operationId: listTables
      parameters:
      - $ref: '#/components/parameters/page-token'
      - $ref: '#/components/parameters/page-size'
      - name: returnUuids
        in: query
        description: If true, include the `table-uuids` field in the response
        required: false
        schema:
          type: boolean
          default: false
      - name: returnProtectionStatus
        in: query
        description: If true, include the `protection-status` field in the response
        required: false
        schema:
          type: boolean
          default: false
      responses:
        200:
          $ref: '#/components/responses/ListTablesResponse'
        400:
          $ref: '#/components/responses/BadRequestErrorResponse'
        401:
          $ref: '#/components/responses/UnauthorizedResponse'
        403:
          $ref: '#/components/responses/ForbiddenResponse'
        404:
          description: Not Found - The namespace specified does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IcebergErrorResponse'
              examples:
                NamespaceNotFound:
                  $ref: '#/components/examples/NoSuchNamespaceError'
        419:
          $ref: '#/components/responses/AuthenticationTimeoutResponse'
        503:
          $ref: '#/components/responses/ServiceUnavailableResponse'
        5XX:
          $ref: '#/components/responses/ServerErrorResponse'
    post:
      tags:
      - Catalog API
      summary: Create a table in the given namespace
      description: 'Create a table or start a create transaction, like atomic CTAS.


        If `stage-create` is false, the table is created immediately.


        If `stage-create` is true, the table is not created, but table metadata is initialized and returned. The service should prepare as needed for a commit to the table commit endpoint to complete the create transaction. The client uses the returned metadata to begin a transaction. To commit the transaction, the client sends all create and subsequent changes to the table commit route. Changes from the table create operation include changes like AddSchemaUpdate and SetCurrentSchemaUpdate that set the initial table state.'
      operationId: createTable
      parameters:
      - $ref: '#/components/parameters/data-access'
      - $ref: '#/components/parameters/idempotency-key'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTableRequest'
      responses:
        200:
          $ref: '#/components/responses/CreateTableResponse'
        400:
          $ref: '#/components/responses/BadRequestErrorResponse'
        401:
          $ref: '#/components/responses/UnauthorizedResponse'
        403:
          $ref: '#/components/responses/ForbiddenResponse'
        404:
          description: Not Found - The namespace specified does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IcebergErrorResponse'
              examples:
                NamespaceNotFound:
                  $ref: '#/components/examples/NoSuchNamespaceError'
        409:
          description: Conflict - The table already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IcebergErrorResponse'
              examples:
                TableAlreadyExists:
                  $ref: '#/components/examples/TableAlreadyExistsError'
        419:
          $ref: '#/components/responses/AuthenticationTimeoutResponse'
        503:
          $ref: '#/components/responses/ServiceUnavailableResponse'
        5XX:
          $ref: '#/components/responses/ServerErrorResponse'
  /v1/{prefix}/namespaces/{namespace}/tables/{table}/plan:
    parameters:
    - $ref: '#/components/parameters/prefix'
    - $ref: '#/components/parameters/namespace'
    - $ref: '#/components/parameters/table'
    - $ref: '#/components/parameters/data-access'
    post:
      tags:
      - Catalog API
      summary: Submit a scan for planning
      description: "Submits a scan for server-side planning.\nPoint-in-time scans are planned by passing snapshot-id to identify the table snapshot to scan. Incremental scans are planned by passing both start-snapshot-id and end-snapshot-id. Requests that include both point in time config properties and incremental config properties are invalid. If the request does not include either incremental or point-in-time config properties, scan planning should produce a point-in-time scan of the latest snapshot in the table's main branch.\nResponses must include a valid status listed below. A \"cancelled\" status is considered invalid for this endpoint.\n- When \"completed\" the planning operation has produced plan tasks and\n\n  file scan tasks that must be returned in the response (not fetched\n  later by calling fetchPlanningResult)\n\n- When \"submitted\" the response must include a plan-id used to poll\n\n  fetchPlanningResult to fetch the planning result when it is ready\n\n- When \"failed\" the response must be a valid error response\nThe response for a \"completed\" planning operation includes two types of tasks (file scan tasks and plan tasks) and both may be included in the response. Tasks must not be included for any other response status.\nResponses that include a plan-id indicate that the service is holding state or performing work for the client.\n- Clients should use the plan-id to fetch results from\n\n  fetchPlanningResult when the response status is \"submitted\"\n\n- Clients should inform the service if planning results are no longer\n\n  needed by calling cancelPlanning. Cancellation is not necessary after\n  fetchScanTasks has been used to fetch scan tasks for each plan task.\n"
      operationId: planTableScan
      parameters:
      - $ref: '#/components/parameters/idempotency-key'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlanTableScanRequest'
      responses:
        200:
          $ref: '#/components/responses/PlanTableScanResponse'
        400:
          $ref: '#/components/responses/BadRequestErrorResponse'
        401:
          $ref: '#/components/responses/UnauthorizedResponse'
        403:
          $ref: '#/components/responses/ForbiddenResponse'
        404:
          description: Not Found - NoSuchTableException, the table does not exist - NoSuchNamespaceException, the namespace does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IcebergErrorResponse'
              examples:
                TableDoesNotExist:
                  $ref: '#/components/examples/NoSuchTableError'
                NamespaceDoesNotExist:
                  $ref: '#/components/examples/NoSuchNamespaceError'
        406:
          $ref: '#/components/responses/UnsupportedOperationResponse'
        419:
          $ref: '#/components/responses/AuthenticationTimeoutResponse'
        503:
          $ref: '#/components/responses/ServiceUnavailableResponse'
        5XX:
          $ref: '#/components/responses/ServerErrorResponse'
  /v1/{prefix}/namespaces/{namespace}/tables/{table}/plan/{plan-id}:
    parameters:
    - $ref: '#/components/parameters/prefix'
    - $ref: '#/components/parameters/namespace'
    - $ref: '#/components/parameters/table'
    - $ref: '#/components/parameters/plan-id'
    - $ref: '#/components/parameters/data-access'
    get:
      tags:
      - Catalog API
      summary: Fetches the result of scan planning for a plan-id
      operationId: fetchPlanningResult
      description: "Fetches the result of scan planning for a plan-id.\nResponses must include a valid status\n- When \"completed\" the planning operation has produced plan-tasks and\n\n  file-scan-tasks that must be returned in the response\n\n- When \"submitted\" the planning operation has not completed; the client\n\n  should wait to call this endpoint again to fetch a completed response\n\n- When \"failed\" the response must be a valid error response\n- When \"cancelled\" the plan-id is invalid and should be discarded\nThe response for a \"completed\" planning operation includes two types of tasks (file scan tasks and plan tasks) and both may be included in the response. Tasks must not be included for any other response status.\n"
      responses:
        200:
          $ref: '#/components/responses/FetchPlanningResultResponse'
        400:
          $ref: '#/components/responses/BadRequestErrorResponse'
        401:
          $ref: '#/components/responses/UnauthorizedResponse'
        403:
          $ref: '#/components/responses/ForbiddenResponse'
        404:
          description: Not Found - NoSuchPlanIdException, the plan-id does not exist - NoSuchTableException, the table does not exist - NoSuchNamespaceException, the namespace does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IcebergErrorResponse'
              examples:
                PlanIdDoesNotExist:
                  $ref: '#/components/examples/NoSuchPlanIdError'
                TableDoesNotExist:
                  $ref: '#/components/examples/NoSuchTableError'
                NamespaceDoesNotExist:
                  $ref: '#/components/examples/NoSuchNamespaceError'
        419:
          $ref: '#/components/responses/AuthenticationTimeoutResponse'
        503:
          $ref: '#/components/responses/ServiceUnavailableResponse'
        5XX:
          $ref: '#/components/responses/ServerErrorResponse'
    delete:
      tags:
      - Catalog API
      summary: Cancels scan planning for a plan-id
      operationId: cancelPlanning
      parameters:
      - $ref: '#/components/parameters/idempotency-key'
      description: "Cancels scan planning for a plan-id.\nThis notifies the service that it can release resources held for the scan. Clients should cancel scans that are no longer needed, either while the plan-id returns a \"submitted\" status or while there are remaining plan tasks that have not been fetched.\nCancellation is not necessary when\n- Scan tasks for each plan task have been fetched using fetchScanTasks\n- A plan-id has produced a \"failed\" or \"cancelled\" status from\n\n  planTableScan or fetchPlanningResult\n"
      responses:
        204:
          description: Success, no content
        400:
          $ref: '#/components/responses/BadRequestErrorResponse'
        401:
          $ref: '#/components/responses/UnauthorizedResponse'
        403:
          $ref: '#/components/responses/ForbiddenResponse'
        404:
          description: Not Found - NoSuchPlanIdException, the plan-id does not exist - NoSuchTableException, the table does not exist - NoSuchNamespaceException, the namespace does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IcebergErrorResponse'
              examples:
                PlanIdDoesNotExist:
                  $ref: '#/components/examples/NoSuchPlanIdError'
                TableDoesNotExist:
                  $ref: '#/components/examples/NoSuchTableError'
                NamespaceDoesNotExist:
                  $ref: '#/components/examples/NoSuchNamespaceError'
        419:
          $ref: '#/components/responses/AuthenticationTimeoutResponse'
        503:
          $ref: '#/components/responses/ServiceUnavailableResponse'
        5XX:
          $ref: '#/components/responses/ServerErrorResponse'
  /v1/{prefix}/namespaces/{namespace}/tables/{table}/tasks:
    parameters:
    - $ref: '#/components/parameters/prefix'
    - $ref: '#/components/parameters/namespace'
    - $ref: '#/components/parameters/table'
    post:
      tags:
      - Catalog API
      summary: Fetches result tasks for a plan task
      operationId: fetchScanTasks
      parameters:
      - $ref: '#/components/parameters/idempotency-key'
      description: Fetches result tasks for a plan task.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FetchScanTasksRequest'
      responses:
        200:
          $ref: '#/components/responses/FetchScanTasksResponse'
        400:
          $ref: '#/components/responses/BadRequestErrorResponse'
        401:
          $ref: '#/components/responses/UnauthorizedResponse'
        403:
          $ref: '#/components/responses/ForbiddenResponse'
        404:
          description: Not Found - NoSuchPlanTaskException, the plan-task does not exist - NoSuchTableException, the table does not exist - NoSuchNamespaceException, the namespace does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IcebergErrorResponse'
              examples:
                PlanTaskDoesNotExist:
                  $ref: '#/components/examples/NoSuchPlanTaskError'
                TableDoesNotExist:
                  $ref: '#/components/examples/NoSuchTableError'
                NamespaceDoesNotExist:
                  $ref: '#/components/examples/NoSuchNamespaceError'
        419:
          $ref: '#/components/responses/AuthenticationTimeoutResponse'
        503:
          $ref: '#/components/responses/ServiceUnavailableResponse'
        5XX:
          $ref: '#/components/responses/ServerErrorResponse'
  /v1/{prefix}/namespaces/{namespace}/register:
    parameters:
    - $ref: '#/components/parameters/prefix'
    - $ref: '#/components/parameters/namespace'
    post:
      tags:
      - Catalog API
      summary: Register a table in the given namespace using given metadata file location
      parameters:
      - $ref: '#/components/parameters/data-access'
      - $ref: '#/components/parameters/idempotency-key'
      description: Register a table using given metadata file location.
      operationId: registerTable
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterTableRequest'
      responses:
        200:
          $ref: '#/components/responses/LoadTableResponse'
        400:
          $ref: '#/components/responses/BadRequestErrorResponse'
        401:
          $ref: '#/components/responses/UnauthorizedResponse'
        403:
          $ref: '#/components/responses/ForbiddenResponse'
        404:
          description: Not Found - The namespace specified does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IcebergErrorResponse'
              examples:
                NamespaceNotFound:
                  $ref: '#/components/examples/NoSuchNamespaceError'
        409:
          description: Conflict - The table already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IcebergErrorResponse'
              examples:
                TableAlreadyExists:
                  $ref: '#/components/examples/TableAlreadyExistsError'
        419:
          $ref: '#/components/responses/AuthenticationTimeoutResponse'
        503:
          $ref: '#/components/responses/ServiceUnavailableResponse'
        5XX:
          $ref: '#/components/responses/ServerErrorResponse'
  /v1/{prefix}/namespaces/{namespace}/tables/{table}:
    parameters:
    - $ref: '#/components/parameters/prefix'
    - $ref: '#/components/parameters/namespace'
    - $ref: '#/components/parameters/table'
    get:
      tags:
      - Catalog API
      summary: Load a table from the catalog
      operationId: loadTable
      description: 'Load a table from the catalog.


        The response contains both configuration and table metadata. The configuration, if non-empty is used as additional configuration for the table that overrides catalog configuration. For example, this configuration may change the FileIO implementation to be used for the table.


        The response also contains the table''s full metadata, matching the table metadata JSON file.


        The catalog configuration may contain credentials that should be used for subsequent requests for the table. The configuration key "token" is used to pass an access token to be used as a bearer token for table requests. Otherwise, a token may be passed using a RFC 8693 token type as a configuration key. For example, "urn:ietf:params:oauth:token-type:jwt=<JWT-token>".'
      parameters:
      - $ref: '#/components/parameters/data-access'
      - name: If-None-Match
        in: header
        description: An optional header that allows the server to return 304 (Not Modified) if the metadata is current. The content is the value of the ETag received in a CreateTableResponse, LoadTableResponse or CommitTableResponse.
        required: false
        schema:
          type: string
      - in: query
        name: snapshots
        description: 'The snapshots to return in the body of the metadata. Setting the value to `all` would return the full set of snapshots currently valid for the table. Setting the value to `refs` would load all snapshots referenced by branches or tags.

          Default if no param is provided is `all`.'
        required: false
        schema:
          type: string
          enum:
          - all
          - refs
      - $ref: '#/components/parameters/referenced-by'
      responses:
        200:
          $ref: '#/components/responses/LoadTableResponse'
        304:
          description: Not Modified - Based on the content of the 'If-None-Match' header the table metadata has not changed since.
        400:
       

# --- truncated at 32 KB (141 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/lakekeeper/refs/heads/main/openapi/lakekeeper-catalog-api-api-openapi.yml