# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Here Batch jobs API
  version: 1.0.0
extends: openapi/here-batch-jobs-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: 18
- target: $.paths['/batch/jobs'].get
  update:
    x-apievangelist-phrasing:
      intent: List batch jobs filtered by status or tag
      effect: read
      questions:
      - Which of my batch jobs are still running?
      - Can I filter my batch jobs by tag and page through them?
      instructions:
      - text: List my batch jobs with status {status}.
        slots:
          status: query.status
      - text: Show batch jobs tagged {tag}, {limit} at a time.
        slots:
          tag: query.tag
          limit: query.limit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/batch/jobs'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a batch job for a service
      effect: write
      questions:
      - How do I submit a batch job against a HERE service?
      - Can a new batch job start immediately after it's created?
      instructions:
      - text: Create a batch job for service {service_hrn} tagged {tag}.
        slots:
          service_hrn: query.serviceHrn
          tag: query.tag
      - text: Create and start a batch job for service {service_hrn} with start job set to {start_job}.
        slots:
          service_hrn: query.serviceHrn
          start_job: query.startJob
      method: generated
      generated: '2026-09-26'
- target: $.paths['/batch/jobs'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete all batch jobs matching a status
      effect: destructive
      questions:
      - Can I bulk delete every finished batch job at once?
      - What happens if no jobs match my delete filter?
      instructions:
      - text: Delete all my batch jobs with status {status}.
        slots:
          status: query.status
      - text: Bulk delete batch jobs in status {status} tagged {tag}.
        slots:
          status: query.status
          tag: query.tag
      method: generated
      generated: '2026-09-26'
- target: $.paths['/batch/jobs/{jobId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a batch job's details
      effect: read
      questions:
      - What are the details of one of my batch jobs?
      - How do I check the current state of a single batch job?
      instructions:
      - text: Show the details of batch job {job_id}.
        slots:
          job_id: path.jobId
      - text: Get the current status of batch job {job_id}.
        slots:
          job_id: path.jobId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/batch/jobs/{jobId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete one batch job
      effect: destructive
      questions:
      - Can I delete a single batch job by its ID?
      - Is there a way to remove just one batch job I created?
      instructions:
      - text: Delete batch job {job_id}.
        slots:
          job_id: path.jobId
      - text: Remove the batch job with ID {job_id}.
        slots:
          job_id: path.jobId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/batch/jobs/{jobId}/errors'].get
  update:
    x-apievangelist-phrasing:
      intent: Download a batch job's errors
      effect: read
      questions:
      - Where do I get the errors from a batch job that finished with failures?
      - What happens if I request errors before a job has any?
      instructions:
      - text: Download the errors for batch job {job_id}.
        slots:
          job_id: path.jobId
      - text: Stream the error output of completed batch job {job_id}.
        slots:
          job_id: path.jobId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/batch/jobs/{jobId}/results'].get
  update:
    x-apievangelist-phrasing:
      intent: Download a batch job's results
      effect: read
      questions:
      - How can I download the output of a batch job that succeeded?
      - Are batch job results returned as a downloadable stream?
      instructions:
      - text: Download the results of batch job {job_id}.
        slots:
          job_id: path.jobId
      - text: Fetch the result stream for completed batch job {job_id}.
        slots:
          job_id: path.jobId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/batch/jobs/{jobId}/start'].put
  update:
    x-apievangelist-phrasing:
      intent: Start a batch job
      effect: write
      questions:
      - What happens if I start a batch job that's already running?
      - Can I schedule a created batch job for immediate execution?
      instructions:
      - text: Start batch job {job_id} now.
        slots:
          job_id: path.jobId
      - text: Schedule batch job {job_id} for immediate execution.
        slots:
          job_id: path.jobId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/batch/jobs/{jobId}/stop'].put
  update:
    x-apievangelist-phrasing:
      intent: Stop a running batch job
      effect: write
      questions:
      - Can I halt a batch job that is in progress?
      - Does stopping a job that isn't running return an error?
      instructions:
      - text: Stop batch job {job_id}.
        slots:
          job_id: path.jobId
      - text: Halt the running batch job {job_id}.
        slots:
          job_id: path.jobId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/jobs'].get
  update:
    x-apievangelist-phrasing:
      intent: List jobs via the unfiltered jobs endpoint
      effect: read
      questions:
      - Is there a simple jobs list at the top-level jobs path with no filters?
      - Which batch jobs does the plain /jobs listing return?
      instructions:
      - text: List all jobs from the top-level jobs endpoint.
      - text: Show every job on the /jobs route without filters.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/jobs'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a job via the top-level jobs endpoint
      effect: write
      questions:
      - Can I create a batch job on the /jobs path instead of /batch/jobs?
      - What does posting to the top-level jobs route do?
      instructions:
      - text: Create a new job using the top-level /jobs endpoint.
      - text: Submit a job to the plain jobs route.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/jobs'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete jobs via the top-level jobs endpoint
      effect: destructive
      questions:
      - Can I delete multiple jobs through the /jobs route?
      - Does the top-level jobs path support bulk deletion without a status filter?
      instructions:
      - text: Delete multiple jobs using the top-level /jobs endpoint.
      - text: Bulk remove jobs through the plain jobs route.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/jobs/{jobId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a job's status via the /jobs route
      effect: read
      questions:
      - How do I check a job's status on the top-level /jobs path?
      - Can I read one job's status from the plain jobs route?
      instructions:
      - text: Get the status of job {job_id} from the /jobs endpoint.
        slots:
          job_id: path.jobId
      - text: Check job {job_id} using the top-level jobs route.
        slots:
          job_id: path.jobId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/jobs/{jobId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a job via the /jobs route
      effect: destructive
      questions:
      - Can I delete one job through the top-level /jobs path?
      - Is deleting a job on the plain jobs route permanent?
      instructions:
      - text: Delete job {job_id} using the /jobs endpoint.
        slots:
          job_id: path.jobId
      - text: Remove job {job_id} through the top-level jobs route.
        slots:
          job_id: path.jobId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/jobs/{jobId}/start'].put
  update:
    x-apievangelist-phrasing:
      intent: Start a job via the /jobs route
      effect: write
      questions:
      - Can I start a job on the top-level /jobs path?
      - Which call kicks off a job through the plain jobs route?
      instructions:
      - text: Start job {job_id} using the /jobs endpoint.
        slots:
          job_id: path.jobId
      - text: Kick off job {job_id} through the top-level jobs route.
        slots:
          job_id: path.jobId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/jobs/{jobId}/stop'].put
  update:
    x-apievangelist-phrasing:
      intent: Stop a job via the /jobs route
      effect: write
      questions:
      - Can I stop a job on the top-level /jobs path?
      - Which call halts a job through the plain jobs route?
      instructions:
      - text: Stop job {job_id} using the /jobs endpoint.
        slots:
          job_id: path.jobId
      - text: Halt job {job_id} through the top-level jobs route.
        slots:
          job_id: path.jobId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/jobs/{jobId}/results'].get
  update:
    x-apievangelist-phrasing:
      intent: Get job results via the /jobs route
      effect: read
      questions:
      - Where are a job's results on the top-level /jobs path?
      - Can I retrieve job output from the plain jobs route?
      instructions:
      - text: Get the results of job {job_id} from the /jobs endpoint.
        slots:
          job_id: path.jobId
      - text: Retrieve job {job_id} output through the top-level jobs route.
        slots:
          job_id: path.jobId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/jobs/{jobId}/errors'].get
  update:
    x-apievangelist-phrasing:
      intent: Get job errors via the /jobs route
      effect: read
      questions:
      - Where are a job's errors on the top-level /jobs path?
      - Can I retrieve job failures from the plain jobs route?
      instructions:
      - text: Get the errors of job {job_id} from the /jobs endpoint.
        slots:
          job_id: path.jobId
      - text: Retrieve job {job_id} failures through the top-level jobs route.
        slots:
          job_id: path.jobId
      method: generated
      generated: '2026-09-26'