---
title: "A build programme from a project's labour hours: tasks by trade, stage and level, working days, CSV and calendar"
method: POST
path: "/programme"
tags: ["Project files"]
---

# A build programme from a project's labour hours: tasks by trade, stage and level, working days, CSV and calendar

`POST /programme`

## Request

- Base URL: `https://api.craftquantities.com/v1`
- URL: `https://api.craftquantities.com/v1/programme`
- Auth: none declared

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.

## 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
  - `token` string: A project state token (cqp1.…) from a project-file answer or an update: the project whose lines are put in order.
  - `file` object: 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` object[]: Whole-job takeoffs, each an id and its measurements, as a project file takes them.
    - `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.
  - `drawing` object: 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.
    - `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.
  - `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.
  - `crew` integer: People in each trade's crew, unless named in crews.
  - `crews` object: People in a trade's crew, by trade id (carpentry, drywall, electrical, roofing …).
  - `hoursPerDay` number: Working hours in a crew's day.
  - `startDate` string: 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` integer[]: The days of the week worked, 1 Monday to 7 Sunday.
  - `daysOff` string[]: Dates not worked (holidays, a shutdown), YYYY-MM-DD.
  - `name` string: The project's name, for the files.

## Response `200`

The tasks, totals and files.

- union
  - object
    - `engine` object, required
    - `from` 'token' | 'file' | 'takeoffs' | 'drawing', required
    - `project` object, required
      - `name` string, required
      - `lines` integer, required
    - `settings` object, required
      - `crew` integer, required
      - `crews` object, required
      - `hoursPerDay` number, required
      - `workDays` integer[], required
      - `startDate` string
      - `daysOff` string[]
    - `tasks` object[], required
      - `id` string, required
      - `stage` string, required
      - `stageName` string, required
      - `trade` string, required
      - `tradeName` string, required
      - `level` object, nullable, required
        - `id` string, required
        - `name` string, required
      - `items` string[], required
      - `hours` object, required: Person-hours (h): the likely figure sets the duration.
        - `low` number, required
        - `likely` number, required
        - `high` number, required
      - `basis` 'site' | 'yours' | 'both', required
      - `crew` integer, required: People.
      - `days` number, required: Working days, in halves.
      - `start` number, required: Working days from the start, in halves.
      - `finish` number, required: Working days from the start, in halves.
      - `startDate` string: First working date (YYYY-MM-DD), with a start date.
      - `endDate` string: Last working date (YYYY-MM-DD), with a start date.
      - `dependsOn` string[], required
    - `totals` object, required
      - `hours` object, required
        - `low` number, required
        - `likely` number, required
        - `high` number, required
      - `personDays` number, required: Person-days (d).
      - `crewDays` number, required: Crew-days (d).
      - `elapsedDays` number, required: Working days (d), first start to last finish.
      - `tasks` integer, required
      - `startDate` string
      - `endDate` string
    - `trades` object[], required
      - `id` string, required
      - `name` string, required
      - `crew` integer, required
    - `levels` object[]
      - `id` string, required
      - `name` string, required
    - `leftOut` object, required
      - `noHours` integer, required
      - `notATrade` integer, required
      - `items` object[], required
        - `title` string, required
        - `why` 'no-hours' | 'not-a-trade', required
    - `files` object, required
      - `csv` object, required
        - `filename` string, required
        - `mediaType` string, required
        - `content` string, required
      - `ics` object
        - `filename` string, required
        - `mediaType` string, required
        - `content` string, required
    - `note` string, required
    - `overlap` string, required
    - `licence` object, required
      - `name` string, required
      - `url` string, required
      - `attribution` string, required
    - `notice` 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.
- `422`: 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)