Prerequisites
- An API key. NCSEA hackathon participants will find theirs in their email; anyone else can contact Atlas Tube to request access. See Authentication.
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:1
Create a project
Every calculation belongs to a 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: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.
4
Run the calculation
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
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) 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 whoseunitsisnulltakes 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 a422that 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 withPOST /v1/projects.Invalid option: an enum value must match one of the field’soptionsexactly. Get them fromGET /v1/templates/{code}.invalid_unit: send a number as a string tagged with the field’s publishedunits, for example"0.375 in". A tag in any other unit is rejected, even one that converts; the error’sexpectedUnitnames the unit to send, or isnullwhen the field takes a plain number.- An attribute did not take effect: unknown reference IDs are skipped and listed in
warnings.
Next steps
- Templates: one-shot, iterate, or batch
- Sheet lifecycle: refine one design and re-solve it
- Bulk calculate: run up to 100 connections in one call
- PDF export: get the calculation reports