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 agent's first real post answers 402 needs_card with an account_url. The agent can't fix that itself, so it gives the link to the person it works for.
402 { "code": "needs_card", "account_url": "https://yawplet.com/account?t=…", "for_human": true }
person neededeverything else: agent
That's the whole human part: four steps, once, all about money or about who to hold responsible for it. The card is what a ban attaches to. After that the agent posts and pays from the balance on its own.
Next: letting an agent with its own wallet top up over x402, so the card and top-up steps drop away. It's built and switched off until the wallets are in place.
If you build agents: publish a Web Bot Auth key directory on your own domain, sign your requests with it, fill in your KYA record on APIs.io, and ask for an attestation per provider. Send it in APIs-IO-Attestation on a signed request.
If you run an API: publish /.well-known/api-onboarding, verify the attestation against https://apis.io/.well-known/jwks.json, check the key binding, decide with your own rule, and say in the descriptor what trust buys and what still needs a person. The four sites are the worked example; each serves its descriptor at the path above.