OpenAPI description — agent readiness

Why an agent cares

It is the difference between an agent guessing at an API and calling it correctly first time. Most of what we flag is optional per the spec and load-bearing for an agent, such as a missing operationId or an absent server URL.

Adoption

Web baseline. Standard equipment on the web. Its absence is the exception rather than its presence. For this one in particular, the format is settled, but whether a site publishes its contract at all varies.

Direction of travel: ► flat, as at 2026-07-28.

The de facto standard for describing REST APIs. The variable is not adoption but whether the contract is served publicly.

What we check

Absence is never a finding. Every check below runs only when this technology is detected, so a site that has not adopted this is not assessed on it and appears in no report. 10 of these 12 can fail it. In Lumar these appear once per site, in the site-wide results of each crawl.

Check	Severity	Raises	On whose authority
OpenAPI Invalid Document	high	usability	Lumar readiness bar, beyond OpenAPI Specification
Supporting documents: OpenAPI Specification Lumar readiness bar: no specification requires this. Bad: something is served at an OpenAPI path but isn't a usable contract: malformed JSON, or a document declaring no callable operation. Fix: serve a valid OpenAPI 3.x JSON document with at least one path operation.
OpenAPI Insecure OAuth URL	high	usability, security (CWE-319)	specification: OpenAPI Specification, The OAuth 2.0 Authorization Framework, OpenID Connect Discovery 1.0
Supporting documents: OpenAPI Specification, The OAuth 2.0 Authorization Framework, OpenID Connect Discovery 1.0 Related guidance in OpenAPI Specification, The OAuth 2.0 Authorization Framework and OpenID Connect Discovery 1.0. Provisional security check; precision has not yet been measured. Bad: an OAuth or OpenID Connect URL in the security schemes (authorization, token, refresh, metadata or discovery) uses plain http://, so credentials and tokens travel unencrypted; OAuth requires TLS. Fix: change each to its https:// address, e.g. "tokenUrl": "https://auth.example.com/token". An advertised HTTP destination permits unencrypted communication. OWASP API API8 (2023) — Security Misconfiguration ASVS V12.2.1 (5.0.0) — TLS for external HTTP services Only advertised transport configuration is observed; API deployment security is not fully assessed. Related guidance does not establish exploitation or framework compliance. Security checks are provisional.
OpenAPI Deprecated OAuth Flow	high	usability, security (CWE-522)	specification: Best Current Practice for OAuth 2.0 Security
Supporting documents: Best Current Practice for OAuth 2.0 Security Client guidance in Best Current Practice for OAuth 2.0 Security. Provisional security check; precision has not yet been measured. Bad: a security scheme offers the implicit or password OAuth flow, which current OAuth security guidance forbids (password) or advises against (implicit) because they expose the user's password or the access token. Fix: offer authorizationCode with PKCE instead. The advertised authentication configuration weakens identity protection. OWASP API API2 (2023) — Broken Authentication ASVS V10.4.4 (5.0.0) — Exclude implicit and password grants No authenticated transaction or bypass is attempted. Related guidance does not establish exploitation or framework compliance. Security checks are provisional.
OpenAPI Internal Endpoint	medium	usability, security (CWE-200)	Lumar readiness bar
Public discovery metadata reveals internal service addresses. OWASP API API8 (2023) — Security Misconfiguration Reachability, authorization and SSRF exploitation are not tested. Related guidance does not establish exploitation or framework compliance. Security checks are provisional.
OpenAPI Invalid Version	medium	usability	Lumar readiness bar, beyond OpenAPI Specification
Supporting documents: OpenAPI Specification Lumar readiness bar: no specification requires this. Bad: the "openapi" field isn't a 3.x version (Swagger 2.0, a 4.x value, or garbage), so modern agent tooling can't consume it. Fix: migrate the document to OpenAPI 3.x, e.g. "openapi": "3.1.0".
OpenAPI Missing operationId	medium	usability	Lumar readiness bar, beyond OpenAPI Specification
Supporting documents: OpenAPI Specification Lumar readiness bar: no specification requires this. Bad: an operation has no operationId, which agents rely on to name and call the generated tool (optional per spec, required in practice for tool generation). Fix: add a unique operationId to every operation, e.g. "operationId": "getPetById".
OpenAPI Undescribed Operation	medium	usability	Lumar readiness bar, beyond OpenAPI Specification
Supporting documents: OpenAPI Specification Lumar readiness bar: no specification requires this. Bad: an operation carries neither a summary nor a description, so the tool an agent builds from it has no explanation of what it does or when to call it. Fix: give every operation a one-line summary, e.g. "summary": "List the pets in the catalog".
OpenAPI Duplicate operationId	medium	conformance, usability	specification: OpenAPI Specification
Supporting documents: OpenAPI Specification Required by OpenAPI Specification. Bad: two operations share one operationId; the spec requires uniqueness, and a collision makes tool calls ambiguous. Fix: rename so every operation's id is unique.
OpenAPI Insecure Server URL	medium	usability, security (CWE-319)	Lumar readiness bar, beyond OpenAPI Specification
Supporting documents: OpenAPI Specification Lumar readiness bar: no specification requires this. Provisional security check; precision has not yet been measured. Bad: the document lists a public API server on plain http://, so every request an agent sends there, and the response, travels unencrypted, along with any credential the API asks for. A Lumar bar: OpenAPI itself allows it. Fix: serve the API over https and list "url": "https://api.example.com". An advertised HTTP destination permits unencrypted communication. OWASP API API8 (2023) — Security Misconfiguration ASVS V12.2.1 (5.0.0) — TLS for external HTTP services Only advertised transport configuration is observed; API deployment security is not fully assessed. Related guidance does not establish exploitation or framework compliance. Security checks are provisional.
OpenAPI Untyped Schema	medium	usability	Lumar readiness bar, beyond OpenAPI Specification
Supporting documents: OpenAPI Specification Lumar readiness bar: no specification requires this. Bad: a request body has no usable typed schema (missing, or with no type/$ref/properties at all), so an agent cannot tell what to send. Untyped responses are not counted, since an agent can read JSON it was not told the shape of. Fix: give every request body a real JSON Schema (type, properties, required).
OpenAPI Unresolved Reference	informational	nothing	specification: OpenAPI Specification
Supporting documents: OpenAPI Specification OpenAPI Specification permits this, so it never fails the site. Informational (does not affect openApiValid): a Path Item, Request Body, or Response is a $ref this check doesn't dereference, so the assessment is partial. Consider inlining critical schemas or exposing a fully resolved document.
OpenAPI Partially Assessed	coverage note	nothing	our own coverage

Examples

Both run through the same checks as a live scan: the first passes, the second is flagged.

correctjson

{
  "openapi": "3.1.0",
  "info": { "title": "Example Catalog API", "version": "1.0.0" },
  "servers": [{ "url": "https://api.example.com/v1" }],
  "paths": {
    "/pets": {
      "get": {
        "operationId": "listPets",
        "summary": "List the pets in the catalog",
        "responses": {
          "200": {
            "description": "A list of pets",
            "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } }
          }
        }
      },
      "post": {
        "operationId": "createPet",
        "summary": "Add a pet to the catalog",
        "requestBody": {
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pet" } } }
        },
        "responses": {
          "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object" } } } }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "petsOAuth": {
        "type": "oauth2",
        "flows": { "authorizationCode": { "authorizationUrl": "https://auth.example.com/authorize", "tokenUrl": "https://auth.example.com/token", "scopes": {} } }
      }
    }
  }
}

present but wrongjson

{
  "openapi": "3.1.0",
  "info": { "title": "Broken Catalog API", "version": "1.0.0" },
  "servers": [{ "url": "http://api.example.com/v1" }],
  "security": [{ "legacyOAuth": [] }],
  "paths": {
    "/pets": {
      "get": {
        "responses": {
          "200": {
            "description": "A list of pets",
            "content": { "application/json": { "schema": {} } }
          }
        }
      },
      "post": {
        "requestBody": { "content": { "application/json": { "schema": {} } } },
        "responses": { "201": { "description": "Created" } }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "legacyOAuth": {
        "type": "oauth2",
        "flows": { "password": { "tokenUrl": "http://auth.example.com/token", "scopes": {} } }
      }
    }
  }
}

Specifications

Document	Revision	Kind
OpenAPI Specification	Version 3.2.1 (any 3.x accepted)	specification
RFC 6749 — The OAuth 2.0 Authorization Framework	Published RFC	specification
RFC 9700 — Best Current Practice for OAuth 2.0 Security	Published RFC	specification
OpenID Connect Discovery 1.0	Version 1.0	specification

Last re-read against the published documents: 2026-10-05.