# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Forge Scheduled Jobs API
  version: 1.0.0
extends: openapi/laravel-scheduled-jobs-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-10-01'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 10
- target: $.paths['/orgs/{organization}/servers/{server}/scheduled-jobs'].get
  update:
    x-apievangelist-phrasing:
      intent: List a server's scheduled jobs
      effect: read
      questions:
      - What cron jobs are scheduled on my server?
      - Can I filter a server's scheduled jobs by status or by the user they run as?
      instructions:
      - text: List the scheduled jobs on server {server} in {organization}.
        slots:
          server: path.server
          organization: path.organization
      - text: Show server-level scheduled jobs on {server} in {organization} that run as {user}.
        slots:
          server: path.server
          organization: path.organization
          user: query.filter[user]
      method: generated
      generated: '2026-10-01'
- target: $.paths['/orgs/{organization}/servers/{server}/scheduled-jobs'].post
  update:
    x-apievangelist-phrasing:
      intent: Schedule a cron job on a server
      effect: write
      questions:
      - How do I add a cron job to a server that isn't tied to a site?
      - Can a server scheduled job use a custom cron expression and a heartbeat?
      instructions:
      - text: Schedule {command} on server {server} in {organization} to run {frequency} as {user}.
        slots:
          command: requestBody.command
          server: path.server
          organization: path.organization
          frequency: requestBody.frequency
          user: requestBody.user
      - text: Create a server cron job on {server} in {organization} running {command} as {user} with frequency {frequency} and cron {cron}.
        slots:
          server: path.server
          organization: path.organization
          command: requestBody.command
          user: requestBody.user
          frequency: requestBody.frequency
          cron: requestBody.cron
      method: generated
      generated: '2026-10-01'
- target: $.paths['/orgs/{organization}/servers/{server}/scheduled-jobs/{job}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a server scheduled job
      effect: read
      questions:
      - What command and schedule does one server cron job have?
      - Can I look up a server-level scheduled job by ID?
      instructions:
      - text: Show scheduled job {job} on server {server} in {organization}.
        slots:
          job: path.job
          server: path.server
          organization: path.organization
      - text: Get server cron job {job} details on {server} in {organization}.
        slots:
          job: path.job
          server: path.server
          organization: path.organization
      method: generated
      generated: '2026-10-01'
- target: $.paths['/orgs/{organization}/servers/{server}/scheduled-jobs/{job}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a server scheduled job
      effect: destructive
      questions:
      - How do I remove a cron job from my server?
      - Can I delete a server scheduled job without touching site jobs?
      instructions:
      - text: Delete scheduled job {job} from server {server} in {organization}.
        slots:
          job: path.job
          server: path.server
          organization: path.organization
      - text: Remove server cron job {job} on {server} in {organization}.
        slots:
          job: path.job
          server: path.server
          organization: path.organization
      method: generated
      generated: '2026-10-01'
- target: $.paths['/orgs/{organization}/servers/{server}/scheduled-jobs/{job}/output'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a server scheduled job's output
      effect: read
      questions:
      - What did my server cron job print the last time it ran?
      - Can I read the output of a scheduled job on a server?
      instructions:
      - text: Show the output of scheduled job {job} on server {server} in {organization}.
        slots:
          job: path.job
          server: path.server
          organization: path.organization
      - text: Fetch what server cron job {job} on {server} in {organization} last printed.
        slots:
          job: path.job
          server: path.server
          organization: path.organization
      method: generated
      generated: '2026-10-01'
- target: $.paths['/orgs/{organization}/servers/{server}/sites/{site}/scheduled-jobs'].get
  update:
    x-apievangelist-phrasing:
      intent: List a site's scheduled jobs
      effect: read
      questions:
      - Which scheduled jobs belong to one particular site?
      - Can I list a site's cron jobs filtered by status?
      instructions:
      - text: List the scheduled jobs for site {site} on server {server} in {organization}.
        slots:
          site: path.site
          server: path.server
          organization: path.organization
      - text: Show site {site}'s scheduled jobs on {server} in {organization} with status {status}.
        slots:
          site: path.site
          server: path.server
          organization: path.organization
          status: query.filter[status]
      method: generated
      generated: '2026-10-01'
- target: $.paths['/orgs/{organization}/servers/{server}/sites/{site}/scheduled-jobs'].post
  update:
    x-apievangelist-phrasing:
      intent: Schedule a cron job for a site
      effect: write
      questions:
      - How do I add a scheduled task that belongs to a specific site?
      - Can a site's scheduled job ping a heartbeat with a grace period?
      instructions:
      - text: Schedule {command} for site {site} on server {server} in {organization} to run {frequency} as {user}.
        slots:
          command: requestBody.command
          site: path.site
          server: path.server
          organization: path.organization
          frequency: requestBody.frequency
          user: requestBody.user
      - text: 'Create a site cron job for {site} on {server} in {organization}: {command} as {user}, frequency {frequency}, cron {cron}.'
        slots:
          site: path.site
          server: path.server
          organization: path.organization
          command: requestBody.command
          user: requestBody.user
          frequency: requestBody.frequency
          cron: requestBody.cron
      method: generated
      generated: '2026-10-01'
- target: $.paths['/orgs/{organization}/servers/{server}/sites/{site}/scheduled-jobs/{job}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a site scheduled job
      effect: read
      questions:
      - What schedule is a particular site cron job using?
      - Can I fetch one of a site's scheduled jobs by its ID?
      instructions:
      - text: Show scheduled job {job} for site {site} on server {server} in {organization}.
        slots:
          job: path.job
          site: path.site
          server: path.server
          organization: path.organization
      - text: Get site cron job {job} on site {site}, server {server}, org {organization}.
        slots:
          job: path.job
          site: path.site
          server: path.server
          organization: path.organization
      method: generated
      generated: '2026-10-01'
- target: $.paths['/orgs/{organization}/servers/{server}/sites/{site}/scheduled-jobs/{job}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a site scheduled job
      effect: destructive
      questions:
      - How do I remove a scheduled task from a site?
      - Can I delete one site cron job and leave the server's jobs alone?
      instructions:
      - text: Delete scheduled job {job} from site {site} on server {server} in {organization}.
        slots:
          job: path.job
          site: path.site
          server: path.server
          organization: path.organization
      - text: Remove site cron job {job} from {site} on {server} in {organization}.
        slots:
          job: path.job
          site: path.site
          server: path.server
          organization: path.organization
      method: generated
      generated: '2026-10-01'
- target: $.paths['/orgs/{organization}/servers/{server}/sites/{site}/scheduled-jobs/{job}/output'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a site scheduled job's output
      effect: read
      questions:
      - What did a site's scheduled task output on its last run?
      - Can I see the output of a cron job attached to a site?
      instructions:
      - text: Show the output of scheduled job {job} for site {site} on server {server} in {organization}.
        slots:
          job: path.job
          site: path.site
          server: path.server
          organization: path.organization
      - text: Fetch the last run output of site cron job {job} on {site}, server {server}, org {organization}.
        slots:
          job: path.job
          site: path.site
          server: path.server
          organization: path.organization
      method: generated
      generated: '2026-10-01'