Agent Readiness

aid: agent-readiness
url: https://raw.githubusercontent.com/api-evangelist/agent-readiness/refs/heads/main/apis.yml
name: Agent Readiness
type: Index
image: https://kinlane-images.s3.amazonaws.com/shared/apis-json/apis-json-logo.jpg
tags:
- Agent Readiness
- AI Agents
- API Discovery
- API Governance
- Machine-Readable APIs
- MCP
- OpenAPI
- AsyncAPI
description: A topic index covering the operational practices, signals, and patterns that make an API surface safely usable by autonomous AI agents rather than only by humans. Catalogs the specifications, identity layers, agent skill formats, and edge-layer signals that combine into a coherent agent-readiness posture, with a dimension model, JSON Schema, JSON-LD context, vocabulary, and example signal records for representative providers.
created: '2026-05-22'
modified: '2026-05-22'
specificationVersion: '0.20'
apis:
- aid: agent-readiness:model-context-protocol
  name: Model Context Protocol (MCP)
  tags:
  - Agent Tooling
  - Agent Readiness
  - JSON-RPC
  - Standards
  humanURL: https://modelcontextprotocol.io
  baseURL: https://modelcontextprotocol.io
  properties:
  - url: https://modelcontextprotocol.io/specification
    type: Documentation
  - url: https://github.com/modelcontextprotocol
    type: GitHubOrganization
  - url: https://github.com/modelcontextprotocol/specification
    type: GitHubRepository
  description: An open JSON-RPC protocol that lets AI agents talk to tools, resources, and prompts through a uniform server surface. MCP is the most direct expression of "an API designed for an agent" — every API surface that ships an MCP server scores higher on agent readiness because agents can call it through one shared transport.
- aid: agent-readiness:openapi-initiative
  name: OpenAPI Specification
  tags:
  - API Specification
  - Agent Readiness
  - Machine-Readable APIs
  - Standards
  humanURL: https://www.openapis.org
  baseURL: https://spec.openapis.org
  properties:
  - url: https://spec.openapis.org/oas/latest.html
    type: Documentation
  - url: https://github.com/OAI/OpenAPI-Specification
    type: GitHubRepository
  description: The dominant machine-readable contract for HTTP APIs. Presence of a public OpenAPI document — with examples, error schemas, security schemes, and rate-limit headers — is the single highest-leverage agent-readiness signal for a REST surface, because it gives an agent everything it needs to call the API without scraping HTML docs.
- aid: agent-readiness:asyncapi-initiative
  name: AsyncAPI Specification
  tags:
  - Event-Driven APIs
  - Agent Readiness
  - Async
  - Standards
  humanURL: https://www.asyncapi.com
  baseURL: https://www.asyncapi.com
  properties:
  - url: https://www.asyncapi.com/docs/reference/specification/latest
    type: Documentation
  - url: https://github.com/asyncapi/spec
    type: GitHubRepository
  description: Machine-readable contract for event-driven APIs (webhooks, message brokers, streaming). Agent-readiness for event surfaces depends on whether the provider ships an AsyncAPI document so agents can subscribe, dispatch, and validate events programmatically.
- aid: agent-readiness:json-schema
  name: JSON Schema
  tags:
  - Schema
  - Validation
  - Agent Readiness
  - Standards
  humanURL: https://json-schema.org
  baseURL: https://json-schema.org
  properties:
  - url: https://json-schema.org/specification.html
    type: Documentation
  - url: https://github.com/json-schema-org/json-schema-spec
    type: GitHubRepository
  description: The vocabulary that lets an agent validate request and response bodies against typed contracts. Published JSON Schemas (independent of, or embedded in, an OpenAPI) are a strong agent-readiness signal because they let agents self-correct payloads before sending.
- aid: agent-readiness:agent-skills
  name: Agent Skills
  tags:
  - Agent Skills
  - Agent Readiness
  - Discoverability
  humanURL: https://agentskills.io
  baseURL: https://agentskills.io
  properties:
  - url: https://agentskills.io/schema/index.json
    type: JSONSchema
  description: A community schema for publishing operational instructions an agent should follow when using a site or API. A provider that ships a `/skills/` directory with a skill index is signalling that it has thought about the agent workflow, not just the human one.
- aid: agent-readiness:well-known-api-catalog
  name: /.well-known/api-catalog (RFC 9727)
  tags:
  - Discovery
  - Linkset
  - Agent Readiness
  - Standards
  humanURL: https://www.rfc-editor.org/rfc/rfc9727.html
  baseURL: https://www.rfc-editor.org/rfc/rfc9727.html
  properties:
  - url: https://www.rfc-editor.org/rfc/rfc9727.html
    type: Documentation
  - url: https://www.rfc-editor.org/rfc/rfc9264.html
    type: Documentation
  - url: examples/agent-readiness-signal-cloudflare-well-known-catalog-example.json
    type: Example
  - url: examples/agent-readiness-signal-memesio-well-known-catalog-example.json
    type: Example
  - url: examples/agent-readiness-signal-merge-well-known-catalog-example.json
    type: Example
  - url: examples/agent-readiness-signal-zuplo-well-known-catalog-example.json
    type: Example
  description: RFC 9727 defines `/.well-known/api-catalog` as the canonical machine entrypoint for discovering an organization's APIs, formatted as an RFC 9264 linkset. Presence of a catalog at this path is one of the cheapest, highest-impact agent-readiness signals — agents do not have to crawl HTML to find specs. As of 2026-05-22, a survey of 74 likely-candidate providers found only four serving a real RFC 9727 linkset at the well-known path — Cloudflare, Memesio, Merge.dev, and Zuplo — with example signal records committed for each.
- aid: agent-readiness:rfc-9421-http-message-signatures
  name: HTTP Message Signatures (RFC 9421)
  tags:
  - Identity
  - Bot Auth
  - Agent Readiness
  - Standards
  humanURL: https://www.rfc-editor.org/rfc/rfc9421.html
  baseURL: https://www.rfc-editor.org/rfc/rfc9421.html
  properties:
  - url: https://www.rfc-editor.org/rfc/rfc9421.html
    type: Documentation
  description: A cryptographic signature scheme for HTTP messages, used by the emerging web-bot-auth profile to let agents authenticate themselves to origins. Provider support for verifying or surfacing RFC 9421 signatures is a forward-looking agent-readiness signal.
- aid: agent-readiness:web-bot-auth
  name: Web Bot Auth (draft)
  tags:
  - Identity
  - Bot Auth
  - Agent Readiness
  - Standards
  humanURL: https://datatracker.ietf.org/doc/draft-meunier-web-bot-auth-architecture/
  baseURL: https://datatracker.ietf.org/doc/draft-meunier-web-bot-auth-architecture/
  properties:
  - url: https://datatracker.ietf.org/doc/draft-meunier-web-bot-auth-architecture/
    type: Documentation
  description: IETF draft layering an "identified bot" profile on top of RFC 9421. A provider that publishes a directory of verified agent identities — or surfaces Web Bot Auth verdicts in its responses — is making agent traffic legible at the protocol layer instead of inferring it from User-Agent strings.
- aid: agent-readiness:content-usage-aipref
  name: Content-Usage / AIPREF (IETF AIPREF WG)
  tags:
  - Consent Signals
  - AI Preferences
  - Agent Readiness
  - Standards
  humanURL: https://datatracker.ietf.org/wg/aipref/about/
  baseURL: https://datatracker.ietf.org/wg/aipref/about/
  properties:
  - url: https://datatracker.ietf.org/doc/draft-ietf-aipref-attach/
    type: Documentation
  description: "The IETF AIPREF working group's effort to standardise machine-readable AI usage preferences (e.g. `Content-Usage: ai-input=y, ai-train=n`). A provider that publishes explicit AIPREF signals is making its consent posture legible to agents rather than burying it in terms of service."
- aid: agent-readiness:cloudflare-content-signals
  name: Cloudflare Content Signals
  tags:
  - Consent Signals
  - AI Preferences
  - Agent Readiness
  humanURL: https://blog.cloudflare.com/content-signals-policy/
  baseURL: https://blog.cloudflare.com/content-signals-policy/
  properties:
  - url: https://blog.cloudflare.com/content-signals-policy/
    type: Documentation
  description: Cloudflare's `Content-Signal` robots.txt directive, complementing the AIPREF drafts. Together they let an origin separate "crawl for search" from "use for AI input" from "use for AI training" — a concrete agent-readiness signal that the operator has made consent explicit.
- aid: agent-readiness:apis-json
  name: APIs.json
  tags:
  - Discovery
  - Agent Readiness
  - Standards
  humanURL: https://apisjson.org
  baseURL: https://apisjson.org
  properties:
  - url: https://apisjson.org
    type: Documentation
  - url: https://github.com/apis-json/api-specification
    type: GitHubRepository
  description: The APIs.json format describes a provider's API portfolio in one machine-readable document. Publishing `/apis.json` (or `/apis.yml`) at the site root is the agent-readiness equivalent of a site identity card — it tells an agent who the operator is and what surfaces are on offer.
- aid: agent-readiness:openid-connect
  name: OpenID Connect
  tags:
  - Identity
  - OAuth
  - Agent Readiness
  - Standards
  humanURL: https://openid.net/connect/
  baseURL: https://openid.net/connect/
  properties:
  - url: https://openid.net/specs/openid-connect-core-1_0.html
    type: Documentation
  description: Identity layer on top of OAuth 2.0. Agent-readiness for authenticated APIs depends on clear, discoverable OIDC metadata (`/.well-known/openid-configuration`) so agents can negotiate auth without reading prose.
- aid: agent-readiness:stripe-api
  name: Stripe API (reference provider)
  tags:
  - Payments
  - Agent Readiness
  - Reference Provider
  humanURL: https://docs.stripe.com/api
  baseURL: https://api.stripe.com
  properties:
  - url: https://docs.stripe.com/api
    type: Documentation
  - url: https://github.com/stripe/openapi
    type: OpenAPI
  - url: https://github.com/stripe
    type: GitHubOrganization
  description: Reference provider for the agent-readiness signal set. Stripe publishes its full OpenAPI, ships idempotency keys, surfaces rate-limit headers, has a consistent error envelope, and exposes a status page and changelog — close to a maximal agent-readiness score for a commercial API.
- aid: agent-readiness:github-rest-api
  name: GitHub REST + GraphQL API (reference provider)
  tags:
  - Developer Tools
  - Agent Readiness
  - Reference Provider
  humanURL: https://docs.github.com/en/rest
  baseURL: https://api.github.com
  properties:
  - url: https://docs.github.com/en/rest
    type: Documentation
  - url: https://github.com/github/rest-api-description
    type: OpenAPI
  - url: https://github.com/github
    type: GitHubOrganization
  - url: graphql/agent-readiness-graphql.md
    type: GraphQL
  description: Reference provider with arguably the most extensively-tooled developer surface on the web. Public OpenAPI, GraphQL schema, webhooks, conditional requests, explicit `X-RateLimit-*` headers, status page, and an MCP server — a near-complete agent-readiness signal set.
- aid: agent-readiness:twilio-api
  name: Twilio API (reference provider)
  tags:
  - Messaging
  - Agent Readiness
  - Reference Provider
  humanURL: https://www.twilio.com/docs
  baseURL: https://api.twilio.com
  properties:
  - url: https://www.twilio.com/docs
    type: Documentation
  - url: https://github.com/twilio/twilio-oai
    type: OpenAPI
  description: Reference provider with strong agent-readiness signals on the messaging side — published OpenAPI, idempotency on resource creation, structured error codes, signed webhooks, status page, and SDKs in every major language.
common:
- type: GitHubOrganization
  url: https://github.com/api-evangelist
- type: GitHubRepository
  url: https://github.com/api-evangelist/agent-readiness
- type: Documentation
  url: https://github.com/api-evangelist/agent-readiness/blob/main/README.md
- type: JSONSchema
  url: json-schema/agent-readiness-signal-schema.json
- type: JSONSchema
  url: json-schema/agent-readiness-provider-schema.json
- type: JSONLD
  url: json-ld/agent-readiness-context.jsonld
- type: Vocabulary
  url: vocabulary/agent-readiness-vocabulary.yaml
- type: Features
  data:
  - name: Dimension Model
    description: A nine-dimension scoring model covering specs, auth, idempotency, error semantics, rate-limit headers, dry-run, examples, MCP, and event contracts
  - name: Signal Schema
    description: JSON Schema describing a single agent-readiness signal (provider, dimension, score, evidence URL)
  - name: Provider Aggregate
    description: JSON Schema for a provider-level aggregate of signals across dimensions
  - name: JSON-LD Context
    description: A JSON-LD context aligning agent-readiness signals with schema.org and common API vocabularies
  - name: Reference Examples
    description: Example signal records for Stripe, Twilio, and GitHub illustrating how the model is applied in practice
  - name: Vocabulary
    description: Controlled vocabulary of agent-readiness terms across operational and capability dimensions
- type: UseCases
  data:
  - name: Provider Self-Assessment
    description: A team auditing their own API surface against a checklist of agent-readiness dimensions
  - name: Consumer Pre-Integration Review
    description: An engineering team evaluating whether a third-party API can be driven by an autonomous agent before committing to integration
  - name: Procurement and RFP Scoring
    description: A buyer scoring vendor APIs on a normalized agent-readiness rubric during procurement
  - name: Aggregator Indexes
    description: A directory or marketplace ranking listed APIs by agent-readiness score to help agent developers pick safe surfaces
  - name: Standards Coverage Map
    description: Mapping where each standard (OpenAPI, AsyncAPI, MCP, AIPREF, RFC 9727, RFC 9421) contributes to which dimension
maintainers:
- FN: Kin Lane
  email: kin@apievangelist.com