Calcs.com API

Calculators - Generic

Endpoint:https://api.calcs.com

Run calculations using any enabled template. Supports all calculator types without requiring endpoint-specific code.

Run a calculation using a template

POST

https://api.calcs.com

/v1/templates/{code}/calculate

Validates inputs against template widget definitions, creates a calculation sheet, solves it, and returns results.

Run a calculation using a template › path Parameters

codestring · required
Template code, as returned by GET /v1/templates (e.g. loadsSnowASCE7-16).

Run a calculation using a template › Headers

Authorizationstring · required
The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Run a calculation using a template › Request Body

projectIdstring · required
Project UUID to create the sheet in
attributesobject · required
Input values keyed by referenceId — the keys are the fields[].referenceId values from GET /v1/templates/{code}. Send numbers for number fields, an option string for enum fields, and an array of row objects for table fields. Omitted fields fall back to the template's defaults (or the chosen preset's).

presetstring
Optional preset code to apply defaults before user attributes
namestring
Optional name for the created sheet

Run a calculation using a template › Responses

Calculation completed successfully

sheetIdstring
Unique identifier for the created calculation sheet
projectIdstring · uuid
The project the sheet was created in.
sheetUrlstring · uri
Direct link to the sheet in the ClearCalcs web app. Always present on a successful response.
templateCodestring
Template code that was used
inputsobject
Echo of the resolved values the calculation ran with — one entry per settable field, keyed by the same referenceIds as fields[] in GET /v1/templates/{code}. Values are echoed in stored form: numbers as strings, enum choices as their stored value or row index, table fields as row arrays.
resultsobject
Calculation results keyed by referenceId — the keys come from the template schema's outputs[] (GET /v1/templates/{code}), and a given calculation carries the subset applicable to its inputs. Value shape depends on the output kind: numbers, strings, or arrays of row objects for table outputs. Numeric values are returned unrounded.
passedboolean | null
Whether the calculation's checks passed; null when the template defines no pass/fail checks
summaryCheck
Value of the template's governing summary check — a pass/fail boolean or a numeric utilisation, depending on the template. Present when the template defines one.
summaryCheckReferenceIdstring
referenceId of the governing check. Present with summaryCheck.
summaryCheckErrorboolean
True when the summary check could not be evaluated. Present when the template defines a summary check.
summaryCheckFailReasonsstring[]
Reasons the summary check failed. Present only on failure.
warningsobject[]
Non-blocking validation warnings, present when any were raised. Unrecognised attribute names are returned as a 422 instead.

List available calculation templates

GET

https://api.calcs.com

/v1/templates

Returns all calculation templates available for API use, including their codes, names, categories, and whether they have API output configured.

List available calculation templates › query Parameters

limitinteger · min: 1 · max: 500
Return up to this many templates. A page may contain fewer — always read the length of templates rather than assuming limit entries.
Default: 100
offsetinteger
Number of templates to skip for pagination. An offset past the end returns an empty page with total unchanged.
Default: 0

List available calculation templates › Headers

Authorizationstring · required
The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

List available calculation templates › Responses

List of available templates

templatesobject[] · required
totalinteger · required
Total number of templates available to this API key, independent of limit and offset. More pages remain while offset plus the number of entries in templates is less than total.
limitinteger · required
The limit applied to this page.
offsetinteger · required
The offset applied to this page.

Get template details

GET

https://api.calcs.com

/v1/templates/{code}

Returns detailed information about a specific template, including its input fields and available presets.

Get template details › path Parameters

codestring · required
Template code, as returned by GET /v1/templates (e.g. loadsSnowASCE7-16).

Get template details › Headers

Authorizationstring · required
The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Get template details › Responses

Template details

idstring · uuid
Identifier of the currently published template version; changes when the template is republished — use code as the stable identifier
versioninteger | null
The template version that will serve calculations and sheet creates; null when the template records no version
codestring
Template code
namestring
Human-readable template name
categorystring | null
Template category
descriptionstring | null
Brief description of the template; null when the template provides none
fieldsobject[]
Input field definitions for the template
outputsobject[]
Everything a calculate call can return: one entry per API output, keyed by referenceId in the calculate response's results object. A given calculation's results carries the subset applicable to its inputs — some outputs are conditional. Empty when the template exposes no API output.
presetsobject[]
Available presets for the template

Get template presets

GET

https://api.calcs.com

/v1/templates/{code}/presets

Returns the available presets for a template, including their default values.

Get template presets › path Parameters

codestring · required
Template code, as returned by GET /v1/templates (e.g. loadsSnowASCE7-16).

Get template presets › Headers

Authorizationstring · required
The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Get template presets › Responses

Template presets

presetsobject[]

Validate inputs against a template

POST

https://api.calcs.com

/v1/templates/{code}/validate

Validates the provided attributes against the template's field definitions without running a calculation. Useful for pre-flight validation before calling the calculate endpoint.

Validate inputs against a template › path Parameters

codestring · required
Template code, as returned by GET /v1/templates (e.g. loadsSnowASCE7-16).

Validate inputs against a template › Headers

Authorizationstring · required
The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Validate inputs against a template › Request Body

attributesobject · required
Widget reference IDs and their values to validate

presetstring
Optional preset code to apply defaults before validation

Validate inputs against a template › Responses

Validation passed

validboolean · enum
Enum values:
warningsobject[]
Non-fatal warnings (e.g., deprecated fields)

Sheets GIS - Environmental Loads

Run a calculation using a template

POST

https://api.calcs.com

/v1/templates/{code}/calculate

Validates inputs against template widget definitions, creates a calculation sheet, solves it, and returns results.

Run a calculation using a template › path Parameters

codestring · required
Template code, as returned by GET /v1/templates (e.g. loadsSnowASCE7-16).

Run a calculation using a template › Headers

Authorizationstring · required
The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Run a calculation using a template › Request Body

projectIdstring · required
Project UUID to create the sheet in
attributesobject · required
Input values keyed by referenceId — the keys are the fields[].referenceId values from GET /v1/templates/{code}. Send numbers for number fields, an option string for enum fields, and an array of row objects for table fields. Omitted fields fall back to the template's defaults (or the chosen preset's).

presetstring
Optional preset code to apply defaults before user attributes
namestring
Optional name for the created sheet

Run a calculation using a template › Responses

Calculation completed successfully

sheetIdstring
Unique identifier for the created calculation sheet
projectIdstring · uuid
The project the sheet was created in.
sheetUrlstring · uri
Direct link to the sheet in the ClearCalcs web app. Always present on a successful response.
templateCodestring
Template code that was used
inputsobject
Echo of the resolved values the calculation ran with — one entry per settable field, keyed by the same referenceIds as fields[] in GET /v1/templates/{code}. Values are echoed in stored form: numbers as strings, enum choices as their stored value or row index, table fields as row arrays.
resultsobject
Calculation results keyed by referenceId — the keys come from the template schema's outputs[] (GET /v1/templates/{code}), and a given calculation carries the subset applicable to its inputs. Value shape depends on the output kind: numbers, strings, or arrays of row objects for table outputs. Numeric values are returned unrounded.
passedboolean | null
Whether the calculation's checks passed; null when the template defines no pass/fail checks
summaryCheck
Value of the template's governing summary check — a pass/fail boolean or a numeric utilisation, depending on the template. Present when the template defines one.
summaryCheckReferenceIdstring
referenceId of the governing check. Present with summaryCheck.
summaryCheckErrorboolean
True when the summary check could not be evaluated. Present when the template defines a summary check.
summaryCheckFailReasonsstring[]
Reasons the summary check failed. Present only on failure.
warningsobject[]
Non-blocking validation warnings, present when any were raised. Unrecognised attribute names are returned as a 422 instead.

List available calculation templates

GET

https://api.calcs.com

/v1/templates

Returns all calculation templates available for API use, including their codes, names, categories, and whether they have API output configured.

List available calculation templates › query Parameters

limitinteger · min: 1 · max: 500
Return up to this many templates. A page may contain fewer — always read the length of templates rather than assuming limit entries.
Default: 100
offsetinteger
Number of templates to skip for pagination. An offset past the end returns an empty page with total unchanged.
Default: 0

List available calculation templates › Headers

Authorizationstring · required
The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

List available calculation templates › Responses

List of available templates

templatesobject[] · required
totalinteger · required
Total number of templates available to this API key, independent of limit and offset. More pages remain while offset plus the number of entries in templates is less than total.
limitinteger · required
The limit applied to this page.
offsetinteger · required
The offset applied to this page.

Get template details

GET

https://api.calcs.com

/v1/templates/{code}

Returns detailed information about a specific template, including its input fields and available presets.

Get template details › path Parameters

codestring · required
Template code, as returned by GET /v1/templates (e.g. loadsSnowASCE7-16).

Get template details › Headers

Authorizationstring · required
The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Get template details › Responses

Template details

idstring · uuid
Identifier of the currently published template version; changes when the template is republished — use code as the stable identifier
versioninteger | null
The template version that will serve calculations and sheet creates; null when the template records no version
codestring
Template code
namestring
Human-readable template name
categorystring | null
Template category
descriptionstring | null
Brief description of the template; null when the template provides none
fieldsobject[]
Input field definitions for the template
outputsobject[]
Everything a calculate call can return: one entry per API output, keyed by referenceId in the calculate response's results object. A given calculation's results carries the subset applicable to its inputs — some outputs are conditional. Empty when the template exposes no API output.
presetsobject[]
Available presets for the template

Get template presets

GET

https://api.calcs.com

/v1/templates/{code}/presets

Returns the available presets for a template, including their default values.

Get template presets › path Parameters

codestring · required
Template code, as returned by GET /v1/templates (e.g. loadsSnowASCE7-16).

Get template presets › Headers

Authorizationstring · required
The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Get template presets › Responses

Template presets

presetsobject[]

Validate inputs against a template

POST

https://api.calcs.com

/v1/templates/{code}/validate

Validates the provided attributes against the template's field definitions without running a calculation. Useful for pre-flight validation before calling the calculate endpoint.

Validate inputs against a template › path Parameters

codestring · required
Template code, as returned by GET /v1/templates (e.g. loadsSnowASCE7-16).

Validate inputs against a template › Headers

Authorizationstring · required
The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Validate inputs against a template › Request Body

attributesobject · required
Widget reference IDs and their values to validate

presetstring
Optional preset code to apply defaults before validation

Validate inputs against a template › Responses

Validation passed

validboolean · enum
Enum values:
warningsobject[]
Non-fatal warnings (e.g., deprecated fields)