Generic Templates

Copy page

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
 
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 — 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
 
curl "https://api.calcs.com/v1/templates/loadsSnowASCE7-16" \
  -H "Authorization: Bearer YOUR_API_KEY"

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

Code
 
curl -X POST "https://api.calcs.com/v1/templates/loadsSnowASCE7-16/calculate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "your-project-id",
    "attributes": {
      "exposure": "Partially Exposed",
      "cond_thermal": "Warm Roof (Ct = 1.0)",
      "W": 30,
      "alpha_roof": 4
    }
  }'

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 keyed by the referenceIds listed in the template schema's outputs.

One-shot or iterate?

There are two ways to run a calculation, and they end in the same place — a solved sheet with the same results for the same inputs. They differ in how many passes you expect to make.

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
 
POST  /v1/templates/{code}/sheets    → create an unsolved sheet
PATCH /v1/sheets/{sheetId}           → update inputs
POST  /v1/sheets/{sheetId}/solve     → solve / re-solve
GET   /v1/sheets/{sheetId}           → read inputs + results

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.

	calculate	Sheet lifecycle
Calls per answer	1	2–3 per pass
Sheets created	one per call	one, reused
Fits	one-shot answers	refine → re-solve loops

The Sheet Lifecycle guide walks the same snow load calculation as the Quick Example above through create → update → solve, so you can compare the 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
• Timber Beam Guide - Typed endpoint with richer validation
• Snow Load Guide - Typed snow load endpoint