# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for dotCMS REST Job Queue API
  version: 1.0.0
extends: openapi/dotcms-job-queue-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-09-26'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 14
- target: $.paths['/api/v1/jobs/abandoned'].get
  update:
    x-apievangelist-phrasing:
      intent: List abandoned background jobs
      effect: read
      questions:
      - Which background jobs were abandoned and never finished?
      - Can I page through abandoned jobs in the job queue?
      instructions:
      - text: List the abandoned jobs.
      - text: Show page {page} of abandoned jobs, {pageSize} per page.
        slots:
          page: query.page
          pageSize: query.pageSize
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/jobs/active'].get
  update:
    x-apievangelist-phrasing:
      intent: List active jobs across all queues
      effect: read
      questions:
      - What jobs are running right now across every queue?
      - How many background jobs are currently active in dotCMS?
      instructions:
      - text: List all active jobs in every queue.
      - text: Show page {page} of currently running jobs across all queues.
        slots:
          page: query.page
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/jobs/{queueName}/active'].get
  update:
    x-apievangelist-phrasing:
      intent: List active jobs in one queue
      effect: read
      questions:
      - Which jobs are active in a particular job queue?
      - Can I see only the running jobs for the import queue?
      instructions:
      - text: List the active jobs in queue {queueName}.
        slots:
          queueName: path.queueName
      - text: Show {pageSize} running jobs per page from queue {queueName}.
        slots:
          pageSize: query.pageSize
          queueName: path.queueName
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/jobs/{jobId}/cancel'].post
  update:
    x-apievangelist-phrasing:
      intent: Cancel a background job
      effect: destructive
      questions:
      - How do I cancel a queued or running background job?
      - Is it possible that a job still completes after I request cancellation?
      instructions:
      - text: Cancel job {jobId}.
        slots:
          jobId: path.jobId
      - text: Request cancellation of background job {jobId}.
        slots:
          jobId: path.jobId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/jobs/canceled'].get
  update:
    x-apievangelist-phrasing:
      intent: List canceled jobs
      effect: read
      questions:
      - Which jobs have been canceled?
      - Can I page through the list of canceled background jobs?
      instructions:
      - text: List the canceled jobs.
      - text: Show page {page} of canceled jobs.
        slots:
          page: query.page
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/jobs/completed'].get
  update:
    x-apievangelist-phrasing:
      intent: List completed jobs
      effect: read
      questions:
      - Which background jobs have completed, whatever their outcome?
      - Can I page through every finished job in the queue?
      instructions:
      - text: List all completed jobs.
      - text: Show page {page} of completed jobs, {pageSize} at a time.
        slots:
          page: query.page
          pageSize: query.pageSize
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/jobs/{queueName}/upload'].post
  update:
    x-apievangelist-phrasing:
      intent: Queue a job with an uploaded file
      effect: write
      questions:
      - How do I submit a background job that needs a file upload, like a CSV import?
      - Can I pass job parameters as multipart form data along with a file?
      instructions:
      - text: Upload {file} and queue a job on {queueName}.
        slots:
          file: requestBody.file
          queueName: path.queueName
      - text: Create a {queueName} job from this file with parameters {params}.
        slots:
          queueName: path.queueName
          params: requestBody.params
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/jobs/{queueName}'].post
  update:
    x-apievangelist-phrasing:
      intent: Queue a job with JSON parameters
      effect: write
      questions:
      - How do I start a background job by posting JSON parameters to a queue?
      - What do I get back when I submit a JSON job to the queue?
      instructions:
      - text: Queue a new job on {queueName} with these JSON parameters.
        slots:
          queueName: path.queueName
      - text: Submit a JSON-configured job to queue {queueName} and give me its id.
        slots:
          queueName: path.queueName
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/jobs/failed'].get
  update:
    x-apievangelist-phrasing:
      intent: List failed jobs
      effect: read
      questions:
      - Which background jobs failed?
      - How do I find jobs that errored so I can retry them?
      instructions:
      - text: List the failed jobs.
      - text: Show page {page} of jobs that failed.
        slots:
          page: query.page
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/jobs/{jobId}/status'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a job's status and progress
      effect: read
      questions:
      - What is the progress and state of a specific background job?
      - Has my job finished, and what result did it produce?
      instructions:
      - text: Get the status of job {jobId}.
        slots:
          jobId: path.jobId
      - text: Show progress and results for job {jobId}.
        slots:
          jobId: path.jobId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/jobs/queues'].get
  update:
    x-apievangelist-phrasing:
      intent: List available job queues
      effect: read
      questions:
      - Which job queues can I submit background jobs to?
      - What queue names does the job system expose?
      instructions:
      - text: List the available job queues.
      - text: Show me every queue name I can post jobs to.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/jobs'].get
  update:
    x-apievangelist-phrasing:
      intent: List all jobs regardless of state
      effect: read
      questions:
      - How do I see every job in the queue system no matter its state?
      - Can I paginate through the full job history?
      instructions:
      - text: List all jobs in any state.
      - text: Show page {page} of all jobs with {pageSize} per page.
        slots:
          page: query.page
          pageSize: query.pageSize
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/jobs/{jobId}/monitor'].get
  update:
    x-apievangelist-phrasing:
      intent: Stream live progress updates for a job
      effect: read
      questions:
      - How do I watch a job's progress in real time with server-sent events?
      - Can I get a live stream of status changes for a running job?
      instructions:
      - text: Stream live updates for job {jobId}.
        slots:
          jobId: path.jobId
      - text: Open a server-sent events connection to monitor job {jobId}.
        slots:
          jobId: path.jobId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/jobs/successful'].get
  update:
    x-apievangelist-phrasing:
      intent: List successfully finished jobs
      effect: read
      questions:
      - Which jobs finished successfully?
      - Can I list only the jobs that succeeded, excluding failures?
      instructions:
      - text: List the successful jobs.
      - text: Show page {page} of jobs that succeeded.
        slots:
          page: query.page
      method: generated
      generated: '2026-09-26'