DEV Community

Paul Spread
Paul Spread

Posted on • Originally published at agentbadge.xyz

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

#ai #agents #api #webdev

cover

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
Enter fullscreen mode Exit fullscreen mode

A developer would:

  1. Google "best API for payments"
  2. Find a marketplace (RapidAPI, AWS Marketplace)
  3. Read documentation
  4. Compare options side by side
  5. Make a decision based on features, pricing, and reputation
  6. 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
Enter fullscreen mode Exit fullscreen mode

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.

Agent workflow — 8-step pipeline: Discover → Understand → Compare → Price → Auth → Select → Call → Handle Errors

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.

Comparison layers — stacked diagram: Search, API Marketplace, OpenAPI, llms.txt, MCP, Agent Readiness

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
Enter fullscreen mode Exit fullscreen mode

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.

Architecture stack — 3-column diagram: Discovery, Understanding, Trust, converging into API

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)
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode
  • 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.

Concept — six question marks in a circle:

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.

Related articles

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode
  1. Read Article 1 — What is Agent Readiness?
  2. Read Article 2 — SEO vs Agent Readiness
  3. Check the knowledge map — See how concepts connect
  4. Run a scan — Web, CLI, or GitHub Action

AgentBadge

Don't certify. Measure.

Agent Readiness for the agentic web.

CTA — terminal aesthetic:

Top comments (0)