Skip to main content
Iterate on one connection’s sheet instead of creating a new sheet per run. Create an unsolved sheet from any template, set or change its inputs, and solve it as often as you need. The sheetId stays the same across every pass. Use calculate when one set of inputs gives you your answer, and the lifecycle when you expect to refine and re-solve. To run many connections at once, see Bulk calculate.

Endpoints

Create Sheet · Get Sheet · Update Sheet Inputs · Solve Sheet

1. Create an unsolved sheet

No calculation runs until you solve it:
name is optional and defaults to "<template name> - API".

2. Update its inputs

Attribute keys are the template’s widget reference IDs, from GET /v1/templates/{code}. For an enum field, send one of the labels in that field’s options:
Send numbers as strings tagged with the field’s published units, as t_sp is here. A field whose units is null takes a plain number. Updating does not recalculate. Solve the sheet to refresh results. The attributes are applied as one unit: either the whole set is written or, if any value is rejected, none of it is. updatedAttributes lists exactly the keys this request stored. A mistyped key is missing from it and named in warnings:
warnings is absent when there is nothing to report. An explicit null does not clear a field: the key is skipped and reported with a null_value warning. To leave a field alone, omit it.

3. Solve it

Abbreviated, with illustrative values:
Solving can take a few seconds. A failing engineering check is still a 200: the calculation ran, so read the check to see how it came out. results holds the template outputs that apply to these inputs, the same set calculate returns. Solving is safe to retry. Repeating a solve with unchanged inputs returns the same results and never creates another sheet. A solve can come back unsolved. If another PATCH lands while the solve is running, the results no longer describe the sheet’s inputs, so the response reports status: "unsolved". Solve again, or serialise writes and solves per sheet.

Reading the verdict

Use summaryCheckStatus for the outcome of the solve you just ran: summaryCheck holds the check’s value and summaryCheckReferenceId names the widget it comes from. A calculator with no governing check reports summaryCheck: true with status not_evaluated, so read the status, not summaryCheck, to tell a pass from no check at all. Do not read passed as the verdict. It is deprecated, and a failing calculation can report true, even on its first solve, or null. To know whether the design as it stands now passes, read two things together: status is solved, and summaryCheckStatus is pass.

4. Read it back

The response has the sheet’s inputs, and while it is solved, its results and check fields. status tells you whether the results belong to the inputs. A PATCH moves the sheet back to unsolved, and while it is unsolved the response carries no results or check fields. inputs is normalised. Numbers read back as strings ("0.375") and booleans as "1" or "0". An enum field reads back as its option label, which you can send straight back in a PATCH. A value that matches no option, such as a =projectDefault(…) formula, is returned unchanged; leave that field out of a write to keep it. A string you send that matches no option is refused with 422. Send the label, not a number. Numbers are not checked against options, so an unmatched number is stored as sent and may select an option you did not intend, with no error. The exception is a field whose options are themselves numbers: it accepts the number or its string, and reads back as the string. Cells in a table column of type lookup are not translated. A cell you wrote reads back as you sent it; a cell set in the app may come back as an internal code. Treat those as opaque.

Iterating to a passing design

Change an input, re-solve, and check the verdict, on the same sheetId every pass. This steps the fin plate thickness t_sp (requires jq):
When the loop ends, the sheet holds the last design you solved. To remove sheets you no longer need, see Deleting and cleanup.

Errors

A well-formed body that is still invalid, such as an unrecognised top-level field or attributes missing, empty, or not an object, is rejected with 422 before anything changes. So is a value the template rejects. A 422 names each bad field in details:
A 200 on PATCH can still carry warnings of type unknown_field (key skipped) or null_value (explicit null skipped, not cleared). A warned key is always absent from updatedAttributes.