# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Redocly Scout Tasks API
  version: 1.0.0
extends: openapi/redocly-tasks-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: 4
- target: $.paths['/orgs/{orgId}/projects/{projectId}/scout/tasks'].get
  update:
    x-apievangelist-phrasing:
      intent: List Scout tasks for a project
      effect: read
      questions:
      - Which Scout tasks exist for my Redocly project right now?
      - Can I sort and filter the list of Scout tasks and page through it with a limit?
      - What jobs has Scout queued or processed for this project?
      instructions:
      - text: List all Scout tasks for project {projectId} in organization {orgId}.
        slots:
          projectId: path.projectId
          orgId: path.orgId
      - text: Show the first {limit} Scout tasks in project {projectId} of org {orgId} matching filter {filter}.
        slots:
          limit: query.limit
          projectId: path.projectId
          orgId: path.orgId
          filter: query.filter
      - text: Get the next page of Scout tasks after cursor {after} for project {projectId} in org {orgId}.
        slots:
          after: query.after
          projectId: path.projectId
          orgId: path.orgId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/orgs/{orgId}/projects/{projectId}/scout/tasks'].post
  update:
    x-apievangelist-phrasing:
      intent: Claim and start the next available Scout job
      effect: write
      questions:
      - Can a Scout worker pull the next available job off the queue and start processing it?
      - What happens when Scout asks for the next job to process in a project?
      instructions:
      - text: Claim and start the next available Scout job for project {projectId} in org {orgId}.
        slots:
          projectId: path.projectId
          orgId: path.orgId
      - text: Have Scout pick up whatever job is next in the queue for project {projectId} in organization {orgId}.
        slots:
          projectId: path.projectId
          orgId: path.orgId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/orgs/{orgId}/projects/{projectId}/scout/tasks/{jobId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one Scout task by its job ID
      effect: read
      questions:
      - Where can I look up the details of a single Scout task using its job ID?
      - What is the current state of one specific Scout job?
      instructions:
      - text: Get Scout task {jobId} in project {projectId} of org {orgId}.
        slots:
          jobId: path.jobId
          projectId: path.projectId
          orgId: path.orgId
      - text: Show me the details of job {jobId} for project {projectId} in organization {orgId}.
        slots:
          jobId: path.jobId
          projectId: path.projectId
          orgId: path.orgId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/orgs/{orgId}/projects/{projectId}/scout/tasks/{jobId}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Mark a processing Scout job completed or failed
      effect: write
      questions:
      - How do I report that a Scout job finished, either completed or failed?
      - Can a job's status move back to processing, or only from processing to completed or failed?
      - Is there a way to attach extra metadata when closing out a Scout job?
      instructions:
      - text: Set Scout job {jobId} in project {projectId} of org {orgId} to status {status}.
        slots:
          jobId: path.jobId
          projectId: path.projectId
          orgId: path.orgId
          status: requestBody.status
      - text: Mark job {jobId} for project {projectId} in org {orgId} as {status} with metadata {metadata}.
        slots:
          jobId: path.jobId
          projectId: path.projectId
          orgId: path.orgId
          status: requestBody.status
          metadata: requestBody.metadata
      method: generated
      generated: '2026-09-26'