# 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 Document**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. - **Insecure OAuth URL**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"`. - **Deprecated OAuth Flow**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. - **Invalid Version**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"`. - **Missing operationId**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"`. - **Undescribed Operation**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"`. - **Duplicate operationId**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. - **Insecure Server URL**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"`. - **Untyped Schema**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). 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. - Host`host` - OpenAPI Valid`openApiValid` - OpenAPI Conformance Issue Detected`openApiConformanceIssueDetected` - OpenAPI Security Risk Detected`openApiSecurityRiskDetected` - OpenAPI Findings`openApiFindings` - OpenAPI Declared Version`openApiDeclaredVersion` - OpenAPI Operation Count`openApiOperationCount` - OpenAPI Duplicate operationId Samples`openApiDuplicateOperationIdSamples` - OpenAPI Invalid Document`openApiInvalidDocument` - OpenAPI Insecure OAuth URL`openApiInsecureOAuthUrl` - OpenAPI Deprecated OAuth Flow`openApiDeprecatedOAuthFlow` - OpenAPI Internal Endpoint`openApiInternalEndpoint` - OpenAPI Invalid Version`openApiInvalidVersion` - OpenAPI Missing operationId`openApiMissingOperationId` - OpenAPI Undescribed Operation`openApiUndescribedOperation` - OpenAPI Duplicate operationId`openApiDuplicateOperationId` - OpenAPI Insecure Server URL`openApiInsecureServerUrl` - OpenAPI Untyped Schema`openApiUntypedSchema` - OpenAPI Unresolved Reference`openApiUnresolvedReference` - Ruleset Version`rulesetVersion` - Security Check Status`securityCheckStatus` - Related Security Frameworks`securityFrameworkReferences` ## About OpenAPI description A machine-readable contract for the site's API. [Read how OpenAPI description is checked](https://agentic-readiness.lumar.io/docs/capabilities/open-api), 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](https://agentic-readiness.lumar.io/scan-at-scale), or check a single URL with the [scanner on this site](https://agentic-readiness.lumar.io/), which runs the same code with no account. [Get Lumar pricing →](https://www.lumar.io/pricing/)