# 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 API
  version: 1.0.0
extends: openapi/apis-io-v1-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: 164
- target: $.paths['/providers'].get
  update:
    x-apievangelist-phrasing:
      intent: Browse and filter API providers in the catalog
      effect: read
      questions:
      - Which API providers in the catalog are tagged Payments and rated in the top band?
      - Can I filter the provider directory by industry, region and minimum score at once?
      - Is there a way to list only providers that publish an OpenAPI and an MCP server?
      instructions:
      - text: List providers tagged {tags} with a composite score of at least {min_score}.
        slots:
          tags: query.tags
          min_score: query.min_score
      - text: Show me providers in the {industry} industry based in {region}.
        slots:
          industry: query.industry
          region: query.region
      - text: Find providers whose name or description mentions {q}.
        slots:
          q: query.q
      method: generated
      generated: '2026-09-26'
- target: $.paths['/providers/{slug}'].get
  update:
    x-apievangelist-phrasing:
      intent: Look up one provider's profile
      effect: read
      questions:
      - What does the apis.io catalog hold about a single provider, like its links, tags and API list?
      - Where can I see one vendor's profile with every API it publishes summarized?
      instructions:
      - text: Get the provider profile for {slug}.
        slots:
          slug: path.slug
      - text: Pull up {slug}'s links and tags, returning only the fields {fields}.
        slots:
          slug: path.slug
          fields: query.fields
      method: generated
      generated: '2026-09-26'
- target: $.paths['/providers/{slug}/apis'].get
  update:
    x-apievangelist-phrasing:
      intent: List the APIs one provider publishes
      effect: read
      questions:
      - Which APIs does a given provider publish, and can I narrow them by tag?
      - Can I list a vendor's APIs with their artifact bodies inlined?
      instructions:
      - text: List all the APIs that {slug} publishes.
        slots:
          slug: path.slug
      - text: Show {slug}'s APIs tagged {tags} that ship a {artifact_types} artifact.
        slots:
          slug: path.slug
          tags: query.tags
          artifact_types: query.artifact_types
      method: generated
      generated: '2026-09-26'
- target: $.paths['/providers/{slug}/rating'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a provider's current rating breakdown
      effect: read
      questions:
      - What is a provider's composite score, band and trend right now?
      - Can I see all six facet scores behind one vendor's rating?
      instructions:
      - text: Show me the full rating breakdown for {slug}.
        slots:
          slug: path.slug
      - text: Give me {slug}'s current band, trend and facet scores.
        slots:
          slug: path.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/apis'].get
  update:
    x-apievangelist-phrasing:
      intent: Discover APIs across every provider
      effect: read
      questions:
      - How do I find messaging APIs from any provider that publish an OpenAPI?
      - Can I filter APIs across the whole network by several providers and tags at once?
      - Which APIs match all of a set of tags rather than any of them?
      instructions:
      - text: List APIs across the network tagged {tags} that publish {artifact_types}.
        slots:
          tags: query.tags
          artifact_types: query.artifact_types
      - text: Find APIs from providers {providers} matching {q}.
        slots:
          providers: query.providers
          q: query.q
      - text: Show APIs in the {industry} industry with a score of at least {min_score}.
        slots:
          industry: query.industry
          min_score: query.min_score
      method: generated
      generated: '2026-09-26'
- target: $.paths['/apis/{aid}'].get
  update:
    x-apievangelist-phrasing:
      intent: Look up a single API by its id
      effect: read
      questions:
      - What does the catalog record for one specific API, looked up by its aid?
      - Can I fetch one API with its artifact bodies included inline?
      instructions:
      - text: Get the API {aid}.
        slots:
          aid: path.aid
      - text: Fetch API {aid} with its {artifact_types} artifacts inlined.
        slots:
          aid: path.aid
          artifact_types: query.artifact_types
      method: generated
      generated: '2026-09-26'
- target: $.paths['/tags'].get
  update:
    x-apievangelist-phrasing:
      intent: Browse and rank the tag taxonomy
      effect: read
      questions:
      - Which tags rank highest across the network by composite?
      - Can I list only tags applied to at least 50 APIs?
      instructions:
      - text: List tags matching {q}, ranked by composite.
        slots:
          q: query.q
      - text: Show tags in band {band} used by at least {min_api_count} APIs.
        slots:
          band: query.band
          min_api_count: query.min_api_count
      method: generated
      generated: '2026-09-26'
- target: $.paths['/tags/{slug}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one tag with its providers and neighbors
      effect: read
      questions:
      - Which providers and APIs carry a particular tag, and what tags sit next to it?
      - What name variants and ranking metadata does one tag have?
      instructions:
      - text: Show me the tag {slug} with its providers, APIs and neighbor tags.
        slots:
          slug: path.slug
      - text: Get tag {slug}'s ranking metadata and name variants.
        slots:
          slug: path.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/tag-groups'].get
  update:
    x-apievangelist-phrasing:
      intent: Find groups of tags that travel together
      effect: read
      questions:
      - What sets of tags consistently appear together across providers?
      - Can I list tag groups that contain at least ten tags?
      instructions:
      - text: Find tag groups matching {q}.
        slots:
          q: query.q
      - text: List tag groups grouped on basis {basis} with at least {min_tags} tags.
        slots:
          basis: query.basis
          min_tags: query.min_tags
      method: generated
      generated: '2026-09-26'
- target: $.paths['/tag-groups/{slug}'].get
  update:
    x-apievangelist-phrasing:
      intent: See a tag group and the providers it covers
      effect: read
      questions:
      - Which providers does a given tag group resolve to?
      - Can I read a tag group's provider roster inside just one country or industry?
      instructions:
      - text: Show the tag group {slug} and its provider roster.
        slots:
          slug: path.slug
      - text: Show providers in tag group {slug} limited to the {industry} industry.
        slots:
          slug: path.slug
          industry: query.industry
      method: generated
      generated: '2026-09-26'
- target: $.paths['/tag-groups/{slug}/tags'].get
  update:
    x-apievangelist-phrasing:
      intent: List the member tags of a tag group
      effect: read
      questions:
      - What individual tags make up a tag group, with their counts?
      - Can I page through the member tags of one group?
      instructions:
      - text: List the member tags inside tag group {slug}.
        slots:
          slug: path.slug
      - text: Show page {page} of the tags in group {slug}.
        slots:
          page: query.page
          slug: path.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/industries'].get
  update:
    x-apievangelist-phrasing:
      intent: Browse the industry taxonomy
      effect: read
      questions:
      - What industry verticals does the catalog group providers into?
      - Which industries have the most providers?
      instructions:
      - text: List industries matching {q}.
        slots:
          q: query.q
      - text: List all industries sorted by {sort}.
        slots:
          sort: query.sort
      method: generated
      generated: '2026-09-26'
- target: $.paths['/industries/{slug}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one industry and its ranked providers
      effect: read
      questions:
      - What does an industry page hold, including its aliases and every member provider?
      - Can I see all providers in a vertical ranked by score, not just the top few?
      instructions:
      - text: Get the industry {slug} with its full ranked provider list.
        slots:
          slug: path.slug
      - text: Show the aliases and counts for industry {slug}.
        slots:
          slug: path.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/regions'].get
  update:
    x-apievangelist-phrasing:
      intent: Browse the geographic region taxonomy
      effect: read
      questions:
      - What geographic regions are providers grouped into?
      - Which regions have the most APIs listed?
      instructions:
      - text: List regions matching {q}.
        slots:
          q: query.q
      - text: List every region sorted by {sort}.
        slots:
          sort: query.sort
      method: generated
      generated: '2026-09-26'
- target: $.paths['/regions/{slug}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one region and its ranked providers
      effect: read
      questions:
      - What name patterns and aliases define a region, and who is in it?
      - Can I see every provider placed in a region ranked by score?
      instructions:
      - text: Get the region {slug} with all its ranked member providers.
        slots:
          slug: path.slug
      - text: Show region {slug}'s aliases, name patterns and counts.
        slots:
          slug: path.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/openapis'].get
  update:
    x-apievangelist-phrasing:
      intent: Search OpenAPI specs across all providers
      effect: read
      questions:
      - Where can I browse OpenAPI specifications from every provider in one list?
      - Can I pull OpenAPI spec bodies inline for a set of providers?
      instructions:
      - text: List OpenAPI specifications from {providers}.
        slots:
          providers: query.providers
      - text: Find OpenAPI specs tagged {tags} and include their content.
        slots:
          tags: query.tags
      method: generated
      generated: '2026-09-26'
- target: $.paths['/asyncapis'].get
  update:
    x-apievangelist-phrasing:
      intent: Search AsyncAPI specs across all providers
      effect: read
      questions:
      - Which providers publish AsyncAPI specifications for their event APIs?
      - Can I list AsyncAPI documents across the catalog filtered by tag?
      instructions:
      - text: List AsyncAPI specifications matching {q}.
        slots:
          q: query.q
      - text: Show AsyncAPI documents published by {providers}.
        slots:
          providers: query.providers
      method: generated
      generated: '2026-09-26'
- target: $.paths['/arazzo'].get
  update:
    x-apievangelist-phrasing:
      intent: Search Arazzo workflows across providers
      effect: read
      questions:
      - Which providers publish Arazzo workflow descriptions?
      - Can I find Arazzo workflows about a topic like onboarding?
      instructions:
      - text: List Arazzo workflows matching {q}.
        slots:
          q: query.q
      - text: Show the Arazzo workflows {providers} publishes.
        slots:
          providers: query.providers
      method: generated
      generated: '2026-09-26'
- target: $.paths['/postman'].get
  update:
    x-apievangelist-phrasing:
      intent: Search Postman collections across providers
      effect: read
      questions:
      - Which vendors ship Postman collections for their APIs?
      - Can I get Postman collections tagged Payments with the collection bodies?
      instructions:
      - text: List Postman collections from {providers}.
        slots:
          providers: query.providers
      - text: Find Postman collections tagged {tags}.
        slots:
          tags: query.tags
      method: generated
      generated: '2026-09-26'
- target: $.paths['/collections'].get
  update:
    x-apievangelist-phrasing:
      intent: Search generic API collections across providers
      effect: read
      questions:
      - Where are the non-Postman API collection artifacts providers publish?
      - Can I list collection artifacts (Collection or Collections type) for one provider?
      instructions:
      - text: List API collection artifacts matching {q}.
        slots:
          q: query.q
      - text: Show the Collection-type artifacts published by {providers}.
        slots:
          providers: query.providers
      method: generated
      generated: '2026-09-26'
- target: $.paths['/graphql'].get
  update:
    x-apievangelist-phrasing:
      intent: Search GraphQL schemas across providers
      effect: read
      questions:
      - Which providers publish a GraphQL schema?
      - Can I list GraphQL schemas tagged e-commerce with the schema text inlined?
      instructions:
      - text: List GraphQL schemas tagged {tags}.
        slots:
          tags: query.tags
      - text: Find GraphQL schemas from {providers}.
        slots:
          providers: query.providers
      method: generated
      generated: '2026-09-26'
- target: $.paths['/json-schemas'].get
  update:
    x-apievangelist-phrasing:
      intent: Search JSON Schema definitions across providers
      effect: read
      questions:
      - Where can I find JSON Schema definitions published by any provider?
      - Can I search the catalog's JSON Schemas for an invoice or address model?
      instructions:
      - text: Search JSON Schema definitions across the catalog for {q}.
        slots:
          q: query.q
      - text: List JSON Schema artifacts tagged {tags}.
        slots:
          tags: query.tags
      method: generated
      generated: '2026-09-26'
- target: $.paths['/json-structures'].get
  update:
    x-apievangelist-phrasing:
      intent: Search JSON Structure definitions
      effect: read
      questions:
      - Which providers publish JSON Structure definitions rather than JSON Schema?
      - Can I list JSON Structure artifacts for a given provider?
      instructions:
      - text: List JSON Structure definitions matching {q}.
        slots:
          q: query.q
      - text: Show the JSON Structure artifacts from {providers}.
        slots:
          providers: query.providers
      method: generated
      generated: '2026-09-26'
- target: $.paths['/json-ld'].get
  update:
    x-apievangelist-phrasing:
      intent: Search JSON-LD contexts across providers
      effect: read
      questions:
      - Which providers publish JSON-LD contexts for linked data?
      - Can I find JSON-LD context documents tagged healthcare?
      instructions:
      - text: List JSON-LD contexts matching {q}.
        slots:
          q: query.q
      - text: Show JSON-LD contexts tagged {tags}.
        slots:
          tags: query.tags
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rules'].get
  update:
    x-apievangelist-phrasing:
      intent: Search governance rulesets like Spectral
      effect: read
      questions:
      - Which providers publish Spectral or other API governance rulesets?
      - Can I read the content of governance rules other companies use?
      instructions:
      - text: List governance rulesets from {providers}.
        slots:
          providers: query.providers
      - text: Find Spectral rulesets matching {q} and include their content.
        slots:
          q: query.q
      method: generated
      generated: '2026-09-26'
- target: $.paths['/examples'].get
  update:
    x-apievangelist-phrasing:
      intent: Search code examples across providers
      effect: read
      questions:
      - Where can I find code examples that API providers publish?
      - Can I list example artifacts tagged SMS across the network?
      instructions:
      - text: List code example artifacts tagged {tags}.
        slots:
          tags: query.tags
      - text: Show the examples {providers} publishes.
        slots:
          providers: query.providers
      method: generated
      generated: '2026-09-26'
- target: $.paths['/finops'].get
  update:
    x-apievangelist-phrasing:
      intent: Search FinOps artifacts across providers
      effect: read
      questions:
      - Which providers publish FinOps cost artifacts?
      - Can I find FinOps artifacts for cloud providers?
      instructions:
      - text: List FinOps artifacts matching {q}.
        slots:
          q: query.q
      - text: Show FinOps artifacts published by {providers}.
        slots:
          providers: query.providers
      method: generated
      generated: '2026-09-26'
- target: $.paths['/plans'].get
  update:
    x-apievangelist-phrasing:
      intent: Search published pricing plans
      effect: read
      questions:
      - Which providers publish machine-readable plans for their APIs?
      - Can I compare the plan artifacts of vendors in one tag?
      instructions:
      - text: List pricing plan artifacts for {providers}.
        slots:
          providers: query.providers
      - text: Find plan artifacts tagged {tags}.
        slots:
          tags: query.tags
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rate-limits'].get
  update:
    x-apievangelist-phrasing:
      intent: Search published rate-limit artifacts
      effect: read
      questions:
      - Which providers document their rate limits in a machine-readable artifact?
      - Can I see the rate limits a specific vendor publishes?
      instructions:
      - text: List rate-limit artifacts from {providers}.
        slots:
          providers: query.providers
      - text: Find rate-limit artifacts tagged {tags} with content inlined.
        slots:
          tags: query.tags
      method: generated
      generated: '2026-09-26'
- target: $.paths['/ratings'].get
  update:
    x-apievangelist-phrasing:
      intent: View the ranked ratings leaderboard
      effect: read
      questions:
      - Which providers have the highest composite scores overall?
      - Can I rank only providers whose governance facet is above 70?
      - Who is trending up on the leaderboard within a tag?
      instructions:
      - text: Show the ratings leaderboard for band {band}.
        slots:
          band: query.band
      - text: Rank providers tagged {tags} whose {facet} facet is at least {min_facet}.
        slots:
          tags: query.tags
          facet: query.facet
          min_facet: query.min_facet
      - text: List rated providers trending {trend}.
        slots:
          trend: query.trend
      method: generated
      generated: '2026-09-26'
- target: $.paths['/ratings/rubric'].get
  update:
    x-apievangelist-phrasing:
      intent: Read the rating rubric behind scores
      effect: read
      questions:
      - What are the band thresholds and facet weights behind apis.io scores?
      - How are rating trends decided, and what are the six facets?
      instructions:
      - text: Show me the current rating rubric with bands, facet weights and trend thresholds.
      - text: Get the rubric version so I can interpret a score block.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/search'].get
  update:
    x-apievangelist-phrasing:
      intent: Search APIs, providers, tags and artifacts together
      effect: read
      questions:
      - Can one query return providers instead of APIs when I search by tag?
      - What's the most flexible way to combine text, tags, providers and artifact types in a single catalog search?
      - Is there a unified search that returns tags or artifacts as the result type?
      instructions:
      - text: Search for {q} and return {return} as the result type.
        slots:
          q: query.q
          return: query.return
      - text: Run a unified search for APIs tagged {tags} that ship {artifact_types}, returning only {fields}.
        slots:
          tags: query.tags
          artifact_types: query.artifact_types
          fields: query.fields
      method: generated
      generated: '2026-09-26'
- target: $.paths['/prices'].get
  update:
    x-apievangelist-phrasing:
      intent: Check per-call pay-as-you-go prices
      effect: read
      questions:
      - What does one API call cost on the pay-as-you-go plan?
      - Is pay-as-you-go pricing live yet or still in preview?
      instructions:
      - text: Show me the per-call price list by cost band.
      - text: Check whether metered pay-as-you-go pricing has launched.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/playground'].get
  update:
    x-apievangelist-phrasing:
      intent: Find free, keyless APIs safe to try
      effect: read
      questions:
      - Which APIs can I call right now with no key and no cost while learning?
      - Are there safe sample APIs with a working example request I can try first?
      instructions:
      - text: List playground APIs tagged {tag}.
        slots:
          tag: query.tag
      - text: Show playground APIs with access type {access}, grouped by {grouping}.
        slots:
          access: query.access
          grouping: query.grouping
      method: generated
      generated: '2026-09-26'
- target: $.paths['/channels'].get
  update:
    x-apievangelist-phrasing:
      intent: Search AsyncAPI event channels
      effect: read
      questions:
      - Which providers expose event channels I could subscribe to for order updates?
      - Can I search individual streaming channels rather than whole AsyncAPI documents?
      instructions:
      - text: Find event channels matching {q}.
        slots:
          q: query.q
      - text: List the event channels {providers} exposes.
        slots:
          providers: query.providers
      method: generated
      generated: '2026-09-26'
- target: $.paths['/mcp'].get
  update:
    x-apievangelist-phrasing:
      intent: Find published MCP servers
      effect: read
      questions:
      - Which providers publish an MCP server?
      - Can I see the server card for MCP servers tagged CRM?
      instructions:
      - text: List MCP servers tagged {tags}.
        slots:
          tags: query.tags
      - text: Find MCP servers matching {q} and include their manifests.
        slots:
          q: query.q
      method: generated
      generated: '2026-09-26'
- target: $.paths['/skills'].get
  update:
    x-apievangelist-phrasing:
      intent: Find published Agent Skills
      effect: read
      questions:
      - Which providers publish Agent Skills for their APIs?
      - Can I read the content of Agent Skills about invoicing?
      instructions:
      - text: List Agent Skills published by {providers}.
        slots:
          providers: query.providers
      - text: Find Agent Skills matching {q}.
        slots:
          q: query.q
      method: generated
      generated: '2026-09-26'
- target: $.paths['/scopes'].get
  update:
    x-apievangelist-phrasing:
      intent: Search OAuth scope sets across providers
      effect: read
      questions:
      - What OAuth scopes do providers define for their APIs?
      - Can I compare the scope sets of vendors in one tag?
      instructions:
      - text: List OAuth scope sets for {providers}.
        slots:
          providers: query.providers
      - text: Find OAuth scopes matching {q}.
        slots:
          q: query.q
      method: generated
      generated: '2026-09-26'
- target: $.paths['/security'].get
  update:
    x-apievangelist-phrasing:
      intent: Search security and auth scheme definitions
      effect: read
      questions:
      - Which providers publish a vulnerability disclosure policy or trust center?
      - What authentication schemes do vendors in a tag document?
      instructions:
      - text: List security scheme definitions from {providers}.
        slots:
          providers: query.providers
      - text: Find security and trust-center artifacts tagged {tags}.
        slots:
          tags: query.tags
      method: generated
      generated: '2026-09-26'
- target: $.paths['/extensions'].get
  update:
    x-apievangelist-phrasing:
      intent: Browse harvested OpenAPI x- extensions
      effect: read
      questions:
      - Which OpenAPI x- extensions are most common across real specs?
      - Where can I see who publishes a vendor extension and how often it appears?
      instructions:
      - text: List OpenAPI specification extensions matching {q}.
        slots:
          q: query.q
      - text: Rank harvested x- extensions by {sort}.
        slots:
          sort: query.sort
      method: generated
      generated: '2026-09-26'
- target: $.paths['/extensions/{slug}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one OpenAPI extension's provenance
      effect: read
      questions:
      - Who publishes a particular x- extension and what value shapes does it take?
      - Is a given extension key originated by API Evangelist rather than a provider?
      instructions:
      - text: Get the provenance for extension {slug}.
        slots:
          slug: path.slug
      - text: Show which providers publish the {slug} extension and where it appears.
        slots:
          slug: path.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/countries'].get
  update:
    x-apievangelist-phrasing:
      intent: Browse the country taxonomy
      effect: read
      questions:
      - Which countries have the most API providers placed in them?
      - Can I search the country list by name?
      instructions:
      - text: List countries matching {q}.
        slots:
          q: query.q
      - text: List all countries sorted by {sort}.
        slots:
          sort: query.sort
      method: generated
      generated: '2026-09-26'
- target: $.paths['/countries/{slug}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one country and its ranked providers
      effect: read
      questions:
      - What providers are based in a given country, ranked by score?
      - How many APIs does the catalog place in one country?
      instructions:
      - text: Get the country {slug} with its full ranked member list.
        slots:
          slug: path.slug
      - text: Show counts for country {slug}.
        slots:
          slug: path.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/areas'].get
  update:
    x-apievangelist-phrasing:
      intent: Browse curated API Evangelist areas
      effect: read
      questions:
      - What curated topic areas like webhooks or authentication does API Evangelist track?
      - Which areas have the most providers?
      instructions:
      - text: List curated areas matching {q}.
        slots:
          q: query.q
      - text: List all areas sorted by {sort}.
        slots:
          sort: query.sort
      method: generated
      generated: '2026-09-26'
- target: $.paths['/countries/{slug}/leaders'].get
  update:
    x-apievangelist-phrasing:
      intent: See the top-rated providers in a country
      effect: read
      questions:
      - Who are the best-rated API providers in Germany?
      - Can I get just the top ten leaders for one country?
      instructions:
      - text: Show the top-rated providers in country {slug}.
        slots:
          slug: path.slug
      - text: List the top {limit} leaders in country {slug}.
        slots:
          limit: query.limit
          slug: path.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/areas/{slug}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one curated area and its providers
      effect: read
      questions:
      - What does a curated area include, like its description, site and member providers?
      - Where is the site link for an API Evangelist area?
      instructions:
      - text: Get the area {slug} with its description and ranked members.
        slots:
          slug: path.slug
      - text: Show the site link and counts for area {slug}.
        slots:
          slug: path.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/compare'].get
  update:
    x-apievangelist-phrasing:
      intent: Compare providers side by side
      effect: read
      questions:
      - How do two payment providers stack up facet by facet?
      - Can I see an artifact-coverage matrix for several vendors at once?
      instructions:
      - text: Compare providers {providers} side by side.
        slots:
          providers: query.providers
      - text: Show the per-facet leaders and artifact matrix across {providers}.
        slots:
          providers: query.providers
      method: generated
      generated: '2026-09-26'
- target: $.paths['/agents'].get
  update:
    x-apievangelist-phrasing:
      intent: Browse the registered A2A agent registry
      effect: read
      questions:
      - Which A2A agents have registered themselves with an agent card?
      - Can I see each registered agent's verification grade and preferred transport?
      instructions:
      - text: List registered A2A agents.
      - text: Show page {page} of the agent registry.
        slots:
          page: query.page
      method: generated
      generated: '2026-09-26'
- target: $.paths['/agents/register'].get
  update:
    x-apievangelist-phrasing:
      intent: Read the agent registration contract
      effect: read
      questions:
      - What body and checks does agent registration require before I submit?
      - What responses can I expect when registering an agent card?
      instructions:
      - text: Describe how to register an agent, including the gate and responses.
      - text: Fetch the self-describing registration contract for agents.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/agents/register'].post
  update:
    x-apievangelist-phrasing:
      intent: Register an A2A agent by its card URL
      effect: write
      questions:
      - How do I add my A2A agent to the registry?
      - What does my agent card need to pass before registration is accepted?
      instructions:
      - text: Register the agent whose card is at {card_url}.
        slots:
          card_url: requestBody.card_url
      - text: Register agent card {card_url} operated by {operator}, contact {contact}.
        slots:
          card_url: requestBody.card_url
          operator: requestBody.operator
          contact: requestBody.contact
      method: generated
      generated: '2026-09-26'
- target: $.paths['/gaps/report'].post
  update:
    x-apievangelist-phrasing:
      intent: Report something missing from the catalog
      effect: write
      questions:
      - Can I tell apis.io about an API I needed but could not find?
      - Is there a free way to flag a missing provider or artifact?
      instructions:
      - text: Report that I looked for {looked_for} and the catalog didn't have it.
        slots:
          looked_for: requestBody.looked_for
      - text: 'File a gap: I needed {looked_for} for {needed_for}; contact me at {contact}.'
        slots:
          looked_for: requestBody.looked_for
          needed_for: requestBody.needed_for
          contact: requestBody.contact
      method: generated
      generated: '2026-09-26'
- target: $.paths['/gaps'].get
  update:
    x-apievangelist-phrasing:
      intent: Find artifact and score gaps for providers
      effect: read
      questions:
      - What artifacts does a provider lack that its peers commonly publish?
      - How does a vendor's score compare to the peer median?
      instructions:
      - text: Run a gap analysis for {providers}.
        slots:
          providers: query.providers
      - text: Show gaps for stack {providers} counting artifacts at least {min_share} of peers publish.
        slots:
          providers: query.providers
          min_share: query.min_share
      method: generated
      generated: '2026-09-26'
- target: $.paths['/changes'].get
  update:
    x-apievangelist-phrasing:
      intent: See catalog changes since a date
      effect: read
      questions:
      - Which providers were added or updated since last month?
      - What rating movement happened in the latest scoring build?
      instructions:
      - text: Show what changed in the catalog since {since}.
        slots:
          since: query.since
      - text: List up to {limit} providers added or updated since {since}.
        slots:
          limit: query.limit
          since: query.since
      method: generated
      generated: '2026-09-26'
- target: $.paths['/stack'].get
  update:
    x-apievangelist-phrasing:
      intent: Design a recommended API stack
      effect: read
      questions:
      - What is the best-rated provider for each capability my product needs?
      - Can I get a recommended API stack restricted to one region?
      instructions:
      - text: Recommend an API stack for {capabilities}.
        slots:
          capabilities: query.capabilities
      - text: Design a stack for {capabilities} using providers in {region}.
        slots:
          capabilities: query.capabilities
          region: query.region
      method: generated
      generated: '2026-09-26'
- target: $.paths['/providers/{slug}/artifacts'].get
  update:
    x-apievangelist-phrasing:
      intent: List every artifact a provider publishes
      effect: read
      questions:
      - What artifacts, from OpenAPI to MCP to pricing, does one vendor publish in total?
      - Can I get all of a provider's artifacts grouped by type in one call?
      instructions:
      - text: List every artifact {slug} publishes, grouped by type.
        slots:
          slug: path.slug
      - text: Count {slug}'s artifacts per type across all its APIs.
        slots:
          slug: path.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/providers/{slug}/onboarding'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a provider's getting-started details
      effect: read
      questions:
      - Where do I sign up, find docs and get base URLs to start using a vendor's API?
      - What are the first steps to onboard with a provider?
      instructions:
      - text: Show me how to get started with {slug}.
        slots:
          slug: path.slug
      - text: Get {slug}'s signup, docs, auth and base URL links.
        slots:
          slug: path.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/providers/{slug}/similar'].get
  update:
    x-apievangelist-phrasing:
      intent: Find providers similar to a given one
      effect: read
      questions:
      - What are the alternatives to a provider I'm already evaluating?
      - Which vendors overlap most in tags, industry and region with one I know?
      instructions:
      - text: Find providers similar to {slug}.
        slots:
          slug: path.slug
      - text: List the top {limit} alternatives to {slug}.
        slots:
          limit: query.limit
          slug: path.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/providers/{slug}/rating/history'].get
  update:
    x-apievangelist-phrasing:
      intent: See how a provider's rating moved
      effect: read
      questions:
      - Did a provider's score go up or down since the previous build?
      - Is there a week-over-week history of a vendor's rating?
      instructions:
      - text: Show the rating movement for {slug}.
        slots:
          slug: path.slug
      - text: Compare {slug}'s current score with its previous build.
        slots:
          slug: path.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/apis/{aid}/artifacts'].get
  update:
    x-apievangelist-phrasing:
      intent: List one API's artifacts by type
      effect: read
      questions:
      - Which artifacts are registered for one specific API?
      - Can I get a single API's artifact bodies grouped by type?
      instructions:
      - text: List the artifacts registered for API {aid}.
        slots:
          aid: path.aid
      - text: Group API {aid}'s artifacts by type and inline their bodies.
        slots:
          aid: path.aid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/apis/{aid}/similar'].get
  update:
    x-apievangelist-phrasing:
      intent: Find APIs similar to a given API
      effect: read
      questions:
      - What other APIs are like the one I'm looking at?
      - Which APIs share the most tags with a given API?
      instructions:
      - text: Find APIs similar to {aid}.
        slots:
          aid: path.aid
      - text: Show {limit} APIs more like {aid}.
        slots:
          limit: query.limit
          aid: path.aid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/openapis/{aid}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an API's primary OpenAPI
      effect: read
      questions:
      - Where is the main OpenAPI definition for a specific API?
      - Can I download the primary OpenAPI spec body for one API?
      instructions:
      - text: Get the primary OpenAPI URL for API {aid}.
        slots:
          aid: path.aid
      - text: Fetch the full OpenAPI spec content for {aid}.
        slots:
          aid: path.aid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/industries/{slug}/leaders'].get
  update:
    x-apievangelist-phrasing:
      intent: See the top-rated providers in an industry
      effect: read
      questions:
      - Who are the highest-scoring API providers in healthcare?
      - Can I get just the top five leaders of an industry vertical?
      instructions:
      - text: Show the leaders of the {slug} industry.
        slots:
          slug: path.slug
      - text: List the top {limit} providers in industry {slug}.
        slots:
          limit: query.limit
          slug: path.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/regions/{slug}/leaders'].get
  update:
    x-apievangelist-phrasing:
      intent: See the top-rated providers in a region
      effect: read
      questions:
      - Which API providers score best in Europe?
      - Can I list the top-rated vendors of a geographic region?
      instructions:
      - text: Show the leaders in region {slug}.
        slots:
          slug: path.slug
      - text: List the top {limit} providers in region {slug}.
        slots:
          limit: query.limit
          slug: path.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/areas/{slug}/leaders'].get
  update:
    x-apievangelist-phrasing:
      intent: See the top-rated providers in a curated area
      effect: read
      questions:
      - Who leads the webhooks area on score?
      - Can I get the best-rated providers of an API Evangelist area?
      instructions:
      - text: Show the leaders of area {slug}.
        slots:
          slug: path.slug
      - text: List the top {limit} providers in area {slug}.
        slots:
          limit: query.limit
          slug: path.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/ratings/movers'].get
  update:
    x-apievangelist-phrasing:
      intent: See the biggest rating movers
      effect: read
      questions:
      - Which providers' scores rose or fell the most in the latest build?
      - Who dropped hardest on the ratings this week?
      instructions:
      - text: Show the biggest rating movers up and down.
      - text: List the top {limit} rating movers.
        slots:
          limit: query.limit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/gaps/industry/{slug}'].get
  update:
    x-apievangelist-phrasing:
      intent: Find artifact gaps across an industry
      effect: read
      questions:
      - Which valuable artifacts like MCP or Arazzo do most fintech providers lack?
      - Where is an industry vertical under-served in published artifacts?
      instructions:
      - text: Run an artifact gap analysis for industry {slug}.
        slots:
          slug: path.slug
      - text: Show artifact types missing from at least {min_share} of industry {slug}.
        slots:
          min_share: query.min_share
          slug: path.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/stack/export'].get
  update:
    x-apievangelist-phrasing:
      intent: Export a designed stack as APIs.json
      effect: read
      questions:
      - Can I get my recommended stack as an APIs.json file to commit?
      - Is there an Arazzo hint included when exporting a stack?
      instructions:
      - text: Export the stack for {capabilities} as APIs.json.
        slots:
          capabilities: query.capabilities
      - text: Export an APIs.json stack for {capabilities} limited to {region}.
        slots:
          capabilities: query.capabilities
          region: query.region
      method: generated
      generated: '2026-09-26'
- target: $.paths['/insights'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the company insights overview
      effect: read
      questions:
      - How many companies and dimensions does the insights dataset cover?
      - What are the top technology investment dimensions across profiled companies?
      instructions:
      - text: Give me the insights overview counts and top investment dimensions.
      - text: Summarize the company insights dataset.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/insights/dimensions'].get
  update:
    x-apievangelist-phrasing:
      intent: Rank technology investment dimensions
      effect: read
      questions:
      - Which of the 40 tracked investment dimensions show signal at the most companies?
      - Can I page through investment dimensions ranked by company count?
      instructions:
      - text: Rank the tracked investment dimensions by company signal.
      - text: Show page {page} of the ranked investment dimensions.
        slots:
          page: query.page
      method: generated
      generated: '2026-09-26'
- target: $.paths['/insights/adoption'].get
  update:
    x-apievangelist-phrasing:
      intent: Rank services, tools and standards by adoption
      effect: read
      questions:
      - Which tools and standards are adopted by the most companies?
      - Can I rank only standards, not services, by how widely companies adopt them?
      instructions:
      - text: Rank technologies of type {type} by company adoption.
        slots:
          type: query.type
      - text: Show the most widely adopted services and tools.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/insights/industries'].get
  update:
    x-apievangelist-phrasing:
      intent: See profiled companies rolled up by industry
      effect: read
      questions:
      - How many profiled companies are in each sector of the insights dataset?
      - Which sectors have the most companies in the demand-side insights?
      instructions:
      - text: Show the industry rollup of profiled companies.
      - text: List insight sectors with their company counts.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/insights/companies'].get
  update:
    x-apievangelist-phrasing:
      intent: Browse companies by technology readiness
      effect: read
      questions:
      - Which companies show the strongest overall technology-readiness signal?
      - Can I look up a company in the insights dataset by name?
      instructions:
      - text: Find profiled companies named {q}.
        slots:
          q: query.q
      - text: List companies ranked by technology readiness, page {page}.
        slots:
          page: query.page
      method: generated
      generated: '2026-09-26'
- target: $.paths['/insights/company/{slug}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one company's demand-side profile
      effect: read
      questions:
      - What technology stack and investment profile does a given company have?
      - Can I see a company's per-quarter history across the 40 dimensions?
      instructions:
      - text: Get the demand-side profile for company {slug}.
        slots:
          slug: path.slug
      - text: Show {slug}'s adopted stack and dimension scores.
        slots:
          slug: path.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/insights/company/{slug}/gaps'].get
  update:
    x-apievangelist-phrasing:
      intent: Find a company's weakest investment areas
      effect: read
      questions:
      - Where is a target company thin enough that a vendor could sell in?
      - What are a company's lowest-scoring investment dimensions?
      instructions:
      - text: Show the weakest dimensions for company {slug}.
        slots:
          slug: path.slug
      - text: List where {slug} is under-invested.
        slots:
          slug: path.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/insights/company/{slug}/match'].get
  update:
    x-apievangelist-phrasing:
      intent: Match providers to a company's adopted stack
      effect: read
      questions:
      - Which catalog providers are already part of a company's tech stack?
      - Can I see the rated API vendors a company uses?
      instructions:
      - text: Match catalog providers to company {slug}'s stack.
        slots:
          slug: path.slug
      - text: List the rated providers {slug} has adopted.
        slots:
          slug: path.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/resolve'].get
  update:
    x-apievangelist-phrasing:
      intent: Resolve a domain, URL or GitHub org to a provider
      effect: read
      questions:
      - I have a company's website URL; which provider slug owns it?
      - Can a GitHub org like github.com/stripe be mapped to its catalog provider?
      instructions:
      - text: Resolve {identifier} to a provider.
        slots:
          identifier: query.identifier
      - text: Tell me which provider owns the domain {identifier}.
        slots:
          identifier: query.identifier
      method: generated
      generated: '2026-09-26'
- target: $.paths['/enrich'].get
  update:
    x-apievangelist-phrasing:
      intent: Enrich a provider with chosen field groups
      effect: read
      questions:
      - Can I get a provider's profile, onboarding and artifacts in a single call?
      - Which enrichment field groups are free and which need a paid plan?
      instructions:
      - text: Enrich {id} with the {fields} field groups.
        slots:
          id: query.id
          fields: query.fields
      - text: Enrich the provider behind {id} in one call.
        slots:
          id: query.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/vcs'].get
  update:
    x-apievangelist-phrasing:
      intent: Search venture-capital firms
      effect: read
      questions:
      - Which VC firms have the most portfolio companies on the network?
      - Can I find venture firms with a fintech thesis?
      instructions:
      - text: Find VC firms matching {q}.
        slots:
          q: query.q
      - text: List VC firms with thesis tags {tags}, sorted by {sort}.
        slots:
          tags: query.tags
          sort: query.sort
      method: generated
      generated: '2026-09-26'
- target: $.paths['/vcs/{slug}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one VC firm's profile and portfolio summary
      effect: read
      questions:
      - What are a venture firm's fund facts and average portfolio rating?
      - What's the band distribution across a VC's portfolio?
      instructions:
      - text: Get the VC firm {slug}.
        slots:
          slug: path.slug
      - text: Show VC {slug} with view {view}.
        slots:
          slug: path.slug
          view: query.view
      method: generated
      generated: '2026-09-26'
- target: $.paths['/vcs/{slug}/portfolio'].get
  update:
    x-apievangelist-phrasing:
      intent: List a VC firm's rated portfolio
      effect: read
      questions:
      - Which of a VC firm's portfolio companies are API providers?
      - Can I filter a fund's portfolio to companies scoring above 60?
      instructions:
      - text: List the portfolio companies of VC {slug}.
        slots:
          slug: path.slug
      - text: Show VC {slug}'s portfolio companies with a score of at least {min_score}.
        slots:
          slug: path.slug
          min_score: query.min_score
      method: generated
      generated: '2026-09-26'
- target: $.paths['/providers/{slug}/investors'].get
  update:
    x-apievangelist-phrasing:
      intent: See which VC firms back a provider
      effect: read
      questions:
      - Who are the investors behind a given API provider?
      - How many venture firms in the network back a vendor?
      instructions:
      - text: Show which VC firms back {slug}.
        slots:
          slug: path.slug
      - text: Count the investors in {slug}.
        slots:
          slug: path.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/me/searches'].get
  update:
    x-apievangelist-phrasing:
      intent: List my saved searches
      effect: read
      questions:
      - What saved searches do I have on my key?
      - Where can I see the searches I've stored?
      instructions:
      - text: List my saved searches.
      - text: Show every search saved under my API key.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/me/searches'].post
  update:
    x-apievangelist-phrasing:
      intent: Save a named search
      effect: write
      questions:
      - Can I save a catalog search so I can re-run it later?
      - What filters can a saved search store, like tags, band and region?
      instructions:
      - text: Save a search named {name} for {q}.
        slots:
          name: requestBody.name
          q: requestBody.q
      - text: Save search {name} for providers tagged {tags} in band {band}.
        slots:
          name: requestBody.name
          tags: requestBody.tags
          band: requestBody.band
      method: generated
      generated: '2026-09-26'
- target: $.paths['/me/searches/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a saved search
      effect: destructive
      questions:
      - How do I remove a saved search I no longer need?
      - Does deleting a saved search also drop its delta cursor?
      instructions:
      - text: Delete saved search {id}.
        slots:
          id: path.id
      - text: Permanently remove my saved search {id} and its cursor.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/me/searches/{id}/results'].get
  update:
    x-apievangelist-phrasing:
      intent: Re-run a saved search against the catalog
      effect: read
      questions:
      - Which providers currently match one of my saved searches?
      - Can I run a stored search again against the live data?
      instructions:
      - text: Run saved search {id}.
        slots:
          id: path.id
      - text: Show the top {limit} current matches for saved search {id}.
        slots:
          limit: query.limit
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/me/searches/{id}/net_new'].get
  update:
    x-apievangelist-phrasing:
      intent: See new matches for a saved search
      effect: write
      questions:
      - What providers newly match my saved search since I last checked?
      - Does checking for new matches advance a cursor so I only see changes?
      instructions:
      - text: Show what's new for saved search {id} since my last check.
        slots:
          id: path.id
      - text: Get the net-new providers for saved search {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/me/lists'].get
  update:
    x-apievangelist-phrasing:
      intent: List my shortlists
      effect: read
      questions:
      - What shortlists and stacks have I created?
      - Where do I see all the provider lists I own?
      instructions:
      - text: List my shortlists.
      - text: Show every list I own.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/me/lists'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a named shortlist
      effect: write
      questions:
      - Can I build a persistent shortlist of providers I'm evaluating?
      - Is it possible to seed a new list with provider slugs and API ids?
      instructions:
      - text: Create a list called {name}.
        slots:
          name: requestBody.name
      - text: Create a list named {name} starting with {members}.
        slots:
          name: requestBody.name
          members: requestBody.members
      method: generated
      generated: '2026-09-26'
- target: $.paths['/me/lists/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: View a shortlist with current scores
      effect: read
      questions:
      - What's in one of my lists, with each member's current band and score?
      - Can I see my shortlist resolved to up-to-date names and ratings?
      instructions:
      - text: Show my list {id} with current ratings.
        slots:
          id: path.id
      - text: Open list {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/me/lists/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a shortlist
      effect: destructive
      questions:
      - How do I permanently remove one of my lists?
      - Can a deleted shortlist be recovered?
      instructions:
      - text: Delete my list {id}.
        slots:
          id: path.id
      - text: Permanently remove shortlist {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/me/lists/{id}/entries'].post
  update:
    x-apievangelist-phrasing:
      intent: Add providers or APIs to a list
      effect: write
      questions:
      - Can I add more providers to a shortlist I already created?
      - Will adding a provider that is already on a list create a duplicate?
      instructions:
      - text: Add {members} to list {id}.
        slots:
          members: requestBody.members
          id: path.id
      - text: Append the providers {members} to my existing list {id}.
        slots:
          members: requestBody.members
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/export'].get
  update:
    x-apievangelist-phrasing:
      intent: Export the default ratings dataset
      effect: read
      questions:
      - Can I pull the whole ratings dataset in one response for publication?
      - What attribution must I cite when publishing exported numbers?
      instructions:
      - text: Export the full default dataset.
      - text: Export the default ratings dataset co-branded as {co_brand}.
        slots:
          co_brand: query.co_brand
      method: generated
      generated: '2026-09-26'
- target: $.paths['/export/{dataset}'].get
  update:
    x-apievangelist-phrasing:
      intent: Export a specific named dataset
      effect: read
      questions:
      - Can I export the providers catalog itself rather than the ratings?
      - Which named datasets, like ratings or providers, can be exported whole?
      instructions:
      - text: Export the {dataset} dataset.
        slots:
          dataset: path.dataset
      - text: Export dataset {dataset} co-branded for {co_brand}.
        slots:
          dataset: path.dataset
          co_brand: query.co_brand
      method: generated
      generated: '2026-09-26'
- target: $.paths['/apis-json'].get
  update:
    x-apievangelist-phrasing:
      intent: Browse APIs.json indexes across the catalog
      effect: read
      questions:
      - Which providers register an APIs.json self-description?
      - Can I read the APIs.json documents of a set of providers?
      instructions:
      - text: List APIs.json indexes for {providers}.
        slots:
          providers: query.providers
      - text: Find APIs.json documents matching {q}.
        slots:
          q: query.q
      method: generated
      generated: '2026-09-26'
- target: $.paths['/cohorts'].get
  update:
    x-apievangelist-phrasing:
      intent: Browse every scored cohort
      effect: read
      questions:
      - What scored populations exist, across tags, industries, regions, areas and VC portfolios?
      - Can I list only cohorts with at least 100 providers?
      instructions:
      - text: List cohorts of kind {kind}.
        slots:
          kind: query.kind
      - text: Show cohorts with at least {min_providers} providers matching {q}.
        slots:
          min_providers: query.min_providers
          q: query.q
      method: generated
      generated: '2026-09-26'
- target: $.paths['/cohorts/compare'].get
  update:
    x-apievangelist-phrasing:
      intent: Compare two cohorts side by side
      effect: read
      questions:
      - How does banking compare to insurance on composite and agent readiness?
      - Can I see deltas between two markets on every facet?
      instructions:
      - text: Compare cohort {a} with cohort {b}.
        slots:
          a: query.a
          b: query.b
      - text: Show facet and adoption deltas between {a} and {b}.
        slots:
          a: query.a
          b: query.b
      method: generated
      generated: '2026-09-26'
- target: $.paths['/cohorts/{kind}/{slug}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a cohort and its member roster
      effect: read
      questions:
      - Who are the members of a cohort, with their Kin Score and agent readiness?
      - How many of a cohort's declared members actually resolve in the catalog?
      instructions:
      - text: Get the {kind} cohort {slug} with its roster.
        slots:
          kind: path.kind
          slug: path.slug
      - text: List every member of {kind} cohort {slug}.
        slots:
          kind: path.kind
          slug: path.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/cohorts/{kind}/{slug}/stats'].get
  update:
    x-apievangelist-phrasing:
      intent: Get score distribution stats for a cohort
      effect: read
      questions:
      - What is the mean and median Kin Score for a whole market?
      - How much of a cohort's roster is actually scored behind its averages?
      instructions:
      - text: Show distribution stats for {kind} cohort {slug}.
        slots:
          kind: path.kind
          slug: path.slug
      - text: Give me the band split and facet averages for {kind} {slug}.
        slots:
          kind: path.kind
          slug: path.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/cohorts/{kind}/{slug}/rankings'].get
  update:
    x-apievangelist-phrasing:
      intent: Rank a cohort by score and agent readiness
      effect: read
      questions:
      - Who leads a market on Kin Score versus on agent readiness?
      - Which members rank very differently on the two leaderboards?
      instructions:
      - text: Rank the members of {kind} cohort {slug}.
        slots:
          kind: path.kind
          slug: path.slug
      - text: Show page {page} of the dual leaderboard for {kind} {slug}.
        slots:
          page: query.page
          kind: path.kind
          slug: path.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/cohorts/{kind}/{slug}/scores'].get
  update:
    x-apievangelist-phrasing:
      intent: Get facet scores relative to the cohort
      effect: read
      questions:
      - How does each member's governance score compare to its market average?
      - Can I see per-facet deltas against the cohort mean for every provider?
      instructions:
      - text: Show cohort-relative facet scores for {kind} {slug}.
        slots:
          kind: path.kind
          slug: path.slug
      - text: Export facet deltas for {kind} cohort {slug} as {format}.
        slots:
          kind: path.kind
          slug: path.slug
          format: query.format
      method: generated
      generated: '2026-09-26'
- target: $.paths['/cohorts/{kind}/{slug}/capabilities'].get
  update:
    x-apievangelist-phrasing:
      intent: See what every cohort member publishes
      effect: read
      questions:
      - What artifacts does each member of a market publish?
      - How do I page through the capability matrix of a very large cohort?
      instructions:
      - text: Show the capability matrix for {kind} cohort {slug}.
        slots:
          kind: path.kind
          slug: path.slug
      - text: Continue the {kind} {slug} capability matrix from cursor {cursor}.
        slots:
          kind: path.kind
          slug: path.slug
          cursor: query.cursor
      method: generated
      generated: '2026-09-26'
- target: $.paths['/providers/{slug}/rating/facets'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a provider's score at facet depth
      effect: read
      questions:
      - Which parts of a provider's composite score can their team actually act on?
      - Does a regulatory regime apply to a vendor's score, and how was it matched?
      instructions:
      - text: Show the facet-level score for {slug}.
        slots:
          slug: path.slug
      - text: Break down {slug}'s composite into facets and any regulatory regime.
        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:
      - Is a provider ready for AI agents, dimension by dimension?
      - Does a vendor have an MCP server, clear auth and idempotency support for agents?
      instructions:
      - text: Show the agent-readiness dimensions for {slug}.
        slots:
          slug: path.slug
      - text: Check how agent-ready {slug} is.
        slots:
          slug: path.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/providers/{slug}/capabilities'].get
  update:
    x-apievangelist-phrasing:
      intent: Count what one provider publishes
      effect: read
      questions:
      - How many artifacts of each type does a provider publish, and which agent dimensions does it meet?
      - What is the free capability count for one vendor's public surface?
      instructions:
      - text: Count {slug}'s published artifacts by type with the agent dimensions it satisfies.
        slots:
          slug: path.slug
      - text: Show the capability counts for {slug}.
        slots:
          slug: path.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/providers/{slug}/evidence'].get
  update:
    x-apievangelist-phrasing:
      intent: See the evidence behind a provider's score
      effect: read
      questions:
      - Which parts of a provider's score were first-party, verified or inferred?
      - Before I quote or dispute a score, where can I check its provenance?
      instructions:
      - text: Show the score evidence for {slug}.
        slots:
          slug: path.slug
      - text: Get the contract coverage and callability behind {slug}'s rating.
        slots:
          slug: path.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/story-leads'].get
  update:
    x-apievangelist-phrasing:
      intent: Get editorial story leads from catalog movement
      effect: read
      questions:
      - What catalog movement would make a good story this week?
      - Are there editorial leads from recent score changes?
      instructions:
      - text: Give me the latest story leads.
      - text: List {limit} story leads from catalog movement.
        slots:
          limit: query.limit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/providers/{slug}/operations'].get
  update:
    x-apievangelist-phrasing:
      intent: List every operation a provider exposes
      effect: read
      questions:
      - What can I actually call on a provider's API, across all its OpenAPIs?
      - Can I list only a vendor's deprecated operations?
      - Which of a provider's operations move money versus just read data?
      instructions:
      - text: List every operation {slug} exposes.
        slots:
          slug: path.slug
      - text: Show {slug}'s {method} operations whose path matches {path}.
        slots:
          slug: path.slug
          method: query.method
          path: query.path
      - text: List {slug}'s operations with deprecated set to {deprecated}.
        slots:
          slug: path.slug
          deprecated: query.deprecated
      method: generated
      generated: '2026-09-26'
- target: $.paths['/providers/{slug}/tools'].get
  update:
    x-apievangelist-phrasing:
      intent: List the MCP tools a provider ships
      effect: read
      questions:
      - What MCP tools does a provider offer, and which operation does each wrap?
      - Can I tell first-party MCP tools apart from ones API Evangelist derived from the OpenAPI?
      instructions:
      - text: List the MCP tools {slug} ships.
        slots:
          slug: path.slug
      - text: Show {slug}'s MCP tools with provenance {provenance}.
        slots:
          slug: path.slug
          provenance: query.provenance
      method: generated
      generated: '2026-09-26'
- target: $.paths['/providers/{slug}/schema'].get
  update:
    x-apievangelist-phrasing:
      intent: List every JSON Schema a provider publishes
      effect: read
      questions:
      - What data shapes does one provider's API work with?
      - Can I search a single vendor's JSON Schemas for a customer object?
      instructions:
      - text: List the JSON Schemas {slug} publishes.
        slots:
          slug: path.slug
      - text: Search {slug}'s schemas for {q}.
        slots:
          slug: path.slug
          q: query.q
      method: generated
      generated: '2026-09-26'
- target: $.paths['/checks'].post
  update:
    x-apievangelist-phrasing:
      intent: Request a re-check of a listing
      effect: write
      questions:
      - What can I do if a listing looks stale or a score seems wrong?
      - Can I ask for a company that isn't in the catalog yet to be added?
      - Is it possible to flag an industry roster that is missing an obvious member?
      instructions:
      - text: Request a check on provider {slug} because {notes}.
        slots:
          slug: requestBody.slug
          notes: requestBody.notes
      - text: Ask for the {target_type} {slug} to be re-checked; contact {contact}.
        slots:
          target_type: requestBody.target_type
          slug: requestBody.slug
          contact: requestBody.contact
      - text: Request that the company at {url} be added to the catalog.
        slots:
          url: requestBody.url
      method: generated
      generated: '2026-09-26'
- target: $.paths['/checks/mine'].get
  update:
    x-apievangelist-phrasing:
      intent: List the check requests I filed
      effect: read
      questions:
      - What check requests have I filed, newest first?
      - Where can I see all my listing re-check requests?
      instructions:
      - text: List my check requests.
      - text: Show every re-check I've filed.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/checks/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Check the status of one check request
      effect: read
      questions:
      - Where does my listing check request stand?
      - Has an operator left any shareable notes on my check?
      instructions:
      - text: Get the status of check {id}.
        slots:
          id: path.id
      - text: Show any shareable notes on check request {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the service record and catalog size
      effect: read
      questions:
      - How many providers, APIs, tags and artifacts does apis.io hold right now?
      - Where are the contract, docs, price list and MCP endpoint for this service?
      instructions:
      - text: Show the service root with catalog counts.
      - text: Confirm the service name and version.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/me'].get
  update:
    x-apievangelist-phrasing:
      intent: View my workspace root and plan
      effect: read
      questions:
      - What plan am I on and how many things have I saved in my workspace?
      - Where do my saved searches, lists and watches live?
      instructions:
      - text: Show my workspace summary.
      - text: Tell me my plan and saved-item counts.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/capabilities'].get
  update:
    x-apievangelist-phrasing:
      intent: Browse the business-capability model
      effect: read
      questions:
      - What can a business actually build from the APIs in the catalog?
      - Which top-level business capabilities are reached by the most providers?
      instructions:
      - text: List business capabilities matching {q}.
        slots:
          q: query.q
      - text: Show the top-level business capabilities with provider counts.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/capabilities/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one capability and who reaches it
      effect: read
      questions:
      - What sub-capabilities sit under a business capability, and which providers reach it?
      - Which external authorities does a capability definition cite?
      instructions:
      - text: Get the business capability {id}.
        slots:
          id: path.id
      - text: Show the sub-capabilities and rated providers for capability {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/capabilities/{id}/edges'].get
  update:
    x-apievangelist-phrasing:
      intent: See the evidence behind a capability
      effect: read
      questions:
      - Says who? What contract fragment proves a provider reaches a capability?
      - What confidence and source file back each provider-to-capability link?
      instructions:
      - text: Show the evidence edges for capability {id}.
        slots:
          id: path.id
      - text: List quoted contract fragments supporting capability {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/providers/{slug}/business-capabilities'].get
  update:
    x-apievangelist-phrasing:
      intent: See what a vendor's APIs let a business do
      effect: read
      questions:
      - What is a vendor actually for, judged by its own contracts?
      - Which business capabilities do a provider's APIs roll up to?
      instructions:
      - text: Show the business capabilities {slug}'s APIs support.
        slots:
          slug: path.slug
      - text: Roll up {slug}'s APIs by business capability with tag evidence.
        slots:
          slug: path.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/agent-readiness'].get
  update:
    x-apievangelist-phrasing:
      intent: Rank providers by agent readiness
      effect: read
      questions:
      - Which providers across the catalog are most ready for AI agents?
      - Can I find providers that have an MCP server but no agent card?
      instructions:
      - text: Rank providers that have {has}.
        slots:
          has: query.has
      - text: List providers missing {missing}.
        slots:
          missing: query.missing
      method: generated
      generated: '2026-09-26'
- target: $.paths['/agent-readiness/dimensions'].get
  update:
    x-apievangelist-phrasing:
      intent: See adoption of each agent-readiness dimension
      effect: read
      questions:
      - What share of scored providers has an MCP server or agent card today?
      - How far has each agent-readiness dimension spread across the catalog?
      instructions:
      - text: Show adoption shares for every agent-readiness dimension.
      - text: Tell me how many providers satisfy each agent dimension.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/providers/{slug}/remediation'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a ranked fix list for a provider
      effect: read
      questions:
      - Which rubric checks does a provider fail, and what is each worth?
      - In what order should a vendor fix things to raise its score?
      instructions:
      - text: Show the ranked remediation plan for {slug}.
        slots:
          slug: path.slug
      - text: List the failing checks for {slug} with their value.
        slots:
          slug: path.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/providers/{slug}/gates'].get
  update:
    x-apievangelist-phrasing:
      intent: See which bands a provider is gated out of
      effect: read
      questions:
      - Is a provider blocked from a band no matter how many points it earns?
      - What band gates apply to a vendor before its score counts?
      instructions:
      - text: Show the band gates for {slug}.
        slots:
          slug: path.slug
      - text: Check which bands {slug} cannot reach.
        slots:
          slug: path.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/providers/{slug}/projection'].get
  update:
    x-apievangelist-phrasing:
      intent: Project a score from a few fixes via URL
      effect: read
      questions:
      - Can I quickly preview a projected score by passing check ids in the query string?
      - Where would a provider's band land after a couple of named fixes?
      instructions:
      - text: Project {slug}'s score if checks {fixes} are fixed.
        slots:
          slug: path.slug
          fixes: query.fixes
      - text: Show {slug}'s current projection with no fixes applied.
        slots:
          slug: path.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/providers/{slug}/projection'].post
  update:
    x-apievangelist-phrasing:
      intent: Simulate a score after a list of fixes
      effect: read
      questions:
      - If we fix a long list of checks, will buying those points still leave us demoted?
      - Can I post a body of check ids to simulate a provider's new score and band?
      instructions:
      - text: Simulate {slug}'s score and band after fixing {fixes}.
        slots:
          slug: path.slug
          fixes: requestBody.fixes
      - text: Post fixes {fixes} for {slug} and re-apply the band gate.
        slots:
          fixes: requestBody.fixes
          slug: path.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/operations'].get
  update:
    x-apievangelist-phrasing:
      intent: Find which providers expose a given path
      effect: read
      questions:
      - Who has a POST /refunds endpoint across the catalog?
      - Can I search every provider's paths for payment intents?
      instructions:
      - text: Find providers exposing a path matching {q}.
        slots:
          q: query.q
      - text: Search all providers for {method} operations on {q}.
        slots:
          method: query.method
          q: query.q
      method: generated
      generated: '2026-09-26'
- target: $.paths['/operations/deprecated'].get
  update:
    x-apievangelist-phrasing:
      intent: List providers with deprecated operations
      effect: read
      questions:
      - Which providers have the most operations marked deprecated in their own OpenAPIs?
      - Where can I see a lifecycle view of deprecations across the catalog?
      instructions:
      - text: List providers publishing deprecated operations.
      - text: Show page {page} of providers ranked by deprecated operation count.
        slots:
          page: query.page
      method: generated
      generated: '2026-09-26'
- target: $.paths['/cohorts/{kind}/{slug}/history'].get
  update:
    x-apievangelist-phrasing:
      intent: See how a cohort's scores moved over time
      effect: read
      questions:
      - How has the banking market's average score moved over six months?
      - How many members were scored on each date in a cohort's time series?
      instructions:
      - text: Show the score history for {kind} cohort {slug}.
        slots:
          kind: path.kind
          slug: path.slug
      - text: Chart the mean score over time for {kind} {slug}.
        slots:
          kind: path.kind
          slug: path.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/cohorts/{kind}/{slug}/failures'].get
  update:
    x-apievangelist-phrasing:
      intent: Find the checks a cohort most often fails
      effect: read
      questions:
      - Which rubric checks do most members of an industry fail?
      - What single fix would lift a market's mean score the most?
      instructions:
      - text: Show the most common failed checks in {kind} cohort {slug}.
        slots:
          kind: path.kind
          slug: path.slug
      - text: Rank the failures of {kind} {slug} by impact on the mean.
        slots:
          kind: path.kind
          slug: path.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/providers/{slug}/claim'].post
  update:
    x-apievangelist-phrasing:
      intent: Claim a provider listing as yours
      effect: write
      questions:
      - How do I prove to apis.io that a listing belongs to my company?
      - Where do I publish the verification token when claiming a listing?
      instructions:
      - text: Start a claim on the listing {slug}.
        slots:
          slug: path.slug
      - text: Get the claim token and hosts to verify for {slug}.
        slots:
          slug: path.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/providers/{slug}/generate'].post
  update:
    x-apievangelist-phrasing:
      intent: See which artifacts can be generated for me
      effect: read
      questions:
      - What artifacts can be generated for my listing, and what file does each produce?
      - Which generated artifacts are available to request for a provider?
      instructions:
      - text: List the artifacts that can be generated for {slug}.
        slots:
          slug: path.slug
      - text: Show generatable artifact options for {slug}.
        slots:
          slug: path.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/providers/{slug}/generate/{artifact}'].post
  update:
    x-apievangelist-phrasing:
      intent: Request a generated artifact you lack
      effect: write
      questions:
      - Can someone generate the MCP or Arazzo file my listing is marked down for missing?
      - Is a requested artifact published for me, or do I commit it myself?
      instructions:
      - text: Request a {artifact} artifact for {slug}.
        slots:
          artifact: path.artifact
          slug: path.slug
      - text: Ask for a generated {artifact} file for my listing {slug}.
        slots:
          artifact: path.artifact
          slug: path.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/providers/{slug}/submit'].post
  update:
    x-apievangelist-phrasing:
      intent: Submit an artifact you already publish
      effect: write
      questions:
      - How can I point the catalog at an OpenAPI we already publish?
      - Can I submit an artifact URL instead of waiting to be discovered?
      instructions:
      - text: Submit the {type} at {url} for {slug}.
        slots:
          type: requestBody.type
          url: requestBody.url
          slug: path.slug
      - text: Tell the catalog {slug} publishes a {type} at {url}; contact {contact}.
        slots:
          slug: path.slug
          type: requestBody.type
          url: requestBody.url
          contact: requestBody.contact
      method: generated
      generated: '2026-09-26'
- target: $.paths['/providers/{slug}/facts'].post
  update:
    x-apievangelist-phrasing:
      intent: Propose corrections to a provider's facts
      effect: write
      questions:
      - Can I fix the name or description the catalog shows for my company?
      - Which fields can I propose changes to, and can I change my score that way?
      instructions:
      - text: 'Propose a new description for {slug}: {description}.'
        slots:
          slug: path.slug
          description: requestBody.description
      - text: Correct {slug}'s tags to {tags} and industries to {industries}.
        slots:
          slug: path.slug
          tags: requestBody.tags
          industries: requestBody.industries
      method: generated
      generated: '2026-09-26'
- target: $.paths['/providers/{slug}/dispute'].post
  update:
    x-apievangelist-phrasing:
      intent: Dispute a finding about a provider
      effect: write
      questions:
      - What if the catalog says we lack something we actually publish?
      - Do I have to prove ownership before disputing a finding?
      instructions:
      - text: 'Dispute a finding on {slug}: {claim}.'
        slots:
          slug: path.slug
          claim: requestBody.claim
      - text: Tell apis.io {claim} for {slug}, with evidence 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}/visibility'].post
  update:
    x-apievangelist-phrasing:
      intent: Request restricted or delisted visibility
      effect: destructive
      questions:
      - Can my company be removed from the catalog entirely?
      - What does restricted visibility keep compared to being delisted?
      instructions:
      - text: Set {slug}'s visibility to {visibility}.
        slots:
          slug: path.slug
          visibility: requestBody.visibility
      - text: Ask for {slug} to be {visibility} because {reason}.
        slots:
          slug: path.slug
          visibility: requestBody.visibility
          reason: requestBody.reason
      method: generated
      generated: '2026-09-26'
- target: $.paths['/me/watch'].get
  update:
    x-apievangelist-phrasing:
      intent: List the listings I'm watching
      effect: read
      questions:
      - Which provider listings am I currently watching?
      - Where do I see all my listing watch registrations?
      instructions:
      - text: List my watched listings.
      - text: Show every provider I've set a watch on.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/me/watch/{slug}'].post
  update:
    x-apievangelist-phrasing:
      intent: Watch a listing for score or band changes
      effect: write
      questions:
      - Can I get notified when a provider's score or band changes?
      - Will a webhook callback work for listing change alerts?
      instructions:
      - text: Watch {slug} and email {contact} when it moves.
        slots:
          slug: path.slug
          contact: requestBody.contact
      - text: Watch {slug} for {events} and post to {callback_url}.
        slots:
          slug: path.slug
          events: requestBody.events
          callback_url: requestBody.callback_url
      method: generated
      generated: '2026-09-26'
- target: $.paths['/me/watch/{slug}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Stop watching a listing
      effect: destructive
      questions:
      - How do I stop getting alerts about a provider listing?
      - Can I unsubscribe from one watched listing?
      instructions:
      - text: Stop watching {slug}.
        slots:
          slug: path.slug
      - text: Remove my watch on {slug}.
        slots:
          slug: path.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/estates'].get
  update:
    x-apievangelist-phrasing:
      intent: List corporate estates
      effect: read
      questions:
      - Which companies have their APIs spread across many provider records?
      - Are two provider slugs really the same company?
      instructions:
      - text: List corporate estates matching {q}.
        slots:
          q: query.q
      - text: Show the largest corporate estates by member count.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/estates/{slug}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one corporate estate and its members
      effect: read
      questions:
      - Which provider records belong to one company's estate, with their bands?
      - What is the estate-wide rating for a large company?
      instructions:
      - text: Get the estate {slug} with its full member roster.
        slots:
          slug: path.slug
      - text: Show the estate-wide rating for {slug}.
        slots:
          slug: path.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/providers/{slug}/estate'].get
  update:
    x-apievangelist-phrasing:
      intent: Find the corporate estate a provider belongs to
      effect: read
      questions:
      - Is a provider part of a larger parent company?
      - Which estate does a given provider slug roll up into?
      instructions:
      - text: Find which estate {slug} belongs to.
        slots:
          slug: path.slug
      - text: Check whether {slug} is part of a larger company.
        slots:
          slug: path.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/auth/providers'].get
  update:
    x-apievangelist-phrasing:
      intent: List the configured sign-in providers
      effect: read
      questions:
      - Which identity providers can I sign in with?
      - Where does the browser sign-in flow start for each login option?
      instructions:
      - text: List the available sign-in providers.
      - text: Show the login URL for each identity provider.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/auth/login'].get
  update:
    x-apievangelist-phrasing:
      intent: Start browser sign-in with an identity provider
      effect: read
      questions:
      - How does a person sign in through the browser to get a Learn key?
      - Can an agent finish sign-in on its own, or must a human complete it?
      instructions:
      - text: Start browser sign-in with {provider}.
        slots:
          provider: query.provider
      - text: Give me the sign-in link to hand to a person for {provider}.
        slots:
          provider: query.provider
      method: generated
      generated: '2026-09-26'
- target: $.paths['/auth/me'].get
  update:
    x-apievangelist-phrasing:
      intent: See my identity, tier, key and usage
      effect: read
      questions:
      - Which key am I using, what tier am I on, and how much have I used today?
      - How many calls remain in my daily window?
      instructions:
      - text: Show my account tier and usage.
      - text: Tell me which API key I'm calling with.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/auth/me'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete my account
      effect: destructive
      questions:
      - How can I erase my account completely?
      - Is account deletion reversible?
      instructions:
      - text: Delete my account permanently.
      - text: Erase this agent principal's account.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/auth/me'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update my account settings
      effect: write
      questions:
      - Can I change my account settings with an API key, or do I need a browser session?
      - Where do I update my account preferences?
      instructions:
      - text: Update my account settings from my signed-in session.
      - text: Change my account preferences.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/auth/me/export'].get
  update:
    x-apievangelist-phrasing:
      intent: Export all data held about me
      effect: read
      questions:
      - Can I get a copy of everything held about my account, keys and usage?
      - Is there a data-subject export for my account?
      instructions:
      - text: Export all the data held about my account.
      - text: Download my personal data export.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/auth/keys'].get
  update:
    x-apievangelist-phrasing:
      intent: List my API keys
      effect: read
      questions:
      - Which API keys exist on my account?
      - Why do I need a signed-in session to see my keys?
      instructions:
      - text: List my API keys.
      - text: Show the keys on my account so I can rotate one.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/auth/keys'].delete
  update:
    x-apievangelist-phrasing:
      intent: Revoke an API key
      effect: destructive
      questions:
      - How do I revoke an API key that leaked?
      - Can I kill a key from a web session?
      instructions:
      - text: Revoke my API key.
      - text: Revoke the compromised key on my account.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/auth/logout'].post
  update:
    x-apievangelist-phrasing:
      intent: Sign out of the web session
      effect: write
      questions:
      - Does logging out also revoke my API keys?
      - What is the way to end my browser session?
      instructions:
      - text: Sign me out of the web session.
      - text: Log out and clear my session cookie.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/auth/authorize'].get
  update:
    x-apievangelist-phrasing:
      intent: Begin OAuth authorization with PKCE
      effect: read
      questions:
      - Where is the OAuth 2.1 authorization endpoint for the authorization-code flow?
      - What scope does a self-registered client get when it authorizes?
      instructions:
      - text: Start an OAuth authorization-code flow with PKCE.
      - text: Send the user to the OAuth authorize endpoint.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/auth/token'].post
  update:
    x-apievangelist-phrasing:
      intent: Exchange a code or refresh token for access
      effect: write
      questions:
      - How do I trade an authorization code and PKCE verifier for an access token?
      - Can I use a refresh token to get a new access token?
      instructions:
      - text: Exchange my authorization code for an access token.
      - text: Refresh my OAuth access token.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/auth/register'].post
  update:
    x-apievangelist-phrasing:
      intent: Register an OAuth client dynamically
      effect: write
      questions:
      - Can I register a public OAuth client without a key?
      - What happens to a registered client that never exchanges for a token?
      instructions:
      - text: Register an OAuth client named {client_name}.
        slots:
          client_name: requestBody.client_name
      - text: Register client {client_name} with redirect URIs {redirect_uris}.
        slots:
          client_name: requestBody.client_name
          redirect_uris: requestBody.redirect_uris
      method: generated
      generated: '2026-09-26'
- target: $.paths['/auth/register/{client_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Read a registered OAuth client
      effect: read
      questions:
      - How do I read back the metadata of an OAuth client I registered?
      - Why would reading my registered client return invalid_token?
      instructions:
      - text: Read the registered OAuth client {client_id}.
        slots:
          client_id: path.client_id
      - text: Show the metadata for client {client_id}.
        slots:
          client_id: path.client_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/auth/register/{client_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a registered OAuth client's metadata
      effect: write
      questions:
      - Can I change the redirect URIs of a client I already registered?
      - Does updating a registered client make it permanent?
      instructions:
      - text: Update the metadata of OAuth client {client_id}.
        slots:
          client_id: path.client_id
      - text: Replace client {client_id}'s registration details.
        slots:
          client_id: path.client_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/auth/register/{client_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a registered OAuth client
      effect: destructive
      questions:
      - How do I remove an OAuth client I registered?
      - Can a dynamic client registration be undone?
      instructions:
      - text: Delete OAuth client {client_id}.
        slots:
          client_id: path.client_id
      - text: Remove the registered client {client_id}.
        slots:
          client_id: path.client_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/billing/access/terms'].get
  update:
    x-apievangelist-phrasing:
      intent: Read the pay-as-you-go mandate terms
      effect: read
      questions:
      - What terms do I accept when letting a saved card be charged automatically?
      - What are the caps and escalation ladder for automatic top-ups?
      instructions:
      - text: Show the current pay-as-you-go terms.
      - text: Fetch the versioned billing mandate.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/billing/access/setup'].post
  update:
    x-apievangelist-phrasing:
      intent: Put a card on file for pay-as-you-go
      effect: write
      questions:
      - How do I save a card for metered pay-as-you-go access?
      - Why would saving a card return access_not_live?
      instructions:
      - text: Set up a card on file for pay-as-you-go.
      - text: Save my card for metered billing.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/billing/access/topup'].post
  update:
    x-apievangelist-phrasing:
      intent: Add prepaid credit
      effect: write
      questions:
      - Can I prepay credit for pay-as-you-go calls?
      - Is topping up my balance available yet?
      instructions:
      - text: Top up my prepaid balance.
      - text: Add credit to my pay-as-you-go account.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/billing/access/settings'].post
  update:
    x-apievangelist-phrasing:
      intent: Set top-up amount, floor and spend caps
      effect: write
      questions:
      - Can I cap how much pay-as-you-go spends automatically?
      - Where do I set the balance floor that triggers a top-up?
      instructions:
      - text: Update my top-up amount and spend caps.
      - text: Change the floor that triggers automatic top-up.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/billing/checkout'].post
  update:
    x-apievangelist-phrasing:
      intent: Subscribe to a paid plan
      effect: write
      questions:
      - How do I upgrade to the Understanding or Influence plan?
      - Can I choose annual or monthly billing when I subscribe?
      instructions:
      - text: Start checkout for the {tier} plan.
        slots:
          tier: requestBody.tier
      - text: Subscribe me to {tier} billed {cycle}.
        slots:
          tier: requestBody.tier
          cycle: requestBody.cycle
      method: generated
      generated: '2026-09-26'
- target: $.paths['/billing/portal'].post
  update:
    x-apievangelist-phrasing:
      intent: Open the subscription billing portal
      effect: write
      questions:
      - Where do I manage or cancel my existing subscription?
      - Can I get a link to update my payment method on my plan?
      instructions:
      - text: Open my billing portal.
      - text: Get me a link to manage my subscription.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/regulations'].get
  update:
    x-apievangelist-phrasing:
      intent: List the regulations the catalog tracks
      effect: read
      questions:
      - Which regulations apply to providers regardless of industry?
      - What laws and regulator guidance does API Evangelist track for a jurisdiction?
      instructions:
      - text: List regulations in jurisdiction {jurisdiction}.
        slots:
          jurisdiction: query.jurisdiction
      - text: Show regulations with scope {scope} of kind {kind}.
        slots:
          scope: query.scope
          kind: query.kind
      method: generated
      generated: '2026-09-26'
- target: $.paths['/regulations/{slug}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one regulation and the cohorts it binds
      effect: read
      questions:
      - Which countries, regions and industries does a particular law reach?
      - Where is the link to the text of a regulation and its scope?
      instructions:
      - text: Get the regulation {slug}.
        slots:
          slug: path.slug
      - text: Show which cohorts regulation {slug} reaches.
        slots:
          slug: path.slug
      method: generated
      generated: '2026-09-26'