{ "openapi": "3.1.2", "info": { "title": "Craft Quantities Engine API", "version": "1.4.0", "summary": "Run Craft Quantities' construction calculators, whole-job takeoffs, room planner, House Estimator and Construction Canvas, and read its diagnoses, Solve Backwards pages, standards map and glossary: quantities in metric and US customary, with versions, sources, citations and links.", "description": "Quantities only: no prices, no design, no certification. Every answer is the calculator's own compute(), run as its page runs it. The same engine answers MCP clients at https://api.craftquantities.com/mcp. Every route answers JSON, or the engine's short Markdown report with ?format=md or Accept: text/markdown. No key, no account; results are published under CC BY 4.0.", "license": { "name": "CC BY 4.0", "url": "https://creativecommons.org/licenses/by/4.0/" }, "contact": { "url": "https://craftquantities.com/api/" } }, "externalDocs": { "url": "https://craftquantities.com/api/", "description": "The API documentation" }, "servers": [ { "url": "https://api.craftquantities.com/v1" } ], "paths": { "/calculate/{slug}": { "get": { "operationId": "calculateGet", "summary": "Run a calculator (inputs in the query)", "description": "Every other query parameter is an input id, its value written with its unit where it measures something: slabLength=3%20m, slabThickness=4%20in.", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,119}$", "description": "The calculator's slug, such as concrete-calculator." } }, { "name": "system", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "metric", "imperial" ], "default": "metric", "description": "The unit system inputs left out open in, and the one the page link opens in. The answer comes in both." } }, { "name": "market", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "US", "CA", "UK", "AU", "INTL" ], "description": "Optional. A market whose own opening choice some inputs take (a UK reader's code, an IEC motor), and whose currency symbol prints the caller's own money figures." } }, { "name": "inputUnits", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "base" ], "description": "Send \"base\" to pass bare numbers on dimensioned inputs in base units (m, m², L, kg …), as the published test vectors are written. Without it a length, area or volume must carry its unit." } }, { "name": "explain", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "description": "true adds the working: the inputs as the calculator received them, every intermediate figure its own compute reports with its unit, the range check and the unit restatement, ending on the same figures. The answer's figures are identical either way." } }, { "name": "detail", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "full", "summary" ], "default": "full", "description": "full (the default): the whole answer. summary: the result lines, the citation line and the page only — fewer tokens to read." }, "description": "summary: the result lines, the citation and the page only (fewer tokens); full, the default: the whole answer. A POST body may carry detail instead." }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json", "md" ] }, "description": "md: the engine's Markdown report as text/markdown (or send Accept: text/markdown); json, the default." } ], "responses": { "200": { "description": "The answer in both systems, with its inputs, sources and citation.", "content": { "application/json": { "schema": { "type": "object", "anyOf": [ { "type": "object", "required": [ "engine", "calculator", "system", "inputs", "result", "sources", "citation", "links", "licence", "notice" ], "properties": { "engine": { "type": "object", "required": [ "name", "version", "api" ], "properties": { "name": { "type": "string" }, "version": { "type": "string" }, "api": { "type": "string" } } }, "calculator": { "type": "object", "required": [ "slug", "title", "category", "version", "lastVerified", "url", "json" ], "properties": { "slug": { "type": "string" }, "title": { "type": "string" }, "category": { "type": "string" }, "description": { "type": "string" }, "version": { "type": "string", "description": "The calculator's own version; a result names the calculator that produced it." }, "lastVerified": { "type": "string", "description": "The date the calculator's sources were last checked." }, "url": { "type": "string", "description": "The calculator's page on craftquantities.com." }, "json": { "type": "string", "description": "The calculator's static API document, with its test vectors." } } }, "system": { "enum": [ "metric", "imperial" ] }, "market": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "inputs": { "type": "array", "items": { "type": "object", "required": [ "id", "label", "type", "value", "source" ], "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "type": { "enum": [ "number", "select" ] }, "value": { "type": [ "number", "string" ] }, "dimension": { "type": "string" }, "baseUnit": { "type": "string" }, "source": { "enum": [ "caller", "default" ] }, "read": { "type": "string" }, "metric": { "type": "object", "required": [ "value", "unit" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string" } } }, "imperial": { "type": "object", "required": [ "value", "unit" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string" } } }, "option": { "type": "string" } } }, "description": "Every input the calculation ran on, and where each came from." }, "result": { "type": "object", "required": [ "label", "metric", "imperial" ], "properties": { "label": { "type": "string" }, "metric": { "type": "object", "required": [ "value", "unit", "printed", "breakdown", "confidence", "isComparison", "canonical" ], "properties": { "value": { "anyOf": [ { "type": "number", "description": "The headline in this system; null where a rate it needs is not given." }, { "type": "null" } ] }, "unit": { "type": "string" }, "printed": { "anyOf": [ { "type": "string", "description": "The headline exactly as the page prints it." }, { "type": "null" } ] }, "breakdown": { "type": "array", "items": { "type": "object", "required": [ "label", "value", "unit", "printed" ], "properties": { "label": { "type": "string" }, "value": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "unit": { "type": "string" }, "printed": { "type": "string" } } } }, "confidence": { "enum": [ "high", "medium", "low" ] }, "confidenceNote": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowance": { "anyOf": [ { "type": "object", "properties": { "label": { "type": "string" }, "percent": { "type": "number" }, "base": { "type": "number" } } }, { "type": "null" } ] }, "limitations": { "type": "array", "items": { "type": "string" } }, "isComparison": { "type": "boolean", "description": "The figure is set against a limit. It is not an approval." }, "withheld": { "anyOf": [ { "type": "object", "properties": { "missingRates": { "type": "array", "items": { "type": "object", "properties": { "input": { "type": "string" }, "label": { "type": "string" } } } } } }, { "type": "null" } ] }, "canonical": { "type": "object", "required": [ "value", "unit" ], "properties": { "value": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "unit": { "type": "string" } }, "description": "The figure in the calculator's own unit, before the display adapter: what its test vectors pin." } } }, "imperial": { "type": "object", "required": [ "value", "unit", "printed", "breakdown", "confidence", "isComparison", "canonical" ], "properties": { "value": { "anyOf": [ { "type": "number", "description": "The headline in this system; null where a rate it needs is not given." }, { "type": "null" } ] }, "unit": { "type": "string" }, "printed": { "anyOf": [ { "type": "string", "description": "The headline exactly as the page prints it." }, { "type": "null" } ] }, "breakdown": { "type": "array", "items": { "type": "object", "required": [ "label", "value", "unit", "printed" ], "properties": { "label": { "type": "string" }, "value": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "unit": { "type": "string" }, "printed": { "type": "string" } } } }, "confidence": { "enum": [ "high", "medium", "low" ] }, "confidenceNote": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowance": { "anyOf": [ { "type": "object", "properties": { "label": { "type": "string" }, "percent": { "type": "number" }, "base": { "type": "number" } } }, { "type": "null" } ] }, "limitations": { "type": "array", "items": { "type": "string" } }, "isComparison": { "type": "boolean", "description": "The figure is set against a limit. It is not an approval." }, "withheld": { "anyOf": [ { "type": "object", "properties": { "missingRates": { "type": "array", "items": { "type": "object", "properties": { "input": { "type": "string" }, "label": { "type": "string" } } } } } }, { "type": "null" } ] }, "canonical": { "type": "object", "required": [ "value", "unit" ], "properties": { "value": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "unit": { "type": "string" } }, "description": "The figure in the calculator's own unit, before the display adapter: what its test vectors pin." } } } } }, "sources": { "type": "array", "items": { "type": "object", "required": [ "label" ], "properties": { "label": { "type": "string", "description": "The source as the calculator cites it." }, "url": { "type": "string", "description": "Only where the calculator gives one; none is invented." }, "references": { "type": "array", "items": { "type": "object", "required": [ "kind", "document" ], "properties": { "kind": { "enum": [ "code", "standard" ] }, "body": { "type": "string" }, "document": { "type": "string" }, "section": { "type": "string" }, "edition": { "type": "string" } } } } } } }, "citation": { "type": "object", "required": [ "author", "title", "url", "formats", "accessDate" ], "properties": { "author": { "type": "string" }, "title": { "type": "string" }, "version": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sourcesChecked": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "url": { "type": "string" }, "accessDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "formats": { "type": "object", "required": [ "plain", "apa", "harvard", "bibtex" ], "properties": { "plain": { "type": "string" }, "apa": { "type": "string" }, "harvard": { "type": "string" }, "bibtex": { "type": "string" } } } } }, "links": { "type": "object", "required": [ "page", "open" ], "properties": { "page": { "type": "string" }, "open": { "type": "string", "description": "Opens the page on these inputs." } } }, "licence": { "type": "object", "required": [ "name", "url", "attribution" ], "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "attribution": { "type": "string" } } }, "notice": { "type": "string" }, "explain": { "type": "object", "required": [ "about", "coverage", "steps", "final", "limits" ], "description": "Only when explain is true. Each figure is the calculator's own; no step is a formula written for the engine.", "properties": { "about": { "type": "string" }, "coverage": { "enum": [ "intermediates", "result-only" ], "description": "result-only: the calculator reports no figures between its inputs and its result." }, "steps": { "type": "array", "items": { "type": "object", "required": [ "n", "kind", "system", "label", "text" ], "properties": { "n": { "type": "integer" }, "kind": { "enum": [ "input", "intermediate", "result", "allowance", "range", "rates", "display" ] }, "system": { "enum": [ "metric", "imperial", "both" ] }, "label": { "type": "string" }, "value": { "anyOf": [ { "type": "number" }, { "type": "string" }, { "type": "null" } ] }, "unit": { "type": "string", "description": "The calculator's own (base) unit for the value." }, "metric": { "type": "object", "required": [ "value", "unit" ], "properties": { "value": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "unit": { "type": "string" } } }, "imperial": { "type": "object", "required": [ "value", "unit" ], "properties": { "value": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "unit": { "type": "string" } } }, "movedBy": { "type": "array", "items": { "type": "string" }, "description": "Input ids whose change moved this figure, measured by running compute again." }, "source": { "enum": [ "caller", "default" ] }, "text": { "type": "string", "description": "The step in words." } } } }, "final": { "type": "object", "required": [ "metric", "imperial" ], "properties": { "metric": { "type": "object", "required": [ "value", "unit", "printed" ], "properties": { "value": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "unit": { "type": "string" }, "printed": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, "imperial": { "type": "object", "required": [ "value", "unit", "printed" ], "properties": { "value": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "unit": { "type": "string" }, "printed": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } }, "description": "The figures the answer returns, copied from it." }, "limits": { "type": "array", "items": { "type": "string" }, "description": "What the trace does not show, and why." } } } } }, { "type": "object", "required": [ "detail", "tool", "title", "lines", "notes", "citation", "url", "open", "more" ], "properties": { "detail": { "const": "summary" }, "tool": { "type": "string" }, "title": { "type": "string" }, "lines": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "string" } }, "description": "The result lines, as the report's table gives them." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "What a professional must decide, when to call one, a false-friend warning, that adoption is local: kept in every summary." }, "citation": { "type": "string", "description": "The one citation line, built from the answer's own data." }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "open": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "more": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } ] } } } }, "400": { "description": "The request was refused; every problem is listed.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "title", "status", "problems" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "problems": { "type": "array", "items": { "type": "object", "required": [ "input", "problem" ], "properties": { "input": { "type": "string" }, "problem": { "type": "string" }, "accepted": { "type": "array", "items": { "type": "string" } } } } }, "didYouMean": { "type": "array", "items": { "type": "string" } } } } } } }, "404": { "description": "The request was refused; every problem is listed.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "title", "status", "problems" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "problems": { "type": "array", "items": { "type": "object", "required": [ "input", "problem" ], "properties": { "input": { "type": "string" }, "problem": { "type": "string" }, "accepted": { "type": "array", "items": { "type": "string" } } } } }, "didYouMean": { "type": "array", "items": { "type": "string" } } } } } } } }, "tags": [ "Calculators" ] }, "post": { "operationId": "calculate", "summary": "Run a calculator", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,119}$", "description": "The calculator's slug, such as concrete-calculator." } }, { "name": "detail", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "full", "summary" ], "default": "full", "description": "full (the default): the whole answer. summary: the result lines, the citation line and the page only — fewer tokens to read." }, "description": "summary: the result lines, the citation and the page only (fewer tokens); full, the default: the whole answer. A POST body may carry detail instead." }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json", "md" ] }, "description": "md: the engine's Markdown report as text/markdown (or send Accept: text/markdown); json, the default." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "inputs": { "type": "object", "maxProperties": 100, "description": "The calculator's input values, by input id (an unknown id is refused with the accepted ids). A length, area, volume or other measured input takes \"12 ft\", \"3.5 m\", \"8' 3 1/2\\\"\" or {\"value\": 12, \"unit\": \"ft\"}; a count or percentage takes a number; a select takes one of its option values. Inputs left out take the value the calculator's page opens on.", "additionalProperties": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] } }, "system": { "type": "string", "enum": [ "metric", "imperial" ], "default": "metric", "description": "The unit system inputs left out open in, and the one the page link opens in. The answer comes in both." }, "market": { "type": "string", "enum": [ "US", "CA", "UK", "AU", "INTL" ], "description": "Optional. A market whose own opening choice some inputs take (a UK reader's code, an IEC motor), and whose currency symbol prints the caller's own money figures." }, "inputUnits": { "type": "string", "enum": [ "base" ], "description": "Send \"base\" to pass bare numbers on dimensioned inputs in base units (m, m², L, kg …), as the published test vectors are written. Without it a length, area or volume must carry its unit." }, "explain": { "type": "boolean", "default": false, "description": "true adds the working: the inputs as the calculator received them, every intermediate figure its own compute reports with its unit, the range check and the unit restatement, ending on the same figures. The answer's figures are identical either way." } } } } } }, "responses": { "200": { "description": "The answer in both systems, with its inputs, sources and citation.", "content": { "application/json": { "schema": { "type": "object", "anyOf": [ { "type": "object", "required": [ "engine", "calculator", "system", "inputs", "result", "sources", "citation", "links", "licence", "notice" ], "properties": { "engine": { "type": "object", "required": [ "name", "version", "api" ], "properties": { "name": { "type": "string" }, "version": { "type": "string" }, "api": { "type": "string" } } }, "calculator": { "type": "object", "required": [ "slug", "title", "category", "version", "lastVerified", "url", "json" ], "properties": { "slug": { "type": "string" }, "title": { "type": "string" }, "category": { "type": "string" }, "description": { "type": "string" }, "version": { "type": "string", "description": "The calculator's own version; a result names the calculator that produced it." }, "lastVerified": { "type": "string", "description": "The date the calculator's sources were last checked." }, "url": { "type": "string", "description": "The calculator's page on craftquantities.com." }, "json": { "type": "string", "description": "The calculator's static API document, with its test vectors." } } }, "system": { "enum": [ "metric", "imperial" ] }, "market": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "inputs": { "type": "array", "items": { "type": "object", "required": [ "id", "label", "type", "value", "source" ], "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "type": { "enum": [ "number", "select" ] }, "value": { "type": [ "number", "string" ] }, "dimension": { "type": "string" }, "baseUnit": { "type": "string" }, "source": { "enum": [ "caller", "default" ] }, "read": { "type": "string" }, "metric": { "type": "object", "required": [ "value", "unit" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string" } } }, "imperial": { "type": "object", "required": [ "value", "unit" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string" } } }, "option": { "type": "string" } } }, "description": "Every input the calculation ran on, and where each came from." }, "result": { "type": "object", "required": [ "label", "metric", "imperial" ], "properties": { "label": { "type": "string" }, "metric": { "type": "object", "required": [ "value", "unit", "printed", "breakdown", "confidence", "isComparison", "canonical" ], "properties": { "value": { "anyOf": [ { "type": "number", "description": "The headline in this system; null where a rate it needs is not given." }, { "type": "null" } ] }, "unit": { "type": "string" }, "printed": { "anyOf": [ { "type": "string", "description": "The headline exactly as the page prints it." }, { "type": "null" } ] }, "breakdown": { "type": "array", "items": { "type": "object", "required": [ "label", "value", "unit", "printed" ], "properties": { "label": { "type": "string" }, "value": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "unit": { "type": "string" }, "printed": { "type": "string" } } } }, "confidence": { "enum": [ "high", "medium", "low" ] }, "confidenceNote": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowance": { "anyOf": [ { "type": "object", "properties": { "label": { "type": "string" }, "percent": { "type": "number" }, "base": { "type": "number" } } }, { "type": "null" } ] }, "limitations": { "type": "array", "items": { "type": "string" } }, "isComparison": { "type": "boolean", "description": "The figure is set against a limit. It is not an approval." }, "withheld": { "anyOf": [ { "type": "object", "properties": { "missingRates": { "type": "array", "items": { "type": "object", "properties": { "input": { "type": "string" }, "label": { "type": "string" } } } } } }, { "type": "null" } ] }, "canonical": { "type": "object", "required": [ "value", "unit" ], "properties": { "value": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "unit": { "type": "string" } }, "description": "The figure in the calculator's own unit, before the display adapter: what its test vectors pin." } } }, "imperial": { "type": "object", "required": [ "value", "unit", "printed", "breakdown", "confidence", "isComparison", "canonical" ], "properties": { "value": { "anyOf": [ { "type": "number", "description": "The headline in this system; null where a rate it needs is not given." }, { "type": "null" } ] }, "unit": { "type": "string" }, "printed": { "anyOf": [ { "type": "string", "description": "The headline exactly as the page prints it." }, { "type": "null" } ] }, "breakdown": { "type": "array", "items": { "type": "object", "required": [ "label", "value", "unit", "printed" ], "properties": { "label": { "type": "string" }, "value": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "unit": { "type": "string" }, "printed": { "type": "string" } } } }, "confidence": { "enum": [ "high", "medium", "low" ] }, "confidenceNote": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowance": { "anyOf": [ { "type": "object", "properties": { "label": { "type": "string" }, "percent": { "type": "number" }, "base": { "type": "number" } } }, { "type": "null" } ] }, "limitations": { "type": "array", "items": { "type": "string" } }, "isComparison": { "type": "boolean", "description": "The figure is set against a limit. It is not an approval." }, "withheld": { "anyOf": [ { "type": "object", "properties": { "missingRates": { "type": "array", "items": { "type": "object", "properties": { "input": { "type": "string" }, "label": { "type": "string" } } } } } }, { "type": "null" } ] }, "canonical": { "type": "object", "required": [ "value", "unit" ], "properties": { "value": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "unit": { "type": "string" } }, "description": "The figure in the calculator's own unit, before the display adapter: what its test vectors pin." } } } } }, "sources": { "type": "array", "items": { "type": "object", "required": [ "label" ], "properties": { "label": { "type": "string", "description": "The source as the calculator cites it." }, "url": { "type": "string", "description": "Only where the calculator gives one; none is invented." }, "references": { "type": "array", "items": { "type": "object", "required": [ "kind", "document" ], "properties": { "kind": { "enum": [ "code", "standard" ] }, "body": { "type": "string" }, "document": { "type": "string" }, "section": { "type": "string" }, "edition": { "type": "string" } } } } } } }, "citation": { "type": "object", "required": [ "author", "title", "url", "formats", "accessDate" ], "properties": { "author": { "type": "string" }, "title": { "type": "string" }, "version": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sourcesChecked": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "url": { "type": "string" }, "accessDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "formats": { "type": "object", "required": [ "plain", "apa", "harvard", "bibtex" ], "properties": { "plain": { "type": "string" }, "apa": { "type": "string" }, "harvard": { "type": "string" }, "bibtex": { "type": "string" } } } } }, "links": { "type": "object", "required": [ "page", "open" ], "properties": { "page": { "type": "string" }, "open": { "type": "string", "description": "Opens the page on these inputs." } } }, "licence": { "type": "object", "required": [ "name", "url", "attribution" ], "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "attribution": { "type": "string" } } }, "notice": { "type": "string" }, "explain": { "type": "object", "required": [ "about", "coverage", "steps", "final", "limits" ], "description": "Only when explain is true. Each figure is the calculator's own; no step is a formula written for the engine.", "properties": { "about": { "type": "string" }, "coverage": { "enum": [ "intermediates", "result-only" ], "description": "result-only: the calculator reports no figures between its inputs and its result." }, "steps": { "type": "array", "items": { "type": "object", "required": [ "n", "kind", "system", "label", "text" ], "properties": { "n": { "type": "integer" }, "kind": { "enum": [ "input", "intermediate", "result", "allowance", "range", "rates", "display" ] }, "system": { "enum": [ "metric", "imperial", "both" ] }, "label": { "type": "string" }, "value": { "anyOf": [ { "type": "number" }, { "type": "string" }, { "type": "null" } ] }, "unit": { "type": "string", "description": "The calculator's own (base) unit for the value." }, "metric": { "type": "object", "required": [ "value", "unit" ], "properties": { "value": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "unit": { "type": "string" } } }, "imperial": { "type": "object", "required": [ "value", "unit" ], "properties": { "value": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "unit": { "type": "string" } } }, "movedBy": { "type": "array", "items": { "type": "string" }, "description": "Input ids whose change moved this figure, measured by running compute again." }, "source": { "enum": [ "caller", "default" ] }, "text": { "type": "string", "description": "The step in words." } } } }, "final": { "type": "object", "required": [ "metric", "imperial" ], "properties": { "metric": { "type": "object", "required": [ "value", "unit", "printed" ], "properties": { "value": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "unit": { "type": "string" }, "printed": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, "imperial": { "type": "object", "required": [ "value", "unit", "printed" ], "properties": { "value": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "unit": { "type": "string" }, "printed": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } }, "description": "The figures the answer returns, copied from it." }, "limits": { "type": "array", "items": { "type": "string" }, "description": "What the trace does not show, and why." } } } } }, { "type": "object", "required": [ "detail", "tool", "title", "lines", "notes", "citation", "url", "open", "more" ], "properties": { "detail": { "const": "summary" }, "tool": { "type": "string" }, "title": { "type": "string" }, "lines": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "string" } }, "description": "The result lines, as the report's table gives them." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "What a professional must decide, when to call one, a false-friend warning, that adoption is local: kept in every summary." }, "citation": { "type": "string", "description": "The one citation line, built from the answer's own data." }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "open": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "more": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } ] } } } }, "400": { "description": "The request was refused; every problem is listed.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "title", "status", "problems" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "problems": { "type": "array", "items": { "type": "object", "required": [ "input", "problem" ], "properties": { "input": { "type": "string" }, "problem": { "type": "string" }, "accepted": { "type": "array", "items": { "type": "string" } } } } }, "didYouMean": { "type": "array", "items": { "type": "string" } } } } } } }, "404": { "description": "The request was refused; every problem is listed.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "title", "status", "problems" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "problems": { "type": "array", "items": { "type": "object", "required": [ "input", "problem" ], "properties": { "input": { "type": "string" }, "problem": { "type": "string" }, "accepted": { "type": "array", "items": { "type": "string" } } } } }, "didYouMean": { "type": "array", "items": { "type": "string" } } } } } } }, "413": { "description": "The request was refused; every problem is listed.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "title", "status", "problems" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "problems": { "type": "array", "items": { "type": "object", "required": [ "input", "problem" ], "properties": { "input": { "type": "string" }, "problem": { "type": "string" }, "accepted": { "type": "array", "items": { "type": "string" } } } } }, "didYouMean": { "type": "array", "items": { "type": "string" } } } } } } } }, "tags": [ "Calculators" ] } }, "/describe/{slug}": { "get": { "operationId": "getCalculator", "summary": "A calculator's inputs, units, opening values, sources and version", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,119}$", "description": "The calculator's slug, such as concrete-calculator." } }, { "name": "detail", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "full", "summary" ], "default": "full", "description": "full (the default): the whole answer. summary: the result lines, the citation line and the page only — fewer tokens to read." }, "description": "summary: the result lines, the citation and the page only (fewer tokens); full, the default: the whole answer. A POST body may carry detail instead." }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json", "md" ] }, "description": "md: the engine's Markdown report as text/markdown (or send Accept: text/markdown); json, the default." } ], "responses": { "200": { "description": "What the calculator asks for.", "content": { "application/json": { "schema": { "type": "object", "anyOf": [ { "type": "object", "required": [ "calculator", "inputs", "citation", "licence" ], "properties": { "calculator": { "type": "object", "required": [ "slug", "title", "category", "version", "lastVerified", "url", "json" ], "properties": { "slug": { "type": "string" }, "title": { "type": "string" }, "category": { "type": "string" }, "description": { "type": "string" }, "version": { "type": "string", "description": "The calculator's own version; a result names the calculator that produced it." }, "lastVerified": { "type": "string", "description": "The date the calculator's sources were last checked." }, "url": { "type": "string", "description": "The calculator's page on craftquantities.com." }, "json": { "type": "string", "description": "The calculator's static API document, with its test vectors." } } }, "inputs": { "type": "array", "items": { "type": "object", "required": [ "id", "label", "type", "help", "opening" ], "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "type": { "enum": [ "number", "select" ] }, "help": { "type": "string" }, "dimension": { "type": "string" }, "baseUnit": { "type": "string" }, "acceptedUnits": { "type": "array", "items": { "type": "string" } }, "opening": { "type": "object", "required": [ "metric", "imperial" ] }, "range": { "type": "object", "properties": { "min": { "type": "number" }, "max": { "type": "number" } } }, "options": { "type": "array", "items": { "type": "object", "required": [ "value", "label" ], "properties": { "value": { "type": "string" }, "label": { "type": "string" } } } }, "money": { "enum": [ "rate", "amount" ] } } } }, "related": { "type": "array", "items": { "type": "string" } }, "testCases": { "type": "integer" }, "changelog": { "type": "array", "items": { "type": "object", "properties": { "version": { "type": "string" }, "date": { "type": "string" }, "change": { "type": "string" } } } }, "citation": { "type": "object", "required": [ "author", "title", "url", "formats", "accessDate" ], "properties": { "author": { "type": "string" }, "title": { "type": "string" }, "version": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sourcesChecked": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "url": { "type": "string" }, "accessDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "formats": { "type": "object", "required": [ "plain", "apa", "harvard", "bibtex" ], "properties": { "plain": { "type": "string" }, "apa": { "type": "string" }, "harvard": { "type": "string" }, "bibtex": { "type": "string" } } } } }, "licence": { "type": "object", "required": [ "name", "url", "attribution" ], "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "attribution": { "type": "string" } } } } }, { "type": "object", "required": [ "detail", "tool", "title", "lines", "notes", "citation", "url", "open", "more" ], "properties": { "detail": { "const": "summary" }, "tool": { "type": "string" }, "title": { "type": "string" }, "lines": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "string" } }, "description": "The result lines, as the report's table gives them." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "What a professional must decide, when to call one, a false-friend warning, that adoption is local: kept in every summary." }, "citation": { "type": "string", "description": "The one citation line, built from the answer's own data." }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "open": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "more": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } ] } } } }, "400": { "description": "The request was refused; every problem is listed.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "title", "status", "problems" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "problems": { "type": "array", "items": { "type": "object", "required": [ "input", "problem" ], "properties": { "input": { "type": "string" }, "problem": { "type": "string" }, "accepted": { "type": "array", "items": { "type": "string" } } } } }, "didYouMean": { "type": "array", "items": { "type": "string" } } } } } } }, "404": { "description": "The request was refused; every problem is listed.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "title", "status", "problems" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "problems": { "type": "array", "items": { "type": "object", "required": [ "input", "problem" ], "properties": { "input": { "type": "string" }, "problem": { "type": "string" }, "accepted": { "type": "array", "items": { "type": "string" } } } } }, "didYouMean": { "type": "array", "items": { "type": "string" } } } } } } } }, "tags": [ "Calculators" ] } }, "/sources/{slug}": { "get": { "operationId": "getSources", "summary": "A calculator's sources and a citation", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,119}$", "description": "The calculator's slug, such as concrete-calculator." } }, { "name": "detail", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "full", "summary" ], "default": "full", "description": "full (the default): the whole answer. summary: the result lines, the citation line and the page only — fewer tokens to read." }, "description": "summary: the result lines, the citation and the page only (fewer tokens); full, the default: the whole answer. A POST body may carry detail instead." }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json", "md" ] }, "description": "md: the engine's Markdown report as text/markdown (or send Accept: text/markdown); json, the default." } ], "responses": { "200": { "description": "The sources as the calculator cites them.", "content": { "application/json": { "schema": { "type": "object", "anyOf": [ { "type": "object", "required": [ "calculator", "sources", "standards", "citation", "licence" ], "properties": { "calculator": { "type": "object", "required": [ "slug", "title", "category", "version", "lastVerified", "url", "json" ], "properties": { "slug": { "type": "string" }, "title": { "type": "string" }, "category": { "type": "string" }, "description": { "type": "string" }, "version": { "type": "string", "description": "The calculator's own version; a result names the calculator that produced it." }, "lastVerified": { "type": "string", "description": "The date the calculator's sources were last checked." }, "url": { "type": "string", "description": "The calculator's page on craftquantities.com." }, "json": { "type": "string", "description": "The calculator's static API document, with its test vectors." } } }, "sources": { "type": "array", "items": { "type": "object", "required": [ "label" ], "properties": { "label": { "type": "string", "description": "The source as the calculator cites it." }, "url": { "type": "string", "description": "Only where the calculator gives one; none is invented." }, "references": { "type": "array", "items": { "type": "object", "required": [ "kind", "document" ], "properties": { "kind": { "enum": [ "code", "standard" ] }, "body": { "type": "string" }, "document": { "type": "string" }, "section": { "type": "string" }, "edition": { "type": "string" } } } } } } }, "standards": { "type": "array", "items": { "type": "object", "required": [ "title", "page" ], "properties": { "title": { "type": "string" }, "page": { "type": "string" }, "publisher": { "type": "string" } } } }, "citation": { "type": "object", "required": [ "author", "title", "url", "formats", "accessDate" ], "properties": { "author": { "type": "string" }, "title": { "type": "string" }, "version": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sourcesChecked": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "url": { "type": "string" }, "accessDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "formats": { "type": "object", "required": [ "plain", "apa", "harvard", "bibtex" ], "properties": { "plain": { "type": "string" }, "apa": { "type": "string" }, "harvard": { "type": "string" }, "bibtex": { "type": "string" } } } } }, "licence": { "type": "object", "required": [ "name", "url", "attribution" ], "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "attribution": { "type": "string" } } } } }, { "type": "object", "required": [ "detail", "tool", "title", "lines", "notes", "citation", "url", "open", "more" ], "properties": { "detail": { "const": "summary" }, "tool": { "type": "string" }, "title": { "type": "string" }, "lines": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "string" } }, "description": "The result lines, as the report's table gives them." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "What a professional must decide, when to call one, a false-friend warning, that adoption is local: kept in every summary." }, "citation": { "type": "string", "description": "The one citation line, built from the answer's own data." }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "open": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "more": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } ] } } } }, "400": { "description": "The request was refused; every problem is listed.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "title", "status", "problems" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "problems": { "type": "array", "items": { "type": "object", "required": [ "input", "problem" ], "properties": { "input": { "type": "string" }, "problem": { "type": "string" }, "accepted": { "type": "array", "items": { "type": "string" } } } } }, "didYouMean": { "type": "array", "items": { "type": "string" } } } } } } }, "404": { "description": "The request was refused; every problem is listed.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "title", "status", "problems" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "problems": { "type": "array", "items": { "type": "object", "required": [ "input", "problem" ], "properties": { "input": { "type": "string" }, "problem": { "type": "string" }, "accepted": { "type": "array", "items": { "type": "string" } } } } }, "didYouMean": { "type": "array", "items": { "type": "string" } } } } } } } }, "tags": [ "Calculators" ] } }, "/link/{slug}": { "get": { "operationId": "openInSiteLink", "summary": "A link that opens the page with these inputs", "description": "Every other query parameter is an input id, its value written with its unit where it measures something: slabLength=3%20m, slabThickness=4%20in.", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,119}$", "description": "The calculator's slug, such as concrete-calculator." } }, { "name": "system", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "metric", "imperial" ], "default": "metric", "description": "The unit system inputs left out open in, and the one the page link opens in. The answer comes in both." } }, { "name": "market", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "US", "CA", "UK", "AU", "INTL" ], "description": "Optional. A market whose own opening choice some inputs take (a UK reader's code, an IEC motor), and whose currency symbol prints the caller's own money figures." } }, { "name": "inputUnits", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "base" ], "description": "Send \"base\" to pass bare numbers on dimensioned inputs in base units (m, m², L, kg …), as the published test vectors are written. Without it a length, area or volume must carry its unit." } }, { "name": "detail", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "full", "summary" ], "default": "full", "description": "full (the default): the whole answer. summary: the result lines, the citation line and the page only — fewer tokens to read." }, "description": "summary: the result lines, the citation and the page only (fewer tokens); full, the default: the whole answer. A POST body may carry detail instead." }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json", "md" ] }, "description": "md: the engine's Markdown report as text/markdown (or send Accept: text/markdown); json, the default." } ], "responses": { "200": { "description": "The link, and the inputs it carries.", "content": { "application/json": { "schema": { "type": "object", "anyOf": [ { "type": "object", "required": [ "url", "page", "inputs" ], "properties": { "url": { "type": "string", "description": "Opens the calculator's page on these inputs, in the chosen system." }, "page": { "type": "string" }, "inputs": { "type": "array", "items": { "type": "object", "required": [ "id", "label", "type", "value", "source" ], "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "type": { "enum": [ "number", "select" ] }, "value": { "type": [ "number", "string" ] }, "dimension": { "type": "string" }, "baseUnit": { "type": "string" }, "source": { "enum": [ "caller", "default" ] }, "read": { "type": "string" }, "metric": { "type": "object", "required": [ "value", "unit" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string" } } }, "imperial": { "type": "object", "required": [ "value", "unit" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string" } } }, "option": { "type": "string" } } } } } }, { "type": "object", "required": [ "detail", "tool", "title", "lines", "notes", "citation", "url", "open", "more" ], "properties": { "detail": { "const": "summary" }, "tool": { "type": "string" }, "title": { "type": "string" }, "lines": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "string" } }, "description": "The result lines, as the report's table gives them." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "What a professional must decide, when to call one, a false-friend warning, that adoption is local: kept in every summary." }, "citation": { "type": "string", "description": "The one citation line, built from the answer's own data." }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "open": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "more": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } ] } } } }, "400": { "description": "The request was refused; every problem is listed.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "title", "status", "problems" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "problems": { "type": "array", "items": { "type": "object", "required": [ "input", "problem" ], "properties": { "input": { "type": "string" }, "problem": { "type": "string" }, "accepted": { "type": "array", "items": { "type": "string" } } } } }, "didYouMean": { "type": "array", "items": { "type": "string" } } } } } } }, "404": { "description": "The request was refused; every problem is listed.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "title", "status", "problems" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "problems": { "type": "array", "items": { "type": "object", "required": [ "input", "problem" ], "properties": { "input": { "type": "string" }, "problem": { "type": "string" }, "accepted": { "type": "array", "items": { "type": "string" } } } } }, "didYouMean": { "type": "array", "items": { "type": "string" } } } } } } } }, "tags": [ "Calculators" ] } }, "/search": { "get": { "operationId": "search", "summary": "Find a calculator", "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "What the job is, in US, UK or Australian words." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 25, "default": 10 } }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json", "md" ] }, "description": "md: the engine's Markdown report as text/markdown (or send Accept: text/markdown); json, the default." } ], "responses": { "200": { "description": "Calculators, best first.", "content": { "application/json": { "schema": { "type": "object", "required": [ "results" ], "properties": { "results": { "type": "array", "items": { "type": "object", "required": [ "id", "title", "url" ], "properties": { "id": { "type": "string", "description": "The result's id: calculator:{slug}, takeoff:{id}, example:{slug} or diagnosis:{slug}." }, "kind": { "enum": [ "calculator", "takeoff", "example", "diagnosis" ] }, "title": { "type": "string" }, "url": { "type": "string" }, "description": { "type": "string" }, "category": { "type": "string" }, "slug": { "type": "string" } } } } } } } } }, "400": { "description": "The request was refused; every problem is listed.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "title", "status", "problems" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "problems": { "type": "array", "items": { "type": "object", "required": [ "input", "problem" ], "properties": { "input": { "type": "string" }, "problem": { "type": "string" }, "accepted": { "type": "array", "items": { "type": "string" } } } } }, "didYouMean": { "type": "array", "items": { "type": "string" } } } } } } } }, "tags": [ "Discovery" ] } }, "/takeoff/{id}": { "get": { "operationId": "getTakeoff", "summary": "A whole-job takeoff's measurements, build-up choices and calculators", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,119}$" } }, { "name": "detail", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "full", "summary" ], "default": "full", "description": "full (the default): the whole answer. summary: the result lines, the citation line and the page only — fewer tokens to read." }, "description": "summary: the result lines, the citation and the page only (fewer tokens); full, the default: the whole answer. A POST body may carry detail instead." }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json", "md" ] }, "description": "md: the engine's Markdown report as text/markdown (or send Accept: text/markdown); json, the default." } ], "responses": { "200": { "description": "What the takeoff asks for.", "content": { "application/json": { "schema": { "type": "object", "anyOf": [ { "type": "object", "required": [ "takeoff", "measurements", "choices", "steps", "excludes", "citation", "licence" ], "properties": { "takeoff": { "type": "object", "required": [ "id", "name", "category", "description", "url" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "category": { "type": "string" }, "description": { "type": "string" }, "url": { "type": "string", "description": "The takeoff's page on craftquantities.com." } } }, "measurements": { "type": "array", "items": { "type": "object", "required": [ "id", "label", "opening" ], "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "help": { "type": "string" }, "dimension": { "type": "string" }, "acceptedUnits": { "type": "array", "items": { "type": "string" } }, "opening": { "type": "object" }, "basis": { "type": "object", "description": "Where a figure comes from: a source the site publishes, or the reason there is none.", "properties": { "unsourced": { "type": "string" }, "source": { "type": "object", "required": [ "kind" ], "properties": { "kind": { "type": "string" } } } } } } } }, "choices": { "type": "array", "items": { "type": "object", "required": [ "id", "label", "options", "opening" ], "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "options": { "type": "array", "items": { "type": "object", "required": [ "id", "label" ] } }, "opening": { "type": "object" } } } }, "steps": { "type": "array", "items": { "type": "object", "required": [ "key", "calculator", "name" ] } }, "excludes": { "type": "array", "items": { "type": "string" } }, "citation": { "type": "object", "required": [ "author", "title", "url", "formats", "accessDate" ], "properties": { "author": { "type": "string" }, "title": { "type": "string" }, "version": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sourcesChecked": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "url": { "type": "string" }, "accessDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "formats": { "type": "object", "required": [ "plain", "apa", "harvard", "bibtex" ], "properties": { "plain": { "type": "string" }, "apa": { "type": "string" }, "harvard": { "type": "string" }, "bibtex": { "type": "string" } } } } }, "licence": { "type": "object", "required": [ "name", "url", "attribution" ], "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "attribution": { "type": "string" } } } } }, { "type": "object", "required": [ "detail", "tool", "title", "lines", "notes", "citation", "url", "open", "more" ], "properties": { "detail": { "const": "summary" }, "tool": { "type": "string" }, "title": { "type": "string" }, "lines": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "string" } }, "description": "The result lines, as the report's table gives them." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "What a professional must decide, when to call one, a false-friend warning, that adoption is local: kept in every summary." }, "citation": { "type": "string", "description": "The one citation line, built from the answer's own data." }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "open": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "more": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } ] } } } }, "400": { "description": "The request was refused; every problem is listed.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "title", "status", "problems" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "problems": { "type": "array", "items": { "type": "object", "required": [ "input", "problem" ], "properties": { "input": { "type": "string" }, "problem": { "type": "string" }, "accepted": { "type": "array", "items": { "type": "string" } } } } }, "didYouMean": { "type": "array", "items": { "type": "string" } } } } } } }, "404": { "description": "The request was refused; every problem is listed.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "title", "status", "problems" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "problems": { "type": "array", "items": { "type": "object", "required": [ "input", "problem" ], "properties": { "input": { "type": "string" }, "problem": { "type": "string" }, "accepted": { "type": "array", "items": { "type": "string" } } } } }, "didYouMean": { "type": "array", "items": { "type": "string" } } } } } } } }, "tags": [ "Takeoffs" ] } }, "/takeoff/{id}/run": { "get": { "operationId": "runTakeoffGet", "summary": "Work a takeoff (measurements in the query, build-up choices as v.{choice})", "description": "The same query the takeoff page's own link carries: each measurement under its id, written with its unit; each build-up choice as v.{choice}={option}.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "system", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "metric", "imperial" ], "default": "metric", "description": "The unit system inputs left out open in, and the one the page link opens in. The answer comes in both." } }, { "name": "market", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "US", "CA", "UK", "AU", "INTL" ], "description": "Optional. A market whose own opening choice some inputs take (a UK reader's code, an IEC motor), and whose currency symbol prints the caller's own money figures." } }, { "name": "inputUnits", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "base" ], "description": "Send \"base\" to pass bare numbers on dimensioned inputs in base units (m, m², L, kg …), as the published test vectors are written. Without it a length, area or volume must carry its unit." } }, { "name": "detail", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "full", "summary" ], "default": "full", "description": "full (the default): the whole answer. summary: the result lines, the citation line and the page only — fewer tokens to read." }, "description": "summary: the result lines, the citation and the page only (fewer tokens); full, the default: the whole answer. A POST body may carry detail instead." }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json", "md" ] }, "description": "md: the engine's Markdown report as text/markdown (or send Accept: text/markdown); json, the default." } ], "responses": { "200": { "description": "Every row, with its quantity, order, working and sources.", "content": { "application/json": { "schema": { "type": "object", "anyOf": [ { "type": "object", "required": [ "engine", "takeoff", "system", "selection", "measurements", "rows", "sizingWithheld", "labour", "excludes", "sources", "citation", "links", "licence", "notice" ], "properties": { "engine": { "type": "object" }, "takeoff": { "type": "object", "required": [ "id", "name", "category", "description", "url" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "category": { "type": "string" }, "description": { "type": "string" }, "url": { "type": "string", "description": "The takeoff's page on craftquantities.com." } } }, "system": { "enum": [ "metric", "imperial" ] }, "market": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "selection": { "type": "object", "additionalProperties": { "type": "string" } }, "measurements": { "type": "array", "items": { "type": "object", "required": [ "id", "label", "value", "source" ], "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "value": { "type": "number" }, "dimension": { "type": "string" }, "baseUnit": { "type": "string" }, "source": { "enum": [ "caller", "default" ] }, "read": { "type": "string" }, "metric": { "type": "object", "required": [ "value", "unit" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string" } } }, "imperial": { "type": "object", "required": [ "value", "unit" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string" } } }, "basis": { "type": "object", "description": "Where a figure comes from: a source the site publishes, or the reason there is none.", "properties": { "unsourced": { "type": "string" }, "source": { "type": "object", "required": [ "kind" ], "properties": { "kind": { "type": "string" } } } } } } } }, "rows": { "type": "array", "items": { "type": "object", "required": [ "key", "name", "calculator", "state", "quantity", "unit", "order", "chain", "printed", "otherSystem", "inputs" ], "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "calculator": { "type": "object", "required": [ "slug", "title", "url" ], "properties": { "slug": { "type": "string" }, "title": { "type": "string" }, "version": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "url": { "type": "string" } } }, "state": { "enum": [ "ready", "untraced", "pending", "failed", "no-answer" ] }, "quantity": { "anyOf": [ { "type": "number", "description": "What a project line carries, after any allowance, in this system's unit." }, { "type": "null" } ] }, "unit": { "type": "string" }, "order": { "anyOf": [ { "type": "object", "required": [ "quantity", "unit", "rule" ], "properties": { "quantity": { "type": "number" }, "unit": { "type": "string" }, "rule": { "enum": [ "pack", "whole", "as-measured" ] } } }, { "type": "null" } ] }, "chain": { "anyOf": [ { "type": "object", "properties": { "mode": { "type": "string" }, "base": { "type": "number" }, "allowanceName": { "type": "string" }, "allowancePercent": { "type": "number" }, "calculatorVersion": { "type": "string" } } }, { "type": "null" } ] }, "printed": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "otherSystem": { "anyOf": [ { "type": "object", "required": [ "quantity", "unit" ], "properties": { "quantity": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "unit": { "type": "string" } } }, { "type": "null" } ] }, "inputs": { "type": "array", "items": { "type": "object", "required": [ "id", "value", "origin" ], "properties": { "id": { "type": "string" }, "value": { "type": [ "number", "string" ] }, "origin": { "type": "string" }, "basis": { "type": "object", "description": "Where a figure comes from: a source the site publishes, or the reason there is none.", "properties": { "unsourced": { "type": "string" }, "source": { "type": "object", "required": [ "kind" ], "properties": { "kind": { "type": "string" } } } } } } } }, "note": { "type": "string" }, "alternativeTo": { "type": "string" }, "leftOut": { "type": "boolean" }, "labourHours": { "anyOf": [ { "type": "object", "required": [ "low", "likely", "high" ], "properties": { "low": { "type": "number" }, "likely": { "type": "number" }, "high": { "type": "number" } } }, { "type": "null" } ] } } } }, "sizingWithheld": { "type": "array", "items": { "type": "string" } }, "labour": { "type": "object", "required": [ "rows", "totalHours", "programme", "likelyDays", "note" ], "properties": { "rows": { "type": "array", "items": { "type": "object", "required": [ "key", "name", "kind" ], "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "kind": { "enum": [ "rated", "part", "not-rated", "unmeasured", "no-work", "sizing" ] }, "hours": { "type": "object", "required": [ "low", "likely", "high" ], "properties": { "low": { "type": "number" }, "likely": { "type": "number" }, "high": { "type": "number" } } }, "rate": { "type": "object", "properties": { "id": { "type": "string" }, "operation": { "type": "string" }, "personHoursPerUnit": { "type": "object", "required": [ "low", "likely", "high" ], "properties": { "low": { "type": "number" }, "likely": { "type": "number" }, "high": { "type": "number" } } }, "per": { "type": "string" }, "basis": { "type": "string" }, "source": { "type": "string" }, "whatMovesIt": { "type": "string" } } }, "countedWith": { "type": "array", "items": { "type": "string" } }, "reason": { "type": "string" }, "unit": { "type": "string" } } } }, "totalHours": { "type": "object", "required": [ "low", "likely", "high" ], "properties": { "low": { "type": "number" }, "likely": { "type": "number" }, "high": { "type": "number" } } }, "programme": { "type": "array", "items": { "type": "object", "required": [ "trade", "crew", "rows", "hours", "days", "startDay" ] } }, "likelyDays": { "type": "number" }, "note": { "type": "string" } } }, "excludes": { "type": "array", "items": { "type": "string" } }, "sources": { "type": "array", "items": { "type": "object", "required": [ "calculator", "title", "version", "sources" ], "properties": { "calculator": { "type": "string" }, "title": { "type": "string" }, "version": { "type": "string" }, "sources": { "type": "array", "items": { "type": "object", "required": [ "label" ], "properties": { "label": { "type": "string", "description": "The source as the calculator cites it." }, "url": { "type": "string", "description": "Only where the calculator gives one; none is invented." }, "references": { "type": "array", "items": { "type": "object", "required": [ "kind", "document" ], "properties": { "kind": { "enum": [ "code", "standard" ] }, "body": { "type": "string" }, "document": { "type": "string" }, "section": { "type": "string" }, "edition": { "type": "string" } } } } } } } } } }, "citation": { "type": "object", "required": [ "author", "title", "url", "formats", "accessDate" ], "properties": { "author": { "type": "string" }, "title": { "type": "string" }, "version": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sourcesChecked": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "url": { "type": "string" }, "accessDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "formats": { "type": "object", "required": [ "plain", "apa", "harvard", "bibtex" ], "properties": { "plain": { "type": "string" }, "apa": { "type": "string" }, "harvard": { "type": "string" }, "bibtex": { "type": "string" } } } } }, "links": { "type": "object", "required": [ "page", "open" ], "properties": { "page": { "type": "string" }, "open": { "type": "string", "description": "Opens the takeoff page on this job." } } }, "licence": { "type": "object", "required": [ "name", "url", "attribution" ], "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "attribution": { "type": "string" } } }, "notice": { "type": "string" } } }, { "type": "object", "required": [ "detail", "tool", "title", "lines", "notes", "citation", "url", "open", "more" ], "properties": { "detail": { "const": "summary" }, "tool": { "type": "string" }, "title": { "type": "string" }, "lines": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "string" } }, "description": "The result lines, as the report's table gives them." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "What a professional must decide, when to call one, a false-friend warning, that adoption is local: kept in every summary." }, "citation": { "type": "string", "description": "The one citation line, built from the answer's own data." }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "open": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "more": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } ] } } } }, "400": { "description": "The request was refused; every problem is listed.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "title", "status", "problems" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "problems": { "type": "array", "items": { "type": "object", "required": [ "input", "problem" ], "properties": { "input": { "type": "string" }, "problem": { "type": "string" }, "accepted": { "type": "array", "items": { "type": "string" } } } } }, "didYouMean": { "type": "array", "items": { "type": "string" } } } } } } }, "404": { "description": "The request was refused; every problem is listed.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "title", "status", "problems" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "problems": { "type": "array", "items": { "type": "object", "required": [ "input", "problem" ], "properties": { "input": { "type": "string" }, "problem": { "type": "string" }, "accepted": { "type": "array", "items": { "type": "string" } } } } }, "didYouMean": { "type": "array", "items": { "type": "string" } } } } } } } }, "tags": [ "Takeoffs" ] }, "post": { "operationId": "runTakeoff", "summary": "Work a takeoff", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "detail", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "full", "summary" ], "default": "full", "description": "full (the default): the whole answer. summary: the result lines, the citation line and the page only — fewer tokens to read." }, "description": "summary: the result lines, the citation and the page only (fewer tokens); full, the default: the whole answer. A POST body may carry detail instead." }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json", "md" ] }, "description": "md: the engine's Markdown report as text/markdown (or send Accept: text/markdown); json, the default." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "measurements": { "type": "object", "maxProperties": 50, "description": "Measurement id → value, each length, area or volume with its unit (\"12 ft\", {\"value\": 3.6, \"unit\": \"m\"}); counts as numbers. Ids are those of the takeoff; any left out opens at the page's own figure.", "additionalProperties": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] } }, "selection": { "type": "object", "maxProperties": 20, "description": "Build-up choice id → option id, the takeoff's own (a stud size, an insulation, a cladding). Choices left out take the page's own for the system.", "additionalProperties": { "type": "string", "maxLength": 80 } }, "allowances": { "type": "object", "maxProperties": 50, "description": "Row → an allowance the reader sets: a percentage (cutting waste, overlap), or the option an allowance follows (a lay pattern). Row names are the takeoff's steps (the calculator slug, or the step key where one runs twice).", "additionalProperties": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 100 }, { "type": "string", "maxLength": 80 } ] } }, "leaveOut": { "type": "array", "maxItems": 100, "items": { "type": "string", "maxLength": 120 }, "description": "Rows the reader leaves out of the job: still worked and shown, not put in the project or counted in labour." }, "system": { "type": "string", "enum": [ "metric", "imperial" ], "default": "metric", "description": "The unit system inputs left out open in, and the one the page link opens in. The answer comes in both." }, "market": { "type": "string", "enum": [ "US", "CA", "UK", "AU", "INTL" ], "description": "Optional. A market whose own opening choice some inputs take (a UK reader's code, an IEC motor), and whose currency symbol prints the caller's own money figures." }, "inputUnits": { "type": "string", "enum": [ "base" ], "description": "Send \"base\" to pass bare numbers on dimensioned inputs in base units (m, m², L, kg …), as the published test vectors are written. Without it a length, area or volume must carry its unit." } } } } } }, "responses": { "200": { "description": "Every row, with its quantity, order, working and sources.", "content": { "application/json": { "schema": { "type": "object", "anyOf": [ { "type": "object", "required": [ "engine", "takeoff", "system", "selection", "measurements", "rows", "sizingWithheld", "labour", "excludes", "sources", "citation", "links", "licence", "notice" ], "properties": { "engine": { "type": "object" }, "takeoff": { "type": "object", "required": [ "id", "name", "category", "description", "url" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "category": { "type": "string" }, "description": { "type": "string" }, "url": { "type": "string", "description": "The takeoff's page on craftquantities.com." } } }, "system": { "enum": [ "metric", "imperial" ] }, "market": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "selection": { "type": "object", "additionalProperties": { "type": "string" } }, "measurements": { "type": "array", "items": { "type": "object", "required": [ "id", "label", "value", "source" ], "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "value": { "type": "number" }, "dimension": { "type": "string" }, "baseUnit": { "type": "string" }, "source": { "enum": [ "caller", "default" ] }, "read": { "type": "string" }, "metric": { "type": "object", "required": [ "value", "unit" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string" } } }, "imperial": { "type": "object", "required": [ "value", "unit" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string" } } }, "basis": { "type": "object", "description": "Where a figure comes from: a source the site publishes, or the reason there is none.", "properties": { "unsourced": { "type": "string" }, "source": { "type": "object", "required": [ "kind" ], "properties": { "kind": { "type": "string" } } } } } } } }, "rows": { "type": "array", "items": { "type": "object", "required": [ "key", "name", "calculator", "state", "quantity", "unit", "order", "chain", "printed", "otherSystem", "inputs" ], "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "calculator": { "type": "object", "required": [ "slug", "title", "url" ], "properties": { "slug": { "type": "string" }, "title": { "type": "string" }, "version": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "url": { "type": "string" } } }, "state": { "enum": [ "ready", "untraced", "pending", "failed", "no-answer" ] }, "quantity": { "anyOf": [ { "type": "number", "description": "What a project line carries, after any allowance, in this system's unit." }, { "type": "null" } ] }, "unit": { "type": "string" }, "order": { "anyOf": [ { "type": "object", "required": [ "quantity", "unit", "rule" ], "properties": { "quantity": { "type": "number" }, "unit": { "type": "string" }, "rule": { "enum": [ "pack", "whole", "as-measured" ] } } }, { "type": "null" } ] }, "chain": { "anyOf": [ { "type": "object", "properties": { "mode": { "type": "string" }, "base": { "type": "number" }, "allowanceName": { "type": "string" }, "allowancePercent": { "type": "number" }, "calculatorVersion": { "type": "string" } } }, { "type": "null" } ] }, "printed": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "otherSystem": { "anyOf": [ { "type": "object", "required": [ "quantity", "unit" ], "properties": { "quantity": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "unit": { "type": "string" } } }, { "type": "null" } ] }, "inputs": { "type": "array", "items": { "type": "object", "required": [ "id", "value", "origin" ], "properties": { "id": { "type": "string" }, "value": { "type": [ "number", "string" ] }, "origin": { "type": "string" }, "basis": { "type": "object", "description": "Where a figure comes from: a source the site publishes, or the reason there is none.", "properties": { "unsourced": { "type": "string" }, "source": { "type": "object", "required": [ "kind" ], "properties": { "kind": { "type": "string" } } } } } } } }, "note": { "type": "string" }, "alternativeTo": { "type": "string" }, "leftOut": { "type": "boolean" }, "labourHours": { "anyOf": [ { "type": "object", "required": [ "low", "likely", "high" ], "properties": { "low": { "type": "number" }, "likely": { "type": "number" }, "high": { "type": "number" } } }, { "type": "null" } ] } } } }, "sizingWithheld": { "type": "array", "items": { "type": "string" } }, "labour": { "type": "object", "required": [ "rows", "totalHours", "programme", "likelyDays", "note" ], "properties": { "rows": { "type": "array", "items": { "type": "object", "required": [ "key", "name", "kind" ], "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "kind": { "enum": [ "rated", "part", "not-rated", "unmeasured", "no-work", "sizing" ] }, "hours": { "type": "object", "required": [ "low", "likely", "high" ], "properties": { "low": { "type": "number" }, "likely": { "type": "number" }, "high": { "type": "number" } } }, "rate": { "type": "object", "properties": { "id": { "type": "string" }, "operation": { "type": "string" }, "personHoursPerUnit": { "type": "object", "required": [ "low", "likely", "high" ], "properties": { "low": { "type": "number" }, "likely": { "type": "number" }, "high": { "type": "number" } } }, "per": { "type": "string" }, "basis": { "type": "string" }, "source": { "type": "string" }, "whatMovesIt": { "type": "string" } } }, "countedWith": { "type": "array", "items": { "type": "string" } }, "reason": { "type": "string" }, "unit": { "type": "string" } } } }, "totalHours": { "type": "object", "required": [ "low", "likely", "high" ], "properties": { "low": { "type": "number" }, "likely": { "type": "number" }, "high": { "type": "number" } } }, "programme": { "type": "array", "items": { "type": "object", "required": [ "trade", "crew", "rows", "hours", "days", "startDay" ] } }, "likelyDays": { "type": "number" }, "note": { "type": "string" } } }, "excludes": { "type": "array", "items": { "type": "string" } }, "sources": { "type": "array", "items": { "type": "object", "required": [ "calculator", "title", "version", "sources" ], "properties": { "calculator": { "type": "string" }, "title": { "type": "string" }, "version": { "type": "string" }, "sources": { "type": "array", "items": { "type": "object", "required": [ "label" ], "properties": { "label": { "type": "string", "description": "The source as the calculator cites it." }, "url": { "type": "string", "description": "Only where the calculator gives one; none is invented." }, "references": { "type": "array", "items": { "type": "object", "required": [ "kind", "document" ], "properties": { "kind": { "enum": [ "code", "standard" ] }, "body": { "type": "string" }, "document": { "type": "string" }, "section": { "type": "string" }, "edition": { "type": "string" } } } } } } } } } }, "citation": { "type": "object", "required": [ "author", "title", "url", "formats", "accessDate" ], "properties": { "author": { "type": "string" }, "title": { "type": "string" }, "version": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sourcesChecked": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "url": { "type": "string" }, "accessDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "formats": { "type": "object", "required": [ "plain", "apa", "harvard", "bibtex" ], "properties": { "plain": { "type": "string" }, "apa": { "type": "string" }, "harvard": { "type": "string" }, "bibtex": { "type": "string" } } } } }, "links": { "type": "object", "required": [ "page", "open" ], "properties": { "page": { "type": "string" }, "open": { "type": "string", "description": "Opens the takeoff page on this job." } } }, "licence": { "type": "object", "required": [ "name", "url", "attribution" ], "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "attribution": { "type": "string" } } }, "notice": { "type": "string" } } }, { "type": "object", "required": [ "detail", "tool", "title", "lines", "notes", "citation", "url", "open", "more" ], "properties": { "detail": { "const": "summary" }, "tool": { "type": "string" }, "title": { "type": "string" }, "lines": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "string" } }, "description": "The result lines, as the report's table gives them." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "What a professional must decide, when to call one, a false-friend warning, that adoption is local: kept in every summary." }, "citation": { "type": "string", "description": "The one citation line, built from the answer's own data." }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "open": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "more": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } ] } } } }, "400": { "description": "The request was refused; every problem is listed.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "title", "status", "problems" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "problems": { "type": "array", "items": { "type": "object", "required": [ "input", "problem" ], "properties": { "input": { "type": "string" }, "problem": { "type": "string" }, "accepted": { "type": "array", "items": { "type": "string" } } } } }, "didYouMean": { "type": "array", "items": { "type": "string" } } } } } } }, "404": { "description": "The request was refused; every problem is listed.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "title", "status", "problems" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "problems": { "type": "array", "items": { "type": "object", "required": [ "input", "problem" ], "properties": { "input": { "type": "string" }, "problem": { "type": "string" }, "accepted": { "type": "array", "items": { "type": "string" } } } } }, "didYouMean": { "type": "array", "items": { "type": "string" } } } } } } } }, "tags": [ "Takeoffs" ] } }, "/example/{slug}": { "get": { "operationId": "getExample", "summary": "A worked example as published", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,119}$", "description": "The calculator's slug, such as concrete-calculator." } }, { "name": "detail", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "full", "summary" ], "default": "full", "description": "full (the default): the whole answer. summary: the result lines, the citation line and the page only — fewer tokens to read." }, "description": "summary: the result lines, the citation and the page only (fewer tokens); full, the default: the whole answer. A POST body may carry detail instead." }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json", "md" ] }, "description": "md: the engine's Markdown report as text/markdown (or send Accept: text/markdown); json, the default." } ], "responses": { "200": { "description": "The example's measurements and steps.", "content": { "application/json": { "schema": { "type": "object", "anyOf": [ { "type": "object", "required": [ "example", "measurements", "steps", "wasteFactors", "citation", "licence" ], "properties": { "example": { "type": "object", "required": [ "slug", "title", "job", "market", "system", "basis", "summary", "url" ], "properties": { "slug": { "type": "string" }, "title": { "type": "string" }, "job": { "type": "string" }, "market": { "type": "string" }, "system": { "enum": [ "metric", "imperial" ] }, "basis": { "enum": [ "modelled", "recorded" ] }, "summary": { "type": "string" }, "published": { "type": "string" }, "updated": { "type": "string" }, "url": { "type": "string" }, "takeoff": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, "measurements": { "type": "array", "items": { "type": "object", "required": [ "what", "how", "value" ] } }, "steps": { "type": "array", "items": { "type": "object", "required": [ "step", "calculator", "needs", "produces", "run" ] } }, "wasteFactors": { "type": "array", "items": { "type": "object", "required": [ "material", "factor", "why" ] } }, "citation": { "type": "object", "required": [ "author", "title", "url", "formats", "accessDate" ], "properties": { "author": { "type": "string" }, "title": { "type": "string" }, "version": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sourcesChecked": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "url": { "type": "string" }, "accessDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "formats": { "type": "object", "required": [ "plain", "apa", "harvard", "bibtex" ], "properties": { "plain": { "type": "string" }, "apa": { "type": "string" }, "harvard": { "type": "string" }, "bibtex": { "type": "string" } } } } }, "licence": { "type": "object", "required": [ "name", "url", "attribution" ], "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "attribution": { "type": "string" } } } } }, { "type": "object", "required": [ "detail", "tool", "title", "lines", "notes", "citation", "url", "open", "more" ], "properties": { "detail": { "const": "summary" }, "tool": { "type": "string" }, "title": { "type": "string" }, "lines": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "string" } }, "description": "The result lines, as the report's table gives them." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "What a professional must decide, when to call one, a false-friend warning, that adoption is local: kept in every summary." }, "citation": { "type": "string", "description": "The one citation line, built from the answer's own data." }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "open": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "more": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } ] } } } }, "404": { "description": "The request was refused; every problem is listed.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "title", "status", "problems" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "problems": { "type": "array", "items": { "type": "object", "required": [ "input", "problem" ], "properties": { "input": { "type": "string" }, "problem": { "type": "string" }, "accepted": { "type": "array", "items": { "type": "string" } } } } }, "didYouMean": { "type": "array", "items": { "type": "string" } } } } } } } }, "tags": [ "Worked examples" ] } }, "/example/{slug}/run": { "get": { "operationId": "runExample", "summary": "Re-run a worked example's pinned steps", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,119}$", "description": "The calculator's slug, such as concrete-calculator." } }, { "name": "detail", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "full", "summary" ], "default": "full", "description": "full (the default): the whole answer. summary: the result lines, the citation line and the page only — fewer tokens to read." }, "description": "summary: the result lines, the citation and the page only (fewer tokens); full, the default: the whole answer. A POST body may carry detail instead." }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json", "md" ] }, "description": "md: the engine's Markdown report as text/markdown (or send Accept: text/markdown); json, the default." } ], "responses": { "200": { "description": "Each step now, and whether it meets the published figure.", "content": { "application/json": { "schema": { "type": "object", "anyOf": [ { "type": "object", "required": [ "engine", "example", "steps", "unpinned", "allMeet", "citation", "licence", "notice" ], "properties": { "engine": { "type": "object" }, "example": { "type": "object", "required": [ "slug", "title", "job", "market", "system", "basis", "summary", "url" ], "properties": { "slug": { "type": "string" }, "title": { "type": "string" }, "job": { "type": "string" }, "market": { "type": "string" }, "system": { "enum": [ "metric", "imperial" ] }, "basis": { "enum": [ "modelled", "recorded" ] }, "summary": { "type": "string" }, "published": { "type": "string" }, "updated": { "type": "string" }, "url": { "type": "string" }, "takeoff": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, "steps": { "type": "array", "items": { "type": "object", "required": [ "step", "calculator", "answer", "otherSystem", "canonical", "expect", "places", "meets", "shown", "link" ], "properties": { "step": { "type": "string" }, "calculator": { "type": "object" }, "answer": { "type": "object" }, "otherSystem": { "type": "object" }, "canonical": { "type": "object" }, "expect": { "type": "number" }, "places": { "type": "integer" }, "meets": { "type": "boolean" }, "shown": { "type": "string" }, "link": { "type": "string" } } } }, "unpinned": { "type": "array", "items": { "type": "string" } }, "allMeet": { "type": "boolean" }, "citation": { "type": "object", "required": [ "author", "title", "url", "formats", "accessDate" ], "properties": { "author": { "type": "string" }, "title": { "type": "string" }, "version": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sourcesChecked": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "url": { "type": "string" }, "accessDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "formats": { "type": "object", "required": [ "plain", "apa", "harvard", "bibtex" ], "properties": { "plain": { "type": "string" }, "apa": { "type": "string" }, "harvard": { "type": "string" }, "bibtex": { "type": "string" } } } } }, "licence": { "type": "object", "required": [ "name", "url", "attribution" ], "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "attribution": { "type": "string" } } }, "notice": { "type": "string" } } }, { "type": "object", "required": [ "detail", "tool", "title", "lines", "notes", "citation", "url", "open", "more" ], "properties": { "detail": { "const": "summary" }, "tool": { "type": "string" }, "title": { "type": "string" }, "lines": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "string" } }, "description": "The result lines, as the report's table gives them." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "What a professional must decide, when to call one, a false-friend warning, that adoption is local: kept in every summary." }, "citation": { "type": "string", "description": "The one citation line, built from the answer's own data." }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "open": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "more": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } ] } } } }, "404": { "description": "The request was refused; every problem is listed.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "title", "status", "problems" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "problems": { "type": "array", "items": { "type": "object", "required": [ "input", "problem" ], "properties": { "input": { "type": "string" }, "problem": { "type": "string" }, "accepted": { "type": "array", "items": { "type": "string" } } } } }, "didYouMean": { "type": "array", "items": { "type": "string" } } } } } } } }, "tags": [ "Worked examples" ] } }, "/my-project-file": { "post": { "operationId": "createMyProjectFile", "summary": "A My Project file from calculators and takeoffs", "description": "Returns the file in `file.content`; with ?download=1, the file itself as an attachment. The reader imports it in My Project with Restore from a backup.", "parameters": [ { "name": "download", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "1" ] } }, { "name": "detail", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "full", "summary" ], "default": "full", "description": "full (the default): the whole answer. summary: the result lines, the citation line and the page only — fewer tokens to read." }, "description": "summary: the result lines, the citation and the page only (fewer tokens); full, the default: the whole answer. A POST body may carry detail instead." }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json", "md" ] }, "description": "md: the engine's Markdown report as text/markdown (or send Accept: text/markdown); json, the default." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "maxLength": 120 }, "system": { "type": "string", "enum": [ "metric", "imperial" ], "default": "metric", "description": "The unit system inputs left out open in, and the one the page link opens in. The answer comes in both." }, "market": { "type": "string", "enum": [ "US", "CA", "UK", "AU", "INTL" ], "description": "Optional. A market whose own opening choice some inputs take (a UK reader's code, an IEC motor), and whose currency symbol prints the caller's own money figures." }, "calculators": { "type": "array", "maxItems": 50, "items": { "type": "object", "additionalProperties": false, "required": [ "slug" ], "properties": { "slug": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,119}$", "description": "The calculator's slug, such as concrete-calculator." }, "inputs": { "type": "object", "maxProperties": 100, "description": "The calculator's input values, by input id (an unknown id is refused with the accepted ids). A length, area, volume or other measured input takes \"12 ft\", \"3.5 m\", \"8' 3 1/2\\\"\" or {\"value\": 12, \"unit\": \"ft\"}; a count or percentage takes a number; a select takes one of its option values. Inputs left out take the value the calculator's page opens on.", "additionalProperties": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] } }, "label": { "type": "string", "maxLength": 120, "description": "The line's name in the project; the calculator's title when left out." }, "inputUnits": { "type": "string", "enum": [ "base" ], "description": "Send \"base\" to pass bare numbers on dimensioned inputs in base units (m, m², L, kg …), as the published test vectors are written. Without it a length, area or volume must carry its unit." } } } }, "takeoffs": { "type": "array", "maxItems": 10, "items": { "type": "object", "additionalProperties": false, "required": [ "takeoff" ], "properties": { "takeoff": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,119}$" }, "measurements": { "type": "object", "maxProperties": 50, "description": "Measurement id → value, each length, area or volume with its unit (\"12 ft\", {\"value\": 3.6, \"unit\": \"m\"}); counts as numbers. Ids are those of the takeoff; any left out opens at the page's own figure.", "additionalProperties": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] } }, "selection": { "type": "object", "maxProperties": 20, "description": "Build-up choice id → option id, the takeoff's own (a stud size, an insulation, a cladding). Choices left out take the page's own for the system.", "additionalProperties": { "type": "string", "maxLength": 80 } }, "allowances": { "type": "object", "maxProperties": 50, "description": "Row → an allowance the reader sets: a percentage (cutting waste, overlap), or the option an allowance follows (a lay pattern). Row names are the takeoff's steps (the calculator slug, or the step key where one runs twice).", "additionalProperties": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 100 }, { "type": "string", "maxLength": 80 } ] } }, "leaveOut": { "type": "array", "maxItems": 100, "items": { "type": "string", "maxLength": 120 }, "description": "Rows the reader leaves out of the job: still worked and shown, not put in the project or counted in labour." }, "inputUnits": { "type": "string", "enum": [ "base" ], "description": "Send \"base\" to pass bare numbers on dimensioned inputs in base units (m, m², L, kg …), as the published test vectors are written. Without it a length, area or volume must carry its unit." } } } }, "houses": { "type": "array", "maxItems": 2, "items": { "type": "object", "additionalProperties": false, "properties": { "example": { "type": "string", "maxLength": 120, "description": "Start from one of the site's example houses (its slug) in place of the estimator's opening house." }, "values": { "type": "object", "maxProperties": 30, "description": "The form's figures, each length with its unit: length, width, storeyHeight, eaveOverhang, rakeOverhang, slabThickness, footingWidth, footingDepth, trenchDepth, windowWidth, windowHeight, doorWidth, doorHeight (\"12 m\", \"40 ft\"); and the counts partitions, windows, outsideDoors, interiorDoors, iceDamEaves. Any left out opens where the page opens it.", "additionalProperties": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] } }, "storeys": { "type": "integer", "enum": [ 1, 2 ] }, "family": { "type": "string", "enum": [ "wall.framed-exterior", "wall.masonry", "wall.sip" ] }, "selection": { "type": "object", "maxProperties": 20, "additionalProperties": { "type": "string", "maxLength": 80 }, "description": "The exterior wall's build-up choices." }, "pitch": { "type": "string", "enum": [ "4", "6", "8", "10", "12" ], "description": "Roof pitch, rise in 12." }, "roofFamily": { "type": "string", "enum": [ "roof.asphalt-shingle", "roof.tile-slate" ] }, "roofSelection": { "type": "object", "maxProperties": 20, "additionalProperties": { "type": "string", "maxLength": 80 } }, "inputUnits": { "type": "string", "enum": [ "base" ], "description": "Send \"base\" to pass bare numbers on dimensioned inputs in base units (m, m², L, kg …), as the published test vectors are written. Without it a length, area or volume must carry its unit." } } } }, "plan": { "type": "object", "additionalProperties": false, "properties": { "kind": { "type": "string", "enum": [ "room", "bathroom", "slab", "deck", "driveway", "fence", "loft", "retaining-wall", "exterior-wall", "stair" ], "description": "The kind of space: a room or a bathroom (from its size, doors and windows), or a slab, deck, driveway, fence, loft, retaining wall, exterior wall or stair." }, "figures": { "type": "object", "maxProperties": 10, "description": "The space's figures, by the planner's ids, each a length with its unit (a room: length, width, height, wallThickness; a fence: length, height; a stair: totalRise, width …).", "additionalProperties": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] } }, "doors": { "type": "object", "additionalProperties": false, "properties": { "count": { "type": "integer", "minimum": 0, "maximum": 20 }, "width": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] }, "height": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] } } }, "windows": { "type": "object", "additionalProperties": false, "properties": { "count": { "type": "integer", "minimum": 0, "maximum": 20 }, "width": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] }, "height": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] } } }, "finishes": { "type": "object", "maxProperties": 10, "additionalProperties": { "type": "string", "maxLength": 80 }, "description": "Surface role → finish id, by the planner's ids." }, "scope": { "type": "object", "maxProperties": 30, "additionalProperties": { "type": [ "string", "number", "boolean" ] }, "description": "Scope question name → answer value, by the planner's ids." }, "intent": { "type": "string", "maxLength": 40, "description": "A trade, or everything." }, "leaveOut": { "type": "array", "maxItems": 100, "items": { "type": "string", "maxLength": 120 }, "description": "Branch ids to leave out." }, "inputs": { "type": "object", "maxProperties": 50, "additionalProperties": { "type": "object", "maxProperties": 30 }, "description": "Branch id → { calculator input id: value in its base unit }." }, "name": { "type": "string", "maxLength": 120 }, "inputUnits": { "type": "string", "enum": [ "base" ], "description": "Send \"base\" to pass bare numbers on dimensioned inputs in base units (m, m², L, kg …), as the published test vectors are written. Without it a length, area or volume must carry its unit." }, "spaces": { "type": "array", "minItems": 1, "maxItems": 12, "items": { "type": "object", "additionalProperties": false, "required": [ "kind", "figures" ], "properties": { "kind": { "type": "string", "enum": [ "room", "bathroom", "slab", "deck", "driveway", "fence", "loft", "retaining-wall", "exterior-wall", "stair" ], "description": "The kind of space: a room or a bathroom (from its size, doors and windows), or a slab, deck, driveway, fence, loft, retaining wall, exterior wall or stair." }, "figures": { "type": "object", "maxProperties": 10, "description": "The space's figures, by the planner's ids, each a length with its unit (a room: length, width, height, wallThickness; a fence: length, height; a stair: totalRise, width …).", "additionalProperties": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] } }, "doors": { "type": "object", "additionalProperties": false, "properties": { "count": { "type": "integer", "minimum": 0, "maximum": 20 }, "width": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] }, "height": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] } } }, "windows": { "type": "object", "additionalProperties": false, "properties": { "count": { "type": "integer", "minimum": 0, "maximum": 20 }, "width": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] }, "height": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] } } }, "finishes": { "type": "object", "maxProperties": 10, "additionalProperties": { "type": "string", "maxLength": 80 }, "description": "Surface role → finish id, by the planner's ids." }, "scope": { "type": "object", "maxProperties": 30, "additionalProperties": { "type": [ "string", "number", "boolean" ] }, "description": "Scope question name → answer value, by the planner's ids." }, "intent": { "type": "string", "maxLength": 40, "description": "A trade, or everything." }, "leaveOut": { "type": "array", "maxItems": 100, "items": { "type": "string", "maxLength": 120 }, "description": "Branch ids to leave out." }, "inputs": { "type": "object", "maxProperties": 50, "additionalProperties": { "type": "object", "maxProperties": 30 }, "description": "Branch id → { calculator input id: value in its base unit }." }, "name": { "type": "string", "maxLength": 120 } } }, "description": "The spaces, in order, each one planned space." }, "roof": { "type": "object", "additionalProperties": false, "properties": { "pitch": { "type": "number", "minimum": 0, "maximum": 24, "description": "The rise per 12 of run (6 = 6 in 12). Left out, each roof row says it waits for the pitch." }, "finishes": { "type": "object", "maxProperties": 10, "additionalProperties": { "type": "string", "maxLength": 80 }, "description": "Surface role → finish id, by the planner's ids." }, "scope": { "type": "object", "maxProperties": 30, "additionalProperties": { "type": [ "string", "number", "boolean" ] }, "description": "Scope question name → answer value, by the planner's ids." }, "intent": { "type": "string", "maxLength": 40, "description": "A trade, or everything." }, "leaveOut": { "type": "array", "maxItems": 100, "items": { "type": "string", "maxLength": 120 }, "description": "Branch ids to leave out." }, "inputs": { "type": "object", "maxProperties": 50, "additionalProperties": { "type": "object", "maxProperties": 30 }, "description": "Branch id → { calculator input id: value in its base unit }." } } } }, "description": "One planned space as plan_room takes it, or a whole project (spaces, roof) as plan_project takes it." }, "drawing": { "type": "object", "additionalProperties": false, "properties": { "house": { "type": "object", "additionalProperties": false, "properties": { "example": { "type": "string", "maxLength": 120, "description": "Start from one of the site's example houses (its slug) in place of the estimator's opening house." }, "values": { "type": "object", "maxProperties": 30, "description": "The form's figures, each length with its unit: length, width, storeyHeight, eaveOverhang, rakeOverhang, slabThickness, footingWidth, footingDepth, trenchDepth, windowWidth, windowHeight, doorWidth, doorHeight (\"12 m\", \"40 ft\"); and the counts partitions, windows, outsideDoors, interiorDoors, iceDamEaves. Any left out opens where the page opens it.", "additionalProperties": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] } }, "storeys": { "type": "integer", "enum": [ 1, 2 ] }, "family": { "type": "string", "enum": [ "wall.framed-exterior", "wall.masonry", "wall.sip" ] }, "selection": { "type": "object", "maxProperties": 20, "additionalProperties": { "type": "string", "maxLength": 80 }, "description": "The exterior wall's build-up choices." }, "pitch": { "type": "string", "enum": [ "4", "6", "8", "10", "12" ], "description": "Roof pitch, rise in 12." }, "roofFamily": { "type": "string", "enum": [ "roof.asphalt-shingle", "roof.tile-slate" ] }, "roofSelection": { "type": "object", "maxProperties": 20, "additionalProperties": { "type": "string", "maxLength": 80 } } }, "description": "The House Estimator's form: the house drawn as the estimator draws it." }, "commands": { "type": "array", "minItems": 1, "maxItems": 500, "items": { "type": "object", "required": [ "op" ], "properties": { "op": { "enum": [ "level", "type", "wall", "opening", "room", "outline", "path", "point", "beam", "stair" ] }, "ref": { "type": "string", "maxLength": 60, "description": "A name by which later commands refer to what this one makes." }, "name": { "type": "string", "maxLength": 60, "description": "A level's, a type's or a room's name." }, "level": { "type": "string", "maxLength": 60, "description": "A ref given to an earlier command, or the name of a level or type (the blank drawing has the level \"ground\" and the types EW-1, IW-1, WN-1, DR-1)." }, "type": { "type": "string", "maxLength": 60, "description": "A ref given to an earlier command, or the name of a level or type (the blank drawing has the level \"ground\" and the types EW-1, IW-1, WN-1, DR-1)." }, "wall": { "type": "string", "maxLength": 60, "description": "The wall an opening goes in: its ref." }, "c": { "type": "string", "maxLength": 40, "description": "outline: slab, roof, floor, driveway, patio, deck, landscaping; path: footing, cable, pipe, duct, fence, retaining-wall; point: column, pier, outlet, switch, light, panel, fixture, drain, radiator, register." }, "kind": { "enum": [ "door", "window" ] }, "assembly": { "type": "string", "maxLength": 80, "description": "A type's build-up: a canvas assembly id (wall.framed-exterior, roof.asphalt-shingle, slab.on-grade …)." }, "selection": { "type": "object", "maxProperties": 20, "additionalProperties": { "type": "string", "maxLength": 80 } }, "thickness": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] }, "wastePercent": { "type": "number", "minimum": 0, "maximum": 100 }, "elevation": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] }, "height": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] }, "from": { "type": "object", "additionalProperties": false, "required": [ "x", "y" ], "properties": { "x": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] }, "y": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] } }, "description": "A point on plan, each coordinate a length with its unit." }, "to": { "type": "object", "additionalProperties": false, "required": [ "x", "y" ], "properties": { "x": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] }, "y": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] } }, "description": "A point on plan, each coordinate a length with its unit." }, "at": { "type": "object", "additionalProperties": false, "required": [ "x", "y" ], "properties": { "x": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] }, "y": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] } }, "description": "A point on plan, each coordinate a length with its unit." }, "offset": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ], "description": "An opening's centre, measured along its wall from the wall's start." }, "points": { "type": "array", "minItems": 2, "maxItems": 500, "items": { "type": "object", "additionalProperties": false, "required": [ "x", "y" ], "properties": { "x": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] }, "y": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] } }, "description": "A point on plan, each coordinate a length with its unit." } }, "closed": { "type": "boolean" }, "p": { "type": "object", "maxProperties": 20, "description": "The component's own properties by id (components/properties.ts): a length with its unit (widthMm, heightMm, sillMm …), a choice's option id, a count, true or false." }, "finishes": { "type": "object", "maxProperties": 10, "additionalProperties": { "type": "string", "maxLength": 80 }, "description": "A room's, or a driveway's, patio's, deck's, fence's or retaining wall's surface role → finish id, by the planner's ids." }, "scope": { "type": "object", "maxProperties": 30, "additionalProperties": { "type": [ "string", "number", "boolean" ] }, "description": "Its scope question name → answer, by the planner's ids." } } }, "description": "Drawing commands, in order, on the canvas's blank drawing (one storey; the wall, partition, window and door types). The whole request is at most 64 KiB." }, "document": { "type": "object", "description": "A Construction Canvas document (schema 1 to the canvas's current), opened and checked by the canvas's own opener." }, "shapes": { "type": "array", "minItems": 1, "maxItems": 40, "items": { "type": "object", "additionalProperties": false, "required": [ "shape" ], "properties": { "shape": { "enum": [ "room", "deck", "patio", "bed", "path", "fence" ], "description": "room: four exterior walls with doors and windows; deck, patio, bed (planted): a rectangle; path: a paved strip; fence: legs and 90° turns. Anything else is refused." }, "ref": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,40}$", "description": "A name a later shape's against uses." }, "name": { "type": "string", "maxLength": 60, "description": "A room's name." }, "at": { "type": "object", "additionalProperties": false, "required": [ "x", "y" ], "properties": { "x": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] }, "y": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] } }, "description": "The south-west corner (a path's or a fence's start). Left out: the origin." }, "width": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ], "description": "Along x (east): a room's, deck's, patio's or bed's; a path's width across it." }, "depth": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ], "description": "Along y (north); for a deck or patio against a side, out from it." }, "length": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ], "description": "A path's length." }, "heading": { "enum": [ "south", "east", "north", "west" ], "description": "The way a path or a fence's first leg runs (default east)." }, "against": { "type": "object", "additionalProperties": false, "required": [ "shape", "side" ], "properties": { "shape": { "type": "string" }, "side": { "enum": [ "south", "east", "north", "west" ] }, "offset": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] } }, "description": "A deck, patio or bed against a side of an earlier room or rectangle: centred on it, or from its west or south end by offset." }, "doors": { "type": "array", "maxItems": 20, "items": { "type": "object", "additionalProperties": false, "required": [ "side", "offset" ], "properties": { "side": { "enum": [ "south", "east", "north", "west" ] }, "offset": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ], "description": "Along the wall from its start: walls run counter-clockwise from the south-west corner." }, "exterior": { "type": "boolean", "description": "A door: an outside door (the default) or an inside one." } } } }, "windows": { "type": "array", "maxItems": 20, "items": { "type": "object", "additionalProperties": false, "required": [ "side", "offset" ], "properties": { "side": { "enum": [ "south", "east", "north", "west" ] }, "offset": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ], "description": "Along the wall from its start: walls run counter-clockwise from the south-west corner." }, "exterior": { "type": "boolean", "description": "A door: an outside door (the default) or an inside one." } } } }, "legs": { "type": "array", "minItems": 1, "maxItems": 20, "items": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] }, "description": "A fence's straight runs, in order." }, "turns": { "type": "array", "maxItems": 19, "items": { "enum": [ "left", "right" ] }, "description": "A 90° turn between each two legs." }, "gates": { "type": "array", "maxItems": 20, "items": { "type": "object", "additionalProperties": false, "required": [ "leg", "offset", "width" ], "properties": { "leg": { "type": "integer", "minimum": 1 }, "offset": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] }, "width": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] } } }, "description": "Gate openings, by leg (from 1) and offset along it; taken out of the run, the gate itself not counted." }, "build": { "enum": [ "pavers", "concrete" ], "description": "A patio's or path's build: a patio is concrete unless pavers; a path is pavers unless concrete." }, "finishes": { "type": "object", "maxProperties": 10, "additionalProperties": { "type": "string", "maxLength": 80 } }, "scope": { "type": "object", "maxProperties": 30, "additionalProperties": { "type": [ "string", "number", "boolean" ] } }, "p": { "type": "object", "maxProperties": 20, "description": "The component's own properties: a fence's heightMm, a bed's mulchDepthMm, each length with its unit." } } }, "description": "Simple shapes the assistant has read from the reader's words — a room, a deck, a patio, a bed, a path, a fence of legs and turns — compiled into the canvas's own commands. Every length with its unit." }, "layout": { "type": "object", "additionalProperties": false, "required": [ "rooms" ], "properties": { "grid": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ], "description": "The grid every figure is snapped to (default 10 mm, or 1/2 in in US units). Each snap that changed a figure is reported." }, "rooms": { "type": "array", "minItems": 1, "maxItems": 30, "items": { "type": "object", "additionalProperties": false, "required": [ "name", "width", "depth" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 60, "description": "Unique in the layout; openings and later rooms refer to it." }, "width": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ], "description": "Along x (east), wall centre to wall centre." }, "depth": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ], "description": "Along y (north), wall centre to wall centre." }, "at": { "type": "object", "additionalProperties": false, "required": [ "x", "y" ], "properties": { "x": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] }, "y": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] } }, "description": "Its south-west corner. The first room without at or against is at the origin." }, "against": { "type": "object", "additionalProperties": false, "required": [ "room", "side" ], "properties": { "room": { "type": "string", "maxLength": 60 }, "side": { "enum": [ "south", "east", "north", "west" ] }, "align": { "enum": [ "start", "centre", "end" ], "description": "Along that side: flush with its west or south end (start, the default), centred, or flush with the other end." }, "offset": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] } }, "description": "Beside a side of an earlier room, sharing that wall." } } } }, "doors": { "type": "array", "maxItems": 60, "items": { "type": "object", "additionalProperties": false, "properties": { "room": { "type": "string", "maxLength": 60, "description": "The room it is in, by name." }, "side": { "enum": [ "south", "east", "north", "west" ], "description": "The side of that room." }, "offset": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ], "description": "Its centre along the side from the side's start (walls counter-clockwise from the south-west corner); left out, the middle." }, "between": { "type": "array", "minItems": 2, "maxItems": 2, "items": { "type": "string", "maxLength": 60 }, "description": "A door only: the two rooms it joins, on the wall they share." }, "width": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ], "description": "The opening's width; left out, the canvas's default." } } }, "description": "Each between two rooms, or in a room's side (an outside door where that side is an exterior wall)." }, "windows": { "type": "array", "maxItems": 60, "items": { "type": "object", "additionalProperties": false, "properties": { "room": { "type": "string", "maxLength": 60, "description": "The room it is in, by name." }, "side": { "enum": [ "south", "east", "north", "west" ], "description": "The side of that room." }, "offset": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ], "description": "Its centre along the side from the side's start (walls counter-clockwise from the south-west corner); left out, the middle." }, "between": { "type": "array", "minItems": 2, "maxItems": 2, "items": { "type": "string", "maxLength": 60 }, "description": "A door only: the two rooms it joins, on the wall they share." }, "width": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ], "description": "The opening's width; left out, the canvas's default." } } }, "description": "Each in a room's side, on an exterior wall." } }, "description": "Rooms by name, size and which room each stands against, laid out on a grid: shared walls drawn once as partitions, every snap or move reported, and each room checked to close." }, "template": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$", "description": "A Construction Canvas template's slug (the template index lists them: single-room, deck, two-car-garage …): the drawing its page shows, in the reader's system, with a link that opens it." }, "variant": { "type": "string", "pattern": "^[a-z0-9-]{1,40}$", "description": "With template: one of its two \"what changes if\" variants, by id; a wrong one is refused with the template's own list." }, "inputUnits": { "type": "string", "enum": [ "base" ], "description": "Send \"base\" to pass bare numbers on dimensioned inputs in base units (m, m², L, kg …), as the published test vectors are written. Without it a length, area or volume must carry its unit." } }, "description": "A drawing as create_drawing takes it; the file carries the drawing itself, which the canvas reopens." } } }, "example": { "name": "Garage slab", "system": "metric", "calculators": [ { "slug": "concrete-calculator", "inputs": { "slabLength": "6 m", "slabWidth": "4 m", "slabThickness": "100 mm" } } ] }, "examples": { "create_project_file_from_calculations": { "summary": "A My Project file with the garage slab's concrete.", "value": { "name": "Garage slab", "system": "metric", "calculators": [ { "slug": "concrete-calculator", "inputs": { "slabLength": "6 m", "slabWidth": "4 m", "slabThickness": "100 mm" } } ] } }, "create_project_file_from_takeoffs": { "summary": "A My Project file with the garage slab's takeoff.", "value": { "name": "Garage slab", "system": "metric", "takeoffs": [ { "takeoff": "concrete-slab", "measurements": { "length": "6 m", "width": "4 m", "thickness": "100 mm" } } ] } }, "create_project_file_from_house": { "summary": "A My Project file for the House Estimator's opening house, with its drawing.", "value": { "name": "House", "system": "metric", "houses": [ {} ] } }, "create_project_file_from_plan": { "summary": "A My Project file for a 4 × 3 m bedroom.", "value": { "name": "Bedroom", "system": "metric", "plan": { "kind": "room", "name": "Bedroom", "figures": { "length": "4 m", "width": "3 m", "height": "2.4 m" }, "doors": { "count": 1 }, "windows": { "count": 1 } } } }, "create_project_file_from_drawing": { "summary": "A My Project file for a 6 × 4 m deck drawn on the canvas.", "value": { "name": "Deck", "system": "metric", "drawing": { "shapes": [ { "shape": "deck", "width": "6 m", "depth": "4 m" } ] } } } } } } }, "responses": { "200": { "description": "The file, what it holds and its state token.", "content": { "application/json": { "schema": { "type": "object", "anyOf": [ { "type": "object", "required": [ "engine", "file", "project", "howToImport", "licence", "notice" ], "properties": { "engine": { "type": "object" }, "file": { "type": "object", "required": [ "filename", "mediaType", "content" ], "properties": { "filename": { "type": "string" }, "mediaType": { "const": "application/json" }, "content": { "type": "object", "required": [ "magic", "v", "exportedAt", "stores" ], "properties": { "magic": { "const": "craftquantities.backup" }, "v": { "type": "integer" }, "exportedAt": { "type": "string" }, "stores": { "type": "object" } } } } }, "project": { "type": "object", "required": [ "name", "system", "lines" ], "properties": { "name": { "type": "string" }, "system": { "enum": [ "metric", "imperial" ] }, "lines": { "type": "array", "items": { "type": "object", "required": [ "label", "quantity", "unit", "from" ] } } } }, "drawing": { "type": "object", "required": [ "carried" ], "properties": { "carried": { "type": "boolean" }, "note": { "type": "string" } } }, "howToImport": { "type": "string" }, "licence": { "type": "object", "required": [ "name", "url", "attribution" ], "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "attribution": { "type": "string" } } }, "notice": { "type": "string" }, "state": { "type": "object", "required": [ "token", "format", "note" ], "properties": { "token": { "anyOf": [ { "type": "string", "description": "The project's inputs, deflated and base64url-encoded with a format version and a CRC-32 check (cqp1.…). Compact, not encrypted: anyone who has it can read it." }, { "type": "null" } ] }, "format": { "type": "string", "description": "The token's format and version." }, "characters": { "type": "integer" }, "link": { "type": "string", "description": "Opens the project on the site from the token, carried in the address fragment, which a browser does not send to any server." }, "note": { "type": "string" } } } } }, { "type": "object", "required": [ "detail", "tool", "title", "lines", "notes", "citation", "url", "open", "more" ], "properties": { "detail": { "const": "summary" }, "tool": { "type": "string" }, "title": { "type": "string" }, "lines": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "string" } }, "description": "The result lines, as the report's table gives them." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "What a professional must decide, when to call one, a false-friend warning, that adoption is local: kept in every summary." }, "citation": { "type": "string", "description": "The one citation line, built from the answer's own data." }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "open": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "more": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } ] } } } }, "400": { "description": "The request was refused; every problem is listed.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "title", "status", "problems" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "problems": { "type": "array", "items": { "type": "object", "required": [ "input", "problem" ], "properties": { "input": { "type": "string" }, "problem": { "type": "string" }, "accepted": { "type": "array", "items": { "type": "string" } } } } }, "didYouMean": { "type": "array", "items": { "type": "string" } } } } } } }, "413": { "description": "The request was refused; every problem is listed.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "title", "status", "problems" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "problems": { "type": "array", "items": { "type": "object", "required": [ "input", "problem" ], "properties": { "input": { "type": "string" }, "problem": { "type": "string" }, "accepted": { "type": "array", "items": { "type": "string" } } } } }, "didYouMean": { "type": "array", "items": { "type": "string" } } } } } } } }, "tags": [ "Project files" ] } }, "/check/{slug}": { "post": { "operationId": "checkQuote", "summary": "Read a quote against the reader's job", "description": "Money in the quote is taken out before reading and never judged. A difference from a range is a question to ask, not a verdict. Nothing is kept.", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "description": "bathroom-quote, plastering-quote, or {takeoff id}-quote" } }, { "name": "detail", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "full", "summary" ], "default": "full", "description": "full (the default): the whole answer. summary: the result lines, the citation line and the page only — fewer tokens to read." }, "description": "summary: the result lines, the citation and the page only (fewer tokens); full, the default: the whole answer. A POST body may carry detail instead." }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json", "md" ] }, "description": "md: the engine's Markdown report as text/markdown (or send Accept: text/markdown); json, the default." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "quote" ], "properties": { "quote": { "type": "string", "maxLength": 20000 }, "measurements": { "type": "object", "maxProperties": 50, "description": "Measurement id → value, each length, area or volume with its unit (\"12 ft\", {\"value\": 3.6, \"unit\": \"m\"}); counts as numbers. Ids are those of the takeoff; any left out opens at the page's own figure.", "additionalProperties": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] } }, "selection": { "type": "object", "maxProperties": 20, "description": "Build-up choice id → option id, the takeoff's own (a stud size, an insulation, a cladding). Choices left out take the page's own for the system.", "additionalProperties": { "type": "string", "maxLength": 80 } }, "system": { "type": "string", "enum": [ "metric", "imperial" ], "default": "metric", "description": "The unit system inputs left out open in, and the one the page link opens in. The answer comes in both." }, "market": { "type": "string", "enum": [ "US", "CA", "UK", "AU", "INTL" ], "description": "Optional. A market whose own opening choice some inputs take (a UK reader's code, an IEC motor), and whose currency symbol prints the caller's own money figures." }, "inputUnits": { "type": "string", "enum": [ "base" ], "description": "Send \"base\" to pass bare numbers on dimensioned inputs in base units (m, m², L, kg …), as the published test vectors are written. Without it a length, area or volume must carry its unit." } } }, "example": { "quote": "Wall and floor tiles 12 m2\nTile adhesive 6 bags\nGrout 3 bags" }, "examples": { "check_quote": { "summary": "Is anything missing from this bathroom quote?", "value": { "quote": "Wall and floor tiles 12 m2\nTile adhesive 6 bags\nGrout 3 bags" } } } } } }, "responses": { "200": { "description": "The reading.", "content": { "application/json": { "schema": { "type": "object", "anyOf": [ { "type": "object", "required": [ "engine", "check", "system", "measurements", "lines", "reading", "rows", "pricesIgnored", "excludes", "citation", "licence", "notice" ], "properties": { "engine": { "type": "object" }, "check": { "type": "object", "required": [ "slug", "job", "url" ], "properties": { "slug": { "type": "string" }, "job": { "type": "string" }, "url": { "type": "string" }, "takeoff": { "type": "object" } } }, "system": { "enum": [ "metric", "imperial" ] }, "market": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "measurements": { "type": "array", "items": { "type": "object", "required": [ "id", "label", "value", "source" ] } }, "lines": { "type": "array", "items": { "type": "object", "required": [ "key", "name", "unit", "low", "high", "minimum", "range", "calculator" ], "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "unit": { "type": "string" }, "low": { "type": "number" }, "high": { "anyOf": [ { "type": "number", "description": "Null where the line is a minimum with no upper end." }, { "type": "null" } ] }, "minimum": { "type": "boolean" }, "range": { "type": "string", "description": "Why the two ends differ." }, "why": { "type": "string" }, "calculator": { "type": "object", "required": [ "title", "url" ], "properties": { "title": { "type": "string" }, "url": { "type": "string" } } }, "alternativeTo": { "type": "string" } } } }, "reading": { "type": "object", "required": [ "rowsRead", "differs", "agrees", "missing", "notComparable", "extras", "listed", "headings", "unmentioned", "questions" ], "properties": { "rowsRead": { "type": "integer" }, "differs": { "type": "array", "items": { "type": "object", "required": [ "line", "quoted", "outcome", "difference", "rows", "explanation", "ask" ], "properties": { "line": { "type": "object", "required": [ "key", "name", "unit", "low", "high", "minimum", "range", "calculator" ], "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "unit": { "type": "string" }, "low": { "type": "number" }, "high": { "anyOf": [ { "type": "number", "description": "Null where the line is a minimum with no upper end." }, { "type": "null" } ] }, "minimum": { "type": "boolean" }, "range": { "type": "string", "description": "Why the two ends differ." }, "why": { "type": "string" }, "calculator": { "type": "object", "required": [ "title", "url" ], "properties": { "title": { "type": "string" }, "url": { "type": "string" } } }, "alternativeTo": { "type": "string" } } }, "quoted": { "type": "number" }, "outcome": { "enum": [ "above", "below" ] }, "difference": { "type": "number" }, "rows": { "type": "array", "items": { "type": "object", "required": [ "text", "unit" ], "properties": { "text": { "type": "string" }, "quantity": { "type": "number" }, "unit": { "type": "string" }, "how": { "type": "string" } } } }, "explanation": { "type": "string" }, "ask": { "type": "string" } } } }, "agrees": { "type": "array", "items": { "type": "object", "required": [ "line", "quoted", "rows" ] } }, "missing": { "type": "array", "items": { "type": "object", "required": [ "line", "alternatives" ] } }, "notComparable": { "type": "array", "items": { "type": "object", "required": [ "line", "reason", "rows" ] } }, "extras": { "type": "array", "items": { "type": "object", "required": [ "text", "unit", "kind" ] } }, "listed": { "type": "array", "items": { "type": "object", "required": [ "text", "unit", "work" ] } }, "headings": { "type": "array", "items": { "type": "string" } }, "unmentioned": { "type": "array", "items": { "type": "object", "required": [ "heading", "why", "ask" ] } }, "questions": { "type": "array", "items": { "type": "object", "required": [ "about", "question" ] } } } }, "rows": { "type": "array", "items": { "type": "object", "required": [ "text", "unit", "readAs" ] } }, "pricesIgnored": { "type": "string" }, "excludes": { "type": "array", "items": { "type": "string" } }, "citation": { "type": "object", "required": [ "author", "title", "url", "formats", "accessDate" ], "properties": { "author": { "type": "string" }, "title": { "type": "string" }, "version": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sourcesChecked": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "url": { "type": "string" }, "accessDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "formats": { "type": "object", "required": [ "plain", "apa", "harvard", "bibtex" ], "properties": { "plain": { "type": "string" }, "apa": { "type": "string" }, "harvard": { "type": "string" }, "bibtex": { "type": "string" } } } } }, "licence": { "type": "object", "required": [ "name", "url", "attribution" ], "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "attribution": { "type": "string" } } }, "notice": { "type": "string" } } }, { "type": "object", "required": [ "detail", "tool", "title", "lines", "notes", "citation", "url", "open", "more" ], "properties": { "detail": { "const": "summary" }, "tool": { "type": "string" }, "title": { "type": "string" }, "lines": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "string" } }, "description": "The result lines, as the report's table gives them." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "What a professional must decide, when to call one, a false-friend warning, that adoption is local: kept in every summary." }, "citation": { "type": "string", "description": "The one citation line, built from the answer's own data." }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "open": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "more": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } ] } } } }, "400": { "description": "The request was refused; every problem is listed.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "title", "status", "problems" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "problems": { "type": "array", "items": { "type": "object", "required": [ "input", "problem" ], "properties": { "input": { "type": "string" }, "problem": { "type": "string" }, "accepted": { "type": "array", "items": { "type": "string" } } } } }, "didYouMean": { "type": "array", "items": { "type": "string" } } } } } } }, "404": { "description": "The request was refused; every problem is listed.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "title", "status", "problems" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "problems": { "type": "array", "items": { "type": "object", "required": [ "input", "problem" ], "properties": { "input": { "type": "string" }, "problem": { "type": "string" }, "accepted": { "type": "array", "items": { "type": "string" } } } } }, "didYouMean": { "type": "array", "items": { "type": "string" } } } } } } }, "413": { "description": "The request was refused; every problem is listed.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "title", "status", "problems" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "problems": { "type": "array", "items": { "type": "object", "required": [ "input", "problem" ], "properties": { "input": { "type": "string" }, "problem": { "type": "string" }, "accepted": { "type": "array", "items": { "type": "string" } } } } }, "didYouMean": { "type": "array", "items": { "type": "string" } } } } } } } }, "tags": [ "Quotes" ] } }, "/house": { "get": { "operationId": "estimateHouseGet", "summary": "Estimate a house (example, system and figures in the query)", "description": "Every parameter other than example, system, storeys, family, pitch, roofFamily and inputUnits is a figure of the form, written with its unit.", "parameters": [ { "name": "example", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "system", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "metric", "imperial" ], "default": "metric", "description": "The unit system inputs left out open in, and the one the page link opens in. The answer comes in both." } }, { "name": "storeys", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 1, 2 ] } }, { "name": "family", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "wall.framed-exterior", "wall.masonry", "wall.sip" ] } }, { "name": "pitch", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "4", "6", "8", "10", "12" ], "description": "Roof pitch, rise in 12." } }, { "name": "roofFamily", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "roof.asphalt-shingle", "roof.tile-slate" ] } }, { "name": "detail", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "full", "summary" ], "default": "full", "description": "full (the default): the whole answer. summary: the result lines, the citation line and the page only — fewer tokens to read." }, "description": "summary: the result lines, the citation and the page only (fewer tokens); full, the default: the whole answer. A POST body may carry detail instead." }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json", "md" ] }, "description": "md: the engine's Markdown report as text/markdown (or send Accept: text/markdown); json, the default." } ], "responses": { "200": { "description": "The house's quantities, plan, labour and sources.", "content": { "application/json": { "schema": { "type": "object", "anyOf": [ { "type": "object", "required": [ "engine", "house", "system", "values", "rows", "counts", "unplaced", "raised", "assumptions", "omitted", "plans", "labour", "sources", "citation", "links", "licence", "notice" ], "properties": { "engine": { "type": "object" }, "house": { "type": "object", "required": [ "storeys", "family", "selection", "pitch", "roofFamily", "roofSelection" ] }, "system": { "enum": [ "metric", "imperial" ] }, "values": { "type": "array", "items": { "type": "object", "required": [ "id", "label", "value", "source" ] } }, "rows": { "type": "array", "items": { "type": "object", "required": [ "key", "section", "label", "where", "quantity", "unit", "otherSystem", "calculator" ], "properties": { "key": { "type": "string" }, "section": { "type": "string" }, "label": { "type": "string" }, "where": { "type": "string" }, "quantity": { "type": "number" }, "unit": { "type": "string" }, "order": { "type": "object", "required": [ "quantity", "unit" ] }, "otherSystem": { "anyOf": [ { "type": "object", "required": [ "quantity", "unit" ] }, { "type": "null" } ] }, "calculator": { "type": "object", "required": [ "slug", "title" ] }, "note": { "type": "string" } } } }, "counts": { "type": "array", "items": { "type": "object", "required": [ "key", "label", "quantity" ] } }, "unplaced": { "type": "object" }, "raised": { "type": "array", "items": { "type": "string" } }, "assumptions": { "type": "array", "items": { "type": "string" } }, "omitted": { "type": "array", "items": { "type": "object", "required": [ "assembly", "step", "why" ] } }, "plans": { "type": "array", "items": { "type": "object", "required": [ "level", "name", "unit", "walls", "openings", "box" ] } }, "labour": { "type": "object", "required": [ "rows", "totalHours", "programme", "likelyDays", "note" ] }, "sources": { "type": "array", "items": { "type": "object", "required": [ "calculator", "title", "version", "sources" ] } }, "citation": { "type": "object", "required": [ "author", "title", "url", "formats", "accessDate" ], "properties": { "author": { "type": "string" }, "title": { "type": "string" }, "version": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sourcesChecked": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "url": { "type": "string" }, "accessDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "formats": { "type": "object", "required": [ "plain", "apa", "harvard", "bibtex" ], "properties": { "plain": { "type": "string" }, "apa": { "type": "string" }, "harvard": { "type": "string" }, "bibtex": { "type": "string" } } } } }, "links": { "type": "object", "required": [ "page" ] }, "licence": { "type": "object", "required": [ "name", "url", "attribution" ], "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "attribution": { "type": "string" } } }, "notice": { "type": "string" } } }, { "type": "object", "required": [ "detail", "tool", "title", "lines", "notes", "citation", "url", "open", "more" ], "properties": { "detail": { "const": "summary" }, "tool": { "type": "string" }, "title": { "type": "string" }, "lines": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "string" } }, "description": "The result lines, as the report's table gives them." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "What a professional must decide, when to call one, a false-friend warning, that adoption is local: kept in every summary." }, "citation": { "type": "string", "description": "The one citation line, built from the answer's own data." }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "open": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "more": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } ] } } } }, "400": { "description": "The request was refused; every problem is listed.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "title", "status", "problems" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "problems": { "type": "array", "items": { "type": "object", "required": [ "input", "problem" ], "properties": { "input": { "type": "string" }, "problem": { "type": "string" }, "accepted": { "type": "array", "items": { "type": "string" } } } } }, "didYouMean": { "type": "array", "items": { "type": "string" } } } } } } }, "404": { "description": "The request was refused; every problem is listed.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "title", "status", "problems" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "problems": { "type": "array", "items": { "type": "object", "required": [ "input", "problem" ], "properties": { "input": { "type": "string" }, "problem": { "type": "string" }, "accepted": { "type": "array", "items": { "type": "string" } } } } }, "didYouMean": { "type": "array", "items": { "type": "string" } } } } } } } }, "tags": [ "House and canvas" ] }, "post": { "operationId": "estimateHouse", "summary": "Estimate a house", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "example": { "type": "string", "maxLength": 120, "description": "Start from one of the site's example houses (its slug) in place of the estimator's opening house." }, "values": { "type": "object", "maxProperties": 30, "description": "The form's figures, each length with its unit: length, width, storeyHeight, eaveOverhang, rakeOverhang, slabThickness, footingWidth, footingDepth, trenchDepth, windowWidth, windowHeight, doorWidth, doorHeight (\"12 m\", \"40 ft\"); and the counts partitions, windows, outsideDoors, interiorDoors, iceDamEaves. Any left out opens where the page opens it.", "additionalProperties": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] } }, "storeys": { "type": "integer", "enum": [ 1, 2 ] }, "family": { "type": "string", "enum": [ "wall.framed-exterior", "wall.masonry", "wall.sip" ] }, "selection": { "type": "object", "maxProperties": 20, "additionalProperties": { "type": "string", "maxLength": 80 }, "description": "The exterior wall's build-up choices." }, "pitch": { "type": "string", "enum": [ "4", "6", "8", "10", "12" ], "description": "Roof pitch, rise in 12." }, "roofFamily": { "type": "string", "enum": [ "roof.asphalt-shingle", "roof.tile-slate" ] }, "roofSelection": { "type": "object", "maxProperties": 20, "additionalProperties": { "type": "string", "maxLength": 80 } }, "system": { "type": "string", "enum": [ "metric", "imperial" ], "default": "metric", "description": "The unit system inputs left out open in, and the one the page link opens in. The answer comes in both." }, "inputUnits": { "type": "string", "enum": [ "base" ], "description": "Send \"base\" to pass bare numbers on dimensioned inputs in base units (m, m², L, kg …), as the published test vectors are written. Without it a length, area or volume must carry its unit." } } } } } }, "responses": { "200": { "description": "The house's quantities, plan, labour and sources.", "content": { "application/json": { "schema": { "type": "object", "anyOf": [ { "type": "object", "required": [ "engine", "house", "system", "values", "rows", "counts", "unplaced", "raised", "assumptions", "omitted", "plans", "labour", "sources", "citation", "links", "licence", "notice" ], "properties": { "engine": { "type": "object" }, "house": { "type": "object", "required": [ "storeys", "family", "selection", "pitch", "roofFamily", "roofSelection" ] }, "system": { "enum": [ "metric", "imperial" ] }, "values": { "type": "array", "items": { "type": "object", "required": [ "id", "label", "value", "source" ] } }, "rows": { "type": "array", "items": { "type": "object", "required": [ "key", "section", "label", "where", "quantity", "unit", "otherSystem", "calculator" ], "properties": { "key": { "type": "string" }, "section": { "type": "string" }, "label": { "type": "string" }, "where": { "type": "string" }, "quantity": { "type": "number" }, "unit": { "type": "string" }, "order": { "type": "object", "required": [ "quantity", "unit" ] }, "otherSystem": { "anyOf": [ { "type": "object", "required": [ "quantity", "unit" ] }, { "type": "null" } ] }, "calculator": { "type": "object", "required": [ "slug", "title" ] }, "note": { "type": "string" } } } }, "counts": { "type": "array", "items": { "type": "object", "required": [ "key", "label", "quantity" ] } }, "unplaced": { "type": "object" }, "raised": { "type": "array", "items": { "type": "string" } }, "assumptions": { "type": "array", "items": { "type": "string" } }, "omitted": { "type": "array", "items": { "type": "object", "required": [ "assembly", "step", "why" ] } }, "plans": { "type": "array", "items": { "type": "object", "required": [ "level", "name", "unit", "walls", "openings", "box" ] } }, "labour": { "type": "object", "required": [ "rows", "totalHours", "programme", "likelyDays", "note" ] }, "sources": { "type": "array", "items": { "type": "object", "required": [ "calculator", "title", "version", "sources" ] } }, "citation": { "type": "object", "required": [ "author", "title", "url", "formats", "accessDate" ], "properties": { "author": { "type": "string" }, "title": { "type": "string" }, "version": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sourcesChecked": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "url": { "type": "string" }, "accessDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "formats": { "type": "object", "required": [ "plain", "apa", "harvard", "bibtex" ], "properties": { "plain": { "type": "string" }, "apa": { "type": "string" }, "harvard": { "type": "string" }, "bibtex": { "type": "string" } } } } }, "links": { "type": "object", "required": [ "page" ] }, "licence": { "type": "object", "required": [ "name", "url", "attribution" ], "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "attribution": { "type": "string" } } }, "notice": { "type": "string" } } }, { "type": "object", "required": [ "detail", "tool", "title", "lines", "notes", "citation", "url", "open", "more" ], "properties": { "detail": { "const": "summary" }, "tool": { "type": "string" }, "title": { "type": "string" }, "lines": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "string" } }, "description": "The result lines, as the report's table gives them." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "What a professional must decide, when to call one, a false-friend warning, that adoption is local: kept in every summary." }, "citation": { "type": "string", "description": "The one citation line, built from the answer's own data." }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "open": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "more": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } ] } } } }, "400": { "description": "The request was refused; every problem is listed.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "title", "status", "problems" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "problems": { "type": "array", "items": { "type": "object", "required": [ "input", "problem" ], "properties": { "input": { "type": "string" }, "problem": { "type": "string" }, "accepted": { "type": "array", "items": { "type": "string" } } } } }, "didYouMean": { "type": "array", "items": { "type": "string" } } } } } } }, "404": { "description": "The request was refused; every problem is listed.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "title", "status", "problems" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "problems": { "type": "array", "items": { "type": "object", "required": [ "input", "problem" ], "properties": { "input": { "type": "string" }, "problem": { "type": "string" }, "accepted": { "type": "array", "items": { "type": "string" } } } } }, "didYouMean": { "type": "array", "items": { "type": "string" } } } } } } } }, "tags": [ "House and canvas" ], "parameters": [ { "name": "detail", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "full", "summary" ], "default": "full", "description": "full (the default): the whole answer. summary: the result lines, the citation line and the page only — fewer tokens to read." }, "description": "summary: the result lines, the citation and the page only (fewer tokens); full, the default: the whole answer. A POST body may carry detail instead." }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json", "md" ] }, "description": "md: the engine's Markdown report as text/markdown (or send Accept: text/markdown); json, the default." } ] } }, "/planner/{kind}": { "get": { "operationId": "getPlanner", "summary": "The planner's ids for one kind of space", "parameters": [ { "name": "kind", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "room", "bathroom", "slab", "deck", "driveway", "fence", "loft", "retaining-wall", "exterior-wall", "stair" ], "description": "The kind of space: a room or a bathroom (from its size, doors and windows), or a slab, deck, driveway, fence, loft, retaining wall, exterior wall or stair." } }, { "name": "detail", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "full", "summary" ], "default": "full", "description": "full (the default): the whole answer. summary: the result lines, the citation line and the page only — fewer tokens to read." }, "description": "summary: the result lines, the citation and the page only (fewer tokens); full, the default: the whole answer. A POST body may carry detail instead." }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json", "md" ] }, "description": "md: the engine's Markdown report as text/markdown (or send Accept: text/markdown); json, the default." } ], "responses": { "200": { "description": "Figures, surfaces and finishes, scope questions, trades, branches and decisions.", "content": { "application/json": { "schema": { "type": "object", "anyOf": [ { "type": "object", "required": [ "kind", "modelSchemaVersion", "url", "figures", "surfaces", "scope", "intents", "branches", "decisions", "licence" ], "properties": { "kind": { "type": "string" }, "modelSchemaVersion": { "type": "integer" }, "url": { "type": "string" }, "figures": { "type": "array", "items": { "type": "object", "required": [ "id", "label", "dimension", "required" ] } }, "openings": { "type": "array" }, "surfaces": { "type": "array", "items": { "type": "object", "required": [ "role", "label", "finishes" ] } }, "scope": { "type": "array", "items": { "type": "object", "required": [ "name", "label", "answers", "help" ] } }, "intents": { "type": "array", "items": { "type": "string" } }, "branches": { "type": "array", "items": { "type": "object", "required": [ "id", "label", "trade", "surface", "role" ] } }, "decisions": { "type": "object" }, "licence": { "type": "object", "required": [ "name", "url", "attribution" ], "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "attribution": { "type": "string" } } } } }, { "type": "object", "required": [ "detail", "tool", "title", "lines", "notes", "citation", "url", "open", "more" ], "properties": { "detail": { "const": "summary" }, "tool": { "type": "string" }, "title": { "type": "string" }, "lines": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "string" } }, "description": "The result lines, as the report's table gives them." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "What a professional must decide, when to call one, a false-friend warning, that adoption is local: kept in every summary." }, "citation": { "type": "string", "description": "The one citation line, built from the answer's own data." }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "open": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "more": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } ] } } } }, "400": { "description": "The request was refused; every problem is listed.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "title", "status", "problems" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "problems": { "type": "array", "items": { "type": "object", "required": [ "input", "problem" ], "properties": { "input": { "type": "string" }, "problem": { "type": "string" }, "accepted": { "type": "array", "items": { "type": "string" } } } } }, "didYouMean": { "type": "array", "items": { "type": "string" } } } } } } } }, "tags": [ "Planner" ] } }, "/plan": { "post": { "operationId": "planRoom", "summary": "Plan a room or another space", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "kind", "figures" ], "properties": { "kind": { "type": "string", "enum": [ "room", "bathroom", "slab", "deck", "driveway", "fence", "loft", "retaining-wall", "exterior-wall", "stair" ], "description": "The kind of space: a room or a bathroom (from its size, doors and windows), or a slab, deck, driveway, fence, loft, retaining wall, exterior wall or stair." }, "figures": { "type": "object", "maxProperties": 10, "description": "The space's figures, by the planner's ids, each a length with its unit (a room: length, width, height, wallThickness; a fence: length, height; a stair: totalRise, width …).", "additionalProperties": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] } }, "doors": { "type": "object", "additionalProperties": false, "properties": { "count": { "type": "integer", "minimum": 0, "maximum": 20 }, "width": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] }, "height": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] } } }, "windows": { "type": "object", "additionalProperties": false, "properties": { "count": { "type": "integer", "minimum": 0, "maximum": 20 }, "width": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] }, "height": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] } } }, "finishes": { "type": "object", "maxProperties": 10, "additionalProperties": { "type": "string", "maxLength": 80 }, "description": "Surface role → finish id, by the planner's ids." }, "scope": { "type": "object", "maxProperties": 30, "additionalProperties": { "type": [ "string", "number", "boolean" ] }, "description": "Scope question name → answer value, by the planner's ids." }, "intent": { "type": "string", "maxLength": 40, "description": "A trade, or everything." }, "leaveOut": { "type": "array", "maxItems": 100, "items": { "type": "string", "maxLength": 120 }, "description": "Branch ids to leave out." }, "inputs": { "type": "object", "maxProperties": 50, "additionalProperties": { "type": "object", "maxProperties": 30 }, "description": "Branch id → { calculator input id: value in its base unit }." }, "name": { "type": "string", "maxLength": 120 }, "system": { "type": "string", "enum": [ "metric", "imperial" ], "default": "metric", "description": "The unit system inputs left out open in, and the one the page link opens in. The answer comes in both." }, "inputUnits": { "type": "string", "enum": [ "base" ], "description": "Send \"base\" to pass bare numbers on dimensioned inputs in base units (m, m², L, kg …), as the published test vectors are written. Without it a length, area or volume must carry its unit." } } }, "example": { "kind": "room", "figures": { "length": "4 m", "width": "3 m", "height": "2.4 m" }, "doors": { "count": 1 }, "windows": { "count": 2 }, "name": "Bedroom" }, "examples": { "plan_room": { "summary": "Plan a 4 × 3 m bedroom with a door and two windows.", "value": { "kind": "room", "figures": { "length": "4 m", "width": "3 m", "height": "2.4 m" }, "doors": { "count": 1 }, "windows": { "count": 2 }, "name": "Bedroom" } } } } } }, "responses": { "200": { "description": "Every row the planner works, and the plan.", "content": { "application/json": { "schema": { "type": "object", "anyOf": [ { "type": "object", "required": [ "engine", "space", "system", "outcomes", "lines", "labour", "assumptions", "model", "sources", "citation", "licence", "notice" ], "properties": { "engine": { "type": "object" }, "space": { "type": "object", "required": [ "id", "kind", "name", "url" ] }, "system": { "enum": [ "metric", "imperial" ] }, "outcomes": { "type": "array", "items": { "type": "object", "required": [ "branch", "label", "trade", "status", "comparison" ], "properties": { "branch": { "type": "string" }, "label": { "type": "string" }, "trade": { "type": "string" }, "status": { "enum": [ "ready", "needs", "loading", "did-not-load", "no-answer", "gap", "left-out", "not-applicable" ] }, "comparison": { "type": "boolean" } } } }, "lines": { "type": "array", "items": { "type": "object", "required": [ "label", "quantity", "unit", "branch", "zone" ] } }, "labour": { "type": "object", "required": [ "rows", "totalHours", "programme", "likelyDays", "note" ] }, "assumptions": { "type": "array", "items": { "type": "object", "required": [ "field", "reason" ] } }, "model": { "type": "object" }, "sources": { "type": "array" }, "citation": { "type": "object", "required": [ "author", "title", "url", "formats", "accessDate" ], "properties": { "author": { "type": "string" }, "title": { "type": "string" }, "version": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sourcesChecked": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "url": { "type": "string" }, "accessDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "formats": { "type": "object", "required": [ "plain", "apa", "harvard", "bibtex" ], "properties": { "plain": { "type": "string" }, "apa": { "type": "string" }, "harvard": { "type": "string" }, "bibtex": { "type": "string" } } } } }, "licence": { "type": "object", "required": [ "name", "url", "attribution" ], "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "attribution": { "type": "string" } } }, "notice": { "type": "string" } } }, { "type": "object", "required": [ "detail", "tool", "title", "lines", "notes", "citation", "url", "open", "more" ], "properties": { "detail": { "const": "summary" }, "tool": { "type": "string" }, "title": { "type": "string" }, "lines": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "string" } }, "description": "The result lines, as the report's table gives them." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "What a professional must decide, when to call one, a false-friend warning, that adoption is local: kept in every summary." }, "citation": { "type": "string", "description": "The one citation line, built from the answer's own data." }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "open": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "more": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } ] } } } }, "400": { "description": "The request was refused; every problem is listed.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "title", "status", "problems" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "problems": { "type": "array", "items": { "type": "object", "required": [ "input", "problem" ], "properties": { "input": { "type": "string" }, "problem": { "type": "string" }, "accepted": { "type": "array", "items": { "type": "string" } } } } }, "didYouMean": { "type": "array", "items": { "type": "string" } } } } } } } }, "tags": [ "Planner" ], "parameters": [ { "name": "detail", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "full", "summary" ], "default": "full", "description": "full (the default): the whole answer. summary: the result lines, the citation line and the page only — fewer tokens to read." }, "description": "summary: the result lines, the citation and the page only (fewer tokens); full, the default: the whole answer. A POST body may carry detail instead." }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json", "md" ] }, "description": "md: the engine's Markdown report as text/markdown (or send Accept: text/markdown); json, the default." } ] } }, "/plan-project": { "post": { "operationId": "planProject", "summary": "Plan several spaces and a roof together", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "spaces" ], "properties": { "spaces": { "type": "array", "minItems": 1, "maxItems": 12, "items": { "type": "object", "additionalProperties": false, "required": [ "kind", "figures" ], "properties": { "kind": { "type": "string", "enum": [ "room", "bathroom", "slab", "deck", "driveway", "fence", "loft", "retaining-wall", "exterior-wall", "stair" ], "description": "The kind of space: a room or a bathroom (from its size, doors and windows), or a slab, deck, driveway, fence, loft, retaining wall, exterior wall or stair." }, "figures": { "type": "object", "maxProperties": 10, "description": "The space's figures, by the planner's ids, each a length with its unit (a room: length, width, height, wallThickness; a fence: length, height; a stair: totalRise, width …).", "additionalProperties": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] } }, "doors": { "type": "object", "additionalProperties": false, "properties": { "count": { "type": "integer", "minimum": 0, "maximum": 20 }, "width": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] }, "height": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] } } }, "windows": { "type": "object", "additionalProperties": false, "properties": { "count": { "type": "integer", "minimum": 0, "maximum": 20 }, "width": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] }, "height": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] } } }, "finishes": { "type": "object", "maxProperties": 10, "additionalProperties": { "type": "string", "maxLength": 80 }, "description": "Surface role → finish id, by the planner's ids." }, "scope": { "type": "object", "maxProperties": 30, "additionalProperties": { "type": [ "string", "number", "boolean" ] }, "description": "Scope question name → answer value, by the planner's ids." }, "intent": { "type": "string", "maxLength": 40, "description": "A trade, or everything." }, "leaveOut": { "type": "array", "maxItems": 100, "items": { "type": "string", "maxLength": 120 }, "description": "Branch ids to leave out." }, "inputs": { "type": "object", "maxProperties": 50, "additionalProperties": { "type": "object", "maxProperties": 30 }, "description": "Branch id → { calculator input id: value in its base unit }." }, "name": { "type": "string", "maxLength": 120 } } }, "description": "The spaces, in order, each one planned space." }, "roof": { "type": "object", "additionalProperties": false, "properties": { "pitch": { "type": "number", "minimum": 0, "maximum": 24, "description": "The rise per 12 of run (6 = 6 in 12). Left out, each roof row says it waits for the pitch." }, "finishes": { "type": "object", "maxProperties": 10, "additionalProperties": { "type": "string", "maxLength": 80 }, "description": "Surface role → finish id, by the planner's ids." }, "scope": { "type": "object", "maxProperties": 30, "additionalProperties": { "type": [ "string", "number", "boolean" ] }, "description": "Scope question name → answer value, by the planner's ids." }, "intent": { "type": "string", "maxLength": 40, "description": "A trade, or everything." }, "leaveOut": { "type": "array", "maxItems": 100, "items": { "type": "string", "maxLength": 120 }, "description": "Branch ids to leave out." }, "inputs": { "type": "object", "maxProperties": 50, "additionalProperties": { "type": "object", "maxProperties": 30 }, "description": "Branch id → { calculator input id: value in its base unit }." } } }, "system": { "type": "string", "enum": [ "metric", "imperial" ], "default": "metric", "description": "The unit system inputs left out open in, and the one the page link opens in. The answer comes in both." }, "inputUnits": { "type": "string", "enum": [ "base" ], "description": "Send \"base\" to pass bare numbers on dimensioned inputs in base units (m, m², L, kg …), as the published test vectors are written. Without it a length, area or volume must carry its unit." } } }, "example": { "spaces": [ { "kind": "room", "name": "Bedroom", "figures": { "length": "4 m", "width": "3 m", "height": "2.4 m" }, "doors": { "count": 1 }, "windows": { "count": 2 } }, { "kind": "bathroom", "figures": { "length": "2.5 m", "width": "2 m", "height": "2.4 m" }, "doors": { "count": 1 } } ], "roof": { "pitch": 6 } }, "examples": { "plan_project": { "summary": "Plan a bedroom and a bathroom with a 6-in-12 roof over both.", "value": { "spaces": [ { "kind": "room", "name": "Bedroom", "figures": { "length": "4 m", "width": "3 m", "height": "2.4 m" }, "doors": { "count": 1 }, "windows": { "count": 2 } }, { "kind": "bathroom", "figures": { "length": "2.5 m", "width": "2 m", "height": "2.4 m" }, "doors": { "count": 1 } } ], "roof": { "pitch": 6 } } } } } } }, "responses": { "200": { "description": "Each space's rows, every line together, and the plan.", "content": { "application/json": { "schema": { "type": "object", "anyOf": [ { "type": "object", "required": [ "engine", "system", "spaces", "lines", "labour", "assumptions", "model", "sources", "citation", "licence", "notice" ], "properties": { "engine": { "type": "object" }, "system": { "enum": [ "metric", "imperial" ] }, "spaces": { "type": "array", "items": { "type": "object", "required": [ "space", "outcomes", "lines" ], "properties": { "space": { "type": "object", "required": [ "id", "kind", "name", "url" ] }, "outcomes": { "type": "array", "items": { "type": "object", "required": [ "branch", "label", "trade", "status", "comparison" ], "properties": { "branch": { "type": "string" }, "label": { "type": "string" }, "trade": { "type": "string" }, "status": { "enum": [ "ready", "needs", "loading", "did-not-load", "no-answer", "gap", "left-out", "not-applicable" ] }, "comparison": { "type": "boolean" } } } }, "lines": { "type": "array", "items": { "type": "object", "required": [ "label", "quantity", "unit", "branch", "zone" ] } } } } }, "lines": { "type": "array", "items": { "type": "object", "required": [ "label", "quantity", "unit", "branch", "zone" ] } }, "labour": { "type": "object", "required": [ "rows", "totalHours", "programme", "likelyDays", "note" ] }, "assumptions": { "type": "array", "items": { "type": "object", "required": [ "field", "reason" ] } }, "model": { "type": "object" }, "sources": { "type": "array" }, "citation": { "type": "object", "required": [ "author", "title", "url", "formats", "accessDate" ], "properties": { "author": { "type": "string" }, "title": { "type": "string" }, "version": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sourcesChecked": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "url": { "type": "string" }, "accessDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "formats": { "type": "object", "required": [ "plain", "apa", "harvard", "bibtex" ], "properties": { "plain": { "type": "string" }, "apa": { "type": "string" }, "harvard": { "type": "string" }, "bibtex": { "type": "string" } } } } }, "licence": { "type": "object", "required": [ "name", "url", "attribution" ], "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "attribution": { "type": "string" } } }, "notice": { "type": "string" } } }, { "type": "object", "required": [ "detail", "tool", "title", "lines", "notes", "citation", "url", "open", "more" ], "properties": { "detail": { "const": "summary" }, "tool": { "type": "string" }, "title": { "type": "string" }, "lines": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "string" } }, "description": "The result lines, as the report's table gives them." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "What a professional must decide, when to call one, a false-friend warning, that adoption is local: kept in every summary." }, "citation": { "type": "string", "description": "The one citation line, built from the answer's own data." }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "open": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "more": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } ] } } } }, "400": { "description": "The request was refused; every problem is listed.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "title", "status", "problems" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "problems": { "type": "array", "items": { "type": "object", "required": [ "input", "problem" ], "properties": { "input": { "type": "string" }, "problem": { "type": "string" }, "accepted": { "type": "array", "items": { "type": "string" } } } } }, "didYouMean": { "type": "array", "items": { "type": "string" } } } } } } }, "413": { "description": "The request was refused; every problem is listed.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "title", "status", "problems" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "problems": { "type": "array", "items": { "type": "object", "required": [ "input", "problem" ], "properties": { "input": { "type": "string" }, "problem": { "type": "string" }, "accepted": { "type": "array", "items": { "type": "string" } } } } }, "didYouMean": { "type": "array", "items": { "type": "string" } } } } } } } }, "tags": [ "Planner" ], "parameters": [ { "name": "detail", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "full", "summary" ], "default": "full", "description": "full (the default): the whole answer. summary: the result lines, the citation line and the page only — fewer tokens to read." }, "description": "summary: the result lines, the citation and the page only (fewer tokens); full, the default: the whole answer. A POST body may carry detail instead." }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json", "md" ] }, "description": "md: the engine's Markdown report as text/markdown (or send Accept: text/markdown); json, the default." } ] } }, "/drawing": { "post": { "operationId": "createDrawing", "summary": "Draw a house on the Construction Canvas", "description": "Exactly one of house, commands or document. Returns the canvas document, everything the canvas lists for it, and a My Project file carrying the drawing.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "house": { "type": "object", "additionalProperties": false, "properties": { "example": { "type": "string", "maxLength": 120, "description": "Start from one of the site's example houses (its slug) in place of the estimator's opening house." }, "values": { "type": "object", "maxProperties": 30, "description": "The form's figures, each length with its unit: length, width, storeyHeight, eaveOverhang, rakeOverhang, slabThickness, footingWidth, footingDepth, trenchDepth, windowWidth, windowHeight, doorWidth, doorHeight (\"12 m\", \"40 ft\"); and the counts partitions, windows, outsideDoors, interiorDoors, iceDamEaves. Any left out opens where the page opens it.", "additionalProperties": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] } }, "storeys": { "type": "integer", "enum": [ 1, 2 ] }, "family": { "type": "string", "enum": [ "wall.framed-exterior", "wall.masonry", "wall.sip" ] }, "selection": { "type": "object", "maxProperties": 20, "additionalProperties": { "type": "string", "maxLength": 80 }, "description": "The exterior wall's build-up choices." }, "pitch": { "type": "string", "enum": [ "4", "6", "8", "10", "12" ], "description": "Roof pitch, rise in 12." }, "roofFamily": { "type": "string", "enum": [ "roof.asphalt-shingle", "roof.tile-slate" ] }, "roofSelection": { "type": "object", "maxProperties": 20, "additionalProperties": { "type": "string", "maxLength": 80 } } }, "description": "The House Estimator's form: the house drawn as the estimator draws it." }, "commands": { "type": "array", "minItems": 1, "maxItems": 500, "items": { "type": "object", "required": [ "op" ], "properties": { "op": { "enum": [ "level", "type", "wall", "opening", "room", "outline", "path", "point", "beam", "stair" ] }, "ref": { "type": "string", "maxLength": 60, "description": "A name by which later commands refer to what this one makes." }, "name": { "type": "string", "maxLength": 60, "description": "A level's, a type's or a room's name." }, "level": { "type": "string", "maxLength": 60, "description": "A ref given to an earlier command, or the name of a level or type (the blank drawing has the level \"ground\" and the types EW-1, IW-1, WN-1, DR-1)." }, "type": { "type": "string", "maxLength": 60, "description": "A ref given to an earlier command, or the name of a level or type (the blank drawing has the level \"ground\" and the types EW-1, IW-1, WN-1, DR-1)." }, "wall": { "type": "string", "maxLength": 60, "description": "The wall an opening goes in: its ref." }, "c": { "type": "string", "maxLength": 40, "description": "outline: slab, roof, floor, driveway, patio, deck, landscaping; path: footing, cable, pipe, duct, fence, retaining-wall; point: column, pier, outlet, switch, light, panel, fixture, drain, radiator, register." }, "kind": { "enum": [ "door", "window" ] }, "assembly": { "type": "string", "maxLength": 80, "description": "A type's build-up: a canvas assembly id (wall.framed-exterior, roof.asphalt-shingle, slab.on-grade …)." }, "selection": { "type": "object", "maxProperties": 20, "additionalProperties": { "type": "string", "maxLength": 80 } }, "thickness": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] }, "wastePercent": { "type": "number", "minimum": 0, "maximum": 100 }, "elevation": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] }, "height": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] }, "from": { "type": "object", "additionalProperties": false, "required": [ "x", "y" ], "properties": { "x": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] }, "y": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] } }, "description": "A point on plan, each coordinate a length with its unit." }, "to": { "type": "object", "additionalProperties": false, "required": [ "x", "y" ], "properties": { "x": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] }, "y": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] } }, "description": "A point on plan, each coordinate a length with its unit." }, "at": { "type": "object", "additionalProperties": false, "required": [ "x", "y" ], "properties": { "x": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] }, "y": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] } }, "description": "A point on plan, each coordinate a length with its unit." }, "offset": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ], "description": "An opening's centre, measured along its wall from the wall's start." }, "points": { "type": "array", "minItems": 2, "maxItems": 500, "items": { "type": "object", "additionalProperties": false, "required": [ "x", "y" ], "properties": { "x": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] }, "y": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] } }, "description": "A point on plan, each coordinate a length with its unit." } }, "closed": { "type": "boolean" }, "p": { "type": "object", "maxProperties": 20, "description": "The component's own properties by id (components/properties.ts): a length with its unit (widthMm, heightMm, sillMm …), a choice's option id, a count, true or false." }, "finishes": { "type": "object", "maxProperties": 10, "additionalProperties": { "type": "string", "maxLength": 80 }, "description": "A room's, or a driveway's, patio's, deck's, fence's or retaining wall's surface role → finish id, by the planner's ids." }, "scope": { "type": "object", "maxProperties": 30, "additionalProperties": { "type": [ "string", "number", "boolean" ] }, "description": "Its scope question name → answer, by the planner's ids." } } }, "description": "Drawing commands, in order, on the canvas's blank drawing (one storey; the wall, partition, window and door types). The whole request is at most 64 KiB." }, "document": { "type": "object", "description": "A Construction Canvas document (schema 1 to the canvas's current), opened and checked by the canvas's own opener." }, "shapes": { "type": "array", "minItems": 1, "maxItems": 40, "items": { "type": "object", "additionalProperties": false, "required": [ "shape" ], "properties": { "shape": { "enum": [ "room", "deck", "patio", "bed", "path", "fence" ], "description": "room: four exterior walls with doors and windows; deck, patio, bed (planted): a rectangle; path: a paved strip; fence: legs and 90° turns. Anything else is refused." }, "ref": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,40}$", "description": "A name a later shape's against uses." }, "name": { "type": "string", "maxLength": 60, "description": "A room's name." }, "at": { "type": "object", "additionalProperties": false, "required": [ "x", "y" ], "properties": { "x": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] }, "y": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] } }, "description": "The south-west corner (a path's or a fence's start). Left out: the origin." }, "width": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ], "description": "Along x (east): a room's, deck's, patio's or bed's; a path's width across it." }, "depth": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ], "description": "Along y (north); for a deck or patio against a side, out from it." }, "length": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ], "description": "A path's length." }, "heading": { "enum": [ "south", "east", "north", "west" ], "description": "The way a path or a fence's first leg runs (default east)." }, "against": { "type": "object", "additionalProperties": false, "required": [ "shape", "side" ], "properties": { "shape": { "type": "string" }, "side": { "enum": [ "south", "east", "north", "west" ] }, "offset": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] } }, "description": "A deck, patio or bed against a side of an earlier room or rectangle: centred on it, or from its west or south end by offset." }, "doors": { "type": "array", "maxItems": 20, "items": { "type": "object", "additionalProperties": false, "required": [ "side", "offset" ], "properties": { "side": { "enum": [ "south", "east", "north", "west" ] }, "offset": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ], "description": "Along the wall from its start: walls run counter-clockwise from the south-west corner." }, "exterior": { "type": "boolean", "description": "A door: an outside door (the default) or an inside one." } } } }, "windows": { "type": "array", "maxItems": 20, "items": { "type": "object", "additionalProperties": false, "required": [ "side", "offset" ], "properties": { "side": { "enum": [ "south", "east", "north", "west" ] }, "offset": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ], "description": "Along the wall from its start: walls run counter-clockwise from the south-west corner." }, "exterior": { "type": "boolean", "description": "A door: an outside door (the default) or an inside one." } } } }, "legs": { "type": "array", "minItems": 1, "maxItems": 20, "items": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] }, "description": "A fence's straight runs, in order." }, "turns": { "type": "array", "maxItems": 19, "items": { "enum": [ "left", "right" ] }, "description": "A 90° turn between each two legs." }, "gates": { "type": "array", "maxItems": 20, "items": { "type": "object", "additionalProperties": false, "required": [ "leg", "offset", "width" ], "properties": { "leg": { "type": "integer", "minimum": 1 }, "offset": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] }, "width": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] } } }, "description": "Gate openings, by leg (from 1) and offset along it; taken out of the run, the gate itself not counted." }, "build": { "enum": [ "pavers", "concrete" ], "description": "A patio's or path's build: a patio is concrete unless pavers; a path is pavers unless concrete." }, "finishes": { "type": "object", "maxProperties": 10, "additionalProperties": { "type": "string", "maxLength": 80 } }, "scope": { "type": "object", "maxProperties": 30, "additionalProperties": { "type": [ "string", "number", "boolean" ] } }, "p": { "type": "object", "maxProperties": 20, "description": "The component's own properties: a fence's heightMm, a bed's mulchDepthMm, each length with its unit." } } }, "description": "Simple shapes the assistant has read from the reader's words — a room, a deck, a patio, a bed, a path, a fence of legs and turns — compiled into the canvas's own commands. Every length with its unit." }, "layout": { "type": "object", "additionalProperties": false, "required": [ "rooms" ], "properties": { "grid": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ], "description": "The grid every figure is snapped to (default 10 mm, or 1/2 in in US units). Each snap that changed a figure is reported." }, "rooms": { "type": "array", "minItems": 1, "maxItems": 30, "items": { "type": "object", "additionalProperties": false, "required": [ "name", "width", "depth" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 60, "description": "Unique in the layout; openings and later rooms refer to it." }, "width": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ], "description": "Along x (east), wall centre to wall centre." }, "depth": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ], "description": "Along y (north), wall centre to wall centre." }, "at": { "type": "object", "additionalProperties": false, "required": [ "x", "y" ], "properties": { "x": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] }, "y": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] } }, "description": "Its south-west corner. The first room without at or against is at the origin." }, "against": { "type": "object", "additionalProperties": false, "required": [ "room", "side" ], "properties": { "room": { "type": "string", "maxLength": 60 }, "side": { "enum": [ "south", "east", "north", "west" ] }, "align": { "enum": [ "start", "centre", "end" ], "description": "Along that side: flush with its west or south end (start, the default), centred, or flush with the other end." }, "offset": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] } }, "description": "Beside a side of an earlier room, sharing that wall." } } } }, "doors": { "type": "array", "maxItems": 60, "items": { "type": "object", "additionalProperties": false, "properties": { "room": { "type": "string", "maxLength": 60, "description": "The room it is in, by name." }, "side": { "enum": [ "south", "east", "north", "west" ], "description": "The side of that room." }, "offset": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ], "description": "Its centre along the side from the side's start (walls counter-clockwise from the south-west corner); left out, the middle." }, "between": { "type": "array", "minItems": 2, "maxItems": 2, "items": { "type": "string", "maxLength": 60 }, "description": "A door only: the two rooms it joins, on the wall they share." }, "width": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ], "description": "The opening's width; left out, the canvas's default." } } }, "description": "Each between two rooms, or in a room's side (an outside door where that side is an exterior wall)." }, "windows": { "type": "array", "maxItems": 60, "items": { "type": "object", "additionalProperties": false, "properties": { "room": { "type": "string", "maxLength": 60, "description": "The room it is in, by name." }, "side": { "enum": [ "south", "east", "north", "west" ], "description": "The side of that room." }, "offset": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ], "description": "Its centre along the side from the side's start (walls counter-clockwise from the south-west corner); left out, the middle." }, "between": { "type": "array", "minItems": 2, "maxItems": 2, "items": { "type": "string", "maxLength": 60 }, "description": "A door only: the two rooms it joins, on the wall they share." }, "width": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ], "description": "The opening's width; left out, the canvas's default." } } }, "description": "Each in a room's side, on an exterior wall." } }, "description": "Rooms by name, size and which room each stands against, laid out on a grid: shared walls drawn once as partitions, every snap or move reported, and each room checked to close." }, "template": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$", "description": "A Construction Canvas template's slug (the template index lists them: single-room, deck, two-car-garage …): the drawing its page shows, in the reader's system, with a link that opens it." }, "variant": { "type": "string", "pattern": "^[a-z0-9-]{1,40}$", "description": "With template: one of its two \"what changes if\" variants, by id; a wrong one is refused with the template's own list." }, "name": { "type": "string", "maxLength": 120, "description": "The project's name in the file." }, "system": { "type": "string", "enum": [ "metric", "imperial" ], "default": "metric", "description": "The unit system inputs left out open in, and the one the page link opens in. The answer comes in both." }, "inputUnits": { "type": "string", "enum": [ "base" ], "description": "Send \"base\" to pass bare numbers on dimensioned inputs in base units (m, m², L, kg …), as the published test vectors are written. Without it a length, area or volume must carry its unit." } } }, "example": { "commands": [ { "op": "wall", "ref": "south", "from": { "x": "0 m", "y": "0 m" }, "to": { "x": "6 m", "y": "0 m" } }, { "op": "wall", "from": { "x": "6 m", "y": "0 m" }, "to": { "x": "6 m", "y": "4 m" } }, { "op": "wall", "from": { "x": "6 m", "y": "4 m" }, "to": { "x": "0 m", "y": "4 m" } }, { "op": "wall", "from": { "x": "0 m", "y": "4 m" }, "to": { "x": "0 m", "y": "0 m" } }, { "op": "opening", "kind": "door", "wall": "south", "offset": "1.5 m", "p": { "exterior": true } }, { "op": "opening", "kind": "window", "wall": "south", "offset": "4 m" }, { "op": "room", "name": "Studio", "at": { "x": "3 m", "y": "2 m" } } ], "name": "Studio", "system": "metric" }, "examples": { "create_drawing": { "summary": "Draw a 6 × 4 m studio with a door and a window, list it, and give me the file.", "value": { "commands": [ { "op": "wall", "ref": "south", "from": { "x": "0 m", "y": "0 m" }, "to": { "x": "6 m", "y": "0 m" } }, { "op": "wall", "from": { "x": "6 m", "y": "0 m" }, "to": { "x": "6 m", "y": "4 m" } }, { "op": "wall", "from": { "x": "6 m", "y": "4 m" }, "to": { "x": "0 m", "y": "4 m" } }, { "op": "wall", "from": { "x": "0 m", "y": "4 m" }, "to": { "x": "0 m", "y": "0 m" } }, { "op": "opening", "kind": "door", "wall": "south", "offset": "1.5 m", "p": { "exterior": true } }, { "op": "opening", "kind": "window", "wall": "south", "offset": "4 m" }, { "op": "room", "name": "Studio", "at": { "x": "3 m", "y": "2 m" } } ], "name": "Studio", "system": "metric" } } } } } }, "responses": { "200": { "description": "The drawing, its list and the file that carries it.", "content": { "application/json": { "schema": { "type": "object", "anyOf": [ { "type": "object", "required": [ "engine", "system", "from", "document", "counts", "rows", "objects", "lines", "assumptions", "omitted", "plans", "labour", "sources", "file", "links", "howToOpen", "citation", "licence", "notice" ], "properties": { "engine": { "type": "object" }, "system": { "enum": [ "metric", "imperial" ] }, "from": { "enum": [ "house", "commands", "document", "shapes", "template", "layout" ] }, "layout": { "type": "object", "required": [ "grid", "rooms", "walls", "adjustments", "checks" ], "description": "The rooms as laid out (both unit systems), the walls drawn, every figure snapped or room moved, and the closure check." }, "template": { "type": "object", "required": [ "slug", "name", "page", "variant", "variants" ], "description": "The template it was drawn from: its page, the variant drawn (null: as the page shows it) and its variants." }, "shapes": { "type": "array", "items": { "type": "object", "required": [ "shape", "ref", "made", "figures" ] } }, "shapeNotes": { "type": "array", "items": { "type": "string" } }, "house": { "type": "object" }, "document": { "type": "object", "required": [ "schema", "units", "counters", "levels", "types", "entities", "assumed", "updatedAt" ] }, "counts": { "type": "object", "required": [ "walls", "openings", "levels" ] }, "rows": { "type": "array", "items": { "type": "object", "required": [ "key", "section", "label", "where", "quantity", "unit", "otherSystem", "calculator" ], "properties": { "key": { "type": "string" }, "section": { "type": "string" }, "label": { "type": "string" }, "where": { "type": "string" }, "quantity": { "type": "number" }, "unit": { "type": "string" }, "order": { "type": "object", "required": [ "quantity", "unit" ] }, "otherSystem": { "anyOf": [ { "type": "object", "required": [ "quantity", "unit" ] }, { "type": "null" } ] }, "calculator": { "type": "object", "required": [ "slug", "title" ] }, "note": { "type": "string" } } } }, "objects": { "type": "array", "items": { "type": "object", "required": [ "key", "label", "quantity" ] } }, "lines": { "type": "array", "items": { "type": "object", "required": [ "label", "quantity", "unit", "zone" ] } }, "assumptions": { "type": "array", "items": { "type": "object", "required": [ "field", "reason" ] } }, "omitted": { "type": "array" }, "plans": { "type": "array" }, "labour": { "type": "object", "required": [ "rows", "totalHours", "programme", "likelyDays", "note" ] }, "sources": { "type": "array" }, "file": { "type": "object", "required": [ "filename", "mediaType", "content" ], "properties": { "filename": { "type": "string" }, "mediaType": { "const": "application/json" }, "content": { "type": "object", "required": [ "magic", "v", "exportedAt", "stores" ], "properties": { "magic": { "const": "craftquantities.backup" }, "v": { "type": "integer" }, "exportedAt": { "type": "string" }, "stores": { "type": "object" } } } } }, "links": { "type": "object", "required": [ "canvas", "drawing" ], "properties": { "canvas": { "type": "string" }, "drawing": { "anyOf": [ { "type": "string", "description": "Opens this drawing on the canvas as a new project's: the drawing rides in the fragment, so nothing is uploaded. Null when the drawing is too large for a link." }, { "type": "null" } ] }, "estimator": { "type": "string" }, "template": { "type": "string", "description": "The template's page, when the drawing is a template's: cite it beside the drawing's link." } } }, "drawingLink": { "type": "string" }, "howToOpen": { "type": "string" }, "citation": { "type": "object", "required": [ "author", "title", "url", "formats", "accessDate" ], "properties": { "author": { "type": "string" }, "title": { "type": "string" }, "version": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sourcesChecked": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "url": { "type": "string" }, "accessDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "formats": { "type": "object", "required": [ "plain", "apa", "harvard", "bibtex" ], "properties": { "plain": { "type": "string" }, "apa": { "type": "string" }, "harvard": { "type": "string" }, "bibtex": { "type": "string" } } } } }, "licence": { "type": "object", "required": [ "name", "url", "attribution" ], "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "attribution": { "type": "string" } } }, "notice": { "type": "string" } } }, { "type": "object", "required": [ "detail", "tool", "title", "lines", "notes", "citation", "url", "open", "more" ], "properties": { "detail": { "const": "summary" }, "tool": { "type": "string" }, "title": { "type": "string" }, "lines": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "string" } }, "description": "The result lines, as the report's table gives them." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "What a professional must decide, when to call one, a false-friend warning, that adoption is local: kept in every summary." }, "citation": { "type": "string", "description": "The one citation line, built from the answer's own data." }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "open": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "more": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } ] } } } }, "400": { "description": "The request was refused; every problem is listed.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "title", "status", "problems" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "problems": { "type": "array", "items": { "type": "object", "required": [ "input", "problem" ], "properties": { "input": { "type": "string" }, "problem": { "type": "string" }, "accepted": { "type": "array", "items": { "type": "string" } } } } }, "didYouMean": { "type": "array", "items": { "type": "string" } } } } } } }, "404": { "description": "The request was refused; every problem is listed.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "title", "status", "problems" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "problems": { "type": "array", "items": { "type": "object", "required": [ "input", "problem" ], "properties": { "input": { "type": "string" }, "problem": { "type": "string" }, "accepted": { "type": "array", "items": { "type": "string" } } } } }, "didYouMean": { "type": "array", "items": { "type": "string" } } } } } } }, "413": { "description": "The request was refused; every problem is listed.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "title", "status", "problems" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "problems": { "type": "array", "items": { "type": "object", "required": [ "input", "problem" ], "properties": { "input": { "type": "string" }, "problem": { "type": "string" }, "accepted": { "type": "array", "items": { "type": "string" } } } } }, "didYouMean": { "type": "array", "items": { "type": "string" } } } } } } }, "422": { "description": "The request was refused; every problem is listed.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "title", "status", "problems" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "problems": { "type": "array", "items": { "type": "object", "required": [ "input", "problem" ], "properties": { "input": { "type": "string" }, "problem": { "type": "string" }, "accepted": { "type": "array", "items": { "type": "string" } } } } }, "didYouMean": { "type": "array", "items": { "type": "string" } } } } } } } }, "tags": [ "House and canvas" ], "parameters": [ { "name": "detail", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "full", "summary" ], "default": "full", "description": "full (the default): the whole answer. summary: the result lines, the citation line and the page only — fewer tokens to read." }, "description": "summary: the result lines, the citation and the page only (fewer tokens); full, the default: the whole answer. A POST body may carry detail instead." }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json", "md" ] }, "description": "md: the engine's Markdown report as text/markdown (or send Accept: text/markdown); json, the default." } ] } }, "/quote-import": { "post": { "operationId": "importQuote", "summary": "The reader's own quote, prices and all, as a My Project file", "description": "The prices are the reader's own figures from the quote they supply, never the site's. Nothing is stored.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "quote" ], "properties": { "quote": { "type": "string", "maxLength": 20000 }, "supplier": { "type": "string", "maxLength": 120 }, "currency": { "type": "string", "maxLength": 8 }, "market": { "type": "string", "enum": [ "US", "CA", "UK", "AU", "INTL" ], "description": "Optional. A market whose own opening choice some inputs take (a UK reader's code, an IEC motor), and whose currency symbol prints the caller's own money figures." }, "name": { "type": "string", "maxLength": 120 } } }, "example": { "quote": "Plasterboard 12.5 mm 30 sheets @ 9.50\nJointing compound 4 bags @ 12.00", "currency": "£", "supplier": "Builders' merchant" }, "examples": { "import_quote": { "summary": "Turn my supplier's quote into a My Project file, prices and all.", "value": { "quote": "Plasterboard 12.5 mm 30 sheets @ 9.50\nJointing compound 4 bags @ 12.00", "currency": "£", "supplier": "Builders' merchant" } } } } } }, "responses": { "200": { "description": "The quote as read, its arithmetic, and the file.", "content": { "application/json": { "schema": { "type": "object", "anyOf": [ { "type": "object", "required": [ "engine", "pricesAreTheReaders", "currency", "lines", "declared", "totals", "arithmetic", "skipped", "file", "howToImport", "licence" ], "properties": { "engine": { "type": "object" }, "pricesAreTheReaders": { "type": "string" }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lines": { "type": "array", "items": { "type": "object", "required": [ "section", "text", "unit", "kind", "doubts", "source" ] } }, "declared": { "type": "object" }, "totals": { "type": "object", "required": [ "subtotal", "tax", "total", "unpriced" ] }, "arithmetic": { "type": "array" }, "skipped": { "type": "array", "items": { "type": "string" } }, "file": { "type": "object", "required": [ "filename", "mediaType", "content" ] }, "howToImport": { "type": "string" }, "licence": { "type": "object", "required": [ "name", "url", "attribution" ], "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "attribution": { "type": "string" } } } } }, { "type": "object", "required": [ "detail", "tool", "title", "lines", "notes", "citation", "url", "open", "more" ], "properties": { "detail": { "const": "summary" }, "tool": { "type": "string" }, "title": { "type": "string" }, "lines": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "string" } }, "description": "The result lines, as the report's table gives them." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "What a professional must decide, when to call one, a false-friend warning, that adoption is local: kept in every summary." }, "citation": { "type": "string", "description": "The one citation line, built from the answer's own data." }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "open": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "more": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } ] } } } }, "400": { "description": "The request was refused; every problem is listed.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "title", "status", "problems" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "problems": { "type": "array", "items": { "type": "object", "required": [ "input", "problem" ], "properties": { "input": { "type": "string" }, "problem": { "type": "string" }, "accepted": { "type": "array", "items": { "type": "string" } } } } }, "didYouMean": { "type": "array", "items": { "type": "string" } } } } } } }, "413": { "description": "The request was refused; every problem is listed.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "title", "status", "problems" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "problems": { "type": "array", "items": { "type": "object", "required": [ "input", "problem" ], "properties": { "input": { "type": "string" }, "problem": { "type": "string" }, "accepted": { "type": "array", "items": { "type": "string" } } } } }, "didYouMean": { "type": "array", "items": { "type": "string" } } } } } } } }, "tags": [ "Quotes" ], "parameters": [ { "name": "detail", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "full", "summary" ], "default": "full", "description": "full (the default): the whole answer. summary: the result lines, the citation line and the page only — fewer tokens to read." }, "description": "summary: the result lines, the citation and the page only (fewer tokens); full, the default: the whole answer. A POST body may carry detail instead." }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json", "md" ] }, "description": "md: the engine's Markdown report as text/markdown (or send Accept: text/markdown); json, the default." } ] } }, "/diagnose": { "get": { "operationId": "diagnoseSymptomGet", "summary": "Diagnosis pages that match a symptom, with candidate causes and how to tell them apart", "parameters": [ { "name": "symptom", "in": "query", "required": true, "schema": { "type": "string", "minLength": 3, "maxLength": 300, "description": "What the reader sees, hears or smells, in their own words: \"my breaker keeps tripping when the kettle is on\"." } }, { "name": "market", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "US", "CA", "UK", "AU", "INTL" ], "description": "Optional. A market whose own opening choice some inputs take (a UK reader's code, an IEC motor), and whose currency symbol prints the caller's own money figures." } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 3, "description": "How many diagnoses at most. Left out: one when the match is clear, up to three when it is not." } }, { "name": "detail", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "full", "summary" ], "default": "full", "description": "full (the default): the whole answer. summary: the result lines, the citation line and the page only — fewer tokens to read." }, "description": "summary: the result lines, the citation and the page only (fewer tokens); full, the default: the whole answer. A POST body may carry detail instead." }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json", "md" ] }, "description": "md: the engine's Markdown report as text/markdown (or send Accept: text/markdown); json, the default." } ], "responses": { "200": { "description": "The matching diagnoses, or the candidates where the words fit several.", "content": { "application/json": { "schema": { "type": "object", "anyOf": [ { "type": "object", "required": [ "engine", "symptom", "match", "matchedBy", "note", "diagnoses", "alsoConsider", "links", "citation", "licence", "notice" ], "properties": { "engine": { "type": "object" }, "symptom": { "type": "string" }, "market": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "match": { "enum": [ "clear", "ambiguous", "none" ] }, "matchedBy": { "enum": [ "site-search", "shared-words" ] }, "note": { "type": "string" }, "diagnoses": { "type": "array", "items": { "type": "object", "required": [ "kind", "slug", "symptom", "url", "callAProfessional" ], "properties": { "kind": { "enum": [ "diagnosis", "structural" ] }, "slug": { "type": "string" }, "symptom": { "type": "string" }, "family": { "type": "string" }, "url": { "type": "string" }, "verdict": { "type": "string", "description": "The page's first line: what to act on before reading further. Not a diagnosis." }, "causes": { "type": "array", "items": { "type": "object", "required": [ "cause", "likelihood", "distinguishedBy", "check" ], "properties": { "cause": { "type": "string" }, "likelihood": { "enum": [ "most common", "common", "less common", "uncommon" ] }, "distinguishedBy": { "type": "string", "description": "What tells this cause apart from the others." }, "check": { "type": "string", "description": "The one thing to look at to confirm or rule it out." } } } }, "checks": { "type": "array", "items": { "type": "object", "required": [ "step", "why" ], "properties": { "step": { "type": "string" }, "why": { "type": "string" } } } }, "callAProfessional": { "type": "array", "items": { "type": "string" } }, "calculators": { "type": "array", "items": { "type": "object", "required": [ "slug", "title", "url" ], "properties": { "slug": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" } } } }, "related": { "type": "array", "items": { "type": "object", "required": [ "slug", "url" ] } }, "looksLike": { "type": "string" }, "whyStructural": { "type": "string" }, "urgency": { "type": "string" } } } }, "alsoConsider": { "type": "array", "items": { "type": "object", "required": [ "slug", "symptom" ] } }, "links": { "type": "object", "required": [ "hub", "structural" ] }, "citation": { "type": "object", "required": [ "author", "title", "url", "formats", "accessDate" ], "properties": { "author": { "type": "string" }, "title": { "type": "string" }, "version": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sourcesChecked": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "url": { "type": "string" }, "accessDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "formats": { "type": "object", "required": [ "plain", "apa", "harvard", "bibtex" ], "properties": { "plain": { "type": "string" }, "apa": { "type": "string" }, "harvard": { "type": "string" }, "bibtex": { "type": "string" } } } } }, "licence": { "type": "object", "required": [ "name", "url", "attribution" ], "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "attribution": { "type": "string" } } }, "notice": { "type": "string" } } }, { "type": "object", "required": [ "detail", "tool", "title", "lines", "notes", "citation", "url", "open", "more" ], "properties": { "detail": { "const": "summary" }, "tool": { "type": "string" }, "title": { "type": "string" }, "lines": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "string" } }, "description": "The result lines, as the report's table gives them." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "What a professional must decide, when to call one, a false-friend warning, that adoption is local: kept in every summary." }, "citation": { "type": "string", "description": "The one citation line, built from the answer's own data." }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "open": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "more": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } ] } } } }, "400": { "description": "The request was refused; every problem is listed.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "title", "status", "problems" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "problems": { "type": "array", "items": { "type": "object", "required": [ "input", "problem" ], "properties": { "input": { "type": "string" }, "problem": { "type": "string" }, "accepted": { "type": "array", "items": { "type": "string" } } } } }, "didYouMean": { "type": "array", "items": { "type": "string" } } } } } } } }, "tags": [ "Diagnoses and documents" ] }, "post": { "operationId": "diagnoseSymptom", "summary": "Diagnosis pages that match a symptom", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "symptom" ], "properties": { "symptom": { "type": "string", "minLength": 3, "maxLength": 300, "description": "What the reader sees, hears or smells, in their own words: \"my breaker keeps tripping when the kettle is on\"." }, "market": { "type": "string", "enum": [ "US", "CA", "UK", "AU", "INTL" ], "description": "Optional. A market whose own opening choice some inputs take (a UK reader's code, an IEC motor), and whose currency symbol prints the caller's own money figures." }, "limit": { "type": "integer", "minimum": 1, "maximum": 3, "description": "How many diagnoses at most. Left out: one when the match is clear, up to three when it is not." } } } } } }, "responses": { "200": { "description": "The matching diagnoses, or the candidates where the words fit several.", "content": { "application/json": { "schema": { "type": "object", "anyOf": [ { "type": "object", "required": [ "engine", "symptom", "match", "matchedBy", "note", "diagnoses", "alsoConsider", "links", "citation", "licence", "notice" ], "properties": { "engine": { "type": "object" }, "symptom": { "type": "string" }, "market": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "match": { "enum": [ "clear", "ambiguous", "none" ] }, "matchedBy": { "enum": [ "site-search", "shared-words" ] }, "note": { "type": "string" }, "diagnoses": { "type": "array", "items": { "type": "object", "required": [ "kind", "slug", "symptom", "url", "callAProfessional" ], "properties": { "kind": { "enum": [ "diagnosis", "structural" ] }, "slug": { "type": "string" }, "symptom": { "type": "string" }, "family": { "type": "string" }, "url": { "type": "string" }, "verdict": { "type": "string", "description": "The page's first line: what to act on before reading further. Not a diagnosis." }, "causes": { "type": "array", "items": { "type": "object", "required": [ "cause", "likelihood", "distinguishedBy", "check" ], "properties": { "cause": { "type": "string" }, "likelihood": { "enum": [ "most common", "common", "less common", "uncommon" ] }, "distinguishedBy": { "type": "string", "description": "What tells this cause apart from the others." }, "check": { "type": "string", "description": "The one thing to look at to confirm or rule it out." } } } }, "checks": { "type": "array", "items": { "type": "object", "required": [ "step", "why" ], "properties": { "step": { "type": "string" }, "why": { "type": "string" } } } }, "callAProfessional": { "type": "array", "items": { "type": "string" } }, "calculators": { "type": "array", "items": { "type": "object", "required": [ "slug", "title", "url" ], "properties": { "slug": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" } } } }, "related": { "type": "array", "items": { "type": "object", "required": [ "slug", "url" ] } }, "looksLike": { "type": "string" }, "whyStructural": { "type": "string" }, "urgency": { "type": "string" } } } }, "alsoConsider": { "type": "array", "items": { "type": "object", "required": [ "slug", "symptom" ] } }, "links": { "type": "object", "required": [ "hub", "structural" ] }, "citation": { "type": "object", "required": [ "author", "title", "url", "formats", "accessDate" ], "properties": { "author": { "type": "string" }, "title": { "type": "string" }, "version": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sourcesChecked": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "url": { "type": "string" }, "accessDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "formats": { "type": "object", "required": [ "plain", "apa", "harvard", "bibtex" ], "properties": { "plain": { "type": "string" }, "apa": { "type": "string" }, "harvard": { "type": "string" }, "bibtex": { "type": "string" } } } } }, "licence": { "type": "object", "required": [ "name", "url", "attribution" ], "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "attribution": { "type": "string" } } }, "notice": { "type": "string" } } }, { "type": "object", "required": [ "detail", "tool", "title", "lines", "notes", "citation", "url", "open", "more" ], "properties": { "detail": { "const": "summary" }, "tool": { "type": "string" }, "title": { "type": "string" }, "lines": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "string" } }, "description": "The result lines, as the report's table gives them." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "What a professional must decide, when to call one, a false-friend warning, that adoption is local: kept in every summary." }, "citation": { "type": "string", "description": "The one citation line, built from the answer's own data." }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "open": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "more": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } ] } } } }, "400": { "description": "The request was refused; every problem is listed.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "title", "status", "problems" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "problems": { "type": "array", "items": { "type": "object", "required": [ "input", "problem" ], "properties": { "input": { "type": "string" }, "problem": { "type": "string" }, "accepted": { "type": "array", "items": { "type": "string" } } } } }, "didYouMean": { "type": "array", "items": { "type": "string" } } } } } } } }, "tags": [ "Diagnoses and documents" ], "parameters": [ { "name": "detail", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "full", "summary" ], "default": "full", "description": "full (the default): the whole answer. summary: the result lines, the citation line and the page only — fewer tokens to read." }, "description": "summary: the result lines, the citation and the page only (fewer tokens); full, the default: the whole answer. A POST body may carry detail instead." }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json", "md" ] }, "description": "md: the engine's Markdown report as text/markdown (or send Accept: text/markdown); json, the default." } ] } }, "/solve/{page}": { "get": { "operationId": "solveBackwardsGet", "summary": "What an amount of material covers, on one Solve Backwards page", "description": "Every other query parameter is a calculator setting, with its unit.", "parameters": [ { "name": "page", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,80}$", "description": "A Solve Backwards page's slug, such as wall-paint, drywall-sheets, bricks, concrete-bags, ready-mix-concrete." } }, { "name": "have", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 60 }, "description": "How much: 20, or 24%20gal." }, { "name": "system", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "metric", "imperial" ], "default": "metric", "description": "The unit system inputs left out open in, and the one the page link opens in. The answer comes in both." } }, { "name": "detail", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "full", "summary" ], "default": "full", "description": "full (the default): the whole answer. summary: the result lines, the citation line and the page only — fewer tokens to read." }, "description": "summary: the result lines, the citation and the page only (fewer tokens); full, the default: the whole answer. A POST body may carry detail instead." }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json", "md" ] }, "description": "md: the engine's Markdown report as text/markdown (or send Accept: text/markdown); json, the default." } ], "responses": { "200": { "description": "The area and the size it covers, as the page works it.", "content": { "application/json": { "schema": { "type": "object", "anyOf": [ { "type": "object", "required": [ "engine", "page", "calculator", "system", "have", "status", "answer", "area", "size", "typical", "chain", "forwards", "assumptions", "settings", "links", "citation", "licence", "notice" ], "properties": { "engine": { "type": "object" }, "page": { "type": "object", "required": [ "slug", "question", "material", "url" ] }, "calculator": { "type": "object", "required": [ "slug", "title", "version", "url" ] }, "otherPages": { "type": "array", "items": { "type": "object", "required": [ "slug", "question", "url" ] } }, "system": { "enum": [ "metric", "imperial" ] }, "have": { "type": "object", "required": [ "amount", "unit", "inCalculatorUnit" ] }, "status": { "enum": [ "reached", "capped", "too-little" ], "description": "reached: the largest size whose requirement fits; capped: more than the calculator's largest job; too-little: less than its smallest." }, "answer": { "type": "string", "description": "The page's own answer line." }, "area": { "anyOf": [ { "type": "object", "required": [ "noun", "exact", "metric", "imperial" ] }, { "type": "null" } ] }, "size": { "anyOf": [ { "type": "object", "required": [ "metres", "feet" ], "properties": { "metres": { "type": "object", "additionalProperties": { "type": "number" } }, "feet": { "type": "object", "additionalProperties": { "type": "number" } } } }, { "type": "null" } ] }, "typical": { "type": "object", "required": [ "count", "each", "size" ] }, "chain": { "type": "array", "items": { "type": "string" } }, "forwards": { "anyOf": [ { "type": "object", "required": [ "inputs", "asks", "left" ] }, { "type": "null" } ] }, "assumptions": { "type": "array", "items": { "type": "object", "required": [ "id", "label", "value" ] } }, "settings": { "type": "array" }, "links": { "type": "object", "required": [ "page", "openInSite", "calculator" ] }, "note": { "type": "string" }, "citation": { "type": "object", "required": [ "author", "title", "url", "formats", "accessDate" ], "properties": { "author": { "type": "string" }, "title": { "type": "string" }, "version": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sourcesChecked": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "url": { "type": "string" }, "accessDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "formats": { "type": "object", "required": [ "plain", "apa", "harvard", "bibtex" ], "properties": { "plain": { "type": "string" }, "apa": { "type": "string" }, "harvard": { "type": "string" }, "bibtex": { "type": "string" } } } } }, "licence": { "type": "object", "required": [ "name", "url", "attribution" ], "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "attribution": { "type": "string" } } }, "notice": { "type": "string" } } }, { "type": "object", "required": [ "detail", "tool", "title", "lines", "notes", "citation", "url", "open", "more" ], "properties": { "detail": { "const": "summary" }, "tool": { "type": "string" }, "title": { "type": "string" }, "lines": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "string" } }, "description": "The result lines, as the report's table gives them." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "What a professional must decide, when to call one, a false-friend warning, that adoption is local: kept in every summary." }, "citation": { "type": "string", "description": "The one citation line, built from the answer's own data." }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "open": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "more": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } ] } } } }, "400": { "description": "The request was refused; every problem is listed.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "title", "status", "problems" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "problems": { "type": "array", "items": { "type": "object", "required": [ "input", "problem" ], "properties": { "input": { "type": "string" }, "problem": { "type": "string" }, "accepted": { "type": "array", "items": { "type": "string" } } } } }, "didYouMean": { "type": "array", "items": { "type": "string" } } } } } } }, "404": { "description": "The request was refused; every problem is listed.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "title", "status", "problems" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "problems": { "type": "array", "items": { "type": "object", "required": [ "input", "problem" ], "properties": { "input": { "type": "string" }, "problem": { "type": "string" }, "accepted": { "type": "array", "items": { "type": "string" } } } } }, "didYouMean": { "type": "array", "items": { "type": "string" } } } } } } } }, "tags": [ "Solve backwards" ] } }, "/solve": { "post": { "operationId": "solveBackwards", "summary": "What an amount of material covers", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "have" ], "properties": { "page": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,80}$", "description": "A Solve Backwards page's slug, such as wall-paint, drywall-sheets, bricks, concrete-bags, ready-mix-concrete." }, "query": { "type": "string", "minLength": 2, "maxLength": 200, "description": "Or what the reader has, in words (\"sheets of drywall\", \"bags of concrete\"), when the slug is not known." }, "have": { "description": "How much the reader has: a count for counted things (20, \"20 sheets\"); a measure with its unit for paint, concrete, soil (\"24 gal\", \"2 m3\", {\"value\": 90, \"unit\": \"L\"}).", "oneOf": [ { "type": "number", "exclusiveMinimum": 0 }, { "type": "string", "maxLength": 60 }, { "type": "object", "additionalProperties": false, "required": [ "value", "unit" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 20 } } } ] }, "system": { "type": "string", "enum": [ "metric", "imperial" ], "description": "The page's system; it sets the market's product (a 4 × 8 ft sheet in imperial). Left out: the unit's system, else metric." }, "settings": { "type": "object", "maxProperties": 20, "additionalProperties": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 60 }, { "type": "object", "required": [ "value", "unit" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string" } } } ] }, "description": "Optional: another calculator input, with its unit (a slab's thickness \"4 in\", coats 3). The inputs the page grows cannot be set." } } } } } }, "responses": { "200": { "description": "The area and the size it covers, as the page works it.", "content": { "application/json": { "schema": { "type": "object", "anyOf": [ { "type": "object", "required": [ "engine", "page", "calculator", "system", "have", "status", "answer", "area", "size", "typical", "chain", "forwards", "assumptions", "settings", "links", "citation", "licence", "notice" ], "properties": { "engine": { "type": "object" }, "page": { "type": "object", "required": [ "slug", "question", "material", "url" ] }, "calculator": { "type": "object", "required": [ "slug", "title", "version", "url" ] }, "otherPages": { "type": "array", "items": { "type": "object", "required": [ "slug", "question", "url" ] } }, "system": { "enum": [ "metric", "imperial" ] }, "have": { "type": "object", "required": [ "amount", "unit", "inCalculatorUnit" ] }, "status": { "enum": [ "reached", "capped", "too-little" ], "description": "reached: the largest size whose requirement fits; capped: more than the calculator's largest job; too-little: less than its smallest." }, "answer": { "type": "string", "description": "The page's own answer line." }, "area": { "anyOf": [ { "type": "object", "required": [ "noun", "exact", "metric", "imperial" ] }, { "type": "null" } ] }, "size": { "anyOf": [ { "type": "object", "required": [ "metres", "feet" ], "properties": { "metres": { "type": "object", "additionalProperties": { "type": "number" } }, "feet": { "type": "object", "additionalProperties": { "type": "number" } } } }, { "type": "null" } ] }, "typical": { "type": "object", "required": [ "count", "each", "size" ] }, "chain": { "type": "array", "items": { "type": "string" } }, "forwards": { "anyOf": [ { "type": "object", "required": [ "inputs", "asks", "left" ] }, { "type": "null" } ] }, "assumptions": { "type": "array", "items": { "type": "object", "required": [ "id", "label", "value" ] } }, "settings": { "type": "array" }, "links": { "type": "object", "required": [ "page", "openInSite", "calculator" ] }, "note": { "type": "string" }, "citation": { "type": "object", "required": [ "author", "title", "url", "formats", "accessDate" ], "properties": { "author": { "type": "string" }, "title": { "type": "string" }, "version": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sourcesChecked": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "url": { "type": "string" }, "accessDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "formats": { "type": "object", "required": [ "plain", "apa", "harvard", "bibtex" ], "properties": { "plain": { "type": "string" }, "apa": { "type": "string" }, "harvard": { "type": "string" }, "bibtex": { "type": "string" } } } } }, "licence": { "type": "object", "required": [ "name", "url", "attribution" ], "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "attribution": { "type": "string" } } }, "notice": { "type": "string" } } }, { "type": "object", "required": [ "detail", "tool", "title", "lines", "notes", "citation", "url", "open", "more" ], "properties": { "detail": { "const": "summary" }, "tool": { "type": "string" }, "title": { "type": "string" }, "lines": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "string" } }, "description": "The result lines, as the report's table gives them." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "What a professional must decide, when to call one, a false-friend warning, that adoption is local: kept in every summary." }, "citation": { "type": "string", "description": "The one citation line, built from the answer's own data." }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "open": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "more": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } ] } } } }, "400": { "description": "The request was refused; every problem is listed.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "title", "status", "problems" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "problems": { "type": "array", "items": { "type": "object", "required": [ "input", "problem" ], "properties": { "input": { "type": "string" }, "problem": { "type": "string" }, "accepted": { "type": "array", "items": { "type": "string" } } } } }, "didYouMean": { "type": "array", "items": { "type": "string" } } } } } } }, "404": { "description": "The request was refused; every problem is listed.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "title", "status", "problems" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "problems": { "type": "array", "items": { "type": "object", "required": [ "input", "problem" ], "properties": { "input": { "type": "string" }, "problem": { "type": "string" }, "accepted": { "type": "array", "items": { "type": "string" } } } } }, "didYouMean": { "type": "array", "items": { "type": "string" } } } } } } } }, "tags": [ "Solve backwards" ], "parameters": [ { "name": "detail", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "full", "summary" ], "default": "full", "description": "full (the default): the whole answer. summary: the result lines, the citation line and the page only — fewer tokens to read." }, "description": "summary: the result lines, the citation and the page only (fewer tokens); full, the default: the whole answer. A POST body may carry detail instead." }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json", "md" ] }, "description": "md: the engine's Markdown report as text/markdown (or send Accept: text/markdown); json, the default." } ] } }, "/documents": { "get": { "operationId": "marketDocuments", "summary": "The document family that governs a subject in a market, and who publishes it", "description": "Never an edition or a date: adoption is local, and the answer names who decides.", "parameters": [ { "name": "market", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 60, "description": "US, CA, UK, AU or INTL — or a country's name (\"England\", \"Canada\"); a country the site has no market for answers as INTL." } }, { "name": "subject", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200, "description": "The work, in words: \"kitchen wiring\", \"stair handrails\", \"gas boiler flue\"." } }, { "name": "calculator", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,119}$", "description": "Or a calculator's slug: the subjects its own sources name." } }, { "name": "detail", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "full", "summary" ], "default": "full", "description": "full (the default): the whole answer. summary: the result lines, the citation line and the page only — fewer tokens to read." }, "description": "summary: the result lines, the citation and the page only (fewer tokens); full, the default: the whole answer. A POST body may carry detail instead." }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json", "md" ] }, "description": "md: the engine's Markdown report as text/markdown (or send Accept: text/markdown); json, the default." } ], "responses": { "200": { "description": "The documents by subject, the adoption sentence and who decides.", "content": { "application/json": { "schema": { "type": "object", "anyOf": [ { "type": "object", "required": [ "engine", "market", "place", "asked", "matchedFrom", "subjects", "adoption", "decidedBy", "notice", "links", "citation", "licence" ], "properties": { "engine": { "type": "object" }, "market": { "enum": [ "US", "CA", "UK", "AU", "INTL" ] }, "place": { "type": "string" }, "marketNote": { "type": "string" }, "asked": { "type": "object" }, "calculator": { "type": "object" }, "matchedFrom": { "enum": [ "subject", "calculator-sources", "calculator-title" ] }, "subjects": { "type": "array", "items": { "type": "object", "required": [ "topic", "subject", "documents" ], "properties": { "topic": { "type": "string" }, "subject": { "type": "string" }, "documents": { "type": "array", "items": { "type": "object", "required": [ "document", "publishers", "standardsPages" ], "properties": { "document": { "type": "string", "description": "The document family, as the site names it — not an edition." }, "publishers": { "type": "array", "items": { "type": "string" } }, "standardsPages": { "type": "array", "items": { "type": "string" } } } } }, "none": { "type": "string" }, "byMarket": { "type": "array", "items": { "type": "object", "required": [ "market", "place", "documents" ], "properties": { "market": { "type": "string" }, "place": { "type": "string" }, "documents": { "type": "array", "items": { "type": "object", "required": [ "document", "publishers", "standardsPages" ], "properties": { "document": { "type": "string", "description": "The document family, as the site names it — not an edition." }, "publishers": { "type": "array", "items": { "type": "string" } }, "standardsPages": { "type": "array", "items": { "type": "string" } } } } } } } } } } }, "none": { "type": "string" }, "adoption": { "type": "string", "description": "The market's fixed sentence: adoption, edition and amendments are decided locally." }, "decidedBy": { "type": "string" }, "notice": { "type": "string" }, "links": { "type": "object", "required": [ "standards" ] }, "citation": { "type": "object", "required": [ "author", "title", "url", "formats", "accessDate" ], "properties": { "author": { "type": "string" }, "title": { "type": "string" }, "version": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sourcesChecked": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "url": { "type": "string" }, "accessDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "formats": { "type": "object", "required": [ "plain", "apa", "harvard", "bibtex" ], "properties": { "plain": { "type": "string" }, "apa": { "type": "string" }, "harvard": { "type": "string" }, "bibtex": { "type": "string" } } } } }, "licence": { "type": "object", "required": [ "name", "url", "attribution" ], "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "attribution": { "type": "string" } } } } }, { "type": "object", "required": [ "detail", "tool", "title", "lines", "notes", "citation", "url", "open", "more" ], "properties": { "detail": { "const": "summary" }, "tool": { "type": "string" }, "title": { "type": "string" }, "lines": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "string" } }, "description": "The result lines, as the report's table gives them." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "What a professional must decide, when to call one, a false-friend warning, that adoption is local: kept in every summary." }, "citation": { "type": "string", "description": "The one citation line, built from the answer's own data." }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "open": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "more": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } ] } } } }, "400": { "description": "The request was refused; every problem is listed.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "title", "status", "problems" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "problems": { "type": "array", "items": { "type": "object", "required": [ "input", "problem" ], "properties": { "input": { "type": "string" }, "problem": { "type": "string" }, "accepted": { "type": "array", "items": { "type": "string" } } } } }, "didYouMean": { "type": "array", "items": { "type": "string" } } } } } } }, "404": { "description": "The request was refused; every problem is listed.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "title", "status", "problems" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "problems": { "type": "array", "items": { "type": "object", "required": [ "input", "problem" ], "properties": { "input": { "type": "string" }, "problem": { "type": "string" }, "accepted": { "type": "array", "items": { "type": "string" } } } } }, "didYouMean": { "type": "array", "items": { "type": "string" } } } } } } } }, "tags": [ "Diagnoses and documents" ] } }, "/term": { "get": { "operationId": "translateTerm", "summary": "A trade word in each market's usage, with the false-friend warning", "parameters": [ { "name": "term", "in": "query", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 80, "description": "A trade word or phrase as one market says it, a brand name said for the product, or a misspelling: \"plasterboard\", \"gyprock\", \"casing\", \"skirting\", \"eavestrough\", \"a yard of concrete\"." } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "US", "CA", "UK", "AU" ], "description": "The market whose word it is, where known." } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "US", "CA", "UK", "AU" ], "description": "The market to say it in." } }, { "name": "detail", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "full", "summary" ], "default": "full", "description": "full (the default): the whole answer. summary: the result lines, the citation line and the page only — fewer tokens to read." }, "description": "summary: the result lines, the citation and the page only (fewer tokens); full, the default: the whole answer. A POST body may carry detail instead." }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json", "md" ] }, "description": "md: the engine's Markdown report as text/markdown (or send Accept: text/markdown); json, the default." } ], "responses": { "200": { "description": "The concept, each market's word and any false friend, the unit traps the word raises and the market's document family.", "content": { "application/json": { "schema": { "type": "object", "anyOf": [ { "type": "object", "required": [ "engine", "term", "matchedBy", "concepts", "links", "citation", "licence" ], "properties": { "engine": { "type": "object" }, "term": { "type": "string" }, "from": { "type": "string" }, "to": { "type": "string" }, "matchedBy": { "enum": [ "term", "variant", "within", "fuzzy", "search" ], "description": "How the word was matched: a glossary name exactly; the same name spaced, hyphenated or plural; a phrase holding a name; a misspelling of one name; or the site's ranking of the definitions." }, "matched": { "type": "array", "items": { "type": "object", "required": [ "concept", "name", "market", "as" ], "properties": { "concept": { "type": "string" }, "name": { "type": "string", "description": "The glossary's own name that matched." }, "market": { "type": "string" }, "as": { "enum": [ "term", "also called" ] } } } }, "readAs": { "type": "string" }, "unitSystems": { "type": "array", "items": { "type": "object", "required": [ "market", "system" ], "properties": { "market": { "type": "string" }, "system": { "enum": [ "metric", "imperial" ] } } }, "description": "Each named market's primary measurement system, as the site's market registry holds it." }, "unitTraps": { "type": "array", "items": { "type": "object", "required": [ "id", "title", "says", "markets", "conversions", "page" ], "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "says": { "type": "string" }, "markets": { "type": "array", "items": { "type": "string" } }, "conversions": { "type": "array", "items": { "type": "object", "required": [ "value", "from", "to", "result", "by" ], "properties": { "definition": { "type": "string", "description": "The defining relation, where one side is not a unit of the conversion table." }, "value": { "type": "number" }, "from": { "type": "string" }, "to": { "type": "string" }, "result": { "type": "number" }, "factor": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "by": { "type": "string", "description": "The engine's unit conversion that gave the result." } } } }, "page": { "type": "string" }, "bags": { "type": "array", "items": { "type": "object", "required": [ "calculator", "input", "metric", "imperial" ], "properties": { "calculator": { "type": "object" }, "input": { "type": "string" }, "metric": { "type": "array", "items": { "type": "string" } }, "imperial": { "type": "array", "items": { "type": "string" } } } } } } } }, "documents": { "type": "object", "required": [ "market", "place", "subjects", "adoption", "decidedBy", "page" ], "description": "The family of documents that governs the concept's subject in the named market. No edition, and no claim that it matches another market's document.", "properties": { "market": { "type": "string" }, "place": { "type": "string" }, "for": { "type": "string", "description": "The calculator whose sources, or the document the glossary names for the concept, the subject was read from." }, "subjects": { "type": "array", "items": { "type": "object", "required": [ "subject", "documents" ], "properties": { "subject": { "type": "string" }, "documents": { "type": "array", "items": { "type": "string" } } } } }, "adoption": { "type": "string" }, "decidedBy": { "type": "string" }, "page": { "type": "string" } } }, "concepts": { "type": "array", "items": { "type": "object", "required": [ "slug", "concept", "url", "definition", "matchedAs", "names", "warnings", "calculators", "confusions" ], "properties": { "slug": { "type": "string" }, "concept": { "type": "string" }, "url": { "type": "string" }, "definition": { "type": "string" }, "matchedAs": { "type": "array", "items": { "type": "object", "required": [ "market", "as" ] } }, "names": { "type": "array", "items": { "type": "object", "required": [ "market", "term", "alsoCalled", "exactness", "note" ], "properties": { "market": { "type": "string" }, "term": { "type": "string" }, "alsoCalled": { "type": "array", "items": { "type": "string" } }, "exactness": { "enum": [ "identical", "close", "false-friend", "absent" ] }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } }, "translation": { "type": "object" }, "warnings": { "type": "array", "items": { "type": "string" } }, "calculators": { "type": "array" }, "confusions": { "type": "array", "items": { "type": "string" } } } } }, "none": { "type": "string" }, "note": { "type": "string" }, "links": { "type": "object", "required": [ "glossary" ] }, "citation": { "type": "object", "required": [ "author", "title", "url", "formats", "accessDate" ], "properties": { "author": { "type": "string" }, "title": { "type": "string" }, "version": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sourcesChecked": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "url": { "type": "string" }, "accessDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "formats": { "type": "object", "required": [ "plain", "apa", "harvard", "bibtex" ], "properties": { "plain": { "type": "string" }, "apa": { "type": "string" }, "harvard": { "type": "string" }, "bibtex": { "type": "string" } } } } }, "licence": { "type": "object", "required": [ "name", "url", "attribution" ], "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "attribution": { "type": "string" } } } } }, { "type": "object", "required": [ "detail", "tool", "title", "lines", "notes", "citation", "url", "open", "more" ], "properties": { "detail": { "const": "summary" }, "tool": { "type": "string" }, "title": { "type": "string" }, "lines": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "string" } }, "description": "The result lines, as the report's table gives them." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "What a professional must decide, when to call one, a false-friend warning, that adoption is local: kept in every summary." }, "citation": { "type": "string", "description": "The one citation line, built from the answer's own data." }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "open": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "more": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } ] } } } }, "400": { "description": "The request was refused; every problem is listed.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "title", "status", "problems" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "problems": { "type": "array", "items": { "type": "object", "required": [ "input", "problem" ], "properties": { "input": { "type": "string" }, "problem": { "type": "string" }, "accepted": { "type": "array", "items": { "type": "string" } } } } }, "didYouMean": { "type": "array", "items": { "type": "string" } } } } } } } }, "tags": [ "Diagnoses and documents" ] } }, "/benchmark": { "get": { "operationId": "getBenchmark", "summary": "A page of the Construction Quantities Benchmark, or one calculator's items", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "description": "Which page of the benchmark, from 1: each page holds the items of a few calculators, in slug order. 1 when left out." } }, { "name": "calculator", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,119}$", "description": "One calculator's items only, by its slug, such as concrete-calculator." } }, { "name": "detail", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "full", "summary" ], "default": "full", "description": "full (the default): the whole answer. summary: the result lines, the citation line and the page only — fewer tokens to read." }, "description": "summary: the result lines, the citation and the page only (fewer tokens); full, the default: the whole answer. A POST body may carry detail instead." }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json", "md" ] }, "description": "md: the engine's Markdown report as text/markdown (or send Accept: text/markdown); json, the default." } ], "responses": { "200": { "description": "The dataset's edition, download and citation, and the page's items.", "content": { "application/json": { "schema": { "type": "object", "anyOf": [ { "type": "object", "required": [ "engine", "dataset", "items", "excluded" ], "properties": { "engine": { "type": "object" }, "dataset": { "type": "object", "required": [ "name", "id", "version", "edition", "items", "pages", "download", "method", "scoring", "licence", "status", "citation" ], "properties": { "name": { "type": "string" }, "id": { "type": "string" }, "version": { "type": "string", "description": "The method and fields version." }, "edition": { "type": "string", "description": "The first twelve hex digits of the JSONL file's SHA-256: which content a citation means." }, "currentTo": { "type": "string" }, "items": { "type": "number" }, "calculators": { "type": "number" }, "vectors": { "type": "number" }, "excluded": { "type": "object", "description": "Vectors left out, by reason: money (the calculator takes or returns a price), partial-vector (its figure needs an input left undefined), refused, no-figure.", "properties": { "money": { "type": "number" }, "partial-vector": { "type": "number" }, "refused": { "type": "number" }, "no-figure": { "type": "number" } } }, "pages": { "type": "number" }, "pageSize": { "type": "string" }, "download": { "type": "object", "required": [ "jsonl", "manifest" ], "properties": { "jsonl": { "type": "string" }, "manifest": { "type": "string" }, "bytes": { "type": "number" }, "sha256": { "type": "string" } } }, "method": { "type": "string" }, "scoring": { "type": "string" }, "licence": { "type": "object", "required": [ "name", "url", "attribution" ], "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "attribution": { "type": "string" } } }, "status": { "type": "string" }, "citation": { "type": "object", "required": [ "author", "title", "url", "formats", "accessDate" ], "properties": { "author": { "type": "string" }, "title": { "type": "string" }, "version": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sourcesChecked": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "url": { "type": "string" }, "accessDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "formats": { "type": "object", "required": [ "plain", "apa", "harvard", "bibtex" ], "properties": { "plain": { "type": "string" }, "apa": { "type": "string" }, "harvard": { "type": "string" }, "bibtex": { "type": "string" } } } } } } }, "page": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "nextPage": { "type": "integer" }, "calculator": { "type": "string" }, "calculators": { "type": "array", "items": { "type": "string" } }, "items": { "type": "array", "items": { "type": "object", "required": [ "id", "dataset", "calculator", "case", "task", "inputs", "prompt", "answer", "steps", "allowance", "confidence" ], "properties": { "id": { "type": "string", "description": "The calculator's slug and the vector's position among its test cases, such as concrete-calculator/1." }, "dataset": { "type": "string" }, "calculator": { "type": "object", "required": [ "slug", "title", "category", "version", "url" ], "properties": { "slug": { "type": "string" }, "title": { "type": "string" }, "category": { "type": "string" }, "version": { "type": "string" }, "url": { "type": "string" } } }, "case": { "type": "string", "description": "The test vector's own name." }, "task": { "type": "string", "description": "What is worked out: the calculator's result label." }, "inputs": { "type": "array", "items": { "type": "object", "required": [ "id", "label", "value", "fromVector", "metric", "imperial" ], "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "value": { "anyOf": [ { "type": "number" }, { "type": "string" } ], "description": "In the base unit for a dimension (metres, m², litres, kg), the option value for a select." }, "baseUnit": { "type": "string" }, "fromVector": { "type": "boolean", "description": "False where the vector leaves the input out and it takes the value the page opens on." }, "metric": { "type": "object", "required": [ "value", "unit" ], "properties": { "value": { "anyOf": [ { "type": "number" }, { "type": "string" } ] }, "unit": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, "imperial": { "type": "object", "required": [ "value", "unit" ], "properties": { "value": { "anyOf": [ { "type": "number" }, { "type": "string" } ] }, "unit": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } }, "prompt": { "type": "object", "required": [ "metric", "imperial" ], "properties": { "metric": { "type": "string" }, "imperial": { "type": "string" } } }, "answer": { "type": "object", "required": [ "canonical", "metric", "imperial" ], "properties": { "canonical": { "type": "object", "required": [ "value", "unit", "toleranceDecimalPlaces" ], "description": "What the test vector pins, in the calculator's own unit: met when |x − value| < 0.5 × 10^−toleranceDecimalPlaces.", "properties": { "value": { "type": "number" }, "unit": { "type": "string" }, "toleranceDecimalPlaces": { "type": "number" } } }, "metric": { "type": "object", "required": [ "value", "unit", "printed", "tolerance" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string" }, "printed": { "type": "string", "description": "The figure as the page prints it." }, "tolerance": { "type": "number", "description": "An answer in this unit is right when it is within this of the value." } } }, "imperial": { "type": "object", "required": [ "value", "unit", "printed", "tolerance" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string" }, "printed": { "type": "string", "description": "The figure as the page prints it." }, "tolerance": { "type": "number", "description": "An answer in this unit is right when it is within this of the value." } } } } }, "steps": { "type": "array", "items": { "type": "object", "required": [ "label", "value", "unit" ], "properties": { "label": { "type": "string" }, "value": { "type": "number" }, "unit": { "type": "string" } } } }, "allowance": { "anyOf": [ { "type": "object", "required": [ "label", "percent" ], "properties": { "label": { "type": "string" }, "percent": { "type": "number" } } }, { "type": "null" } ] }, "confidence": { "type": "string" } } } }, "excluded": { "type": "array", "items": { "type": "object", "required": [ "id", "reason" ], "properties": { "id": { "type": "string" }, "reason": { "enum": [ "money", "partial-vector", "refused", "no-figure" ] } } } }, "none": { "type": "string" } } }, { "type": "object", "required": [ "detail", "tool", "title", "lines", "notes", "citation", "url", "open", "more" ], "properties": { "detail": { "const": "summary" }, "tool": { "type": "string" }, "title": { "type": "string" }, "lines": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "string" } }, "description": "The result lines, as the report's table gives them." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "What a professional must decide, when to call one, a false-friend warning, that adoption is local: kept in every summary." }, "citation": { "type": "string", "description": "The one citation line, built from the answer's own data." }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "open": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "more": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } ] } } } }, "400": { "description": "The request was refused; every problem is listed.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "title", "status", "problems" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "problems": { "type": "array", "items": { "type": "object", "required": [ "input", "problem" ], "properties": { "input": { "type": "string" }, "problem": { "type": "string" }, "accepted": { "type": "array", "items": { "type": "string" } } } } }, "didYouMean": { "type": "array", "items": { "type": "string" } } } } } } }, "404": { "description": "The request was refused; every problem is listed.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "title", "status", "problems" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "problems": { "type": "array", "items": { "type": "object", "required": [ "input", "problem" ], "properties": { "input": { "type": "string" }, "problem": { "type": "string" }, "accepted": { "type": "array", "items": { "type": "string" } } } } }, "didYouMean": { "type": "array", "items": { "type": "string" } } } } } } } }, "tags": [ "Benchmark" ] } }, "/supplier-quote-request": { "post": { "operationId": "createSupplierQuoteRequest", "summary": "A request for quote to merchants from a bill of materials, with no price", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "items" ], "properties": { "items": { "type": "array", "minItems": 1, "maxItems": 400, "items": { "type": "object", "description": "A bill line: as a takeoff, house, plan or calculation answer gives it (label or name, quantity, unit, and order where it says what to buy), or the reader's own.", "properties": { "description": { "type": "string", "maxLength": 160 }, "label": { "type": "string", "maxLength": 200 }, "name": { "type": "string", "maxLength": 200 }, "quantity": { "type": "number", "exclusiveMinimum": 0 }, "unit": { "type": "string", "maxLength": 24 }, "order": { "type": "object", "properties": { "quantity": { "type": "number" }, "unit": { "type": "string" } } }, "notes": { "type": "string", "maxLength": 200 }, "packSize": { "type": "number", "exclusiveMinimum": 0 }, "packs": { "type": "number", "minimum": 0 }, "packName": { "type": "string", "maxLength": 120 } } } }, "project": { "type": "string", "maxLength": 120, "description": "The project's name, as the merchants will see it." }, "currency": { "type": "string", "maxLength": 8, "description": "The currency prices are asked in; left out, the market's." }, "market": { "type": "string", "enum": [ "US", "CA", "UK", "AU", "INTL" ], "description": "Optional. A market whose own opening choice some inputs take (a UK reader's code, an IEC motor), and whose currency symbol prints the caller's own money figures." }, "note": { "type": "string", "maxLength": 600, "description": "A note to the merchants: delivery address area, dates, access." } } }, "example": { "project": "Garage slab", "market": "UK", "items": [ { "description": "Ready-mix concrete, C25/30", "quantity": 2.64, "unit": "m³", "notes": "Pump access from the drive" }, { "description": "Rebar, 12 mm, 12 m lengths", "quantity": 11, "unit": "sticks" }, { "description": "Formwork boards, 2.4 m", "quantity": 10, "unit": "boards" } ] }, "examples": { "create_supplier_quote_request": { "summary": "Turn my slab's bill into a request for quote I can send to two merchants.", "value": { "project": "Garage slab", "market": "UK", "items": [ { "description": "Ready-mix concrete, C25/30", "quantity": 2.64, "unit": "m³", "notes": "Pump access from the drive" }, { "description": "Rebar, 12 mm, 12 m lengths", "quantity": 11, "unit": "sticks" }, { "description": "Formwork boards, 2.4 m", "quantity": 10, "unit": "boards" } ] } } } } } }, "responses": { "200": { "description": "The request as Markdown, CSV, the site's link and a My Project file.", "content": { "application/json": { "schema": { "type": "object", "anyOf": [ { "type": "object", "required": [ "engine", "project", "currency", "rows", "markdown", "csv", "link", "howToSend", "requestFile", "file", "howToImport", "links", "licence", "notice" ], "properties": { "engine": { "type": "object" }, "project": { "type": "string" }, "currency": { "type": "string" }, "rows": { "type": "array", "items": { "type": "object", "required": [ "label", "quantity", "unit" ], "properties": { "label": { "type": "string" }, "quantity": { "type": "number" }, "unit": { "type": "string" }, "packSize": { "type": "number" }, "packs": { "type": "number" }, "packName": { "type": "string" } } } }, "dropped": { "type": "integer" }, "markdown": { "type": "string", "description": "The request, to paste into a message." }, "csv": { "type": "object", "required": [ "filename", "mediaType", "content" ] }, "link": { "type": "string", "description": "The site's request link: the merchant opens it, prices it in their own browser and sends a reply link back." }, "howToSend": { "type": "string" }, "requestFile": { "type": "object", "required": [ "filename", "mediaType", "content" ], "properties": { "schema": { "type": "string", "description": "The open JSON Schema the request file follows, for a supplier's own software." } } }, "file": { "type": "object", "required": [ "filename", "mediaType", "content" ] }, "howToImport": { "type": "string" }, "links": { "type": "object", "required": [ "rfq", "project" ] }, "licence": { "type": "object", "required": [ "name", "url", "attribution" ], "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "attribution": { "type": "string" } } }, "notice": { "type": "string" } } }, { "type": "object", "required": [ "detail", "tool", "title", "lines", "notes", "citation", "url", "open", "more" ], "properties": { "detail": { "const": "summary" }, "tool": { "type": "string" }, "title": { "type": "string" }, "lines": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "string" } }, "description": "The result lines, as the report's table gives them." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "What a professional must decide, when to call one, a false-friend warning, that adoption is local: kept in every summary." }, "citation": { "type": "string", "description": "The one citation line, built from the answer's own data." }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "open": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "more": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } ] } } } }, "400": { "description": "The request was refused; every problem is listed.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "title", "status", "problems" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "problems": { "type": "array", "items": { "type": "object", "required": [ "input", "problem" ], "properties": { "input": { "type": "string" }, "problem": { "type": "string" }, "accepted": { "type": "array", "items": { "type": "string" } } } } }, "didYouMean": { "type": "array", "items": { "type": "string" } } } } } } }, "413": { "description": "The request was refused; every problem is listed.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "title", "status", "problems" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "problems": { "type": "array", "items": { "type": "object", "required": [ "input", "problem" ], "properties": { "input": { "type": "string" }, "problem": { "type": "string" }, "accepted": { "type": "array", "items": { "type": "string" } } } } }, "didYouMean": { "type": "array", "items": { "type": "string" } } } } } } } }, "tags": [ "Quotes" ], "parameters": [ { "name": "detail", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "full", "summary" ], "default": "full", "description": "full (the default): the whole answer. summary: the result lines, the citation line and the page only — fewer tokens to read." }, "description": "summary: the result lines, the citation and the page only (fewer tokens); full, the default: the whole answer. A POST body may carry detail instead." }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json", "md" ] }, "description": "md: the engine's Markdown report as text/markdown (or send Accept: text/markdown); json, the default." } ] } }, "/sketch": { "post": { "operationId": "measureSketch", "summary": "Areas, perimeters and lengths from points read off a plan, sketch or photo, scaled by one known reference", "description": "Points in the image's pixels and one reference; no image is sent. Returns the figures in both systems with an uncertainty band, closure and crossing checks, and a link that opens the scaled shapes on the canvas.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "shapes", "reference" ], "properties": { "shapes": { "type": "array", "minItems": 1, "maxItems": 40, "description": "The outlines and lines read off the image, in its pixels.", "items": { "type": "object", "additionalProperties": false, "required": [ "kind", "points" ], "properties": { "kind": { "enum": [ "area", "length" ], "description": "area: a closed outline (a floor, a slab, a roof plane on plan); length: a line or a path (a fence, a footing, a run)." }, "name": { "type": "string", "maxLength": 60 }, "points": { "type": "array", "minItems": 2, "maxItems": 501, "items": { "type": "object", "additionalProperties": false, "required": [ "x", "y" ], "properties": { "x": { "type": "number" }, "y": { "type": "number" } }, "description": "A point in the image's own pixels: x to the right, y down from the top-left corner." }, "description": "In order round the outline or along the path." }, "closed": { "type": "boolean", "description": "A length only: the path closes back to its first point." }, "as": { "enum": [ "measure", "room", "slab", "floor", "patio", "deck", "driveway", "landscaping", "roof", "fence", "footing", "retaining-wall" ], "description": "What it is drawn as on the canvas: a kept measure (the default), or a room (walls round it), slab, floor, patio, deck, driveway, landscaping or roof outline; a fence, footing or retaining wall path. A component is listed with its materials." }, "calculator": { "type": "object", "additionalProperties": false, "required": [ "slug", "input" ], "properties": { "slug": { "type": "string", "maxLength": 120 }, "input": { "type": "string", "maxLength": 80, "description": "The id of the calculator's input that takes the figure." }, "figure": { "enum": [ "area", "perimeter", "length" ] }, "inputs": { "type": "object", "maxProperties": 100, "description": "The calculator's input values, by input id (an unknown id is refused with the accepted ids). A length, area, volume or other measured input takes \"12 ft\", \"3.5 m\", \"8' 3 1/2\\\"\" or {\"value\": 12, \"unit\": \"ft\"}; a count or percentage takes a number; a select takes one of its option values. Inputs left out take the value the calculator's page opens on.", "additionalProperties": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] } } }, "description": "A calculator the figure goes into, run on the figure and on both ends of its band (at most 10 per request)." } } } }, "reference": { "type": "object", "additionalProperties": false, "description": "ONE known size in the same image: a figured dimension, or an object of known size by its four corners.", "properties": { "dimension": { "type": "object", "additionalProperties": false, "required": [ "from", "to", "length" ], "properties": { "from": { "type": "object", "additionalProperties": false, "required": [ "x", "y" ], "properties": { "x": { "type": "number" }, "y": { "type": "number" } }, "description": "A point in the image's own pixels: x to the right, y down from the top-left corner." }, "to": { "type": "object", "additionalProperties": false, "required": [ "x", "y" ], "properties": { "x": { "type": "number" }, "y": { "type": "number" } }, "description": "A point in the image's own pixels: x to the right, y down from the top-left corner." }, "length": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] }, "tolerance": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ], "description": "How far the figure itself may be off (a dimension rounded to the nearest 10 mm: 5 mm)." } } }, "object": { "enum": [ "card", "a4", "letter", "custom" ], "description": "card: ISO/IEC 7810 ID-1 (85.60 × 53.98 mm); a4: 210 × 297 mm; letter: 8.5 × 11 in; custom: width and height given." }, "width": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] }, "height": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] }, "corners": { "type": "array", "minItems": 4, "maxItems": 4, "items": { "type": "object", "additionalProperties": false, "required": [ "x", "y" ], "properties": { "x": { "type": "number" }, "y": { "type": "number" } }, "description": "A point in the image's own pixels: x to the right, y down from the top-left corner." }, "description": "Top-left, top-right, bottom-right, bottom-left; the width runs from the first to the second." } } }, "pixelError": { "type": "number", "minimum": 0.1, "maximum": 50, "default": 2, "description": "How far any point may be off, in pixels: it sets the band." }, "system": { "type": "string", "enum": [ "metric", "imperial" ], "default": "metric", "description": "The unit system inputs left out open in, and the one the page link opens in. The answer comes in both." }, "inputUnits": { "type": "string", "enum": [ "base" ], "description": "Send \"base\" to pass bare numbers on dimensioned inputs in base units (m, m², L, kg …), as the published test vectors are written. Without it a length, area or volume must carry its unit." } } }, "example": { "reference": { "dimension": { "from": { "x": 100, "y": 80 }, "to": { "x": 700, "y": 80 }, "length": "6 m" } }, "shapes": [ { "name": "Living room", "kind": "area", "points": [ { "x": 100, "y": 100 }, { "x": 700, "y": 100 }, { "x": 700, "y": 500 }, { "x": 400, "y": 500 }, { "x": 400, "y": 350 }, { "x": 100, "y": 350 } ], "calculator": { "slug": "self-leveling-underlayment-calculator", "input": "floorArea" } }, { "name": "Garden fence", "kind": "length", "as": "fence", "points": [ { "x": 100, "y": 600 }, { "x": 700, "y": 600 }, { "x": 700, "y": 800 } ] } ], "system": "metric" }, "examples": { "measure_sketch": { "summary": "From the plan in my photo: the living room's floor area and the fence along the garden, scaled from the 6 m dimension.", "value": { "reference": { "dimension": { "from": { "x": 100, "y": 80 }, "to": { "x": 700, "y": 80 }, "length": "6 m" } }, "shapes": [ { "name": "Living room", "kind": "area", "points": [ { "x": 100, "y": 100 }, { "x": 700, "y": 100 }, { "x": 700, "y": 500 }, { "x": 400, "y": 500 }, { "x": 400, "y": 350 }, { "x": 100, "y": 350 } ], "calculator": { "slug": "self-leveling-underlayment-calculator", "input": "floorArea" } }, { "name": "Garden fence", "kind": "length", "as": "fence", "points": [ { "x": 100, "y": 600 }, { "x": 700, "y": 600 }, { "x": 700, "y": 800 } ] } ], "system": "metric" } } } } } }, "responses": { "200": { "description": "The scale, each shape's figures and band, and the canvas link.", "content": { "application/json": { "schema": { "type": "object", "anyOf": [ { "type": "object", "required": [ "engine", "system", "scale", "shapes", "document", "links", "drawingLink", "accuracy", "privacy", "citation", "licence", "notice" ], "properties": { "engine": { "type": "object" }, "system": { "enum": [ "metric", "imperial" ] }, "scale": { "type": "object", "required": [ "pixelsPerMm", "perPixel", "reference", "pixelError", "scaleUncertaintyPercent" ] }, "shapes": { "type": "array", "items": { "type": "object", "required": [ "name", "kind", "as", "points", "closed", "uncertaintyPercent" ], "properties": { "name": { "type": "string" }, "kind": { "enum": [ "area", "length" ] }, "as": { "type": "string" }, "points": { "type": "integer" }, "closed": { "type": "boolean" }, "closure": { "type": "string" }, "area": { "type": "object", "required": [ "m2", "ft2", "low", "high", "text" ], "properties": { "m2": { "type": "number" }, "ft2": { "type": "number" }, "low": { "type": "object" }, "high": { "type": "object" }, "text": { "type": "string" } } }, "perimeter": { "type": "object", "required": [ "m", "ft", "low", "high", "text" ], "properties": { "m": { "type": "number" }, "ft": { "type": "number" }, "low": { "type": "object" }, "high": { "type": "object" }, "text": { "type": "string" } } }, "length": { "type": "object", "required": [ "m", "ft", "low", "high", "text" ], "properties": { "m": { "type": "number" }, "ft": { "type": "number" }, "low": { "type": "object" }, "high": { "type": "object" }, "text": { "type": "string" } } }, "uncertaintyPercent": { "type": "object" }, "calculator": { "type": "object" } } } }, "rows": { "type": "array", "items": { "type": "object", "required": [ "key", "label", "quantity", "unit", "calculator" ] } }, "notMeasured": { "type": "array", "items": { "type": "string" }, "description": "What the canvas could not measure among the components drawn, and why (a patio, deck or driveway outline that is not square-cornered is drawn, not measured)." }, "document": { "type": "object", "required": [ "schema", "levels", "entities" ] }, "links": { "type": "object", "required": [ "canvas", "drawing", "page" ], "properties": { "canvas": { "type": "string" }, "drawing": { "anyOf": [ { "type": "string", "description": "Opens the scaled shapes on the canvas; the drawing rides in the fragment, so nothing is uploaded." }, { "type": "null" } ] }, "page": { "type": "string", "description": "The site's Photo Takeoff page, whose geometry this is." } } }, "drawingLink": { "type": "string" }, "accuracy": { "type": "array", "items": { "type": "string" } }, "privacy": { "type": "string" }, "citation": { "type": "object", "required": [ "author", "title", "url", "formats", "accessDate" ], "properties": { "author": { "type": "string" }, "title": { "type": "string" }, "version": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sourcesChecked": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "url": { "type": "string" }, "accessDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "formats": { "type": "object", "required": [ "plain", "apa", "harvard", "bibtex" ], "properties": { "plain": { "type": "string" }, "apa": { "type": "string" }, "harvard": { "type": "string" }, "bibtex": { "type": "string" } } } } }, "licence": { "type": "object", "required": [ "name", "url", "attribution" ], "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "attribution": { "type": "string" } } }, "notice": { "type": "string" } } }, { "type": "object", "required": [ "detail", "tool", "title", "lines", "notes", "citation", "url", "open", "more" ], "properties": { "detail": { "const": "summary" }, "tool": { "type": "string" }, "title": { "type": "string" }, "lines": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "string" } }, "description": "The result lines, as the report's table gives them." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "What a professional must decide, when to call one, a false-friend warning, that adoption is local: kept in every summary." }, "citation": { "type": "string", "description": "The one citation line, built from the answer's own data." }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "open": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "more": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } ] } } } }, "400": { "description": "The request was refused; every problem is listed.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "title", "status", "problems" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "problems": { "type": "array", "items": { "type": "object", "required": [ "input", "problem" ], "properties": { "input": { "type": "string" }, "problem": { "type": "string" }, "accepted": { "type": "array", "items": { "type": "string" } } } } }, "didYouMean": { "type": "array", "items": { "type": "string" } } } } } } }, "404": { "description": "The request was refused; every problem is listed.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "title", "status", "problems" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "problems": { "type": "array", "items": { "type": "object", "required": [ "input", "problem" ], "properties": { "input": { "type": "string" }, "problem": { "type": "string" }, "accepted": { "type": "array", "items": { "type": "string" } } } } }, "didYouMean": { "type": "array", "items": { "type": "string" } } } } } } }, "413": { "description": "The request was refused; every problem is listed.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "title", "status", "problems" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "problems": { "type": "array", "items": { "type": "object", "required": [ "input", "problem" ], "properties": { "input": { "type": "string" }, "problem": { "type": "string" }, "accepted": { "type": "array", "items": { "type": "string" } } } } }, "didYouMean": { "type": "array", "items": { "type": "string" } } } } } } } }, "tags": [ "House and canvas" ], "parameters": [ { "name": "detail", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "full", "summary" ], "default": "full", "description": "full (the default): the whole answer. summary: the result lines, the citation line and the page only — fewer tokens to read." }, "description": "summary: the result lines, the citation and the page only (fewer tokens); full, the default: the whole answer. A POST body may carry detail instead." }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json", "md" ] }, "description": "md: the engine's Markdown report as text/markdown (or send Accept: text/markdown); json, the default." } ] } }, "/drawing-export": { "post": { "operationId": "exportDrawing", "summary": "A Construction Canvas drawing as DXF (CQ-* layers) and SVG plan files", "description": "The drawing as create_drawing takes it; one file per drawn level, by the canvas's own plan painters. A file too large to return inline is rebuilt from the drawing's link.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "house": { "type": "object", "additionalProperties": false, "properties": { "example": { "type": "string", "maxLength": 120, "description": "Start from one of the site's example houses (its slug) in place of the estimator's opening house." }, "values": { "type": "object", "maxProperties": 30, "description": "The form's figures, each length with its unit: length, width, storeyHeight, eaveOverhang, rakeOverhang, slabThickness, footingWidth, footingDepth, trenchDepth, windowWidth, windowHeight, doorWidth, doorHeight (\"12 m\", \"40 ft\"); and the counts partitions, windows, outsideDoors, interiorDoors, iceDamEaves. Any left out opens where the page opens it.", "additionalProperties": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] } }, "storeys": { "type": "integer", "enum": [ 1, 2 ] }, "family": { "type": "string", "enum": [ "wall.framed-exterior", "wall.masonry", "wall.sip" ] }, "selection": { "type": "object", "maxProperties": 20, "additionalProperties": { "type": "string", "maxLength": 80 }, "description": "The exterior wall's build-up choices." }, "pitch": { "type": "string", "enum": [ "4", "6", "8", "10", "12" ], "description": "Roof pitch, rise in 12." }, "roofFamily": { "type": "string", "enum": [ "roof.asphalt-shingle", "roof.tile-slate" ] }, "roofSelection": { "type": "object", "maxProperties": 20, "additionalProperties": { "type": "string", "maxLength": 80 } } }, "description": "The House Estimator's form: the house drawn as the estimator draws it." }, "commands": { "type": "array", "minItems": 1, "maxItems": 500, "items": { "type": "object", "required": [ "op" ], "properties": { "op": { "enum": [ "level", "type", "wall", "opening", "room", "outline", "path", "point", "beam", "stair" ] }, "ref": { "type": "string", "maxLength": 60, "description": "A name by which later commands refer to what this one makes." }, "name": { "type": "string", "maxLength": 60, "description": "A level's, a type's or a room's name." }, "level": { "type": "string", "maxLength": 60, "description": "A ref given to an earlier command, or the name of a level or type (the blank drawing has the level \"ground\" and the types EW-1, IW-1, WN-1, DR-1)." }, "type": { "type": "string", "maxLength": 60, "description": "A ref given to an earlier command, or the name of a level or type (the blank drawing has the level \"ground\" and the types EW-1, IW-1, WN-1, DR-1)." }, "wall": { "type": "string", "maxLength": 60, "description": "The wall an opening goes in: its ref." }, "c": { "type": "string", "maxLength": 40, "description": "outline: slab, roof, floor, driveway, patio, deck, landscaping; path: footing, cable, pipe, duct, fence, retaining-wall; point: column, pier, outlet, switch, light, panel, fixture, drain, radiator, register." }, "kind": { "enum": [ "door", "window" ] }, "assembly": { "type": "string", "maxLength": 80, "description": "A type's build-up: a canvas assembly id (wall.framed-exterior, roof.asphalt-shingle, slab.on-grade …)." }, "selection": { "type": "object", "maxProperties": 20, "additionalProperties": { "type": "string", "maxLength": 80 } }, "thickness": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] }, "wastePercent": { "type": "number", "minimum": 0, "maximum": 100 }, "elevation": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] }, "height": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] }, "from": { "type": "object", "additionalProperties": false, "required": [ "x", "y" ], "properties": { "x": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] }, "y": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] } }, "description": "A point on plan, each coordinate a length with its unit." }, "to": { "type": "object", "additionalProperties": false, "required": [ "x", "y" ], "properties": { "x": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] }, "y": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] } }, "description": "A point on plan, each coordinate a length with its unit." }, "at": { "type": "object", "additionalProperties": false, "required": [ "x", "y" ], "properties": { "x": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] }, "y": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] } }, "description": "A point on plan, each coordinate a length with its unit." }, "offset": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ], "description": "An opening's centre, measured along its wall from the wall's start." }, "points": { "type": "array", "minItems": 2, "maxItems": 500, "items": { "type": "object", "additionalProperties": false, "required": [ "x", "y" ], "properties": { "x": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] }, "y": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] } }, "description": "A point on plan, each coordinate a length with its unit." } }, "closed": { "type": "boolean" }, "p": { "type": "object", "maxProperties": 20, "description": "The component's own properties by id (components/properties.ts): a length with its unit (widthMm, heightMm, sillMm …), a choice's option id, a count, true or false." }, "finishes": { "type": "object", "maxProperties": 10, "additionalProperties": { "type": "string", "maxLength": 80 }, "description": "A room's, or a driveway's, patio's, deck's, fence's or retaining wall's surface role → finish id, by the planner's ids." }, "scope": { "type": "object", "maxProperties": 30, "additionalProperties": { "type": [ "string", "number", "boolean" ] }, "description": "Its scope question name → answer, by the planner's ids." } } }, "description": "Drawing commands, in order, on the canvas's blank drawing (one storey; the wall, partition, window and door types). The whole request is at most 64 KiB." }, "document": { "type": "object", "description": "A Construction Canvas document (schema 1 to the canvas's current), opened and checked by the canvas's own opener." }, "shapes": { "type": "array", "minItems": 1, "maxItems": 40, "items": { "type": "object", "additionalProperties": false, "required": [ "shape" ], "properties": { "shape": { "enum": [ "room", "deck", "patio", "bed", "path", "fence" ], "description": "room: four exterior walls with doors and windows; deck, patio, bed (planted): a rectangle; path: a paved strip; fence: legs and 90° turns. Anything else is refused." }, "ref": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,40}$", "description": "A name a later shape's against uses." }, "name": { "type": "string", "maxLength": 60, "description": "A room's name." }, "at": { "type": "object", "additionalProperties": false, "required": [ "x", "y" ], "properties": { "x": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] }, "y": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] } }, "description": "The south-west corner (a path's or a fence's start). Left out: the origin." }, "width": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ], "description": "Along x (east): a room's, deck's, patio's or bed's; a path's width across it." }, "depth": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ], "description": "Along y (north); for a deck or patio against a side, out from it." }, "length": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ], "description": "A path's length." }, "heading": { "enum": [ "south", "east", "north", "west" ], "description": "The way a path or a fence's first leg runs (default east)." }, "against": { "type": "object", "additionalProperties": false, "required": [ "shape", "side" ], "properties": { "shape": { "type": "string" }, "side": { "enum": [ "south", "east", "north", "west" ] }, "offset": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] } }, "description": "A deck, patio or bed against a side of an earlier room or rectangle: centred on it, or from its west or south end by offset." }, "doors": { "type": "array", "maxItems": 20, "items": { "type": "object", "additionalProperties": false, "required": [ "side", "offset" ], "properties": { "side": { "enum": [ "south", "east", "north", "west" ] }, "offset": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ], "description": "Along the wall from its start: walls run counter-clockwise from the south-west corner." }, "exterior": { "type": "boolean", "description": "A door: an outside door (the default) or an inside one." } } } }, "windows": { "type": "array", "maxItems": 20, "items": { "type": "object", "additionalProperties": false, "required": [ "side", "offset" ], "properties": { "side": { "enum": [ "south", "east", "north", "west" ] }, "offset": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ], "description": "Along the wall from its start: walls run counter-clockwise from the south-west corner." }, "exterior": { "type": "boolean", "description": "A door: an outside door (the default) or an inside one." } } } }, "legs": { "type": "array", "minItems": 1, "maxItems": 20, "items": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] }, "description": "A fence's straight runs, in order." }, "turns": { "type": "array", "maxItems": 19, "items": { "enum": [ "left", "right" ] }, "description": "A 90° turn between each two legs." }, "gates": { "type": "array", "maxItems": 20, "items": { "type": "object", "additionalProperties": false, "required": [ "leg", "offset", "width" ], "properties": { "leg": { "type": "integer", "minimum": 1 }, "offset": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] }, "width": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] } } }, "description": "Gate openings, by leg (from 1) and offset along it; taken out of the run, the gate itself not counted." }, "build": { "enum": [ "pavers", "concrete" ], "description": "A patio's or path's build: a patio is concrete unless pavers; a path is pavers unless concrete." }, "finishes": { "type": "object", "maxProperties": 10, "additionalProperties": { "type": "string", "maxLength": 80 } }, "scope": { "type": "object", "maxProperties": 30, "additionalProperties": { "type": [ "string", "number", "boolean" ] } }, "p": { "type": "object", "maxProperties": 20, "description": "The component's own properties: a fence's heightMm, a bed's mulchDepthMm, each length with its unit." } } }, "description": "Simple shapes the assistant has read from the reader's words — a room, a deck, a patio, a bed, a path, a fence of legs and turns — compiled into the canvas's own commands. Every length with its unit." }, "layout": { "type": "object", "additionalProperties": false, "required": [ "rooms" ], "properties": { "grid": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ], "description": "The grid every figure is snapped to (default 10 mm, or 1/2 in in US units). Each snap that changed a figure is reported." }, "rooms": { "type": "array", "minItems": 1, "maxItems": 30, "items": { "type": "object", "additionalProperties": false, "required": [ "name", "width", "depth" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 60, "description": "Unique in the layout; openings and later rooms refer to it." }, "width": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ], "description": "Along x (east), wall centre to wall centre." }, "depth": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ], "description": "Along y (north), wall centre to wall centre." }, "at": { "type": "object", "additionalProperties": false, "required": [ "x", "y" ], "properties": { "x": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] }, "y": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] } }, "description": "Its south-west corner. The first room without at or against is at the origin." }, "against": { "type": "object", "additionalProperties": false, "required": [ "room", "side" ], "properties": { "room": { "type": "string", "maxLength": 60 }, "side": { "enum": [ "south", "east", "north", "west" ] }, "align": { "enum": [ "start", "centre", "end" ], "description": "Along that side: flush with its west or south end (start, the default), centred, or flush with the other end." }, "offset": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] } }, "description": "Beside a side of an earlier room, sharing that wall." } } } }, "doors": { "type": "array", "maxItems": 60, "items": { "type": "object", "additionalProperties": false, "properties": { "room": { "type": "string", "maxLength": 60, "description": "The room it is in, by name." }, "side": { "enum": [ "south", "east", "north", "west" ], "description": "The side of that room." }, "offset": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ], "description": "Its centre along the side from the side's start (walls counter-clockwise from the south-west corner); left out, the middle." }, "between": { "type": "array", "minItems": 2, "maxItems": 2, "items": { "type": "string", "maxLength": 60 }, "description": "A door only: the two rooms it joins, on the wall they share." }, "width": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ], "description": "The opening's width; left out, the canvas's default." } } }, "description": "Each between two rooms, or in a room's side (an outside door where that side is an exterior wall)." }, "windows": { "type": "array", "maxItems": 60, "items": { "type": "object", "additionalProperties": false, "properties": { "room": { "type": "string", "maxLength": 60, "description": "The room it is in, by name." }, "side": { "enum": [ "south", "east", "north", "west" ], "description": "The side of that room." }, "offset": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ], "description": "Its centre along the side from the side's start (walls counter-clockwise from the south-west corner); left out, the middle." }, "between": { "type": "array", "minItems": 2, "maxItems": 2, "items": { "type": "string", "maxLength": 60 }, "description": "A door only: the two rooms it joins, on the wall they share." }, "width": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ], "description": "The opening's width; left out, the canvas's default." } } }, "description": "Each in a room's side, on an exterior wall." } }, "description": "Rooms by name, size and which room each stands against, laid out on a grid: shared walls drawn once as partitions, every snap or move reported, and each room checked to close." }, "template": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$", "description": "A Construction Canvas template's slug (the template index lists them: single-room, deck, two-car-garage …): the drawing its page shows, in the reader's system, with a link that opens it." }, "variant": { "type": "string", "pattern": "^[a-z0-9-]{1,40}$", "description": "With template: one of its two \"what changes if\" variants, by id; a wrong one is refused with the template's own list." }, "system": { "type": "string", "enum": [ "metric", "imperial" ], "default": "metric", "description": "The unit system inputs left out open in, and the one the page link opens in. The answer comes in both." }, "inputUnits": { "type": "string", "enum": [ "base" ], "description": "Send \"base\" to pass bare numbers on dimensioned inputs in base units (m, m², L, kg …), as the published test vectors are written. Without it a length, area or volume must carry its unit." }, "formats": { "type": "array", "minItems": 1, "maxItems": 3, "items": { "enum": [ "dxf", "svg", "ifc" ] }, "description": "dxf, svg, ifc (openBIM IFC4: one file for the whole drawing, every level, with quantity sets), or several; left out, dxf and svg." }, "level": { "type": "string", "maxLength": 60, "description": "One level by its id or name; left out, every level with something on its plan." } } }, "example": { "template": "single-room", "system": "metric" }, "examples": { "export_drawing": { "summary": "The single-room template as a DXF and an SVG I can open in CAD.", "value": { "template": "single-room", "system": "metric" } } } } } }, "responses": { "200": { "description": "The files, inline where they fit, and the drawing's link.", "content": { "application/json": { "schema": { "type": "object", "anyOf": [ { "type": "object", "required": [ "engine", "system", "from", "levels", "files", "units", "layers", "links", "rebuild", "citation", "licence", "notice" ], "properties": { "engine": { "type": "object" }, "system": { "enum": [ "metric", "imperial" ] }, "from": { "type": "string" }, "template": { "type": "object" }, "levels": { "type": "array", "items": { "type": "object", "required": [ "id", "name" ] } }, "files": { "type": "array", "items": { "type": "object", "required": [ "format", "filename", "mediaType", "bytes", "content" ], "properties": { "level": { "type": "object" }, "format": { "enum": [ "dxf", "svg", "ifc" ] }, "filename": { "type": "string" }, "mediaType": { "type": "string" }, "bytes": { "type": "integer" }, "content": { "anyOf": [ { "type": "string", "description": "The file's text." }, { "type": "null" } ] }, "layers": { "type": "array", "items": { "type": "string" } }, "note": { "type": "string" } } } }, "units": { "type": "string" }, "layers": { "type": "string" }, "links": { "type": "object", "required": [ "canvas", "drawing" ], "properties": { "canvas": { "type": "string" }, "drawing": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, "rebuild": { "type": "string" }, "document": { "type": "object" }, "citation": { "type": "object", "required": [ "author", "title", "url", "formats", "accessDate" ], "properties": { "author": { "type": "string" }, "title": { "type": "string" }, "version": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sourcesChecked": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "url": { "type": "string" }, "accessDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "formats": { "type": "object", "required": [ "plain", "apa", "harvard", "bibtex" ], "properties": { "plain": { "type": "string" }, "apa": { "type": "string" }, "harvard": { "type": "string" }, "bibtex": { "type": "string" } } } } }, "licence": { "type": "object", "required": [ "name", "url", "attribution" ], "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "attribution": { "type": "string" } } }, "notice": { "type": "string" } } }, { "type": "object", "required": [ "detail", "tool", "title", "lines", "notes", "citation", "url", "open", "more" ], "properties": { "detail": { "const": "summary" }, "tool": { "type": "string" }, "title": { "type": "string" }, "lines": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "string" } }, "description": "The result lines, as the report's table gives them." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "What a professional must decide, when to call one, a false-friend warning, that adoption is local: kept in every summary." }, "citation": { "type": "string", "description": "The one citation line, built from the answer's own data." }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "open": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "more": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } ] } } } }, "400": { "description": "The request was refused; every problem is listed.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "title", "status", "problems" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "problems": { "type": "array", "items": { "type": "object", "required": [ "input", "problem" ], "properties": { "input": { "type": "string" }, "problem": { "type": "string" }, "accepted": { "type": "array", "items": { "type": "string" } } } } }, "didYouMean": { "type": "array", "items": { "type": "string" } } } } } } }, "413": { "description": "The request was refused; every problem is listed.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "title", "status", "problems" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "problems": { "type": "array", "items": { "type": "object", "required": [ "input", "problem" ], "properties": { "input": { "type": "string" }, "problem": { "type": "string" }, "accepted": { "type": "array", "items": { "type": "string" } } } } }, "didYouMean": { "type": "array", "items": { "type": "string" } } } } } } }, "422": { "description": "The request was refused; every problem is listed.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "title", "status", "problems" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "problems": { "type": "array", "items": { "type": "object", "required": [ "input", "problem" ], "properties": { "input": { "type": "string" }, "problem": { "type": "string" }, "accepted": { "type": "array", "items": { "type": "string" } } } } }, "didYouMean": { "type": "array", "items": { "type": "string" } } } } } } } }, "tags": [ "House and canvas" ], "parameters": [ { "name": "detail", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "full", "summary" ], "default": "full", "description": "full (the default): the whole answer. summary: the result lines, the citation line and the page only — fewer tokens to read." }, "description": "summary: the result lines, the citation and the page only (fewer tokens); full, the default: the whole answer. A POST body may carry detail instead." }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json", "md" ] }, "description": "md: the engine's Markdown report as text/markdown (or send Accept: text/markdown); json, the default." } ] } }, "/rebar-layout": { "post": { "operationId": "layoutReinforcement", "summary": "A bar layout drawing and counts for a rectangular slab or footing, from the bar size, spacing and cover given", "description": "A quantity layout, not a design: the engineer chooses bar size, spacing and cover. Counts by the site's Rebar Calculator's method inside the cover; weight by its Rebar Weight Calculator where it carries the size.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "length", "width", "cover", "barSize" ], "properties": { "element": { "enum": [ "slab", "footing" ], "default": "slab", "description": "A slab, or a pad or strip footing, as a rectangle on plan." }, "length": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ], "description": "Along x, with its unit." }, "width": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ], "description": "Along y, with its unit." }, "cover": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ], "description": "The cover to the bars on plan, as the engineer gives it." }, "barSize": { "type": "string", "minLength": 2, "maxLength": 12, "description": "As the engineer gives it: #4, 15M, N12, H12, T12 or 12 mm." }, "spacing": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ], "description": "The spacing both ways, as the engineer gives it." }, "lengthwise": { "type": "object", "additionalProperties": false, "properties": { "spacing": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] }, "count": { "type": "integer", "minimum": 0, "maximum": 1000, "description": "A number of bars spread evenly from cover to cover; 0 leaves this direction out." } }, "description": "The bars running along the length (spaced across the width): a spacing of their own, or a count." }, "widthwise": { "type": "object", "additionalProperties": false, "properties": { "spacing": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] }, "count": { "type": "integer", "minimum": 0, "maximum": 1000, "description": "A number of bars spread evenly from cover to cover; 0 leaves this direction out." } }, "description": "The bars running along the width (spaced along the length): a spacing of their own, or a count." }, "mats": { "enum": [ 1, 2 ], "default": 1, "description": "One mat, or two (top and bottom) laid out alike." }, "lapPercent": { "type": "number", "minimum": 0, "maximum": 40, "description": "The lap-splice allowance on the total; left out, the Rebar Calculator's own default." }, "chairs": { "type": "object", "additionalProperties": false, "required": [ "supportSpacing" ], "properties": { "supportSpacing": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ], "description": "The bar-support supplier's rated spacing." }, "supportEveryNth": { "enum": [ "1", "2", "3" ] } }, "description": "Count the bar supports too, from the supplier's support spacing." }, "formats": { "type": "array", "minItems": 1, "maxItems": 2, "items": { "enum": [ "svg", "dxf" ] }, "description": "The drawing's files: svg, dxf or both (the default)." }, "system": { "type": "string", "enum": [ "metric", "imperial" ], "default": "metric", "description": "The unit system inputs left out open in, and the one the page link opens in. The answer comes in both." }, "inputUnits": { "type": "string", "enum": [ "base" ], "description": "Send \"base\" to pass bare numbers on dimensioned inputs in base units (m, m², L, kg …), as the published test vectors are written. Without it a length, area or volume must carry its unit." } } }, "example": { "element": "slab", "length": "20 ft", "width": "12 ft", "cover": "2 in", "barSize": "#4", "spacing": "12 in", "system": "imperial" }, "examples": { "layout_reinforcement": { "summary": "Lay out #4 bars at 12 in each way with 2 in cover in a 20 × 12 ft slab, and count them.", "value": { "element": "slab", "length": "20 ft", "width": "12 ft", "cover": "2 in", "barSize": "#4", "spacing": "12 in", "system": "imperial" } } } } } }, "responses": { "200": { "description": "The bars each way, the totals, the checks and the drawing's files.", "content": { "application/json": { "schema": { "type": "object", "anyOf": [ { "type": "object", "required": [ "engine", "system", "element", "given", "clear", "bars", "totals", "calculatorCheck", "weight", "chairs", "files", "method", "leftOut", "notDesign", "citation", "licence", "notice" ], "properties": { "engine": { "type": "object" }, "system": { "enum": [ "metric", "imperial" ] }, "element": { "enum": [ "slab", "footing" ] }, "given": { "type": "object", "required": [ "length", "width", "cover", "barSize", "mats", "lapPercent" ] }, "clear": { "type": "object", "required": [ "length", "width" ], "properties": { "length": { "type": "object", "required": [ "m", "ft", "text" ], "properties": { "m": { "type": "number" }, "ft": { "type": "number" }, "text": { "type": "string" } } }, "width": { "type": "object", "required": [ "m", "ft", "text" ], "properties": { "m": { "type": "number" }, "ft": { "type": "number" }, "text": { "type": "string" } } } } }, "bars": { "type": "object", "required": [ "lengthwise", "widthwise", "totalBars" ] }, "totals": { "type": "object", "required": [ "barLength", "withLap", "lapPercent", "stockLength", "sticks", "sticksUnit" ] }, "calculatorCheck": { "anyOf": [ { "type": "object", "required": [ "calculator", "sticksOneMat", "barsLengthwise", "barsWidthwise", "agrees" ] }, { "type": "null" } ] }, "weight": { "anyOf": [ { "type": "object", "required": [ "metric", "imperial", "calculator" ] }, { "type": "null" } ] }, "weightNote": { "type": "string" }, "chairs": { "anyOf": [ { "type": "object", "required": [ "value", "unit", "calculator" ] }, { "type": "null" } ] }, "files": { "type": "array", "items": { "type": "object", "required": [ "format", "filename", "mediaType", "bytes", "content" ], "properties": { "level": { "type": "object" }, "format": { "enum": [ "dxf", "svg", "ifc" ] }, "filename": { "type": "string" }, "mediaType": { "type": "string" }, "bytes": { "type": "integer" }, "content": { "anyOf": [ { "type": "string", "description": "The file's text." }, { "type": "null" } ] }, "layers": { "type": "array", "items": { "type": "string" } }, "note": { "type": "string" } } } }, "method": { "type": "array", "items": { "type": "string" } }, "leftOut": { "type": "array", "items": { "type": "string" } }, "notDesign": { "type": "string" }, "citation": { "type": "object", "required": [ "author", "title", "url", "formats", "accessDate" ], "properties": { "author": { "type": "string" }, "title": { "type": "string" }, "version": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sourcesChecked": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "url": { "type": "string" }, "accessDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "formats": { "type": "object", "required": [ "plain", "apa", "harvard", "bibtex" ], "properties": { "plain": { "type": "string" }, "apa": { "type": "string" }, "harvard": { "type": "string" }, "bibtex": { "type": "string" } } } } }, "licence": { "type": "object", "required": [ "name", "url", "attribution" ], "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "attribution": { "type": "string" } } }, "notice": { "type": "string" } } }, { "type": "object", "required": [ "detail", "tool", "title", "lines", "notes", "citation", "url", "open", "more" ], "properties": { "detail": { "const": "summary" }, "tool": { "type": "string" }, "title": { "type": "string" }, "lines": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "string" } }, "description": "The result lines, as the report's table gives them." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "What a professional must decide, when to call one, a false-friend warning, that adoption is local: kept in every summary." }, "citation": { "type": "string", "description": "The one citation line, built from the answer's own data." }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "open": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "more": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } ] } } } }, "400": { "description": "The request was refused; every problem is listed.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "title", "status", "problems" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "problems": { "type": "array", "items": { "type": "object", "required": [ "input", "problem" ], "properties": { "input": { "type": "string" }, "problem": { "type": "string" }, "accepted": { "type": "array", "items": { "type": "string" } } } } }, "didYouMean": { "type": "array", "items": { "type": "string" } } } } } } }, "413": { "description": "The request was refused; every problem is listed.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "title", "status", "problems" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "problems": { "type": "array", "items": { "type": "object", "required": [ "input", "problem" ], "properties": { "input": { "type": "string" }, "problem": { "type": "string" }, "accepted": { "type": "array", "items": { "type": "string" } } } } }, "didYouMean": { "type": "array", "items": { "type": "string" } } } } } } } }, "tags": [ "House and canvas" ], "parameters": [ { "name": "detail", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "full", "summary" ], "default": "full", "description": "full (the default): the whole answer. summary: the result lines, the citation line and the page only — fewer tokens to read." }, "description": "summary: the result lines, the citation and the page only (fewer tokens); full, the default: the whole answer. A POST body may carry detail instead." }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json", "md" ] }, "description": "md: the engine's Markdown report as text/markdown (or send Accept: text/markdown); json, the default." } ] } }, "/convert": { "get": { "operationId": "convertUnits", "summary": "Convert a value between units with the site's exact factors", "parameters": [ { "name": "value", "in": "query", "required": true, "schema": { "type": "number" } }, { "name": "from", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 40 } }, { "name": "to", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 40 } }, { "name": "dimension", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 40 } }, { "name": "detail", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "full", "summary" ], "default": "full", "description": "full (the default): the whole answer. summary: the result lines, the citation line and the page only — fewer tokens to read." }, "description": "summary: the result lines, the citation and the page only (fewer tokens); full, the default: the whole answer. A POST body may carry detail instead." }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json", "md" ] }, "description": "md: the engine's Markdown report as text/markdown (or send Accept: text/markdown); json, the default." } ], "responses": { "200": { "description": "The converted value and the factor.", "content": { "application/json": { "schema": { "type": "object", "anyOf": [ { "type": "object", "required": [ "value", "from", "to", "dimension", "factor" ], "properties": { "value": { "type": "number" }, "from": { "type": "object", "required": [ "unit", "symbol", "label" ], "properties": { "unit": { "type": "string" }, "symbol": { "type": "string" }, "label": { "type": "string" } } }, "to": { "type": "object", "required": [ "unit", "symbol", "label", "value" ], "properties": { "unit": { "type": "string" }, "symbol": { "type": "string" }, "label": { "type": "string" }, "value": { "type": "number" } } }, "dimension": { "type": "string" }, "factor": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } } }, { "type": "object", "required": [ "detail", "tool", "title", "lines", "notes", "citation", "url", "open", "more" ], "properties": { "detail": { "const": "summary" }, "tool": { "type": "string" }, "title": { "type": "string" }, "lines": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "string" } }, "description": "The result lines, as the report's table gives them." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "What a professional must decide, when to call one, a false-friend warning, that adoption is local: kept in every summary." }, "citation": { "type": "string", "description": "The one citation line, built from the answer's own data." }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "open": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "more": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } ] } } } }, "400": { "description": "The request was refused; every problem is listed.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "title", "status", "problems" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "problems": { "type": "array", "items": { "type": "object", "required": [ "input", "problem" ], "properties": { "input": { "type": "string" }, "problem": { "type": "string" }, "accepted": { "type": "array", "items": { "type": "string" } } } } }, "didYouMean": { "type": "array", "items": { "type": "string" } } } } } } } }, "tags": [ "Units" ] } }, "/calculate-batch": { "post": { "operationId": "calculateBatch", "summary": "Several calculator runs in one request, each answered or refused on its own", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "items" ], "properties": { "items": { "type": "array", "minItems": 1, "maxItems": 25, "items": { "type": "object", "additionalProperties": false, "required": [ "slug" ], "properties": { "slug": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,119}$", "description": "The calculator's slug or permanent id, such as concrete-calculator or cq-c0201." }, "inputs": { "type": "object", "maxProperties": 100, "description": "The calculator's input values, by input id (an unknown id is refused with the accepted ids). A length, area, volume or other measured input takes \"12 ft\", \"3.5 m\", \"8' 3 1/2\\\"\" or {\"value\": 12, \"unit\": \"ft\"}; a count or percentage takes a number; a select takes one of its option values. Inputs left out take the value the calculator's page opens on.", "additionalProperties": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] } }, "system": { "type": "string", "enum": [ "metric", "imperial" ], "default": "metric", "description": "The unit system inputs left out open in, and the one the page link opens in. The answer comes in both." }, "market": { "type": "string", "enum": [ "US", "CA", "UK", "AU", "INTL" ], "description": "Optional. A market whose own opening choice some inputs take (a UK reader's code, an IEC motor), and whose currency symbol prints the caller's own money figures." }, "inputUnits": { "type": "string", "enum": [ "base" ], "description": "Send \"base\" to pass bare numbers on dimensioned inputs in base units (m, m², L, kg …), as the published test vectors are written. Without it a length, area or volume must carry its unit." }, "ref": { "type": "string", "maxLength": 80, "description": "The caller's own label for this run, returned with its result." } } }, "description": "The runs, 1 to 25, each one calculator and its inputs; answered in the same order." }, "system": { "type": "string", "enum": [ "metric", "imperial" ], "default": "metric", "description": "The unit system for every run that does not name its own." }, "market": { "type": "string", "enum": [ "US", "CA", "UK", "AU", "INTL" ], "description": "The market for every run that does not name its own." }, "inputUnits": { "type": "string", "enum": [ "base" ], "description": "Send \"base\" to pass bare numbers on dimensioned inputs in base units (m, m², L, kg …), as the published test vectors are written. Without it a length, area or volume must carry its unit." } } }, "example": { "system": "metric", "items": [ { "ref": "Slab", "slug": "concrete-calculator", "inputs": { "slabLength": "6 m", "slabWidth": "4 m", "slabThickness": "100 mm" } }, { "ref": "Walls", "slug": "drywall-calculator" }, { "ref": "Paint", "slug": "cq-c0656" } ] }, "examples": { "calculate_batch": { "summary": "In one request: the concrete for a 6 × 4 m slab, the drywall and the paint for the room (by its permanent id).", "value": { "system": "metric", "items": [ { "ref": "Slab", "slug": "concrete-calculator", "inputs": { "slabLength": "6 m", "slabWidth": "4 m", "slabThickness": "100 mm" } }, { "ref": "Walls", "slug": "drywall-calculator" }, { "ref": "Paint", "slug": "cq-c0656" } ] } } } } } }, "responses": { "200": { "description": "One entry per run, in order: the calculator's answer or that run's refusal.", "content": { "application/json": { "schema": { "type": "object", "anyOf": [ { "type": "object", "required": [ "engine", "counts", "results", "licence", "notice" ], "properties": { "engine": { "type": "object" }, "counts": { "type": "object", "required": [ "asked", "answered", "refused" ], "properties": { "asked": { "type": "integer" }, "answered": { "type": "integer" }, "refused": { "type": "integer" } } }, "results": { "type": "array", "items": { "anyOf": [ { "type": "object", "required": [ "index", "ok", "result" ], "properties": { "index": { "type": "integer" }, "ref": { "type": "string" }, "ok": { "const": true }, "result": { "type": "object", "required": [ "engine", "calculator", "system", "inputs", "result", "sources", "citation", "links", "licence", "notice" ], "properties": { "engine": { "type": "object", "required": [ "name", "version", "api" ], "properties": { "name": { "type": "string" }, "version": { "type": "string" }, "api": { "type": "string" } } }, "calculator": { "type": "object", "required": [ "slug", "title", "category", "version", "lastVerified", "url", "json" ], "properties": { "slug": { "type": "string" }, "title": { "type": "string" }, "category": { "type": "string" }, "description": { "type": "string" }, "version": { "type": "string", "description": "The calculator's own version; a result names the calculator that produced it." }, "lastVerified": { "type": "string", "description": "The date the calculator's sources were last checked." }, "url": { "type": "string", "description": "The calculator's page on craftquantities.com." }, "json": { "type": "string", "description": "The calculator's static API document, with its test vectors." } } }, "system": { "enum": [ "metric", "imperial" ] }, "market": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "inputs": { "type": "array", "items": { "type": "object", "required": [ "id", "label", "type", "value", "source" ], "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "type": { "enum": [ "number", "select" ] }, "value": { "type": [ "number", "string" ] }, "dimension": { "type": "string" }, "baseUnit": { "type": "string" }, "source": { "enum": [ "caller", "default" ] }, "read": { "type": "string" }, "metric": { "type": "object", "required": [ "value", "unit" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string" } } }, "imperial": { "type": "object", "required": [ "value", "unit" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string" } } }, "option": { "type": "string" } } }, "description": "Every input the calculation ran on, and where each came from." }, "result": { "type": "object", "required": [ "label", "metric", "imperial" ], "properties": { "label": { "type": "string" }, "metric": { "type": "object", "required": [ "value", "unit", "printed", "breakdown", "confidence", "isComparison", "canonical" ], "properties": { "value": { "anyOf": [ { "type": "number", "description": "The headline in this system; null where a rate it needs is not given." }, { "type": "null" } ] }, "unit": { "type": "string" }, "printed": { "anyOf": [ { "type": "string", "description": "The headline exactly as the page prints it." }, { "type": "null" } ] }, "breakdown": { "type": "array", "items": { "type": "object", "required": [ "label", "value", "unit", "printed" ], "properties": { "label": { "type": "string" }, "value": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "unit": { "type": "string" }, "printed": { "type": "string" } } } }, "confidence": { "enum": [ "high", "medium", "low" ] }, "confidenceNote": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowance": { "anyOf": [ { "type": "object", "properties": { "label": { "type": "string" }, "percent": { "type": "number" }, "base": { "type": "number" } } }, { "type": "null" } ] }, "limitations": { "type": "array", "items": { "type": "string" } }, "isComparison": { "type": "boolean", "description": "The figure is set against a limit. It is not an approval." }, "withheld": { "anyOf": [ { "type": "object", "properties": { "missingRates": { "type": "array", "items": { "type": "object", "properties": { "input": { "type": "string" }, "label": { "type": "string" } } } } } }, { "type": "null" } ] }, "canonical": { "type": "object", "required": [ "value", "unit" ], "properties": { "value": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "unit": { "type": "string" } }, "description": "The figure in the calculator's own unit, before the display adapter: what its test vectors pin." } } }, "imperial": { "type": "object", "required": [ "value", "unit", "printed", "breakdown", "confidence", "isComparison", "canonical" ], "properties": { "value": { "anyOf": [ { "type": "number", "description": "The headline in this system; null where a rate it needs is not given." }, { "type": "null" } ] }, "unit": { "type": "string" }, "printed": { "anyOf": [ { "type": "string", "description": "The headline exactly as the page prints it." }, { "type": "null" } ] }, "breakdown": { "type": "array", "items": { "type": "object", "required": [ "label", "value", "unit", "printed" ], "properties": { "label": { "type": "string" }, "value": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "unit": { "type": "string" }, "printed": { "type": "string" } } } }, "confidence": { "enum": [ "high", "medium", "low" ] }, "confidenceNote": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowance": { "anyOf": [ { "type": "object", "properties": { "label": { "type": "string" }, "percent": { "type": "number" }, "base": { "type": "number" } } }, { "type": "null" } ] }, "limitations": { "type": "array", "items": { "type": "string" } }, "isComparison": { "type": "boolean", "description": "The figure is set against a limit. It is not an approval." }, "withheld": { "anyOf": [ { "type": "object", "properties": { "missingRates": { "type": "array", "items": { "type": "object", "properties": { "input": { "type": "string" }, "label": { "type": "string" } } } } } }, { "type": "null" } ] }, "canonical": { "type": "object", "required": [ "value", "unit" ], "properties": { "value": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "unit": { "type": "string" } }, "description": "The figure in the calculator's own unit, before the display adapter: what its test vectors pin." } } } } }, "sources": { "type": "array", "items": { "type": "object", "required": [ "label" ], "properties": { "label": { "type": "string", "description": "The source as the calculator cites it." }, "url": { "type": "string", "description": "Only where the calculator gives one; none is invented." }, "references": { "type": "array", "items": { "type": "object", "required": [ "kind", "document" ], "properties": { "kind": { "enum": [ "code", "standard" ] }, "body": { "type": "string" }, "document": { "type": "string" }, "section": { "type": "string" }, "edition": { "type": "string" } } } } } } }, "citation": { "type": "object", "required": [ "author", "title", "url", "formats", "accessDate" ], "properties": { "author": { "type": "string" }, "title": { "type": "string" }, "version": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sourcesChecked": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "url": { "type": "string" }, "accessDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "formats": { "type": "object", "required": [ "plain", "apa", "harvard", "bibtex" ], "properties": { "plain": { "type": "string" }, "apa": { "type": "string" }, "harvard": { "type": "string" }, "bibtex": { "type": "string" } } } } }, "links": { "type": "object", "required": [ "page", "open" ], "properties": { "page": { "type": "string" }, "open": { "type": "string", "description": "Opens the page on these inputs." } } }, "licence": { "type": "object", "required": [ "name", "url", "attribution" ], "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "attribution": { "type": "string" } } }, "notice": { "type": "string" }, "explain": { "type": "object", "required": [ "about", "coverage", "steps", "final", "limits" ], "description": "Only when explain is true. Each figure is the calculator's own; no step is a formula written for the engine.", "properties": { "about": { "type": "string" }, "coverage": { "enum": [ "intermediates", "result-only" ], "description": "result-only: the calculator reports no figures between its inputs and its result." }, "steps": { "type": "array", "items": { "type": "object", "required": [ "n", "kind", "system", "label", "text" ], "properties": { "n": { "type": "integer" }, "kind": { "enum": [ "input", "intermediate", "result", "allowance", "range", "rates", "display" ] }, "system": { "enum": [ "metric", "imperial", "both" ] }, "label": { "type": "string" }, "value": { "anyOf": [ { "type": "number" }, { "type": "string" }, { "type": "null" } ] }, "unit": { "type": "string", "description": "The calculator's own (base) unit for the value." }, "metric": { "type": "object", "required": [ "value", "unit" ], "properties": { "value": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "unit": { "type": "string" } } }, "imperial": { "type": "object", "required": [ "value", "unit" ], "properties": { "value": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "unit": { "type": "string" } } }, "movedBy": { "type": "array", "items": { "type": "string" }, "description": "Input ids whose change moved this figure, measured by running compute again." }, "source": { "enum": [ "caller", "default" ] }, "text": { "type": "string", "description": "The step in words." } } } }, "final": { "type": "object", "required": [ "metric", "imperial" ], "properties": { "metric": { "type": "object", "required": [ "value", "unit", "printed" ], "properties": { "value": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "unit": { "type": "string" }, "printed": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, "imperial": { "type": "object", "required": [ "value", "unit", "printed" ], "properties": { "value": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "unit": { "type": "string" }, "printed": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } }, "description": "The figures the answer returns, copied from it." }, "limits": { "type": "array", "items": { "type": "string" }, "description": "What the trace does not show, and why." } } } } } } }, { "type": "object", "required": [ "index", "ok", "error" ], "properties": { "index": { "type": "integer" }, "ref": { "type": "string" }, "ok": { "const": false }, "error": { "type": "object", "required": [ "title", "status", "problems" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "problems": { "type": "array", "items": { "type": "object", "required": [ "input", "problem" ], "properties": { "input": { "type": "string" }, "problem": { "type": "string" }, "accepted": { "type": "array", "items": { "type": "string" } } } } }, "didYouMean": { "type": "array", "items": { "type": "string" } } } } } } ] }, "description": "One entry per run, in the order asked: the calculator's full answer, or why that run was refused. One refusal leaves the others answered." }, "licence": { "type": "object", "required": [ "name", "url", "attribution" ], "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "attribution": { "type": "string" } } }, "notice": { "type": "string" } } }, { "type": "object", "required": [ "detail", "tool", "title", "lines", "notes", "citation", "url", "open", "more" ], "properties": { "detail": { "const": "summary" }, "tool": { "type": "string" }, "title": { "type": "string" }, "lines": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "string" } }, "description": "The result lines, as the report's table gives them." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "What a professional must decide, when to call one, a false-friend warning, that adoption is local: kept in every summary." }, "citation": { "type": "string", "description": "The one citation line, built from the answer's own data." }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "open": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "more": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } ] } } } }, "400": { "description": "The request was refused; every problem is listed.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "title", "status", "problems" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "problems": { "type": "array", "items": { "type": "object", "required": [ "input", "problem" ], "properties": { "input": { "type": "string" }, "problem": { "type": "string" }, "accepted": { "type": "array", "items": { "type": "string" } } } } }, "didYouMean": { "type": "array", "items": { "type": "string" } } } } } } }, "413": { "description": "The request was refused; every problem is listed.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "title", "status", "problems" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "problems": { "type": "array", "items": { "type": "object", "required": [ "input", "problem" ], "properties": { "input": { "type": "string" }, "problem": { "type": "string" }, "accepted": { "type": "array", "items": { "type": "string" } } } } }, "didYouMean": { "type": "array", "items": { "type": "string" } } } } } } } }, "tags": [ "Agent tools" ], "parameters": [ { "name": "detail", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "full", "summary" ], "default": "full", "description": "full (the default): the whole answer. summary: the result lines, the citation line and the page only — fewer tokens to read." }, "description": "summary: the result lines, the citation and the page only (fewer tokens); full, the default: the whole answer. A POST body may carry detail instead." }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json", "md" ] }, "description": "md: the engine's Markdown report as text/markdown (or send Accept: text/markdown); json, the default." } ] } }, "/project-update": { "post": { "operationId": "updateProject", "summary": "Change a project held in a state token: spaces, dimensions, takeoffs, calculator lines, roof pitch", "description": "Stateless: the token carries the project's inputs (compressed, not encrypted), and the answer carries the new token. Every line is rebuilt.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "token" ], "properties": { "token": { "type": "string", "minLength": 8, "maxLength": 16384, "description": "A project state token from a project-file answer or an earlier update." }, "operations": { "type": "array", "maxItems": 20, "items": { "type": "object", "additionalProperties": false, "required": [ "op" ], "properties": { "op": { "enum": [ "add_space", "remove_space", "set_dimension", "add_takeoff", "remove_takeoff", "add_calculator", "remove_calculator", "set_roof_pitch", "rename" ], "description": "add_space (space) and remove_space (index) on a plan; set_dimension (target, index, field, value) on a space's figure, a calculator's input, a takeoff's measurement or a house's figure; add_takeoff (takeoff) and remove_takeoff (index or takeoff id); add_calculator (calculator) and remove_calculator (index); set_roof_pitch (pitch) on a plan's roof or a house; rename (name)." }, "space": { "type": "object", "description": "add_space: one space as a plan takes it (kind, figures, doors, windows, finishes …)." }, "takeoff": { "anyOf": [ { "type": "object", "additionalProperties": false, "required": [ "takeoff" ], "properties": { "takeoff": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,119}$" }, "measurements": { "type": "object", "maxProperties": 50, "description": "Measurement id → value, each length, area or volume with its unit (\"12 ft\", {\"value\": 3.6, \"unit\": \"m\"}); counts as numbers. Ids are those of the takeoff; any left out opens at the page's own figure.", "additionalProperties": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] } }, "selection": { "type": "object", "maxProperties": 20, "description": "Build-up choice id → option id, the takeoff's own (a stud size, an insulation, a cladding). Choices left out take the page's own for the system.", "additionalProperties": { "type": "string", "maxLength": 80 } }, "allowances": { "type": "object", "maxProperties": 50, "description": "Row → an allowance the reader sets: a percentage (cutting waste, overlap), or the option an allowance follows (a lay pattern). Row names are the takeoff's steps (the calculator slug, or the step key where one runs twice).", "additionalProperties": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 100 }, { "type": "string", "maxLength": 80 } ] } }, "leaveOut": { "type": "array", "maxItems": 100, "items": { "type": "string", "maxLength": 120 }, "description": "Rows the reader leaves out of the job: still worked and shown, not put in the project or counted in labour." }, "inputUnits": { "type": "string", "enum": [ "base" ], "description": "Send \"base\" to pass bare numbers on dimensioned inputs in base units (m, m², L, kg …), as the published test vectors are written. Without it a length, area or volume must carry its unit." } } }, { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,119}$" } ], "description": "add_takeoff: a takeoff and its measurements; remove_takeoff: a takeoff id." }, "calculator": { "type": "object", "additionalProperties": false, "required": [ "slug" ], "properties": { "slug": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,119}$", "description": "The calculator's slug, such as concrete-calculator." }, "inputs": { "type": "object", "maxProperties": 100, "description": "The calculator's input values, by input id (an unknown id is refused with the accepted ids). A length, area, volume or other measured input takes \"12 ft\", \"3.5 m\", \"8' 3 1/2\\\"\" or {\"value\": 12, \"unit\": \"ft\"}; a count or percentage takes a number; a select takes one of its option values. Inputs left out take the value the calculator's page opens on.", "additionalProperties": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] } }, "label": { "type": "string", "maxLength": 120, "description": "The line's name in the project; the calculator's title when left out." }, "inputUnits": { "type": "string", "enum": [ "base" ], "description": "Send \"base\" to pass bare numbers on dimensioned inputs in base units (m, m², L, kg …), as the published test vectors are written. Without it a length, area or volume must carry its unit." } } }, "target": { "enum": [ "space", "calculator", "takeoff", "house" ], "description": "set_dimension: what the figure belongs to." }, "index": { "type": "integer", "minimum": 0, "maximum": 49, "description": "Which space, calculator, takeoff or house, counting from 0 (default 0)." }, "field": { "type": "string", "maxLength": 60, "description": "set_dimension: the figure's id (a space's figure, a calculator's input, a takeoff's measurement, a house's value)." }, "value": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] }, "pitch": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 24 }, { "type": "string", "maxLength": 8 } ], "description": "set_roof_pitch: rise in 12 (a plan's roof takes 0 to 24; a house 4, 6, 8, 10 or 12)." }, "name": { "type": "string", "maxLength": 120 } } }, "description": "The changes, applied in order (0 to 20); none returns the project as the token holds it." }, "file": { "type": "boolean", "default": false, "description": "true: the updated My Project file as well." } } }, "example": { "token": "cqp1.zZYtBDsIgEEWvYv6amFRdzdKb1M4IxMIYoDZNw90NRBfG5fv_vR0v0GDw8JFBeM5jhEEcg4BwFU6qAQZ5y0UCCEFK8hMMbsobaP-GH-8vvHu7JMnNnCXa4kC4HNqzeu507uTEW1dAOB3bXQ1YNfVu0iUW0FBbE1nX37XWNw.a6887bd2", "operations": [ { "op": "set_dimension", "target": "space", "index": 0, "field": "length", "value": "4.5 m" }, { "op": "add_space", "space": { "kind": "bathroom", "name": "Bathroom", "figures": { "length": "2.5 m", "width": "2 m", "height": "2.4 m" }, "doors": { "count": 1 } } }, { "op": "set_roof_pitch", "pitch": 6 } ] }, "examples": { "update_project": { "summary": "Make the bedroom 4.5 m long, add a bathroom and put a 6-in-12 roof over both.", "value": { "token": "cqp1.zZYtBDsIgEEWvYv6amFRdzdKb1M4IxMIYoDZNw90NRBfG5fv_vR0v0GDw8JFBeM5jhEEcg4BwFU6qAQZ5y0UCCEFK8hMMbsobaP-GH-8vvHu7JMnNnCXa4kC4HNqzeu507uTEW1dAOB3bXQ1YNfVu0iUW0FBbE1nX37XWNw.a6887bd2", "operations": [ { "op": "set_dimension", "target": "space", "index": 0, "field": "length", "value": "4.5 m" }, { "op": "add_space", "space": { "kind": "bathroom", "name": "Bathroom", "figures": { "length": "2.5 m", "width": "2 m", "height": "2.4 m" }, "doors": { "count": 1 } } }, { "op": "set_roof_pitch", "pitch": 6 } ] } } } } } }, "responses": { "200": { "description": "The new token, the diff, the totals and the site link.", "content": { "application/json": { "schema": { "type": "object", "anyOf": [ { "type": "object", "required": [ "engine", "kind", "state", "applied", "project", "diff", "totals", "licence", "notice" ], "properties": { "engine": { "type": "object" }, "kind": { "enum": [ "calculators", "takeoffs", "houses", "plan", "drawing" ] }, "state": { "type": "object", "required": [ "token", "format", "note" ], "properties": { "token": { "anyOf": [ { "type": "string", "description": "The project's inputs, deflated and base64url-encoded with a format version and a CRC-32 check (cqp1.…). Compact, not encrypted: anyone who has it can read it." }, { "type": "null" } ] }, "format": { "type": "string", "description": "The token's format and version." }, "characters": { "type": "integer" }, "link": { "type": "string", "description": "Opens the project on the site from the token, carried in the address fragment, which a browser does not send to any server." }, "note": { "type": "string" } } }, "applied": { "type": "array", "items": { "type": "string" }, "description": "Each operation as it was applied." }, "project": { "type": "object", "required": [ "name", "system", "lines" ], "properties": { "name": { "type": "string" }, "system": { "enum": [ "metric", "imperial" ] }, "lines": { "type": "array", "items": { "type": "object", "required": [ "label", "quantity", "unit", "from" ] } } } }, "diff": { "type": "object", "required": [ "added", "removed", "changed", "unchanged" ], "properties": { "added": { "type": "array", "items": { "type": "object", "required": [ "zone", "label", "unit", "quantity" ], "properties": { "zone": { "type": "string" }, "label": { "type": "string" }, "unit": { "type": "string" }, "quantity": { "type": "number" } } } }, "removed": { "type": "array", "items": { "type": "object", "required": [ "zone", "label", "unit", "quantity" ], "properties": { "zone": { "type": "string" }, "label": { "type": "string" }, "unit": { "type": "string" }, "quantity": { "type": "number" } } } }, "changed": { "type": "array", "items": { "type": "object", "required": [ "zone", "label", "unit", "from", "to" ], "properties": { "zone": { "type": "string" }, "label": { "type": "string" }, "unit": { "type": "string" }, "from": { "type": "number" }, "to": { "type": "number" } } } }, "unchanged": { "type": "integer" }, "more": { "type": "integer" } }, "description": "What the operations changed, line by line (lines that share a zone, a name and a unit are summed)." }, "totals": { "type": "object", "required": [ "lines", "byUnit", "note" ], "properties": { "lines": { "type": "integer" }, "byUnit": { "type": "array", "items": { "type": "object", "required": [ "unit", "quantity", "lines" ], "properties": { "unit": { "type": "string" }, "quantity": { "type": "number" }, "lines": { "type": "integer" } } } }, "note": { "type": "string" } } }, "file": { "type": "object", "required": [ "filename", "mediaType", "content" ], "properties": { "filename": { "type": "string" }, "mediaType": { "const": "application/json" }, "content": { "type": "object", "required": [ "magic", "v", "exportedAt", "stores" ], "properties": { "magic": { "const": "craftquantities.backup" }, "v": { "type": "integer" }, "exportedAt": { "type": "string" }, "stores": { "type": "object" } } } } }, "howToImport": { "type": "string" }, "licence": { "type": "object", "required": [ "name", "url", "attribution" ], "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "attribution": { "type": "string" } } }, "notice": { "type": "string" } } }, { "type": "object", "required": [ "detail", "tool", "title", "lines", "notes", "citation", "url", "open", "more" ], "properties": { "detail": { "const": "summary" }, "tool": { "type": "string" }, "title": { "type": "string" }, "lines": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "string" } }, "description": "The result lines, as the report's table gives them." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "What a professional must decide, when to call one, a false-friend warning, that adoption is local: kept in every summary." }, "citation": { "type": "string", "description": "The one citation line, built from the answer's own data." }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "open": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "more": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } ] } } } }, "400": { "description": "The request was refused; every problem is listed.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "title", "status", "problems" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "problems": { "type": "array", "items": { "type": "object", "required": [ "input", "problem" ], "properties": { "input": { "type": "string" }, "problem": { "type": "string" }, "accepted": { "type": "array", "items": { "type": "string" } } } } }, "didYouMean": { "type": "array", "items": { "type": "string" } } } } } } }, "413": { "description": "The request was refused; every problem is listed.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "title", "status", "problems" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "problems": { "type": "array", "items": { "type": "object", "required": [ "input", "problem" ], "properties": { "input": { "type": "string" }, "problem": { "type": "string" }, "accepted": { "type": "array", "items": { "type": "string" } } } } }, "didYouMean": { "type": "array", "items": { "type": "string" } } } } } } }, "422": { "description": "The request was refused; every problem is listed.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "title", "status", "problems" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "problems": { "type": "array", "items": { "type": "object", "required": [ "input", "problem" ], "properties": { "input": { "type": "string" }, "problem": { "type": "string" }, "accepted": { "type": "array", "items": { "type": "string" } } } } }, "didYouMean": { "type": "array", "items": { "type": "string" } } } } } } } }, "tags": [ "Agent tools" ], "parameters": [ { "name": "detail", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "full", "summary" ], "default": "full", "description": "full (the default): the whole answer. summary: the result lines, the citation line and the page only — fewer tokens to read." }, "description": "summary: the result lines, the citation and the page only (fewer tokens); full, the default: the whole answer. A POST body may carry detail instead." }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json", "md" ] }, "description": "md: the engine's Markdown report as text/markdown (or send Accept: text/markdown); json, the default." } ] } }, "/classify": { "post": { "operationId": "classifyItems", "summary": "Group lines, calculators or a project by MasterFormat 2018 division (a suggestion)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [], "properties": { "token": { "type": "string", "minLength": 8, "maxLength": 16384, "description": "A project state token: its lines are grouped." }, "lines": { "type": "array", "minItems": 1, "maxItems": 400, "items": { "type": "object", "additionalProperties": true, "properties": { "label": { "type": "string", "maxLength": 200 }, "description": { "type": "string", "maxLength": 200 }, "quantity": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 }, "slug": { "type": "string", "maxLength": 120, "description": "The calculator that made the line, where known." }, "calculator": { "type": "string", "maxLength": 120 }, "from": { "type": "string", "maxLength": 160, "description": "Where the line came from, as a project file names it (calculator:…, takeoff:…)." } } }, "description": "Lines of a takeoff, plan, house, drawing or bill: each a label, and the calculator slug where known." }, "calculators": { "type": "array", "minItems": 1, "maxItems": 400, "items": { "type": "string", "maxLength": 120 }, "description": "Calculator slugs or permanent ids." } } }, "example": { "lines": [ { "label": "Ready-mix concrete", "quantity": 2.64, "unit": "m³", "slug": "concrete-calculator" }, { "label": "Rebar, 12 mm", "quantity": 11, "unit": "sticks", "slug": "rebar-calculator" }, { "label": "Damp-proof membrane", "quantity": 30, "unit": "m²" }, { "label": "Hardcore sub-base", "quantity": 2.4, "unit": "t" } ] }, "examples": { "classify_items": { "summary": "Group my slab's bill by MasterFormat division.", "value": { "lines": [ { "label": "Ready-mix concrete", "quantity": 2.64, "unit": "m³", "slug": "concrete-calculator" }, { "label": "Rebar, 12 mm", "quantity": 11, "unit": "sticks", "slug": "rebar-calculator" }, { "label": "Damp-proof membrane", "quantity": 30, "unit": "m²" }, { "label": "Hardcore sub-base", "quantity": 2.4, "unit": "t" } ] } } } } } }, "responses": { "200": { "description": "The lines by division, in MasterFormat order.", "content": { "application/json": { "schema": { "type": "object", "anyOf": [ { "type": "object", "required": [ "scheme", "divisions", "counts", "note", "licence" ], "properties": { "scheme": { "type": "object", "required": [ "name", "edition", "level" ], "properties": { "name": { "type": "string" }, "edition": { "type": "string" }, "level": { "type": "string" } } }, "divisions": { "type": "array", "items": { "type": "object", "required": [ "code", "name", "lines" ], "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "lines": { "type": "array", "items": { "type": "object", "required": [ "label", "basis" ], "properties": { "label": { "type": "string" }, "quantity": { "type": "number" }, "unit": { "type": "string" }, "slug": { "type": "string" }, "basis": { "enum": [ "calculator", "words", "none" ] } } } } } } }, "counts": { "type": "object", "required": [ "lines", "divisions", "unassigned" ], "properties": { "lines": { "type": "integer" }, "divisions": { "type": "integer" }, "unassigned": { "type": "integer" } } }, "note": { "type": "string" }, "otherSchemes": { "type": "string" }, "licence": { "type": "object", "required": [ "name", "url", "attribution" ], "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "attribution": { "type": "string" } } } } }, { "type": "object", "required": [ "detail", "tool", "title", "lines", "notes", "citation", "url", "open", "more" ], "properties": { "detail": { "const": "summary" }, "tool": { "type": "string" }, "title": { "type": "string" }, "lines": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "string" } }, "description": "The result lines, as the report's table gives them." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "What a professional must decide, when to call one, a false-friend warning, that adoption is local: kept in every summary." }, "citation": { "type": "string", "description": "The one citation line, built from the answer's own data." }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "open": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "more": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } ] } } } }, "400": { "description": "The request was refused; every problem is listed.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "title", "status", "problems" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "problems": { "type": "array", "items": { "type": "object", "required": [ "input", "problem" ], "properties": { "input": { "type": "string" }, "problem": { "type": "string" }, "accepted": { "type": "array", "items": { "type": "string" } } } } }, "didYouMean": { "type": "array", "items": { "type": "string" } } } } } } }, "422": { "description": "The request was refused; every problem is listed.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "title", "status", "problems" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "problems": { "type": "array", "items": { "type": "object", "required": [ "input", "problem" ], "properties": { "input": { "type": "string" }, "problem": { "type": "string" }, "accepted": { "type": "array", "items": { "type": "string" } } } } }, "didYouMean": { "type": "array", "items": { "type": "string" } } } } } } } }, "tags": [ "Agent tools" ], "parameters": [ { "name": "detail", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "full", "summary" ], "default": "full", "description": "full (the default): the whole answer. summary: the result lines, the citation line and the page only — fewer tokens to read." }, "description": "summary: the result lines, the citation and the page only (fewer tokens); full, the default: the whole answer. A POST body may carry detail instead." }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json", "md" ] }, "description": "md: the engine's Markdown report as text/markdown (or send Accept: text/markdown); json, the default." } ] } }, "/id/{id}": { "get": { "operationId": "resolveId", "summary": "A permanent id, an old slug or a site address to the page as it is today", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 300, "description": "A permanent id (cq-c0412), a current or earlier slug, or a craftquantities.com address." } }, { "name": "kind", "in": "query", "required": false, "schema": { "enum": [ "calculator", "takeoff", "guide", "example", "term", "diagnosis" ], "description": "Only pages of this kind." } }, { "name": "detail", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "full", "summary" ], "default": "full", "description": "full (the default): the whole answer. summary: the result lines, the citation line and the page only — fewer tokens to read." }, "description": "summary: the result lines, the citation and the page only (fewer tokens); full, the default: the whole answer. A POST body may carry detail instead." }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json", "md" ] }, "description": "md: the engine's Markdown report as text/markdown (or send Accept: text/markdown); json, the default." } ], "responses": { "200": { "description": "The page or pages it names.", "content": { "application/json": { "schema": { "type": "object", "anyOf": [ { "type": "object", "required": [ "matches", "licence" ], "properties": { "matches": { "type": "array", "items": { "type": "object", "required": [ "id", "kind", "slug", "history", "url", "permanentUrl" ], "properties": { "id": { "type": "string", "description": "The permanent id: assigned once, kept whatever the page's slug or category becomes." }, "kind": { "enum": [ "calculator", "takeoff", "guide", "example", "term", "diagnosis" ] }, "slug": { "type": "string", "description": "The slug the page answers on today." }, "history": { "type": "array", "items": { "type": "string" }, "description": "Every slug the page has had, the current one last." }, "url": { "type": "string", "description": "The page's address today." }, "permanentUrl": { "type": "string", "description": "The site's /id/ address for the page, which redirects to wherever the page is." }, "retired": { "type": "object", "properties": { "replacedBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } }, "description": "The pages the reference names: one for an id, more where pages of different kinds share a slug." }, "licence": { "type": "object", "required": [ "name", "url", "attribution" ], "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "attribution": { "type": "string" } } } } }, { "type": "object", "required": [ "detail", "tool", "title", "lines", "notes", "citation", "url", "open", "more" ], "properties": { "detail": { "const": "summary" }, "tool": { "type": "string" }, "title": { "type": "string" }, "lines": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "string" } }, "description": "The result lines, as the report's table gives them." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "What a professional must decide, when to call one, a false-friend warning, that adoption is local: kept in every summary." }, "citation": { "type": "string", "description": "The one citation line, built from the answer's own data." }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "open": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "more": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } ] } } } }, "400": { "description": "The request was refused; every problem is listed.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "title", "status", "problems" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "problems": { "type": "array", "items": { "type": "object", "required": [ "input", "problem" ], "properties": { "input": { "type": "string" }, "problem": { "type": "string" }, "accepted": { "type": "array", "items": { "type": "string" } } } } }, "didYouMean": { "type": "array", "items": { "type": "string" } } } } } } }, "404": { "description": "The request was refused; every problem is listed.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "title", "status", "problems" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "problems": { "type": "array", "items": { "type": "object", "required": [ "input", "problem" ], "properties": { "input": { "type": "string" }, "problem": { "type": "string" }, "accepted": { "type": "array", "items": { "type": "string" } } } } }, "didYouMean": { "type": "array", "items": { "type": "string" } } } } } } } }, "tags": [ "Agent tools" ] } }, "/programme": { "post": { "operationId": "planProgramme", "summary": "A build programme from a project's labour hours: tasks by trade, stage and level, working days, CSV and calendar", "description": "Stateless: the project comes as a state token, a My Project file, takeoffs or a drawing. Durations are the labour hours over the crew and working day given; no dates without a start date; hours and days only.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "token": { "type": "string", "minLength": 8, "maxLength": 16384, "description": "A project state token (cqp1.…) from a project-file answer or an update: the project whose lines are put in order." }, "file": { "type": "object", "description": "A My Project file (the backup a project-file answer returns, or one the reader exported): its active project's lines and any hours typed on them." }, "takeoffs": { "type": "array", "minItems": 1, "maxItems": 10, "items": { "type": "object", "additionalProperties": false, "required": [ "takeoff" ], "properties": { "takeoff": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,119}$" }, "measurements": { "type": "object", "maxProperties": 50, "description": "Measurement id → value, each length, area or volume with its unit (\"12 ft\", {\"value\": 3.6, \"unit\": \"m\"}); counts as numbers. Ids are those of the takeoff; any left out opens at the page's own figure.", "additionalProperties": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] } }, "selection": { "type": "object", "maxProperties": 20, "description": "Build-up choice id → option id, the takeoff's own (a stud size, an insulation, a cladding). Choices left out take the page's own for the system.", "additionalProperties": { "type": "string", "maxLength": 80 } }, "allowances": { "type": "object", "maxProperties": 50, "description": "Row → an allowance the reader sets: a percentage (cutting waste, overlap), or the option an allowance follows (a lay pattern). Row names are the takeoff's steps (the calculator slug, or the step key where one runs twice).", "additionalProperties": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 100 }, { "type": "string", "maxLength": 80 } ] } }, "leaveOut": { "type": "array", "maxItems": 100, "items": { "type": "string", "maxLength": 120 }, "description": "Rows the reader leaves out of the job: still worked and shown, not put in the project or counted in labour." }, "inputUnits": { "type": "string", "enum": [ "base" ], "description": "Send \"base\" to pass bare numbers on dimensioned inputs in base units (m, m², L, kg …), as the published test vectors are written. Without it a length, area or volume must carry its unit." } } }, "description": "Whole-job takeoffs, each an id and its measurements, as a project file takes them." }, "drawing": { "type": "object", "additionalProperties": false, "properties": { "house": { "type": "object", "additionalProperties": false, "properties": { "example": { "type": "string", "maxLength": 120, "description": "Start from one of the site's example houses (its slug) in place of the estimator's opening house." }, "values": { "type": "object", "maxProperties": 30, "description": "The form's figures, each length with its unit: length, width, storeyHeight, eaveOverhang, rakeOverhang, slabThickness, footingWidth, footingDepth, trenchDepth, windowWidth, windowHeight, doorWidth, doorHeight (\"12 m\", \"40 ft\"); and the counts partitions, windows, outsideDoors, interiorDoors, iceDamEaves. Any left out opens where the page opens it.", "additionalProperties": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] } }, "storeys": { "type": "integer", "enum": [ 1, 2 ] }, "family": { "type": "string", "enum": [ "wall.framed-exterior", "wall.masonry", "wall.sip" ] }, "selection": { "type": "object", "maxProperties": 20, "additionalProperties": { "type": "string", "maxLength": 80 }, "description": "The exterior wall's build-up choices." }, "pitch": { "type": "string", "enum": [ "4", "6", "8", "10", "12" ], "description": "Roof pitch, rise in 12." }, "roofFamily": { "type": "string", "enum": [ "roof.asphalt-shingle", "roof.tile-slate" ] }, "roofSelection": { "type": "object", "maxProperties": 20, "additionalProperties": { "type": "string", "maxLength": 80 } } }, "description": "The House Estimator's form: the house drawn as the estimator draws it." }, "commands": { "type": "array", "minItems": 1, "maxItems": 500, "items": { "type": "object", "required": [ "op" ], "properties": { "op": { "enum": [ "level", "type", "wall", "opening", "room", "outline", "path", "point", "beam", "stair" ] }, "ref": { "type": "string", "maxLength": 60, "description": "A name by which later commands refer to what this one makes." }, "name": { "type": "string", "maxLength": 60, "description": "A level's, a type's or a room's name." }, "level": { "type": "string", "maxLength": 60, "description": "A ref given to an earlier command, or the name of a level or type (the blank drawing has the level \"ground\" and the types EW-1, IW-1, WN-1, DR-1)." }, "type": { "type": "string", "maxLength": 60, "description": "A ref given to an earlier command, or the name of a level or type (the blank drawing has the level \"ground\" and the types EW-1, IW-1, WN-1, DR-1)." }, "wall": { "type": "string", "maxLength": 60, "description": "The wall an opening goes in: its ref." }, "c": { "type": "string", "maxLength": 40, "description": "outline: slab, roof, floor, driveway, patio, deck, landscaping; path: footing, cable, pipe, duct, fence, retaining-wall; point: column, pier, outlet, switch, light, panel, fixture, drain, radiator, register." }, "kind": { "enum": [ "door", "window" ] }, "assembly": { "type": "string", "maxLength": 80, "description": "A type's build-up: a canvas assembly id (wall.framed-exterior, roof.asphalt-shingle, slab.on-grade …)." }, "selection": { "type": "object", "maxProperties": 20, "additionalProperties": { "type": "string", "maxLength": 80 } }, "thickness": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] }, "wastePercent": { "type": "number", "minimum": 0, "maximum": 100 }, "elevation": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] }, "height": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] }, "from": { "type": "object", "additionalProperties": false, "required": [ "x", "y" ], "properties": { "x": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] }, "y": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] } }, "description": "A point on plan, each coordinate a length with its unit." }, "to": { "type": "object", "additionalProperties": false, "required": [ "x", "y" ], "properties": { "x": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] }, "y": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] } }, "description": "A point on plan, each coordinate a length with its unit." }, "at": { "type": "object", "additionalProperties": false, "required": [ "x", "y" ], "properties": { "x": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] }, "y": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] } }, "description": "A point on plan, each coordinate a length with its unit." }, "offset": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ], "description": "An opening's centre, measured along its wall from the wall's start." }, "points": { "type": "array", "minItems": 2, "maxItems": 500, "items": { "type": "object", "additionalProperties": false, "required": [ "x", "y" ], "properties": { "x": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] }, "y": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] } }, "description": "A point on plan, each coordinate a length with its unit." } }, "closed": { "type": "boolean" }, "p": { "type": "object", "maxProperties": 20, "description": "The component's own properties by id (components/properties.ts): a length with its unit (widthMm, heightMm, sillMm …), a choice's option id, a count, true or false." }, "finishes": { "type": "object", "maxProperties": 10, "additionalProperties": { "type": "string", "maxLength": 80 }, "description": "A room's, or a driveway's, patio's, deck's, fence's or retaining wall's surface role → finish id, by the planner's ids." }, "scope": { "type": "object", "maxProperties": 30, "additionalProperties": { "type": [ "string", "number", "boolean" ] }, "description": "Its scope question name → answer, by the planner's ids." } } }, "description": "Drawing commands, in order, on the canvas's blank drawing (one storey; the wall, partition, window and door types). The whole request is at most 64 KiB." }, "document": { "type": "object", "description": "A Construction Canvas document (schema 1 to the canvas's current), opened and checked by the canvas's own opener." }, "shapes": { "type": "array", "minItems": 1, "maxItems": 40, "items": { "type": "object", "additionalProperties": false, "required": [ "shape" ], "properties": { "shape": { "enum": [ "room", "deck", "patio", "bed", "path", "fence" ], "description": "room: four exterior walls with doors and windows; deck, patio, bed (planted): a rectangle; path: a paved strip; fence: legs and 90° turns. Anything else is refused." }, "ref": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,40}$", "description": "A name a later shape's against uses." }, "name": { "type": "string", "maxLength": 60, "description": "A room's name." }, "at": { "type": "object", "additionalProperties": false, "required": [ "x", "y" ], "properties": { "x": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] }, "y": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] } }, "description": "The south-west corner (a path's or a fence's start). Left out: the origin." }, "width": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ], "description": "Along x (east): a room's, deck's, patio's or bed's; a path's width across it." }, "depth": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ], "description": "Along y (north); for a deck or patio against a side, out from it." }, "length": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ], "description": "A path's length." }, "heading": { "enum": [ "south", "east", "north", "west" ], "description": "The way a path or a fence's first leg runs (default east)." }, "against": { "type": "object", "additionalProperties": false, "required": [ "shape", "side" ], "properties": { "shape": { "type": "string" }, "side": { "enum": [ "south", "east", "north", "west" ] }, "offset": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] } }, "description": "A deck, patio or bed against a side of an earlier room or rectangle: centred on it, or from its west or south end by offset." }, "doors": { "type": "array", "maxItems": 20, "items": { "type": "object", "additionalProperties": false, "required": [ "side", "offset" ], "properties": { "side": { "enum": [ "south", "east", "north", "west" ] }, "offset": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ], "description": "Along the wall from its start: walls run counter-clockwise from the south-west corner." }, "exterior": { "type": "boolean", "description": "A door: an outside door (the default) or an inside one." } } } }, "windows": { "type": "array", "maxItems": 20, "items": { "type": "object", "additionalProperties": false, "required": [ "side", "offset" ], "properties": { "side": { "enum": [ "south", "east", "north", "west" ] }, "offset": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ], "description": "Along the wall from its start: walls run counter-clockwise from the south-west corner." }, "exterior": { "type": "boolean", "description": "A door: an outside door (the default) or an inside one." } } } }, "legs": { "type": "array", "minItems": 1, "maxItems": 20, "items": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] }, "description": "A fence's straight runs, in order." }, "turns": { "type": "array", "maxItems": 19, "items": { "enum": [ "left", "right" ] }, "description": "A 90° turn between each two legs." }, "gates": { "type": "array", "maxItems": 20, "items": { "type": "object", "additionalProperties": false, "required": [ "leg", "offset", "width" ], "properties": { "leg": { "type": "integer", "minimum": 1 }, "offset": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] }, "width": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] } } }, "description": "Gate openings, by leg (from 1) and offset along it; taken out of the run, the gate itself not counted." }, "build": { "enum": [ "pavers", "concrete" ], "description": "A patio's or path's build: a patio is concrete unless pavers; a path is pavers unless concrete." }, "finishes": { "type": "object", "maxProperties": 10, "additionalProperties": { "type": "string", "maxLength": 80 } }, "scope": { "type": "object", "maxProperties": 30, "additionalProperties": { "type": [ "string", "number", "boolean" ] } }, "p": { "type": "object", "maxProperties": 20, "description": "The component's own properties: a fence's heightMm, a bed's mulchDepthMm, each length with its unit." } } }, "description": "Simple shapes the assistant has read from the reader's words — a room, a deck, a patio, a bed, a path, a fence of legs and turns — compiled into the canvas's own commands. Every length with its unit." }, "layout": { "type": "object", "additionalProperties": false, "required": [ "rooms" ], "properties": { "grid": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ], "description": "The grid every figure is snapped to (default 10 mm, or 1/2 in in US units). Each snap that changed a figure is reported." }, "rooms": { "type": "array", "minItems": 1, "maxItems": 30, "items": { "type": "object", "additionalProperties": false, "required": [ "name", "width", "depth" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 60, "description": "Unique in the layout; openings and later rooms refer to it." }, "width": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ], "description": "Along x (east), wall centre to wall centre." }, "depth": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ], "description": "Along y (north), wall centre to wall centre." }, "at": { "type": "object", "additionalProperties": false, "required": [ "x", "y" ], "properties": { "x": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] }, "y": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] } }, "description": "Its south-west corner. The first room without at or against is at the origin." }, "against": { "type": "object", "additionalProperties": false, "required": [ "room", "side" ], "properties": { "room": { "type": "string", "maxLength": 60 }, "side": { "enum": [ "south", "east", "north", "west" ] }, "align": { "enum": [ "start", "centre", "end" ], "description": "Along that side: flush with its west or south end (start, the default), centred, or flush with the other end." }, "offset": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] } }, "description": "Beside a side of an earlier room, sharing that wall." } } } }, "doors": { "type": "array", "maxItems": 60, "items": { "type": "object", "additionalProperties": false, "properties": { "room": { "type": "string", "maxLength": 60, "description": "The room it is in, by name." }, "side": { "enum": [ "south", "east", "north", "west" ], "description": "The side of that room." }, "offset": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ], "description": "Its centre along the side from the side's start (walls counter-clockwise from the south-west corner); left out, the middle." }, "between": { "type": "array", "minItems": 2, "maxItems": 2, "items": { "type": "string", "maxLength": 60 }, "description": "A door only: the two rooms it joins, on the wall they share." }, "width": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ], "description": "The opening's width; left out, the canvas's default." } } }, "description": "Each between two rooms, or in a room's side (an outside door where that side is an exterior wall)." }, "windows": { "type": "array", "maxItems": 60, "items": { "type": "object", "additionalProperties": false, "properties": { "room": { "type": "string", "maxLength": 60, "description": "The room it is in, by name." }, "side": { "enum": [ "south", "east", "north", "west" ], "description": "The side of that room." }, "offset": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ], "description": "Its centre along the side from the side's start (walls counter-clockwise from the south-west corner); left out, the middle." }, "between": { "type": "array", "minItems": 2, "maxItems": 2, "items": { "type": "string", "maxLength": 60 }, "description": "A door only: the two rooms it joins, on the wall they share." }, "width": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ], "description": "The opening's width; left out, the canvas's default." } } }, "description": "Each in a room's side, on an exterior wall." } }, "description": "Rooms by name, size and which room each stands against, laid out on a grid: shared walls drawn once as partitions, every snap or move reported, and each room checked to close." }, "template": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$", "description": "A Construction Canvas template's slug (the template index lists them: single-room, deck, two-car-garage …): the drawing its page shows, in the reader's system, with a link that opens it." }, "variant": { "type": "string", "pattern": "^[a-z0-9-]{1,40}$", "description": "With template: one of its two \"what changes if\" variants, by id; a wrong one is refused with the template's own list." }, "inputUnits": { "type": "string", "enum": [ "base" ], "description": "Send \"base\" to pass bare numbers on dimensioned inputs in base units (m, m², L, kg …), as the published test vectors are written. Without it a length, area or volume must carry its unit." } }, "description": "A Construction Canvas drawing (a template, a house form, shapes, drawing commands or a canvas document), as a project file takes it; its levels set the level-by-level order." }, "system": { "type": "string", "enum": [ "metric", "imperial" ], "default": "metric", "description": "The unit system inputs left out open in, and the one the page link opens in. The answer comes in both." }, "market": { "type": "string", "enum": [ "US", "CA", "UK", "AU", "INTL" ], "description": "Optional. A market whose own opening choice some inputs take (a UK reader's code, an IEC motor), and whose currency symbol prints the caller's own money figures." }, "crew": { "type": "integer", "minimum": 1, "maximum": 50, "default": 2, "description": "People in each trade's crew, unless named in crews." }, "crews": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 1, "maximum": 50 }, "description": "People in a trade's crew, by trade id (carpentry, drywall, electrical, roofing …)." }, "hoursPerDay": { "type": "number", "minimum": 1, "maximum": 24, "default": 8, "description": "Working hours in a crew's day." }, "startDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Optional first day (YYYY-MM-DD): the working days are then given dates and a calendar file is returned. No date is assumed without it." }, "workDays": { "type": "array", "minItems": 1, "maxItems": 7, "uniqueItems": true, "items": { "type": "integer", "minimum": 1, "maximum": 7 }, "default": [ 1, 2, 3, 4, 5 ], "description": "The days of the week worked, 1 Monday to 7 Sunday." }, "daysOff": { "type": "array", "maxItems": 400, "items": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "description": "Dates not worked (holidays, a shutdown), YYYY-MM-DD." }, "name": { "type": "string", "maxLength": 120, "description": "The project's name, for the files." } } }, "example": { "drawing": { "template": "two-storey-house" }, "crew": 2, "hoursPerDay": 8, "startDate": "2026-11-02" }, "examples": { "plan_programme": { "summary": "How long would a crew of two take to build the two-storey house template, eight-hour days, starting 2 November?", "value": { "drawing": { "template": "two-storey-house" }, "crew": 2, "hoursPerDay": 8, "startDate": "2026-11-02" } } } } } }, "responses": { "200": { "description": "The tasks, totals and files.", "content": { "application/json": { "schema": { "type": "object", "anyOf": [ { "type": "object", "required": [ "engine", "from", "project", "settings", "tasks", "totals", "trades", "leftOut", "files", "note", "overlap", "licence", "notice" ], "properties": { "engine": { "type": "object" }, "from": { "enum": [ "token", "file", "takeoffs", "drawing" ] }, "project": { "type": "object", "required": [ "name", "lines" ], "properties": { "name": { "type": "string" }, "lines": { "type": "integer" } } }, "settings": { "type": "object", "required": [ "crew", "crews", "hoursPerDay", "workDays" ], "properties": { "crew": { "type": "integer" }, "crews": { "type": "object" }, "hoursPerDay": { "type": "number" }, "workDays": { "type": "array", "items": { "type": "integer" } }, "startDate": { "type": "string" }, "daysOff": { "type": "array", "items": { "type": "string" } } } }, "tasks": { "type": "array", "items": { "type": "object", "required": [ "id", "stage", "stageName", "trade", "tradeName", "level", "items", "hours", "basis", "crew", "days", "start", "finish", "dependsOn" ], "properties": { "id": { "type": "string" }, "stage": { "type": "string" }, "stageName": { "type": "string" }, "trade": { "type": "string" }, "tradeName": { "type": "string" }, "level": { "type": [ "object", "null" ], "required": [ "id", "name" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "items": { "type": "array", "items": { "type": "string" } }, "hours": { "type": "object", "required": [ "low", "likely", "high" ], "properties": { "low": { "type": "number" }, "likely": { "type": "number" }, "high": { "type": "number" } }, "description": "Person-hours (h): the likely figure sets the duration." }, "basis": { "enum": [ "site", "yours", "both" ] }, "crew": { "type": "integer", "description": "People." }, "days": { "type": "number", "description": "Working days, in halves." }, "start": { "type": "number", "description": "Working days from the start, in halves." }, "finish": { "type": "number", "description": "Working days from the start, in halves." }, "startDate": { "type": "string", "description": "First working date (YYYY-MM-DD), with a start date." }, "endDate": { "type": "string", "description": "Last working date (YYYY-MM-DD), with a start date." }, "dependsOn": { "type": "array", "items": { "type": "string" } } } } }, "totals": { "type": "object", "required": [ "hours", "personDays", "crewDays", "elapsedDays", "tasks" ], "properties": { "hours": { "type": "object", "required": [ "low", "likely", "high" ], "properties": { "low": { "type": "number" }, "likely": { "type": "number" }, "high": { "type": "number" } } }, "personDays": { "type": "number", "description": "Person-days (d)." }, "crewDays": { "type": "number", "description": "Crew-days (d)." }, "elapsedDays": { "type": "number", "description": "Working days (d), first start to last finish." }, "tasks": { "type": "integer" }, "startDate": { "type": "string" }, "endDate": { "type": "string" } } }, "trades": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "crew" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "crew": { "type": "integer" } } } }, "levels": { "type": "array", "items": { "type": [ "object", "null" ], "required": [ "id", "name" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" } } } }, "leftOut": { "type": "object", "required": [ "noHours", "notATrade", "items" ], "properties": { "noHours": { "type": "integer" }, "notATrade": { "type": "integer" }, "items": { "type": "array", "items": { "type": "object", "required": [ "title", "why" ], "properties": { "title": { "type": "string" }, "why": { "enum": [ "no-hours", "not-a-trade" ] } } } } } }, "files": { "type": "object", "required": [ "csv" ], "properties": { "csv": { "type": "object", "required": [ "filename", "mediaType", "content" ], "properties": { "filename": { "type": "string" }, "mediaType": { "type": "string" }, "content": { "type": "string" } } }, "ics": { "type": "object", "required": [ "filename", "mediaType", "content" ], "properties": { "filename": { "type": "string" }, "mediaType": { "type": "string" }, "content": { "type": "string" } } } } }, "note": { "type": "string" }, "overlap": { "type": "string" }, "licence": { "type": "object", "required": [ "name", "url", "attribution" ], "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "attribution": { "type": "string" } } }, "notice": { "type": "string" } } }, { "type": "object", "required": [ "detail", "tool", "title", "lines", "notes", "citation", "url", "open", "more" ], "properties": { "detail": { "const": "summary" }, "tool": { "type": "string" }, "title": { "type": "string" }, "lines": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "string" } }, "description": "The result lines, as the report's table gives them." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "What a professional must decide, when to call one, a false-friend warning, that adoption is local: kept in every summary." }, "citation": { "type": "string", "description": "The one citation line, built from the answer's own data." }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "open": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "more": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } ] } } } }, "400": { "description": "The request was refused; every problem is listed.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "title", "status", "problems" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "problems": { "type": "array", "items": { "type": "object", "required": [ "input", "problem" ], "properties": { "input": { "type": "string" }, "problem": { "type": "string" }, "accepted": { "type": "array", "items": { "type": "string" } } } } }, "didYouMean": { "type": "array", "items": { "type": "string" } } } } } } }, "413": { "description": "The request was refused; every problem is listed.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "title", "status", "problems" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "problems": { "type": "array", "items": { "type": "object", "required": [ "input", "problem" ], "properties": { "input": { "type": "string" }, "problem": { "type": "string" }, "accepted": { "type": "array", "items": { "type": "string" } } } } }, "didYouMean": { "type": "array", "items": { "type": "string" } } } } } } }, "422": { "description": "The request was refused; every problem is listed.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "title", "status", "problems" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "problems": { "type": "array", "items": { "type": "object", "required": [ "input", "problem" ], "properties": { "input": { "type": "string" }, "problem": { "type": "string" }, "accepted": { "type": "array", "items": { "type": "string" } } } } }, "didYouMean": { "type": "array", "items": { "type": "string" } } } } } } } }, "tags": [ "Project files" ], "parameters": [ { "name": "detail", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "full", "summary" ], "default": "full", "description": "full (the default): the whole answer. summary: the result lines, the citation line and the page only — fewer tokens to read." }, "description": "summary: the result lines, the citation and the page only (fewer tokens); full, the default: the whole answer. A POST body may carry detail instead." }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json", "md" ] }, "description": "md: the engine's Markdown report as text/markdown (or send Accept: text/markdown); json, the default." } ] } }, "/optimise-cuts": { "post": { "operationId": "optimiseCuts", "summary": "Optimise a cut list: pieces from stock lengths, or rectangles nested on sheets", "description": "Stateless: the cut list arrives and the plan goes back. The site's own optimiser, as its cut-list tool and the Construction Canvas run it.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "kind", "pieces" ], "properties": { "kind": { "enum": [ "linear", "sheet" ], "description": "linear: lengths cut from stock lengths (studs, plates, joists, rafters, bars, trim, boards). sheet: rectangles nested on sheets (plasterboard or drywall, plywood, OSB, tiles)." }, "material": { "enum": [ "timber", "rebar", "casing", "plasterboard", "plywood", "osb", "tile" ], "description": "What is cut, for the market's stock lengths or sheet sizes, saw kerf and grain when they are left out: timber (the default for linear), rebar or casing; plasterboard (the default for sheet), plywood, OSB or tile." }, "pieces": { "type": "array", "minItems": 1, "maxItems": 200, "description": "The cut list: up to 200 lines and 3000 pieces (1500 for sheets) in all.", "items": { "type": "object", "additionalProperties": false, "required": [ "count" ], "properties": { "length": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ], "description": "linear: the finished length, with its unit." }, "width": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ], "description": "sheet: the piece's width, with its unit." }, "height": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ], "description": "sheet: the piece's height (along the grain), with its unit." }, "count": { "type": "integer", "minimum": 1, "maximum": 3000 }, "label": { "type": "string", "maxLength": 60 }, "join": { "type": "boolean", "description": "linear: a run that may be joined where a stock length runs out (a plate, a rim, trim, a board run). Left out, a piece longer than every stock length is listed, not split: a joint in a joist, a rafter or a bar is the designer's." }, "rotate": { "type": "boolean", "description": "sheet: whether this piece may turn a quarter; left out, as the request says." } } } }, "stock": { "type": "array", "minItems": 1, "maxItems": 12, "items": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] }, "description": "linear: the stock lengths on offer, each in any number, with units (\"4.8 m\", \"16 ft\"). Left out, the market's usual lengths for the material in the system asked for." }, "sheets": { "type": "array", "minItems": 1, "maxItems": 6, "items": { "type": "object", "additionalProperties": false, "required": [ "width", "height" ], "properties": { "width": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] }, "height": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ] } } }, "description": "sheet: the sheet sizes on offer (the plan takes the one that buys the least area). Left out, the market's usual size for the material." }, "kerf": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ], "description": "The saw's kerf, charged on every piece (both ways on a sheet). Left out, the material's: 3 mm or 1/8 in for a saw, none for a bar shear or a board knife." }, "minOffcut": { "oneOf": [ { "type": "number" }, { "type": "string", "maxLength": 200 }, { "type": "object", "additionalProperties": false, "required": [ "value" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "maxLength": 40 } } } ], "description": "linear: the shortest offcut worth keeping; shorter ones count as waste." }, "rotate": { "type": "boolean", "description": "sheet: whether pieces may turn a quarter (no grain or strength axis to keep). Left out: yes for plasterboard and tiles, no for plywood and OSB." }, "system": { "type": "string", "enum": [ "metric", "imperial" ], "default": "metric", "description": "The unit system inputs left out open in, and the one the page link opens in. The answer comes in both." }, "inputUnits": { "type": "string", "enum": [ "base" ], "description": "Send \"base\" to pass bare numbers on dimensioned inputs in base units (m, m², L, kg …), as the published test vectors are written. Without it a length, area or volume must carry its unit." } } }, "example": { "kind": "linear", "material": "timber", "pieces": [ { "length": "2.326 m", "count": 24, "label": "stud" }, { "length": "1.225 m", "count": 3, "label": "sill" }, { "length": "8.9 m", "count": 3, "label": "plate", "join": true } ], "stock": [ "2.4 m", "3 m", "3.6 m", "4.8 m" ], "kerf": "3 mm", "system": "metric" }, "examples": { "optimise_cuts": { "summary": "A wall's 24 studs, 3 sills and 3 plates: which lengths of timber to buy from 2.4, 3, 3.6 and 4.8 m, with a 3 mm saw?", "value": { "kind": "linear", "material": "timber", "pieces": [ { "length": "2.326 m", "count": 24, "label": "stud" }, { "length": "1.225 m", "count": 3, "label": "sill" }, { "length": "8.9 m", "count": 3, "label": "plate", "join": true } ], "stock": [ "2.4 m", "3 m", "3.6 m", "4.8 m" ], "kerf": "3 mm", "system": "metric" } } } } } }, "responses": { "200": { "description": "What to buy, the cutting plan, the waste and the bound.", "content": { "application/json": { "schema": { "type": "object", "anyOf": [ { "type": "object", "required": [ "engine", "system", "kind", "material", "given", "buy", "waste", "bound", "proven", "patterns", "patternsTotal", "notDesign", "method", "citation", "licence", "notice", "links" ], "properties": { "engine": { "type": "object" }, "system": { "enum": [ "metric", "imperial" ] }, "kind": { "enum": [ "linear", "sheet" ] }, "material": { "type": "string" }, "given": { "type": "object", "description": "What the plan was worked from, in both systems: the stock lengths or sheet sizes, the kerf, the minimum offcut, whether pieces turn." }, "buy": { "type": "array", "items": { "type": "object", "required": [ "count", "text" ], "properties": { "count": { "type": "integer" }, "stock": { "type": "object", "required": [ "m", "ft", "text" ], "properties": { "m": { "type": "number" }, "ft": { "type": "number" }, "text": { "type": "string", "description": "In the system asked for, then the other." } } }, "sheet": { "type": "object" }, "text": { "type": "string" } } }, "description": "What to buy: each stock length or the sheet size, and how many." }, "pieces": { "type": "integer" }, "bought": { "anyOf": [ { "type": "object", "required": [ "m", "ft", "text" ], "properties": { "m": { "type": "number" }, "ft": { "type": "number" }, "text": { "type": "string", "description": "In the system asked for, then the other." } } }, { "type": "object", "required": [ "m2", "ft2", "text" ], "properties": { "m2": { "type": "number" }, "ft2": { "type": "number" }, "text": { "type": "string" } } } ] }, "required": { "anyOf": [ { "type": "object", "required": [ "m", "ft", "text" ], "properties": { "m": { "type": "number" }, "ft": { "type": "number" }, "text": { "type": "string", "description": "In the system asked for, then the other." } } }, { "type": "object", "required": [ "m2", "ft2", "text" ], "properties": { "m2": { "type": "number" }, "ft2": { "type": "number" }, "text": { "type": "string" } } } ] }, "waste": { "type": "object", "required": [ "percent" ], "properties": { "percent": { "type": "number" }, "excludingKeptOffcutsPercent": { "type": "number" }, "keptOffcut": { "type": "object", "required": [ "m", "ft", "text" ], "properties": { "m": { "type": "number" }, "ft": { "type": "number" }, "text": { "type": "string", "description": "In the system asked for, then the other." } } } } }, "bound": { "type": "object", "required": [ "wastePercent" ], "description": "The floor no plan can beat: the pieces with their kerf over the stock (with one stock length, at least one bar for each piece over half a bar; on sheets, one sheet for each piece too big to share one)." }, "gapPercent": { "type": "number", "description": "How far this plan is above the bound, percent." }, "proven": { "type": "boolean", "description": "True when no plan buys less: the exact branch and bound finished, or the plan meets the bound." }, "patterns": { "type": "array", "items": { "anyOf": [ { "type": "object", "required": [ "times", "stock", "cuts", "offcut", "keep" ], "properties": { "times": { "type": "integer" }, "stock": { "type": "object", "required": [ "m", "ft", "text" ], "properties": { "m": { "type": "number" }, "ft": { "type": "number" }, "text": { "type": "string", "description": "In the system asked for, then the other." } } }, "cuts": { "type": "array", "items": { "type": "object", "required": [ "length" ], "properties": { "length": { "type": "object", "required": [ "m", "ft", "text" ], "properties": { "m": { "type": "number" }, "ft": { "type": "number" }, "text": { "type": "string", "description": "In the system asked for, then the other." } } }, "label": { "type": "string" }, "joined": { "type": "boolean" } } } }, "offcut": { "type": "object", "required": [ "m", "ft", "text" ], "properties": { "m": { "type": "number" }, "ft": { "type": "number" }, "text": { "type": "string", "description": "In the system asked for, then the other." } } }, "keep": { "type": "boolean" } } }, { "type": "object", "required": [ "times", "placed" ], "properties": { "times": { "type": "integer" }, "placed": { "type": "array", "items": { "type": "object", "required": [ "x", "y", "width", "height", "rotated" ], "properties": { "x": { "type": "object", "required": [ "m", "ft", "text" ], "properties": { "m": { "type": "number" }, "ft": { "type": "number" }, "text": { "type": "string", "description": "In the system asked for, then the other." } } }, "y": { "type": "object", "required": [ "m", "ft", "text" ], "properties": { "m": { "type": "number" }, "ft": { "type": "number" }, "text": { "type": "string", "description": "In the system asked for, then the other." } } }, "width": { "type": "object", "required": [ "m", "ft", "text" ], "properties": { "m": { "type": "number" }, "ft": { "type": "number" }, "text": { "type": "string", "description": "In the system asked for, then the other." } } }, "height": { "type": "object", "required": [ "m", "ft", "text" ], "properties": { "m": { "type": "number" }, "ft": { "type": "number" }, "text": { "type": "string", "description": "In the system asked for, then the other." } } }, "rotated": { "type": "boolean" }, "label": { "type": "string" } } } }, "largestOffcut": { "type": "object" } } } ] }, "description": "Each way a bar or sheet is cut, with how many are cut that way; up to 150, most used first." }, "patternsTotal": { "type": "integer" }, "tooLong": { "type": "array", "items": { "type": "object" }, "description": "Pieces no stock length or sheet takes, listed rather than split." }, "joinedRuns": { "type": "integer" }, "steps": { "type": "integer", "description": "Search steps spent (bounded)." }, "method": { "type": "array", "items": { "type": "string" } }, "notDesign": { "type": "string" }, "citation": { "type": "object", "required": [ "author", "title", "url", "formats", "accessDate" ], "properties": { "author": { "type": "string" }, "title": { "type": "string" }, "version": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sourcesChecked": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "url": { "type": "string" }, "accessDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "formats": { "type": "object", "required": [ "plain", "apa", "harvard", "bibtex" ], "properties": { "plain": { "type": "string" }, "apa": { "type": "string" }, "harvard": { "type": "string" }, "bibtex": { "type": "string" } } } } }, "licence": { "type": "object", "required": [ "name", "url", "attribution" ], "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "attribution": { "type": "string" } } }, "notice": { "type": "string" }, "links": { "type": "object", "required": [ "page" ], "properties": { "page": { "type": "string" } } } } }, { "type": "object", "required": [ "detail", "tool", "title", "lines", "notes", "citation", "url", "open", "more" ], "properties": { "detail": { "const": "summary" }, "tool": { "type": "string" }, "title": { "type": "string" }, "lines": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "string" } }, "description": "The result lines, as the report's table gives them." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "What a professional must decide, when to call one, a false-friend warning, that adoption is local: kept in every summary." }, "citation": { "type": "string", "description": "The one citation line, built from the answer's own data." }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "open": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "more": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } ] } } } }, "400": { "description": "The request was refused; every problem is listed.", "content": { "application/problem+json": { "schema": { "type": "object", "required": [ "title", "status", "problems" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "problems": { "type": "array", "items": { "type": "object", "required": [ "input", "problem" ], "properties": { "input": { "type": "string" }, "problem": { "type": "string" }, "accepted": { "type": "array", "items": { "type": "string" } } } } }, "didYouMean": { "type": "array", "items": { "type": "string" } } } } } } } }, "tags": [ "Calculators" ], "parameters": [ { "name": "detail", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "full", "summary" ], "default": "full", "description": "full (the default): the whole answer. summary: the result lines, the citation line and the page only — fewer tokens to read." }, "description": "summary: the result lines, the citation and the page only (fewer tokens); full, the default: the whole answer. A POST body may carry detail instead." }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json", "md" ] }, "description": "md: the engine's Markdown report as text/markdown (or send Accept: text/markdown); json, the default." } ] } } }, "tags": [ { "name": "Discovery", "description": "Find a calculator, takeoff or worked example by what the job is." }, { "name": "Calculators", "description": "One calculator: what it asks, its answer in both systems, its sources and a link to its page." }, { "name": "Units", "description": "Conversions by the exact factors the calculators use." }, { "name": "Takeoffs", "description": "A whole job worked row by row, as its takeoff page works it." }, { "name": "Worked examples", "description": "The site's published examples, re-run now against their pinned figures." }, { "name": "Planner", "description": "The room-by-room planner: one space, or several and a roof." }, { "name": "House and canvas", "description": "The House Estimator and the Construction Canvas: a drawn house and everything it is built from, a sketch measured from its points, a drawing as DXF and SVG, and a reinforcement layout." }, { "name": "Quotes", "description": "A contractor's quote read against the job; the reader's own quote turned into a project." }, { "name": "Project files", "description": "A My Project file the reader restores on the site. Nothing is stored." }, { "name": "Solve backwards", "description": "What the material the reader already has will cover, as the site's Solve Backwards pages work it." }, { "name": "Diagnoses and documents", "description": "Faults by symptom, the documents each market uses, and trade words across markets." }, { "name": "Benchmark", "description": "The Construction Quantities Benchmark: the calculators' test vectors as questions in both unit systems, with their answers, CC BY 4.0." }, { "name": "Agent tools", "description": "Many calculations in one request, a project changed through its state token, a list grouped by MasterFormat division, and permanent ids." } ] }