Audit contracts
over HTTP.

Overview

Send the complete OpenAPI document as a string in the specification property. JSON and YAML contracts using OpenAPI 3.0 or 3.1 are accepted.

The playground can import a direct public HTTPS specification URL in your browser. URL fetching is not part of the HTTP API; imported documents are still submitted as text.

Free score

curl -X POST https://www.readinessapi.com/v1/openapi/score \
  -H 'content-type: application/json' \
  --data '{"specification":"openapi: 3.1.0\ninfo: ..."}'

{
  "score": 47,
  "classification": "needs_work",
  "metrics": {
    "structural_validity": 87,
    "operation_clarity": 31,
    "input_schema_quality": 71,
    "output_schema_quality": 58,
    "error_model_quality": 0,
    "agent_safety": 0
  },
  "top_findings": [/* up to five finding previews */],
  "rules_version": "2026-07-17.2"
}

Rate limits are 10 requests per minute and 100 requests per day for each pseudonymized client address.

Paid audit

Without a payment signature, the route responds with HTTP 402 and advertises an exact USDC payment on Base Sepolia.

import { wrapFetchWithPayment, x402Client } from "@x402/fetch";
import { registerExactEvmScheme } from "@x402/evm/exact/client";
import {
  appendPaymentIdentifierToExtensions,
  generatePaymentId,
} from "@x402/extensions/payment-identifier";
import { privateKeyToAccount } from "viem/accounts";

// Run server-side only. Never expose a wallet private key in browser code.
const client = new x402Client();
registerExactEvmScheme(client, {
  signer: privateKeyToAccount(process.env.EVM_PRIVATE_KEY),
});

const paymentId = generatePaymentId();
client.onBeforePaymentCreation(async ({ paymentRequired }) => {
  appendPaymentIdentifierToExtensions(
    paymentRequired.extensions ?? {},
    paymentId,
  );
});

const fetchWithPayment = wrapFetchWithPayment(fetch, client);
const response = await fetchWithPayment(
  "https://www.readinessapi.com/v1/openapi/audit",
  {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify({ specification }),
  },
);

if (!response.ok) throw new Error(`Audit failed: ${response.status}`);
const audit = await response.json();

Keep this server-side. Do not ship an EVM private key in frontend JavaScript. An identical retry is replay-safe for 24 hours; reusing the identifier with a different body returns HTTP 409.

{
  "score": 47,
  "classification": "needs_work",
  "findings": [/* every finding with exact JSON Pointer */],
  "patches": [/* reviewed RFC 6902 patch groups */],
  "mcp": { "bundles": [], "excluded_operations": [] },
  "integrity": {
    "raw_input_sha256": "…",
    "semantic_input_sha256": "…",
    "audit_result_sha256": "…",
    "rules_version": "2026-07-17.2"
  }
}

Audit options

• includeJsonPatch — defaults to true.
• includeMcpTools — defaults to true.
• includeOperationIds — selects exact operation IDs and explicitly permits selected mutation operations.

Limits & privacy

• 4 MiB and 500-operation application limits, plus bounded nesting, nodes, strings, references, compositions, findings, patches, and MCP output.
• Browser URL imports require a direct public HTTPS file, omit credentials, time out after ten seconds, and depend on the source site's CORS policy.
• 50 YAML aliases and a 20-second processing deadline.
• The audit server performs no outbound contract dereferencing.
• Raw specifications are processed in memory and not intentionally persisted or written to application logs.
• Paid derived reports and hashed idempotency keys expire after 24 hours. Reports can include schemas and fragments derived from the submitted contract.

See the user-readable Privacy data lifecycle before submitting a sensitive contract.

Errors

Every application error uses { error: { code, message, request_id, details? } }. Common statuses are 400, 402, 409, 413, 415, 422, 429, and 503.

Use the request ID when correlating a failure with operational telemetry. Error details contain locations and validation issues, never submitted secret values.

Beta status endpoints

Operational clients can check /healthz for process health and /readyz for dependency readiness. These endpoints are intended for monitoring, not product navigation.