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-productions.s3.amazonaws.com/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
  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.
- 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
  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: [email protected]