{"openapi":"3.1.0","info":{"title":"Contractor Payment Application Audit API","version":"1.0.0","description":"Check contractor payment applications against schedule of values, measured work, approved variations, previous certificates, retention rules, and deductions. Every adjustment includes calculation evidence and a recommended payable amount for review. Paid with x402 exact USDC on Base. No account is required.","contact":{"email":"support@brainiac.software"},"x-guidance":"BRAINIAC.software is a pay-per-call API for software agents. No account or API key is required.\nPayment uses the x402 protocol with exact USDC on Base (chain id 8453). Each POST operation has a fixed USD price.\nHow to call an operation:\n1. POST JSON matching the requestBody. Invalid input returns 400 with no payment challenge.\n2. A valid unpaid call returns 402 with the exact amount and payTo.\n3. Pay and retry with payment-signature. Payment settles only if the operation returns 2xx. A 4xx/5xx is not charged.\nInclude an Idempotency-Key header of 64 hex characters from 32 random bytes. Reuse that key only for retries of the same operation and request body.\nAll outputs are compliance prechecks, drafts, or data lookups for human review. They are not official determinations, legal advice, identity confirmation, or certified filings. Verify time-sensitive or official data with the cited source before acting."},"servers":[{"url":"https://www.brainiac.software"}],"paths":{"/api/v1/construction-commercial/contractor-payment-application-audit":{"post":{"operationId":"audit_contractor_payment_applications","summary":"Audit contractor payment applications","description":"Independently check a contractor payment application against the schedule of values, measured work, approved variations, previous certificates, retention rules, and deductions. Unsupported claims, duplicated work, unapproved variations, retention errors, and certificate mismatches are adjusted with calculation evidence. The recommended payable amount is for review only.","tags":["construction-commercial"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"contract":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":120},"currency":{"type":"string","pattern":"^[A-Z]{3}$"},"retention_bps":{"type":"integer","minimum":0,"maximum":10000},"retention_release_bps":{"type":"integer","minimum":0,"maximum":10000}},"required":["id","currency","retention_bps"],"additionalProperties":false},"schedule_of_values":{"minItems":1,"maxItems":2000,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":120},"description":{"type":"string","minLength":1,"maxLength":240},"contracted_amount":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["id","contracted_amount"],"additionalProperties":false}},"payment_application":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":120},"application_number":{"type":"integer","minimum":1,"maximum":10000},"submitted_on":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"lines":{"minItems":1,"maxItems":2000,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":120},"sov_item_id":{"type":"string","minLength":1,"maxLength":120},"claimed_amount":{"type":"integer","minimum":0,"maximum":9007199254740991},"variation_id":{"type":"string","minLength":1,"maxLength":120},"previously_certified_amount":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["id","sov_item_id","claimed_amount"],"additionalProperties":false}},"claimed_retention_release":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["id","application_number","submitted_on","lines"],"additionalProperties":false},"previous_certificates":{"maxItems":500,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":120},"certificate_number":{"type":"integer","minimum":1,"maximum":10000},"certified_on":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"lines":{"minItems":1,"maxItems":2000,"type":"array","items":{"type":"object","properties":{"sov_item_id":{"type":"string","minLength":1,"maxLength":120},"certified_amount":{"type":"integer","minimum":0,"maximum":9007199254740991},"variation_id":{"type":"string","minLength":1,"maxLength":120}},"required":["sov_item_id","certified_amount"],"additionalProperties":false}},"retention_held":{"type":"integer","minimum":0,"maximum":9007199254740991},"deductions":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["id","certificate_number","certified_on","lines"],"additionalProperties":false}},"measured_work":{"maxItems":5000,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":120},"sov_item_id":{"type":"string","minLength":1,"maxLength":120},"measured_amount":{"type":"integer","minimum":0,"maximum":9007199254740991},"measured_on":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},"required":["id","sov_item_id","measured_amount"],"additionalProperties":false}},"variations":{"maxItems":2000,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":120},"sov_item_id":{"type":"string","minLength":1,"maxLength":120},"approved_amount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"approved":{"type":"boolean"},"approved_on":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"description":{"type":"string","minLength":1,"maxLength":240}},"required":["id","approved_amount","approved"],"additionalProperties":false}},"deductions":{"maxItems":500,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":120},"amount":{"type":"integer","minimum":0,"maximum":9007199254740991},"reason":{"type":"string","minLength":1,"maxLength":240}},"required":["id","amount"],"additionalProperties":false}}},"required":["contract","schedule_of_values","payment_application"],"additionalProperties":false},"example":{"contract":{"id":"c1","currency":"GBP","retention_bps":500,"retention_release_bps":10000},"schedule_of_values":[{"id":"sov-1","description":"Foundations","contracted_amount":100000},{"id":"sov-2","description":"Frame","contracted_amount":200000}],"payment_application":{"id":"app-3","application_number":3,"submitted_on":"2026-11-05","claimed_retention_release":1000,"lines":[{"id":"l1","sov_item_id":"sov-1","claimed_amount":40000,"previously_certified_amount":50000},{"id":"l2","sov_item_id":"sov-2","claimed_amount":25000},{"id":"l3","sov_item_id":"sov-2","claimed_amount":10000,"variation_id":"var-1"}]},"previous_certificates":[{"id":"cert-1","certificate_number":1,"certified_on":"2026-10-01","retention_held":2500,"lines":[{"sov_item_id":"sov-1","certified_amount":50000}]}],"measured_work":[{"id":"m1","sov_item_id":"sov-1","measured_amount":80000},{"id":"m2","sov_item_id":"sov-2","measured_amount":20000}],"variations":[{"id":"var-1","sov_item_id":"sov-2","approved_amount":8000,"approved":false,"description":"Extra steel"}],"deductions":[{"id":"d1","amount":500,"reason":"Defects"}]}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Fresh random 32-byte value encoded as 64 hexadecimal characters. Reuse unchanged only for retries of the same operation and request.","schema":{"type":"string","pattern":"^[0-9a-fA-F]{64}$"}}],"responses":{"200":{"description":"Illustrative endpoint-specific JSON response shape. Conditional fields depend on the result and data-source availability.","content":{"application/json":{"schema":{"type":"object","properties":{"currency":{"type":"string"},"verified_lines":{"type":"array","items":{"type":"object","properties":{"application_line_id":{"type":"string"},"sov_item_id":{"type":"string"},"code":{"type":"string"},"claimed_amount":{"type":"number"},"recommended_amount":{"type":"number"},"adjustment_amount":{"type":"number"},"evidence":{"type":"array","items":{"type":"string"}}},"additionalProperties":true}},"unsupported_claims":{"type":"array","items":{}},"duplicated_work":{"type":"array","items":{}},"variation_mismatches":{"type":"array","items":{"type":"object","properties":{"application_line_id":{"type":"string"},"variation_id":{"type":"string"},"claimed_amount":{"type":"number"},"detail":{"type":"string"}},"additionalProperties":true}},"certificate_discrepancies":{"type":"array","items":{}},"retention":{"type":"object","properties":{"retention_bps":{"type":"number"},"recommended_gross":{"type":"number"},"retention_held_this_period":{"type":"number"},"previous_retention_held":{"type":"number"},"retention_release":{"type":"number"},"calculation":{"type":"string"}},"additionalProperties":true},"deductions":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"amount":{"type":"number"},"reason":{"type":"string"}},"additionalProperties":true}},"total":{"type":"number"}},"additionalProperties":true},"recommended_for_review":{"type":"object","properties":{"claimed_gross":{"type":"number"},"recommended_gross":{"type":"number"},"retention_held_this_period":{"type":"number"},"retention_release":{"type":"number"},"deductions_total":{"type":"number"},"recommended_payable":{"type":"number"},"calculation":{"type":"string"}},"additionalProperties":true},"adjustments":{"type":"array","items":{"type":"object","properties":{"application_line_id":{"type":"string"},"sov_item_id":{"type":"string"},"code":{"type":"string"},"claimed_amount":{"type":"number"},"recommended_amount":{"type":"number"},"adjustment_amount":{"type":"number"},"evidence":{"type":"array","items":{"type":"string"}}},"additionalProperties":true}},"explanations":{"type":"array","items":{"type":"string"}}},"additionalProperties":true},"example":{"currency":"GBP","verified_lines":[{"application_line_id":"l1","sov_item_id":"sov-1","code":"claim_exceeds_measure_or_contract","claimed_amount":40000,"recommended_amount":30000,"adjustment_amount":-10000,"evidence":["measured_amount 80000, previously certified 50000, contracted_amount 100000.","Allowable incremental amount is min(contracted-prior, measured-prior) = 30000.","Claimed 40000 was reduced to 30000."]},{"application_line_id":"l2","sov_item_id":"sov-2","code":"claim_exceeds_measure_or_contract","claimed_amount":25000,"recommended_amount":20000,"adjustment_amount":-5000,"evidence":["measured_amount 20000, previously certified 0, contracted_amount 200000.","Allowable incremental amount is min(contracted-prior, measured-prior) = 20000.","Claimed 25000 was reduced to 20000."]},{"application_line_id":"l3","sov_item_id":"sov-2","code":"unapproved_variation","claimed_amount":10000,"recommended_amount":0,"adjustment_amount":-10000,"evidence":["Variation var-1 has approved=false, so the claimed amount is excluded."]}],"unsupported_claims":[],"duplicated_work":[],"variation_mismatches":[{"application_line_id":"l3","variation_id":"var-1","claimed_amount":10000,"detail":"Variation is not marked approved."}],"certificate_discrepancies":[],"retention":{"retention_bps":500,"recommended_gross":50000,"retention_held_this_period":2500,"previous_retention_held":2500,"retention_release":1000,"calculation":"retention_held_this_period = floor(recommended_gross 50000 * retention_bps 500 / 10000) = 2500"},"deductions":{"items":[{"id":"d1","amount":500,"reason":"Defects"}],"total":500},"recommended_for_review":{"claimed_gross":75000,"recommended_gross":50000,"retention_held_this_period":2500,"retention_release":1000,"deductions_total":500,"recommended_payable":48000,"calculation":"recommended_payable = recommended_gross 50000 - retention 2500 + retention_release 1000 - deductions 500 = 48000"},"adjustments":[{"application_line_id":"l1","sov_item_id":"sov-1","code":"claim_exceeds_measure_or_contract","claimed_amount":40000,"recommended_amount":30000,"adjustment_amount":-10000,"evidence":["measured_amount 80000, previously certified 50000, contracted_amount 100000.","Allowable incremental amount is min(contracted-prior, measured-prior) = 30000.","Claimed 40000 was reduced to 30000."]},{"application_line_id":"l2","sov_item_id":"sov-2","code":"claim_exceeds_measure_or_contract","claimed_amount":25000,"recommended_amount":20000,"adjustment_amount":-5000,"evidence":["measured_amount 20000, previously certified 0, contracted_amount 200000.","Allowable incremental amount is min(contracted-prior, measured-prior) = 20000.","Claimed 25000 was reduced to 20000."]},{"application_line_id":"l3","sov_item_id":"sov-2","code":"unapproved_variation","claimed_amount":10000,"recommended_amount":0,"adjustment_amount":-10000,"evidence":["Variation var-1 has approved=false, so the claimed amount is excluded."]},{"application_line_id":"app-3","sov_item_id":"*","code":"retention_release_accepted","claimed_amount":1000,"recommended_amount":1000,"adjustment_amount":0,"evidence":["Claimed retention release 1000 is within held retention 2500."]}],"explanations":["Non-variation lines require measured_work. Allowable incremental amount = min(contracted_amount - previously_certified, measured_amount - previously_certified).","Variation lines require approved=true. Claims above approved_amount - previously_certified are capped.","previously_certified is summed from previous_certificates lines for the same sov_item_id and optional variation_id.","retention_held_this_period = floor(recommended_gross * retention_bps / 10000).","Every adjustment includes calculation evidence. No unstated rates or quantities are invented."]}}}},"400":{"description":"Invalid JSON or request schema."},"402":{"description":"Payment required. The JSON body is the x402 PaymentRequired object: x402Version, resource with the operation description, accepts with the price and network, and extensions.bazaar with the input schema, input example, output schema, and output example."},"409":{"description":"Idempotency conflict, in-progress payment, or expired result cache. Reusing the key cannot trigger a second charge."},"413":{"description":"Request body exceeds the 24 MB limit."},"500":{"description":"Operation failed before settlement, so no payment is taken. Reuse the same idempotency key to retrieve the stored error without paying again."},"503":{"description":"Payment or retry-safe result storage is unavailable; the operation is not run."}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.04"},"protocols":[{"x402":{"facilitator":"https://api.cdp.coinbase.com/platform/v2/x402"}}],"facilitator":"https://api.cdp.coinbase.com/platform/v2/x402"}}}},"components":{"schemas":{"ApiError":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}}