Opens in a new tabSkip to content
Agent LighthouseAgent Lighthouse

    Searches the text of every published page. The evidence sources themselves are not in this index — search all of them on the trusted sources page.

    GitHub ↗
    Browse checks and page contents
    agent-interfaces/openapi-exists

    API description discoverable

    What it checks

    One discovery audit over the API-description mechanisms that actually exist, strongest first.

    State Result
    an RFC 9727 linkset at /.well-known/api-catalog — served as data, parseable, with a non-empty linkset array pass
    a valid OpenAPI document at /openapi.json or /openapi.yaml (version key and a paths object, non-HTML content type) pass
    a <link rel="service-desc"> (or a spec-shaped alternate) on any crawled page, followed and verified pass
    /openapi.json served but not an OpenAPI document; or a <link> advertising a spec that does not resolve to one; or the scan was blocked by a WAF warn, priority medium
    none of the above — no API surface at all na

    Why it matters

    An AI agent given only a site’s origin fetches /openapi.json or /openapi.yaml, and converts the operations it finds into callable tools, without a developer having registered the document with the agent first.

    Evidence

    • OpenAPI 3.1 defines no discovery path or well-known URI; it only states “It is RECOMMENDED that the root OpenAPI document be named: openapi.json or openapi.yaml”, which is the sole basis for probing those two paths — spec.openapis.org/…/v3.1.0.html (verified 2026-08-21)

    • OpenAI GPT Actions are built by pasting the OpenAPI schema into the Action editor, not by ChatGPT retrieving it from the site. The doc describes what happens next: “ChatGPT uses those names and descriptions to understand (a) which API action should be called and (b) which parameter should be used” — developers.openai.com/…/getting-started (verified 2026-08-21)

    • Microsoft 365 Copilot plugins “interact with … REST APIs that have an OpenAPI description”, supplied inside a plugin manifest that the developer packages and publishes — learn.microsoft.com/…/overview-api-plugins (verified 2026-08-21)

    • The standards-track machine-discovery path for APIs is /.well-known/api-catalog (RFC 9727, June 2025), a linkset that may point at OpenAPI documents — not /openapi.json; no AI-agent consumer of it is documented — rfc-editor.org/…/rfc9727.html (verified 2026-08-21)

    • 2026-08-24 — evidence sweep: re-checked, no change. B / informative / weight 0 stands; the “adopted forward rather than fading” sentence is withdrawn on ARD counter-evidence.

    Limits

    No crawler or agent documentation from OpenAI, Anthropic, Google, Microsoft, or Perplexity states that any named agent fetches /openapi.json from a site root. The plugin-era discovery chain (/.well-known/ai-plugin.json pointing at a spec URL) is gone from OpenAI’s current documentation, which describes pasting a schema instead. For remote tool surfaces, the documented discovery paths in 2026 are MCP’s server/discover and the DNS-verified MCP Registry, not a root OpenAPI file. Passing this audit therefore proves an artifact exists, not that any agent will find it.

    How it scores

    OpenAPI is unambiguously the format documented consumers ingest. But every documented consumer receives the document from a developer at build time, and no vendor documents a named agent that discovers a spec by probing a site root. The discovery leg this audit actually measures is convention, not proven behavior.

    Sources