API

The contract is services/construction/openapi.yaml↗, generated from the Go types. Everything below describes it; it does not restate it.

Reads use the platform {header, payload} envelope with page pagination under payload.meta. Writes take {"data": {...}, "why": {...}} and require an Idempotency-KeyIdempotency-Key: A caller-supplied header, stable across retries, that lets command.Execute claim the operation once and replay the same response on duplicate requests. header. Dates in request and response bodies are YYYY-MM-DD strings; money is integer minor units.

Routes

A development project:

The plan:

A relation's relation_type is one of parent_of (such as a master plan over one of its buildings), depends_on, blocks, updates, shared_milestone, or related_to.

Tasks. A task belongs to one project first and can count toward others:

A link's relationship_type is primary for the task's own project, and affects (the default), shared, or deliverable_for for the others.

Document control:

Variations and the budget:

A variation's result is recorded by its approval: when the last required reviewer answers, the variation becomes approved or rejected in the same transaction.

The three registers. Each record belongs to one project. A list route takes an optional project_id; without it the list spans every project:

Vendors and files. The firms themselves, their contacts and their insurance are in the vendors service; construction keeps what a firm does on a project:

An upload is two calls with a blob upload between them. The first returns a short-lived link to blob storage; the client puts the file there with the header x-ms-blob-type: BlockBlob, then calls the second with the blob name it was given. Files can go on a task (record_type task) or on a document revision (document_revision). A revision takes files only while it is a draft or in internal review.

The vendor portal has its own routes under /v1/vendor, described on Vendor portal.

Only the single-record routes return nested collections. A decision's alternatives and an approval's reviewers are absent from the list responses, so a list of two hundred decisions is not a list of two hundred decisions and their options.

Who answers an approval

POST /v1/approvals/{id}/response takes a response and an optional note. It does not take a reviewer, because the reviewer is the authenticated caller. Answering on somebody else's behalf means signing in as them, which is the point. Reviewers are named by email, the same lowercased email Cloudflare Access gives the caller, and the caller must also be an editor.

A caller who is not named on the approval gets 403, not 404: the approval exists and they may read it, they just may not answer it. A caller who has already answered gets 409 already_answered.

Refusals worth designing a client around

These are the conflicts a client has to have an answer for, rather than generic validation failures.

Several 422s exist for inputs that are shaped correctly but mean nothing: leaving award without the award, a reported figure filed against a package measured by tasks, a package that belongs to another project, a chosen alternative that belongs to a different decision, an approval with no required reviewer.

Actions

Every internal route names one of twenty-eight actions:

CreateProject, ReadProject, PlanProject, AdvanceStage, RecordProgress, OpenDecision, RecordDecision, ReadDecisions, RequestApproval, RespondToApproval, ReadApprovals, RaiseRisk, ManageRisk, ReadRisks, ManageVendors, ReadVendors, ManageTasks, ReadTasks, ManageDocuments, PublishDocument, ReadDocuments, ManageVariations, ReadVariations, ManageBudget, ReadBudget, ReadReports, AttachDocument, ReadAttachments.

The eleven whose names start with Read are open to anyone Cloudflare Access admits. The other seventeen need the caller to be in CONSTRUCTION_EDITORS, and a caller who is not gets 403. Each route's OpenAPI description says which of the two it is. A request with no valid Access token, or locally no dev principal, gets 401.