The Blueprint
Everything APIs.io publishes for machines, in one list — what each document says, the specification behind it, and what it is worth on the Kin Score. All of it is fetchable right now, none of it is bespoke, and copying it is the point.
That third number is the argument. Fifty-eight of the hundred and thirty-nine points in Agent Readiness are earned by publishing documents about an API you already have — not by rewriting it. A provider that adds nothing but files moves a long way up the rating, because most of what an agent needs to know was never in the API to begin with. It was in a portal, a PDF, and somebody’s head.
The eleven files
Every URL below is live. Fetch them, read them, copy the shape.
| Document | What it tells a machine | Specification | Kin Score |
|---|---|---|---|
| api-catalog | Every API surface we run and where its description, docs and metadata live. One fetch and an agent has the map. | RFC 9727 + RFC 9264 linkset | 4 Well-Known Catalog |
| oauth-protected-resource | This resource is protected, and here is who protects it. Naming the authorization server is what turns a lock into a key. | RFC 9728 | 5 Protected Resource Metadata |
| oauth-authorization-server | Issuer, endpoints, grants and scopes. Carries registration_endpoint, which is the difference between an agent onboarding itself and a developer filling in a form. |
RFC 8414, RFC 7591 | 21 Auth Clarity 9 · Registration 6 · Delegated Identity 6 |
| mcp/server-card.json | An MCP server exists, at this URL, with these tools and this auth. The card is the pointer; the points come from the server answering. | Model Context Protocol | 12 MCP Server · probed |
| agent-skills/index.json | Task-shaped instructions an agent can load — what you can actually do here, not just which endpoints exist. | Agent Skills | 5 Agent Skills |
| http-message-signatures-directory | The public keys our signed requests are made with, so a caller can be identified rather than merely rate-limited. | RFC 9421, Web Bot Auth | 3 Consent & Bot Identity |
| api-onboarding | What it takes to get in — the doors, the tiers, the credential shapes, and what we require of a consumer. The part OpenAPI never described. | API Onboarding Descriptor | — not yet scored |
| aauth-resource.json | We can authenticate an agent we have never registered, by signature rather than by shared secret. | draft-hardt-oauth-aauth-protocol |
— counts toward Well-Known Published |
| security.txt | Who to tell when something is wrong. | RFC 9116 | — counts toward Well-Known Catalog |
| llms.txt | The plain-text orientation an arriving model reads first. | llms.txt | — discovery, not a scored dimension |
| agent-card.json | What this agent is, what it can do, and how to reach it. Graded on conformance rather than presence — ours is near-conformant and says why. | A2A 1.0.0 | 8 A2A Agent Card · graded |
Serving the file is half of it — point at it too. Several of these dimensions are read from
the common[] pointers in your APIs.json, not from a blind sweep of your domain: Well-Known
Catalog looks for a WellKnown / APICatalog entry, and Consent & Bot Identity looks for
WebBotAuth or HTTPMessageSignatures. A document served at the right path and never declared is
a document we have no reason to go looking for. Publish your APIs.json and
list what you serve.
MCP is scored on a probe, not a pointer. The 12 points need a server card and a server that answers. A card describing an endpoint that does not respond earns the same as no card.
Points are the dimension at full credit, and several are graded. Auth Clarity pays 10 for a bound credential (mTLS, DPoP, HTTP signatures) and 9 for a served discovery document; Protected Resource Metadata pays 5 when it names its authorization servers and 2.5 when it merely declares a resource. The rubric is public and every score recomputable — read it rather than taking this table’s word for it.
The other eighty-one points are in the contract
Files get you halfway. The rest is what your OpenAPI actually says, and these are the four that most providers leave on the table:
| Dimension | What earns it | Points |
|---|---|---|
| Machine-Readable Contract | An OpenAPI document at all. The floor, and the largest single dimension. | 18 |
| Idempotency | Mutating operations that declare an Idempotency-Key header — declared in the contract, not just honoured by the server. | 9 |
| Rate-Limit Signaling | RateLimit / X-RateLimit-* documented on responses, so a caller reads its budget instead of guessing it. | 7 |
| Request/Response Examples | Real examples in the contract. An agent that has seen one correct call makes far fewer wrong ones. | 7 |
| Documented Reversibility | A reversal operation, graded up when the window is documented too. An agent that cannot undo will not act. | 6 |
Idempotency is the cheapest big win and almost nobody declares it. The header is usually already supported; saying so in the contract is a schema edit.
What we do not serve, and why that is on this page
A blueprint that only lists successes is marketing. These are ours, open on the road map:
Our A2A agent card is near-conformant, not conformant — 4.8 of 8 points. It is served at
/.well-known/agent-card.json and it records four deviations
against itself, because that is more useful than a claim of conformance: we serve no A2A JSON-RPC
endpoint, preferredTransport reads MCP which A2A does not define, the pre-0.3
/.well-known/agent.json alias is absent, and subdomain probes rewrite the path instead of
resolving to the apex card.
This is the pattern worth copying, more than the file is. Naming your own deviations costs a few points and buys something a conformance badge cannot: a reader who knows exactly what they are getting. A card that advertised an endpoint we do not serve would score better and be worth less.
Our published OpenAPI was short by 33 endpoints — fixed 2026-09-10. The contract we served
described 96 paths while the one we test against described 129, and both stamped version: 1.6.0.
The missing third was the entire own-your-listing surface — claim, dispute, correct, request a
check — so an agent reading our contract could not discover the very actions this page asks
providers to take. Both copies are now byte-identical at 129 paths and a test fails if they ever
separate again.
It is left on this page rather than deleted, because the interesting part is not the fix. Nothing detected this for months: the suite validated the copy the portal builds from, the world was served a different file, and no check compared them. If you keep two copies of your contract, something has to compare them — that is the transferable lesson, and it cost us more than it should have.
No agentic-commerce document. /.well-known/ucp.json is absent, correctly — we are not a
storefront. Worth saying out loud, because an absent document and an unearned point are different
facts and the rating should not blur them.
Start where the leverage is
- Serve
/.well-known/api-catalog. One file, and every other document below becomes findable. - Serve RFC 9728 and RFC 8414 metadata. If you already run OAuth, both are descriptions of infrastructure you have. That is 21 points for publishing facts about yourself.
- Declare
Idempotency-Keyon your mutating operations. A schema edit. - Then the harder ones — MCP, agent skills, examples, reversibility.
What reaching exemplar earns you
The rating is not only a number on a page. Every provider in the exemplar band is measured on Model Visibility, free — what Claude, ChatGPT and Gemini actually say about your API, whether it is true, and whether any of it came from us. Three assistants, asked both with and without live search, checked against your own published artifacts rather than against an opinion.
Almost nobody can compute that about you. We can, because we already hold verified ground truth about what you publish — which is the same reason the score exists at all.
That is the whole loop, and it is why this page is worth your afternoon: the documents that raise your Kin Score are the documents that make assistants describe you correctly. An OpenAPI a model can read is an OpenAPI a model can quote. Below exemplar the measurement is available on request as part of the Influence tier; at exemplar it is simply yours.
See your own numbers
The rating is not something we do to you. Add your API and the probe reads your
apis.json, your onboarding descriptor, your OpenAPI, your llms.txt and your MCP endpoint before
it asks you to fill in anything. Every score is recomputable from a public rubric, and if we are
wrong about you, say so — corrections are free and always will be.
Machines can ask too: the whole catalog, any provider, and the scoring rubric are on the API and MCP server, keyless.