# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Perigon Supplemental Endpoints API
  version: 1.0.0
extends: openapi/perigon-supplemental-endpoints-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['/v1/companies/all'].get
  update:
    x-apievangelist-phrasing:
      intent: Search tracked companies
      effect: read
      questions:
      - Can I look up a company by its stock ticker or domain?
      - Which tracked companies are in a given industry and country?
      - How do I filter companies by employee count or IPO date?
      instructions:
      - text: Find the company with ticker {symbol}.
        slots:
          symbol: query.symbol
      - text: Search companies in the {industry} industry based in {country}.
        slots:
          industry: query.industry
          country: query.country
      - text: Look up the company that owns domain {domain}.
        slots:
          domain: query.domain
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/journalists/all'].get
  update:
    x-apievangelist-phrasing:
      intent: Search journalists
      effect: read
      questions:
      - How can I find journalists who cover a specific topic?
      - Which reporters write for a given news source?
      - Can I filter journalists by how often they publish each month?
      instructions:
      - text: Find journalists who cover {topic}.
        slots:
          topic: query.topic
      - text: Search for journalists named {name} writing for {source}.
        slots:
          name: query.name
          source: query.source
      - text: List journalists based in {country} who publish at least {minMonthlyPosts} pieces a month.
        slots:
          country: query.country
          minMonthlyPosts: query.minMonthlyPosts
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/journalists/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a journalist's profile
      effect: read
      questions:
      - Can I get more detail on a journalist using the ID from an article?
      - What does the full profile of a single journalist include?
      instructions:
      - text: Get the profile for journalist {id}.
        slots:
          id: path.id
      - text: Show details on the author with journalist ID {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/people/all'].get
  update:
    x-apievangelist-phrasing:
      intent: Search known people
      effect: read
      questions:
      - How do I look up a public figure mentioned in the news?
      - Can I find people by occupation, like all politicians or athletes?
      instructions:
      - text: Find the person named {name}.
        slots:
          name: query.name
      - text: Look up the person with Wikidata ID {wikidataId}.
        slots:
          wikidataId: query.wikidataId
      - text: List people whose occupation is {occupationLabel}.
        slots:
          occupationLabel: query.occupationLabel
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/sources/all'].get
  update:
    x-apievangelist-phrasing:
      intent: Search media sources
      effect: read
      questions:
      - Which news outlets are available, and can I filter them by country?
      - Can I find media sources by monthly traffic or paywall status?
      - How do I look up a news source by its domain?
      instructions:
      - text: Find the media source for domain {domain}.
        slots:
          domain: query.domain
      - text: List news sources in {sourceCountry} with at least {minMonthlyVisits} monthly visits.
        slots:
          sourceCountry: query.sourceCountry
          minMonthlyVisits: query.minMonthlyVisits
      - text: Show sources in source group {sourceGroup}.
        slots:
          sourceGroup: query.sourceGroup
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/topics/all'].get
  update:
    x-apievangelist-phrasing:
      intent: Browse available news topics
      effect: read
      questions:
      - What topics can I filter news by?
      - Which topics fall under a particular category or subcategory?
      instructions:
      - text: Search topics named {name}.
        slots:
          name: query.name
      - text: List topics in category {category}.
        slots:
          category: query.category
      method: generated
      generated: '2026-10-01'