API Documentation

All projects of the account, as an array of project objects, optionally paged with ?limit= and ?offset=. GET /projects/{clientId} returns the same shape filtered to one client; an unknown client yields [].

Create a project for an existing client. Answers 200 with the created project and writes a created entry to its history.

POST /project
{
  "name": "Henderson Residence",
  "clientId": 7,
  "tags": ["gunite", "2026"],
  "variables": {
    "shape": "rectangle",
    "length": 32,
    "width": 16,
    "depthProfileType": "standard",
    "shallowDepth": 3.5,
    "deepDepth": 8,
    "shallowEndLength": 10,
    "deepEndLength": 8
  }
}

Partial update. Send only the fields to change; each one you send replaces the stored value (the model and the tag list are replaced whole, not merged). Every call bumps lastUpdatedAt and writes an updated history entry.

Removes the project and its whole history. Answers 200 {"success": true}, or 404 when there is no such project. Estimates bound to the project keep their snapshot of the model.

The project report as application/pdf (an attachment named aquaticus_project_<name>.pdf). The calculators run server-side, so the report always reflects the stored model.

Every change to the project, newest first (page with ?limit= and ?offset=). Each entry has id, projectId, userId, userEmail, userName, action (created, updated or rollback), the model before and after (previousVariables, newVariables), previousName/newName, previousTags/newTags and createdAt. Changes made with an API key are attributed to the account owner.

POST /project/{id}/history/{historyId}/rollback (Edit) restores the state before that entry (or the initial state for a created entry), appends a rollback entry and answers with the project. 400 InvalidHistoryEntry when the entry belongs to another project.

Runs every calculator on the model in the body and returns the results as one flat JSON object; nothing is stored. GET /calculate/{projectId} does the same for a saved project. Unlike saving a project, calculating validates the shape strictly (400 InvalidParameter when, say, a rectangle has no length).

The result keys are defined by the formula set and include, among others, perimeter, floorArea, wallArea, totalSurfaceArea, averageDepth, volume, maxGallons, digVolume, gravelTons, concreteFloorYards, concreteWallAndCornersYards, concreteYards, rebarFeet, gpmMainFilterLoop, numberOfSkimmers, numberOfReturns, pipeSizeMainFiltrationSuction and pipeSizeMainFiltrationReturn. GET /formulas/js returns the calculator source together with a description object documenting each output (name, formula, inputs, unit, category, example).

POST /calculate
{
  "shape": "rectangle", "length": 32, "width": 16,
  "depthProfileType": "standard", "shallowDepth": 3.5, "deepDepth": 8,
  "shallowEndLength": 10, "deepEndLength": 8,
  "wallThickness": 8, "floorThickness": 6, "turnoverHours": 8
}

200 OK
{
  "perimeter": 96,
  "floorArea": 561.4,
  "volume": 2718.7,
  "maxGallons": 20336,
  "concreteYards": 31.3,
  "gpmMainFilterLoop": 42.4,
  "numberOfSkimmers": 2,
  "rebarFeet": { "totalFeet": 3241.0, "bar3": 0, "bar4": 3241.0, "bar5": 0, "bar6": 0 },
  "…": "…"
}

The reusable tag vocabulary as an array of strings. POST /tag adds one — the body is the tag as plain text (Content-Type: text/plain), and re-adding an existing tag is a no-op. DELETE /tag/{tag} removes it from the vocabulary without touching projects that already carry it. Both answer {"status": "ok"}.

Saved spa configurations, sorted by name. A preset is { id, userId, name, notes, config, createdAt, updatedAt } where config is a spa object. Create with POST /spa-presets (name 2–255 characters, optional notes, config with at least depth) → 201; update with PUT /spa-presets/{id} (any subset of name, notes, config — config is replaced whole); remove with DELETE /spa-presets/{id} → 204. Projects keep a copy of the spa, so deleting a preset never changes a project.

All clients sorted by name. ?search= filters by name or email (case-insensitive, substring). Page with ?limit= (how many to return, at least 1) and ?offset= (how many to skip, default 0); either works on its own. A page shorter than limit is the last one.

GET /clients?search=henderson&limit=25&offset=50

Answers 200 with the created client.

Partial update with one quirk: all five keys must be present — send null for the ones you are not changing, or the request is rejected with 400 BadJsonBody. A null leaves the field alone; an empty string clears phoneNumber, address or notes. The same validation as on create applies. 409 EmailExists when another client already uses the email.

PATCH /client/7
{
  "name": "Henderson, James R.",
  "email": null,
  "phoneNumber": "+15559876543",
  "address": null,
  "notes": null
}

Answers 200 with an empty body. Every project of the client, and each project's history, is deleted with it. Check GET /projects/{clientId} first if that matters to you.

Newest-updated first. Query: status (one of the four statuses), search (substring of the name), tagId, limit (default 50) and offset (default 0). Items carry totalCost but no sections.

Creates a DRAFT with its root section. Answers 201 with the estimate. To price it against a project, follow up with bind-project.

POST /estimates
{
  "name": "Johnson Backyard Pool",
  "taxProfileId": "5e7c9a02-4b18-49d3-bb61-7f2c8e105d3a",
  "markupPresetId": "b2f4a610-77c1-4e39-9d85-0a3f61c8d244",
  "clientId": 118,
  "notes": "Includes spa."
}

201 Created
{
  "id": "3f9b1c2e-5d41-4a77-9f0b-6c2d8a1e0b53",
  "userId": 42,
  "name": "Johnson Backyard Pool",
  "clientId": 118,
  "clientName": "Dana Johnson",
  "status": "DRAFT",
  "notes": "Includes spa.",
  "rootSectionId": "c41d9b77-2e58-4f10-8b6a-1d7e3c095aa2",
  "rootMarkupPresetId": "b2f4a610-77c1-4e39-9d85-0a3f61c8d244",
  "rootMarkupPresetName": "Standard",
  "rootMarkupPresetMaterialRate": 0.3,
  "rootMarkupPresetLaborRate": 0.5,
  "rootTaxProfileId": "5e7c9a02-4b18-49d3-bb61-7f2c8e105d3a",
  "rootTaxProfileName": "CA – Los Angeles",
  "createdAt": 1757500800000,
  "updatedAt": 1757500800000
}

Partial update: any subset of name, clientId, notes, validUntil, tagIds (replaces the tag set) and preferredVendorIds (replaces the ordered vendor list; each must be one of your suppliers). Fields you omit are unchanged; this endpoint cannot clear a field.

Body {"status": "SENT"}. Moving out of DRAFT snapshots every line item's resolved inventory item and unit cost, so later inventory price changes no longer move the estimate. Any status may be set from any other.

Copies the estimate (sections, items, overrides, snapshot) as a new DRAFT named "<name> — Change order N" and linked to the chain root. Refused with 409 Conflict while any revision in the chain is SENT. GET /estimates/{id}/chain lists the chain oldest first as { id, originalEstimateId, name, status, creatorName, creatorEmail, createdAt, updatedAt }; GET /estimates/{id}/changes diffs a change order against the revision before it, returning { baselineName, revisedName, sections: [{ name, depth, type, items: [{ description, type, oldQty, newQty, oldUnitPrice, newUnitPrice, oldTotal, newTotal }], oldTotal, newTotal }], baselineTotal, revisedTotal } where type is ADDED, REMOVED, MODIFIED or UNCHANGED.

Body {"projectId": 91}. Sets the project and copies its current model into projectVariableSnapshot; binding again refreshes the snapshot. Drafts only (400 otherwise). POST …/unbind-project clears both.

{
  "sections": [
    { "name": "Excavation", "materialCost": 0.0, "laborCost": 3145.0, "materialSell": 0.0, "laborSell": 4717.5, "sectionTax": 0.0, "sectionTotal": 4717.5 },
    { "name": "Equipment", "materialCost": 4820.0, "laborCost": 0.0, "materialSell": 6266.0, "laborSell": 0.0, "sectionTax": 548.28, "sectionTotal": 6814.28 }
  ],
  "summary": { "materialSubtotal": 6266.0, "laborSubtotal": 4717.5, "subtotal": 10983.5, "totalTax": 548.28, "grandTotal": 11531.78 },
  "taxProfile": { "name": "CA – Los Angeles", "materialTaxRate": 0.0875, "laborTaxRate": 0.0 },
  "profitAnalysis": { "totalCost": 7965.0, "totalRevenue": 11531.78, "totalTax": 548.28, "grossProfit": 3018.5, "grossMarginPercent": 26.2, "materialMarginPercent": 23.1, "laborMarginPercent": 33.3 }
}

sections lists every section at every depth, in tree order. Margin percentages are whole percents.

application/pdf. ?view= is client-itemized (default), client-phase, client-lump or builder; ?scope=changes renders the change-order diff instead of the whole estimate.

Adds a section under the estimate's root (or under parentSectionId). POST /sections/{id}/sections adds a child to any section, template sections included. Answers 201 with the section.

No body. Copies the template's tree into the estimate, under ?parentSectionId= or the root. Every formula in the template is first checked against the estimate's model snapshot; if one references a calculator output the model cannot produce, the whole call is refused with 400 and the description names the outputs.

Body {"markupPresetId": "…", "taxProfileId": null}. This is a replace: a field you omit or set to null is cleared back to inherit. Use it with estimate.rootSectionId to change the estimate-level overrides. PUT /sections/{id}, by contrast, only sets what you send (name, description, sortOrder, parentSectionId).

Body {"sectionIds": [...]} — exactly the current child ids, in the new order. POST /sections/{id}/items/reorder takes {"itemIds": [...]} the same way. Both answer {"status": "reordered"}; a list that is not exactly the current set is refused with 400.

POST /sections/7b21e4d9-0a53-4c68-9e17-8f4b2d60c1a5/items
{
  "sectionId": "7b21e4d9-0a53-4c68-9e17-8f4b2d60c1a5",
  "formula": "{Excavation Labor} * digVolume"
}

201 Created
{
  "id": "e0c7a914-6b32-4d85-a1f7-52d9b3e08c46",
  "sectionId": "7b21e4d9-0a53-4c68-9e17-8f4b2d60c1a5",
  "inventoryItemIds": ["9d13f6c8-2a47-4e91-b035-7c6e148af2d0"],
  "formula": "{Excavation Labor} * digVolume",
  "resolvedInventoryItemName": "Excavation Labor",
  "unit": "yd³",
  "quantity": 135.2,
  "unitCost": 42.5,
  "taxStatus": "TAXABLE",
  "createdAt": 1757500800000,
  "updatedAt": 1757500800000
}

PUT /line-items/{id} accepts any subset of the same fields plus sectionId to move the item; omitted fields stay. PUT /line-items/{id}/overrides takes { markupOverride, taxStatus, taxRateOverride } as a replace — omitted overrides are cleared and an omitted taxStatus resets to TAXABLE.

Body {"formula": "…", "estimateId": "…"}. With estimateId the formula is checked against that estimate's snapshot; without it, against every known variable and output. Always 200 — read ok:

{
  "ok": false,
  "errors": [{ "message": "Unknown inventory item '{Pmup}'", "start": 0, "end": 6 }],
  "projectVariables": [],
  "inventoryItemNames": [],
  "projectOutputs": []
}

Body { "name", "description", "tagIds" } creates an empty template (201); build it up with POST /sections/{id}/sections and POST /sections/{id}/items. PUT /templates/{id} updates name, description and tags. POST /templates/from-estimate/{estimateId} with { "name", "description" } turns an estimate into a template, keeping its markup and tax overrides but dropping the frozen prices so the template re-prices wherever it is used. GET /templates lists templates without their trees; GET /templates/{id} includes the whole tree.

Answers 201 with the item. A MATERIAL item needs at least one entry in vendorCosts; a LABOR item takes unitCost directly and ignores vendorCosts.

POST /inventory
{
  "name": "Pentair IntelliFlo VSF Pump",
  "sku": "PMP-3HP-VSF",
  "unit": "each",
  "costType": "MATERIAL",
  "categoryId": "3a6c1f80-11d2-4c3e-8a2b-9c0f77b1a201",
  "vendorCosts": [
    { "supplierId": "5d2b8c91-4e07-4f3a-9b11-2a8e6c4d0f77", "cost": 1289.5, "supplierSku": "PEN-011056", "isPreferred": true }
  ]
}

201 Created
{
  "id": "8f14e45f-ceea-467a-9a36-dedd4bea2543",
  "userId": 42,
  "name": "Pentair IntelliFlo VSF Pump",
  "sku": "PMP-3HP-VSF",
  "unit": "each",
  "unitCost": 1289.5,
  "costType": "MATERIAL",
  "categoryId": "3a6c1f80-11d2-4c3e-8a2b-9c0f77b1a201",
  "categoryName": "Equipment",
  "preferredVendorName": "Heritage Pool Plus",
  "preferredVendorCost": 1289.5,
  "vendorCosts": [
    {
      "id": "e1c9a77b-2f40-4b8d-9a6e-77c1d0e3b512",
      "inventoryItemId": "8f14e45f-ceea-467a-9a36-dedd4bea2543",
      "supplierId": "5d2b8c91-4e07-4f3a-9b11-2a8e6c4d0f77",
      "supplierName": "Heritage Pool Plus",
      "supplierAdapterType": "magento",
      "supplierSku": "PEN-011056",
      "cost": 1289.5,
      "isPreferred": true,
      "lastUpdated": 1757635200000,
      "createdAt": 1757635200000
    }
  ],
  "createdAt": 1757635200000,
  "updatedAt": 1757635200000
}

PUT /inventory/{id} takes any subset of the same fields plus isActive and clearSubcategory. A vendorCosts or tagIds you send replaces the whole list. Every cost change is recorded in the price history.

Body { "op", "itemIds", ... } where op is DELETE (deactivate), ADD_TAGS / REMOVE_TAGS (with tagIds), SET_CATEGORY (with categoryId, subcategoryId, clearSubcategory) or ADJUST_COST (with costMultiplier > 0, applied to the item and all its vendor prices). Answers { "op", "affected" }.

Re-reads the price of every vendor cost that opted in (autoUpdate on the price, autoUpdateFromApi on the item, a live vendor and a vendor SKU) and is older than ?maxAgeMs= (default 6 hours), up to 100 per call. Answers { "updated", "unchanged", "failed", "errors" }. POST /inventory/apply-vendor with { "supplierId", "itemIds", "makePreferred" } looks up to 200 material items up in a live vendor's catalogue and attaches the matches, answering { "applied", "unmatched", "skipped", "unmatchedNames", "errors" }.

text/csv of all active items with the columns name, sku, mpn, description, unit, unitCost, costType, vendor, category, subcategory, taxStatus, tags (tags separated by |).

POST /inventory/import.csv takes the same layout as a raw CSV body (Content-Type: text/csv, up to 5 MB and 50,000 rows). name, unit, unitCost and costType are required columns; vendor is required for material rows. Unknown categories, tags and vendors are created on the fly. ?updateExistingBySku=true updates items whose SKU matches instead of skipping them. Always answers 200 { "created", "updated", "skipped", "errors": ["Line 14: …"] } — check errors.

Newest first: [{ id, inventoryItemId, oldCost, newCost, source, note, changedAt }] with source one of MANUAL, API, IMPORT, BULK. Notes work the same way: GET /inventory/{id}/notes → [{ id, inventoryItemId, body, source, createdAt }], POST with { "body" } (up to 10,000 characters) → 201, DELETE …/notes/{noteId} → 204.

Body { "inventoryItemId", "supplierId", "cost", "supplierSku", "isPreferred", "autoUpdate", "notes" } (inventoryItemId must be present; the path value is used). PUT …/prices/{priceId} updates any subset of cost, supplierSku, isPreferred, autoUpdate, notes; DELETE removes the price. Prefer PUT /inventory/{id} with a full vendorCosts list when you also need the item's unitCost and price history kept in step.

A manual supplier just needs { "name" }. A live one names a predefined vendor and its customer login: { "name", "vendorKey": "heritage_pool_plus", "customerEmail", "customerPassword" }; the login is verified with the vendor before saving (401 SupplierAuthFailed when it is rejected). PUT /suppliers/{id} updates name, baseUrl and the credentials. DELETE /suppliers/{id} also removes every vendor price that references the supplier. GET /suppliers/{id}/search?q=&category=&page=&pageSize= and GET /suppliers/{id}/categories query a live vendor's catalogue.