> ## Documentation Index
> Fetch the complete documentation index at: https://connectionshub.atlastube.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Sheet lifecycle

> Create a sheet, update its inputs, and re-solve it until the connection passes.

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`](https://connectionshub.atlastube.com/docs/api/guides/templates#one-shot-iterate-or-batch) 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](https://connectionshub.atlastube.com/docs/api/guides/bulk-calculate.md).

## Endpoints

```
POST  /v1/templates/{code}/sheets    → create an unsolved sheet
GET   /v1/sheets/{sheetId}           → get inputs and results
PATCH /v1/sheets/{sheetId}           → update inputs
POST  /v1/sheets/{sheetId}/solve     → solve or re-solve
```

[Create Sheet](https://connectionshub.atlastube.com/docs/api/reference/sheets/create-sheet.md) · [Get Sheet](https://connectionshub.atlastube.com/docs/api/reference/sheets/get-sheet.md) · [Update Sheet Inputs](https://connectionshub.atlastube.com/docs/api/reference/sheets/update-sheet-inputs.md) · [Solve Sheet](https://connectionshub.atlastube.com/docs/api/reference/sheets/solve-sheet.md)

## 1. Create an unsolved sheet

No calculation runs until you solve it:

```bash theme={null}
curl -X POST "https://api.calcs.com/v1/templates/steelConnectionHssBeamToHssMomentAISC360-22/sheets" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"projectId": "56b9335c-6859-4978-a6ec-33d780599c23", "name": "Roof Beam Connection B1", "preset": "Fin Plate"}'
```

```json theme={null}
{
  "sheetId": "84cb248b-a36f-41a9-9639-575bc597341e",
  "projectId": "56b9335c-6859-4978-a6ec-33d780599c23",
  "name": "Roof Beam Connection B1",
  "templateCode": "steelConnectionHssBeamToHssMomentAISC360-22",
  "status": "unsolved",
  "createdAt": "2026-08-24T07:59:05.038Z",
  "sheetUrl": "https://app.calcs.com/project/56b9335c-6859-4978-a6ec-33d780599c23/sheet/84cb248b-a36f-41a9-9639-575bc597341e"
}
```

`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}`](https://connectionshub.atlastube.com/docs/api/reference/templates/get-template-details). For an `enum` field, send one of the labels in that field's `options`:

```bash theme={null}
curl -X PATCH "https://api.calcs.com/v1/sheets/84cb248b-a36f-41a9-9639-575bc597341e" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"attributes": {"design_method": "LRFD", "member_beam": "HSS8X4X.375", "member_column": "HSS10X10X.500", "t_sp": "0.375 in"}}'
```

```json theme={null}
{
  "sheetId": "84cb248b-a36f-41a9-9639-575bc597341e",
  "status": "unsolved",
  "updatedAttributes": ["design_method", "member_beam", "member_column", "t_sp"]
}
```

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`:

```json theme={null}
{
  "sheetId": "84cb248b-a36f-41a9-9639-575bc597341e",
  "status": "unsolved",
  "updatedAttributes": ["t_sp"],
  "warnings": [
    { "field": "membr_beam", "message": "Unknown field 'membr_beam' - will be ignored", "type": "unknown_field" }
  ]
}
```

`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

```bash theme={null}
curl -X POST "https://api.calcs.com/v1/sheets/84cb248b-a36f-41a9-9639-575bc597341e/solve" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Abbreviated, with illustrative values:

```json theme={null}
{
  "sheetId": "84cb248b-a36f-41a9-9639-575bc597341e",
  "projectId": "56b9335c-6859-4978-a6ec-33d780599c23",
  "status": "solved",
  "results": { "…": "the template outputs that apply to these inputs, keyed by reference ID" },
  "summaryCheck": 0.62,
  "summaryCheckReferenceId": "…",
  "summaryCheckStatus": "pass",
  "sheetUrl": "https://app.calcs.com/project/56b9335c-6859-4978-a6ec-33d780599c23/sheet/84cb248b-a36f-41a9-9639-575bc597341e"
}
```

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:

| `summaryCheckStatus` | Meaning |
| - | - |
| `pass` | The governing check passed: `summaryCheck` is `true`, or a number from 0 to 1, the same rule the app applies |
| `fail` | The check evaluated and failed. `summaryCheckFailReasons` says why |
| `error` | The check could not be evaluated, and `summaryCheck` is absent. Treat it as not passing |
| `not_evaluated` | The calculator defines no governing check |

`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

```bash theme={null}
curl "https://api.calcs.com/v1/sheets/84cb248b-a36f-41a9-9639-575bc597341e" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

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`](https://jqlang.org)):

```bash theme={null}
SHEET_ID="84cb248b-a36f-41a9-9639-575bc597341e"

for T in 0.25 0.375 0.5; do  # inches
  curl -s -X PATCH "https://api.calcs.com/v1/sheets/$SHEET_ID" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d "{\"attributes\": {\"t_sp\": \"$T in\"}}" > /dev/null

  curl -s -X POST "https://api.calcs.com/v1/sheets/$SHEET_ID/solve" \
    -H "Authorization: Bearer YOUR_API_KEY" | jq "{t_sp: $T, summaryCheck, summaryCheckStatus}"
done
```

When the loop ends, the sheet holds the last design you solved. To remove sheets you no longer need, see [Deleting and cleanup](https://connectionshub.atlastube.com/docs/api/guides/deleting.md).

## Errors

| `error.code` | Status | Means |
| - | - | - |
| `NOT_FOUND` | `404` | The sheet, template, or project does not exist or is not accessible with this key |
| `VALIDATION_ERROR` | `400` / `422` | `400` for malformed JSON or a non-UUID ID; `422` for a request the template or endpoint rejects. Nothing is written |
| `CALCULATION_ERROR` | `422` | The solve ran but produced no results, usually because required inputs are missing or none of the template's outputs applied to them |

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`:

```json theme={null}
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "attributes cannot be empty. Provide at least one widget reference ID.",
    "details": [
      { "field": "attributes", "message": "attributes cannot be empty. Provide at least one widget reference ID." }
    ]
  }
}
```

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`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.