{"openapi":"3.1.0","info":{"title":"QuoteBuild Chat Tools API","version":"0.1.0","description":"Provider-neutral access to the same narrow QuoteBuild application services exposed over MCP."},"servers":[{"url":"https://mcp.quotebuild.co.uk"}],"components":{"securitySchemes":{"oauth2":{"type":"oauth2","flows":{"authorizationCode":{"authorizationUrl":"https://udktmbcoygipnrmgliat.supabase.co/auth/v1/oauth/authorize","tokenUrl":"https://udktmbcoygipnrmgliat.supabase.co/auth/v1/oauth/token","scopes":{"openid":"Verify QuoteBuild openid","email":"Verify QuoteBuild email","profile":"Verify QuoteBuild profile"}}}}},"schemas":{"QuoteBuildToolResult":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"ok":{"type":"boolean"},"data":{},"warnings":{"type":"array","items":{"type":"string"}},"assumptions":{"type":"array","items":{"type":"string"}},"provenance":{"type":"object","properties":{"formulaVersion":{"type":"number"},"rateSources":{"type":"array","items":{"type":"string"}},"calculationRunId":{"type":"string"},"recordVersion":{"type":"string"}},"additionalProperties":false},"nextActions":{"type":"array","items":{"type":"object","properties":{"action":{"type":"string"},"requiresConfirmation":{"type":"boolean"}},"required":["action","requiresConfirmation"],"additionalProperties":false}},"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHENTICATED","FORBIDDEN","VALIDATION_ERROR","CONFLICT","RATE_LIMITED","FEATURE_UNAVAILABLE","RETRYABLE"]},"message":{"type":"string"},"recovery":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["ok","warnings","assumptions","nextActions"],"additionalProperties":false}}},"paths":{"/tools/discover_calculators":{"post":{"operationId":"discover_calculators","summary":"Discover QuoteBuild calculators","description":"Finds the narrowest deterministic QuoteBuild calculator for a UK building task.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"query":{"type":"string","maxLength":300}},"additionalProperties":false}}}},"responses":{"200":{"description":"QuoteBuild tool result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteBuildToolResult"}}}},"400":{"description":"Invalid request"},"401":{"description":"Authentication required"},"429":{"description":"Rate limited"}}}},"/tools/prepare_calculation":{"post":{"operationId":"prepare_calculation","summary":"Prepare a calculation","description":"Returns the exact questions and typed inputs required before a deterministic calculation can run.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"calculatorId":{"type":"string","enum":["bathroom","kitchen","extension","flatRoof","boarding","room","patio"]},"supplied":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["calculatorId"],"additionalProperties":false}}}},"responses":{"200":{"description":"QuoteBuild tool result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteBuildToolResult"}}}},"400":{"description":"Invalid request"},"401":{"description":"Authentication required"},"429":{"description":"Rate limited"}}}},"/tools/run_calculation":{"post":{"operationId":"run_calculation","summary":"Run a QuoteBuild calculation","description":"Runs one versioned QuoteBuild formula. Missing inputs use disclosed example defaults; confirm them and labour inclusion before drafting. Rates are baseline allowances. The model must not calculate monetary totals itself.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"calculatorId":{"type":"string","enum":["bathroom","kitchen","extension","flatRoof","boarding","room","patio"]},"values":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"pricing":{"type":"object","properties":{"marginPercent":{"description":"Percentage applied using marginMode. Defaults to zero. Markup is an uplift on cost; gross margin is a share of selling price.","type":"number","minimum":0,"maximum":300},"marginMode":{"default":"markup","description":"Confirm the intended mode with the user. Gross margin must be below 100 percent.","type":"string","enum":["markup","gross_margin"]},"vatPercent":{"type":"number","minimum":0,"maximum":30},"contingencyPercent":{"type":"number","minimum":0,"maximum":50}},"required":["marginMode"],"additionalProperties":false}},"required":["calculatorId","values"],"additionalProperties":false}}}},"responses":{"200":{"description":"QuoteBuild tool result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteBuildToolResult"}}}},"400":{"description":"Invalid request"},"401":{"description":"Authentication required"},"429":{"description":"Rate limited"}}}},"/tools/compare_calculations":{"post":{"operationId":"compare_calculations","summary":"Compare calculation scenarios","description":"Runs and compares up to five scenarios using the same versioned QuoteBuild formula.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"calculatorId":{"type":"string","enum":["bathroom","kitchen","extension","flatRoof","boarding","room","patio"]},"scenarios":{"minItems":2,"maxItems":5,"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1},"values":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"pricing":{"type":"object","properties":{"marginPercent":{"description":"Percentage applied using marginMode. Defaults to zero. Markup is an uplift on cost; gross margin is a share of selling price.","type":"number","minimum":0,"maximum":300},"marginMode":{"default":"markup","description":"Confirm the intended mode with the user. Gross margin must be below 100 percent.","type":"string","enum":["markup","gross_margin"]},"vatPercent":{"type":"number","minimum":0,"maximum":30},"contingencyPercent":{"type":"number","minimum":0,"maximum":50}},"required":["marginMode"],"additionalProperties":false}},"required":["name","values"],"additionalProperties":false}}},"required":["calculatorId","scenarios"],"additionalProperties":false}}}},"responses":{"200":{"description":"QuoteBuild tool result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteBuildToolResult"}}}},"400":{"description":"Invalid request"},"401":{"description":"Authentication required"},"429":{"description":"Rate limited"}}}},"/tools/review_estimate_scope":{"post":{"operationId":"review_estimate_scope","summary":"Review estimate scope","description":"Checks line completeness, unresolved scope and zero rates without changing the estimate. This does not establish construction scope completeness or readiness to quote.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"items":{"maxItems":500,"type":"array","items":{"type":"object","properties":{"trade":{"type":"string","minLength":1},"description":{"type":"string","minLength":1},"quantity":{"type":"number","minimum":0},"unit":{"type":"string","minLength":1},"rate":{"type":"number","minimum":0},"category":{"type":"string","enum":["materials","labour","hire"]},"scopeStatus":{"type":"string","enum":["included","excluded","optional","provisional_sum","client_supplied","contractor_supplied","by_others","to_be_confirmed"]}},"required":["trade","description","quantity","unit","rate","category"],"additionalProperties":false}}},"required":["items"],"additionalProperties":false}}}},"responses":{"200":{"description":"QuoteBuild tool result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteBuildToolResult"}}}},"400":{"description":"Invalid request"},"401":{"description":"Authentication required"},"429":{"description":"Rate limited"}}}},"/tools/list_jobs":{"post":{"operationId":"list_jobs","summary":"List jobs","description":"Lists the signed-in user’s jobs. Client contact details and full addresses are omitted unless clients:read is granted.","security":[{"oauth2":["openid","email","profile"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"status":{"type":"string","maxLength":50},"limit":{"default":25,"type":"integer","minimum":1,"maximum":100}},"required":["limit"],"additionalProperties":false}}}},"responses":{"200":{"description":"QuoteBuild tool result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteBuildToolResult"}}}},"400":{"description":"Invalid request"},"401":{"description":"Authentication required"},"429":{"description":"Rate limited"}}}},"/tools/get_job":{"post":{"operationId":"get_job","summary":"Get job","description":"Gets one owned job with client data redacted unless clients:read is granted.","security":[{"oauth2":["openid","email","profile"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"jobId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["jobId"],"additionalProperties":false}}}},"responses":{"200":{"description":"QuoteBuild tool result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteBuildToolResult"}}}},"400":{"description":"Invalid request"},"401":{"description":"Authentication required"},"429":{"description":"Rate limited"}}}},"/tools/get_estimate":{"post":{"operationId":"get_estimate","summary":"Get estimate","description":"Gets the latest or requested immutable estimate version for one owned job.","security":[{"oauth2":["openid","email","profile"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"jobId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"versionNumber":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"required":["jobId"],"additionalProperties":false}}}},"responses":{"200":{"description":"QuoteBuild tool result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteBuildToolResult"}}}},"400":{"description":"Invalid request"},"401":{"description":"Authentication required"},"429":{"description":"Rate limited"}}}},"/tools/get_quote":{"post":{"operationId":"get_quote","summary":"Get quote","description":"Gets one owned quote and its recipient-visible pack data.","security":[{"oauth2":["openid","email","profile"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"quoteId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["quoteId"],"additionalProperties":false}}}},"responses":{"200":{"description":"QuoteBuild tool result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteBuildToolResult"}}}},"400":{"description":"Invalid request"},"401":{"description":"Authentication required"},"429":{"description":"Rate limited"}}}},"/tools/get_job_financials":{"post":{"operationId":"get_job_financials","summary":"Get job financials","description":"Returns current estimate, quote, cost, variation and invoice totals for one owned job.","security":[{"oauth2":["openid","email","profile"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"jobId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["jobId"],"additionalProperties":false}}}},"responses":{"200":{"description":"QuoteBuild tool result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteBuildToolResult"}}}},"400":{"description":"Invalid request"},"401":{"description":"Authentication required"},"429":{"description":"Rate limited"}}}},"/tools/list_variations":{"post":{"operationId":"list_variations","summary":"List variations","description":"Lists variations belonging to one owned job.","security":[{"oauth2":["openid","email","profile"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"jobId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["jobId"],"additionalProperties":false}}}},"responses":{"200":{"description":"QuoteBuild tool result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteBuildToolResult"}}}},"400":{"description":"Invalid request"},"401":{"description":"Authentication required"},"429":{"description":"Rate limited"}}}},"/tools/list_invoices":{"post":{"operationId":"list_invoices","summary":"List invoices","description":"Lists invoices belonging to one owned job.","security":[{"oauth2":["openid","email","profile"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"jobId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["jobId"],"additionalProperties":false}}}},"responses":{"200":{"description":"QuoteBuild tool result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteBuildToolResult"}}}},"400":{"description":"Invalid request"},"401":{"description":"Authentication required"},"429":{"description":"Rate limited"}}}},"/tools/list_job_files":{"post":{"operationId":"list_job_files","summary":"List job files","description":"Lists job photos and files without exposing private storage credentials.","security":[{"oauth2":["openid","email","profile"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"jobId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["jobId"],"additionalProperties":false}}}},"responses":{"200":{"description":"QuoteBuild tool result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteBuildToolResult"}}}},"400":{"description":"Invalid request"},"401":{"description":"Authentication required"},"429":{"description":"Rate limited"}}}},"/tools/get_business_report":{"post":{"operationId":"get_business_report","summary":"Get business report","description":"Returns aggregate business and margin totals for an owned date range.","security":[{"oauth2":["openid","email","profile"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"from":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"to":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"}},"required":["from","to"],"additionalProperties":false}}}},"responses":{"200":{"description":"QuoteBuild tool result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteBuildToolResult"}}}},"400":{"description":"Invalid request"},"401":{"description":"Authentication required"},"429":{"description":"Rate limited"}}}},"/tools/get_billing_status":{"post":{"operationId":"get_billing_status","summary":"Get billing status","description":"Returns subscription and trial entitlement status, never payment-card data.","security":[{"oauth2":["openid","email","profile"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{},"additionalProperties":false}}}},"responses":{"200":{"description":"QuoteBuild tool result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteBuildToolResult"}}}},"400":{"description":"Invalid request"},"401":{"description":"Authentication required"},"429":{"description":"Rate limited"}}}},"/tools/create_job":{"post":{"operationId":"create_job","summary":"Create job draft","description":"Creates an owned job draft. This does not contact the client.","security":[{"oauth2":["openid","email","profile"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"idempotencyKey":{"type":"string","minLength":8,"maxLength":200},"name":{"type":"string","minLength":1,"maxLength":160},"clientName":{"type":"string","minLength":1,"maxLength":160},"clientEmail":{"type":"string","format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"clientPhone":{"type":"string","maxLength":60},"address":{"type":"string","maxLength":500},"jobType":{"type":"string","minLength":1,"maxLength":100},"notes":{"type":"string","maxLength":5000}},"required":["idempotencyKey","name","clientName","jobType"],"additionalProperties":false}}}},"responses":{"200":{"description":"QuoteBuild tool result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteBuildToolResult"}}}},"400":{"description":"Invalid request"},"401":{"description":"Authentication required"},"429":{"description":"Rate limited"}}}},"/tools/save_estimate_draft":{"post":{"operationId":"save_estimate_draft","summary":"Save estimate version","description":"Creates a new immutable estimate version; it never overwrites the last valid version.","security":[{"oauth2":["openid","email","profile"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"idempotencyKey":{"type":"string","minLength":8,"maxLength":200},"jobId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"expectedVersion":{"type":"string","minLength":1,"maxLength":100},"label":{"type":"string","maxLength":120},"items":{"maxItems":500,"type":"array","items":{"type":"object","properties":{"trade":{"type":"string","minLength":1},"description":{"type":"string","minLength":1},"quantity":{"type":"number","minimum":0},"unit":{"type":"string","minLength":1},"rate":{"type":"number","minimum":0},"category":{"type":"string","enum":["materials","labour","hire"]},"scopeStatus":{"type":"string","enum":["included","excluded","optional","provisional_sum","client_supplied","contractor_supplied","by_others","to_be_confirmed"]}},"required":["trade","description","quantity","unit","rate","category"],"additionalProperties":false}},"marginMaterials":{"default":20,"type":"number","minimum":0,"maximum":300},"marginLabour":{"default":30,"type":"number","minimum":0,"maximum":300},"contingencyPercent":{"default":0,"type":"number","minimum":0,"maximum":50},"vatEnabled":{"default":false,"type":"boolean"},"vatRate":{"default":20,"type":"number","minimum":0,"maximum":30},"notes":{"type":"string","maxLength":5000}},"required":["idempotencyKey","jobId","items","marginMaterials","marginLabour","contingencyPercent","vatEnabled","vatRate"],"additionalProperties":false}}}},"responses":{"200":{"description":"QuoteBuild tool result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteBuildToolResult"}}}},"400":{"description":"Invalid request"},"401":{"description":"Authentication required"},"429":{"description":"Rate limited"}}}},"/tools/create_quote_draft":{"post":{"operationId":"create_quote_draft","summary":"Create quote draft","description":"Creates an unsent quote from an owned, versioned estimate and recalculates every monetary total inside QuoteBuild.","security":[{"oauth2":["openid","email","profile"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"idempotencyKey":{"type":"string","minLength":8,"maxLength":200},"jobId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"expectedVersion":{"type":"string","minLength":1,"maxLength":100},"quoteNumber":{"type":"string","minLength":1,"maxLength":80},"estimateVersionNumber":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"validUntil":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"notes":{"type":"string","maxLength":5000}},"required":["idempotencyKey","jobId","expectedVersion","quoteNumber"],"additionalProperties":false}}}},"responses":{"200":{"description":"QuoteBuild tool result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteBuildToolResult"}}}},"400":{"description":"Invalid request"},"401":{"description":"Authentication required"},"429":{"description":"Rate limited"}}}},"/tools/add_job_cost":{"post":{"operationId":"add_job_cost","summary":"Add live job cost","description":"Adds one actual or forecast job cost to an owned job.","security":[{"oauth2":["openid","email","profile"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"idempotencyKey":{"type":"string","minLength":8,"maxLength":200},"jobId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"expectedVersion":{"type":"string","minLength":1,"maxLength":100},"trade":{"type":"string","minLength":1},"description":{"type":"string","minLength":1},"itemType":{"type":"string","enum":["materials","labour","subcontractor","hire","other"]},"quantity":{"type":"number","exclusiveMinimum":0},"unit":{"type":"string","minLength":1},"unitCost":{"type":"number","minimum":0},"actualCost":{"type":"number","minimum":0},"expenseDate":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"notes":{"type":"string","maxLength":2000}},"required":["idempotencyKey","jobId","trade","description","itemType","quantity","unit","unitCost"],"additionalProperties":false}}}},"responses":{"200":{"description":"QuoteBuild tool result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteBuildToolResult"}}}},"400":{"description":"Invalid request"},"401":{"description":"Authentication required"},"429":{"description":"Rate limited"}}}},"/tools/prepare_job_evidence_upload":{"post":{"operationId":"prepare_job_evidence_upload","summary":"Prepare receipt or payment-proof upload","description":"Creates a one-time, ten-minute secure image upload for a supplier receipt, customer payment proof or job evidence. Uploading proof never marks an invoice as paid.","security":[{"oauth2":["openid","email","profile"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"idempotencyKey":{"type":"string","minLength":8,"maxLength":200},"jobId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"kind":{"type":"string","enum":["supplier_receipt","customer_payment_proof","job_evidence"]},"fileName":{"type":"string","minLength":1,"maxLength":255},"mimeType":{"type":"string","enum":["image/jpeg","image/png","image/webp"]},"fileSize":{"type":"integer","exclusiveMinimum":0,"maximum":5000000},"costItemId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"invoiceId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"note":{"type":"string","maxLength":500}},"required":["idempotencyKey","jobId","kind","fileName","mimeType","fileSize"],"additionalProperties":false}}}},"responses":{"200":{"description":"QuoteBuild tool result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteBuildToolResult"}}}},"400":{"description":"Invalid request"},"401":{"description":"Authentication required"},"429":{"description":"Rate limited"}}}},"/tools/attach_job_file":{"post":{"operationId":"attach_job_file","summary":"Attach job file","description":"Registers a host-provided file after upload reservation validation. It never performs OCR or plan reading.","security":[{"oauth2":["openid","email","profile"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"idempotencyKey":{"type":"string","minLength":8,"maxLength":200},"jobId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"fileName":{"type":"string","minLength":1,"maxLength":255},"mimeType":{"type":"string","minLength":1,"maxLength":120},"fileSize":{"type":"integer","exclusiveMinimum":0,"maximum":25000000},"hostFileUrl":{"type":"string","format":"uri"}},"required":["idempotencyKey","jobId","fileName","mimeType","fileSize","hostFileUrl"],"additionalProperties":false}}}},"responses":{"200":{"description":"QuoteBuild tool result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteBuildToolResult"}}}},"400":{"description":"Invalid request"},"401":{"description":"Authentication required"},"429":{"description":"Rate limited"}}}},"/tools/create_variation_draft":{"post":{"operationId":"create_variation_draft","summary":"Create variation draft","description":"Creates an unsent variation draft and calculates its amount from the supplied reviewed lines inside QuoteBuild.","security":[{"oauth2":["openid","email","profile"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"idempotencyKey":{"type":"string","minLength":8,"maxLength":200},"jobId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"quoteId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"description":{"type":"string","minLength":1,"maxLength":2000},"items":{"minItems":1,"maxItems":200,"type":"array","items":{"type":"object","properties":{"trade":{"type":"string","minLength":1},"description":{"type":"string","minLength":1},"quantity":{"type":"number","minimum":0},"unit":{"type":"string","minLength":1},"rate":{"type":"number","minimum":0},"category":{"type":"string","enum":["materials","labour","hire"]},"scopeStatus":{"type":"string","enum":["included","excluded","optional","provisional_sum","client_supplied","contractor_supplied","by_others","to_be_confirmed"]}},"required":["trade","description","quantity","unit","rate","category"],"additionalProperties":false}},"notes":{"type":"string","maxLength":5000}},"required":["idempotencyKey","jobId","description","items"],"additionalProperties":false}}}},"responses":{"200":{"description":"QuoteBuild tool result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteBuildToolResult"}}}},"400":{"description":"Invalid request"},"401":{"description":"Authentication required"},"429":{"description":"Rate limited"}}}},"/tools/create_invoice_draft":{"post":{"operationId":"create_invoice_draft","summary":"Create invoice draft","description":"Creates an unsent invoice draft and calculates its amount from the supplied reviewed lines inside QuoteBuild.","security":[{"oauth2":["openid","email","profile"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"idempotencyKey":{"type":"string","minLength":8,"maxLength":200},"jobId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"quoteId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"invoiceNumber":{"type":"string","minLength":1,"maxLength":80},"dueDate":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"items":{"minItems":1,"maxItems":200,"type":"array","items":{"type":"object","properties":{"trade":{"type":"string","minLength":1},"description":{"type":"string","minLength":1},"quantity":{"type":"number","minimum":0},"unit":{"type":"string","minLength":1},"rate":{"type":"number","minimum":0},"category":{"type":"string","enum":["materials","labour","hire"]},"scopeStatus":{"type":"string","enum":["included","excluded","optional","provisional_sum","client_supplied","contractor_supplied","by_others","to_be_confirmed"]}},"required":["trade","description","quantity","unit","rate","category"],"additionalProperties":false}},"notes":{"type":"string","maxLength":5000}},"required":["idempotencyKey","jobId","invoiceNumber","items"],"additionalProperties":false}}}},"responses":{"200":{"description":"QuoteBuild tool result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteBuildToolResult"}}}},"400":{"description":"Invalid request"},"401":{"description":"Authentication required"},"429":{"description":"Rate limited"}}}},"/tools/prepare_invoice_payment_record":{"post":{"operationId":"prepare_invoice_payment_record","summary":"Prepare invoice payment record","description":"Shows the exact unpaid invoice and records a one-use ten-minute confirmation. It does not mark the invoice paid.","security":[{"oauth2":["openid","email","profile"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"idempotencyKey":{"type":"string","minLength":8,"maxLength":200},"invoiceId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"expectedVersion":{"type":"string","minLength":1,"maxLength":100},"paidAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"paymentMethod":{"type":"string","enum":["bank_transfer","cash","card","cheque","other"]},"paymentReference":{"type":"string","maxLength":160},"paymentProofId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["idempotencyKey","invoiceId","expectedVersion","paymentMethod"],"additionalProperties":false}}}},"responses":{"200":{"description":"QuoteBuild tool result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteBuildToolResult"}}}},"400":{"description":"Invalid request"},"401":{"description":"Authentication required"},"429":{"description":"Rate limited"}}}},"/tools/record_invoice_payment":{"post":{"operationId":"record_invoice_payment","summary":"Record confirmed invoice payment","description":"Marks the exact prepared invoice as paid only after an explicit, one-use confirmation. It never contacts the customer or payment provider.","security":[{"oauth2":["openid","email","profile"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"idempotencyKey":{"type":"string","minLength":8,"maxLength":200},"invoiceId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"confirmationToken":{"type":"string","minLength":32,"maxLength":300}},"required":["idempotencyKey","invoiceId","confirmationToken"],"additionalProperties":false}}}},"responses":{"200":{"description":"QuoteBuild tool result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteBuildToolResult"}}}},"400":{"description":"Invalid request"},"401":{"description":"Authentication required"},"429":{"description":"Rate limited"}}}},"/tools/prepare_quote_send":{"post":{"operationId":"prepare_quote_send","summary":"Prepare quote send","description":"Previews the exact current quote recipient and payload, then stores a one-use ten-minute confirmation token. This does not send.","security":[{"oauth2":["openid","email","profile"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"quoteId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"expectedVersion":{"type":"string","minLength":1,"maxLength":100},"idempotencyKey":{"type":"string","minLength":8,"maxLength":200}},"required":["quoteId","expectedVersion","idempotencyKey"],"additionalProperties":false}}}},"responses":{"200":{"description":"QuoteBuild tool result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteBuildToolResult"}}}},"400":{"description":"Invalid request"},"401":{"description":"Authentication required"},"429":{"description":"Rate limited"}}}},"/tools/send_quote":{"post":{"operationId":"send_quote","summary":"Send quote","description":"Sends the exact prepared quote payload after validating the one-use confirmation token.","security":[{"oauth2":["openid","email","profile"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"quoteId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"confirmationToken":{"type":"string","minLength":32,"maxLength":300},"idempotencyKey":{"type":"string","minLength":8,"maxLength":200}},"required":["quoteId","confirmationToken","idempotencyKey"],"additionalProperties":false}}}},"responses":{"200":{"description":"QuoteBuild tool result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteBuildToolResult"}}}},"400":{"description":"Invalid request"},"401":{"description":"Authentication required"},"429":{"description":"Rate limited"}}}},"/tools/prepare_variation_send":{"post":{"operationId":"prepare_variation_send","summary":"Prepare variation send","description":"Previews the exact current variation recipient and payload, then stores a one-use ten-minute confirmation token. This does not send.","security":[{"oauth2":["openid","email","profile"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"variationId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"expectedVersion":{"type":"string","minLength":1,"maxLength":100},"idempotencyKey":{"type":"string","minLength":8,"maxLength":200}},"required":["variationId","expectedVersion","idempotencyKey"],"additionalProperties":false}}}},"responses":{"200":{"description":"QuoteBuild tool result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteBuildToolResult"}}}},"400":{"description":"Invalid request"},"401":{"description":"Authentication required"},"429":{"description":"Rate limited"}}}},"/tools/send_variation":{"post":{"operationId":"send_variation","summary":"Send variation","description":"Sends the exact prepared variation payload after validating the one-use confirmation token.","security":[{"oauth2":["openid","email","profile"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"variationId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"confirmationToken":{"type":"string","minLength":32,"maxLength":300},"idempotencyKey":{"type":"string","minLength":8,"maxLength":200}},"required":["variationId","confirmationToken","idempotencyKey"],"additionalProperties":false}}}},"responses":{"200":{"description":"QuoteBuild tool result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteBuildToolResult"}}}},"400":{"description":"Invalid request"},"401":{"description":"Authentication required"},"429":{"description":"Rate limited"}}}},"/tools/prepare_invoice_send":{"post":{"operationId":"prepare_invoice_send","summary":"Prepare invoice send","description":"Previews the exact current invoice recipient and payload, then stores a one-use ten-minute confirmation token. This does not send.","security":[{"oauth2":["openid","email","profile"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"invoiceId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"expectedVersion":{"type":"string","minLength":1,"maxLength":100},"idempotencyKey":{"type":"string","minLength":8,"maxLength":200}},"required":["invoiceId","expectedVersion","idempotencyKey"],"additionalProperties":false}}}},"responses":{"200":{"description":"QuoteBuild tool result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteBuildToolResult"}}}},"400":{"description":"Invalid request"},"401":{"description":"Authentication required"},"429":{"description":"Rate limited"}}}},"/tools/send_invoice":{"post":{"operationId":"send_invoice","summary":"Send invoice","description":"Sends the exact prepared invoice payload after validating the one-use confirmation token.","security":[{"oauth2":["openid","email","profile"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"invoiceId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"confirmationToken":{"type":"string","minLength":32,"maxLength":300},"idempotencyKey":{"type":"string","minLength":8,"maxLength":200}},"required":["invoiceId","confirmationToken","idempotencyKey"],"additionalProperties":false}}}},"responses":{"200":{"description":"QuoteBuild tool result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteBuildToolResult"}}}},"400":{"description":"Invalid request"},"401":{"description":"Authentication required"},"429":{"description":"Rate limited"}}}}}}