# 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 Cohorts API
  version: 1.0.0
extends: openapi/apis-io-cohorts-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-09-26'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 7
- target: $.paths['/cohorts'].get
  update:
    x-apievangelist-phrasing:
      intent: Browse scored market cohorts
      effect: read
      questions:
      - What scored cohorts exist across tags, industries, regions, areas and VC portfolios?
      - Which cohorts are big enough to reach the report promotion tier?
      instructions:
      - text: List cohorts of kind {kind}.
        slots:
          kind: query.kind
      - text: Find cohorts matching {q} with at least {min_providers} providers.
        slots:
          q: query.q
          min_providers: query.min_providers
      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 one industry compare to a tag cohort on agent readiness?
      - Can I see the score deltas between two markets on every facet?
      instructions:
      - text: Compare cohort {a} with cohort {b}.
        slots:
          a: query.a
          b: query.b
      - text: Show the facet and adoption-rate 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 given cohort, with their Kin Scores?
      - How many providers in a cohort's declared roster actually resolve to the catalog?
      instructions:
      - text: Get the {kind} cohort {slug} with its member roster.
        slots:
          kind: path.kind
          slug: path.slug
      - text: Show who belongs to cohort {slug} of kind {kind}.
        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 the score distribution for a cohort
      effect: read
      questions:
      - What is the mean and median Kin Score for a whole market?
      - Can I get the band split and artifact adoption rates for a cohort?
      instructions:
      - text: Get the score distribution for the {kind} cohort {slug}.
        slots:
          kind: path.kind
          slug: path.slug
      - text: Show the mean, median and spread of scores for cohort {slug} of kind {kind}.
        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 cohort on Kin Score, and who leads it on agent readiness?
      - Which providers rank very differently on composite than on agent readiness?
      instructions:
      - text: Show the leaderboard for the {kind} cohort {slug}.
        slots:
          kind: path.kind
          slug: path.slug
      - text: Rank the members of cohort {slug} ({kind}), {limit} per page.
        slots:
          kind: path.kind
          slug: path.slug
          limit: query.limit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/cohorts/{kind}/{slug}/scores'].get
  update:
    x-apievangelist-phrasing:
      intent: Get facet scores relative to a cohort average
      effect: read
      questions:
      - How does each provider's governance facet compare to its cohort's average?
      - Can I see per-facet deltas against the market average for every member?
      instructions:
      - text: Get cohort-relative facet scores for the {kind} cohort {slug}.
        slots:
          kind: path.kind
          slug: path.slug
      - text: Export the per-facet scores for cohort {slug} of kind {kind} 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 each cohort member publishes
      effect: read
      questions:
      - What artifacts does every member of a cohort publish, by type?
      - Which agent-readiness dimensions does each provider in a market satisfy?
      instructions:
      - text: Show the capability matrix for the {kind} cohort {slug}.
        slots:
          kind: path.kind
          slug: path.slug
      - text: List artifact counts per member of cohort {slug} ({kind}).
        slots:
          kind: path.kind
          slug: path.slug
      method: generated
      generated: '2026-09-26'