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

# Quick start

> Create a project and run your first HSS connection through the Connections Hub API.

## Prerequisites

* An API key. NCSEA hackathon participants will find theirs in their email; anyone else can [contact Atlas Tube](https://www.atlastube.com/contact-us/) to request access. See [Authentication](https://connectionshub.atlastube.com/docs/api/authentication.md).

> [!NOTE]
>
> **Windows PowerShell:** type `curl.exe`, not `curl`. The examples below don't run as pasted in Windows PowerShell 5.1: the `\` line breaks don't work there, and PowerShell strips the quotes inside single-quoted JSON, so the API replies `Expected property name or '}' in JSON…`. For requests with a body, use `Invoke-RestMethod` with `ConvertTo-Json`:
>
> ```powershell theme={null}
> $body = @{ name = "My First Project"; buildingStandard = "US" } | ConvertTo-Json
> Invoke-RestMethod -Method Post -Uri "https://api.calcs.com/v1/projects" -Headers @{ Authorization = "Bearer YOUR_API_KEY" } -ContentType "application/json" -Body $body
> ```

**1. Create a project**

Every calculation belongs to a project.

```bash theme={null}
curl -X POST "https://api.calcs.com/v1/projects" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "My First Project", "buildingStandard": "US"}'
```

```json theme={null}
{
  "projectId": "e206293f-773b-44ae-96ba-b0df6ddb75f6",
  "projectUrl": "https://app.calcs.com/project/e206293f-773b-44ae-96ba-b0df6ddb75f6",
  "name": "My First Project"
}
```

Keep the `projectId`.

**2. Look up the calculator's inputs**

Inputs are keyed by each field's reference ID. Get them, with types, units, options and presets, from the template:

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

For the HSS to HSS moment connection, `design_method` takes `ASD` or `LRFD`, `member_beam` and `member_column` take a section name such as `HSS8X4X.375`, and the presets include `Fin Plate` and `Field-Welded Seated`.

**3. Check your inputs (optional)**

Validate before you calculate. Nothing is created.

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

```json theme={null}
{ "valid": true, "errors": [], "warnings": [] }
```

**4. Run the 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": "e206293f-773b-44ae-96ba-b0df6ddb75f6",
    "preset": "Fin Plate",
    "name": "Roof Beam Connection B1",
    "attributes": {
      "design_method": "LRFD",
      "member_beam": "HSS8X4X.375",
      "member_column": "HSS10X10X.500"
    }
  }'
```

The response includes the new `sheetId`, a `sheetUrl` that opens the sheet in the app, the resolved `inputs` (one `{value, label, units}` entry per field), the `results`, and the governing check.

## Reading the result

| Field | Meaning |
| - | - |
| `summaryCheckStatus` | The verdict of the governing check: `pass`, `fail`, `error` (the check could not be evaluated, for example with no loads applied), or `not_evaluated` (the calculator defines no governing check) |
| `summaryCheck` | The governing check's value: `true`/`false`, or a utilisation that passes from 0 to 1. Absent when the status is `error` |
| `summaryCheckFailReasons` | Present only when the check evaluated and failed |
| `results` | The template outputs that apply to these inputs, keyed by reference ID |

The design passes when `summaryCheckStatus` is `pass`. Treat `error` as not passing. Do not read `passed`: it is deprecated, and a failing calculation can report `true`.

## Units

The template endpoints (`POST /v1/templates/{code}/calculate` and `/validate`, `PATCH /v1/sheets/{sheetId}`, and [bulk calculate](https://connectionshub.atlastube.com/docs/api/guides/bulk-calculate.md)) follow three rules:

* **Tag every number you write.** Send it as a string with the unit the calculator lists for that field or table column in `GET /v1/templates/{code}`, for example `"0.375 in"` or `"4000 psi"`, table cells included. A field or column whose `units` is `null` takes a plain number, and so do a few fields that list units. On a number field, use exactly the listed unit: a tag in any other unit, even one that converts, is rejected with a `422` that names the unit to send, or asks for the plain number.
* **Send only the fields you change.** On a sheet, everything you leave out keeps its current value. On calculate, it takes the template's default, or the preset's.
* **Never send back a number you read from `inputs`.** Build every number you send, table rows included, from your own values. A number read back may not carry its unit.

## Common issues

* **`projectId is required`**: create a project first with `POST /v1/projects`.
* **`Invalid option`**: an enum value must match one of the field's `options` exactly. Get them from `GET /v1/templates/{code}`.
* **`invalid_unit`**: send a number as a string tagged with the field's published `units`, for example `"0.375 in"`. A tag in any other unit is rejected, even one that converts; the error's `expectedUnit` names the unit to send, or is `null` when the field takes a plain number.
* **An attribute did not take effect**: unknown reference IDs are skipped and listed in `warnings`.

## Next steps

* [Templates](https://connectionshub.atlastube.com/docs/api/guides/templates.md): one-shot, iterate, or batch
* [Sheet lifecycle](https://connectionshub.atlastube.com/docs/api/guides/sheet-lifecycle.md): refine one design and re-solve it
* [Bulk calculate](https://connectionshub.atlastube.com/docs/api/guides/bulk-calculate.md): run up to 100 connections in one call
* [PDF export](https://connectionshub.atlastube.com/docs/api/guides/pdf-export.md): get the calculation reports


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