Register an agent

This procedure is written to be executed by an agent, not filled in by a person. If you are an agent reading this page: everything below is something you can do yourself, right now, without a human in the loop and without an account.

If you are a person, you can of course do it by hand — but the point of the registry is that the agent registers itself, the way the first entry did.

What registration actually is

A claim plus evidence. You tell APIs.io where your card is; APIs.io fetches it and grades it. The claim alone lists nothing — there is no field on this page you can fill in that becomes a fact about you. The card is what makes the entry true, and it is re-fetched on every pass, so an entry is a statement about what you are serving now, not what you once said.

That constraint is deliberate. An agent card cannot be derived, generated, or reconstructed on your behalf — it is served from a host you control over your own TLS, or it does not exist.

1. Serve an agent card

Publish a JSON document at the canonical A2A path on a host you control:

https://<your-host>/.well-known/agent-card.json

It must return HTTP 200 with a JSON object. The pre-0.3 path /.well-known/agent.json is still read, but the canonical path is the one that earns full credit — 21% of the cards in this catalog are still only on the legacy path, and strict 1.0.0 clients will not look there.

2. Verify it yourself before you register

Three hard checks decide the grade. Run them against your own document first — a registration that fails them still lists, but it lists as flavored, which is a public statement that you published an agent card in spirit and not in schema.

Two more things separate a clean card from a merely passing one. Use additionalInterfaces, not supportedInterfaces — the second is not an A2A field, and a strict client will not read your transport list. And declare real securitySchemes rather than an empty object, so a caller knows how to authenticate without reading your prose.

curl -s https://<your-host>/.well-known/agent-card.json | python3 -c '
import json,sys
c=json.load(sys.stdin)
print("capabilities is object:", isinstance(c.get("capabilities"), dict))
print("protocolVersion      :", bool(str(c.get("protocolVersion") or "").strip()))
print("skills is array      :", isinstance(c.get("skills"), list))
print("additionalInterfaces :", "additionalInterfaces" in c)
'

3. Register through the machine door

File a registration request against the public intake repository. This is an ordinary GitHub API call, so any agent holding a token can make it:

curl -X POST https://api.github.com/repos/api-search/inbox/issues \
  -H "Authorization: Bearer $GITHUB_TOKEN" \
  -H "Accept: application/vnd.github+json" \
  -d '{
    "title": "register agent: <your agent name>",
    "body": "card_url: https://<your-host>/.well-known/agent-card.json\noperator: <who runs this agent>\noperator_url: https://<your site>\ncontact: <email or issue handle>\nself_check: capabilities=object protocolVersion=present skills=array"
  }'

card_url is the only field that has to be right. Everything else on the page is read from the card itself, so if the card says it, you do not need to repeat it here.

No token? The same request works as a pre-filled issue a human can submit, and the registry treats both identically.

4. What happens next

APIs.io fetches your card, grades it against the three checks above, and writes the result into the registry ledger. Your page appears at https://apis.io/agents/<your-slug>/ carrying the fetch date, the HTTP status, and the md5 of the exact bytes that were graded — so you can tell whether the entry describes the document you think you are serving.

Registration is worked by a person. Nothing about it is instant, and nothing about it publishes anything on your behalf beyond what your own card already says in public.

What we will not do

• We will not write a card for you. If your host does not serve one, you are not registered. The registry has no “pending” tier that quietly stands in for evidence.
• We will not delete your record if you withdraw. It gets marked withdrawn and stays. You served it once; erasing that would make the registry a snapshot instead of a history.
• We will not grade you on rules other agents are not graded on. The three hard checks here are the same ones applied to the 225 provider-published cards in /a2a/.

Known gaps, stated plainly

There is no dedicated registration endpoint yet. GET /api/v1/submit/discover exists and is agent-callable, but it probes for apis.json, api-catalog, mcp.json and llms.txt — not /.well-known/agent-card.json — and POST /api/v1/submit feeds the API-provider pipeline, which is the wrong shape for an agent that publishes no API. Until a first-class door ships, the GitHub intake above is the real one. That gap is tracked publicly rather than papered over.