---
title: "A My Project file from calculators and takeoffs"
method: POST
path: "/my-project-file"
tags: ["Project files"]
---

# A My Project file from calculators and takeoffs

`POST /my-project-file`

## Request

- Base URL: `https://api.craftquantities.com/v1`
- URL: `https://api.craftquantities.com/v1/my-project-file`
- Auth: none declared

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.

## Query parameters

- `download` '1'
- `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
  - `name` string
  - `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.
  - `calculators` object[]
    - `slug` string, required: The calculator's slug, such as concrete-calculator.
    - `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.
    - `label` string: The line's name in the project; the calculator's title when left out.
    - `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.
  - `takeoffs` object[]
    - `takeoff` string, required
    - `measurements` object: 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.
    - `selection` object: 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.
    - `allowances` object: 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).
    - `leaveOut` string[]: Rows the reader leaves out of the job: still worked and shown, not put in the project or counted in labour.
    - `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.
  - `houses` object[]
    - `example` string: Start from one of the site's example houses (its slug) in place of the estimator's opening house.
    - `values` object: 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.
    - `storeys` 1 | 2
    - `family` 'wall.framed-exterior' | 'wall.masonry' | 'wall.sip'
    - `selection` object: The exterior wall's build-up choices.
    - `pitch` '4' | '6' | '8' | '10' | '12': Roof pitch, rise in 12.
    - `roofFamily` 'roof.asphalt-shingle' | 'roof.tile-slate'
    - `roofSelection` object
    - `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.
  - `plan` object: One planned space as plan_room takes it, or a whole project (spaces, roof) as plan_project takes it.
    - `kind` 'room' | 'bathroom' | 'slab' | 'deck' | 'driveway' | 'fence' | 'loft' | 'retaining-wall' | 'exterior-wall' | 'stair': 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` object: 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 …).
    - `doors` object
      - `count` integer
      - `width` union
        - number
        - string
        - object
          - `value` number, required
          - `unit` string
      - `height` union
        - number
        - string
        - object
          - `value` number, required
          - `unit` string
    - `windows` object
      - `count` integer
      - `width` union
        - number
        - string
        - object
          - `value` number, required
          - `unit` string
      - `height` union
        - number
        - string
        - object
          - `value` number, required
          - `unit` string
    - `finishes` object: Surface role → finish id, by the planner's ids.
    - `scope` object: Scope question name → answer value, by the planner's ids.
    - `intent` string: A trade, or everything.
    - `leaveOut` string[]: Branch ids to leave out.
    - `inputs` object: Branch id → { calculator input id: value in its base unit }.
    - `name` string
    - `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.
    - `spaces` object[]: The spaces, in order, each one planned space.
      - `kind` 'room' | 'bathroom' | 'slab' | 'deck' | 'driveway' | 'fence' | 'loft' | 'retaining-wall' | 'exterior-wall' | 'stair', required: 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` object, required: 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 …).
      - `doors` object
        - `count` integer
        - `width` union
          - number
          - string
          - object
            - `value` number, required
            - `unit` string
        - `height` union
          - number
          - string
          - object
            - `value` number, required
            - `unit` string
      - `windows` object
        - `count` integer
        - `width` union
          - number
          - string
          - object
            - `value` number, required
            - `unit` string
        - `height` union
          - number
          - string
          - object
            - `value` number, required
            - `unit` string
      - `finishes` object: Surface role → finish id, by the planner's ids.
      - `scope` object: Scope question name → answer value, by the planner's ids.
      - `intent` string: A trade, or everything.
      - `leaveOut` string[]: Branch ids to leave out.
      - `inputs` object: Branch id → { calculator input id: value in its base unit }.
      - `name` string
    - `roof` object
      - `pitch` number: The rise per 12 of run (6 = 6 in 12). Left out, each roof row says it waits for the pitch.
      - `finishes` object: Surface role → finish id, by the planner's ids.
      - `scope` object: Scope question name → answer value, by the planner's ids.
      - `intent` string: A trade, or everything.
      - `leaveOut` string[]: Branch ids to leave out.
      - `inputs` object: Branch id → { calculator input id: value in its base unit }.
  - `drawing` object: A drawing as create_drawing takes it; the file carries the drawing itself, which the canvas reopens.
    - `house` object: The House Estimator's form: the house drawn as the estimator draws it.
      - `example` string: Start from one of the site's example houses (its slug) in place of the estimator's opening house.
      - `values` object: 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.
      - `storeys` 1 | 2
      - `family` 'wall.framed-exterior' | 'wall.masonry' | 'wall.sip'
      - `selection` object: The exterior wall's build-up choices.
      - `pitch` '4' | '6' | '8' | '10' | '12': Roof pitch, rise in 12.
      - `roofFamily` 'roof.asphalt-shingle' | 'roof.tile-slate'
      - `roofSelection` object
    - `commands` object[]: 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.
      - `op` 'level' | 'type' | 'wall' | 'opening' | 'room' | 'outline' | 'path' | 'point' | 'beam' | 'stair', required
      - `ref` string: A name by which later commands refer to what this one makes.
      - `name` string: A level's, a type's or a room's name.
      - `level` string: 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` string: 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` string: The wall an opening goes in: its ref.
      - `c` string: 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` 'door' | 'window'
      - `assembly` string: A type's build-up: a canvas assembly id (wall.framed-exterior, roof.asphalt-shingle, slab.on-grade …).
      - `selection` object
      - `thickness` union
        - number
        - string
        - object
          - `value` number, required
          - `unit` string
      - `wastePercent` number
      - `elevation` union
        - number
        - string
        - object
          - `value` number, required
          - `unit` string
      - `height` union
        - number
        - string
        - object
          - `value` number, required
          - `unit` string
      - `from` object: A point on plan, each coordinate a length with its unit.
        - `x` union, required
          - number
          - string
          - object
            - `value` number, required
            - `unit` string
        - `y` union, required
          - number
          - string
          - object
            - `value` number, required
            - `unit` string
      - `to` object: A point on plan, each coordinate a length with its unit.
        - `x` union, required
          - number
          - string
          - object
            - `value` number, required
            - `unit` string
        - `y` union, required
          - number
          - string
          - object
            - `value` number, required
            - `unit` string
      - `at` object: A point on plan, each coordinate a length with its unit.
        - `x` union, required
          - number
          - string
          - object
            - `value` number, required
            - `unit` string
        - `y` union, required
          - number
          - string
          - object
            - `value` number, required
            - `unit` string
      - `offset` union: An opening's centre, measured along its wall from the wall's start.
        - number
        - string
        - object
          - `value` number, required
          - `unit` string
      - `points` object[]
        - `x` union, required
          - number
          - string
          - object
            - `value` number, required
            - `unit` string
        - `y` union, required
          - number
          - string
          - object
            - `value` number, required
            - `unit` string
      - `closed` boolean
      - `p` object: 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` object: 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` object: Its scope question name → answer, by the planner's ids.
    - `document` object: A Construction Canvas document (schema 1 to the canvas's current), opened and checked by the canvas's own opener.
    - `shapes` object[]: 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.
      - `shape` 'room' | 'deck' | 'patio' | 'bed' | 'path' | 'fence', required: 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` string: A name a later shape's against uses.
      - `name` string: A room's name.
      - `at` object: The south-west corner (a path's or a fence's start). Left out: the origin.
        - `x` union, required
          - number
          - string
          - object
            - `value` number, required
            - `unit` string
        - `y` union, required
          - number
          - string
          - object
            - `value` number, required
            - `unit` string
      - `width` union: Along x (east): a room's, deck's, patio's or bed's; a path's width across it.
        - number
        - string
        - object
          - `value` number, required
          - `unit` string
      - `depth` union: Along y (north); for a deck or patio against a side, out from it.
        - number
        - string
        - object
          - `value` number, required
          - `unit` string
      - `length` union: A path's length.
        - number
        - string
        - object
          - `value` number, required
          - `unit` string
      - `heading` 'south' | 'east' | 'north' | 'west': The way a path or a fence's first leg runs (default east).
      - `against` object: 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.
        - `shape` string, required
        - `side` 'south' | 'east' | 'north' | 'west', required
        - `offset` union
          - number
          - string
          - object
            - `value` number, required
            - `unit` string
      - `doors` object[]
        - `side` 'south' | 'east' | 'north' | 'west', required
        - `offset` union, required: Along the wall from its start: walls run counter-clockwise from the south-west corner.
          - number
          - string
          - object
            - `value` number, required
            - `unit` string
        - `exterior` boolean: A door: an outside door (the default) or an inside one.
      - `windows` object[]
        - `side` 'south' | 'east' | 'north' | 'west', required
        - `offset` union, required: Along the wall from its start: walls run counter-clockwise from the south-west corner.
          - number
          - string
          - object
            - `value` number, required
            - `unit` string
        - `exterior` boolean: A door: an outside door (the default) or an inside one.
      - `legs` union[]: A fence's straight runs, in order.
        - union
          - number
          - string
          - object
            - `value` number, required
            - `unit` string
      - `turns` string[]: A 90° turn between each two legs.
      - `gates` object[]: Gate openings, by leg (from 1) and offset along it; taken out of the run, the gate itself not counted.
        - `leg` integer, required
        - `offset` union, required
          - number
          - string
          - object
            - `value` number, required
            - `unit` string
        - `width` union, required
          - number
          - string
          - object
            - `value` number, required
            - `unit` string
      - `build` 'pavers' | 'concrete': A patio's or path's build: a patio is concrete unless pavers; a path is pavers unless concrete.
      - `finishes` object
      - `scope` object
      - `p` object: The component's own properties: a fence's heightMm, a bed's mulchDepthMm, each length with its unit.
    - `layout` object: 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.
      - `grid` union: 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.
        - number
        - string
        - object
          - `value` number, required
          - `unit` string
      - `rooms` object[], required
        - `name` string, required: Unique in the layout; openings and later rooms refer to it.
        - `width` union, required: Along x (east), wall centre to wall centre.
          - number
          - string
          - object
            - `value` number, required
            - `unit` string
        - `depth` union, required: Along y (north), wall centre to wall centre.
          - number
          - string
          - object
            - `value` number, required
            - `unit` string
        - `at` object: Its south-west corner. The first room without at or against is at the origin.
          - `x` union, required
            - number
            - string
            - object
              - …
          - `y` union, required
            - number
            - string
            - object
              - …
        - `against` object: Beside a side of an earlier room, sharing that wall.
          - `room` string, required
          - `side` 'south' | 'east' | 'north' | 'west', required
          - `align` 'start' | 'centre' | 'end': Along that side: flush with its west or south end (start, the default), centred, or flush with the other end.
          - `offset` union
            - number
            - string
            - object
              - …
      - `doors` object[]: Each between two rooms, or in a room's side (an outside door where that side is an exterior wall).
        - `room` string: The room it is in, by name.
        - `side` 'south' | 'east' | 'north' | 'west': The side of that room.
        - `offset` union: Its centre along the side from the side's start (walls counter-clockwise from the south-west corner); left out, the middle.
          - number
          - string
          - object
            - `value` number, required
            - `unit` string
        - `between` string[]: A door only: the two rooms it joins, on the wall they share.
        - `width` union: The opening's width; left out, the canvas's default.
          - number
          - string
          - object
            - `value` number, required
            - `unit` string
      - `windows` object[]: Each in a room's side, on an exterior wall.
        - `room` string: The room it is in, by name.
        - `side` 'south' | 'east' | 'north' | 'west': The side of that room.
        - `offset` union: Its centre along the side from the side's start (walls counter-clockwise from the south-west corner); left out, the middle.
          - number
          - string
          - object
            - `value` number, required
            - `unit` string
        - `between` string[]: A door only: the two rooms it joins, on the wall they share.
        - `width` union: The opening's width; left out, the canvas's default.
          - number
          - string
          - object
            - `value` number, required
            - `unit` string
    - `template` string: 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` string: With template: one of its two "what changes if" variants, by id; a wrong one is refused with the template's own list.
    - `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.

## Response `200`

The file, what it holds and its state token.

- union
  - object
    - `engine` object, required
    - `file` object, required
      - `filename` string, required
      - `mediaType` 'application/json', required
      - `content` object, required
        - `magic` 'craftquantities.backup', required
        - `v` integer, required
        - `exportedAt` string, required
        - `stores` object, required
    - `project` object, required
      - `name` string, required
      - `system` 'metric' | 'imperial', required
      - `lines` object[], required
    - `drawing` object
      - `carried` boolean, required
      - `note` string
    - `howToImport` string, required
    - `licence` object, required
      - `name` string, required
      - `url` string, required
      - `attribution` string, required
    - `notice` string, required
    - `state` object
      - `token` string, nullable, required: 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.
      - `format` string, required: The token's format and version.
      - `characters` integer
      - `link` string: Opens the project on the site from the token, carried in the address fragment, which a browser does not send to any server.
      - `note` string, required
  - 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.
- `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)