Skip to main content
POST
Run a calculation using a template

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

Authorization
string
required

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Path Parameters

code
string
required

Template code, as returned by GET /v1/templates (e.g. steelConnectionHssBeamToHssMomentAISC360-22).

Body

application/json
projectId
string
required

Project UUID to create the sheet in

attributes
object
required

Input values keyed by referenceId — the keys are the fields[].referenceId values from GET /v1/templates/{code}. Send each number as a string tagged with the field's published units, for example "24 ft" (a field whose units are null takes a plain number, and so do a few that list units, such as a roof slope listed as ":12"; a tagged value there is refused with a 422 that asks for the plain number), a list of rows for table fields (each row an array of values in columns[] order, numbers tagged the same way), and for enum fields an entry of that field's options copied exactly as published — including any leading or trailing whitespace, which can be the only thing separating two different options. Almost every option is a string; a few fields publish numbers, and those are accepted either as the number or as its string. Omitted fields fall back to the template's defaults (or the chosen preset's).

preset
string

Optional preset code to apply defaults before user attributes

name
string

Optional name for the created sheet

Response

Calculation completed successfully

sheetId
string

Unique identifier for the created calculation sheet

projectId
string<uuid>

The project the sheet was created in.

sheetUrl
string<uri>

Direct link to the sheet in the Calcs.com app. Always present on a successful response.

templateCode
string

Template code that was used

inputs
object

Echo of the resolved values the calculation ran with — one entry per settable field, keyed by the same referenceIds as fields[] in GET /v1/templates/{code}. Values are echoed in stored form: numbers as strings, enum choices as their stored value or row index, table fields as row arrays.

results
object

Calculation results keyed by referenceId. The keys come from the template schema's outputs[] (GET /v1/templates/{code}), and a given calculation returns the subset of those that apply to the inputs you sent. Value shape depends on the output kind: numbers, booleans, strings (including multi-sentence guidance text), and arrays of row objects, which may be empty. Numeric values are returned unrounded.

passed
boolean | null
deprecated

Deprecated: read summaryCheckStatus for the verdict. passed is not this calculation's verdict: a failing calculation can report true, even on its first solve, or null.

summaryCheck
any

Value of the template's governing summary check — a pass/fail boolean or a numeric utilisation, depending on the template. Absent when the check could not be evaluated; true when the template defines no governing check. Read the verdict from summaryCheckStatus.

summaryCheckReferenceId
string

referenceId of the governing check. Present with summaryCheck.

summaryCheckError
boolean

True when the summary check could not be evaluated. Present when the template defines a summary check.

summaryCheckFailReasons
string[]

Reasons the summary check failed. Present only on failure.

summaryCheckStatus
enum<string>

Verdict of the template's governing check for this calculation. pass: the check passed (summaryCheck is true, or a number from 0 to 1). fail: the check evaluated and failed (false, or a number outside 0 to 1). error: the check could not be evaluated — summaryCheckError is true, or the solve produced no value for a check the template defines; treat it as not passing. not_evaluated: the template defines no governing check.

Available options:
pass,
fail,
error,
not_evaluated
warnings
object[]

Non-blocking validation warnings, present when any were raised. Unrecognised attribute names are returned as a 422 instead.