Discovering APIs via Catalog
Given a company name or a task description, resolve it to a catalog record and act on it:
1. resolve "stripe.com" -> GET /api/v1/providers?domain=stripe.com
-> { slug: "stripe", score: 94, band: "gold" }
2. GET /api/v1/providers/stripe/apis
-> list of APIs with aid, name, category
3. GET /api/v1/apis/{aid}/spec -> OpenAPI/AsyncAPI/GraphQL/Postman doc
4. Parse spec, answer the user's question or generate integration code.
If the user names a company rather than a slug (the common case), always resolve first — never guess a slug from the company name.
Progress:
- Step 1: Identify intent — find an API, inspect a spec, onboard a provider, check agent-readiness, score an API, or research a market/cohort
- Step 2: Resolve any company/domain/URL/GitHub org to a provider slug via
/api/v1/providers?domain=or?q= - Step 3: Call the narrowest matching endpoint (see routing table below)
- Step 4: If response is HTTP 402, fall back to the free-tier subset and say what Pro would add
- Step 5: Cite provenance — distinguish first-party provider claims from apis.io-derived scores before stating them as fact
- Step 6: Present a concrete answer: a recommendation, a ranked punch list, a shortlist, or runnable integration steps — not a dump of raw JSON
Routing table (intent → endpoint/skill behavior):
| User intent | Action |
|---|---|
| "What API exists for X?" | search /api/v1/apis?q= + ?capability=, rank, recommend top 1 with spec link |
| "Who makes a company's API?" | resolve provider by domain/name first |
| "Show me the endpoints/spec" | GET /api/v1/apis/{aid}/spec, parse OpenAPI/AsyncAPI/GraphQL/Postman |
| "Help me integrate with X" | resolve provider → pull signup, auth, base URL, spec → write first-call steps |
| "Is X agent-ready?" | check for MCP server, Agent Skills, llms.txt, machine-readable contracts |
| "Find MCP servers / skills" | /api/v1/mcp-servers or /api/v1/skills filtered by provider/capability |
| "How does my API score?" | pull Kin Score rubric + provider score, produce ranked next-publish list |
| "Compare my API to peers" | pull peer set by category, diff facet scores (Pro; degrade gracefully) |
| "Shortlist vendors for X" | score candidates, compare, recommend (Pro) |
| "Research a market/sector" | treat as a cohort — pull member list with scores and agent-readiness |
| "What's a company buying?" | reverse lookup — their stack vs. catalog providers (demand side) |
| "Has anything changed?" | diff against last-seen state via saved search / list (Pro, free fallback = manual recheck) |
Example 1: Input: "What should I use for sending transactional email?" Output: Searched apis.io for capability=email+transactional, found 6 candidates. Top pick: Postmark (gold band, 91/100) — has OpenAPI 3.1, signup API, and rate-limit docs. Runner-up: SendGrid (silver, 78/100, spec incomplete). Recommendation: Postmark, with its spec link and a 5-step first-integration snippet.
Example 2: Input: "Is Twilio ready for AI agents to use?" Output: Twilio publishes OpenAPI 3.0 (machine-readable), no MCP server found in catalog, no llms.txt, no published Agent Skills. Agent-readiness: partial — good contract, no agent-native tooling. Compare to peers who publish MCP servers if the user wants alternatives.
Example 3: Input: "How does acme-api.com's API score and what should they fix first?" Output: Pulled Kin Score for acme (62/100, bronze). Breakdown shows missing: rate-limit docs (+8), OpenAPI examples (+6), pricing artifact (+5). Ranked punch list: publish rate limits first (highest point gain, lowest effort), then spec examples, then pricing.
- Always resolve company names to provider slugs before querying — don't assume the slug matches the domain.
- Prefer the narrowest endpoint (spec, artifact-type-specific search) over a generic keyword search when the artifact type is known.
- Separate what a provider claims (first-party) from what apis.io computed (derived score) — flag this distinction whenever a score or rating is quoted back to a user, especially if they might dispute it.
- Default to the free tier; only mention Pro features if the user's request actually needs comparison, gaps, scopes, security detail, saved searches, or export.
- When recommending one API among many, always attach the spec link and a concrete next step, not just a name.
- For "onboard this provider" tasks, pull signup, auth, base URL, and spec together in one pass rather than round-tripping per field.
- Don't guess a provider slug from a company name — resolve via domain/name lookup first; slugs don't always match.
- Don't treat a 402 response as a dead end — fall back to the free-tier answer and note what's gated, rather than failing silently.
- Don't present a derived Kin Score as a provider's own claim, or vice versa — always check provenance first when it matters.
- Don't scrape the HTML catalog pages — use the v1 REST API, MCP server, or markdown mirror; HTML is not the intended interface.
- Don't recommend an API based on name recognition alone — check the spec actually exists and is parseable before recommending it as the answer.
- Don't run one-off checks for "watch this vendor" style requests — point toward saved searches/lists for recurring monitoring instead of repeating manual queries.