OpenAPI spec audit

Lint an OpenAPI spec and validate a sample payload against it - catch schema errors in one pass.

When to use this pack

A developer has an OpenAPI spec URL and wants a quick quality check: does it lint cleanly (missing descriptions, unused schemas, invalid refs) and does a sample payload pass validation? Useful before publishing to a marketplace or generating client SDKs.

Tools in this pack

All 3 run inside the single $0.004 call above. Each is also callable on its own if you only need one part.

• OpenAPI agent-readiness lint POST /api/openapi-lint Score an OpenAPI 3.x or Swagger 2.x spec on agent-readiness - i.e. does an LLM-driven caller have what it needs to call the API correctly without guessing. Returns a 0..100 score, severity counts, and a structured list of violations with stable rule codes. Checks: documented title/servers/paths, per-operation summary/description/operationId/tags, documented 2xx + error responses, param descriptions/schemas/examples, response descriptions, JSON response schemas. Pure CPU - deterministic, no network, no $ref dereferencing.
• OpenAPI payload validator POST /api/openapi-validate-payload Validate a JSON payload against the request or response schema for one operation in an OpenAPI 3.x or Swagger 2.x spec. Locate the operation by operationId or method+path; choose `part: "request"` or `part: "response"` (status defaults to the first 2xx). Deterministic subset of JSON Schema: type, required, enum, properties, items, additionalProperties:false, oneOf/anyOf/allOf, $ref-detection (not dereferenced). Returns `valid`, `schemaPresent` (false → no contract to check; result is vacuously valid), and ordered `errors[]` with stable rule codes. Pure CPU - deterministic, no network.
• OpenAPI security summary POST /api/openapi-security-summary Resolve authentication requirements across an OpenAPI 3.x or Swagger 2.x document. Returns the catalog of security schemes (`components.securitySchemes` in OpenAPI 3, `securityDefinitions` in Swagger 2) verbatim, the document-level default, and the *effective* security for each operation after layering. Honors the OpenAPI rule that `security: []` on an operation overrides the global default with "explicitly open" rather than inheriting it - so an agent sees `open: true` for that op and won't try to attach a token. Includes a `schemeUsage` count so callers know which scheme is actually needed. Operations are sorted `METHOD /path` for deterministic output. Pure CPU - deterministic, no network.

Bought one at a time, these 3 tools cost $0.004 together; the pack is that sum less a 10% bundle discount, rounded up to the $0.001 settlement floor, which is $0.004.

Workflow

1. Call openapi-lint with the spec URL to get lint warnings and errors - missing descriptions, unused schemas, invalid references.
2. Call openapi-validate-payload with an empty payload to surface required-field violations and schema mismatches.
3. Call openapi-security-summary to map the spec's auth posture - which security schemes are declared, which operations require them, and which are left unprotected. A clean lint on an endpoint that forgot its auth requirement is the audit finding that matters most.

Arguments

What one call returns

A JSON object with pack, args, steps, summary; steps holds one entry per tool (openapi-lint, openapi-validate-payload, openapi-security-summary), each with its own result or error. Full example on the API page.

Call it directly

Any x402 client pays the 402 and gets the whole workflow back in one response. With the agent402-client SDK (npm i agent402-client, an ES module):

import { Agent402 } from "agent402-client";
// payFetch: an x402-wrapped fetch your wallet signs (@x402/fetch).
// Tools on the free tier need no options: new Agent402() pays them by proof-of-work.
// an existing prepaid credits key also works: new Agent402({ creditsKey })
const client = new Agent402({ fetch: payFetch });
const result = await client.call("skill-openapi-audit", {"url":"https://petstore3.swagger.io/api/v3/openapi.json"});

Run it in Claude

claude mcp add agent402 -s user -- npx -y agent402-mcp@latest

Then paste this prompt into Claude:

Audit the OpenAPI spec at https://petstore3.swagger.io/api/v3/openapi.json using Agent402's openapi-audit skill pack: (1) lint it for warnings and errors, (2) validate an empty payload against the first endpoint, (3) summarize the security posture with openapi-security-summary. Report lint issues, validation failures, and any unprotected operations.

← All skill packs