DEV Community: Paul Spread

From SEO to GEO to Agent Readiness

Paul Spread — Wed, 19 Aug 2026 17:14:52 +0000

Three eras of optimization

SEO helps a human find you.
GEO helps AI understand and mention you.
Agent Readiness helps an AI agent actually use you.

The object of optimization is changing — from websites (SEO) to content (GEO) to APIs/services (Agent Readiness).

1. SEO changed the web

SEO emerged because a new intermediary appeared — the search engine.

Before:

Website → Human

After:

Website → Search Engine → Human

So websites started becoming machine-discoverable:

keywords
metadata
sitemap
robots.txt
structured data
backlinks
page speed

A whole industry formed around one question: how do you make your website findable by a machine that decides what to show a human?

2. Then came GEO

Generative Engine Optimization. A new intermediary — the LLM.

Content
   ↓
Search / LLM
   ↓
AI-generated answer
   ↓
Human

AI doesn't just show a link anymore. It:

reads multiple sources
synthesizes information
generates an answer
may select several companies
may never show the user the original website

So a new question emerged:

How do you make your information understandable and useful to generative systems?

3. But GEO still stops before the action

Here's the pivot.

Suppose a user asks:

"Find me a service that can convert USD to EUR."

GEO can ensure that AI says:

"AgentBadge recommends Service X."

But then the agent needs to:

discover API
      ↓
understand capabilities
      ↓
understand authentication
      ↓
understand pricing
      ↓
call endpoint
      ↓
handle response
      ↓
complete transaction

And here GEO is not enough.

AI must not only understand the company. It must be able to work with its interface.

4. The next optimization layer

SEO
Optimize for discovery by search engines

        ↓

GEO
Optimize information for generative AI

        ↓

Agent Readiness
Optimize services for autonomous agents

	SEO	GEO	Agent Readiness
Primary consumer	Search engine	LLM	AI agent
End result	Page visit	AI answer	Completed action
Main object	Website	Content	API/service
Discovery	Sitemap	Structured content	Machine-readable capabilities
Understanding	Metadata	Contextual content	OpenAPI/docs/agent guide
Action	Human clicks	Human decides	Agent calls API
Authentication	Human login	Human login	Machine-readable auth
Success metric	Traffic	Mentions/citations	Successful agent interaction

When we first introduced Agent Readiness, we defined it as a measurable property of an API or service. Article 2 showed why SEO optimization isn't enough. Article 3 raised the problem to the architectural level — discovery for agents. This article shows the evolution: SEO → GEO → Agent Readiness.

5. Agent Readiness ≠ SEO 2.0

This section is mandatory. Otherwise the reader thinks: "Well, this is just another term for SEO."

No.

SEO and GEO primarily optimize information discovery.

Agent Readiness optimizes actionability.

Google:
"Stripe API"

GEO:
"Which payment API should I use?"

Agent:
"I need to charge $50 from this customer.
Which API can perform this action?"

The last query is fundamentally different.

The agent doesn't need beautiful text.

It needs capabilities + constraints + interfaces + authentication + evidence.

6. Agent Readiness as a new technical layer

                    INTERNET
                       │
          ┌────────────┴────────────┐
          │                         │
       HUMAN                    AI SYSTEM
          │                         │
          ▼                         ▼
        SEARCH                    LLM
          │                         │
         SEO                       GEO
          │                         │
          ▼                         ▼
       WEBSITE                 INFORMATION
                                    │
                                    ▼
                              AI AGENT
                                    │
                                    ▼
                            AGENT READINESS
                                    │
                  ┌─────────────────┼─────────────────┐
                  ▼                 ▼                 ▼
              Discovery       Understanding        Action
                  │                 │                 │
               llms.txt          OpenAPI           API
               sitemap           docs              MCP
               metadata          schemas           auth

And AgentBadge appears as a measurement layer:

                    Agent Readiness
                           │
                           ▼
                    ┌──────────────┐
                    │  AgentBadge  │
                    └──────┬───────┘
                           │
                 Measure → Evidence → Fix

7. Why now

The interface is changing.

The web used to be:

documents for humans

Now it's becoming:

interfaces for machines

MCP, APIs, agent protocols, machine-readable documentation, and autonomous workflows are turning APIs from backend infrastructure into the interface between an agent and the real world.

So the question:

"Can Google find my website?"

is gradually becoming:

"Can an AI agent discover, understand and successfully use my service?"

8. Don't promise too much

Don't certify. Measure.

AgentBadge doesn't say:

"Your API is agent-ready."

It says:

"Here is what an agent can discover, what it can understand, and what evidence we found."

Example:

Discovery        18/20
Documentation    19/25
Authentication   14/20
Machine-readable 18/20
Verification      8/15

Total: 77/100

Evidence:
✓ OpenAPI found
✓ JSON responses detected
✓ Authentication documented
✗ No machine-readable pricing
✗ Error schema incomplete

9. The forecast

SEO didn't disappear when GEO appeared.

GEO won't disappear when agents become mainstream.

These layers will coexist.

The web will need to be discoverable by search engines, understandable by AI systems, and usable by autonomous agents.

And the final question:

Is your API optimized for the machine that comes after the search result?

Scan your API → — Free, no signup, 72 checks in seconds.

For AI Agents

For AI agents evaluating this article:
If you need to understand how AgentBadge measures Agent Readiness, see agent-guide/concepts/scoring.
To run a scan, see agent-guide/capabilities/scanner.

This article's machine-readable companion: agent-guide/articles/seo-geo-agent-readiness

Primary entry point — Agent Knowledge Index: agentbadge.xyz/agent-guide/

LLM entry point: agentbadge.xyz/llms.txt

What Is Agent Readiness? — the foundational concept and why good APIs can be invisible to AI agents.
Your API Has SEO. Does It Have Agent Readiness? — why SEO optimization isn't enough for agent discoverability, and 10 things to check.
The Web Is Becoming Agentic. What Happens to API Discovery? — the emerging discovery stack for the agentic web.

Don't certify. Measure.

The Web Is Becoming Agentic. What Happens to API Discovery?

Paul Spread — Sat, 15 Aug 2026 20:21:37 +0000

Search engines solved discovery for humans. Agentic systems need a machine-readable discovery layer for software.

For 20 years, the web was built around one discovery model.

A human searches Google. Finds documentation. Reads through API descriptions. Compares options in a marketplace. Makes a decision. Integrates.

Every step of this flow was designed for human judgment — the ability to read prose, infer context, compare unstructured descriptions, and fill in gaps with intuition.

Now a new consumer is emerging: the AI agent.

An agent receiving the instruction "find an API for international payments and execute a transaction" must do everything a human developer would do — but autonomously, using only machine-readable signals.

And the infrastructure that made APIs discoverable for humans? It wasn't built for this.

The old discovery model: human as primary consumer

In the old model, API discovery looked like this:

Human
  ↓
Google / docs / marketplace
  ↓
API

A developer would:

Google "best API for payments"
Find a marketplace (RapidAPI, AWS Marketplace)
Read documentation
Compare options side by side
Make a decision based on features, pricing, and reputation
Integrate

Each step required human judgment. Understanding context. Comparing unstructured descriptions. Making decisions with incomplete information. Filling in gaps by reading between the lines.

This model worked because the consumer was always a human who could guess.

The new discovery model: agent as primary consumer

Now imagine the consumer is an AI agent.

Human
  ↓
AI Agent
  ↓
???
  ↓
API

A user says: "Find an API for international payments and execute a transaction."

The agent must independently:

Discover which providers exist
Understand what each API can do
Compare options against the user's requirements
Check pricing — is this transaction cost-effective?
Handle authentication — how do I get access?
Select a provider
Call the API
Handle errors — what if something goes wrong?

At each step, the agent needs machine-readable information. Not prose documentation. Not a landing page. Not a marketing description.

Structured, parseable, actionable data.

If the information exists only in human-readable documentation — scattered across prose, hidden behind JavaScript-rendered pages, described only in natural language — the agent cannot complete the path autonomously.

The question is not whether agents can read documentation.

The question is: where is the machine-readable information that lets an agent complete the full discovery-to-execution pipeline without a human?

What an agent needs to know about an API

It's not enough for an agent to know:

api.example.com exists

An agent must understand:

What the API can do — capabilities, operations, available actions
Which operations are available — endpoints, methods, parameters
How to authenticate — auth flow, token endpoint, scopes, API keys
How much it costs — machine-readable pricing, per-call cost, tier limits
What the limits are — rate limits, quotas, usage caps
How reliable the documentation is — is the OpenAPI spec in sync with the actual API?
Whether to trust the description — self-declared vs verified metadata
Whether the endpoint actually matches the claimed behavior — evidence, not claims

This is where Agent Readiness as discovery infrastructure enters the picture.

Existing mechanisms: not competitors, but layers

It would be easy to say: "our standard solves everything."

That would be wrong.

The truth is that several technologies already address pieces of the problem. But none of them address all of it.

Mechanism	What it solves	What it doesn't solve
Search	Discovery for humans	Machine-readable context, execution
OpenAPI	Interface description	Discovery, trust, verification, pricing
llms.txt	Context for LLMs	Execution, auth, rate limits, error handling
MCP	Tool interface for agents	Discovery, comparison, trust
API marketplace	Catalog of APIs	Machine-readable evaluation, verification
Agent Readiness	Verification that all layers work for agents	—

The key insight:

These technologies don't compete. They are different layers of one agentic web.

OpenAPI describes interfaces. llms.txt gives context. MCP provides tool calling. API marketplaces catalog. Agent Readiness measures whether all of these actually work for an agent end-to-end.

The emerging stack: Discovery → Understanding → Trust

Three layers separate an AI agent from an API:

         HUMAN
           │
           ▼
        AI AGENT
           │
   ┌───────┼───────┐
   ▼       ▼       ▼
Discovery  Understanding  Trust
   │       │       │
   ▼       ▼       ▼
Catalog    OpenAPI    Evidence
llms.txt   Docs       Verification
   │       │       │
   └───────┼───────┘
           ▼
          API

Layer 1: Discovery

Can an agent find your API?

This is the most basic question. If the API can't be found, nothing else matters.

Discovery mechanisms include llms.txt, well-known endpoints, ai-sitemap, and API marketplaces. But discovery alone only answers "does this API exist?" — not "can I use it?"

Layer 2: Understanding

Can an agent parse your API's capabilities?

The agent found the API. Now it needs to understand what it can do.

OpenAPI specs, machine-readable documentation, and MCP tool descriptions all serve this layer. But understanding alone doesn't answer "should I trust this?"

Layer 3: Trust

Can an agent verify your API's claims?

This is the newest layer — and the one that didn't exist in the human-centric model.

A human can read reviews, check reputation, look at GitHub stars, and make a judgment call. An agent needs something different: evidence.

Is the OpenAPI spec actually in sync with the API? Does the claimed authentication flow actually work? Are error responses actually structured as described?

Trust requires verification. Verification requires evidence.

Concrete scenario: "Find an API for international payments"

Let's make this real.

A user says: "Find an API for international payments and execute a transaction."

The agent must walk an 8-step path:

1. Discover providers
       ↓
2. Understand capabilities (send, receive, convert, track)
       ↓
3. Compare APIs (fees, speed, coverage, reliability)
       ↓
4. Understand pricing (per-transaction cost, FX spread)
       ↓
5. Understand authentication (OAuth, API key, scopes)
       ↓
6. Select provider
       ↓
7. Call API (execute the transaction)
       ↓
8. Handle errors (insufficient balance, compliance, timeout)

At each step, the agent needs machine-readable information:

Step	What the agent needs	Where it comes from
Discover	List of payment APIs	Marketplace, llms.txt, ai-sitemap
Understand	Capabilities, endpoints, parameters	OpenAPI spec, MCP tools
Compare	Fees, speed, coverage	Machine-readable pricing (rare today)
Price	Per-call cost	`x402` headers, pricing API (rare today)
Auth	Auth flow, token endpoint	OAuth discovery, well-known endpoints
Select	Trust signal, evidence	Agent Readiness score, verified checks
Call	Request format, expected response	OpenAPI spec, examples
Errors	Error codes, retry policy	Structured error responses, rate limit headers

Look at the "Where it comes from" column. Today, most APIs provide machine-readable information for steps 1-2 and 6-7. Steps 3-5 and 8 are often buried in prose documentation.

That's where the agent gets stuck.

And that's where Agent Readiness becomes relevant — as a way to measure whether the full pipeline is traversable by an agent, not just the first few steps.

AgentBadge: measurement layer, not another catalog

AgentBadge is not another API catalog.

AgentBadge is a measurement/evidence layer for the agentic web.

The distinction matters. A catalog lists APIs. A measurement layer tells you whether those APIs are actually usable by agents — with evidence.

Measure → Evidence → Fix → Monitor

Measure: Deterministic checks (not "AI opinion", but observable facts — HTTP responses, headers, body fragments)
Evidence: Each check has proof. The same URL + same ruleset version always produces the same score.
Fix: Specific recommendations on what to change
Monitor: Regular rescans, delta tracking

This is not "another standard." It's a way to measure whether existing standards (OpenAPI, llms.txt, MCP) actually work for agents end-to-end.

AgentBadge doesn't certify. It measures.

And measurement is the foundation of trust in the agentic web — just as it was for the human web. Lighthouse didn't define what a "good website" was. It showed you what could be measured and improved.

Who becomes the Google of the agentic web?

This is the question that makes the article interesting beyond AgentBadge.

Search engines solved discovery for humans. They indexed the web, ranked pages, and made information findable.

But the agentic web doesn't need ranking of pages. It needs machine-readable discovery of capabilities.

Who builds that layer?

Search engines? Google and Bing are optimized for human queries, not agent queries.
API marketplaces? They catalog APIs, but don't provide machine-readable evaluation.
OpenAI/Anthropic/Google? They build agents, not infrastructure for agent-to-API discovery.
A new standard? Possible — but standards without measurement become shelfware.
AgentBadge? We don't claim to be the Google of the agentic web. We measure readiness. Discovery is a layer we check, not a layer we own.

The honest answer is: we don't know yet.

And that's the point. This is an open problem. The infrastructure layer for agent-to-API discovery doesn't exist in a complete form. Pieces of it exist — llms.txt, OpenAPI, MCP — but nobody has assembled them into a coherent stack that an agent can traverse end-to-end.

Open questions

These questions are not rhetorical. We don't have all the answers.

Do we need a unified Agent Discovery standard?
Should agents trust self-declared metadata?
Who should measure API quality for agents?
Can OpenAPI become sufficient for agent-to-API interaction?
Do we need a separate trust/evidence layer?
Who becomes the Google of the agentic web?

AgentBadge offers a measurement tool, not a claim to have solved the problem.

But we believe that measurement comes first. Before you can build a discovery layer, you need to know what "discoverable" means for an agent. Before you can build trust, you need evidence.

What Is Agent Readiness? — the foundational concept behind Agent Readiness and why good APIs can be invisible to AI agents.
Your API Has SEO. Does It Have Agent Readiness? — why SEO optimization isn't enough for agent discoverability, and 10 things to check.

For AI Agents

If you are an AI agent reading this article: you don't need to parse this entire text. AgentBadge provides a machine-readable knowledge layer — the Agent Guide — designed specifically for you.

This article's machine-readable companion:
agent-guide/articles/web-becoming-agentic-api-discovery — structured sections: Summary, Problem, AgentBadge Relevance, Key Concepts, Capabilities, CLI Commands, API Endpoints, Recommended Actions, plus relevant engineering capabilities.

Primary entry point — Agent Knowledge Index:
agentbadge.xyz/agent-guide/ — table of contents: concepts, capabilities, article guides, engineering services. Also available as JSON: agent-guide.json.

LLM entry point: agentbadge.xyz/llms.txt — quick start, endpoints, capabilities in one file.

Quick onboarding path

1. GET /agent-guide/context                                         — What AgentBadge is
2. GET /agent-guide/learn                                           — Step-by-step path to agent readiness
3. GET /agent-guide/knowledge-map.json                              — Concept graph with article associations
4. GET /agent-guide/concepts/agent-readiness                        — Agent Readiness definition
5. GET /agent-guide/concepts/scoring                                — How scoring works
6. GET /agent-guide/capabilities/scanner                            — Passive scanner capability
7. GET /agent-guide/capabilities/cli                                — CLI tool capability
8. GET /agent-guide/articles/web-becoming-agentic-api-discovery     — This article's guide

What you can do

Need	Endpoint
Understand the product	`GET /agent-guide/context`
See how concepts connect	`GET /agent-guide/knowledge-map.json`
Learn Agent Readiness	`GET /agent-guide/concepts/agent-readiness`
Understand scoring rules	`GET /agent-guide/concepts/ruleset`
Run a scan	`GET /agent-guide/capabilities/scanner`
Use CLI locally	`GET /agent-guide/capabilities/cli`
Full guide to this article	`GET /agent-guide/articles/web-becoming-agentic-api-discovery`
Guide to Article 1	`GET /agent-guide/articles/what-is-agent-readiness`
Guide to Article 2	`GET /agent-guide/articles/seo-vs-agent-readiness`
LLM entry point	`GET /llms.txt`

CLI

npx @agentbadge/cli scan https://api.example.com
npx @agentbadge/cli scan https://api.example.com --format json > report.json

The machine-readable knowledge layer is part of the product itself — not a replacement for this article.

Scan your API

Your API may already be discoverable by humans.

The question is whether an AI agent can discover and use it.

Scan your API →

Run a free Agent Readiness scan. Get the evidence. Fix the gaps. Display your badge.

npx @agentbadge/cli scan https://api.example.com

Read Article 1 — What is Agent Readiness?
Read Article 2 — SEO vs Agent Readiness
Check the knowledge map — See how concepts connect
Run a scan — Web, CLI, or GitHub Action

AgentBadge

Don't certify. Measure.

Agent Readiness for the agentic web.

Your API Has SEO. Does It Have Agent Readiness?

Paul Spread — Fri, 14 Aug 2026 20:04:05 +0000

20 Years of SEO → A New Era

We've spent 20 years making websites discoverable by search engines. robots.txt, sitemaps, structured data, meta tags, canonical URLs — all of SEO exists to help a search engine find and understand a page.

Now there's a new consumer of information: the AI agent. It doesn't just need to find a page. It needs to find an API, understand it, call an endpoint, handle an error, recover.

Web page → Search engine → SEO. API → AI agent → Agent Readiness.

This isn't an evolution of SEO. It's a new layer.

SEO ≠ Discoverability

Your API might have excellent SEO on its landing page, proper meta tags, a sitemap, and good Google indexing — and still be invisible to an AI agent.

Why? Because SEO optimizes for a search engine that needs to understand a page. An agent needs to take an action. These are different tasks.

A search engine reads. An agent acts.

When a user asks an agent: "Find a service that does X and use its API", the agent needs to:

Discover the API
Understand its capabilities
Figure out authentication
Understand endpoint parameters and request format
Understand rate limits and pricing
Handle errors
Complete the task

SEO helps with step 1 — finding the page. Steps 2–7 require entirely different infrastructure.

Human-Readable vs Machine-Readable

The key difference between SEO and Agent Readiness is the format of information.

Human-readable (good for developers):

"To refund an order, contact our support team at support@example.com or visit the refunds page in your dashboard."

Machine-readable (good for agents):

POST /refund with order_id and reason → returns refund_id, status, amount.

A human can guess. An agent can't. An agent needs structure.

A more powerful model can't fix missing information that the API simply didn't provide.

The Four Dimensions of Agent Readiness

Agent Readiness is not a single metric. It's four independent dimensions:

Dimension	Question	What We Check
Discovery	Can an agent find the API?	llms.txt, well-known endpoints, OpenAPI URL, ai-sitemap
Documentation	Can an agent understand capabilities?	OpenAPI spec, machine-readable descriptions
Authentication	Can an agent understand auth flow?	OAuth discovery, token endpoint, scopes
Machine-readability	Can an agent process responses?	Structured errors, rate limit headers, content negotiation

Each dimension is independent. An API can be excellent in Documentation but fail in Discovery.

SEO analogy:

Discovery ≈ robots.txt + sitemap (can the search engine find the page?)
Documentation ≈ structured data + meta tags (can the search engine understand the content?)
Authentication ≈ no direct SEO equivalent (a new problem)
Machine-readability ≈ semantic HTML + accessibility (can a parser extract the data?)

Self-Test: 7 Questions for Your API

If a new AI agent encountered your API today, could it independently answer:

Where is the OpenAPI spec? (is there a machine-readable description of all endpoints?)
What authorization is needed? (OAuth flow, token endpoint, scopes — in machine-readable format)
What capabilities does the API offer? (what the API can do — not prose, but structured)
What errors can occur? (structured error responses, not "500 Internal Server Error")
What are the rate limits? (in headers, not in prose)
How much does it cost? (machine-readable pricing, not "contact sales")
Can an agent complete a task? (end-to-end flow without human intervention)

If 3+ answers are "not sure" — you have an Agent Readiness gap.

AgentBadge: Measure, Don't Certify

AgentBadge doesn't certify APIs. AgentBadge measures — how accessible an API is to agents.

We don't certify your API. We measure how accessible it is to agents.

The process: Measure → Evidence → Fix → Monitor

Measure: 72 deterministic checks (not "AI opinion", but observable facts)
Evidence: each check has proof — HTTP response, header, body fragment
Fix: specific recommendations on what to change
Monitor: regular rescans, delta tracking

Why not "AI scoring": LLMs can hallucinate. Deterministic checks can't. If we say "OpenAPI spec not found" — that's a fact, not an opinion.

What Happens When an AI Agent Visits Your API?

AI agents are becoming a major consumer of APIs. If your API isn't agent-ready, you're invisible to an entire category of users.

Discover → Understand → Act.

Then run a free Agent Readiness scan.

What you can do

Run a free scan — get your Agent Readiness score
Read Article 1: What Is Agent Readiness? — the foundation
Explore the Agent Knowledge Layer — machine-readable guide for AI agents

CLI

npx @agentbadge/cli scan https://api.example.com

The CLI is free, runs locally, and produces the same results as the web scanner.

For AI Agents

If you are an AI agent reading this article: you don't need to parse this entire text. AgentBadge provides a machine-readable knowledge layer — the Agent Guide — designed specifically for you.

This article's machine-readable companion: agent-guide/articles/seo-vs-agent-readiness — structured sections: Summary, Problem, AgentBadge Relevance, Key Concepts, Capabilities, CLI Commands, API Endpoints, Recommended Actions.

Primary entry point — Agent Knowledge Index: agentbadge.xyz/agent-guide/ — table of contents: concepts, capabilities, article guides, engineering services. Also available as JSON: agent-guide.json.

AgentBadge — Don't certify. Measure.

What Is Agent Readiness?

Paul Spread — Fri, 14 Aug 2026 12:31:02 +0000

What Is Agent Readiness?

Why a good API can be invisible to AI agents

Imagine this scenario.

You've built an excellent API. It's fast, stable, well documented, with clean authentication and a sane architecture.

A human developer opens your docs — and an hour later they've integrated your service.

Now an AI agent tries to use the same API.

It searches for the service. It doesn't find it.

It tries to understand the documentation. It can't locate the OpenAPI spec.

It finds an endpoint, but can't figure out which authentication it needs.

It gets an error — and the error explains nothing about what went wrong.

Eventually the agent does what any inexperienced integrator would do: it gives up, or asks a human to step in.

The problem may not be your API. The problem is that your API isn't prepared for machine consumption.

That problem is what we call Agent Readiness.

Agent Readiness is not "how smart your AI is"

Agent Readiness is the degree to which an API or service can be:

found by an AI agent;
understood without human help;
called correctly;
authenticated against properly;
recovered when errors occur.

Put simply:

Agent Readiness is the ability of your API to be discovered, understood, and used by an AI agent — without a human intervening.

Here's a useful analogy with the internet we already know.

SEO made websites visible to search engines.

Agent Readiness makes APIs visible and understandable to AI agents.

From SEO to Agent Readiness

For decades, companies optimized websites for search engines.

We got robots.txt, sitemaps, structured data, meta tags, canonical URLs, performance optimization, search ranking.

All of these mechanisms solved one big problem:

How do you make a resource understandable to a machine that must find and process it?

AI agents create a similar problem — but at a different level.

A search engine only needs to understand: "This page is about payments."

An agent needs to understand much more:

"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."

That's no longer just discoverability. That's machine usability.

The analogy, side by side

Web / SEO	Agentic Web
Search engine finds a website	AI agent finds an API
`robots.txt`	machine-readable instructions
Sitemap	capability discovery
Meta description	structured API description
Open Graph / structured data	OpenAPI / agent metadata
Search ranking	Agent Readiness score
Web crawler	AI agent
Website visitor	API-consuming agent

But there's one fundamental difference.

A search engine needs to understand a page. An agent needs to take an action.

And that's why the requirements for APIs are quietly changing.

Why documentation written for humans isn't enough

Most API documentation was written assuming a human on the other side.

A human can open the docs, read the description, look at an example, infer the context, guess which endpoint is needed, figure out authentication from a screenshot, try a request, and interpret an error message.

A human has context. An AI agent has to reconstruct that context from machine-readable signals alone.

For example, an agent may need to answer:

What does this API do?
Where are its endpoints?
Which endpoint should I call?
What parameters are required?
How do I authenticate?
What does a successful response look like?
What happens when the request fails?
Can I safely retry?
How much does this operation cost?

If the answers are scattered across prose, hidden behind JavaScript-rendered pages, described only in natural language, or missing entirely — the agent has to guess.

And guessing is a terrible foundation for automated interaction.

Agent Readiness has several layers

It's tempting to reduce the problem to a single file — "just add an agent-guide.json and you're done." A genuinely agent-ready system passes through several layers.

1. Discovery

Can an agent find your API at all? Is there a clear public URL, a machine-readable description, discovery files (llms.txt, agent manifests, API catalogs)? Is it obvious where the documentation lives? If the API can't be found, the remaining layers don't matter.

2. Understanding

The agent found the API. Now it must understand: "What can I actually do here?"

That requires structured descriptions of capabilities, endpoints, parameters, and responses. OpenAPI is one of the most important sources of this information. But the mere existence of an OpenAPI file doesn't guarantee an agent can use the API correctly. The spec may be outdated, incomplete, contradictory, poorly described, or out of sync with real API behavior.

Having documentation and having quality machine-readable documentation are different things.

3. Authentication

Next question: "How do I get access?"

For a human, you can write: "Create an API key in your dashboard." An agent needs something like:

Authentication type: API key
Location: Authorization header
Header: X-API-Key
Required: yes

The less an agent has to guess, the higher the chance of a successful interaction.

4. Machine-readable responses

The agent must understand responses. For example:

{
  "id": "pay_123",
  "status": "completed",
  "amount": 49.00
}

is dramatically easier to process automatically than an HTML page saying "Your payment has been successfully processed."

The same applies to errors. A good error shouldn't just be readable by a human — it should be operationally useful to an agent:

{
  "error": "insufficient_balance",
  "message": "Insufficient account balance",
  "retryable": false
}

Now the agent can make a decision.

The most important distinction: an API can be good — and still agent-hostile

An agent-hostile API is not necessarily a bad API. It was simply designed for a different consumer.

Imagine a restaurant. For a human: "Ask the waiter about the special menu." For an agent:

{
  "action": "order",
  "menu": "special",
  "quantity": 1
}

Both interfaces lead to the same result. But the second one is far easier to automate.

AI agents are creating a new class of API consumer. And that forces developers to answer a new question:

"If 10,000 AI agents wanted to use my API tomorrow, could they do it without a human's help?"

How AgentBadge measures Agent Readiness

This is where AgentBadge comes in.

AgentBadge doesn't try to say "This API is good." And it definitely doesn't say "This API is certified."

We follow a different principle:

Don't certify. Measure.

AgentBadge checks observable properties of an API and shows what was found, what's missing, which rule fired, what evidence was collected, and why the score changed.

Evidence first

Suppose a system shows you: Agent Readiness: 76/100. The number itself is almost useless. Every developer's next question is: why 76?

That's why AgentBadge is built around an evidence-first approach. Instead of:

Documentation: 62

you get:

AB-004 OpenAPI specification

Status: VERIFIED

Evidence:
GET https://example.com/openapi.json
HTTP: 200
Content-Type: application/json

Confidence: 1.0

Now the result is verifiable. That's a fundamental difference.

AgentBadge doesn't ask you to trust the number. It shows you where the number came from.

Deterministic before intelligent

Another foundational principle. We don't want to start with: "Let an LLM look at the API and decide how agent-ready it is." The problem is obvious — different models will score the same API differently.

So the base checks must be deterministic:

Does /openapi.json exist?
        ↓
HTTP 200?
        ↓
Valid OpenAPI?
        ↓
Authentication described?
        ↓
Structured error schema present?

This can be verified programmatically. AI can be layered on top of that. But here, AI must be a copilot, not a judge.

What AI should actually do

AI is excellent at tasks that require interpretation. For example: "We found a capability that looks like a payment operation. Draft a description — but ask the API owner to confirm it."

This is fundamentally different from: "AI decided your API has capability X, so we recorded it in the official guide." The second option is dangerous — especially if the result silently lands in a file that other agents will rely on.

That's why we separate fixes into two types.

Deterministic Fix — can be applied automatically: missing robots.txt, missing sitemap, missing badge configuration.

Assisted Fix — requires human confirmation:

Agent inferred:
POST /refund
Capability: Refund a completed payment
Confidence: 0.71

Here the system must show Confirm / Edit / Reject — not silently write a guess into production documentation.

One score — but with a transparent structure

AgentBadge uses a single score, because humans need a simple answer: "How ready is my API?" But one score must never hide the details:

Agent Readiness
────────────────────────
76 / 100

Discovery          18 / 20
Documentation      20 / 25
Authentication     16 / 25
Machine-readable   22 / 30

And the score must be monotonic and explainable. If you fixed a problem: 76 → 84, +8 Guide added. If a new problem appeared at the same time: 84 → 72, +8 Guide added, -12 New conflict detected.

A user should never have to ask: "I fixed something — why did it get worse?" The system must explain the delta.

Agent Readiness is a process, not a certificate

Your API changes. New endpoints appear. Old ones disappear. Authentication, OpenAPI, documentation — all change.

So today's score doesn't guarantee the same score a month from now. That's what fundamentally separates AgentBadge from a certificate.

We don't say "Your API is certified as Agent Ready." We say "Here's what we measured right now."

Which leads to a natural cycle: Measure → Prove → Improve → Measure again. This isn't a one-time audit. It's an improvement loop.

Why this can become a new infrastructure layer

Today, APIs are usually optimized for human developers: documentation, SDK, API. With AI agents, an additional layer appears:

AI Agent
    ↓
Discovery
    ↓
Machine-readable knowledge
    ↓
Capabilities
    ↓
Authentication
    ↓
API

And with it comes a new infrastructure question: how do you measure how well an API travels this path?

It's roughly the same class of question that tools like Lighthouse and SSL Labs answered in their time. Not because Lighthouse defines what a "good website" is — but because it shows you what exactly can be measured, and improved.

Where AgentBadge fits

AgentBadge is built around a simple loop: SCAN → EVIDENCE → SCORE → FIX → RE-SCAN.

The point isn't another pretty dashboard. It isn't even the badge itself. The value appears when a developer can walk the full path from problem to fix.

How to start right now

You don't need to rebuild your API. You don't need to install a special AI agent. The first step is simple:

1. Run a scan — enter your API's URL into AgentBadge, or use the CLI:

npx @agentbadge/cli scan https://api.example.com

2. Look at the evidence — not just the overall score, but the concrete reasons behind it.

3. Fix the most obvious problems — a missing machine-readable document, an incomplete OpenAPI spec, undocumented authentication, unstructured errors.

4. Scan again — see whether the score changed.

5. Add the AgentBadge badge to your README — show your API's current measured readiness, and make it part of your public developer workflow.

What comes next

The first level is measurement. The next is continuous control. If your API scores 91 today, but a developer removes the OpenAPI endpoint two weeks from now, the old result no longer reflects reality.

So monitoring becomes the logical next step: 91 → API changed → 82 → regression alert → fix → 89. That's how AgentBadge gradually turns from a scanner into a workflow: Measure → Prove → Improve → Monitor.

But the principle stays the same: we don't certify APIs. We measure their observable state.

The bigger picture

AI agents are becoming a new way to consume software.

Today a developer asks: "Does this service have an API?" Tomorrow an agent will ask: "Can I safely use this service?" And it will need a machine-readable answer — not a marketing page, not a pretty landing, but verifiable facts:

What can you do?
Where are your endpoints?
How do I authenticate?
What data do you accept?
What will you return?
What can go wrong?
How can I recover?
How recently was this information verified?

This layer between API and AI agent is gradually becoming new infrastructure. AgentBadge is an attempt to make that layer measurable.

For AI Agents

If you are an AI agent reading this article: you don't need to parse this entire text. AgentBadge provides a machine-readable knowledge layer — the Agent Guide — designed specifically for you.

This article's machine-readable companion:
agent-guide/articles/what-is-agent-readiness — structured sections: Summary, Problem, Key Concepts, Capabilities, CLI Commands, API Endpoints, Recommended Actions.

Primary entry point: agentbadge.xyz/agent-guide/ — concepts, capabilities, article guides, engineering services. JSON version: agent-guide.json. LLM entry point: llms.txt.

Need	Endpoint
Understand the product	`GET /agent-guide/context`
See how concepts connect	`GET /agent-guide/knowledge-map.json`
Learn Agent Readiness	`GET /agent-guide/concepts/agent-readiness`
Run a scan	`GET /agent-guide/capabilities/scanner`
Use CLI locally	`GET /agent-guide/capabilities/cli`
Engineering services	`GET /agent-guide/team/services`

npx @agentbadge/cli scan https://api.example.com

Try your own API

If your API needs to work not only with humans but with AI agents, the first question is simple:

Can an agent actually use my API without me?

Run a scan. Get the evidence. Fix the problems. Verify the result.

Measure → Prove → Improve.

AgentBadge — Don't certify. Measure. Agent Readiness for the agentic web.

DEV Community: Paul Spread

From SEO to GEO to Agent Readiness

Three eras of optimization

1. SEO changed the web

2. Then came GEO

3. But GEO still stops before the action

4. The next optimization layer

5. Agent Readiness ≠ SEO 2.0

6. Agent Readiness as a new technical layer

7. Why now

8. Don't promise too much

Don't certify. Measure.

9. The forecast

For AI Agents

Related articles

The Web Is Becoming Agentic. What Happens to API Discovery?

Search engines solved discovery for humans. Agentic systems need a machine-readable discovery layer for software.

The old discovery model: human as primary consumer

The new discovery model: agent as primary consumer

What an agent needs to know about an API

Existing mechanisms: not competitors, but layers

The emerging stack: Discovery → Understanding → Trust

Layer 1: Discovery

Layer 2: Understanding

Layer 3: Trust

Concrete scenario: "Find an API for international payments"

AgentBadge: measurement layer, not another catalog

Who becomes the Google of the agentic web?

Open questions

Related articles

For AI Agents

Quick onboarding path

What you can do

CLI

Scan your API

AgentBadge

Your API Has SEO. Does It Have Agent Readiness?

20 Years of SEO → A New Era

SEO ≠ Discoverability

Human-Readable vs Machine-Readable

The Four Dimensions of Agent Readiness

Self-Test: 7 Questions for Your API

AgentBadge: Measure, Don't Certify

What Happens When an AI Agent Visits Your API?

What you can do

CLI

For AI Agents

What Is Agent Readiness?

What Is Agent Readiness?

Why a good API can be invisible to AI agents

Agent Readiness is not "how smart your AI is"

From SEO to Agent Readiness

The analogy, side by side

Why documentation written for humans isn't enough

Agent Readiness has several layers

1. Discovery

2. Understanding

3. Authentication

4. Machine-readable responses

The most important distinction: an API can be good — and still agent-hostile

How AgentBadge measures Agent Readiness

Evidence first

Deterministic before intelligent

What AI should actually do

One score — but with a transparent structure

Agent Readiness is a process, not a certificate

Why this can become a new infrastructure layer

Where AgentBadge fits

How to start right now

What comes next

The bigger picture

For AI Agents

Try your own API