# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Cogny Reports API
  version: 1.0.0
extends: openapi/cogny-reports-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: 6
- target: $.paths['/reports'].get
  update:
    x-apievangelist-phrasing:
      intent: List growth reports
      effect: read
      questions:
      - Which growth reports have I generated so far in Cogny?
      - Can I see only the reports that ran against one particular warehouse?
      - What reports were created within a given date range, and which are still running?
      instructions:
      - text: List all my growth reports.
      - text: List reports for warehouse {warehouse_id} with status {status}.
        slots:
          warehouse_id: query.warehouse_id
          status: query.status
      - text: Show reports created after {created_after} and before {created_before}.
        slots:
          created_after: query.created_after
          created_before: query.created_before
      method: generated
      generated: '2026-10-01'
- target: $.paths['/reports'].post
  update:
    x-apievangelist-phrasing:
      intent: Start an AI-generated growth report
      effect: write
      questions:
      - How do I ask a plain-English question and get an AI growth report from my warehouse data?
      - Can I give extra context along with my prompt when generating a new report?
      instructions:
      - text: 'Generate a new report on warehouse {warehouse_id} answering: {prompt}'
        slots:
          warehouse_id: requestBody.warehouse_id
          prompt: requestBody.prompt
      - text: 'Kick off a growth report over {warehouse_id} for "{prompt}" using this background: {context}.'
        slots:
          warehouse_id: requestBody.warehouse_id
          prompt: requestBody.prompt
          context: requestBody.context
      method: generated
      generated: '2026-10-01'
- target: $.paths['/reports/{report_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Check a report's status
      effect: read
      questions:
      - Is my growth report finished yet or still generating?
      - What's the current state of a report I started earlier?
      instructions:
      - text: Check the status of report {report_id}.
        slots:
          report_id: path.report_id
      - text: Tell me whether report {report_id} has completed or failed.
        slots:
          report_id: path.report_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/reports/{report_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Cancel a report in progress
      effect: destructive
      questions:
      - Can I stop a growth report that's taking too long to generate?
      - How do I cancel a report I kicked off by mistake?
      instructions:
      - text: Cancel report {report_id}.
        slots:
          report_id: path.report_id
      - text: Abort the generation of report {report_id} now.
        slots:
          report_id: path.report_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/reports/{report_id}/stream'].get
  update:
    x-apievangelist-phrasing:
      intent: Stream live progress of a report
      effect: read
      questions:
      - Can I watch a report's queries, insights and charts appear live as it's being generated?
      - What events does the server-sent events feed emit while a report is building?
      instructions:
      - text: Stream the live generation events for report {report_id}.
        slots:
          report_id: path.report_id
      - text: Follow report {report_id} over SSE until it completes or errors.
        slots:
          report_id: path.report_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/reports/{report_id}/content'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a finished report's content
      effect: read
      questions:
      - Where do I fetch the full findings of a completed growth report?
      - Can I pull the final written content of a report once it's done?
      instructions:
      - text: Fetch the content of report {report_id}.
        slots:
          report_id: path.report_id
      - text: Give me the full findings from finished report {report_id}.
        slots:
          report_id: path.report_id
      method: generated
      generated: '2026-10-01'