---
title: "Run a calculator"
method: POST
path: "/calculate/{slug}"
tags: ["Calculators"]
---

# Run a calculator

`POST /calculate/{slug}`

## Request

- Base URL: `https://api.craftquantities.com/v1`
- URL: `https://api.craftquantities.com/v1/calculate/{slug}`
- Auth: none declared

## Path parameters

- `slug` string, required: The calculator's slug, such as concrete-calculator.

## Query parameters

- `detail` 'full' | 'summary': full (the default): the whole answer. summary: the result lines, the citation line and the page only — fewer tokens to read.
- `format` 'json' | 'md'

## Request body

- object
  - `inputs` object: 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.
  - `system` 'metric' | 'imperial': The unit system inputs left out open in, and the one the page link opens in. The answer comes in both.
  - `market` 'US' | 'CA' | 'UK' | 'AU' | 'INTL': 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` 'base': 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` boolean: 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.

## Response `200`

The answer in both systems, with its inputs, sources and citation.

- union
  - object
    - `engine` object, required
      - `name` string, required
      - `version` string, required
      - `api` string, required
    - `calculator` object, required
      - `slug` string, required
      - `title` string, required
      - `category` string, required
      - `description` string
      - `version` string, required: The calculator's own version; a result names the calculator that produced it.
      - `lastVerified` string, required: The date the calculator's sources were last checked.
      - `url` string, required: The calculator's page on craftquantities.com.
      - `json` string, required: The calculator's static API document, with its test vectors.
    - `system` 'metric' | 'imperial', required
    - `market` string, nullable
    - `inputs` object[], required: Every input the calculation ran on, and where each came from.
      - `id` string, required
      - `label` string, required
      - `type` 'number' | 'select', required
      - `value` union, required
        - number
        - string
      - `dimension` string
      - `baseUnit` string
      - `source` 'caller' | 'default', required
      - `read` string
      - `metric` object
        - `value` number, required
        - `unit` string, required
      - `imperial` object
        - `value` number, required
        - `unit` string, required
      - `option` string
    - `result` object, required
      - `label` string, required
      - `metric` object, required
        - `value` number, nullable, required: The headline in this system; null where a rate it needs is not given.
        - `unit` string, required
        - `printed` string, nullable, required: The headline exactly as the page prints it.
        - `breakdown` object[], required
          - `label` string, required
          - `value` number, nullable, required
          - `unit` string, required
          - `printed` string, required
        - `confidence` 'high' | 'medium' | 'low', required
        - `confidenceNote` string, nullable
        - `allowance` object, nullable
          - `label` string
          - `percent` number
          - `base` number
        - `limitations` string[]
        - `isComparison` boolean, required: The figure is set against a limit. It is not an approval.
        - `withheld` object, nullable
          - `missingRates` object[]
            - `input` string
            - `label` string
        - `canonical` object, required: The figure in the calculator's own unit, before the display adapter: what its test vectors pin.
          - `value` number, nullable, required
          - `unit` string, required
      - `imperial` object, required
        - `value` number, nullable, required: The headline in this system; null where a rate it needs is not given.
        - `unit` string, required
        - `printed` string, nullable, required: The headline exactly as the page prints it.
        - `breakdown` object[], required
          - `label` string, required
          - `value` number, nullable, required
          - `unit` string, required
          - `printed` string, required
        - `confidence` 'high' | 'medium' | 'low', required
        - `confidenceNote` string, nullable
        - `allowance` object, nullable
          - `label` string
          - `percent` number
          - `base` number
        - `limitations` string[]
        - `isComparison` boolean, required: The figure is set against a limit. It is not an approval.
        - `withheld` object, nullable
          - `missingRates` object[]
            - `input` string
            - `label` string
        - `canonical` object, required: The figure in the calculator's own unit, before the display adapter: what its test vectors pin.
          - `value` number, nullable, required
          - `unit` string, required
    - `sources` object[], required
      - `label` string, required: The source as the calculator cites it.
      - `url` string: Only where the calculator gives one; none is invented.
      - `references` object[]
        - `kind` 'code' | 'standard', required
        - `body` string
        - `document` string, required
        - `section` string
        - `edition` string
    - `citation` object, required
      - `author` string, required
      - `title` string, required
      - `version` string, nullable
      - `sourcesChecked` string, nullable
      - `url` string, required
      - `accessDate` string, nullable, required
      - `formats` object, required
        - `plain` string, required
        - `apa` string, required
        - `harvard` string, required
        - `bibtex` string, required
    - `links` object, required
      - `page` string, required
      - `open` string, required: Opens the page on these inputs.
    - `licence` object, required
      - `name` string, required
      - `url` string, required
      - `attribution` string, required
    - `notice` string, required
    - `explain` object: Only when explain is true. Each figure is the calculator's own; no step is a formula written for the engine.
      - `about` string, required
      - `coverage` 'intermediates' | 'result-only', required: result-only: the calculator reports no figures between its inputs and its result.
      - `steps` object[], required
        - `n` integer, required
        - `kind` 'input' | 'intermediate' | 'result' | 'allowance' | 'range' | 'rates' | 'display', required
        - `system` 'metric' | 'imperial' | 'both', required
        - `label` string, required
        - `value` union
          - number
          - string
        - `unit` string: The calculator's own (base) unit for the value.
        - `metric` object
          - `value` number, nullable, required
          - `unit` string, required
        - `imperial` object
          - `value` number, nullable, required
          - `unit` string, required
        - `movedBy` string[]: Input ids whose change moved this figure, measured by running compute again.
        - `source` 'caller' | 'default'
        - `text` string, required: The step in words.
      - `final` object, required: The figures the answer returns, copied from it.
        - `metric` object, required
          - `value` number, nullable, required
          - `unit` string, required
          - `printed` string, nullable, required
        - `imperial` object, required
          - `value` number, nullable, required
          - `unit` string, required
          - `printed` string, nullable, required
      - `limits` string[], required: What the trace does not show, and why.
  - object
    - `detail` 'summary', required
    - `tool` string, required
    - `title` string, required
    - `lines` object[], required: The result lines, as the report's table gives them.
    - `notes` string[], required: What a professional must decide, when to call one, a false-friend warning, that adoption is local: kept in every summary.
    - `citation` string, required: The one citation line, built from the answer's own data.
    - `url` string, nullable, required
    - `open` string, nullable, required
    - `more` string, nullable, required

## Other responses

- `400`: The request was refused; every problem is listed.
- `404`: The request was refused; every problem is listed.
- `413`: The request was refused; every problem is listed.

---

[API](https://skmtc.dev/craftquantities/apis/craft-quantities-engine-api.md) · [All operations](https://skmtc.dev/craftquantities/apis/craft-quantities-engine-api/llms.txt) · [OpenAPI document](https://skmtc.dev/craftquantities/apis/craft-quantities-engine-api/revisions/a69883abc23b?raw)