# 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 Ratings API
  version: 1.0.0
extends: openapi/apis-io-ratings-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: 8
- target: $.paths['/providers/{slug}/rating'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one provider's rating
      effect: read
      questions:
      - What is a provider's Kin Score, band and trend?
      - How is a single provider rated right now, overall and by facet?
      instructions:
      - text: Get the rating for {slug}.
        slots:
          slug: path.slug
      - text: Show {slug}'s composite score, band and trend.
        slots:
          slug: path.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/ratings'].get
  update:
    x-apievangelist-phrasing:
      intent: Show the ratings leaderboard
      effect: read
      questions:
      - Which providers are rated highest overall?
      - Can I list only improving providers in a given band?
      instructions:
      - text: Show the ratings leaderboard for providers tagged {tags}.
        slots:
          tags: query.tags
      - text: Rank providers in band {band} with trend {trend}.
        slots:
          band: query.band
          trend: query.trend
      method: generated
      generated: '2026-09-26'
- target: $.paths['/ratings/rubric'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the rating rubric
      effect: read
      questions:
      - What are the rating bands and their thresholds?
      - How are the six facets weighted in the composite score?
      instructions:
      - text: Get the current rating rubric.
      - text: Show the band thresholds and facet weights.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/providers/{slug}/rating/history'].get
  update:
    x-apievangelist-phrasing:
      intent: See a provider's rating movement
      effect: read
      questions:
      - Has a provider's rating gone up or down since the last build?
      - Is there a full time series of a provider's score?
      instructions:
      - text: Show the rating movement for {slug}.
        slots:
          slug: path.slug
      - text: Get {slug}'s current and previous score.
        slots:
          slug: path.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/ratings/movers'].get
  update:
    x-apievangelist-phrasing:
      intent: Find the biggest rating movers
      effect: read
      questions:
      - Which providers' scores moved most in the latest scoring build?
      - Who dropped the most in the ratings this build?
      instructions:
      - text: List the biggest rating movers.
      - text: Show the top {limit} rating movers up and down.
        slots:
          limit: query.limit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/providers/{slug}/rating/facets'].get
  update:
    x-apievangelist-phrasing:
      intent: Break a provider's score down by facet
      effect: read
      questions:
      - Which regulatory regime applies to a provider's score, and how was it matched?
      - What parts of a provider's composite can a team actually act on?
      instructions:
      - text: Break down {slug}'s score by facet.
        slots:
          slug: path.slug
      - text: Show the facets and regulatory regime behind {slug}'s composite.
        slots:
          slug: path.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/providers/{slug}/agent-readiness'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a provider's agent-readiness dimensions
      effect: read
      questions:
      - How agent-ready is a provider, dimension by dimension?
      - Does a provider have an MCP server, idempotency and clear error semantics?
      instructions:
      - text: Get the agent-readiness dimensions for {slug}.
        slots:
          slug: path.slug
      - text: Score {slug}'s agent readiness.
        slots:
          slug: path.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/providers/{slug}/evidence'].get
  update:
    x-apievangelist-phrasing:
      intent: See how a provider's score was established
      effect: read
      questions:
      - 'How was a provider''s score established: first-party, verified or derived?'
      - Can I check the provenance before quoting a rating?
      instructions:
      - text: Show the evidence behind {slug}'s score.
        slots:
          slug: path.slug
      - text: Get the provenance and contract coverage for {slug}.
        slots:
          slug: path.slug
      method: generated
      generated: '2026-09-26'