Why endpoint pages need machine-readable intent

An endpoint page has two readers.

The first is human. They scan the price, method, input shape, output shape, and the x402 payment flow. They ask a direct question: should I call this?

The second reader is an agent, or the LLM that routes work for one. It doesn't browse like a person. It extracts names, actions, prices, schemas, and source text. Then it decides what to cite, what to call, and what to skip.

That's why every paid endpoint page should emit schema.org JSON-LD.

HTML can say a lot, but JSON-LD says it in a form parsers already expect. WebAPI says this page describes an API. Service says the endpoint is a paid callable service. TechArticle gives AI search systems a citation target. Offer carries the price. ConsumeAction says the thing can be called.

Short version: the endpoint isn't just content. It's an action with a cost.

The shape we emit

Agentutility currently tracks 254 endpoints across edge-finance, locale, edge-market, prooflayer, wordmint, web-probe, mediakit, and synthforge. Prices run from $0.001 to $0.3 per call.

That range matters. An agent deciding between a cheap lookup and a paid analysis endpoint needs the price next to the action, not buried in prose.

A page-level graph can look like this: 

{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "TechArticle",
      "@id": "https://agentutility.ai/endpoints/secrets-exposure-check#article",
      "headline": "Secrets exposure check",
      "about": {
        "@id": "https://agentutility.ai/endpoints/secrets-exposure-check#api"
      },
      "author": {
        "@type": "Organization",
        "name": "agentutility"
      }
    },
    {
      "@type": "WebAPI",
      "@id": "https://agentutility.ai/endpoints/secrets-exposure-check#api",
      "name": "Secrets exposure check",
      "url": "https://agentutility.ai/endpoints/secrets-exposure-check",
      "documentation": "https://agentutility.ai/endpoints/secrets-exposure-check",
      "provider": {
        "@type": "Organization",
        "name": "agentutility"
      },
      "potentialAction": {
        "@id": "https://agentutility.ai/endpoints/secrets-exposure-check#consume"
      }
    }
  ]
}

The IDs do real work. The article points at the API. The API points at the action. Search systems can cite the human page while agents can still find the callable surface.

Service and Offer describe the paid endpoint

x402 changes the normal API page. The endpoint can return 402 Payment Required, and the client can pay on Base mainnet before retrying the request. That payment behavior belongs in structured data too, at least as price and service terms. 

{
  "@context": "https://schema.org",
  "@type": "Service",
  "@id": "https://agentutility.ai/endpoints/secrets-exposure-check#service",
  "name": "Secrets exposure check",
  "serviceType": "x402 paid HTTP endpoint",
  "provider": {
    "@type": "Organization",
    "name": "agentutility"
  },
  "areaServed": "Internet",
  "offers": {
    "@type": "Offer",
    "price": "0.01",
    "priceCurrency": "USD",
    "availability": "https://schema.org/InStock",
    "url": "https://agentutility.ai/endpoints/secrets-exposure-check"
  }
}

Look at the exact fields an agent can keep:

serviceType: x402 paid HTTP endpoint.

price: 0.01.

priceCurrency: USD.

url: the endpoint page.

No guesswork. No scraping a pricing table.

ConsumeAction tells agents what can happen next

ConsumeAction is where the page stops being passive. It marks the endpoint as something a client can call. 

{
  "@context": "https://schema.org",
  "@type": "ConsumeAction",
  "@id": "https://agentutility.ai/endpoints/secrets-exposure-check#consume",
  "name": "Call secrets exposure check",
  "target": {
    "@type": "EntryPoint",
    "urlTemplate": "https://api.agentutility.ai/prooflayer/secrets-exposure-check",
    "httpMethod": "POST",
    "encodingType": "application/json",
    "contentType": "application/json"
  },
  "object": {
    "@id": "https://agentutility.ai/endpoints/secrets-exposure-check#service"
  }
}

This isn't a replacement for OpenAPI. Keep OpenAPI for full request and response contracts. JSON-LD has a different job: tell crawlers and agent routers that the page represents a paid action, then link that action to the service, the API, and the citation page.

And yes, the endpoint page should still show examples in plain Markdown. LLMs quote visible text. JSON-LD helps them pick the right page before they quote it.

What AI search gets wrong without it

Without JSON-LD, an AI search index may see a page title, some docs text, and a code sample. It may know there's an endpoint, but miss the fact that it's callable through x402. It may cite a cluster page when the endpoint page is the better source. It may flatten a $0.001 lookup and a $0.3 analysis call into the same vague bucket.

Structured data cuts that ambiguity.

For a catalog with 254 paid endpoints, this matters more than it does for a blog. Endpoint pages compete with each other inside the same domain. A locale endpoint shouldn't be cited for a prooflayer task. A web-probe tool shouldn't be routed when the agent needs edge-market data.

JSON-LD gives every page a clean identity: article, API, service, offer, action.

The practical rule

If an endpoint can be paid for and called, its page should say five things in JSON-LD.

It has a readable article URL. It describes a WebAPI. It represents a Service. It has an Offer with a price. It exposes a ConsumeAction with an EntryPoint.

That's enough for AI search citation. It's enough for agent routing. And it's simple enough to emit on every endpoint page without turning docs into a second API spec.