openapi3.yaml

openapi: 3.0.3
info:
  title: Job Manager Service - API v1
  description: Job Manager Service API version 1
  version: 0.1.9
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
security: []
paths:
  /v1/jobs:
    get:
      operationId: findJobsV1
      parameters:
        - $ref: '#/components/parameters/jobNameQueryParam'
        - $ref: '#/components/parameters/fromDate'
        - $ref: '#/components/parameters/endDate'
        - $ref: '#/components/parameters/priority'
        - $ref: '#/components/parameters/includeStages'
      summary: Retrieve jobs matching criteria
      description: |
        Filter jobs by name, date range, priority. Optional stage inclusion.
        Returns empty array if no matches.
      tags:
        - jobs
      responses:
        '200':
          description: Successfully retrieved matching jobs
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/job'
        '400':
          description: Invalid query parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/badRequestResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/internalErrorsResponse'
    post:
      operationId: createJobV1
      summary: Create job
      description: |
        Create job with config and metadata. Initial status: PENDING.
      tags:
        - jobs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/createJobPayload'
            examples:
              simple_job:
                summary: Simple job with minimal configuration
                description: Basic job creation with default priority
                value:
                  name: data_processing
                  data:
                    input_path: /data/raw/batch_001
                    output_path: /data/processed/batch_001
                    format: parquet
              complex_job:
                summary: Complex job with full configuration
                description: Job with high priority and custom metadata
                value:
                  name: critical_analysis
                  data:
                    input_sources:
                      - /data/source1/*.csv
                      - /data/source2/*.json
                    transformations:
                      - type: filter
                        conditions:
                          - status = 'active'
                          - created_date > '2024-01-01'
                      - type: aggregate
                        group_by:
                          - region
                          - category
                        metrics:
                          - sum(revenue)
                          - count(transactions)
                    output_config:
                      format: delta
                      partitions:
                        - year
                        - month
                      compression: snappy
                  priority: VERY_HIGH
                  userMetadata:
                    department: analytics
                    owner: data-team@company.com
                    deadline: '2025-08-01T00:00:00.000Z'
                    cost_center: CC-12345
              job_with_tracing:
                summary: Job with explicit tracing context
                description: Job creation with provided distributed tracing context
                value:
                  name: traced_processing
                  data:
                    input_path: /data/traced/batch_001
                    output_path: /data/output/batch_001
                  traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
                  tracestate: rojo=00f067aa0ba902b7,congo=t61rcWkgMzE
      responses:
        '201':
          description: Job created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/job'
              examples:
                simple_job_response:
                  summary: Response for simple job creation
                  value:
                    id: 550e8400-e29b-41d4-a716-446655440000
                    name: data_processing
                    status: PENDING
                    percentage: 0
                    priority: MEDIUM
                    creationTime: '2025-07-27T10:30:00.000Z'
                    updateTime: '2025-07-27T10:30:00.000Z'
                    data:
                      input_path: /data/raw/batch_001
                      output_path: /data/processed/batch_001
                      format: parquet
                    userMetadata: {}
                    traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
                complex_job_response:
                  summary: Response for complex job creation
                  value:
                    id: 660f9511-f3ac-52e5-b827-557766551111
                    name: critical_analysis
                    status: PENDING
                    percentage: 0
                    priority: VERY_HIGH
                    creationTime: '2025-07-27T10:30:00.000Z'
                    updateTime: '2025-07-27T10:30:00.000Z'
                    data:
                      input_sources:
                        - /data/source1/*.csv
                        - /data/source2/*.json
                      transformations:
                        - type: filter
                          conditions:
                            - status = 'active'
                            - created_date > '2024-01-01'
                        - type: aggregate
                          group_by:
                            - region
                            - category
                          metrics:
                            - sum(revenue)
                            - count(transactions)
                      output_config:
                        format: delta
                        partitions:
                          - year
                          - month
                        compression: snappy
                    userMetadata:
                      department: analytics
                      owner: data-team@company.com
                      deadline: '2025-08-01T00:00:00.000Z'
                      cost_center: CC-12345
                    traceparent: 00-660f9511f3ac52e5b827557766551111-22b378cc5ca902b7-01
                    tracestate: analytics=dept123,priority=very_high
        '400':
          description: Invalid request, could not create job
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/badRequestResponse'
              examples:
                validation_error:
                  summary: Validation error
                  description: Request failed due to missing required fields
                  value:
                    message: >-
                      Validation failed: 'name' is required and must be a
                      non-empty string. 'data' is required and must be an
                      object.
                    code: VALIDATION_ERROR
                invalid_priority:
                  summary: Invalid priority value
                  value:
                    message: >-
                      Invalid priority value 'SUPER_HIGH'. Valid values are:
                      VERY_HIGH, HIGH, MEDIUM, LOW, VERY_LOW.
                    code: VALIDATION_ERROR
                malformed_data:
                  summary: Malformed request data
                  value:
                    message: >-
                      Invalid JSON format in request body. Expected object but
                      received array at line 1, column 1.
                    code: VALIDATION_ERROR
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/internalErrorsResponse'
  /v1/jobs/{jobId}:
    parameters:
      - $ref: '#/components/parameters/jobId'
    get:
      operationId: getJobByIdV1
      parameters:
        - $ref: '#/components/parameters/includeStages'
      summary: Retrieve a specific job by its ID
      description: >
        Fetches detailed information about a job using its unique identifier.

        Includes job configuration, status, metadata, and completion percentage.


        Optional inclusion of related stage data via the should_return_stages
        parameter,

        which allows clients to retrieve the complete job hierarchy in a single
        request.
      tags:
        - jobs
      responses:
        '200':
          description: Job data retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/job'
              examples:
                job_with_stages:
                  summary: Job with complete stage and task hierarchy
                  description: Full job details when should_return_stages=true
                  value:
                    id: 550e8400-e29b-41d4-a716-446655440000
                    name: ml_pipeline
                    status: IN_PROGRESS
                    percentage: 45
                    priority: HIGH
                    creationTime: '2025-07-27T08:00:00.000Z'
                    updateTime: '2025-07-27T10:30:00.000Z'
                    traceparent: 00-660f9511f3ac52e5b827557766551111-22b378cc5ca902b7-01
                    data:
                      model_type: random_forest
                      training_data: /data/ml/training_set.parquet
                      features:
                        - age
                        - income
                        - location
                        - purchase_history
                      target: churn_probability
                      hyperparameters:
                        n_estimators: 100
                        max_depth: 10
                        min_samples_split: 5
                    userMetadata:
                      experiment_id: EXP-2025-001
                      researcher: ml-team@company.com
                      budget: $5000
                    stages:
                      - id: dd301d64-69b2-4b49-ba26-fb2a87fa0150
                        type: data_preparation
                        status: COMPLETED
                        percentage: 100
                        jobId: 550e8400-e29b-41d4-a716-446655440000
                        order: 1
                        data:
                          validation_split: 0.2
                          preprocessing_steps:
                            - normalize
                            - encode_categorical
                        userMetadata: {}
                        summary:
                          pending: 0
                          inProgress: 0
                          completed: 5
                          failed: 0
                          created: 0
                          retried: 0
                          total: 5
                        traceparent: >-
                          00-550e8400e29b41d4a716446655440000-22b378cc5ca902b7-01
                      - id: 2d9b2481-ec1c-4efd-9350-f33bd79d51eb
                        type: model_training
                        status: IN_PROGRESS
                        percentage: 60
                        jobId: 550e8400-e29b-41d4-a716-446655440000
                        order: 2
                        data:
                          cross_validation_folds: 5
                          early_stopping: true
                        userMetadata: {}
                        summary:
                          pending: 1
                          inProgress: 2
                          completed: 2
                          failed: 0
                          created: 0
                          retried: 0
                          total: 5
                        traceparent: >-
                          00-550e8400e29b41d4a716446655440000-22b378cc5ca902b7-01
                      - id: 637c05f3-e0b0-4c26-a791-89308c58e316
                        type: model_evaluation
                        status: WAITING
                        percentage: 0
                        jobId: 550e8400-e29b-41d4-a716-446655440000
                        order: 3
                        data:
                          metrics:
                            - accuracy
                            - precision
                            - recall
                            - f1_score
                          validation_dataset: /data/ml/validation_set.parquet
                        userMetadata: {}
                        summary:
                          pending: 3
                          inProgress: 0
                          completed: 0
                          failed: 0
                          created: 0
                          retried: 0
                          total: 3
                        traceparent: >-
                          00-550e8400e29b41d4a716446655440000-22b378cc5ca902b7-01
                simple_job:
                  summary: Simple job without stages
                  description: Basic job details when should_return_stages=false
                  value:
                    id: 660f9511-f3ac-52e5-b827-557766551111
                    name: data_backup
                    status: COMPLETED
                    percentage: 100
                    priority: LOW
                    creationTime: '2025-07-26T14:00:00.000Z'
                    updateTime: '2025-07-26T15:30:00.000Z'
                    traceparent: 00-660f9511f3ac52e5b827557766551111-22b378cc5ca902b7-01
                    data:
                      source_path: /data/production
                      destination: s3://backup-bucket/2025-07-26
                      compression: gzip
                      encryption: true
                    userMetadata:
                      backup_type: daily
                      retention_days: 30
        '400':
          description: Invalid request, could not get job
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/badRequestResponse'
        '404':
          description: Job not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/jobNotFoundResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/internalErrorsResponse'
    delete:
      operationId: deleteJobV1
      summary: Delete a job and all its associated resources (stages, tasks)
      description: >
        Permanently removes a job and all its associated stages and tasks from
        the system.

        This operation cascades to delete all child resources and cannot be
        undone.


        The job must exist in the system for this operation to succeed.

        Jobs can only be deleted when they are in a finite state (COMPLETED,
        FAILED, or ABORTED).

        Attempting to delete a job in any other state will result in a 400
        error.


        Returns a success message with code JOB_DELETED_SUCCESSFULLY when
        completed.
      tags:
        - jobs
      responses:
        '200':
          description: Job deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/defaultOkMessage'
              example:
                code: JOB_DELETED_SUCCESSFULLY
        '400':
          description: Invalid parameters or validation error
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/baseErrorResponse'
                  - type: object
                    description: >
                      Error response structure for bad request errors, providing
                      a consistent

                      format for common-readable error codes and human-readable
                      messages.
                    required:
                      - code
                    properties:
                      code:
                        enum:
                          - VALIDATION_ERROR
                          - JOB_NOT_IN_FINITE_STATE
        '404':
          description: Job not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/jobNotFoundResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/internalErrorsResponse'
  /v1/jobs/{jobId}/user-metadata:
    patch:
      operationId: updateUserMetadataV1
      parameters:
        - $ref: '#/components/parameters/jobId'
      summary: Update job's custom metadata
      description: >
        Updates the user-defined metadata object for a specific job.

        This endpoint allows clients to attach or modify arbitrary data related
        to a job

        without affecting the job's core properties or execution status.


        User metadata is useful for storing application-specific context,
        tracking information,

        or any custom data needed by client applications.
      tags:
        - jobs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/userMetadata'
      responses:
        '200':
          description: User metadata successfully updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/defaultOkMessage'
              example:
                code: JOB_MODIFIED_SUCCESSFULLY
        '400':
          description: Invalid metadata format or validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/badRequestResponse'
        '404':
          description: Job not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/jobNotFoundResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/internalErrorsResponse'
  /v1/jobs/{jobId}/priority:
    parameters:
      - $ref: '#/components/parameters/jobId'
    patch:
      operationId: updateJobPriorityV1
      summary: Modify job's priority level
      description: >
        Updates the priority level for a specific job.

        This affects how the job is scheduled relative to other jobs in the
        system.


        Higher priority jobs will be processed before lower priority ones when
        resources

        are constrained. Priority changes take effect immediately and apply to
        all 

        pending tasks associated with the job.
      tags:
        - jobs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                priority:
                  $ref: '#/components/schemas/priority'
              required:
                - priority
      responses:
        '200':
          description: Job priority successfully changed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/defaultOkMessage'
              example:
                code: JOB_MODIFIED_SUCCESSFULLY
        '204':
          description: No change made - requested priority equals current priority
          headers:
            Reason:
              description: Won't change priority if equal to current
              schema:
                type: string
          content: {}
        '400':
          description: Invalid priority value or other request error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/badRequestResponse'
        '404':
          description: Job not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/jobNotFoundResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/internalErrorsResponse'
  /v1/jobs/{jobId}/status:
    parameters:
      - $ref: '#/components/parameters/jobId'
    put:
      operationId: updateStatusV1
      summary: Update job status for workflow control
      description: >
        Updates the operational status of a job to control its workflow
        execution. This endpoint 

        supports user-initiated operations including PENDING (resume), ABORTED
        (cancel), and 

        PAUSED (suspend), which may cascade changes to related stages and tasks.


        Internal status transitions (such as IN_PROGRESS, COMPLETED, FAILED,
        CREATED) are managed 

        automatically by the system based on stage and task completion, and
        cannot be set through 

        this endpoint.


        Status changes follow a state machine that enforces valid transitions.
        When a job's status 

        is changed, the system will automatically update timestamps and
        completion percentages as 

        appropriate.
      tags:
        - jobs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  $ref: '#/components/schemas/jobOperationStatus'
              required:
                - status
      responses:
        '200':
          description: Job status successfully changed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/defaultOkMessage'
              example:
                code: JOB_MODIFIED_SUCCESSFULLY
        '400':
          description: Invalid status or illegal state transition
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/baseErrorResponse'
                  - type: object
                    description: >
                      Error response structure for bad request errors, providing
                      a consistent

                      format for common-readable error codes and human-readable
                      messages.
                    properties:
                      code:
                        enum:
                          - VALIDATION_ERROR
                          - ILLEGAL_JOB_STATUS_TRANSITION
        '404':
          description: Job not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/jobNotFoundResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/internalErrorsResponse'
  /v1/jobs/{jobId}/stages:
    parameters:
      - $ref: '#/components/parameters/jobId'
    get:
      operationId: getStagesByJobIdV1
      parameters:
        - $ref: '#/components/parameters/includeTasks'
      summary: Retrieve all stages for a specific job in execution order
      description: >
        Fetches all stages associated with the specified job ID, automatically
        ordered by 

        their execution sequence (order field). Provides complete information
        about each 

        stage including type, status, progress, and sequential order number.


        Stages are returned in ascending order based on their order field (1, 2,
        3, etc.)

        to maintain the correct workflow execution sequence defined when stages
        were created.


        Optional inclusion of related task data via the should_return_tasks
        parameter,

        allowing clients to retrieve the complete job hierarchy in a single
        request.
      tags:
        - jobs
      responses:
        '200':
          description: Successfully retrieved stages for the specified job
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/getStageResponse'
        '400':
          description: Invalid job ID format or other parameter error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/badRequestResponse'
        '404':
          description: Job not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/jobNotFoundResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/internalErrorsResponse'
  /v1/jobs/{jobId}/stage:
    post:
      operationId: addStageV1
      summary: Add a new stage as the last stage in the job workflow
      description: >
        Appends a new stage to an existing job with automatic order assignment.

        The stage will be added after any existing stages in the job's workflow
        sequence.

        Each stage is automatically assigned an incremental order number (1, 2,
        3, etc.) 

        within the scope of its parent job to maintain execution sequence.


        This endpoint allows for extending job workflows at runtime by adding
        new processing steps.

        The order field ensures stages are processed in the correct sequence
        when retrieved.


        The job must exist and be in a valid state to accept new stages.
      parameters:
        - $ref: '#/components/parameters/jobId'
      tags:
        - jobs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/createStagePayloadRequest'
            examples:
              processing_stage:
                summary: Data processing stage
                description: Stage for data transformation and validation
                value:
                  type: data_processing
                  data:
                    processing_type: batch
                    chunk_size: 1000
                    validation_rules:
                      - 'not_null: [id, timestamp]'
                      - 'range: [amount, 0, 1000000]'
                  userMetadata:
                    estimated_duration: 2h
                    resource_requirements:
                      cpu: 4 cores
                      memory: 8GB
              waiting_stage:
                summary: Manual approval stage
                description: Stage that waits for manual intervention
                value:
                  type: manual_approval
                  startAsWaiting: true
                  data:
                    approval_type: quality_check
                    reviewers:
                      - senior-analyst@company.com
                    checklist:
                      - Data quality metrics within acceptable range
                      - No PII detected in output
                      - Performance benchmarks met
                  userMetadata:
                    priority: high
                    sla: 24h
              stage_with_tracing:
                summary: Stage with distributed tracing
                description: Stage creation with provided tracing context
                value:
                  type: data_validation
                  data:
                    validation_type: schema_check
                    strict_mode: true
                  traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
                  tracestate: vendor=trace123,service=validation
      responses:
        '201':
          description: Stage successfully created and added to the job
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stageResponse'
              examples:
                processing_stage_response:
                  summary: Response for data processing stage creation
                  value:
                    id: e9db7d16-a84c-4297-a45d-e59665760084
                    type: data_processing
                    status: CREATED
                    percentage: 0
                    jobId: 550e8400-e29b-41d4-a716-446655440000
                    order: 1
                    data:
                      processing_type: batch
                      chunk_size: 1000
                      validation_rules:
                        - 'not_null: [id, timestamp]'
                        - 'range: [amount, 0, 1000000]'
                    userMetadata:
                      estimated_duration: 2h
                      resource_requirements:
                        cpu: 4 cores
                        memory: 8GB
                    summary:
                      pending: 0
                      inProgress: 0
                      completed: 0
                      failed: 0
                      created: 0
                      retried: 0
                      total: 0
                    traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-33c489dd6db902b7-01
                    tracestate: processing=batch001,stage=data_proc
                waiting_stage_response:
                  summary: Response for manual approval stage creation
                  value:
                    id: 4f45bec6-08c4-4f7a-a3ea-be65eddc1235
                    type: manual_approval
                    status: WAITING
                    percentage: 0
                    jobId: 550e8400-e29b-41d4-a716-446655440000
                    order: 2
                    data:
                      approval_type: quality_check
                      reviewers:
                        - senior-analyst@company.com
                      checklist:
                        - Data quality metrics within acceptable range
                        - No PII detected in output
                        - Performance benchmarks met
                    userMetadata:
                      priority: high
                      sla: 24h
                    summary:
                      pending: 0
                      inProgress: 0
                      completed: 0
                      failed: 0
                      created: 0
                      retried: 0
                      total: 0
                    traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-44d59aee7ec902b7-01
        '400':
          description: Invalid request format.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/baseErrorResponse'
                  - type: object
                    description: >
                      Error response structure for bad request errors, providing
                      a consistent

                      format for common-readable error codes and human-readable
                      messages.
                    properties:
                      code:
                        enum:
                          - VALIDATION_ERROR
                          - JOB_IN_FINITE_STATE
        '404':
          description: Job not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/jobNotFoundResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/internalErrorsResponse'
  /v1/stages:
    get:
      operationId: getStagesV1
      parameters:
        - $ref: '#/components/parameters/paramJobId'
        - $ref: '#/components/parameters/paramStageType'
        - $ref: '#/components/parameters/stageStatus'
        - $ref: '#/components/parameters/includeTasks'
      summary: Retrieve stages matching specified criteria
      description: >
        Returns a filtered list of stages based on the provided query
        parameters.

        Supports filtering by job ID, stage type, and status.


        Optional inclusion of related task data via the should_return_tasks
        parameter

        allows clients to retrieve the complete stage hierarchy in a single
        request.
      tags:
        - stages
      responses:
        '200':
          description: Successfully retrieved matching stages
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/getStageResponse'
        '400':
          description: Invalid query parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/badRequestResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/internalErrorsResponse'
  /v1/stages/{stageId}:
    parameters:
      - $ref: '#/components/parameters/stageId'
    get:
      operationId: getStageByIdV1
      parameters:
        - $ref: '#/components/parameters/includeTasks'
      summary: Retrieve a specific stage by its ID
      description: >
        Fetches detailed information about a stage using its unique identifier.

        Includes stage configuration, status, metadata, and completion
        information.


        Optional inclusion of related task data via the should_return_tasks
        parameter,

        which allows clients to retrieve the complete stage hierarchy in a
        single request.
      tags:
        - stages
      responses:
        '200':
          description: Stage data retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/getStageResponse'
        '400':
          description: Invalid request format or parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/badRequestResponse'
        '404':
          description: Stage not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stageNotFoundResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/internalErrorsResponse'
  /v1/stages/{stageId}/summary:
    get:
      operationId: getStageSummaryV1
      parameters:
        - $ref: '#/components/parameters/stageId'
      summary: Get stage progress summary
      description: >
        Retrieves aggregated statistics about the tasks within a specific stage.

        Provides counts of tasks by status (pending, in progress, completed,
        etc.) 

        and a total task count for monitoring stage progress.


        This endpoint is useful for displaying progress indicators or status
        dashboards

        without needing to retrieve and process all individual task details.
      tags:
        - stages
      responses:
        '200':
          description: Stage summary retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/summary'
        '400':
          description: Invalid stage ID format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/badRequestResponse'
        '404':
          description: Stage not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stageNotFoundResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/internalErrorsResponse'
  /v1/stages/{stageId}/user-metadata:
    patch:
      operationId: updateStageUserMetadataV1
      parameters:
        - $ref: '#/components/parameters/stageId'
      summary: Update stage's custom metadata
      description: >
        Updates the user-defined metadata object for a specific stage.

        This endpoint allows clients to attach or modify arbitrary data related
        to a stage

        without affecting the stage's core properties or execution status.


        User metadata is useful for storing application-specific context,
        tracking information,

        or any custom data needed by client applications.
      tags:
        - stages
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/userMetadata'
      responses:
        '200':
          description: User metadata successfully updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/defaultOkMessage'
              example:
                code: STAGE_MODIFIED_SUCCESSFULLY
        '400':
          description: Invalid metadata format or validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/badRequestResponse'
        '404':
          description: Stage not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stageNotFoundResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/internalErrorsResponse'
  /v1/stages/{stageId}/status:
    put:
      operationId: updateStageStatusV1
      parameters:
        - $ref: '#/components/parameters/stageId'
      summary: Update stage status to trigger workflow progression
      description: >
        Updates the operational status of a stage to PENDING, which may trigger
        workflow 

        transitions and cascade changes to related tasks and the parent job.
        This endpoint 

        is restricted to manually advancing stages in the workflow sequence.


        Common use cases:

        - Resuming a WAITING stage (e.g., after manual intervention or approval)

        - Unblocking workflow progression when a stage is ready to proceed


        Internal status transitions (such as IN_PROGRESS, COMPLETED, FAILED,
        ABORTED, 

        WAITING, CREATED) are managed automatically by the system based on task
        completion, 

        job state, and workflow rules.


        Status changes follow a state machine that enforces valid transitions.
        When a stage's 

        status changes, it may automatically update the parent job's status and
        trigger 

        transitions in subsequent stages (e.g., activating the next stage in the
        sequence).
      tags:
        - stages
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  $ref: '#/components/schemas/stageOperationStatus'
              required:
                - status
      responses:
        '200':
          description: Stage status successfully changed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/defaultOkMessage'
              example:
                code: STAGE_MODIFIED_SUCCESSFULLY
        '400':
          description: Invalid status or illegal state transition
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/baseErrorResponse'
                  - type: object
                    description: >
                      Error response structure for bad request errors, providing
                      a consistent

                      format for common-readable error codes and human-readable
                      messages.
                    properties:
                      code:
                        enum:
                          - VALIDATION_ERROR
                          - ILLEGAL_STAGE_STATUS_TRANSITION
        '404':
          description: Stage not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stageNotFoundResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/baseErrorResponse'
                  - type: object
                    description: >
                      Error response structure for internal server errors,
                      providing a consistent

                      format for common-readable error codes and human-readable
                      messages.
                    properties:
                      code:
                        enum:
                          - DATABASE_RELATED_ERROR
                          - UNKNOWN_ERROR
                          - ILLEGAL_JOB_STATUS_TRANSITION
                          - JOB_NOT_FOUND
  /v1/stages/{stageId}/tasks:
    parameters:
      - $ref: '#/components/parameters/stageId'
    get:
      operationId: getTasksByStageIdV1
      summary: Retrieve all tasks for a specific stage
      description: >
        Fetches all tasks associated with the specified stage ID.

        Provides complete information about each task including type, status,
        and attempt count.
      responses:
        '200':
          description: Successfully retrieved tasks for the specified stage
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/taskResponse'
        '400':
          description: Invalid stage ID format or other parameter error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/badRequestResponse'
        '404':
          description: Stage not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stageNotFoundResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/internalErrorsResponse'
      tags:
        - stages
    post:
      operationId: addTasksV1
      summary: Add new tasks to an existing stage
      description: >
        Creates and appends new tasks to an existing stage.

        This endpoint allows for extending stage processing capabilities by
        adding more work units.


        Task objects require type and data properties, with optional user
        metadata and 

        maximum attempt configuration. Tasks are created with an initial status
        of PENDING.


        The stage must exist and be in a valid state to accept new tasks.
      parameters:
        - $ref: '#/components/parameters/stageId'
      tags:
        - stages
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/createTaskPayload'
            examples:
              file_processing_tasks:
                summary: Multiple file processing tasks
                description: Batch creation of tasks for processing multiple files
                value:
                  - data:
                      file_path: /data/input/file_001.csv
                      output_path: /data/processed/file_001.parquet
                      transformation: csv_to_parquet
                    userMetadata:
                      file_size: 125MB
                      estimated_time: 5m
                    maxAttempts: 3
                  - data:
                      file_path: /data/input/file_002.csv
                      output_path: /data/processed/file_002.parquet
                      transformation: csv_to_parquet
                    userMetadata:
                      file_size: 89MB
                      estimated_time: 3m
                    maxAttempts: 3
                  - data:
                      file_path: /data/input/file_003.csv
                      output_path: /data/processed/file_003.parquet
                      transformation: csv_to_parquet
                    userMetadata:
                      file_size: 256MB
                      estimated_time: 8m
                    maxAttempts: 5
              api_integration_tasks:
                summary: API integration tasks with different configurations
                value:
                  - data:
                      endpoint: https://api.external.com/customers
                      method: GET
                      headers:
                        Authorization: Bearer ${API_TOKEN}
                      pagination:
                        page_size: 100
                        max_pages: 50
                    userMetadata:
                      source: customer_system
                      priority: high
                  - data:
                      endpoint: https://api.external.com/orders
                      method: GET
                      headers:
                        Authorization: Bearer ${API_TOKEN}
                      query_params:
                        start_date: '2025-01-01T00:00:00.000Z'
                        end_date: '2025-07-27T00:00:00.000Z'
                    userMetadata:
                      source: order_system
                      priority: medium
              tasks_with_tracing:
                summary: Tasks with distributed tracing context
                description: Task creation with tracing information for observability
                value:
                  - data:
                      process_type: data_enrichment
                      input_dataset: customer_profiles
                      enrichment_sources:
                        - demographic_api
                        - credit_api
                    traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
                    tracestate: customer=enrich123,priority=high
                    maxAttempts: 2
                  - data:
                      process_type: data_validation
                      validation_rules:
                        - email_format
                        - phone_format
                    traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-11a268bb4ba902b7-01
                    maxAttempts: 1
      responses:
        '201':
          description: Tasks successfully created and added to the stage
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/taskResponse'
              examples:
                file_processing_tasks_response:
                  summary: Response for multiple file processing tasks creation
                  value:
                    - id: 3f09f17d-029e-417f-b84e-d6782efc2371
                      data:
                        file_path: /data/input/file_001.csv
                        output_path: /data/processed/file_001.parquet
                        transformation: csv_to_parquet
                      stageId: 5251e4cb-3f34-4be7-812f-dca3fa6e733a
                      userMetadata:
                        file_size: 125MB
                        estimated_time: 5m
                      status: PENDING
                      attempts: 0
                      maxAttempts: 3
                      creationTime: '2025-07-27T10:30:00.000Z'
                      updateTime: '2025-07-27T10:30:00.000Z'
                      traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-55e6abbf8fd902b7-01
                      tracestate: file=001,processing=csv_parquet
                    - id: 469e8a0c-9232-4144-920f-fb5cef356ff7
                      data:
                        file_path: /data/input/file_002.csv
                        output_path: /data/processed/file_002.parquet
                        transformation: csv_to_parquet
                      stageId: 6e1e2e25-22ee-4e24-b394-c544d253ff43
                      userMetadata:
                        file_size: 89MB
                        estimated_time: 3m
                      status: PENDING
                      attempts: 0
                      maxAttempts: 3
                      creationTime: '2025-07-27T10:30:00.000Z'
                      updateTime: '2025-07-27T10:30:00.000Z'
                      traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-66f7bcc090e902b7-01
                      tracestate: file=002,processing=csv_parquet
                    - id: 6a7ecf04-4455-41d1-aa04-8786178cb4a3
                      data:
                        file_path: /data/input/file_003.csv
                        output_path: /data/processed/file_003.parquet
                        transformation: csv_to_parquet
                      stageId: 714ef37c-218f-4818-a166-cbc13d2850a6
                      userMetadata:
                        file_size: 256MB
                        estimated_time: 8m
                      status: PENDING
                      attempts: 0
                      maxAttempts: 5
                      creationTime: '2025-07-27T10:30:00.000Z'
                      updateTime: '2025-07-27T10:30:00.000Z'
                      traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-77081dd1a1f902b7-01
                      tracestate: file=003,processing=csv_parquet
                api_integration_tasks_response:
                  summary: Response for API integration tasks creation
                  value:
                    - id: ddfad658-da33-4573-b5a3-d70a204a3e0b
                      data:
                        endpoint: https://api.external.com/customers
                        method: GET
                        headers:
                          Authorization: Bearer ${API_TOKEN}
                        pagination:
                          page_size: 100
                          max_pages: 50
                      stageId: a09866f1-74f1-49c1-b996-268586ad346d
                      userMetadata:
                        source: customer_system
                        priority: high
                      status: PENDING
                      attempts: 0
                      maxAttempts: 3
                      creationTime: '2025-07-27T10:30:00.000Z'
                      updateTime: '2025-07-27T10:30:00.000Z'
                      traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-88192ee2b20902b7-01
                      tracestate: api=customers,source=external
                    - id: df59d74e-f442-4e66-b8c9-b312ad948c47
                      data:
                        endpoint: https://api.external.com/orders
                        method: GET
                        headers:
                          Authorization: Bearer ${API_TOKEN}
                        query_params:
                          start_date: '2025-01-01T00:00:00.000Z'
                          end_date: '2025-07-27T00:00:00.000Z'
                      stageId: 4daa6a5c-da33-4cbe-8e4a-dbc00182fcfa
                      userMetadata:
                        source: order_system
                        priority: medium
                      status: PENDING
                      attempts: 0
                      maxAttempts: 3
                      creationTime: '2025-07-27T10:30:00.000Z'
                      updateTime: '2025-07-27T10:30:00.000Z'
                      traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-99203ff3c31902b7-01
                      tracestate: api=orders,source=external
                tasks_with_lifecycle_states:
                  summary: >-
                    Tasks showing different lifecycle states with timing
                    information
                  description: >-
                    Examples of tasks in various states showing startTime and
                    endTime usage
                  value:
                    - id: f1a2b3c4-5678-90ab-cdef-123456789012
                      data:
                        process_type: data_processing
                        input_file: /data/raw/dataset_001.json
                      stageId: 1a2b3c4d-5e6f-7890-ab12-345678901234
                      status: PENDING
                      attempts: 0
                      maxAttempts: 3
                      userMetadata: {}
                      creationTime: '2025-07-27T10:30:00.000Z'
                      updateTime: '2025-07-27T10:30:00.000Z'
                      traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-aa111bb222c902b7-01
                      tracestate: state=pending
                    - id: f2a3b4c5-6789-01bc-def2-345678901234
                      data:
                        process_type: data_validation
                        input_file: /data/raw/dataset_002.json
                      stageId: 2b3c4d5e-6f78-9012-bc34-567890123456
                      status: IN_PROGRESS
                      attempts: 1
                      maxAttempts: 3
                      userMetadata: {}
                      creationTime: '2025-07-27T10:30:00.000Z'
                      updateTime: '2025-07-27T10:32:15.000Z'
                      startTime: '2025-07-27T10:32:15.000Z'
                      traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-bb222cc333d902b7-01
                      tracestate: state=in_progress
                    - id: f3a4b5c6-789a-12cd-ef34-567890123456
                      data:
                        process_type: data_export
                        output_file: /data/processed/dataset_003.parquet
                      stageId: 3c4d5e6f-7890-1234-cd56-789012345678
                      status: COMPLETED
                      attempts: 1
                      maxAttempts: 3
                      userMetadata: {}
                      creationTime: '2025-07-27T10:30:00.000Z'
                      updateTime: '2025-07-27T10:35:45.000Z'
                      startTime: '2025-07-27T10:33:20.000Z'
                      endTime: '2025-07-27T10:35:45.000Z'
                      traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-cc333dd444e902b7-01
                      tracestate: state=completed
                    - id: f4a5b6c7-89ab-23de-f456-789012345678
                      data:
                        process_type: data_cleanup
                        cleanup_rules:
                          - remove_duplicates
                          - validate_schema
                      stageId: 4d5e6f78-9012-3456-de78-901234567890
                      status: FAILED
                      attempts: 3
                      maxAttempts: 3
                      userMetadata: {}
                      creationTime: '2025-07-27T10:30:00.000Z'
                      updateTime: '2025-07-27T10:38:12.000Z'
                      startTime: '2025-07-27T10:36:05.000Z'
                      endTime: '2025-07-27T10:38:12.000Z'
                      traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-dd444ee555f902b7-01
                      tracestate: state=failed
        '400':
          description: Invalid request format or validation error
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/baseErrorResponse'
                  - type: object
                    description: >
                      Error response structure for bad request errors, providing
                      a consistent

                      format for common-readable error codes and human-readable
                      messages.
                    properties:
                      code:
                        enum:
                          - VALIDATION_ERROR
                          - STAGE_IN_FINITE_STATE
                          - NOT_ALLOWED_TO_ADD_TASKS_TO_IN_PROGRESS_STAGE
        '404':
          description: Stage not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/stageNotFoundResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/internalErrorsResponse'
  /v1/stages/{stageType}/tasks/dequeue:
    parameters:
      - $ref: '#/components/parameters/stageType'
    patch:
      operationId: dequeueTaskV1
      summary: Find and claim the highest priority pending task of specified stage type
      description: >
        Retrieves the highest priority task of the specified stage type that is
        in PENDING or RETRIED status, 

        and automatically updates its status to IN_PROGRESS. This endpoint
        implements a priority-based 

        work queue pattern where workers can claim the next available task.


        The endpoint considers task priority (inherited from the parent job),
        searches only for tasks 

        that are in valid states (PENDING or RETRIED), and updates related stage
        and job status if needed.


        If successful, returns the complete task details with status updated to
        IN_PROGRESS.
      tags:
        - stages
      responses:
        '200':
          description: Task successfully dequeued and status updated to IN_PROGRESS
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/taskResponse'
        '400':
          description: Invalid stageType parameter or other validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/badRequestResponse'
        '404':
          description: No pending tasks of requested type are available
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/taskNotFoundResponse'
        '500':
          description: Internal server error or invalid state transition
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/baseErrorResponse'
                  - type: object
                    description: >
                      Error response structure for internal server errors,
                      providing a consistent

                      format for common-readable error codes and human-readable
                      messages.
                    properties:
                      code:
                        enum:
                          - DATABASE_RELATED_ERROR
                          - UNKNOWN_ERROR
                          - TASK_STATUS_UPDATE_FAILED
                          - ILLEGAL_TASK_STATUS_TRANSITION
                          - ILLEGAL_STAGE_STATUS_TRANSITION
                          - ILLEGAL_JOB_STATUS_TRANSITION
                          - STAGE_NOT_FOUND
                          - JOB_NOT_FOUND
  /v1/tasks:
    parameters:
      - $ref: '#/components/parameters/paramStageId'
      - $ref: '#/components/parameters/paramStageType'
      - $ref: '#/components/parameters/fromDate'
      - $ref: '#/components/parameters/endDate'
      - $ref: '#/components/parameters/paramsTaskStatus'
    get:
      operationId: getTasksByCriteriaV1
      summary: Retrieve tasks matching specified criteria
      description: >
        Returns a filtered list of tasks based on the provided query parameters.

        Supports filtering by stage ID, task type, date range, and operational
        status.


        This endpoint is useful for monitoring task progress across multiple
        stages and jobs,

        enabling clients to build custom dashboards or track specific task
        types.
      responses:
        '200':
          description: Successfully retrieved matching tasks
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/taskResponse'
        '400':
          description: Invalid query parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/badRequestResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/internalErrorsResponse'
      tags:
        - tasks
  /v1/tasks/{taskId}:
    parameters:
      - $ref: '#/components/parameters/taskId'
    get:
      operationId: getTaskByIdV1
      summary: Retrieve a specific task by its ID
      description: >
        Fetches detailed information about a task using its unique identifier.

        Returns complete task data including type, status, payload, and attempt
        information.
      responses:
        '200':
          description: Task data retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/taskResponse'
        '400':
          description: Invalid task ID format or other parameter error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/badRequestResponse'
        '404':
          description: Task not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/taskNotFoundResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/internalErrorsResponse'
      tags:
        - tasks
  /v1/tasks/{taskId}/user-metadata:
    patch:
      operationId: updateTaskUserMetadataV1
      parameters:
        - $ref: '#/components/parameters/taskId'
      summary: Update task's custom metadata
      description: >
        Updates the user-defined metadata object for a specific task.

        This endpoint allows clients to attach or modify arbitrary data related
        to a task

        without affecting the task's core properties or execution status.


        User metadata is useful for storing application-specific context,
        tracking information,

        or any custom data needed by client applications.
      tags:
        - tasks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/userMetadata'
      responses:
        '200':
          description: User metadata successfully updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/defaultOkMessage'
              example:
                code: TASK_MODIFIED_SUCCESSFULLY
        '400':
          description: Invalid metadata format or validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/badRequestResponse'
        '404':
          description: Task not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/taskNotFoundResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/internalErrorsResponse'
  /v1/tasks/{taskId}/status:
    parameters:
      - $ref: '#/components/parameters/taskId'
    put:
      operationId: updateTaskStatusV1
      summary: Mark task as completed or failed
      description: >
        Updates the operational status of a task to either COMPLETED or FAILED,
        which may trigger 

        cascading updates to the parent stage and job. This endpoint is
        restricted to marking tasks 

        as finished by external workers.


        Internal status transitions (such as PENDING to IN_PROGRESS) are managed
        automatically 

        by the system through the dequeue operation and cannot be set through
        this endpoint.


        Status changes follow a state machine that enforces valid transitions.
        When a task's status 

        is changed, the system will automatically update the parent stage's
        summary statistics and 

        may affect the stage's overall status.
      tags:
        - tasks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  $ref: '#/components/schemas/taskOperationStatus'
              required:
                - status
            examples:
              complete_task:
                summary: Mark task as completed
                description: Update task status to COMPLETED after successful execution
                value:
                  status: COMPLETED
              fail_task:
                summary: Mark task as failed
                description: Update task status to FAILED when processing encounters errors
                value:
                  status: FAILED
      responses:
        '200':
          description: Task status successfully changed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/taskResponse'
        '400':
          description: Invalid status or illegal state transition
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/baseErrorResponse'
                  - type: object
                    description: >
                      Error response structure for bad request errors, providing
                      a consistent

                      format for common-readable error codes and human-readable
                      messages.
                    properties:
                      code:
                        enum:
                          - VALIDATION_ERROR
                          - ILLEGAL_TASK_STATUS_TRANSITION
        '404':
          description: Task not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/taskNotFoundResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/baseErrorResponse'
                  - type: object
                    description: >
                      Error response structure for internal server errors,
                      providing a consistent

                      format for common-readable error codes and human-readable
                      messages.
                    properties:
                      code:
                        enum:
                          - DATABASE_RELATED_ERROR
                          - UNKNOWN_ERROR
                          - TASK_STATUS_UPDATE_FAILED
                          - ILLEGAL_TASK_STATUS_TRANSITION
                          - ILLEGAL_STAGE_STATUS_TRANSITION
                          - ILLEGAL_JOB_STATUS_TRANSITION
                          - STAGE_NOT_FOUND
                          - JOB_NOT_FOUND
components:
  schemas:
    creationTime:
      type: string
      format: date-time
      description: Timestamp indicating when the resource was created
    updateTime:
      type: string
      format: date-time
      description: Timestamp indicating when the resource was last updated
    startTime:
      type: string
      format: date-time
      description: >-
        Timestamp indicating when the resource began processing (in-progress
        state)
    endTime:
      type: string
      format: date-time
      description: >-
        Timestamp indicating when the resource reached a finite state (e.g.,
        COMPLETED, FAILED, ABORTED)
    jobId:
      type: string
      format: uuid
      description: Unique identifier for a job
    jobPayload:
      type: object
      additionalProperties: true
      description: Custom job configuration data containing job-specific parameters
    percentage:
      type: integer
      minimum: 0
      maximum: 100
      description: Completion percentage of a job, stage, or task (0-100)
    attempts:
      type: integer
      minimum: 0
      description: Number of times a task has been attempted
    maxAttempts:
      type: integer
      minimum: 1
      description: Maximum number of retries allowed for a task
    stageId:
      type: string
      format: uuid
      description: Unique identifier for a stage
    stagePayload:
      type: object
      additionalProperties: true
      description: Custom stage configuration data containing stage-specific parameters
    order:
      type: integer
      minimum: 1
      description: Stage execution order within job
      example: 1
    priority:
      type: string
      enum:
        - VERY_HIGH
        - HIGH
        - MEDIUM
        - LOW
        - VERY_LOW
      example: LOW
      description: |
        Job priority for processing order. Higher priority processed first.
        VERY_HIGH > HIGH > MEDIUM > LOW > VERY_LOW
    traceparent:
      type: string
      description: |
        W3C traceparent for distributed tracing. Auto-injected if not provided.
        See [W3C Trace Context](https://www.w3.org/TR/trace-context/).
      pattern: ^[\da-f]{2}-[\da-f]{32}-[\da-f]{16}-[\da-f]{2}$
      example: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
    tracestate:
      type: string
      description: >-
        W3C tracestate for distributed tracing. Optional, auto-injected if
        available.
      pattern: >-
        ^[a-z0-9][a-z0-9_\\-\\*\\/]*=[^,=]+(?:,[a-z0-9][a-z0-9_\\-\\*\\/]*=[^,=]+)*$
      example: rojo=00f067aa0ba902b7,congo=t61rcWkgMzE
    successMessages:
      type: string
      enum:
        - JOB_MODIFIED_SUCCESSFULLY
        - TASK_MODIFIED_SUCCESSFULLY
        - STAGE_MODIFIED_SUCCESSFULLY
        - JOB_DELETED_SUCCESSFULLY
      example: JOB_MODIFIED_SUCCESSFULLY
      description: Success response codes
    jobOperationStatus:
      type: string
      enum:
        - PENDING
        - ABORTED
        - PAUSED
      example: PENDING
      description: >
        User-controllable job statuses: PENDING (resume), ABORTED (cancel),
        PAUSED (suspend).

        System-managed: IN_PROGRESS, COMPLETED, FAILED, CREATED.
    jobOperationStatusResponse:
      type: string
      enum:
        - PENDING
        - IN_PROGRESS
        - COMPLETED
        - FAILED
        - ABORTED
        - PAUSED
        - CREATED
      example: PENDING
      description: >
        All job states. User-controllable: PENDING, ABORTED, PAUSED.
        System-managed: IN_PROGRESS, COMPLETED, FAILED, CREATED.

        Terminal states: COMPLETED, FAILED, ABORTED.
    stageOperationStatus:
      type: string
      enum:
        - PENDING
      description: >
        User-controllable stage status: PENDING only.

        System-managed: IN_PROGRESS, COMPLETED, FAILED, ABORTED, WAITING,
        CREATED.
    stageOperationStatusResponse:
      type: string
      enum:
        - PENDING
        - IN_PROGRESS
        - COMPLETED
        - FAILED
        - ABORTED
        - WAITING
        - CREATED
      example: PENDING
      description: >
        All stage states. User-controllable: PENDING. System-managed:
        IN_PROGRESS, COMPLETED, FAILED, ABORTED, WAITING, CREATED.

        Terminal states: COMPLETED, FAILED, ABORTED.
    taskOperationStatus:
      type: string
      enum:
        - COMPLETED
        - FAILED
      example: COMPLETED
      description: |
        User-controllable task statuses: COMPLETED, FAILED.
        System-managed: PENDING, IN_PROGRESS, CREATED, RETRIED.
    taskOperationStatusResponse:
      type: string
      enum:
        - PENDING
        - IN_PROGRESS
        - COMPLETED
        - FAILED
        - CREATED
        - RETRIED
      example: PENDING
      description: |
        All task states including RETRIED for retry handling.
        Terminal states: COMPLETED, FAILED.
    jobName:
      type: string
      example: DEFAULT
      minLength: 2
      maxLength: 50
      description: Job category/type for filtering and behavior
    stageType:
      type: string
      maxLength: 50
      example: unknown
      description: >
        Free-form string identifier for stage functionality, allowing flexible
        categorization

        of stage operations. Used for routing tasks to appropriate workers and

        for filtering in API requests. Can be any descriptive name up to 50
        characters.
    returnStage:
      type: boolean
      description: >-
        Flag indicating whether to include complete stage details in job
        response payloads
    returnTask:
      type: boolean
      description: >-
        Flag indicating whether to include complete task details in stage
        response payloads
    userMetadata:
      type: object
      additionalProperties: true
      default: {}
      description: >-
        Application-specific custom data container that can store arbitrary
        client information without affecting core operations
    summary:
      description: >
        Aggregated task statistics grouped by operational status, providing a
        complete overview of stage progress.

        Used for monitoring progress, generating dashboards, and determining
        when stages/jobs are complete.

        The total field should always equal the sum of all other status counts.
      type: object
      properties:
        pending:
          type: integer
          minimum: 0
          description: Number of tasks awaiting execution
        inProgress:
          type: integer
          minimum: 0
          description: Number of tasks currently being processed
        completed:
          type: integer
          minimum: 0
          description: Number of tasks that finished successfully
        failed:
          type: integer
          minimum: 0
          description: Number of tasks that encountered errors and could not be completed
        created:
          type: integer
          minimum: 0
          description: Number of tasks in initial state before becoming pending
        retried:
          type: integer
          minimum: 0
          description: Number of tasks scheduled for re-execution after failure
        total:
          type: integer
          minimum: 0
          description: Total count of tasks belonging to the stage
      required:
        - pending
        - inProgress
        - completed
        - failed
        - created
        - retried
        - total
      additionalProperties: false
    createJobPayload:
      type: object
      properties:
        name:
          $ref: '#/components/schemas/jobName'
        data:
          $ref: '#/components/schemas/jobPayload'
        priority:
          allOf:
            - $ref: '#/components/schemas/priority'
            - default: MEDIUM
        userMetadata:
          $ref: '#/components/schemas/userMetadata'
        traceparent:
          $ref: '#/components/schemas/traceparent'
        tracestate:
          $ref: '#/components/schemas/tracestate'
      required:
        - data
        - name
      additionalProperties: false
      description: >
        Input payload for creating a new job in the system.

        Contains all required configuration for job execution, including
        processing mode,

        custom parameters, metadata.


        Tracing fields (traceparent, tracestate) are optional:

        - If traceparent is provided, user's trace context is used (tracestate
        defaults to null if not provided)

        - If traceparent is not provided, the system automatically injects both
        traceparent and tracestate 
          from the active OpenTelemetry context using propagation.inject() (tracestate may still be null if not available)
    job:
      type: object
      required:
        - id
        - name
        - data
        - userMetadata
        - traceparent
        - status
        - percentage
        - creationTime
        - updateTime
        - priority
      description: >
        Complete job information with status and metadata.


        Comprehensive job response model containing all job details including
        configuration,

        execution status, progress tracking, and associated metadata. This
        schema represents

        the complete state of a job in the system and is returned by job
        retrieval operations.


        Includes optional stage data when requested via query parameters,
        allowing clients

        to retrieve the complete job hierarchy in a single request.
      properties:
        id:
          $ref: '#/components/schemas/jobId'
        status:
          $ref: '#/components/schemas/jobOperationStatusResponse'
        percentage:
          $ref: '#/components/schemas/percentage'
        creationTime:
          $ref: '#/components/schemas/creationTime'
        updateTime:
          $ref: '#/components/schemas/updateTime'
        name:
          $ref: '#/components/schemas/jobName'
        data:
          $ref: '#/components/schemas/jobPayload'
        priority:
          $ref: '#/components/schemas/priority'
        userMetadata:
          $ref: '#/components/schemas/userMetadata'
        traceparent:
          $ref: '#/components/schemas/traceparent'
        tracestate:
          $ref: '#/components/schemas/tracestate'
        stages:
          type: array
          items:
            $ref: '#/components/schemas/stageResponse'
    createStagePayloadRequest:
      allOf:
        - $ref: '#/components/schemas/createStagePayload'
        - type: object
          properties:
            startAsWaiting:
              type: boolean
              description: >
                Optional flag indicating whether the stage should be created in
                a waiting state.

                If true, the stage will not start processing immediately and
                will require

                manual intervention to begin execution. Useful for staging
                workflows where

                stages need to be prepared but not executed until all
                dependencies are met.
              example: false
          description: >
            Input payload for creating a new processing stage.

            Defines the stage type, custom configuration data, and user-defined
            metadata.

            Used when adding stages to jobs or creating stages as part of job
            creation.

            The system automatically assigns an incremental order number to
            maintain execution sequence.

            The startAsWaiting flag allows for creating stages that are not
            immediately active,

            enabling more complex workflows where stages can be prepared in
            advance.
    createStagePayload:
      type: object
      description: >
        Input payload for creating a new stage within a job.

        Contains stage type, operational parameters, and optional user metadata.


        Tracing fields (traceparent, tracestate) are optional:

        - If traceparent is provided, user's trace context is used (tracestate
        defaults to null if not provided)

        - If traceparent is not provided, the system automatically injects both
        traceparent and tracestate 
          from the active OpenTelemetry context using propagation.inject() (tracestate may still be null if not available)
      properties:
        type:
          $ref: '#/components/schemas/stageType'
        data:
          $ref: '#/components/schemas/stagePayload'
        userMetadata:
          $ref: '#/components/schemas/userMetadata'
        traceparent:
          $ref: '#/components/schemas/traceparent'
        tracestate:
          $ref: '#/components/schemas/tracestate'
      required:
        - data
        - type
    stageResponse:
      allOf:
        - $ref: '#/components/schemas/createStagePayload'
        - type: object
          required:
            - id
            - summary
            - jobId
            - order
            - traceparent
            - userMetadata
            - percentage
            - status
          properties:
            id:
              $ref: '#/components/schemas/stageId'
            summary:
              $ref: '#/components/schemas/summary'
            percentage:
              $ref: '#/components/schemas/percentage'
            status:
              $ref: '#/components/schemas/stageOperationStatusResponse'
            jobId:
              $ref: '#/components/schemas/jobId'
            order:
              $ref: '#/components/schemas/order'
            traceparent:
              $ref: '#/components/schemas/traceparent'
          description: >
            Complete stage information returned by the API, including all fields
            from the 

            creation payload plus system-generated fields like ID, progress
            statistics,

            execution status, and parent job reference.
    getStageResponse:
      allOf:
        - $ref: '#/components/schemas/stageResponse'
        - type: object
          description: >
            Extended stage response that includes associated tasks when
            requested with 

            should_return_tasks=true. Used to retrieve the complete stage
            hierarchy

            in a single API call.
          properties:
            tasks:
              type: array
              description: Associated tasks belonging to this stage
              items:
                $ref: '#/components/schemas/taskResponse'
    taskId:
      type: string
      format: uuid
      description: Unique identifier for a task, generated by the system upon task creation
    taskPayload:
      type: object
      additionalProperties: true
      description: >
        Custom task configuration data containing operation-specific parameters.

        The schema varies based on task type and contains all necessary
        information

        for task execution by workers.
    createTaskPayload:
      type: object
      description: >
        Input payload for creating a new task within a stage.

        Contains task type, operational parameters, and optional retry
        configuration.

        Used when adding tasks to existing stages.


        Trace propagation  (traceparent, tracestate) are optional:

        - If traceparent is provided, user's trace context is used (tracestate
        defaults to null if not provided)

        - If traceparent is not provided, the system automatically injects both
        traceparent and tracestate 
          from the active OpenTelemetry context using propagation.inject() (tracestate may still be null if not available)
      properties:
        data:
          $ref: '#/components/schemas/taskPayload'
        userMetadata:
          $ref: '#/components/schemas/userMetadata'
        maxAttempts:
          $ref: '#/components/schemas/maxAttempts'
        traceparent:
          $ref: '#/components/schemas/traceparent'
        tracestate:
          $ref: '#/components/schemas/tracestate'
      required:
        - data
      additionalProperties: false
    taskResponse:
      type: object
      description: >
        Complete task information returned by the API, including all
        configuration

        data along with execution status, attempt tracking, and associated stage
        reference.

        Used when retrieving task details or after task creation.
      properties:
        id:
          $ref: '#/components/schemas/taskId'
        data:
          $ref: '#/components/schemas/taskPayload'
        stageId:
          $ref: '#/components/schemas/stageId'
        userMetadata:
          $ref: '#/components/schemas/userMetadata'
        creationTime:
          $ref: '#/components/schemas/creationTime'
        updateTime:
          $ref: '#/components/schemas/updateTime'
        startTime:
          $ref: '#/components/schemas/startTime'
        endTime:
          $ref: '#/components/schemas/endTime'
        status:
          $ref: '#/components/schemas/taskOperationStatusResponse'
        attempts:
          $ref: '#/components/schemas/attempts'
        maxAttempts:
          $ref: '#/components/schemas/maxAttempts'
        traceparent:
          $ref: '#/components/schemas/traceparent'
        tracestate:
          $ref: '#/components/schemas/tracestate'
      required:
        - id
        - data
        - stageId
        - status
        - attempts
        - maxAttempts
        - traceparent
        - userMetadata
        - creationTime
        - updateTime
      additionalProperties: false
    defaultOkMessage:
      type: object
      description: |
        Standard success response structure used for operations that don't
        return entity data, providing a standardized confirmation message.
      properties:
        code:
          $ref: '#/components/schemas/successMessages'
      required:
        - code
    baseErrorResponse:
      type: object
      description: >
        Foundation schema for standardized error responses across all API
        endpoints.

        Provides consistent structure with human-readable message and
        common-readable code fields

        that are extended by individual endpoints to define their specific error
        scenarios.
      properties:
        message:
          type: string
          description: Human-readable error message describing the issue
        code:
          type: string
          description: common-readable error code indicating the specific error type
      required:
        - message
        - code
    internalErrorsResponse:
      allOf:
        - $ref: '#/components/schemas/baseErrorResponse'
        - type: object
          description: >
            Provides a unified error response format for internal server errors,
            including a common-readable error code and a clear, human-readable
            message to help clients identify and handle issues consistently.
          properties:
            code:
              enum:
                - DATABASE_RELATED_ERROR
                - UNKNOWN_ERROR
          required:
            - code
    badRequestResponse:
      allOf:
        - $ref: '#/components/schemas/baseErrorResponse'
        - type: object
          description: >
            Standardized error response structure for bad request errors,
            providing a consistent

            format for common-readable error codes and human-readable messages.
          properties:
            code:
              enum:
                - VALIDATION_ERROR
          required:
            - code
    jobNotFoundResponse:
      allOf:
        - $ref: '#/components/schemas/baseErrorResponse'
        - type: object
          description: >
            Standardized error response for cases where a requested job is not
            found in the system.

            Provides a consistent format for common-readable error codes and
            human-readable messages.
          properties:
            code:
              enum:
                - JOB_NOT_FOUND
          required:
            - code
    stageNotFoundResponse:
      allOf:
        - $ref: '#/components/schemas/baseErrorResponse'
        - type: object
          description: >
            Standardized error response for cases where a requested stage is not
            found in the system.

            Provides a consistent format for common-readable error codes and
            human-readable messages.
          properties:
            code:
              enum:
                - STAGE_NOT_FOUND
          required:
            - code
    taskNotFoundResponse:
      allOf:
        - $ref: '#/components/schemas/baseErrorResponse'
        - type: object
          description: >
            Standardized error response for cases where a requested task is not
            found in the system.

            Provides a consistent format for common-readable error codes and
            human-readable messages.
          properties:
            code:
              enum:
                - TASK_NOT_FOUND
          required:
            - code
  parameters:
    jobId:
      in: path
      name: jobId
      description: Unique identifier for the job
      required: true
      schema:
        $ref: '#/components/schemas/jobId'
    stageId:
      in: path
      name: stageId
      description: Unique identifier for the stage
      required: true
      schema:
        $ref: '#/components/schemas/stageId'
    taskId:
      in: path
      name: taskId
      description: Unique identifier for the task
      required: true
      schema:
        $ref: '#/components/schemas/taskId'
    paramsTaskStatus:
      in: query
      name: status
      description: Filter tasks by their operational status
      required: false
      schema:
        $ref: '#/components/schemas/taskOperationStatusResponse'
    jobNameQueryParam:
      in: query
      name: job_name
      description: Filter jobs by their name/type
      required: false
      schema:
        $ref: '#/components/schemas/jobName'
    priority:
      in: query
      name: priority
      description: Filter jobs by their priority level
      required: false
      schema:
        $ref: '#/components/schemas/priority'
    fromDate:
      in: query
      name: from_date
      description: Filter results by update time, starting from this date/time
      required: false
      schema:
        type: string
        format: date-time
    endDate:
      in: query
      name: end_date
      description: Filter results by update time, ending at this date/time
      required: false
      schema:
        type: string
        format: date-time
    includeStages:
      in: query
      name: should_return_stages
      description: When true, includes stage data in the response
      required: false
      schema:
        $ref: '#/components/schemas/returnStage'
    includeTasks:
      in: query
      name: should_return_tasks
      description: When true, includes task data in the response
      required: false
      schema:
        $ref: '#/components/schemas/returnTask'
    paramStageId:
      in: query
      name: stage_id
      description: Filter results by stage identifier
      required: false
      schema:
        $ref: '#/components/schemas/stageId'
    paramJobId:
      in: query
      name: job_id
      description: Filter results by job identifier
      required: false
      schema:
        $ref: '#/components/schemas/jobId'
    paramStageType:
      in: query
      name: stage_type
      description: Filter results by stage type (e.g., processing, validation)
      required: false
      schema:
        $ref: '#/components/schemas/stageType'
    stageType:
      in: path
      name: stageType
      description: Stage type identifier for dequeuing tasks
      required: true
      schema:
        $ref: '#/components/schemas/stageType'
    stageStatus:
      in: query
      name: stage_operation_status
      description: |
        Filter results by stage operational status (e.g., PENDING, IN_PROGRESS).
        Used to find stages in specific execution states.
      required: false
      schema:
        $ref: '#/components/schemas/stageOperationStatusResponse'