agentic‑readiness docs
/
Scan at scale Blog Build one › Run a scan ›
Menu

Scan at scaleSites with an invalid OpenAPI contract

Sites with an invalid OpenAPI contract

A site-wide report: one row per host, over the openapi rows the crawl emitted.

What this report returns

An OpenAPI contract describes a site's API in a form agents can turn directly into tool calls.

A row appears here when any of these is wrong, worst first:

  • Invalid DocumentSomething 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.
  • Insecure OAuth URLAn 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".
  • Deprecated OAuth FlowA 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.
  • Invalid VersionThe "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".
  • Missing operationIdAn 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".
  • Undescribed OperationAn 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".
  • Duplicate operationIdTwo operations share one operationId; the spec requires uniqueness, and a collision makes tool calls ambiguous.Fix Rename so every operation's id is unique.
  • Insecure Server URLThe 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".
  • Untyped SchemaA 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).

The Conformance Issue Detected column says whether the contract actually breaks the specification, and on most of these rows it is false: only a reused operationId violates OpenAPI 3.2, which requires every operationId to be unique, while a missing operationId, a missing summary or an untyped body is conformant but leaves agents guessing, so it is part of Lumar's readiness bar.

A version outside 3.x makes no conformance claim either way, because this single flag cannot tell a conformant OAS 2.0 document apart from a malformed or nonexistent version.

Security checks are provisional; precision has not yet been measured. A clean row is not a security assessment.

The columns it shows

Every defect this technology can carry is a column in the grid, worst first, so nothing is hidden behind a filter you have to know to apply.

  • Hosthost
  • OpenAPI ValidopenApiValid
  • OpenAPI Conformance Issue DetectedopenApiConformanceIssueDetected
  • OpenAPI Security Risk DetectedopenApiSecurityRiskDetected
  • OpenAPI FindingsopenApiFindings
  • OpenAPI Declared VersionopenApiDeclaredVersion
  • OpenAPI Operation CountopenApiOperationCount
  • OpenAPI Duplicate operationId SamplesopenApiDuplicateOperationIdSamples
  • OpenAPI Invalid DocumentopenApiInvalidDocument
  • OpenAPI Insecure OAuth URLopenApiInsecureOAuthUrl
  • OpenAPI Deprecated OAuth FlowopenApiDeprecatedOAuthFlow
  • OpenAPI Internal EndpointopenApiInternalEndpoint
  • OpenAPI Invalid VersionopenApiInvalidVersion
  • OpenAPI Missing operationIdopenApiMissingOperationId
  • OpenAPI Undescribed OperationopenApiUndescribedOperation
  • OpenAPI Duplicate operationIdopenApiDuplicateOperationId
  • OpenAPI Insecure Server URLopenApiInsecureServerUrl
  • OpenAPI Untyped SchemaopenApiUntypedSchema
  • OpenAPI Unresolved ReferenceopenApiUnresolvedReference
  • Ruleset VersionrulesetVersion
  • Security Check StatussecurityCheckStatus
  • Related Security FrameworkssecurityFrameworkReferences

About OpenAPI description

A machine-readable contract for the site's API.

Read how OpenAPI description is checked, including the specification it is validated against and a worked correct and broken example.

Running it

This report comes with Agentic Readiness in Lumar and appears on every crawl of any project that has it turned on. See the whole set, or check a single URL with the scanner on this site, which runs the same code with no account.

Get Lumar pricing