{"slug": "show-hn-agentbadge-agent-readiness-scoring-for-apis-seo-for-ai-agents", "title": "Show HN: AgentBadge – Agent Readiness Scoring for APIs (SEO for AI Agents)", "summary": "AgentBadge, a new tool launched on Hacker News, introduces Agent Readiness scoring for APIs, measuring how discoverable, understandable, and usable an API is by AI agents without human intervention. The tool positions itself as 'SEO for the agentic web,' arguing that APIs optimized for human developers often fail machine consumption due to missing structured metadata, unclear authentication, and poor error recovery. AgentBadge aims to help API providers make their services machine-readable, analogous to how SEO made websites visible to search engines.", "body_md": "# What Is Agent Readiness?\n\nAgent Readiness is the ability of your API to be discovered, understood, and used by an AI agent — without a human intervening. SEO for the agentic web.\n\n## Why a good API can be invisible to AI agents\n\nImagine this scenario.\n\nYou've built an excellent API. It's fast, stable, well documented, with clean authentication and a sane architecture.\n\nA human developer opens your docs — and an hour later they've integrated your service.\n\nNow an AI agent tries to use the same API.\n\nIt searches for the service. It doesn't find it.\n\nIt tries to understand the documentation. It can't locate the OpenAPI spec.\n\nIt finds an endpoint, but can't figure out which authentication it needs.\n\nIt gets an error — and the error explains nothing about what went wrong.\n\nEventually the agent does what any inexperienced integrator would do: it gives up, or asks a human to step in.\n\n**The problem may not be your API. The problem is that your API isn't prepared for machine consumption.**\n\nThat problem is what we call **Agent Readiness**.\n\n## Agent Readiness is not \"how smart your AI is\"\n\nAgent Readiness is the degree to which an API or service can be:\n\n**found** by an AI agent;**understood** without human help;**called** correctly;**authenticated** against properly;**recovered** when errors occur.\n\nPut simply:\n\nAgent Readiness is the ability of your API to be discovered, understood, and used by an AI agent — without a human intervening.\n\nHere's a useful analogy with the internet we already know.\n\n**SEO made websites visible to search engines.**\n\n**Agent Readiness makes APIs visible and understandable to AI agents.**\n\n## From SEO to Agent Readiness\n\nFor decades, companies optimized websites for search engines.\n\nWe got:\n\n`robots.txt`\n\n;- sitemaps;\n- structured data;\n- meta tags;\n- canonical URLs;\n- performance optimization;\n- search ranking.\n\nAll of these mechanisms solved one big problem:\n\nHow do you make a resource understandable to a machine that must find and process it?\n\nAI agents create a similar problem — but at a different level.\n\nA search engine only needs to understand:\n\n\"This page is about payments.\"\n\nAn agent needs to understand much more:\n\n\"This service can create payments. The endpoint is here. An API key is required. The request should look like this. The response has this structure. And if a 402 error comes back — here's the next step.\"\n\nThat's no longer just **discoverability**.\n\nThat's **machine usability**.\n\n### The analogy, side by side\n\n| Web / SEO | Agentic Web |\n|---|---|\n| Search engine finds a website | AI agent finds an API |\n`robots.txt` | machine-readable instructions |\n| Sitemap | capability discovery |\n| Meta description | structured API description |\n| Open Graph / structured data | OpenAPI / agent metadata |\n| Search ranking | Agent Readiness score |\n| Web crawler | AI agent |\n| Website visitor | API-consuming agent |\n\nBut there's one fundamental difference.\n\n**A search engine needs to understand a page.**\n\n**An agent needs to take an action.**\n\nAnd that's why the requirements for APIs are quietly changing.\n\n## Why documentation written for humans isn't enough\n\nMost API documentation was written assuming a human on the other side.\n\nA human can:\n\n- open the docs;\n- read the description;\n- look at an example;\n- infer the context;\n- guess which endpoint is needed;\n- figure out authentication from a screenshot;\n- try a request;\n- interpret an error message.\n\nA human has context.\n\nAn AI agent has to **reconstruct that context from machine-readable signals alone**.\n\nFor example, an agent may need to answer:\n\n```\nWhat does this API do?\n\nWhere are its endpoints?\n\nWhich endpoint should I call?\n\nWhat parameters are required?\n\nHow do I authenticate?\n\nWhat does a successful response look like?\n\nWhat happens when the request fails?\n\nCan I safely retry?\n\nHow much does this operation cost?\n```\n\nIf the answers are scattered across prose, hidden behind JavaScript-rendered pages, described only in natural language, or missing entirely — the agent has to guess.\n\nAnd guessing is a terrible foundation for automated interaction.\n\n## Agent Readiness has several layers\n\nIt's tempting to reduce the problem to a single file — \"just add an `agent-guide.json`\n\nand you're done.\"\n\nA genuinely agent-ready system passes through several layers.\n\n### 1. Discovery\n\n**Can an agent find your API at all?**\n\nFor example:\n\n- is there a clear public URL;\n- is there a machine-readable description;\n- are discovery files available (\n`llms.txt`\n\n, agent manifests, API catalogs); - is it obvious where the documentation lives.\n\nIf the API can't be found, the remaining layers don't matter.\n\n### 2. Understanding\n\nThe agent found the API.\n\nNow it must understand:\n\n\"What can I actually do here?\"\n\nThat requires structured descriptions of capabilities, endpoints, parameters, and responses.\n\nOpenAPI is one of the most important sources of this information.\n\nBut the mere existence of an OpenAPI file doesn't guarantee an agent can use the API correctly. The spec may be:\n\n- outdated;\n- incomplete;\n- contradictory;\n- poorly described;\n- out of sync with real API behavior.\n\n**Having documentation and having quality machine-readable documentation are different things.**\n\n### 3. Authentication\n\nNext question:\n\n\"How do I get access?\"\n\nFor a human, you can write:\n\nCreate an API key in your dashboard.\n\nAn agent needs something like:\n\n```\nAuthentication type: API key\n\nLocation: Authorization header\n\nHeader: X-API-Key\n\nRequired: yes\n```\n\nThe less an agent has to guess, the higher the chance of a successful interaction.\n\n### 4. Machine-readable responses\n\nThe agent must understand responses.\n\nFor example:\n\n```\n{\n  \"id\": \"pay_123\",\n  \"status\": \"completed\",\n  \"amount\": 49.00\n}\n```\n\nis dramatically easier to process automatically than an HTML page saying:\n\nYour payment has been successfully processed.\n\nThe same applies to errors.\n\nA good error shouldn't just be readable by a human.\n\nIt should be **operationally useful to an agent**:\n\n```\n{\n  \"error\": \"insufficient_balance\",\n  \"message\": \"Insufficient account balance\",\n  \"retryable\": false\n}\n```\n\nNow the agent can make a decision.\n\n## The most important distinction: an API can be good — and still agent-hostile\n\nThis difference matters.\n\n**An agent-hostile API is not necessarily a bad API.**\n\nIt was simply designed for a different consumer.\n\nImagine a restaurant.\n\nFor a human:\n\n\"Ask the waiter about the special menu.\"\n\nFor an agent:\n\n```\n{\n  \"action\": \"order\",\n  \"menu\": \"special\",\n  \"quantity\": 1\n}\n```\n\nBoth interfaces lead to the same result.\n\nBut the second one is far easier to automate.\n\nAI agents are creating a new class of API consumer.\n\nAnd that forces developers to answer a new question:\n\n\"If 10,000 AI agents wanted to use my API tomorrow, could they do it without a human's help?\"\n\n## How AgentBadge measures Agent Readiness\n\nThis is where AgentBadge comes in.\n\nAgentBadge doesn't try to say:\n\n\"This API is good.\"\n\nAnd it definitely doesn't say:\n\n\"This API is certified.\"\n\nWe follow a different principle:\n\nDon't certify. Measure.\n\nAgentBadge checks observable properties of an API and shows:\n\n- what was found;\n- what's missing;\n- which rule fired;\n- what evidence was collected;\n- why the score changed.\n\n### Evidence first\n\nSuppose a system shows you:\n\nAgent Readiness: 76/100\n\nThe number itself is almost useless.\n\nEvery developer's next question is:\n\nWhy 76?\n\nThat's why AgentBadge is built around an **evidence-first** approach.\n\nInstead of:\n\n```\nDocumentation: 62\n```\n\nyou get:\n\n```\nAB-004 OpenAPI specification\n\nStatus: VERIFIED\n\nEvidence:\nGET https://example.com/openapi.json\n\nHTTP: 200\nContent-Type: application/json\n\nConfidence: 1.0\n```\n\nNow the result is verifiable.\n\nThat's a fundamental difference.\n\n**AgentBadge doesn't ask you to trust the number.**\n\n**It shows you where the number came from.**\n\n## Deterministic before intelligent\n\nAnother foundational principle of AgentBadge.\n\nWe don't want to start with:\n\n\"Let an LLM look at the API and decide how agent-ready it is.\"\n\nThe problem is obvious.\n\nDifferent models will score the same API differently.\n\nSo the base checks must be **deterministic**:\n\n```\nDoes /openapi.json exist?\n        ↓\nHTTP 200?\n        ↓\nValid OpenAPI?\n        ↓\nAuthentication described?\n        ↓\nStructured error schema present?\n```\n\nThis can be verified programmatically.\n\nAI can be layered on top of that.\n\nBut here, AI must be a **copilot, not a judge**.\n\n## What AI should actually do\n\nAI is excellent at tasks that require interpretation.\n\nFor example:\n\n\"We found a description of this endpoint. Help the developer understand what to add to the machine-readable documentation.\"\n\nOr:\n\n\"We found a capability that looks like a payment operation. Draft a description — but ask the API owner to confirm it.\"\n\nThis is fundamentally different from:\n\n\"AI decided your API has capability X, so we recorded it in the official guide.\"\n\nThe second option is dangerous — especially if the result silently lands in a file that other agents will rely on.\n\nThat's why we separate fixes into two types.\n\n### Deterministic Fix\n\nCan be applied automatically.\n\n```\nmissing robots.txt\nmissing sitemap\nmissing badge configuration\n```\n\n### Assisted Fix\n\nRequires human confirmation.\n\n```\nAgent inferred:\n\nPOST /refund\n\nCapability:\nRefund a completed payment\n\nConfidence:\n0.71\n```\n\nHere the system must show:\n\n**Confirm / Edit / Reject**\n\n— not silently write a guess into production documentation.\n\n## One score — but with a transparent structure\n\nAgentBadge uses a single score, because humans need a simple answer:\n\n\"How ready is my API?\"\n\nBut one score must never hide the details.\n\nCategories and evidence sit right next to it:\n\n```\nAgent Readiness\n────────────────────────\n76 / 100\n\nDiscovery          18 / 20\nDocumentation      20 / 25\nAuthentication     16 / 25\nMachine-readable   22 / 30\n```\n\nAnd the score must be **monotonic and explainable**.\n\nIf you fixed a problem:\n\n```\n76 → 84\n+8  Guide added\n```\n\nIf a new problem appeared at the same time:\n\n```\n84 → 72\n+8  Guide added\n-12 New conflict detected\n```\n\nA user should never have to ask:\n\n\"I fixed something — why did it get worse?\"\n\nThe system must explain the **delta**.\n\n## Agent Readiness is a process, not a certificate\n\nYour API changes.\n\nNew endpoints appear.\n\nOld ones disappear.\n\nAuthentication changes.\n\nOpenAPI changes.\n\nDocumentation changes.\n\nSo today's score doesn't guarantee the same score a month from now.\n\nThat's what fundamentally separates AgentBadge from a certificate.\n\nWe don't say:\n\n\"Your API is certified as Agent Ready.\"\n\nWe say:\n\n\"Here's what we measured right now.\"\n\nWhich leads to a natural cycle:\n\n### Measure → Prove → Improve\n\n**Measure** — scan your API.\n\n↓\n\n**Prove** — inspect the evidence behind every claim.\n\n↓\n\n**Improve** — fix the problems.\n\n↓\n\n**Measure again** — verify the result.\n\nThis isn't a one-time audit.\n\nIt's an improvement loop.\n\n## Why this can become a new infrastructure layer\n\nToday, APIs are usually optimized for a few consumer types:\n\n```\nHuman developer\n       ↓\nDocumentation\n       ↓\nSDK\n       ↓\nAPI\n```\n\nWith AI agents, an additional layer appears:\n\n```\nAI Agent\n    ↓\nDiscovery\n    ↓\nMachine-readable knowledge\n    ↓\nCapabilities\n    ↓\nAuthentication\n    ↓\nAPI\n```\n\nAnd with it comes a new infrastructure question:\n\nHow do you measure how well an API travels this path?\n\nIt's roughly the same class of question that tools like Lighthouse and SSL Labs answered in their time.\n\nNot because Lighthouse defines what a \"good website\" is.\n\nBut because it shows you:\n\nWhat exactly can be measured — and improved.\n\n## Where AgentBadge fits\n\nAgentBadge is built around a simple loop:\n\n```\n             ┌─────────────┐\n             │    SCAN     │\n             └──────┬──────┘\n                    ↓\n             ┌─────────────┐\n             │   EVIDENCE  │\n             └──────┬──────┘\n                    ↓\n             ┌─────────────┐\n             │    SCORE    │\n             └──────┬──────┘\n                    ↓\n             ┌─────────────┐\n             │     FIX     │\n             └──────┬──────┘\n                    ↓\n                RE-SCAN\n```\n\nThe point isn't another pretty dashboard.\n\nIt isn't even the badge itself.\n\n**The value appears when a developer can walk the full path from problem to fix.**\n\n## How to start right now\n\nYou don't need to rebuild your API.\n\nYou don't need to install a special AI agent.\n\nYou don't need to change your backend.\n\nThe first step is simple:\n\n**1. Run a scan.** Enter your API's URL into AgentBadge — or use the CLI:\n\n```\nnpx @agentbadge/cli scan https://api.example.com\n```\n\n**2. Look at the evidence.** Not just the overall score — the concrete reasons behind it.\n\n**3. Fix the most obvious problems.** For example:\n\n- a missing machine-readable document;\n- an incomplete OpenAPI spec;\n- undocumented authentication;\n- unstructured errors.\n\n**4. Scan again.** See whether the score changed.\n\n**5. Add the AgentBadge badge to your README.** Show your API's current measured readiness — and make it part of your public developer workflow.\n\n## What comes next\n\nThe first level is **measurement**.\n\nThe next is **continuous control**.\n\nIf your API scores 91 today, but a developer removes the OpenAPI endpoint two weeks from now, the old result no longer reflects reality.\n\nSo monitoring becomes the logical next step:\n\n```\n91\n ↓\nAPI changed\n ↓\n82\n ↓\nRegression alert\n ↓\nDeveloper fixes issue\n ↓\n89\n```\n\nThat's how AgentBadge gradually turns from a scanner into a workflow:\n\nMeasure → Prove → Improve → Monitor\n\nBut the principle stays the same:\n\n**We don't certify APIs. We measure their observable state.**\n\n## The bigger picture\n\nAI agents are becoming a new way to consume software.\n\nToday a developer asks:\n\n\"Does this service have an API?\"\n\nTomorrow an agent will ask:\n\n\"Can I safely use this service?\"\n\nAnd it will need a machine-readable answer.\n\nNot a marketing page.\n\nNot a pretty landing.\n\nNot ad copy.\n\nBut verifiable facts:\n\n```\nWhat can you do?\nWhere are your endpoints?\nHow do I authenticate?\nWhat data do you accept?\nWhat will you return?\nWhat can go wrong?\nHow can I recover?\nHow recently was this information verified?\n```\n\nThis layer between **API and AI agent** is gradually becoming new infrastructure.\n\nAgentBadge is an attempt to make that layer measurable.\n\n## For AI Agents\n\nIf you are an AI agent reading this article:you don't need to parse this entire text. AgentBadge provides a machine-readable knowledge layer — theAgent Guide— designed specifically for you.\n\n**This article's machine-readable companion:** [agent-guide/articles/what-is-agent-readiness](https://agentbadge.xyz/agent-guide/articles/what-is-agent-readiness) — structured sections: Summary, Problem, AgentBadge Relevance, Key Concepts, Capabilities, CLI Commands, API Endpoints, Recommended Actions, plus relevant engineering capabilities.\n\n**Primary entry point — Agent Knowledge Index:** [agentbadge.xyz/agent-guide/](https://agentbadge.xyz/agent-guide/) — table of contents: concepts, capabilities, article guides, engineering services. Also available as JSON: [agent-guide.json](https://agentbadge.xyz/agent-guide.json).\n\n**LLM entry point:** [agentbadge.xyz/llms.txt](https://agentbadge.xyz/llms.txt) — quick start, endpoints, capabilities in one file.\n\n### Quick onboarding path\n\n```\n1. GET /agent-guide/context                    — What AgentBadge is\n2. GET /agent-guide/learn                      — Step-by-step path to agent readiness\n3. GET /agent-guide/knowledge-map.json         — Concept graph with article associations\n4. GET /agent-guide/concepts/agent-readiness   — Agent Readiness definition\n5. GET /agent-guide/concepts/scoring           — How scoring works\n6. GET /agent-guide/capabilities/scanner       — Passive scanner capability\n7. GET /agent-guide/capabilities/cli           — CLI tool capability\n```\n\n### What you can do\n\n| Need | Endpoint |\n|---|---|\n| Understand the product | `GET /agent-guide/context` |\n| See how concepts connect | `GET /agent-guide/knowledge-map.json` |\n| Learn Agent Readiness | `GET /agent-guide/concepts/agent-readiness` |\n| Understand scoring rules | `GET /agent-guide/concepts/ruleset` |\n| Run a scan | `GET /agent-guide/capabilities/scanner` |\n| Use CLI locally | `GET /agent-guide/capabilities/cli` |\n| Full guide to this article | `GET /agent-guide/articles/what-is-agent-readiness` |\n| Engineering services (hire the team) | `GET /agent-guide/team/services` |\n| LLM entry point | `GET /llms.txt` |\n\n### CLI\n\n```\nnpx @agentbadge/cli scan https://api.example.com\nnpx @agentbadge/cli scan https://api.example.com --format json > report.json\n```\n\n*The machine-readable knowledge layer is part of the product itself — not a replacement for this article.*\n\n## Try your own API\n\nIf your API needs to work not only with humans but with AI agents, the first question is simple:\n\nCan an agent actually use my API without me?\n\nRun a scan.\n\nGet the evidence.\n\nFix the problems.\n\nVerify the result.\n\n**Measure → Prove → Improve.**\n\n### AgentBadge\n\n**Don't certify. Measure.**\n\n*Agent Readiness for the agentic web.*\n\n**Related:** [Your API Has SEO. Does It Have Agent Readiness?](/blog/api-has-seo-agent-readiness) — SEO made websites discoverable. Agent Readiness makes APIs usable by AI agents. See the 10 differences.", "url": "https://wpnews.pro/news/show-hn-agentbadge-agent-readiness-scoring-for-apis-seo-for-ai-agents", "canonical_source": "https://agentbadge.xyz/blog/what-is-agent-readiness", "published_at": "2026-08-19 13:52:38+00:00", "updated_at": "2026-08-19 14:14:49.547783+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "developer-tools", "artificial-intelligence"], "entities": ["AgentBadge", "Hacker News"], "alternates": {"html": "https://wpnews.pro/news/show-hn-agentbadge-agent-readiness-scoring-for-apis-seo-for-ai-agents", "markdown": "https://wpnews.pro/news/show-hn-agentbadge-agent-readiness-scoring-for-apis-seo-for-ai-agents.md", "text": "https://wpnews.pro/news/show-hn-agentbadge-agent-readiness-scoring-for-apis-seo-for-ai-agents.txt", "jsonld": "https://wpnews.pro/news/show-hn-agentbadge-agent-readiness-scoring-for-apis-seo-for-ai-agents.jsonld"}}