InstantTakeoff API (v1)

Upload a lighting drawing set, let the takeoff run, then read counts per fixture type per sheet, the priced estimate and Excel or CSV exports.

• Base URL: https://app.instanttakeoff.ai/api/v1
• OpenAPI: [https://app.instanttakeoff.ai/api/v1/openapi.json](/api/v1/openapi.json)
• MCP connector for Claude, ChatGPT and other assistants: see the connector guide.

v1 is stable: fields may be added, never renamed or removed. Page numbers are 1-based, like a PDF viewer.

Authentication

Create an API key in the app under Team and billing, API keys. The key is shown once; store it like a password. Send it on every request:

Authorization: Bearer itk_...

A key belongs to one member and one company and acts as that member. It stops working when it is revoked, when it expires, or when the member leaves the company. Owners and admins can see and revoke every member's keys.

Scopes: a key is either read (look at projects, results and estimates, make export links) or read and write (also create projects, upload drawing sets and start takeoffs).

Billing rules are the app's: a company on its free trial can change only its free trial project, and a view-only company can still read and export. A write that is not allowed answers 402 with payment_required, trial_limit or read_only.

Quick start

KEY=itk_your_key
API=https://app.instanttakeoff.ai/api/v1

# 1. a project
curl -s -X POST $API/projects -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" -d '{"name": "Riverside Clinic"}'

# 2a. upload from a link (the server downloads it; poll the job)
curl -s -X POST $API/projects/$PROJECT/uploads/from-url -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" -d '{"url": "https://files.example.com/plans.pdf"}'

# 2b. or upload the file in parts
curl -s -X POST $API/projects/$PROJECT/uploads -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" -d '{"filename": "plans.pdf", "bytes": 48213004}'
#   -> {"id": UPLOAD, "part_size": 33554432, "parts": 2, ...}
curl -s -X PUT $API/uploads/$UPLOAD/parts/1 -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/octet-stream" --data-binary @part1
curl -s -X PUT $API/uploads/$UPLOAD/parts/2 -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/octet-stream" --data-binary @part2
curl -s -X POST $API/uploads/$UPLOAD/complete -H "Authorization: Bearer $KEY"
#   -> {"set_id": SET, "job_id": ..., "duplicate": false}

# 3. wait until the stage is "ready"
curl -s $API/sets/$SET -H "Authorization: Bearer $KEY"

# 4. counts per type per sheet, the estimate, an Excel link
curl -s $API/sets/$SET/results -H "Authorization: Bearer $KEY"
curl -s $API/sets/$SET/estimate -H "Authorization: Bearer $KEY"
curl -s -X POST $API/sets/$SET/exports -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" -d '{"format": "xlsx"}'

Split the file into parts of exactly part_size bytes (the last part is shorter), for example with split -b 33554432 plans.pdf part. The same file uploaded twice to one company returns the existing drawing set ("duplicate": true).

The takeoff

Completing an upload starts everything on its own. GET /sets/{set_id} reports the stage:

To count more sheets, look them up with GET /sets/{set_id}/pages and send POST /sets/{set_id}/takeoff with {"page_numbers": [12, 13]}. {"all_pages": true} checks every page, not only the electrical ones.

The model counts every fixture, exit sign and lighting control on the chosen sheets and types each one from its tag against the fixture schedule. The model keeps improving and is checked against a held-out test set. Every count is a box the estimator can open and check in the app; untagged in the results is the number of counted symbols with no type tag beside them, worth a look before bidding.

After the count, a review layer double-checks every sheet. GET /projects/{project_id}/review reports it: summary (e.g. "Review: 3 of 5 sheets reviewed"), and per sheet the lines the app shows (the quick pass, the checks, what is being re-examined now, the fixtures it found and added, the corrections applied), corrections counts once reviewed, and undo: the groups of added boxes that can still be taken back in the app.

Endpoints

Pricing, bids and proposals

GET /sets/{set_id}/estimate prices every line the way the app does: a price typed in the app, else the project's selected vendor quote, else the matched price list line; labor hours from the line's labor unit unless typed. Each item says where its price came from (material_source, price_item, labor_unit), and bid holds the totals with markups and the warnings.

Assemblies

An assembly is a fixture plus the parts that go with it (a whip, a box, connectors, supports...), priced as one unit. Each part is a price list line (item_id) or a typed item (description, unit, price), with a quantity per fixture (qty) and labor hours per part (hours). A fixture type of an estimate uses the assembly picked for it in the project, else one remembered for its catalog #, else the first rule that fits: a type tag, a word or phrase of the schedule description, or the fixture kind (used_for: {tags, words, kinds}). The parts are added to every counted fixture of the type.

In GET /sets/{set_id}/estimate, an item that uses an assembly has assembly (its name, chosen_by, per_fixture, the fixture's own totals and every part's quantity, material and labor). material_each and labor_hours_each stay the fixture's own; material_total, labor_hours, labor_total and line_total include the parts, so the bid totals, markups and proposals include them too. The Excel export adds an Assemblies sheet (the fixture row and the part rows of every type that uses an assembly), and the CSV the same table at the end. PUT /projects/{project_id}/pricing takes use_assemblies: false to price a bid without them.

The starter assemblies are starting points: round quantities and labor hours to replace with your own, and no prices until their parts are linked to your price list or given a price. A company holds at most 200 assemblies of at most 30 parts each.

Export links work for a few minutes, need no Authorization header, and stop working when the key that made them is revoked. Share them only with people who may see the estimate.

Errors and limits

Errors are JSON: {"detail": "..."} or {"detail": {"error": "...", "message": "..."}}.

Rate limits apply per key and per company, per minute and per day.