# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Perigon News & Stories API
  version: 1.0.0
extends: openapi/perigon-news-stories-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: 8
- target: $.paths['/v1/articles/all'].get
  update:
    x-apievangelist-phrasing:
      intent: Search news articles
      effect: read
      questions:
      - How do I search news articles by keyword, source and date range?
      - Can I find articles that mention a specific company or person?
      - Is it possible to filter news articles by sentiment or language?
      instructions:
      - text: Find news articles about {q} published since {from}.
        slots:
          q: query.q
          from: query.from
      - text: Search articles mentioning {companyName} from {source}.
        slots:
          companyName: query.companyName
          source: query.source
      - text: Get {language} articles in category {category} sorted by {sortBy}.
        slots:
          language: query.language
          category: query.category
          sortBy: query.sortBy
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/articles/refresh/jobs'].post
  update:
    x-apievangelist-phrasing:
      intent: Queue articles for a background refresh
      effect: write
      questions:
      - How do I ask for updated data on a batch of articles I already have?
      - Can I schedule a refresh for articles that aren't in the fresh cache yet?
      instructions:
      - text: Submit a refresh job for articles {articleIds}.
        slots:
          articleIds: requestBody.articleIds
      - text: Start a background refresh of article IDs {articleIds} and give me the job id.
        slots:
          articleIds: requestBody.articleIds
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/articles/refresh/jobs/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Check an article refresh job's status
      effect: read
      questions:
      - Is my article refresh job finished yet?
      - Can I see partial results from a refresh job while it is still running?
      instructions:
      - text: Check the status of refresh job {id}.
        slots:
          id: path.id
      - text: Get the per-article results computed so far for refresh job {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/articles/refresh/peek'].post
  update:
    x-apievangelist-phrasing:
      intent: Peek at cached refreshed article data
      effect: read
      questions:
      - Can I see already-cached refreshed article data without starting a new job?
      - What refreshed data is available right now for some articles, best effort?
      instructions:
      - text: Peek at cached refresh data for articles {articleIds} without queuing a job.
        slots:
          articleIds: requestBody.articleIds
      - text: Return whatever refreshed data is already cached for {articleIds}.
        slots:
          articleIds: requestBody.articleIds
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/stories/all'].get
  update:
    x-apievangelist-phrasing:
      intent: Search clustered news stories
      effect: read
      questions:
      - How can I follow an evolving news story rather than individual articles?
      - Which top stories right now involve a particular company?
      - Can I limit stories to ones covered by a minimum number of unique sources?
      instructions:
      - text: Find news stories about {q} updated since {updatedFrom}.
        slots:
          q: query.q
          updatedFrom: query.updatedFrom
      - text: Show stories involving {companyName} covered by at least {minUniqueSources} sources.
        slots:
          companyName: query.companyName
          minUniqueSources: query.minUniqueSources
      - text: List top stories in {country} for topic {topic}.
        slots:
          country: query.country
          topic: query.topic
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/stories/history'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a story's past versions and changelog
      effect: read
      questions:
      - How has a news story's summary changed over time?
      - Can I see the changelog for previous versions of a story cluster?
      instructions:
      - text: Show the version history of story {clusterId}.
        slots:
          clusterId: query.clusterId
      - text: Get earlier versions of story {clusterId} between {from} and {to} that include a changelog.
        slots:
          clusterId: query.clusterId
          from: query.from
          to: query.to
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/stories/stats'].get
  update:
    x-apievangelist-phrasing:
      intent: Count stories over time
      effect: read
      questions:
      - How many news stories about a topic appeared each day this month?
      - Can I chart story volume by week or by hour?
      instructions:
      - text: Count stories about {q} grouped by {splitBy}.
        slots:
          q: query.q
          splitBy: query.splitBy
      - text: Give me story counts per {splitBy} for {companyName} since {from}.
        slots:
          splitBy: query.splitBy
          companyName: query.companyName
          from: query.from
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/vector/news/all'].post
  update:
    x-apievangelist-phrasing:
      intent: Semantic search over recent news
      effect: read
      questions:
      - Can I search news with a natural-language question instead of keywords?
      - How far back does the semantic news search go?
      instructions:
      - text: Run a semantic news search for {prompt}.
        slots:
          prompt: requestBody.prompt
      - text: Find the news articles most relevant to {prompt} published after {pubDateFrom}.
        slots:
          prompt: requestBody.prompt
          pubDateFrom: requestBody.pubDateFrom
      method: generated
      generated: '2026-10-01'