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

    OpenAPI servers array valid

    What it checks

    Without a servers array, AI agents do not know the base URL for your API. They cannot construct valid request URLs, rendering the entire spec unusable. Add at least your production server URL.

    Why it matters

    An agent runtime builds each request URL by joining a servers[].url entry with the operation path, so a spec whose servers entries yield no resolvable base URL produces requests the agent cannot address.

    Evidence

    • OpenAI GPT Actions schemas declare the API location in the servers array (servers: - url: https://api.weather.gov), which is where the built action sends its calls — developers.openai.com/…/getting-started (verified 2026-08-21)
    • Microsoft 365 Copilot treats the servers section as the domains an API plugin declares. “The Copilot runtime … doesn’t evaluate it against any domains the plugin declares (such as the servers section of an API plugin’s OpenAPI description)” — learn.microsoft.com/…/overview-api-plugins (verified 2026-08-21)
    • OpenAPI 3.1 Server Object defines url as the base URL for the API, supports relative URLs and {variable} templating with variables defaults — spec.openapis.org/…/v3.1.0.html (verified 2026-08-21)

    Limits

    Strong, on the half of the signal the code actually weights. OpenAPI 3.1 states: “If the servers property is not provided, or is an empty array, the default value would be a Server Object with a url value of /.” An absent servers array is therefore legal, and resolvable against the document’s own location. It is not the fatal condition the audit’s copy claims. No vendor documentation treats a bare GET on the base URL as a validity test. 401, 403, 404 and 405 are ordinary healthy responses at an API root.

    Templated server URLs such as https://{region}.api.example.com, and relative ones such as /api, are legal forms that cannot be fetched literally. The reachability leg of this signal is therefore unsupported; only the structural leg (a parseable base URL is declared or derivable) carries the B.

    How it scores

    That agents resolve requests against the declared server URL is documented at named consumers. But the specification supplies a legal default, /, when the array is absent. The liveness probe this audit performs has no documented consumer at all.

    Example failure

    A site publishes /openapi.json describing three endpoints and omits the servers array, or lists one whose only entry has a description and no url. An agent has the operations but no base URL to join them to, so it cannot address a single request.

    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.

    Sources