# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Chef Automate API Documentation Config Mgmt API
  version: 1.0.0
extends: openapi/progress-software-configmgmt-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: 25
- target: $.paths['/api/beta/cfgmgmt/rollouts/create'].post
  update:
    x-apievangelist-phrasing:
      intent: Record a policy rollout
      effect: write
      questions:
      - How can a CI job record that a new policy revision is being rolled out to a policy group?
      - Can I attach the SCM commit and author details to a rollout record in Chef Automate?
      instructions:
      - text: Create a rollout record for policy {policy_name} revision {policy_revision_id} on policy group {policy_node_group}.
        slots:
          policy_name: requestBody.policy_name
          policy_revision_id: requestBody.policy_revision_id
          policy_node_group: requestBody.policy_node_group
      - text: Log a new rollout from CI job {ci_job_id} with commit {policy_scm_commit}.
        slots:
          ci_job_id: requestBody.ci_job_id
          policy_scm_commit: requestBody.policy_scm_commit
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/beta/cfgmgmt/rollouts/find'].get
  update:
    x-apievangelist-phrasing:
      intent: Find the rollout matching a policy revision
      effect: read
      questions:
      - Which rollout does a given policy name, policy group and revision belong to?
      - Can I look up the rollout a Chef Infra Client run was part of from its policy revision?
      instructions:
      - text: Find the rollout for policy {policy_name} in group {policy_group} at revision {policy_revision_id}.
        slots:
          policy_name: query.policy_name
          policy_group: query.policy_group
          policy_revision_id: query.policy_revision_id
      - text: Look up which rollout delivered revision {policy_revision_id}.
        slots:
          policy_revision_id: query.policy_revision_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/beta/cfgmgmt/rollouts/list'].get
  update:
    x-apievangelist-phrasing:
      intent: List policy rollouts
      effect: read
      questions:
      - What policy rollouts have been recorded so far?
      - Can I filter the list of rollouts to just the ones I care about?
      instructions:
      - text: List all recorded policy rollouts.
      - text: List rollouts matching filter {filter}.
        slots:
          filter: query.filter
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/beta/cfgmgmt/rollouts/progress_by_node_segment'].get
  update:
    x-apievangelist-phrasing:
      intent: Show rollout progress by node segment
      effect: read
      questions:
      - How far along is each node segment in picking up the latest policy rollout?
      - Where can I see rollout progress grouped by policy group segment?
      instructions:
      - text: Show rollout progress for every node segment.
      - text: Show rollout progress by node segment filtered by {filter}.
        slots:
          filter: query.filter
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/beta/cfgmgmt/rollouts/rollout/{rollout_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a rollout by ID
      effect: read
      questions:
      - What are the details of one specific rollout if I have its ID?
      - Can I fetch a single rollout record directly?
      instructions:
      - text: Get rollout {rollout_id}.
        slots:
          rollout_id: path.rollout_id
      - text: Show me the details of rollout {rollout_id}.
        slots:
          rollout_id: path.rollout_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/beta/cfgmgmt/rollouts/test_create'].post
  update:
    x-apievangelist-phrasing:
      intent: Test rollout ingestion connectivity
      effect: read
      questions:
      - Is there a no-op call to check my CI client can reach the rollout endpoint with the right auth?
      - Can I verify end-to-end connectivity before creating real rollout records?
      instructions:
      - text: Run the rollout test call to confirm my client config and permissions work.
      - text: Check connectivity to rollout ingestion without creating a rollout.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v0/cfgmgmt/errors'].get
  update:
    x-apievangelist-phrasing:
      intent: List the most common Chef run errors
      effect: read
      questions:
      - What are the most common errors on my nodes' latest Chef Infra Client runs?
      - Can I limit how many top run errors come back?
      instructions:
      - text: List the top {size} errors from nodes' most recent Chef runs.
        slots:
          size: query.size
      - text: Show the most common Chef Infra run errors for nodes matching {filter}.
        slots:
          filter: query.filter
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v0/cfgmgmt/node_metadata_counts'].get
  update:
    x-apievangelist-phrasing:
      intent: Count nodes by metadata field value
      effect: read
      questions:
      - How many of my infra nodes run each platform?
      - Can I get a breakdown of distinct values for a node field like platform or environment?
      instructions:
      - text: Count nodes by each distinct value of {type}.
        slots:
          type: query.type
      - text: Break down nodes by {type} between {start} and {end}.
        slots:
          type: query.type
          start: query.start
          end: query.end
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v0/cfgmgmt/node_runs_daily_status_time_series'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a node's daily run status history
      effect: read
      questions:
      - Did a particular node have a failed run on each of the last several days?
      - What does a day-by-day run status timeline look like for one node?
      instructions:
      - text: Show the daily run status for node {node_id} over the last {days_ago} days.
        slots:
          node_id: query.node_id
          days_ago: query.days_ago
      - text: Give me the 24-hour run status series for node {node_id}.
        slots:
          node_id: query.node_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v0/cfgmgmt/nodes'].get
  update:
    x-apievangelist-phrasing:
      intent: List checked-in infra nodes
      effect: read
      questions:
      - Which infra nodes have checked in to Chef Automate?
      - Can I page and sort the list of checked-in nodes by a field?
      - Are filters on the same field combined with OR when listing nodes?
      instructions:
      - text: List checked-in nodes matching {filter}.
        slots:
          filter: query.filter
      - text: List checked-in nodes page {page}, sorted by {sort_field}.
        slots:
          page: query.pagination.page
          sort_field: query.sorting.field
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v0/cfgmgmt/nodes/export'].post
  update:
    x-apievangelist-phrasing:
      intent: Export nodes as JSON or CSV
      effect: read
      questions:
      - How do I download my full node list as a CSV file?
      - Can a node export be filtered and sorted even though it isn't paginated?
      instructions:
      - text: Export all nodes as {output_type}.
        slots:
          output_type: requestBody.output_type
      - text: Export nodes matching {filter} to CSV.
        slots:
          filter: requestBody.filter
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v0/cfgmgmt/nodes/{node_id}/attribute'].get
  update:
    x-apievangelist-phrasing:
      intent: Show a node's latest attributes
      effect: read
      questions:
      - What attributes did a node last report?
      - Where do I see the latest Ohai attributes for one node?
      instructions:
      - text: Show the latest attributes for node {node_id}.
        slots:
          node_id: path.node_id
      - text: Get the reported attribute data of node {node_id}.
        slots:
          node_id: path.node_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v0/cfgmgmt/nodes/{node_id}/runs'].get
  update:
    x-apievangelist-phrasing:
      intent: List a node's Chef runs
      effect: read
      questions:
      - What runs has a specific node done, with their start, end and status?
      - Can I list only one node's failed runs since a certain date?
      instructions:
      - text: List runs for node {node_id} since {start}.
        slots:
          node_id: path.node_id
          start: query.start
      - text: List node {node_id}'s runs matching {filter}.
        slots:
          node_id: path.node_id
          filter: query.filter
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v0/cfgmgmt/nodes/{node_id}/runs/{run_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Show one Chef run report for a node
      effect: read
      questions:
      - How can I see the full report of a single run on a node?
      - What resources changed during a particular Chef Infra run?
      instructions:
      - text: Show run {run_id} for node {node_id}.
        slots:
          run_id: path.run_id
          node_id: path.node_id
      - text: Open the run report {run_id} on node {node_id} that ended at {end_time}.
        slots:
          run_id: path.run_id
          node_id: path.node_id
          end_time: query.end_time
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v0/cfgmgmt/organizations'].get
  update:
    x-apievangelist-phrasing:
      intent: List organizations of checked-in nodes
      effect: read
      questions:
      - Which Chef organizations do my checked-in nodes belong to?
      - Can I see every org that has nodes reporting in?
      instructions:
      - text: List all organizations with nodes reporting in.
      - text: Show me the Chef orgs associated with checked-in nodes.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v0/cfgmgmt/policy_revision/{revision_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: List cookbooks for a policy revision
      effect: read
      questions:
      - Which cookbooks were part of a specific policy revision?
      - Can I map a policy revision ID from a run to its cookbook names?
      instructions:
      - text: List the cookbooks in policy revision {revision_id}.
        slots:
          revision_id: path.revision_id
      - text: Show policy names and cookbook identifiers for revision {revision_id}.
        slots:
          revision_id: path.revision_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v0/cfgmgmt/reports/export'].post
  update:
    x-apievangelist-phrasing:
      intent: Export node run reports
      effect: read
      questions:
      - How do I export run reports for a node as CSV?
      - Can I export run reports for a date range without pagination?
      instructions:
      - text: Export run reports for node {node_id} from {start} to {end}.
        slots:
          node_id: requestBody.node_id
          start: requestBody.start
          end: requestBody.end
      - text: Export node run reports as {output_type}.
        slots:
          output_type: requestBody.output_type
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v0/cfgmgmt/source_fqdns'].get
  update:
    x-apievangelist-phrasing:
      intent: List Chef Infra Servers with nodes
      effect: read
      questions:
      - Which Chef Infra Servers have nodes checking in?
      - What server FQDNs are associated with my reporting nodes?
      instructions:
      - text: List the Chef Infra Servers associated with checked-in nodes.
      - text: Show the source FQDNs of all reporting nodes.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v0/cfgmgmt/stats/checkin_counts_timeseries'].get
  update:
    x-apievangelist-phrasing:
      intent: Get daily unique node check-in counts
      effect: read
      questions:
      - How many unique nodes checked in each day this past week?
      - What does the daily node check-in trend look like?
      instructions:
      - text: Show daily unique node check-ins for the last {days_ago} days.
        slots:
          days_ago: query.days_ago
      - text: Chart node check-ins per day for nodes matching {filter}.
        slots:
          filter: query.filter
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v0/cfgmgmt/stats/missing_node_duration_counts'].get
  update:
    x-apievangelist-phrasing:
      intent: Count missing nodes by duration
      effect: read
      questions:
      - How many nodes have been missing for more than a week or a month?
      - Can I count missing nodes across several time windows at once?
      instructions:
      - text: Count nodes missing for {durations}.
        slots:
          durations: query.durations
      - text: Show how many nodes went missing over 3 days, 1 week and 1 month.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v0/cfgmgmt/stats/node_counts'].get
  update:
    x-apievangelist-phrasing:
      intent: Count nodes by run status
      effect: read
      questions:
      - How many of my infra nodes are failing, succeeding or missing?
      - What's the total node count matching a name filter?
      instructions:
      - text: Count failed, successful and missing nodes.
      - text: Give node status totals for nodes matching {filter}.
        slots:
          filter: query.filter
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v0/cfgmgmt/stats/run_counts'].get
  update:
    x-apievangelist-phrasing:
      intent: Count a node's successful and failed runs
      effect: read
      questions:
      - How many runs on a given node failed versus succeeded?
      - Can I total a node's run outcomes since a start date?
      instructions:
      - text: Count failed and successful runs for node {node_id} since {start}.
        slots:
          node_id: query.node_id
          start: query.start
      - text: Total the run outcomes for node {node_id}.
        slots:
          node_id: query.node_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v0/cfgmgmt/suggestions'].get
  update:
    x-apievangelist-phrasing:
      intent: Suggest node filter values
      effect: read
      questions:
      - What values can I use when filtering nodes by a field like platform?
      - Does the node filter typeahead support wildcards?
      instructions:
      - text: Suggest {type} values starting with {text}.
        slots:
          type: query.type
          text: query.text
      - text: List possible filter values for {type}.
        slots:
          type: query.type
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v0/cfgmgmt/telemetry/nodes/count'].get
  update:
    x-apievangelist-phrasing:
      intent: Count unique nodes for telemetry
      effect: read
      questions:
      - How many unique nodes ran since telemetry was last sent?
      - Where do I get the node usage count used for telemetry reporting?
      instructions:
      - text: Get the unique node usage count for telemetry.
      - text: Count distinct nodes with a last run since the last telemetry report.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v0/cfgmgmt/telemetry/nodes/count/updated'].put
  update:
    x-apievangelist-phrasing:
      intent: Mark node telemetry as reported
      effect: write
      questions:
      - How do I acknowledge that node usage telemetry has been sent?
      - Can I update the date telemetry for client runs was last reported?
      instructions:
      - text: Set the last telemetry reported date to {last_telemetry_reported_at}.
        slots:
          last_telemetry_reported_at: requestBody.last_telemetry_reported_at
      - text: Acknowledge that node usage telemetry was reported just now.
      method: generated
      generated: '2026-10-01'