---
title: "Compute Assembly"
method: POST
path: "/api/assemblies/{slug}/compute"
tags: ["assemblies"]
---

# Compute Assembly

`POST /api/assemblies/{slug}/compute`

## Request

- Base URL: `https://api.civilquants.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.civilquants.com/api/assemblies/{slug}/compute`
- Auth: none declared

## Path parameters

- `slug` string, required

## Headers

- `authorization` string, nullable

## Request body

- CivilquantsApiRoutesAssembliesComputeRequest
  - `parameters` object
  - `standard` 'CESMM4' | 'NRM2' | 'SMM7' | 'MMHW', required
  - `project` ProjectMeta: Option C free-text Project entity per 25th-fire (filed 2026-05-19, in-scope for the architectural rewrite per INBOX 26th-fire Amendment C). Thin-slice precursor to a full Project entity in v1.1: just two optional free-text fields that the workspace surfaces at the top of every assembly form and that propagate to the BoQ header, the PDF cover sheet, and the DXF title block. No DB persistence, no cross-assembly rollup — those land in v1.1.
    - `name` string, nullable: Free-text project name, e.g. "Phase 2 Drainage Works".
    - `reference` string, nullable: Free-text project reference, e.g. "PRJ-2026-042".
  - `render_artefacts` boolean, nullable: Opt-in to eagerly render + persist the Excel/DXF/PDF export bundle (signed-URL artefacts) inline on this compute. Omitted / null / false means OFF, so the interactive workspace recompute path — debounced POST /compute on every parameter change — stays pure-engine fast and never launches the Puppeteer/Chromium PDF sidecar. Exports are fetched on demand via the dedicated /excel /pdf /dxf endpoints; only callers that genuinely want inline download URLs in one round-trip (e.g. an agent batch) set this True. Nullable default (mirroring `project`) keeps it an optional request field in the generated client. Still subject to the same server-side entitlement + export-gate checks.

## Response `200`

Successful Response

- ComputeResponse
  - `metadata` ComputeMetadata, required: Envelope: assembly + version + chosen standard + hash cell + export gate. `hash_cell` is the 6-char hex from civilquants.core.hash_cell — the cross- reference between this API response, the rendered artefacts, and any email or workspace UI referencing the same parameter set. `export_gate_enabled` reflects server-side EXPORT_GATE_<STANDARD>_ENABLED env var per spec §15 invariant — UI never displays "this export would be allowed if X" client-side state. If false, signed URLs are NOT included in the response.
    - `assembly_slug` string, required
    - `assembly_version` string, required
    - `standard_code` 'CESMM4' | 'NRM2' | 'SMM7' | 'MMHW', required
    - `hash_cell` string, required: 6-char lowercase hex from civilquants.core.hash_cell
    - `bill_total_lines` integer, required
    - `export_gate_enabled` boolean, required
  - `bill` BoQRowRef[], required
    - `code` string, required
    - `description` string, required
    - `unit` string, required
    - `quantity` number, required
    - `rate` number
    - `total` number
    - `source_assembly` string, required
    - `source_element` string, required
    - `nrm1_group_element` integer, nullable
    - `nrm1_element` string, nullable
    - `nrm1_sub_element` string, nullable
  - `totals_summary` TotalsSummary, required: Schema § 1.4 — totals_summary as a typed wrapper around the free-form dict. Wire shape is a flat object (`{"concrete_m3": {...}, "rebar_t": {...}}`). We model it as `RootModel`-equivalent via `model_config(extra="allow")` + a single `__root__`-style `entries` dict. Pydantic v2 recommends `RootModel` for free-form roots; using a wrapper class keeps the import surface uniform with the rest of this module.
    - `entries` object
  - `workings` WorkingRef[]: WorkItem stream behind the BoQ — every measured quantity with its derivation (calculation_steps). Surfaces to the workspace Workings · Audit Trail panel. Standard-agnostic; identical across the four standards because the BoQ rendering is the only standard-aware step. CLAUDE.md pin 10 §15 invariant — every quantity is traceable; "the only margin for error is user input".
    - `category` string, required: WorkCategory string value, e.g. "concrete_rc" or "excavation_general".
    - `quantity` number, required
    - `unit` string, required
    - `source_assembly` string, nullable
    - `source_element` string, nullable
    - `sub_category` string, nullable
    - `notes` string, nullable
    - `calculation_steps` CalculationStepRef[]
      - `label` string, required
      - `formula` string, required
      - `inputs` object
      - `result` number, nullable
      - `unit` string, nullable
  - `warnings` WarningRef[]: Non-fatal geometry advisories (56th-fire T2). Advisory only — never changes a measured quantity; flags geometry that is valid but likely a mistake (e.g. a dependent height left at a stale default after the primary height was raised). Surfaces to the workspace warnings panel. Present on both tiers.
    - `code` string, required
    - `severity` 'info' | 'advisory' | 'caution', required
    - `message` string, required
    - `affected_params` string[]
    - `detail` object
  - `drawing` DrawingRef: Server-rendered SVG preview of the assembly geometry. Per G.6.3 / STATUS.md decision 6 (2026-05-19): one source of geometry (`DrawEntity` list emitted by `Assembly.compute`), two output paths (this SVG for inline preview, the `GET .../dxf` endpoint for the real CAD download). The browser displays `svg_b64` decoded inline; `viewbox` drives client zoom/pan controls without re-parsing the SVG. `svg_b64` is base64 of a UTF-8 SVG document with one `<g class="cq-layer cq-layer-<name>">` per layer. Styling defaults are inlined so the preview renders without an external stylesheet; front-end CSS may override via the class names.
    - `svg_b64` string, required: Base64-encoded SVG document
    - `viewbox_x` number, required: SVG viewBox x in engine units (m)
    - `viewbox_y` number, required: SVG viewBox y in engine units (m)
    - `viewbox_width` number, required: SVG viewBox width in engine units (m)
    - `viewbox_height` number, required: SVG viewBox height in engine units (m)
    - `entity_count` integer, required: Number of DrawEntities rendered
    - `unit_of_drawing` 'm': Engine geometry is in metres. Surfaced here so the client never has to guess; if a future engine switches to mm this becomes the discriminator.
  - `artefacts` ArtefactRef[]: Signed-URL pointers to rendered Excel + DXF + PDF artefacts. Empty when EXPORT_GATE_<STANDARD>_ENABLED is false (spec §15 invariant: gating is server-side, never client-side).
    - `format` 'xlsx' | 'dxf' | 'pdf', required
    - `url` string, required: Pre-signed URL
    - `size_bytes` integer, required
    - `expires_at_iso` string, required: ISO 8601 UTC, e.g. 2026-05-02T00:00:00Z

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/civilquants/apis/civilquants-api.md) · [All operations](https://skmtc.dev/civilquants/apis/civilquants-api/llms.txt) · [OpenAPI document](https://skmtc.dev/civilquants/apis/civilquants-api/revisions/84569a3761e1?raw)