Lakekeeper Tasks API

openapi: 3.2.0
info:
  title: Lakekeeper Tasks API
  version: 0.0.0
  description: 'Operations tagged tasks across 2 of this provider''s published API definitions: lakekeeper-management-api-openapi.yml, lakekeeper-management-plus-api-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: '{scheme}://{host}{basePath}'
  description: Lakekeeper Management API
  variables:
    basePath:
      default: ''
      description: Optional path prefix (starting with '/') to be prepended to all routes
    host:
      default: localhost
      description: The host (and optional port) for the specified server
    scheme:
      default: https
      description: The scheme of the URI, either http or https
security:
- bearerAuth: []
tags:
- name: tasks
  description: View & Manage Tasks
paths:
  /management/v1/project/task-queue/task_log_cleanup/config:
    get:
      tags:
      - tasks
      summary: Get the configuration for a Project-level Task Queue.
      description: These configurations are global per project and shared across all instances of this kind of task.
      operationId: get_project_task_queue_config_task_log_cleanup
      parameters:
      - name: x-project-id
        in: header
        description: Project ID (optional; falls back to the default project if not provided)
        required: false
        schema:
          type:
          - string
          - 'null'
      responses:
        '200':
          description: ''
          headers:
            x-request-id:
              schema:
                type: string
                format: uuid
              description: Request identifier, add this to your bug reports.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetTaskLogCleanupConfig'
        4XX:
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IcebergErrorResponse'
    post:
      tags:
      - tasks
      summary: Set the configuration for a Project-level Task Queue.
      description: These configurations are global per project and shared across all instances of this kind of task.
      operationId: set_project_task_queue_config_task_log_cleanup
      parameters:
      - name: x-project-id
        in: header
        description: Project ID (optional; falls back to the default project if not provided)
        required: false
        schema:
          type:
          - string
          - 'null'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetTaskLogCleanupConfig'
        required: true
      responses:
        '204':
          description: Project-level Task queue config set successfully
        4XX:
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IcebergErrorResponse'
    servers:
    - url: '{scheme}://{host}{basePath}'
      description: Lakekeeper Management API
      variables:
        basePath:
          default: ''
          description: Optional path prefix (starting with '/') to be prepended to all routes
        host:
          default: localhost
          description: The host (and optional port) for the specified server
        scheme:
          default: https
          description: The scheme of the URI, either http or https
  /management/v1/project/task/by-id/{task_id}:
    get:
      tags:
      - tasks
      summary: Get Details about a specific Project-level task by its ID.
      operationId: get_project_task_details
      parameters:
      - name: task_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: numAttempts
        in: query
        description: 'Number of attempts to retrieve (default: 5)'
        required: false
        schema:
          type:
          - integer
          - 'null'
          format: int32
          default: 5
          minimum: 0
      - name: x-project-id
        in: header
        description: Project ID (optional; falls back to the default project if not provided)
        required: false
        schema:
          type:
          - string
          - 'null'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetProjectTaskDetailsResponse'
        4XX:
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IcebergErrorResponse'
    servers:
    - url: '{scheme}://{host}{basePath}'
      description: Lakekeeper Management API
      variables:
        basePath:
          default: ''
          description: Optional path prefix (starting with '/') to be prepended to all routes
        host:
          default: localhost
          description: The host (and optional port) for the specified server
        scheme:
          default: https
          description: The scheme of the URI, either http or https
  /management/v1/project/task/control:
    post:
      tags:
      - tasks
      summary: Control a set of Project-level tasks by their IDs (e.g., cancel, request stop, run now)
      description: Accepts at most 100 task IDs in one request.
      operationId: control_project_tasks
      parameters:
      - name: x-project-id
        in: header
        description: Project ID (optional; falls back to the default project if not provided)
        required: false
        schema:
          type:
          - string
          - 'null'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ControlTasksRequest'
        required: true
      responses:
        '204':
          description: All requested actions were successful
        4XX:
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IcebergErrorResponse'
    servers:
    - url: '{scheme}://{host}{basePath}'
      description: Lakekeeper Management API
      variables:
        basePath:
          default: ''
          description: Optional path prefix (starting with '/') to be prepended to all routes
        host:
          default: localhost
          description: The host (and optional port) for the specified server
        scheme:
          default: https
          description: The scheme of the URI, either http or https
  /management/v1/project/task/list:
    post:
      tags:
      - tasks
      summary: List active and historic Project-level tasks.
      operationId: list_project_tasks
      parameters:
      - name: x-project-id
        in: header
        description: Project ID (optional; falls back to the default project if not provided)
        required: false
        schema:
          type:
          - string
          - 'null'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListProjectTasksRequest'
        required: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListProjectTasksResponse'
        4XX:
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IcebergErrorResponse'
    servers:
    - url: '{scheme}://{host}{basePath}'
      description: Lakekeeper Management API
      variables:
        basePath:
          default: ''
          description: Optional path prefix (starting with '/') to be prepended to all routes
        host:
          default: localhost
          description: The host (and optional port) for the specified server
        scheme:
          default: https
          description: The scheme of the URI, either http or https
  /management/v1/warehouse/{warehouse_id}/task-queue/tabular_expiration/config:
    get:
      tags:
      - tasks
      summary: Get the configuration for a Task Queue.
      description: These configurations are global per warehouse and shared across all instances of this kind of task.
      operationId: get_task_queue_config_tabular_expiration
      parameters:
      - name: warehouse_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: ''
          headers:
            x-request-id:
              schema:
                type: string
                format: uuid
              description: Request identifier, add this to your bug reports.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetTabularExpirationQueueConfig'
        4XX:
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IcebergErrorResponse'
    post:
      tags:
      - tasks
      summary: Set the configuration for a Task Queue.
      description: These configurations are global per warehouse and shared across all instances of this kind of task.
      operationId: set_task_queue_config_tabular_expiration
      parameters:
      - name: warehouse_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetTabularExpirationQueueConfig'
        required: true
      responses:
        '204':
          description: Task queue config set successfully
        4XX:
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IcebergErrorResponse'
    servers:
    - url: '{scheme}://{host}{basePath}'
      description: Lakekeeper Management API
      variables:
        basePath:
          default: ''
          description: Optional path prefix (starting with '/') to be prepended to all routes
        host:
          default: localhost
          description: The host (and optional port) for the specified server
        scheme:
          default: https
          description: The scheme of the URI, either http or https
  /management/v1/warehouse/{warehouse_id}/task-queue/tabular_purge/config:
    get:
      tags:
      - tasks
      summary: Get the configuration for a Task Queue.
      description: These configurations are global per warehouse and shared across all instances of this kind of task.
      operationId: get_task_queue_config_tabular_purge
      parameters:
      - name: warehouse_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: ''
          headers:
            x-request-id:
              schema:
                type: string
                format: uuid
              description: Request identifier, add this to your bug reports.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetPurgeQueueConfig'
        4XX:
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IcebergErrorResponse'
    post:
      tags:
      - tasks
      summary: Set the configuration for a Task Queue.
      description: These configurations are global per warehouse and shared across all instances of this kind of task.
      operationId: set_task_queue_config_tabular_purge
      parameters:
      - name: warehouse_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetPurgeQueueConfig'
        required: true
      responses:
        '204':
          description: Task queue config set successfully
        4XX:
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IcebergErrorResponse'
    servers:
    - url: '{scheme}://{host}{basePath}'
      description: Lakekeeper Management API
      variables:
        basePath:
          default: ''
          description: Optional path prefix (starting with '/') to be prepended to all routes
        host:
          default: localhost
          description: The host (and optional port) for the specified server
        scheme:
          default: https
          description: The scheme of the URI, either http or https
  /management/v1/warehouse/{warehouse_id}/task/by-id/{task_id}:
    get:
      tags:
      - tasks
      summary: Get Details about a specific task by its ID.
      operationId: get_task_details
      parameters:
      - name: warehouse_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: task_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: numAttempts
        in: query
        description: 'Number of attempts to retrieve (default: 5)'
        required: false
        schema:
          type:
          - integer
          - 'null'
          format: int32
          default: 5
          minimum: 0
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetTaskDetailsResponse'
        4XX:
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IcebergErrorResponse'
    servers:
    - url: '{scheme}://{host}{basePath}'
      description: Lakekeeper Management API
      variables:
        basePath:
          default: ''
          description: Optional path prefix (starting with '/') to be prepended to all routes
        host:
          default: localhost
          description: The host (and optional port) for the specified server
        scheme:
          default: https
          description: The scheme of the URI, either http or https
  /management/v1/warehouse/{warehouse_id}/task/control:
    post:
      tags:
      - tasks
      summary: Control a set of tasks by their IDs (e.g., cancel, request stop, run now)
      description: Accepts at most 100 task IDs in one request.
      operationId: control_tasks
      parameters:
      - name: warehouse_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ControlTasksRequest'
        required: true
      responses:
        '204':
          description: All requested actions were successful
        4XX:
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IcebergErrorResponse'
    servers:
    - url: '{scheme}://{host}{basePath}'
      description: Lakekeeper Management API
      variables:
        basePath:
          default: ''
          description: Optional path prefix (starting with '/') to be prepended to all routes
        host:
          default: localhost
          description: The host (and optional port) for the specified server
        scheme:
          default: https
          description: The scheme of the URI, either http or https
  /management/v1/warehouse/{warehouse_id}/task/list:
    post:
      tags:
      - tasks
      summary: List active and historic tasks.
      operationId: list_tasks
      parameters:
      - name: warehouse_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListTasksRequest'
        required: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListTasksResponse'
        4XX:
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IcebergErrorResponse'
    servers:
    - url: '{scheme}://{host}{basePath}'
      description: Lakekeeper Management API
      variables:
        basePath:
          default: ''
          description: Optional path prefix (starting with '/') to be prepended to all routes
        host:
          default: localhost
          description: The host (and optional port) for the specified server
        scheme:
          default: https
          description: The scheme of the URI, either http or https
  /management/v1/warehouse/{warehouse_id}/task-queue/expire_snapshots/config:
    get:
      tags:
      - tasks
      summary: Get the configuration for a Task Queue.
      description: These configurations are global per warehouse and shared across all instances of this kind of task.
      operationId: get_task_queue_config_expire_snapshots
      parameters:
      - name: warehouse_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: ''
          headers:
            x-request-id:
              schema:
                type: string
                format: uuid
              description: Request identifier, add this to your bug reports.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetExpireSnapshotsQueueConfig'
        4XX:
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IcebergErrorResponse'
    post:
      tags:
      - tasks
      summary: Set the configuration for a Task Queue.
      description: These configurations are global per warehouse and shared across all instances of this kind of task.
      operationId: set_task_queue_config_expire_snapshots
      parameters:
      - name: warehouse_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetExpireSnapshotsQueueConfig'
        required: true
      responses:
        '204':
          description: Task queue config set successfully
        4XX:
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IcebergErrorResponse'
    servers:
    - url: '{scheme}://{host}{basePath}'
      description: Lakekeeper Management API
      variables:
        basePath:
          default: ''
          description: Optional path prefix (starting with '/') to be prepended to all routes
        host:
          default: localhost
          description: The host (and optional port) for the specified server
        scheme:
          default: https
          description: The scheme of the URI, either http or https
  /management/v1/warehouse/{warehouse_id}/task-queue/expire_snapshots/schedule:
    post:
      tags:
      - tasks
      summary: Schedule a task for an entity.
      description: 'Pre-checks run against the warehouse config and target entity

        properties before the task is enqueued. A failure surfaces as `400`

        with a specific error code (see the operator guide for the full set

        of pre-check codes).


        When a task is already active for the same (warehouse, entity,

        queue) triple, the call returns `409 TaskAlreadyActive` with the

        existing `task-id` in the body — chain to `POST /task/control`

        with `run-now` or `run-at` to retime it without an extra

        `task/list` round-trip.'
      operationId: schedule_task_expire_snapshots
      parameters:
      - name: warehouse_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScheduleExpireSnapshotsTaskRequest'
        required: true
      responses:
        '200':
          description: Task scheduled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScheduleTaskResponse'
        '400':
          description: Pre-check failed (e.g. scheduling disabled at the warehouse, entity opted out, unsupported entity type) or the request violates a shape limit (e.g. scheduled-for too far in the future).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IcebergErrorResponse'
        '404':
          description: Target entity not found in this warehouse.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IcebergErrorResponse'
        '409':
          description: A task is already active for this (warehouse, entity, queue). The error message includes the existing task-id; retime or cancel via POST /task/control.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IcebergErrorResponse'
        4XX:
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IcebergErrorResponse'
    servers:
    - url: '{scheme}://{host}{basePath}'
      description: Lakekeeper Management API
      variables:
        basePath:
          default: ''
          description: Optional path prefix (starting with '/') to be prepended to all routes
        host:
          default: localhost
          description: The host (and optional port) for the specified server
        scheme:
          default: https
          description: The scheme of the URI, either http or https
  /management/v1/warehouse/{warehouse_id}/task-queue/remove_orphan_files/config:
    get:
      tags:
      - tasks
      summary: Get the configuration for a Task Queue.
      description: These configurations are global per warehouse and shared across all instances of this kind of task.
      operationId: get_task_queue_config_remove_orphan_files
      parameters:
      - name: warehouse_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: ''
          headers:
            x-request-id:
              schema:
                type: string
                format: uuid
              description: Request identifier, add this to your bug reports.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetRemoveOrphanFilesQueueConfig'
        4XX:
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IcebergErrorResponse'
    post:
      tags:
      - tasks
      summary: Set the configuration for a Task Queue.
      description: These configurations are global per warehouse and shared across all instances of this kind of task.
      operationId: set_task_queue_config_remove_orphan_files
      parameters:
      - name: warehouse_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetRemoveOrphanFilesQueueConfig'
        required: true
      responses:
        '204':
          description: Task queue config set successfully
        4XX:
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IcebergErrorResponse'
    servers:
    - url: '{scheme}://{host}{basePath}'
      description: Lakekeeper Management API
      variables:
        basePath:
          default: ''
          description: Optional path prefix (starting with '/') to be prepended to all routes
        host:
          default: localhost
          description: The host (and optional port) for the specified server
        scheme:
          default: https
          description: The scheme of the URI, either http or https
  /management/v1/warehouse/{warehouse_id}/task-queue/remove_orphan_files/schedule:
    post:
      tags:
      - tasks
      summary: Schedule a task for an entity.
      description: 'Pre-checks run against the warehouse config and target entity

        properties before the task is enqueued. A failure surfaces as `400`

        with a specific error code (see the operator guide for the full set

        of pre-check codes).


        When a task is already active for the same (warehouse, entity,

        queue) triple, the call returns `409 TaskAlreadyActive` with the

        existing `task-id` in the body — chain to `POST /task/control`

        with `run-now` or `run-at` to retime it without an extra

        `task/list` round-trip.'
      operationId: schedule_task_remove_orphan_files
      parameters:
      - name: warehouse_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScheduleRemoveOrphanFilesTaskRequest'
        required: true
      responses:
        '200':
          description: Task scheduled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScheduleTaskResponse'
        '400':
          description: Pre-check failed (e.g. scheduling disabled at the warehouse, entity opted out, unsupported entity type) or the request violates a shape limit (e.g. scheduled-for too far in the future).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IcebergErrorResponse'
        '404':
          description: Target entity not found in this warehouse.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IcebergErrorResponse'
        '409':
          description: A task is already active for this (warehouse, entity, queue). The error message includes the existing task-id; retime or cancel via POST /task/control.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IcebergErrorResponse'
        4XX:
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IcebergErrorResponse'
    servers:
    - url: '{scheme}://{host}{basePath}'
      description: Lakekeeper Management API
      variables:
        basePath:
          default: ''
          description: Optional path prefix (starting with '/') to be prepended to all routes
        host:
          default: localhost
          description: The host (and optional port) for the specified server
        scheme:
          default: https
          description: The scheme of the URI, either http or https
components:
  schemas:
    GetTaskLogCleanupConfig:
      type: object
      required:
      - queue-config
      properties:
        max-seconds-since-last-heartbeat:
          type:
          - integer
          - 'null'
          format: int64
        queue-config:
          $ref: '#/components/schemas/TaskLogCleanupConfig'
    TaskLogCleanupConfig:
      type: object
      properties:
        cleanup-period:
          type:
          - string
          - 'null'
          description: 'How often to run the cleanup task in ISO8601 duration format. Defaults to once a day (P1D).

            If a value below 1 day is provided, it will be set to the default of 1 day.'
          example: PT1H30M45.5S
        retention-period:
          type:
          - string
          - 'null'
          description: How long to retain task logs before deletion in ISO8601 duration format. Defaults to 90 days.
          example: PT1H30M45.5S
    SetTaskLogCleanupConfig:
      type: object
      required:
      - queue-config
      properties:
        max-seconds-since-last-heartbeat:
          type:
          - integer
          - 'null'
          format: int64
        queue-config:
          $ref: '#/components/schemas/TaskLogCleanupConfig'
    IcebergErrorResponse:
      type: object
      description: JSON wrapper for all error responses (non-2xx)
      required:
      - error
      properties:
        error:
          $ref: '#/components/schemas/ErrorModel'
    ListProjectTasksResponse:
      type: object
      required:
      - tasks
      properties:
        next-page-token:
          type:
          - string
          - 'null'
          description: Token for the next page of results
        tasks:
          type: array
          items:
            $ref: '#/components/schemas/ProjectTaskInfo'
          description: List of tasks
    WarehouseTaskEntityId:
      oneOf:
      - type: object
        required:
        - table-id
        - type
        properties:
          table-id:
            type: string
            format: uuid
          type:
            type: string
            enum:
            - table
      - type: object
        required:
        - view-id
        - type
        properties:
          type:
            type: string
            enum:
            - view
          view-id:
            type: string
            format: uuid
      - type: object
        required:
        - generic-table-id
        - type
        properties:
          generic-table-id:
            type: string
            format: uuid
          type:
            type: string
            enum:
            - generic-table
    TaskStatus:
      type: string
      enum:
      - RUNNING
      - SCHEDULED
      - STOPPING
      - CANCELLED
      - SUCCESS
      - FAILED
    ListTasksRequest:
      type: object
      properties:
        created-after:
          type:
          - string
          - 'null'
          format: date-time
          description: Filter tasks created after this timestamp
          example: 2025-12-31 23:59:59+00:00
        created-before:
          type:
          - string
          - 'null'
          format: date-time
          description: Filter tasks created before this timestamp
          example: 2025-12-31 23:59:59+00:00
        entities:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/WarehouseTaskEntityFilter'
          description: Filter by specific entity
        page-size:
          type:
          - integer
          - 'null'
          format: int64
          description: Number of results per page
        page-token:
          type:
          - string
          - 'null'
          description: 'Next page token, re-use the same request as for the original request,

            but set this to the `next_page_token` from the previous response.

            Stop iterating when no more items are returned in a page.'
        queue-name:
          type:
          - array
          - 'null'
          items:
            type: string
          description: Filter by one or more queue names
        status:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/TaskStatus'
          description: Filter by task status
    GetProjectTaskDetailsResponse:
      allOf:
      - $ref: '#/components/schemas/ProjectTaskInfo'
        description: Most recent task information
      - type: object
        required:
        - task-data
        - attempts
        properties:
          attempts:
            type: array
            items:
              $ref: '#/components/schemas/TaskAttempt'
            description: History of past attempts
          execution-details:
            type:
            - object
            - 'null'
            description: Execution details for the current attempt
          message:
            type:
            - string
            - 'null'
            descripti

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