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

# Templates

> Find a Hub calculator's inputs and run it with the generic template endpoints.

Every Hub calculator is a template. The template endpoints work the same way for all of them: look up a calculator's inputs, then calculate.

## Endpoints

| Method | Path | Description |
| - | - | - |
| `GET` | `/v1/templates` | List the templates your key can use |
| `GET` | `/v1/templates/{code}` | Get a template's input fields, outputs, and presets |
| `GET` | `/v1/templates/{code}/presets` | Get a template's presets |
| `POST` | `/v1/templates/{code}/validate` | Validate inputs without calculating |
| `POST` | `/v1/templates/{code}/calculate` | Create a sheet, apply inputs, and solve it |
| `POST` | `/v1/templates/{code}/sheets` | Create an unsolved sheet, the start of the [sheet lifecycle](https://connectionshub.atlastube.com/docs/api/guides/sheet-lifecycle.md) |

The template codes for each Hub calculator are listed in the [introduction](https://connectionshub.atlastube.com/docs/api.md#hub-calculator-template-codes).

## Example

**1. Discover templates**

```bash theme={null}
curl "https://api.calcs.com/v1/templates?limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Alongside `templates`, the response carries `total`, `limit` and `offset`. Page through with `offset` (`?limit=20&offset=20` returns the next twenty) while `offset` plus the number of entries you received is less than `total`. Omitting `limit` returns up to 100. The Hub's calculators have the category `Connections`.

**2. Inspect a template**

```bash theme={null}
curl "https://api.calcs.com/v1/templates/steelConnectionHssBeamToHssMomentAISC360-22" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

This returns the template's input `fields` (reference IDs, types, units, defaults, enum `options`, and table column definitions), an `outputs` block describing everything a calculate call can return, and the available `presets`. For this template the fields include `design_method`, `member_beam`, `member_column` and `W_s` (weld size, in `in`).

Send a number as a string tagged with exactly the field's `units`, for example `"W_s": "0.25 in"`. A field whose `units` is `null` takes a plain number. A value tagged in any other unit, even one that converts, is rejected with a `422` whose error carries `type: "invalid_unit"` and the `expectedUnit`.

**3. Run a calculation**

```bash theme={null}
curl -X POST "https://api.calcs.com/v1/templates/steelConnectionHssBeamToHssMomentAISC360-22/calculate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "your-project-id",
    "preset": "Fin Plate",
    "attributes": {
      "design_method": "LRFD",
      "member_beam": "HSS8X4X.375",
      "member_column": "HSS10X10X.500"
    }
  }'
```

The response includes a `sheetId`, a `sheetUrl` deep link to the sheet in the app, the resolved `inputs` (one `{value, label, units}` entry per field, under the same reference IDs and units as the template's `fields`), and `results` carrying the outputs that apply to those inputs. A field that is both settable and reported appears in both, holding the value you sent in `inputs` and the solved value in `results`.

## One-shot, iterate, or batch?

All three end in the same place: solved sheets with the same `results` for the same inputs. They differ in how many passes you expect to make and how many designs you run at once.

**`POST /v1/templates/{code}/calculate`** creates a sheet, applies your inputs, and solves it in one call. Every call creates a **new** sheet. Use it when one set of inputs gives you your answer.

**The [sheet lifecycle](https://connectionshub.atlastube.com/docs/api/guides/sheet-lifecycle.md)** splits that into steps on **one** sheet:

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

Use it when you expect to refine and re-solve, for example stepping up a plate thickness until the connection passes. The `sheetId` stays the same, so you end with one sheet holding the final design instead of a trail of near-duplicates.

**[Bulk calculate](https://connectionshub.atlastube.com/docs/api/guides/bulk-calculate.md)** runs the one-shot path for **many** designs, up to 100 in one project from a single call:

```
POST /v1/sheets/bulk-calculate                  → submit, returns batchId
GET  /v1/projects/{projectId}/batches/{batchId} → poll, then read every item
```

Use it for a set of connections run together, such as every beam-to-column connection on a floor. It is asynchronous: you poll instead of waiting on the response.

| | `calculate` | Sheet lifecycle | Bulk calculate |
| - | - | - | - |
| Calls per answer | 1 | 2–3 per pass | 1 submit + polls, for the whole set |
| Sheets created | one per call | one, reused | one per item, up to 100 |
| Answer arrives | in the response | in the response | on a later poll |
| Fits | one-shot answers | refine and re-solve loops | many designs at once |

## Key concepts

**Template codes** identify a calculator, such as `steelConnectionHssBeamToHssMomentAISC360-22`.

**Attributes** are keyed by the template's widget reference IDs, not API-specific names. `GET /v1/templates/{code}` lists them.

**Enum values** must match one of the field's `options` exactly, for example `HSS10X10X.500` for a section or `Gr 120 (e.g. A325)` for a bolt grade.

**Presets** apply a starting configuration before your attributes, matching the connection types in the app (for example `Fin Plate` or `Field-Welded Seated`).

**Validation** with `POST /v1/templates/{code}/validate` checks inputs against the template without creating anything.

## Next steps

* [Sheet lifecycle](https://connectionshub.atlastube.com/docs/api/guides/sheet-lifecycle.md)
* [Bulk calculate](https://connectionshub.atlastube.com/docs/api/guides/bulk-calculate.md)
* [API reference: Templates](https://connectionshub.atlastube.com/docs/api/reference/templates/run-a-calculation-using-a-template.md)


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