Documents API

​

Base prefix

/api/documents

​

Upload flow

1. POST /api/documents validates file metadata and creates document rows.
2. The response returns presigned upload instructions for accepted files.
3. The browser uploads directly to S3 or LocalStack.
4. Object-created events trigger malware scanning.
5. Estimate-scoped uploads continue through parsing, summarisation, classification, and area modules. Project-scoped and company-scoped on-demand uploads stop at stored immediately after a clean scan, before parsing, until the user routes and processes them.
6. Users review suggestions before any estimate records are created.

​

Service version endpoint

​

GET /version

{
  "version": "1.2.3",
  "commit": "0123456789abcdef0123456789abcdef01234567"
}

• version — value from SERVICE_VERSION, falling back to package.json only when that variable is absent.
• commit — the Git commit SHA stamped into the Lambda as SERVICE_COMMIT at deploy time. Returns "unknown" when SERVICE_COMMIT is not set.

​

OpenAPI contract endpoint

​

GET /openapi.json

​

Document endpoints

​

Document update endpoint

​

PATCH /:id

{
  "relatedFolder": "Tender / Drawings / Issued",
  "title": "Head Contract v2",
  "issueDate": "2026-07-01",
  "reviewDate": "2027-07-01"
}

• relatedFolder — optional. A slash-delimited breadcrumb string up to 2048 characters, or null to clear it. Each segment must contain at least one non-whitespace character (Tender//Issued is rejected). Leading and trailing whitespace per segment is trimmed; the canonical form uses / (space–slash–space) as separator.
• title — optional. A display name up to 300 characters, or null to clear it. Used on company document lists when set; the UI falls back to fileName when absent.
• issueDate — optional. Calendar date in YYYY-MM-DD format, or null to clear it.
• reviewDate — optional. Calendar date in YYYY-MM-DD format, or null to clear it.

​

Delete endpoint

​

DELETE /:id

• Document lists (GET /api/documents?estimateId=, ?projectId=, ?partyId=) no longer return the document.
• The suggestions summary (GET /suggestions/summary) excludes the document.
• Any active drive-sync mapping for the document is set to excluded in the same transaction, so the file is never re-imported.

• The document row is still accessible via GET /:id. The response includes deletedAt.
• The upload file, all rendered pages, conversion output, extracted text, area runs, and suggestions remain intact.

​

Upload scoping

​

Pinned kind constraints

​

Routing and processing endpoints

​

POST /:id/route

{
  "estimateId": "estimate-uuid",
  "process": true,
  "targetAreas": ["work_items", "project_rates"]
}

• estimateId — required. UUID of the target estimate, or null to unroute.
• process — optional boolean. When true, the document is moved to processing in the same transaction as the route write.
• targetAreas — optional non-empty array. Limits AI processing to the listed areas. Valid values: takeoff, work_items, project_rates, programme_tender, subcontracts. Supplying this field requests processing even when process is omitted.

• The estimate must belong to the document’s project. A mismatch returns 422. Company documents (owned by partyId) have no project and always return 422 from this endpoint.
• Re-routing an active document to its current estimate is idempotent. Routing it to a different estimate while it is not settled returns 409.
• Changing an estimate link or unroute requires a settled state (stored, processed, or failed); re-routing an active document to its existing estimate is the idempotent exception.
• Processing starts only when the document is stored and scan-clean. A route request can still succeed when processing cannot start; its 200 response reports processing: { started: false, reason: "not_stored" }.
• A linked drive document routed with processing requested is fetched first: the response reports processing: { started: false, reason: "fetching", jobId }, and the fetch job starts processing once the copy scans clean. A store-only document routes normally and reports reason: "store_only".
• The estimate-service reference validation is server-to-server. If the upstream service is unreachable, the endpoint returns 502.

​

POST /:id/process

{
  "targetAreas": ["work_items"]
}

• targetAreas — optional array. Limits processing to the listed areas. An explicit empty array returns 400. Omitting the field processes all applicable areas.

• A first processing start requires stored, a clean scan verdict, a non-null estimateId, and no superseding document.
• The endpoint uses a compare-and-swap write. A retry or race that finds the document on the active processing path (parsing, summarising, processing_areas, or processed) with a clean scan is a benign 200 no-op with reason: "already_processing".
• A DWG or DXF drawing whose PDF derivative has not yet been produced returns 200 with started: false, reason: "conversion_pending". The document will become processable once conversion completes. The client should poll and retry.
• A routed linked drive document is fetched first: the endpoint creates or joins a fetch job and returns 202 with { started: false, reason: "fetching", job }. Processing starts once the copy scans clean.
• Store-only documents return 409 with a store_only: message. A linked file that can be viewed but not processed returns 409 not_processable, and one that opens only in the drive returns 409 drive_only.
• Unrouted, infected, superseded, failed, rejected, or otherwise genuinely unprocessable documents return 409. This includes DWG or DXF documents whose conversion has failed.

​

Takeoff review endpoint

​

PUT /:id/takeoff-review

{
  "status": "approved"
}

• status — required. Must be "approved" or "rejected".

{
  "id": "doc-uuid",
  "takeoffReviewStatus": "approved",
  "takeoffReviewedAt": "2026-07-13T10:00:00.000Z"
}

• The document must have status: "processed". A document that is still in the pipeline returns 422 Unprocessable Entity.
• The decision is changeable. Calling the endpoint again with a different status overwrites the previous decision and refreshes takeoffReviewedAt.
• The write is atomic: the status = processed precondition and the decision commit in one statement, so a concurrent area rerun cannot produce an inconsistent state.
• A decision does not modify the per-page takeoff page selection stored by PUT /:id/takeoff-pages.
• In-flight sync rows are invisible to this endpoint. An ID that names a sync-provisioning row returns 404, the same as a document that does not exist.

​

Page render endpoints

​

GET /:id/thumbnails

{
  "expiresAt": "2026-10-06T10:00:00.000Z",
  "pageCount": 10,
  "thumbnails": [
    { "page": 1, "status": "ready", "url": "https://..." },
    { "page": 2, "status": "pending" },
    { "page": 3, "status": "failed" }
  ]
}

• expiresAt: taken before signing, so it is never later than any URL’s own expiry.
• pageCount: the document’s page count, or 0 while the parse has not counted the pages yet.
• thumbnails: one entry per page in the range. status is ready (with url), pending (not rendered yet), or failed (the page’s render failed after its retries).

​

GET /:id/page-thumbnails

{
  "items": [
    { "page": 1, "url": "https://..." },
    { "page": 2, "url": "https://..." }
  ],
  "pageCount": 10,
  "complete": false
}

• items — presigned URLs for contiguous pages rendered so far (pages 1 through thumbnailPageCount).
• pageCount — the document’s known total page count, or the rendered count when the total is not yet available.
• complete — true when every page is rendered. false while rendering is in progress, while a DWG drawing is still being converted, or when the total page count is not yet known. true (with an empty items array) when the document is not a scan-clean PDF and conversion is not expected, so the picker degrades to numbered placeholders rather than polling indefinitely.

​

GET /:id/pages/:page/image

{
  "page": 1,
  "url": "https://...",
  "expiresAt": "2026-07-12T15:00:00Z",
  "width": 3508,
  "height": 2480,
  "pageWidthPt": 841.89,
  "pageHeightPt": 595.28
}

• page — the requested page number.
• url — presigned download URL for the full-resolution render.
• expiresAt — ISO 8601 expiry timestamp for the presigned URL.
• width / height — the render’s actual pixel dimensions, read from the PNG header. Use these to derive the true aspect ratio without guessing a paper size.
• pageWidthPt / pageHeightPt — the PDF page box in points (1 pt = 1/72 in). Use these together with width / height to convert a pixel distance to millimetres exactly: mm = px / width × pageWidthPt / 72 × 25.4.
• Any field the server cannot establish is omitted from the response. Absence means “not measured” — the url is still valid and is always returned.

• With async=1, the answer is 202 { "page": 1, "status": "rendering", "retryAfterMs": 2000 }. Ask again after retryAfterMs.
• With async=1, a page whose render failed after its retries answers 200 { "page": 1, "status": "failed" } until retry=1 queues it again.
• Without async=1, the request waits up to 20 seconds for the worker and then returns the image. If the render is still not ready, it returns 503 with a Retry-After: 2 header and { "message": "This page is still being prepared. Please try again in a moment.", "retryAfterSeconds": 2 }. A failed page is queued again.

​

GET /:id/takeoff-pages

{
  "pages": [
    { "page": 1 },
    {
      "page": 3,
      "scale": "1:100",
      "scaleSource": "auto",
      "scaleAuto": { "detectedFrom": "text", "detectedAt": "2026-10-07T04:00:00.000Z" }
    }
  ],
  "version": 2
}

• pages — the saved selection, sorted ascending by page number. Each entry has a page number and an optional scale string.
• scaleSource: only on a scaled page: manual (set by the estimator), filled (given by the same-size fill when the estimator set another page), or auto (set by the render worker from the page’s one clear scale). A scaled page with no source is manual.
• scaleAuto: only with scaleSource: "auto": detectedFrom (text or vision) and the detection’s detectedAt.
• version — monotonically increasing integer, bumped whenever the set changes. Echo this value in PUT /:id/takeoff-pages to prevent stale overwrites.

​

POST /:id/takeoff-pages/add

{
  "pages": [
    { "page": 2 },
    { "page": 4, "scale": "1:200" }
  ]
}

• pages — required, 1–500 entries. Each entry is a page number (1–10,000) or an object with page and an optional scale string (up to 40 characters).
• A bare page number is accepted and normalised to { page }.
• All pages must be within the document’s known page count; requests that exceed it return 422.

{
  "pages": [
    { "page": 1 },
    { "page": 2 },
    { "page": 4, "scale": "1:200" }
  ],
  "version": 3
}

• The merge and version bump run inside a single transaction with a row lock, so concurrent adds and replaces cannot race each other.
• Adding a page that is already selected is a no-op; the existing entry’s scale is preserved.
• Replaying an identical add does not bump the version.
• For a renderable document with at least one selected page, full-resolution renders are enqueued after each call, including replays, so a failed warm-up from a previous call can be retried.
• In-flight sync rows are invisible to this endpoint. An ID that names a sync-provisioning row returns 404, the same as a document that does not exist.

​

PUT /:id/takeoff-pages

{
  "pages": [
    { "page": 1 },
    { "page": 3, "scale": "1:100" }
  ],
  "version": 2
}

• pages — required, 0–500 entries. Accepts the same shapes as POST /:id/takeoff-pages/add. An empty array clears the selection.
• version — required. Must match the version returned by the most recent GET /:id/takeoff-pages or write response. A mismatch returns 409 with the current { pages, version } under a current key.

{
  "pages": [
    { "page": 1 },
    { "page": 3, "scale": "1:100" }
  ],
  "version": 3
}

• The version check and the write share one transaction under a row lock, so a concurrent add cannot slip between the check and the write.
• A replace that resolves to the identical set writes nothing and does not bump the version.
• A page sent back with the scale it already had keeps its scaleSource. A page whose scale changed, or that newly has one, becomes manual.
• For a renderable document with at least one saved page, full-resolution renders are enqueued after every call, including no-op saves, so a previously failed warm-up is retried. Clearing the selection enqueues nothing.
• In-flight sync rows are invisible to this endpoint. An ID that names a sync-provisioning row returns 404, the same as a document that does not exist.

​

PUT /:id/takeoff-pages/:page/scale

{
  "scale": "1:200",
  "fillUnscaledPages": true
}

• scale: required. The ratio as written, up to 40 characters.
• fillUnscaledPages: optional, defaults to true. false writes only the named page.

{
  "pages": [
    { "page": 1, "scale": "1:200", "scaleSource": "filled" },
    { "page": 2, "scale": "1:200", "scaleSource": "manual" },
    { "page": 3, "scale": "1:100", "scaleSource": "manual" }
  ],
  "version": 5,
  "filledPages": [1],
  "skippedPages": { "differentSize": [4], "unknownSize": [], "notToScale": [5] },
  "pageSize": { "widthMm": 841.0, "heightMm": 594.0, "sheet": "A1" }
}

• pages and version: the saved selection after the write. The version is bumped only when the set changed.
• filledPages: the other pages that gained the scale. Never includes the set page.
• skippedPages: unscaled pages left alone: differentSize (a different sheet size), unknownSize (a size that could not be read, or every page when the set page’s own size is unknown), and notToScale (the page’s cached scale detection says it is not to scale).
• pageSize: the set page’s size in millimetres and ISO sheet name (sheet is null for a non-ISO size), or null when unknown.

• The set page always takes the new scale and is recorded as manual. Filled pages are recorded as filled.
• Two pages are the same sheet size when each edge matches within 2.5%, either way up, using the PDF’s page boxes. A page that already has a scale is never changed, whatever its source.
• The write runs in one transaction under the row lock. There is no version echo: the fill only writes pages that are empty at the locked read.
• Only the set page’s full-resolution render is warmed. Filled pages render when they are opened.

​

DELETE /:id/takeoff-pages/:page/scale

{
  "page": 3,
  "pages": [{ "page": 1 }, { "page": 3 }],
  "version": 6
}

​

POST /:id/takeoff-pages/:page/scale-detection

{ "refresh": true }

• refresh: optional. true reads past a cached answer (including a cached “nothing found”) and queues a fresh detection. The Find scale on drawing button sends it. Poll without refresh, so polling never restarts the job.

• A cached answer is returned straight away with 200.
• Otherwise the page is queued for the render worker. With async=1, the answer is 202 { "page": 3, "status": "pending", "retryAfterMs": 2000 }. Without it, the answer is 200 with status: "unavailable".
• A failed detection answers status: "unavailable" once and is not cached, so the next request asks again. The estimator can always set the scale by hand.

{
  "version": 2,
  "page": 3,
  "status": "found",
  "pageSize": { "widthMm": 841.0, "heightMm": 594.0, "sheet": "A1" },
  "candidates": [
    {
      "statedScale": "1:200",
      "statedSheetSize": "A1",
      "check": "matches",
      "appliedScale": "1:200",
      "fromLongEdgeScale": null,
      "axis": null,
      "fromViewTitle": false,
      "scaleEvidence": { "text": "SCALE 1:200 @ A1", "box": { "x": 0.82, "y": 0.94, "width": 0.08, "height": 0.02 } },
      "sheetSizeEvidence": null,
      "sheetSizesDisagree": false
    }
  ],
  "preselected": 0,
  "notToScale": false,
  "source": "text",
  "visionChecked": false,
  "detectedAt": "2026-10-07T04:00:00.000Z"
}

• status: found (one scale that can be applied as is), choose (more than one scale, or a sheet size mismatch), none (nothing states a scale), or unavailable (detection could not run; candidates is empty).
• candidates: each scale statement found: the ratio as written (statedScale), the sheet size named with it (statedSheetSize), how that size compares with the page (check: matches, converted, mismatch or not-stated), the ratio to save (appliedScale, null when the estimator must choose), and where the text sits as page fractions (scaleEvidence.box). fromViewTitle is true for a scale read from a view title such as “SECTION A 1:20”.
• preselected: the index of the candidate to start on (the title-block scale), or null when nothing was found.
• notToScale: true when the drawing says it is not to scale.
• source: text or vision, or null when nothing was found. visionChecked says whether a vision read was attempted.

​

Suggestion endpoints

​

Cloud drive sync endpoints

​

Drive identity endpoints

​

Drive source endpoints

​

Sync connection endpoints

​

Drive source states

​

Synced file states

​

Link-first drive endpoints

​

POST /:id/open

• version: "auto" (default), "keep", or "latest". keep and latest act for the entity the open came from.
• entityType and entityId: the entity the open came from. Supply both or neither.

​

GET /drive-fetches/:jobId

​

POST /:id/drive-version

​

POST /prefetch

• A repeat call for the same entity within 30 minutes returns 202 { queued: 0, joined: 0, skipped: [] }, because the entity is already warm or warming.
• When the organisation has already used its hourly budget, the call returns 429 prefetch_throttled with retryAfterSeconds. This is the only case that returns 429.

​

GET /usages/:entityType/:entityId/changes

​

PUT /usages/:module/:entityType/:entityId

{
  "frozen": false,
  "usageVersion": 42,
  "label": "Earthworks estimate",
  "projectId": "project-uuid",
  "usages": [
    { "documentId": "doc-uuid", "purpose": "takeoff_measurement", "count": 3 }
  ]
}

• frozen: required. true when the entity is locked, for example a submitted estimate. Changes then produce possible-variation flags rather than prompts.
• usageVersion: required integer, 0 or more, rising per entity. The set is applied only when this is higher than the version held.
• label: optional string or null. Surrounding whitespace is trimmed, a blank value is stored as null, and a value longer than 200 characters is cut to 200. It is never a reason to reject the set.
• projectId: optional UUID or null.
• usages: required array of up to 5,000 entries. purpose is 2 to 40 characters of lower-case letters, digits and underscores, starting with a letter. count is 1 to 1,000,000.

​

POST /projects/:projectId/processing-recommendations

{
  "recommendations": [
    {
      "documentId": "doc-uuid",
      "fileName": "Site Plan - Civil Works.pdf",
      "folderPath": "Tender / Drawings",
      "reason": "Site plan drawing, likely suitable for takeoff.",
      "suggestedAreas": ["takeoff"]
    }
  ]
}

• folderPath: the document’s relatedFolder, or null.
• suggestedAreas: de-duplicated area keys: takeoff, work_items, project_rates, programme_tender, or subcontracts.

​

Schedule export endpoint

​

POST /:id/schedule-export

{
  "estimateId": "estimate-uuid",
  "items": [
    {
      "itemNumber": "1.1",
      "description": "Excavate",
      "quantity": 4,
      "unit": "m",
      "rate": 150,
      "amount": 600
    }
  ],
  "tags": [
    {
      "listKey": "departures",
      "code": "D1",
      "text": "Rock excluded",
      "linkedItemNumbers": ["1.1"]
    }
  ]
}

• estimateId — required. The estimate the workbook belongs to. The document identified by :id must belong to the same estimate.
• items — required array, 1–2,000 entries. Each item is a priced schedule line.
  • itemNumber — the item’s reference number as it appears in the schedule, or null when there is no item number column.
  • description — the item description.
  • quantity — the item quantity.
  • unit — the unit of measurement.
  • rate — the unit rate to write into the workbook, or null to leave the matched row’s rate cell unchanged.
  • amount — the line amount to write. Required.
• tags — required array, up to 5,000 entries; an empty array is valid. Each entry becomes a row on the TAGs - departures sheet appended to the workbook.
  • listKey — the clause list this tag belongs to (for example, "departures" or "assumptions").
  • code — the clause reference code.
  • text — the clause text.
  • linkedItemNumbers — schedule item numbers this clause relates to.

• The document must be a .xlsx or .xlsm file with a clean scan verdict and no syncAttempt flag.
• The AI surveys up to the first 10 sheets and first 100 rows of each to identify where each schedule table’s header row sits and which columns hold item number, description, rate, and amount. The AI does not calculate, change, or invent any value — it only identifies column positions.
• A column mapping with confidence below 0.75 is rejected as ambiguous.
• Rates and amounts are written only into rows that match an item exactly (by normalised item number or normalised description). A match that is duplicated in the workbook returns 422. An item with no matching row returns 422.
• A TAGs - departures sheet is always replaced or appended with four columns: Type, Reference, Text, and Linked schedule items. An empty tags array produces the header row with no tag entries.
• The response is the completed Excel file. The Content-Disposition header sets a filename of the form <original stem> - Priced.<ext>.
• If the completed workbook exceeds 4 MB, the request returns 422.

​

Variation assessment endpoints

​

Tender scope draft endpoint

​

POST /projects/:projectId/tender-scope-draft

{
  "projectName": "Grafton Road Upgrade",
  "items": [
    { "description": "Excavate to formation level", "section": "Earthworks", "quantity": 4500, "unit": "m³" },
    { "description": "Supply and lay AC 20 wearing course", "section": "Surfacing", "quantity": 2800, "unit": "m²" }
  ]
}

• projectName: required, 1 to 1,000 characters after trimming.
• items: required, 1 to 10,000 entries, each with description (up to 4,000 characters), section (up to 1,000), quantity (a finite number or null), and unit (up to 100). No other fields are accepted.

{
  "scope": {
    "type": "doc",
    "content": [
      { "type": "heading", "attrs": { "level": 2 }, "content": [{ "type": "text", "text": "Earthworks" }] },
      { "type": "paragraph", "content": [{ "type": "text", "text": "Bulk earthworks to formation level..." }] }
    ]
  },
  "documentsUsed": ["Site Investigation Report.pdf"],
  "documentsArePartial": true
}

• scope: a rich-text document of level 2 heading and paragraph nodes, in the same format as the project scope. The model is asked for at most 8 sections and 2,000 words.
• documentsUsed: the file names whose text was included.
• documentsArePartial: always true, because excerpts are bounded. Review the draft against the original documents.

​

Tender check endpoints

​

Document response fields

• projectId — UUID of the owning project, or null for company documents.
• partyId — UUID of the owning company, or null for project documents.
• title — display name set by a user, or null. Company document lists show this field; the UI falls back to fileName when absent.
• docKind — one of prequal, contract_agreement, day_rates, or other. Always other for project documents.
• issueDate — calendar date (YYYY-MM-DD), or null.
• reviewDate — calendar date (YYYY-MM-DD), or null.
• supersededAt — ISO 8601 timestamp at which a pinned document was replaced by a newer upload, or null when the document is current. Only meaningful for contract_agreement and day_rates kinds.
• relatedFolder — the document’s folder assignment as a canonical breadcrumb string (e.g. "Tender / Drawings / Issued"), or null when no folder is assigned. Use PATCH /:id to set or clear this field.
• takeoffReviewStatus — "approved", "rejected", or null (no decision yet).
• takeoffReviewedAt — ISO 8601 timestamp of the last decision, or null.
• deletedAt — ISO 8601 timestamp at which the document was soft-deleted, or null when the document is live. Only present on GET /:id responses; document lists never return deleted documents.
• storeOnly: "store_only_type" (emails and MS Project plans), "too_large_to_process" (PNG or JPEG images over 10 MB), or null when the document can be processed. Store-only documents can be downloaded but never processed.
• driveLink: for a drive-synced document, what the drive holds compared with what Stralos holds; null for any other document. See Drive link object.

​

Drive link object

​

Document kinds

​

Status model

• linked
• uploading
• scanning
• parsing
• summarising
• processing_areas
• stored
• processed
• failed
• infected
• rejected

​

Areas

• takeoff
• work_items
• project_rates
• programme_tender
• subcontracts

​

Billing access

​

Download gate

​

Provider modes

• AI: the central api-assistant structured-completion gateway (Gemini), or fixture
• OCR: textract, local, or fixture
• Scan: guardduty or stub
• DWG/DXF conversion: aps (Autodesk Platform Services) or fixture (deterministic, no external calls)
• Drive sync: live or fixture