API Evangelist conversational phrasing for APIs.io Provider Control API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for APIs.io Provider Control API
  version: 1.0.0
extends: openapi/apis-io-provider-control-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-09-26'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 13
- target: $.paths['/providers/{slug}/correction'].post
  update:
    x-apievangelist-phrasing:
      intent: Report an error in a provider's listing
      effect: write
      questions:
      - How do I tell the catalog that its listing for my company has something wrong?
      - Is reporting a listing error free, and does sending it twice file it twice?
      instructions:
      - text: 'Report that {slug}''s listing is wrong: {wrong}.'
        slots:
          slug: path.slug
          wrong: requestBody.wrong
      - text: File a correction for {slug} saying {wrong} should read {correct}, with evidence at {evidence}.
        slots:
          slug: path.slug
          wrong: requestBody.wrong
          correct: requestBody.correct
          evidence: requestBody.evidence
      method: generated
      generated: '2026-09-26'
- target: $.paths['/providers/{slug}/claim'].post
  update:
    x-apievangelist-phrasing:
      intent: Claim ownership of a provider listing
      effect: write
      questions:
      - Can I claim the listing for my own company as its owner?
      - What happens if someone else has already claimed a provider listing?
      instructions:
      - text: Claim the listing for {slug}.
        slots:
          slug: path.slug
      - text: Claim provider {slug} and send updates to {contact}.
        slots:
          slug: path.slug
          contact: requestBody.contact
      method: generated
      generated: '2026-09-26'
- target: $.paths['/providers/{slug}/facts'].post
  update:
    x-apievangelist-phrasing:
      intent: Correct a listing's name, description or tags
      effect: write
      questions:
      - Can I update the name, description or website shown on my listing?
      - Can I amend my pending change to a listing's industries and tags?
      instructions:
      - text: Submit a fact correction for {slug} setting the description to {description}.
        slots:
          slug: path.slug
          description: requestBody.description
      - text: Correct the website for {slug} to {url} and its tags to {tags}.
        slots:
          slug: path.slug
          url: requestBody.url
          tags: requestBody.tags
      method: generated
      generated: '2026-09-26'
- target: $.paths['/providers/{slug}/submit'].post
  update:
    x-apievangelist-phrasing:
      intent: Submit an artifact pointer for a listing
      effect: write
      questions:
      - How do I point the catalog at an OpenAPI or AsyncAPI my company publishes?
      - Will submitting a second spec of the same type replace the one already listed?
      instructions:
      - text: Submit the {type} at {url} for provider {slug}.
        slots:
          type: requestBody.type
          url: requestBody.url
          slug: path.slug
      - text: Add a {type} artifact pointer to {slug}'s listing from {url}.
        slots:
          type: requestBody.type
          url: requestBody.url
          slug: path.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/providers/{slug}/visibility'].post
  update:
    x-apievangelist-phrasing:
      intent: Request a restricted listing or removal
      effect: destructive
      questions:
      - Can I have my company removed from the catalog entirely?
      - What does a restricted listing keep, and is it still rated?
      instructions:
      - text: Request {visibility} visibility for {slug}.
        slots:
          visibility: requestBody.visibility
          slug: path.slug
      - text: Ask to set {slug} to {visibility} because {reason}.
        slots:
          slug: path.slug
          visibility: requestBody.visibility
          reason: requestBody.reason
      method: generated
      generated: '2026-09-26'
- target: $.paths['/providers/{slug}/dispute'].post
  update:
    x-apievangelist-phrasing:
      intent: Dispute a finding in a provider's rating
      effect: write
      questions:
      - The rating says my API lacks something it actually has; can I dispute that?
      - Do I need to claim a listing before I can contest a rating finding?
      instructions:
      - text: 'Dispute the rating finding on {slug}: {claim}.'
        slots:
          slug: path.slug
          claim: requestBody.claim
      - text: Contest {claim} for {slug} with proof at {evidence_url}.
        slots:
          claim: requestBody.claim
          slug: path.slug
          evidence_url: requestBody.evidence_url
      method: generated
      generated: '2026-09-26'
- target: $.paths['/providers/{slug}/generate'].post
  update:
    x-apievangelist-phrasing:
      intent: See which artifacts can be generated for a provider
      effect: read
      questions:
      - Which missing artifacts could be authored for my listing, and how do I ask for them?
      - What artifacts is the catalog able to generate on a provider's behalf?
      instructions:
      - text: Show what artifacts can be generated for {slug}.
        slots:
          slug: path.slug
      - text: Check which artifacts could be authored on behalf of {slug}.
        slots:
          slug: path.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/providers/{slug}/projection'].post
  update:
    x-apievangelist-phrasing:
      intent: Project a provider's score after a set of fixes
      effect: read
      questions:
      - If I fixed a few failing checks, what would my score become?
      - Can I dry-run a set of fixes without anything being stored or queued?
      instructions:
      - text: Project {slug}'s score if {fixes} were fixed.
        slots:
          slug: path.slug
          fixes: requestBody.fixes
      - text: Simulate fixing checks {fixes} for provider {slug}.
        slots:
          fixes: requestBody.fixes
          slug: path.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/providers/{slug}/remediation'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a provider's ranked remediation list
      effect: read
      questions:
      - What should my company fix first to raise its rating?
      - Is there a ranked, costed punch list across both rating layers?
      instructions:
      - text: Show the remediation punch list for {slug}.
        slots:
          slug: path.slug
      - text: List the ranked, costed fixes for {slug}, do-first items on top.
        slots:
          slug: path.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/providers/{slug}/gates'].get
  update:
    x-apievangelist-phrasing:
      intent: Check a provider's unmet band gates
      effect: read
      questions:
      - Which band gates is a provider failing, and what is unmet?
      - What is holding a provider back from the next rating band?
      instructions:
      - text: Show the band gates for {slug} and what is unmet.
        slots:
          slug: path.slug
      - text: List unmet band gates for provider {slug}.
        slots:
          slug: path.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/providers/{slug}/rating/checks'].get
  update:
    x-apievangelist-phrasing:
      intent: List a provider's missed Kin Score checks
      effect: read
      questions:
      - Which Kin Score checks did a provider miss or only partly pass?
      - Can I see check-level rating results ordered by points available?
      instructions:
      - text: List the missed and partial Kin Score checks for {slug}.
        slots:
          slug: path.slug
      - text: Show per-check rating results for {slug}.
        slots:
          slug: path.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/checks'].post
  update:
    x-apievangelist-phrasing:
      intent: Request a re-profile of a provider or market
      effect: write
      questions:
      - Can I ask for a provider to be re-profiled against its live site?
      - Is it possible to request a fresh check of a whole industry, tag or area?
      instructions:
      - text: Request a re-profile of provider {slug}.
        slots:
          slug: requestBody.slug
      - text: Queue a check of {url} with the note {notes}.
        slots:
          url: requestBody.url
          notes: requestBody.notes
      method: generated
      generated: '2026-09-26'
- target: $.paths['/gaps/report'].post
  update:
    x-apievangelist-phrasing:
      intent: Report an API you looked for and did not find
      effect: write
      questions:
      - How do I tell the catalog about an API I searched for and couldn't find?
      - Is reporting a missing API free and keyless?
      instructions:
      - text: 'Report a gap: I looked for {looked_for}.'
        slots:
          looked_for: requestBody.looked_for
      - text: Report that {looked_for} is missing, with context {context}.
        slots:
          looked_for: requestBody.looked_for
          context: requestBody.context
      method: generated
      generated: '2026-09-26'