{"openapi": "3.1.0", "info": {"title": "NumProof", "version": "0.2.22", "description": "Deterministic verification of numeric & financial claims for AI agents and spreadsheets \u2014 VERIFY/REFUTE/ABSTAIN with provenance and signed, offline-re-checkable receipts. Audits, covenant checks, and report-version diffs included."}, "servers": [{"url": "https://numproof.com"}], "components": {"securitySchemes": {"ApiKeyBearer": {"type": "http", "scheme": "bearer", "bearerFormat": "vk_*"}}, "schemas": {"Error": {"type": "object", "properties": {"error": {"type": "string"}}, "additionalProperties": true}, "AnyBundle": {"type": "object", "additionalProperties": true}, "Rows": {"type": "array", "items": {"type": "array", "items": {}}}}}, "paths": {"/verify": {"post": {"summary": "Verify one numeric claim", "security": [{"ApiKeyBearer": []}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"claim": {"type": "string"}, "allow_llm": {"type": "boolean", "default": false, "description": "Opt in to Gemini fallback when rule-based parsing cannot formalize the claim. Paid endpoints are deterministic-by-default."}, "webhook_url": {"type": "string", "format": "uri", "description": "Optional API-key-only HTTPS callback URL. Private, loopback, link-local, metadata, and non-HTTPS targets are rejected before billing."}}, "required": ["claim"]}}}}, "responses": {"200": {"description": "Verification result"}, "402": {"description": "Payment required", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}}, "additionalProperties": true}}}}}}}, "/verify/batch": {"post": {"summary": "Verify multiple claim strings", "security": [{"ApiKeyBearer": []}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"claims": {"type": "array", "items": {"type": "string"}}, "allow_llm": {"type": "boolean", "default": false, "description": "Opt in to Gemini fallback. Default false for CI/paid safety."}, "webhook_url": {"type": "string", "format": "uri", "description": "Optional API-key-only HTTPS callback URL. Private, loopback, link-local, metadata, and non-HTTPS targets are rejected before billing."}}, "required": ["claims"]}}}}, "responses": {"200": {"description": "Batch result"}, "402": {"description": "Payment required", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}}, "additionalProperties": true}}}}}}}, "/verify/proof": {"post": {"summary": "Create a premium Lean proof artifact for one claim", "security": [{"ApiKeyBearer": []}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"claim": {"type": "string"}, "allow_llm": {"type": "boolean", "default": false, "description": "Opt in to Gemini fallback before Lean proof generation. Default false for proof safety."}, "webhook_url": {"type": "string", "format": "uri", "description": "Optional API-key-only HTTPS callback URL. Private, loopback, link-local, metadata, and non-HTTPS targets are rejected before billing."}}, "required": ["claim"]}}}}, "responses": {"200": {"description": "Lean proof result"}, "402": {"description": "Payment required", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}}, "additionalProperties": true}}}}}}}, "/verify/audit": {"post": {"summary": "Create signed spreadsheet audit bundle", "security": [{"ApiKeyBearer": []}], "parameters": [{"name": "format", "in": "query", "required": false, "schema": {"type": "string", "enum": ["json", "html", "pdf", "zip", "package"]}, "description": "Use html or pdf for human-readable audit reports with a public /audit/verify verifier hint; use zip/package for signed JSON plus a human report in one charged response. JSON is the default."}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"rows": {"$ref": "#/components/schemas/Rows"}, "ratio_tolerance": {"type": "string"}, "subtotal_tolerance": {"type": "string"}, "webhook_url": {"type": "string", "format": "uri", "description": "Optional API-key-only HTTPS callback URL. Private, loopback, link-local, metadata, and non-HTTPS targets are rejected before billing."}}, "required": ["rows"]}}}}, "responses": {"200": {"description": "Audit bundle, human-readable report, or artifact package", "content": {"application/json": {"schema": {"type": "object", "additionalProperties": true}}, "text/html": {"schema": {"type": "string"}}, "application/pdf": {"schema": {"type": "string", "format": "binary"}}, "application/zip": {"schema": {"type": "string", "format": "binary"}}}}, "402": {"description": "Payment required", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}}, "additionalProperties": true}}}}}}}, "/verify/diff": {"post": {"summary": "Create signed report-version diff bundle", "security": [{"ApiKeyBearer": []}], "parameters": [{"name": "format", "in": "query", "required": false, "schema": {"type": "string", "enum": ["json", "html", "pdf", "zip", "package"]}, "description": "Use html or pdf for human-readable report diffs with a public /audit/verify verifier hint; use zip/package for signed JSON plus a human report in one charged response. JSON is the default."}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"rows_before": {"$ref": "#/components/schemas/Rows"}, "rows_after": {"$ref": "#/components/schemas/Rows"}, "materiality_tolerance": {"type": "string"}, "webhook_url": {"type": "string", "format": "uri", "description": "Optional API-key-only HTTPS callback URL. Private, loopback, link-local, metadata, and non-HTTPS targets are rejected before billing."}}, "required": ["rows_before", "rows_after"]}}}}, "responses": {"200": {"description": "Diff bundle, human-readable report, or artifact package", "content": {"application/json": {"schema": {"type": "object", "additionalProperties": true}}, "text/html": {"schema": {"type": "string"}}, "application/pdf": {"schema": {"type": "string", "format": "binary"}}, "application/zip": {"schema": {"type": "string", "format": "binary"}}}}, "402": {"description": "Payment required", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}}, "additionalProperties": true}}}}}}}, "/verify/covenants": {"post": {"summary": "Evaluate signed covenant/threshold rule pack", "security": [{"ApiKeyBearer": []}], "parameters": [{"name": "format", "in": "query", "required": false, "schema": {"type": "string", "enum": ["json", "html", "pdf", "zip", "package"]}, "description": "Use html or pdf for human-readable covenant reports with a public /audit/verify verifier hint; use zip/package for signed JSON plus a human report in one charged response. JSON is the default."}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"rows": {"$ref": "#/components/schemas/Rows"}, "rules": {"type": "array", "items": {"type": "object", "additionalProperties": true}, "description": "Rules such as {'name':'DSCR','numerator':'EBITDA','denominator':'Debt Service','op':'>=','threshold':'1.25'} or {'metric':'debt_to_ebitda','op':'<=','threshold':'3.0'}"}, "rule_pack": {"type": "string", "description": "Optional built-in template id from GET /rule-packs, e.g. credit_covenants_basic. Used when rules is omitted."}, "webhook_url": {"type": "string", "format": "uri", "description": "Optional API-key-only HTTPS callback URL. Private, loopback, link-local, metadata, and non-HTTPS targets are rejected before billing."}}, "required": ["rows"]}}}}, "responses": {"200": {"description": "Covenant bundle, human-readable report, or artifact package", "content": {"application/json": {"schema": {"type": "object", "additionalProperties": true}}, "text/html": {"schema": {"type": "string"}}, "application/pdf": {"schema": {"type": "string", "format": "binary"}}, "application/zip": {"schema": {"type": "string", "format": "binary"}}}}, "402": {"description": "Payment required", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}}, "additionalProperties": true}}}}}}}, "/rule-packs": {"get": {"summary": "List built-in covenant/threshold rule-pack templates", "responses": {"200": {"description": "Editable starter rule-pack templates", "content": {"application/json": {"schema": {"type": "object", "additionalProperties": true}}}}}}}, "/finance": {"get": {"summary": "Finance workflow page with sample covenant pack", "parameters": [{"name": "source", "in": "query", "required": false, "schema": {"type": "string"}, "description": "Privacy-safe acquisition source token; utm_source is also accepted."}, {"name": "campaign", "in": "query", "required": false, "schema": {"type": "string"}, "description": "Privacy-safe campaign token; utm_campaign is also accepted."}, {"name": "plan", "in": "query", "required": false, "schema": {"type": "string"}, "description": "Optional plan-interest token for aggregate funnel reporting."}], "responses": {"200": {"description": "HTML finance workflow page"}}}}, "/sample/finance-covenants": {"get": {"summary": "Return a public signed sample covenant bundle or report", "parameters": [{"name": "format", "in": "query", "required": false, "schema": {"type": "string", "enum": ["json", "html", "pdf"]}, "description": "Use html or pdf for a human-readable finance sample with a public /audit/verify verifier hint; JSON is the default."}], "responses": {"200": {"description": "Sample signed covenant bundle or report", "content": {"application/json": {"schema": {"type": "object", "additionalProperties": true}}, "text/html": {"schema": {"type": "string"}}, "application/pdf": {"schema": {"type": "string", "format": "binary"}}}}}}}, "/audit/verify": {"get": {"summary": "Browser page for verifying signed audit, diff, or covenant bundles", "responses": {"200": {"description": "HTML bundle signature verifier"}}}, "post": {"summary": "Verify an audit, diff, or covenant bundle signature", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"audit": {"type": "object", "additionalProperties": true}}, "required": ["audit"]}}}}, "responses": {"200": {"description": "Signature verification result"}}}}, "/feedback/dispute": {"post": {"summary": "Report a disputed verdict without sending raw claim text", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"endpoint": {"type": "string"}, "verdict": {"type": "string"}, "reason": {"type": "string", "enum": ["correctness", "translation", "source_data", "performance", "billing", "other"]}, "claim": {"type": "string", "description": "Optional; only a SHA-256 hash is retained in aggregate counters"}, "bundle_sha256": {"type": "string"}}}}}}, "responses": {"200": {"description": "Feedback counted"}, "400": {"description": "Invalid feedback", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}}, "additionalProperties": true}}}}, "429": {"description": "Rate limit", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}}, "additionalProperties": true}}}}}}}, "/feedback/support": {"post": {"summary": "Count a support request category for aggregate support KPI", "requestBody": {"required": false, "content": {"application/json": {"schema": {"type": "object", "properties": {"reason": {"type": "string", "enum": ["billing", "integration", "correctness", "account", "performance", "other"]}}}}}}, "responses": {"200": {"description": "Support request counted"}, "429": {"description": "Rate limit", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}}, "additionalProperties": true}}}}}}}, "/pilot": {"get": {"summary": "Finance pilot intake page", "parameters": [{"name": "source", "in": "query", "required": false, "schema": {"type": "string"}, "description": "Privacy-safe acquisition source token; utm_source is also accepted."}, {"name": "campaign", "in": "query", "required": false, "schema": {"type": "string"}, "description": "Privacy-safe campaign token; utm_campaign is also accepted."}, {"name": "plan", "in": "query", "required": false, "schema": {"type": "string"}, "description": "Optional plan-interest token for aggregate funnel reporting."}], "responses": {"200": {"description": "HTML pilot intake form"}}}, "post": {"summary": "Record a voluntary finance pilot lead", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"email": {"type": "string", "format": "email"}, "company": {"type": "string"}, "role": {"type": "string"}, "plan": {"type": "string"}, "campaign": {"type": "string"}, "rule_pack": {"type": "string"}, "use_case": {"type": "string"}, "message": {"type": "string"}, "source": {"type": "string"}, "consent": {"type": "boolean"}}, "required": ["email", "consent"]}}}}, "responses": {"200": {"description": "Lead recorded without returning raw contact data"}, "400": {"description": "Invalid lead", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}}, "additionalProperties": true}}}}, "429": {"description": "Rate limit", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}}, "additionalProperties": true}}}}}}}, "/start": {"get": {"summary": "Self-serve API key onboarding page", "parameters": [{"name": "source", "in": "query", "required": false, "schema": {"type": "string"}, "description": "Privacy-safe acquisition source token; utm_source is also accepted."}, {"name": "campaign", "in": "query", "required": false, "schema": {"type": "string"}, "description": "Privacy-safe campaign token; utm_campaign is also accepted."}, {"name": "plan", "in": "query", "required": false, "schema": {"type": "string"}, "description": "Optional plan-interest token for aggregate funnel reporting."}], "responses": {"200": {"description": "HTML signup/onboarding page"}}}}, "/workbench": {"get": {"summary": "Browser API-key workbench with inline trial signup, top-up, and downloadable paid CSV/TSV reports", "parameters": [{"name": "source", "in": "query", "required": false, "schema": {"type": "string"}, "description": "Privacy-safe acquisition source token; utm_source is also accepted."}, {"name": "campaign", "in": "query", "required": false, "schema": {"type": "string"}, "description": "Privacy-safe campaign token; utm_campaign is also accepted."}, {"name": "plan", "in": "query", "required": false, "schema": {"type": "string"}, "description": "Optional plan-interest token for aggregate funnel reporting."}], "responses": {"200": {"description": "HTML API-key workbench with inline trial key minting, top-up register/claim controls, CSV/TSV audit, diff, and covenant runners, and downloadable signed outputs"}}}}, "/signup": {"post": {"summary": "Create a trial API key", "requestBody": {"content": {"application/json": {"schema": {"type": "object", "properties": {"email": {"type": "string", "format": "email"}, "source": {"type": "string"}, "campaign": {"type": "string"}, "plan": {"type": "string"}}}}}}, "responses": {"200": {"description": "API key and top-up instructions"}, "429": {"description": "Trial limit reached", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}}, "additionalProperties": true}}}}}}}, "/topup": {"get": {"summary": "Self-serve API-key credit top-up page", "parameters": [{"name": "source", "in": "query", "required": false, "schema": {"type": "string"}, "description": "Privacy-safe acquisition source token; utm_source is also accepted."}, {"name": "campaign", "in": "query", "required": false, "schema": {"type": "string"}, "description": "Privacy-safe campaign token; utm_campaign is also accepted."}, {"name": "plan", "in": "query", "required": false, "schema": {"type": "string"}, "description": "Optional plan-interest token for aggregate funnel reporting."}], "responses": {"200": {"description": "HTML top-up page"}}}}, "/topup/register": {"post": {"summary": "Bind a paying wallet to an API key", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"key": {"type": "string"}, "wallet": {"type": "string"}, "source": {"type": "string"}, "campaign": {"type": "string"}, "plan": {"type": "string"}}, "required": ["key", "wallet"]}}}}, "responses": {"200": {"description": "Wallet registered"}, "400": {"description": "Invalid key/wallet", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}}, "additionalProperties": true}}}}}}}, "/topup/claim": {"post": {"summary": "Credit newly observed on-chain USDC transfers", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"key": {"type": "string"}, "source": {"type": "string"}, "campaign": {"type": "string"}, "plan": {"type": "string"}}, "required": ["key"]}}}}, "responses": {"200": {"description": "Claim result"}, "400": {"description": "Invalid request", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}}, "additionalProperties": true}}}}}}}, "/balance": {"get": {"summary": "Get API-key credit balance", "security": [{"ApiKeyBearer": []}], "responses": {"200": {"description": "Credit balance"}, "400": {"description": "Missing bearer key", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}}, "additionalProperties": true}}}}, "404": {"description": "Unknown API key", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}}, "additionalProperties": true}}}}}}}, "/usage": {"get": {"summary": "Get API-key balance and recent ledger events", "security": [{"ApiKeyBearer": []}], "parameters": [{"name": "limit", "in": "query", "required": false, "schema": {"type": "integer", "minimum": 1, "maximum": 100}}], "responses": {"200": {"description": "Usage ledger"}, "400": {"description": "Missing bearer key or invalid limit", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}}, "additionalProperties": true}}}}, "404": {"description": "Unknown API key", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}}, "additionalProperties": true}}}}}}}, "/mcp": {"post": {"summary": "Streamable HTTP MCP endpoint", "responses": {"200": {"description": "JSON-RPC response"}}}}, "/mcp.json": {"get": {"summary": "MCP descriptor", "responses": {"200": {"description": "MCP descriptor"}}}}, "/.well-known/x402": {"get": {"summary": "x402 discovery", "responses": {"200": {"description": "x402 discovery"}}}}, "/ops/product-kpi": {"get": {"summary": "Private product KPI/SLO health check and aggregate report for operators", "parameters": [{"name": "full", "in": "query", "required": false, "schema": {"type": "boolean", "default": false}, "description": "When true, return the full aggregate-only product KPI report instead of the short Cloud Monitoring summary."}], "responses": {"200": {"description": "Aggregate KPI status or full aggregate KPI report"}, "403": {"description": "Missing or invalid ops token"}}}}, "/ops/pilot-leads": {"get": {"summary": "Private pilot lead list for operators", "responses": {"200": {"description": "Pilot lead list; raw contact only with include_contact=1 and ops token"}, "403": {"description": "Missing or invalid ops token"}}}}, "/ops/pilot-leads/status": {"post": {"summary": "Private pilot lead lifecycle status update", "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"id": {"type": "string"}, "lead_id": {"type": "string"}, "email_hash": {"type": "string"}, "status": {"type": "string", "enum": ["new", "contacted", "qualified", "pilot_started", "won", "lost", "nurture"]}, "reason": {"type": "string"}, "note": {"type": "string", "description": "Only hash/length are retained"}, "owner": {"type": "string"}}}}}}, "responses": {"200": {"description": "Status update result; raw note is not stored"}, "400": {"description": "Invalid lead/status"}, "403": {"description": "Missing or invalid ops token"}}}}}}