openapi: 3.0.0
info:
  title: Task
  version: 2.0.0
  description: >
    A **Task** is an operation the platform runs in the background instead of
    during the request,

    because it is too long to complete inline — for example synchronising the
    people of a project

    from a CSV file.


    Each task records the `handler` that performs the work, the `user_id` who
    started it, the

    `request` it was given and the `response` it produced.


    The `status` follows this lifecycle:

    - `TODO`: queued, not started yet

    - `PENDING`: waiting on an external condition

    - `PROCESSING`: running

    - `DONE`: completed successfully — the outcome is in `response`

    - `FAILED`: stopped with an error — the reason is in `response`


    Use this API to:

    - Follow an operation you started, by polling its status

    - Read the result of a completed task

    - Find the tasks started by a user (filter by `user_id`)
servers:
  - url: http://service.4hse.com/
security:
  - OAuth2: []
  - AccessToken: []
paths:
  /v2/task/index:
    post:
      summary: index
      operationId: indexTask
      tags:
        - Tasks
      description: |
        Returns a paginated and filterable list of tasks.
        Use POST to allow complex filters via JSON payload.
      requestBody:
        description: Parameters for searching tasks
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TaskIndexParams"
            example:
              filter:
                handler: ImportHandler
                status: pending
              per-page: 10
              page: 1
              sort: created_at
      responses:
        "200":
          description: List of tasks
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Task"
              example:
                task_id: task-1
                handler: ImportHandler
                user_id: user-1
                status: pending
                created_at: 2024-01-01
                updated_at: 2024-01-02
          headers:
            X-Pagination-Current-Page:
              schema:
                type: integer
              description: Current page
            X-Pagination-Page-Count:
              schema:
                type: integer
              description: Total number of pages
            X-Pagination-Per-Page:
              schema:
                type: integer
              description: Number of items per page
            X-Pagination-Total-Count:
              schema:
                type: integer
              description: Total number of items
  /v2/task/create:
    post:
      summary: create
      operationId: createTask
      tags:
        - Tasks
      description: |
        Create a new task by providing the required details.
      requestBody:
        description: Task object to be created
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Task"
            example:
              handler: ExportHandler
              user_id: user-2
              status: pending
      responses:
        "201":
          description: Task created successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Task"
              example:
                task_id: task-2
                handler: ExportHandler
                user_id: user-2
                status: pending
  /v2/task/view/{id}:
    get:
      summary: view
      operationId: viewTask
      tags:
        - Tasks
      description: |
        Retrieve a task by its unique ID.
      parameters:
        - name: id
          in: path
          description: ID of the task to retrieve
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Task found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Task"
              example:
                task_id: task-1
                handler: ImportHandler
                user_id: user-1
                status: pending
                created_at: 2024-01-01
                updated_at: 2024-01-02
        "404":
          description: Task not found
  /v2/task/delete/{id}:
    delete:
      summary: delete
      operationId: deleteTask
      tags:
        - Tasks
      description: |
        Delete a task by its unique ID.
        If force=true, all related entities will also be deleted.
      parameters:
        - name: id
          in: path
          description: ID of the task to delete
          required: true
          schema:
            type: string
            format: uuid
        - name: force
          in: query
          description: Force the deletion of the entity and all related entities
          schema:
            type: boolean
            default: false
      responses:
        "204":
          description: Task deleted successfully
        "400":
          description: If force=false, the operation is interrupted and the list of
            connected entities that will be deleted in case of confirmation
            (force=true) is returned
  /v2/task/update/{id}:
    put:
      summary: update
      operationId: updateTask
      tags:
        - Tasks
      description: |
        Update an existing task by its unique ID.
      parameters:
        - name: id
          in: path
          description: ID of the task to update
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        description: Task object with updated data
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Task"
            example:
              status: completed
      responses:
        "200":
          description: Task updated successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Task"
              example:
                task_id: task-1
                status: completed
        "404":
          description: Task not found
components:
  schemas:
    Task:
      type: object
      properties:
        task_id:
          type: string
          format: uuid
          description: The unique identifier for the task.
        handler:
          type: string
          description: The name of the handler assigned to the task.
        user_id:
          type: string
          description: The unique identifier for the user associated with the task.
        entity_id:
          type: string
          nullable: true
          description: The unique identifier for the entity associated with the task
            (optional).
        status:
          type: string
          description: The current status of the task (e.g., pending, completed, etc.).
        request:
          type: string
          nullable: true
          format: json
          description: The JSON request data related to the task.
        response:
          type: string
          nullable: true
          format: json
          description: The JSON response data related to the task.
        created_at:
          type: string
          format: date
          description: The timestamp when the task was created.
        updated_at:
          type: string
          format: date
          description: The timestamp when the task was last updated.
    ViewTask:
      $ref: "#/components/schemas/Task"
    TaskIndexParams:
      type: object
      properties:
        filter:
          $ref: "#/components/schemas/Task"
        per-page:
          type: integer
          minimum: 1
          default: 100
        page:
          type: integer
          minimum: 1
          default: 1
        sort:
          type: string
          description: Field to sort by. Prefix with minus for descending order (e.g.
            -created_at).
          enum:
            - status
            - created_at
            - updated_at
      example:
        filter:
          status: TODO
        per-page: 100
        page: 1
        sort: -created_at
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        password:
          tokenUrl: https://auth.4hse.com/realms/4hse/protocol/openid-connect/token
          scopes: {}
    AccessToken:
      type: apiKey
      in: query
      name: access-token
