API Evangelist conversational phrasing for APIs.io API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for APIs.io 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'


# --- truncated at 32 KB (96 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/apis-io/refs/heads/main/overlays/apis-io-v1-phrasing-overlay.yaml