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-endpoints

    OpenAPI has endpoints

    What it checks

    An OpenAPI spec without endpoints is like a menu with no items. AI agents need at least one path with an operation to know what actions they can perform on your site. Add your most important endpoints first.

    Why it matters

    A tool-calling runtime creates one callable function per OpenAPI path operation, so a document whose paths object contains no operations exposes zero actions to the agent that ingests it.

    Evidence

    • Microsoft 365 Copilot builds one function per operation, then selects among them by path description. “Operation IDs are unique identifiers for an operation in the API and are used by Copilot to create functions that are executed when responding to a user’s prompt.” The document continues: “it searches through the descriptions of the paths to determine the endpoint to use to satisfy the user’s request” — learn.microsoft.com/…/openapi-document-guidance (verified 2026-08-21)
    • OpenAI GPT Actions expose the schema’s operations as the actions ChatGPT may invoke: “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)
    • The Path Item / Operation Object is the unit of the described API surface in OpenAPI 3.1 — spec.openapis.org/…/v3.1.0.html (verified 2026-08-21)

    Limits

    The measured state is close to unobservable in the wild. A published spec with a paths object but no operation objects is rare. No adoption or effect data distinguishes passing from failing here, beyond what 5.1 already establishes. OpenAPI 3.1 also lets a document declare its surface through webhooks or $ref-ed path items, so “zero operations” as this audit counts them does not always mean zero agent-callable actions.

    How it scores

    The operation-to-function conversion is documented consumer behavior at two named agents, but the path is only proven once a developer registers the document, and the audit’s own discovery leg is the C-grade claim recorded in 5.1.

    Example failure

    A site publishes /openapi.json carrying info, components and an empty paths object. An agent reads a valid document and finds zero actions it can take.

    A site that publishes no OpenAPI document at all is not a failure here. This audit judges a document’s contents; with no document, it returns “not applicable” and takes no weight off the score.

    A document whose paths is present and yields nothing readable fails too, and the report names the defect. "paths": ["get","post"] puts a string where a path item belongs; {"/x": {"get": "yes"}} puts one where an operation belongs. Absent means absent; present-and-broken is a finding.

    One broken entry does not erase the operations beside it. A document with twenty working operations and one null path item passes on its twenty, and the skipped entry is named in the report. A path item that is legal and declares nothing — {"/x": {}} — is an empty document, not a broken one.

    Sources