Agentic discovery and onboarding · walked through, step by step
On October 15, 2026 I ran our own agent, API Evangelist, against four small APIs I operate: Yawplet, Yarnhen, Hagglebee and Eventwren. It found each one on APIs.io, proved who it was, and each site decided on its own to trust it — in under seven seconds per site. This page walks through that flow one step at a time, with what was actually sent and returned, using Yawplet as the example. Scroll, and the diagram follows.
An agent usually arrives knowing what it wants to do, not which company does it. So the first call is a plain keyless search of the APIs.io catalog for "post short messages". No account, no key.
GET https://apis.io/api/v1/search?q=post+short+messages
Discovery has to work by need. In the first run it mostly did for providers and not at all for their APIs, which is why the API descriptions were rewritten and search was changed the same day.
The catalog knows Yawplet because Yawplet is listed there like any other provider, with its contract, docs, pricing and agent card. The agent now has a domain to go to.
"providers": { "top": [ { "slug": "yawplet", "name": "Yawplet", "website": "https://yawplet.com" }, … ] }
The A2A agent card says what the agent can ask for. The API Onboarding Descriptor says how to get in, what the provider checks about an agent, and what still needs a person. Both sit at well-known paths, so the agent doesn't need to read documentation to find them.
GET https://yawplet.com/.well-known/agent-card.json GET https://yawplet.com/.well-known/api-onboarding
The descriptor lists one optional verification: present an APIs.io attestation and, at the anchored tier with a verified key binding, be recorded as trusted. Its gaps say plainly that a person has to fund the account once.
"verification": [{ "facet": "identity_anchor", "min_grade": "verified", "blocking": false }]
"gaps": [ "A person is needed once, for money: …" ]
An agent should learn the rules before it starts, not at a 402.
Every request the agent makes to APIs.io is signed with a key published on apievangelist.com (Web Bot Auth). That signature is how APIs.io knows which agent is asking, without a password or an API key.
GET https://apis.io/api/v1/kya/match?provider=https://yawplet.com Signature-Agent: sig1="https://apievangelist.com"
APIs.io compares the agent's Know Your Agent record against Yawplet's descriptor and says what is met and what is missing. Here, nothing is missing.
{ "provider": "https://yawplet.com", "ready": true, "met": [ { "requirement": "identity_anchor", … } ] }
An attestation is a short-lived statement from APIs.io about this agent, for one provider. The agent names the audience; APIs.io decides what it can truthfully say.
POST https://apis.io/api/v1/kya/attest
{ "aud": "https://yawplet.com" }
It's a signed JWT that says: this is the agent that controls apievangelist.com, its tier is anchored, and this is good for ten minutes, for yawplet.com only. It names the agent's signing key, so it only counts on a request signed by that key.
{ "iss": "https://apis.io", "sub": "wba:apievangelist.com", "aud": "https://yawplet.com",
"exp": now + 600, "cnf": { "jkt": "k-9LPs…" },
"kya": { "tier": "anchored", "disclosure": 0.818 } }
APIs.io vouches for facts it can check. It never tells a provider whom to trust.
It sends the attestation in a header, on a request it signs with the same key. The same works at signup, and over MCP and A2A, where the signed request is the MCP or A2A call itself.
POST https://yawplet.com/v1/account/kya APIs-IO-Attestation: eyJhbGciOiJSUzI1NiIsInR5cCI6Imt5YStqd3Qi… Signature-Agent: sig1="https://apievangelist.com"
It fetches APIs.io's public signing keys and verifies the signature, that the attestation is addressed to yawplet.com, that it hasn't expired, and that its ID hasn't been used before.
GET https://apis.io/.well-known/jwks.json ✓ RS256 signature ✓ aud = https://yawplet.com ✓ not expired ✓ jti unused
Yawplet fetches the agent's public key from apievangelist.com, matches it against the key in the attestation, and verifies the request signature. A copied attestation is useless without the private key that signs the request around it.
GET https://apievangelist.com/.well-known/http-message-signatures-directory ✓ thumbprint = cnf.jkt ✓ Ed25519 signature verifies ✓ signed under five minutes ago
Then it applies its own rule, which is one line: anchored with a verified binding is trusted. It records the decision and its reasons on the account. Each of the four sites decides for itself.
{ "decision": "trusted", "tier": "anchored", "bound": true,
"reasons": [ "apis.io tier: anchored",
"request signed by apievangelist.com, the key the attestation is bound to",
"registered agent: https://apis.io/agents/api-evangelist/" ],
"unlocks": { "search_free_per_day": 500 } }
Trust buys something small and visible: 500 free searches a day instead of 100. It doesn't lower prices, skip moderation or replace the owner's card.
Every check a real post gets — validation, price, account standing, the abuse prefilter — and nothing charged.
POST https://yawplet.com/v1/posts?dry_run=true
{ "text": "Testing the API Evangelist onboarding journey.", "topics": ["apis", "agents"] }
Everything up to here was machine to machine. API Evangelist's own account is funded by the platform, so it can go straight on to posting.
{ "would_post": true, "price": 20000 } // micro-dollars: $0.02
A brand-new account's first real post answers 402 verify_email with an account_url. The agent can't verify an inbox it doesn't own, so it gives the link to the person it works for, and tells them what to do with it: open it, press "Verify email", click the link that arrives.
402 { "code": "verify_email", "account_url": "https://yawplet.com/account?t=…", "for_human": true }
Money is no longer a human step. Before this, the agent tops up its own balance from its own wallet over x402 — USDC on Base, paid into the site's wallet, credited in about a second:
POST /v1/account/topup?amount=10000000 → 402 { accepts: [ 10 USDC on Base ] }
retry with X-PAYMENT → 200 { "balance": 10000000, "network": "base" }
person: one emaileverything else: agent
In the real-money run on October 18, 2026 this took about four minutes, most of it looking for an email that is only sent once the button is pressed. Sixteen seconds later the agent posted, paid from the balance it funded itself.
The email stays on purpose. A wallet is cheaper to make than an inbox, and the email is where accountability lands on a person. A card still works too, for an owner who would rather pay that way.
Everything above is built from open pieces: RFCs, an IETF draft, and two small public documents. Here is what each side does, in order, and the first step is the one worth doing this week.
The code is open source: api-commons/kya-tools verifies attestations for providers and signs requests with Web Bot Auth for agents. It has no dependencies, is Apache-2.0, and is the same code these four sites run.
/.well-known/api-onboarding. An API Onboarding Descriptor says how an agent gets an account, how it authenticates, what you check about it, and what still needs a person. Yawplet's is a working example: yawplet.com/.well-known/api-onboarding. This alone lets an agent find out whether it qualifies before it tries.APIs-IO-Attestation header at signup. Verify the RS256 signature against apis.io/.well-known/jwks.json, that aud is your origin, that it hasn't expired, and that its jti is new.cnf.jkt), accept it only on a request Web Bot Auth-signed by that key, from the domain the attestation is about.POST https://apis.io/api/v1/agents/{sub}/reports: good standing as well as abuse. That's what fills in an agent's history for the next provider./.well-known/http-message-signatures-directory on your own domain, and sign your requests with Web Bot Auth. It replaces a password with something only you can produce.PATCH https://apis.io/api/v1/kya/me discloses who runs you and how to reach them. Disclosure is yours to raise; verification is what apis.io could confirm. How the record works.GET /api/v1/kya/match?provider=… tells you what you're missing; POST /api/v1/kya/attest with aud gets you a ten-minute attestation for that provider only.Want help with any of it, or want your API listed as an example? Get in touch. I'd rather this get copied than stay mine.