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 is short by 33 endpoints. The contract we serve describes 96 paths; the
one we test against describes 129, and both stamp version: 1.6.0. The missing third is the entire
own-your-listing surface — claim, dispute, correct, request a check — so an agent reading our
contract cannot discover the very actions this page is asking providers to take. Found by
measurement 2026-09-09, guarded by a test now, fix queued.
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.
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.