Generic Templates
The generic template endpoints let you run calculations for any calculation template available on Calcs.com, without needing a dedicated typed endpoint.
For templates with dedicated endpoints (like Timber Beam or Snow Load), those typed endpoints provide richer validation and documented schemas. Use the generic endpoints when no typed endpoint exists, or when you want a uniform interface across template types.
Endpoints
| Method | Path | Description |
|---|---|---|
GET | /v1/templates | List all available templates |
GET | /v1/templates/{code} | Get template details and input fields |
GET | /v1/templates/{code}/presets | Get available presets for a template |
POST | /v1/templates/{code}/calculate | Run a calculation |
POST | /v1/templates/{code}/validate | Validate inputs without calculating |
POST | /v1/templates/{code}/sheets | Create an unsolved sheet — the start of the sheet lifecycle |
Quick Example
1. Discover templates
Code
Alongside templates, the response carries total, limit and offset. Page through with offset — ?limit=20&offset=20 returns the next twenty — and keep going while offset plus the number of entries you received is less than total. Omitting limit returns up to 100.
2. Inspect a template
Code
This returns the template's input fields (with reference IDs, types, units, defaults, and table column definitions), an outputs block describing everything a calculate call can return, and available presets. For loadsSnowASCE7-16 those fields include exposure, W (in ft), and alpha_roof — the reference IDs used in the next step.
3. Run a calculation
Running many designs at once? Bulk Calculate runs up to 100 calculators in one call instead of one call per design. One-shot, iterate, or batch? below compares the three.
Code
The response includes a sheetId, a sheetUrl deep-link to open the sheet in the Calcs.com app, the resolved inputs (one {value, label, units} entry per field, under the same referenceId keys and with the same units as the template schema's fields), and results carrying the subset of the template schema's outputs that apply to those inputs. A field that is both settable and reported appears in both inputs and results, holding the value you sent in one and the solved value in the other.
One-shot, iterate, or batch?
There are three ways to run a calculation, and they 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 in how many designs you are running at once.
POST /v1/templates/{code}/calculate creates a sheet, applies your attributes, 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 splits that into steps on one sheet:
Code
Use it when you expect to refine inputs and re-solve — checking a design against a
requirement, adjusting, and solving again. The sheetId stays the same across every
pass, so you iterate one sheet toward a passing design instead of leaving a trail of
near-duplicates.
Bulk calculate runs the one-shot path for many designs at once — up to 100 calculators in one project from a single call:
Code
Use it when you have a set of designs to run together — a floor of joists, a batch of columns. It is asynchronous: you poll instead of waiting on the response, and you get one call to make, one thing to poll, and one unit to retry, rather than orchestrating N calls yourself.
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 → re-solve loops | many designs at once |
The Sheet Lifecycle guide walks the same snow load calculation as the Quick Example above through create → update → solve, so you can compare those two paths on the same numbers.
Key Concepts
Template codes identify calculation types (e.g., loadsSnowASCE7-16, timberBeamASD). Use GET /v1/templates to discover available codes.
Attributes use widget reference IDs from the template, not API-specific field names. Use GET /v1/templates/{code} to see the expected fields.
Presets apply sensible defaults before your attributes, reducing the number of fields you need to set. Use GET /v1/templates/{code}/presets to see what's available.
Validation can be done as a pre-flight check via POST /v1/templates/{code}/validate before committing to a full calculation.
Next Steps
- API Reference - Full endpoint documentation with schemas
- Sheet Lifecycle - The iterate-and-re-solve alternative to
calculate— same calculation, one sheet across passes - Bulk Calculate - Create and solve up to 100 sheets in one call, then poll once for every result
- Timber Beam Guide - Typed endpoint with richer validation
- Snow Load Guide - Typed snow load endpoint