Schemas

Project the sheets are created in.

The sheets to create and solve, 1 to 100. Reported back in this order.

Template to create the sheet from.

Input values keyed by widget reference ID, as for a single calculate. Required on every item: unlike a single calculate, a batch item that sends none is refused.

Your own identifier for this item, echoed on its status. Must be unique within the batch when given.

Sheet name. Defaults to the template name plus the item's ref or position.

A preset code of the template to apply before attributes.

Identifier to poll.

Always bulk-calculate.

processing while sheets are being created and solved. completed once every item has an outcome; items that could not be solved carry their own error, so a completed batch can have summary.solved of 0. failed when the batch itself could not run, or when it stopped before finishing and will not resume (see error). Treat an unrecognised value as still in progress.

Whole-number share of the batch's own sheets solved so far, 0 to 100, while processing. Set to 100 when the batch reaches completed, whatever summary.solved is; read summary for the outcome. Frozen where it stopped when failed.

Number of items requested.

Counts over the items. pending is total - solved - errored - stale and is 0 once the batch is terminal, where every item is solved or carries an error. The three non-solved counters answer different questions and are never folded together, because the remedy differs: errored counts items the batch could not produce results for, where retrying is the fix; stale counts items it did solve whose inputs have changed since, where nothing failed and re-solving the sheet is the fix; checkErrored counts items that solved but whose governing check produced no verdict, and those are also counted in solved. To confirm every item is usable, check errored, stale and checkErrored are all 0. state is the completion signal. While processing the counts are progress, and pending can read 0 in the moments between the last sheet solving and the batch reaching a terminal state; do not use it to detect completion. On a terminal batch the counters are recomputed from the sheets' current state on every poll, so the same batchId can report different counts later if its sheets are edited or deleted.

null until the batch is terminal.

How long the batch took. Set when the batch reached a terminal state and the duration was recorded; null otherwise. A batch the worker had to mark failed as a last resort can be failed with durationSeconds null.

Why the batch itself failed. Set when the batch failed and the reason was recorded; null otherwise. A batch the worker had to mark failed as a last resort can be failed with error null.

One entry per requested item, in request order. null until the batch is terminal.

The ref sent for this item, or null if none was.

null when no sheet was created for this item.

solved when results were computed from the inputs the sheet holds now. Any item that is not solved carries error.

As on GET /v1/sheets/{sheetId}.

Link to the sheet in the Calcs.com app.

Whether this sheet has ever passed: true from its first passing solve onwards, null before that. It is not this batch's verdict — a sheet edited into failing and re-solved still reports true. Read summaryCheck and summaryCheckError for the verdict. Present when solved.

As on GET /v1/sheets/{sheetId}. Present when solved.

Value of the template's governing check for the last solve. Present only when the check produced a verdict: absent when the template defines no governing check, and absent when the check could not be evaluated, where summaryCheckError is true instead. The check passes when this is present, summaryCheckError is false, and the value is true or a number from 0 to 1.

Reference ID of the widget summaryCheck came from.

Whether the governing check could not be evaluated. A check in error has no verdict and carries no summaryCheck; the item is still reported as solved, and summary.checkErrored counts it.

Why the governing check failed. Present only when the check evaluated and failed; absent when it passed and when it errored.

Non-fatal findings against the attributes sent for this item, as a single calculate reports them. Absent when there is nothing to report, and withheld on an item whose template is no longer accessible.

Why one item has no results. SOLVE_FAILED: the solver could not answer this sheet. RESULTS_STALE: the batch solved this sheet, but its inputs have changed since (edited in the app, patched through the API, the project's defaults changed, or the sheet was upgraded), so the results no longer match. Solve the sheet again or resubmit the item. SHEET_UNAVAILABLE: the item has no sheet to report, either because it was deleted after the batch ran or because the batch died before creating it without recording a reason. TEMPLATE_NOT_FOUND: the template is no longer accessible with this API key. A batch-level code (BATCH_FAILED, VALIDATION_CHANGED, BATCH_ABANDONED) appears here when the batch stopped before this item was finished. Treat an unrecognised code as a failure.

Presigned S3 URL, or null while the export is still processing or has failed. Populated only once state === "completed", after which it expires 10 minutes after this response.

URI identifying the problem type.

Short, human-readable summary of the problem type.

HTTP status code.

Human-readable explanation specific to this occurrence.

The request path that produced the error.

Gateway trace metadata for support (timestamp, requestId, buildId, rayId).

Beam span length in feet

Member selection type. 'Database' uses standard lumber from NDS tables, 'Custom' allows custom dimensions

Lumber designation when type='Database' (e.g., '2x10 D.Fir-L SS', '4x12 DF-L No.1')

Support definitions. Each support is [type, position_ft, bearing_width_in]. Minimum 2 supports required.

Distributed loads array. Format: [label, start, end, width1, width2, {load_cases}]. For joist presets use: [label, 0, 'L', 'spacing', 'TW_s', {load_cases}]

Concentrated/point loads. Format: [label, position_ft, {load_cases}] where load_cases contains {D: [force, moment], L: [force, moment]}

Line loads (force per unit length). Format: [label, start_ft, end_ft, {load_cases}] where load_cases contains {D: [plf_start, plf_end], L: [plf_start, plf_end]}

Distributed loads for inclined beams. Format: [label, start, end, width1, width2, orientation, {load_cases}]. Orientation: 'Gravity - Plan', 'Gravity - Inclined', or 'Aligned'. Requires incline_flag to be set.

Point loads for inclined beams. Format: [label, position_ft, null, orientation, {load_cases}]. Orientation: 'Gravity' or 'Aligned'. Requires incline_flag to be set.

Line loads for inclined beams. Format: [label, start_ft, end_ft, orientation, {load_cases}]. Orientation: 'Gravity - Plan', 'Gravity - Inclined', or 'Aligned'. Requires incline_flag to be set.

Joist spacing in inches (for joist presets). floorJoist, ceilingJoist, deckJoist default to 16.

Number of plies for multi-ply beams. Defaults: floorGirder/roofGirder/floorHeader/deckBeam=3, ceilingJoist/hipValley/roofHeader/comboBeam=2, others=1.

Enable flitch plates (steel reinforcement). Defaults to 'Yes' for genericFlitchBeam preset.

Number of steel flitch plates. Defaults to 2 for genericFlitchBeam preset.

Thickness of flitch plates in inches. Defaults to 0.375 for genericFlitchBeam preset.

Depth of flitch plates in inches. If omitted, auto-calculated based on wood member depth.

Yield strength of flitch plate steel in psi. Defaults to 36000 (36 ksi).

Service moisture condition. Defaults: deckJoist/deckBeam='Wet' (outdoor exposure), all others='Dry'.

Temperature range for adjustment factors

Include self-weight in analysis

Live load type for load combinations. ceilingJoist defaults to 'Storage'. Most presets default to 'Occupancy'.

Absolute deflection limit in inches

Short-term deflection limit as L/xxx (e.g., 360 means L/360)

Long-term deflection limit as L/xxx

Consider simplified DL+LL deflection check. Defaults to 'Yes' for genericFlitchBeam, floorGirder, ceilingJoist, rafter, hipValley, roofGirder, roofHeader, floorHeader, deckJoist, deckBeam, and comboBeam presets.

Simplified DL+(LL or SL) deflection limit as L/xxx. Preset defaults: floorJoist/floorGirder/ceilingJoist/roofHeader/floorHeader/deckJoist/deckBeam/comboBeam=180, rafter/hipValley/roofGirder=100, genericFlitchBeam=240.

Member repetition for load sharing. Presets floorJoist, floorGirder, ceilingJoist, rafter, roofGirder, floorHeader, deckJoist, deckBeam default to 'Repeating'. Most others default to 'Non-Repeating'.

Lateral torsional buckling bracing condition. Defaults: floorJoist/deckJoist/deckBeam='Top Braced', ceilingJoist='Bottom Braced', floorGirder/roofGirder/headers='No Continuous Bracing'.

Double L/ deflection limits for cantilevers. Defaults to 'Yes' for rafter, hipValley, roofGirder, roofHeader, floorHeader, deckJoist, deckBeam, and comboBeam presets.

Custom section width in inches. Required when type='Custom'.

Custom section depth in inches. Required when type='Custom'.

Wood species and grade. Required when type='Custom'. Example values: 'Douglas Fir-Larch SS (DL)', 'Southern Pine No.1 (SP)'.

Bending axis for analysis. Defaults to 'X-X' (strong axis).

Beam inclination mode. 'Horizontal' for standard beams, 'Simple Slope' for rafters, 'Hip/Corner Slope' for hip/valley rafters. When set to a slope mode, use the _incline load variants.

Beam inclination angle in degrees (for Simple Slope mode).

First roof slope angle in degrees (required for hipValley preset / Hip/Corner Slope mode).

Second roof slope angle in degrees (required for hipValley preset / Hip/Corner Slope mode).

Side length in feet for hip/valley geometry.

Whether load and support positions are measured along the plan (horizontal) or inclined (along-slope) length.

Point loads provide lateral bracing.

Include shear deflection in analysis.

Consider pattern loading for live loads.

Incised treatment for preservative-treated lumber. Applies Ci adjustment factor per NDS.

Whether the beam passes all design checks

Overall utilization ratio (demand/capacity)

Roof exposure condition per ASCE 7 Table 7.3-1

Thermal condition code per ASCE 7-16 Table 7.3-2

Horizontal distance from eave to ridge in feet

Roof slope ratio (rise per 12 inches of run, e.g., 6 for 6:12)

Set to true to override project defaults for risk category, ground snow load, and roughness

Building risk category per ASCE 7 Table 1.5-1

Ground snow load in psf. Required if overrideDefaults is true.

Ground surface roughness category per ASCE 7 Table 7.3-1

Roof surface type affecting snow sliding

Array of lower roof drift configurations: [label, upperFetch, lowerFetch, heightDiff]

Array of projection drift configurations: [label, fetchDistance, projectionHeight]

Optional notes or comments to include on the calculation sheet

Roof exposure condition per ASCE 7 Table 7.3-1

Thermal condition description per ASCE 7-22 Table 7.3-2

Horizontal distance from eave to ridge in feet

Roof slope ratio (rise per 12 inches of run)

Set to true to override project defaults

Building risk category per ASCE 7 Table 1.5-1

Ground snow load in psf. Required if overrideDefaults is true.

Ground surface roughness category per ASCE 7 Table 7.3-1

Roof surface type affecting snow sliding

Roof insulation R-value (hr·ft²·°F/BTU)

Width factor W₂ for unbalanced loads

Array of lower roof drift configurations

Array of projection drift configurations

Optional notes or comments to include on the calculation sheet

Whether the calculation passed all checks

Calculation outputs

Unique identifier for the sheet

Calculation status

Name of the sheet

Design standard used

Sheet creation timestamp

Current attribute values on the sheet

Calculated snow load results. Note: Additional output fields may be available beyond those documented here.

Horizontal distance from eave to ridge (ft)

Roof slope ratio (rise per 12 inches)

Roof exposure condition

Thermal condition (format depends on sheet's standard)

Set to true to override project defaults

Building risk category

Ground snow load (psf)

Ground surface roughness

Roof surface type

Roof insulation R-value (ASCE 7-22 only)

Width factor W2 (ASCE 7-22 only)

Lower roof drift configurations

Projection drift configurations

Optional notes or comments

Unique identifier for the sheet.

Project the sheet belongs to.

Template the sheet was created from.

A newly created sheet has no results yet.

Link to the sheet in the Calcs.com app.

Sheet name.

Creation timestamp.

Unique identifier for the sheet.

Project the sheet belongs to.

Template the sheet was created from.

solved while the stored results were computed from the inputs the sheet holds now. A sheet that has never been solved, or whose inputs changed since its last solve, is unsolved — re-solve to get results for the current inputs.

Current input values keyed by widget reference ID. Numbers read back as strings and booleans as "1"/"0". An enum field reads back as its option label, as a string — the label listed in that field's options on GET /v1/templates/{code} — so a value you read can be displayed as-is or sent straight back in a PATCH. A value matching no option, such as a formula like =projectDefault(...), is returned unchanged. A field whose options are numbers reads back as the string of that number (2.8 publishes, "2.8" reads back), and accepts either form.

Link to the sheet in the Calcs.com app.

Whether this sheet has ever passed: true from its first passing solve onwards, null before that. It is not the latest solve's verdict — a sheet edited into failing and re-solved still reports true. Read summaryCheck for the current verdict. Present when solved.

Value of the template's governing check for the last solve. The check passes when summaryCheckError is false and this is true or a number from 0 to 1. Absent when the template defines no governing check.

Reference ID of the widget summaryCheck came from.

Whether the governing check could not be evaluated. A check in error has no verdict, whatever summaryCheck holds.

Why the governing check failed, when it did.

Solved outputs, keyed by the reference IDs the template schema lists in outputs[]. A given solve returns the subset of those that apply to the inputs you sent. Present when solved.

Unique identifier for the sheet. Unchanged by updates.

Updated inputs take effect at the next solve.

Reference IDs the sheet now holds from this request. A key the template does not define is skipped, so it is absent here and named in warnings — compare the two to confirm a write landed.

Keys that were not applied, and why. Absent when there is nothing to report.

Unique identifier for the sheet.

solved when the results below were computed from the inputs the sheet holds now — the normal outcome. unsolved only where another write landed on the sheet while the solve was running, leaving results that no longer match its inputs; solve again to get results for them.

Whether this sheet has ever passed: true from its first passing solve onwards, null before that. It is not this solve's verdict — a sheet edited into failing and re-solved still reports true. Read summaryCheck for the verdict of this solve.

Solved outputs, keyed by the reference IDs the template schema lists in outputs[]. A given solve returns the subset of those that apply to the inputs you sent.

Link to the sheet in the Calcs.com app.

Project the sheet belongs to.

Value of the template's governing check for this solve. The check passes when summaryCheckError is false and this is true or a number from 0 to 1. Absent when the template defines no governing check.

Reference ID of the widget summaryCheck came from.

Whether the governing check could not be evaluated. A check in error has no verdict, whatever summaryCheck holds.

Why the governing check failed, when it did.