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

# Run a calculation using a template

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

Running many designs at once? [Bulk Calculate](/api/calculators-generic#bulk-calculate) runs up to 100 in one call instead of one call per design.



## OpenAPI

````yaml api/openapi.json POST /v1/templates/{code}/calculate
openapi: 3.1.0
info:
  title: Connections Hub API
  version: 1.0.0
  description: >-
    Run HSS Connections Hub calculators programmatically: create projects,
    create and solve sheets from any calculator template, run batches, and
    export reports to PDF.


    All endpoints require API key authentication.
servers:
  - url: https://api.calcs.com
security:
  - bearerAuth: []
tags:
  - name: Projects
    description: >-
      Create and manage calculation projects. Each user can have multiple
      projects to organize their calculations.
  - name: Sheets
    description: >-
      Manage individual calculation sheets — read one back, update its inputs,
      solve or re-solve it, and delete single sheets or clean up many at once.
  - name: Templates
    description: >-
      Run calculations using any enabled template. Supports all calculator types
      without requiring endpoint-specific code.
paths:
  /v1/templates/{code}/calculate:
    post:
      tags:
        - Templates
      summary: Run a calculation using a template
      description: >-
        Validates inputs against template widget definitions, creates a
        calculation sheet, solves it, and returns results.


        Running many designs at once? [Bulk
        Calculate](/api/calculators-generic#bulk-calculate) runs up to 100 in
        one call instead of one call per design.
      operationId: template-calculate
      parameters:
        - name: Authorization
          in: header
          required: true
          example: Bearer YOUR_KEY_HERE
          schema:
            type: string
          description: >-
            The `Authorization` header is used to authenticate with the API
            using your API key. Value is of the format `Bearer YOUR_KEY_HERE`.
        - name: code
          in: path
          required: true
          schema:
            type: string
          description: >-
            Template code, as returned by `GET /v1/templates` (e.g.
            `steelConnectionHssBeamToHssMomentAISC360-22`).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - projectId
                - attributes
              properties:
                projectId:
                  type: string
                  description: Project UUID to create the sheet in
                preset:
                  type: string
                  description: >-
                    Optional preset code to apply defaults before user
                    attributes
                name:
                  type: string
                  description: Optional name for the created sheet
                attributes:
                  type: object
                  description: >-
                    Input values keyed by referenceId — the keys are the
                    fields[].referenceId values from GET /v1/templates/{code}.
                    Send each number as a string tagged with the field's
                    published units, for example "24 ft" (a field whose units
                    are null takes a plain number, and so do a few that list
                    units, such as a roof slope listed as ":12"; a tagged value
                    there is refused with a 422 that asks for the plain number),
                    a list of rows for table fields (each row an array of values
                    in columns[] order, numbers tagged the same way), and for
                    enum fields an entry of that field's options copied exactly
                    as published — including any leading or trailing whitespace,
                    which can be the only thing separating two different
                    options. Almost every option is a string; a few fields
                    publish numbers, and those are accepted either as the number
                    or as its string. Omitted fields fall back to the template's
                    defaults (or the chosen preset's).
                  additionalProperties: true
      responses:
        '201':
          description: Calculation completed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  sheetId:
                    type: string
                    description: Unique identifier for the created calculation sheet
                  projectId:
                    type: string
                    format: uuid
                    description: The project the sheet was created in.
                  sheetUrl:
                    type: string
                    format: uri
                    description: >-
                      Direct link to the sheet in the Calcs.com app. Always
                      present on a successful response.
                  templateCode:
                    type: string
                    description: Template code that was used
                  inputs:
                    type: object
                    description: >-
                      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.
                    additionalProperties:
                      type: object
                      required:
                        - value
                        - label
                        - units
                      properties:
                        value:
                          description: >-
                            The resolved value the calculation used, in stored
                            form
                        label:
                          type:
                            - string
                            - 'null'
                          description: >-
                            Human-readable label of the field, not of its value.
                            For an enum this is the field's own name — nothing
                            in this response names the option that value
                            encodes, so it cannot be recovered here. Read the
                            sheet with GET /v1/sheets/{sheetId} to get that
                            option as its label.
                        units:
                          type:
                            - string
                            - 'null'
                          description: >-
                            Units of the field value, matching fields[].units in
                            the template schema; null when the template declares
                            none
                  results:
                    type: object
                    description: >-
                      Calculation results keyed by referenceId. The keys come
                      from the template schema's outputs[] (GET
                      /v1/templates/{code}), and a given calculation returns the
                      subset of those that apply to the inputs you sent. Value
                      shape depends on the output kind: numbers, booleans,
                      strings (including multi-sentence guidance text), and
                      arrays of row objects, which may be empty. Numeric values
                      are returned unrounded.
                  passed:
                    type:
                      - boolean
                      - 'null'
                    deprecated: true
                    description: >-
                      Deprecated: read `summaryCheckStatus` for the verdict.
                      `passed` is not this calculation's verdict: a failing
                      calculation can report `true`, even on its first solve, or
                      `null`.
                  summaryCheck:
                    description: >-
                      Value of the template's governing summary check — a
                      pass/fail boolean or a numeric utilisation, depending on
                      the template. Absent when the check could not be
                      evaluated; `true` when the template defines no governing
                      check. Read the verdict from `summaryCheckStatus`.
                  summaryCheckReferenceId:
                    type: string
                    description: >-
                      referenceId of the governing check. Present with
                      summaryCheck.
                  summaryCheckError:
                    type: boolean
                    description: >-
                      True when the summary check could not be evaluated.
                      Present when the template defines a summary check.
                  summaryCheckFailReasons:
                    type: array
                    items:
                      type: string
                    description: Reasons the summary check failed. Present only on failure.
                  summaryCheckStatus:
                    type: string
                    enum:
                      - pass
                      - fail
                      - error
                      - not_evaluated
                    description: >-
                      Verdict of the template's governing check for this
                      calculation. `pass`: the check passed (`summaryCheck` is
                      `true`, or a number from 0 to 1). `fail`: the check
                      evaluated and failed (`false`, or a number outside 0 to
                      1). `error`: the check could not be evaluated —
                      `summaryCheckError` is `true`, or the solve produced no
                      value for a check the template defines; treat it as not
                      passing. `not_evaluated`: the template defines no
                      governing check.
                  warnings:
                    type: array
                    items:
                      type: object
                      properties:
                        field:
                          type: string
                        message:
                          type: string
                        type:
                          type: string
                    description: >-
                      Non-blocking validation warnings, present when any were
                      raised. Unrecognised attribute names are returned as a 422
                      instead.
        '400':
          description: >-
            The gateway could not read the request envelope — the body is not a
            JSON object, `projectId` is missing or not a UUID, or `attributes`
            is missing. Those responses use the shape below. A calculation is
            also rejected with `400` by the upstream service for an unrecognised
            `preset`, an `attributes` value that is not an object, too many
            attributes, or an archived project; those bodies are passed through
            unchanged and do **not** all use this shape. A field value that
            fails validation is reported as `422`, not here.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
              examples:
                missing_project_id:
                  summary: projectId is absent from the request body
                  value:
                    error:
                      code: VALIDATION_ERROR
                      message: projectId is required
                invalid_project_id:
                  summary: projectId is present but is not a UUID
                  value:
                    error:
                      code: VALIDATION_ERROR
                      message: projectId must be a UUID.
                missing_attributes:
                  summary: attributes is absent, or is not an object
                  value:
                    error:
                      code: VALIDATION_ERROR
                      message: attributes object is required
        '404':
          description: The template does not exist, or is not accessible with this API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                not_found:
                  summary: >-
                    Template does not exist, or is not accessible with this API
                    key
                  value:
                    error:
                      code: NOT_FOUND
                      message: Template not found.
        '422':
          description: >-
            The calculation could not be completed as requested. A field-level
            failure rejects the request before any sheet is created. The other
            two causes — attribute names that were not recognised, and a
            calculation that returned no results — are reported after the sheet
            exists, and carry its `sheetId`.
          content:
            application/json:
              schema:
                oneOf:
                  - title: Field validation failure (no sheet created)
                    type: object
                    required:
                      - valid
                      - errors
                      - warnings
                    properties:
                      valid:
                        type: boolean
                        description: Always false on this response
                      errors:
                        type: array
                        items:
                          type: object
                          required:
                            - field
                            - error
                            - type
                          properties:
                            field:
                              type: string
                              description: referenceId of the rejected field
                            error:
                              type: string
                              description: Human-readable reason
                            type:
                              type: string
                              description: >-
                                Machine-readable reason kind (e.g. invalid_type,
                                invalid_option)
                            label:
                              type: string
                              description: Field label, where the field resolved
                            value:
                              description: The rejected value, where applicable
                      warnings:
                        type: array
                        items:
                          type: object
                          properties:
                            field:
                              type: string
                            message:
                              type: string
                            type:
                              type: string
                        description: Non-blocking issues found alongside the errors
                  - title: Sheet created, but the result was not usable
                    type: object
                    required:
                      - error
                    properties:
                      error:
                        type: object
                        required:
                          - code
                          - message
                          - sheetId
                        properties:
                          code:
                            type: string
                            description: Always CALCULATION_ERROR on this response
                          message:
                            type: string
                            description: >-
                              Which of the two causes applied: attribute names
                              that were not recognised, or a calculation that
                              returned no results.
                          warnings:
                            type: array
                            description: >-
                              Present only when the failure is unrecognised
                              attribute names, and it then lists them. The
                              no-results failure never carries this key.
                            items:
                              type: object
                              required:
                                - field
                                - message
                                - type
                              properties:
                                field:
                                  type: string
                                message:
                                  type: string
                                type:
                                  type: string
                          sheetId:
                            type: string
                            description: >-
                              The sheet the calculation created before the
                              rejection
              examples:
                invalid_value:
                  summary: A field value fails validation — nothing is created
                  value:
                    valid: false
                    errors:
                      - field: W
                        label: Horizontal Distance From Eave to Ridge
                        value: not a number
                        error: Expected a number, got 'not a number'
                        type: invalid_type
                    warnings: []
                unknown_attribute:
                  summary: >-
                    An attribute name is not a field referenceId — the sheet
                    exists, use the template schema's fields[]
                  value:
                    error:
                      code: CALCULATION_ERROR
                      message: >-
                        Calculation completed but some attributes were not
                        recognized. Use widget reference IDs from the template,
                        not API field names.
                      warnings:
                        - field: bogus_field
                          message: Unknown field 'bogus_field' - will be ignored
                          type: unknown_field
                      sheetId: 662f0b28-3c2e-4dae-a61b-1bdfa367373b
                no_results:
                  summary: >-
                    The calculation returned nothing — the sheet exists but has
                    no results
                  value:
                    error:
                      code: CALCULATION_ERROR
                      message: >-
                        Calculation produced no results. This usually means
                        required inputs are missing, or none of the template's
                        outputs applied to them.
                      sheetId: 662f0b28-3c2e-4dae-a61b-1bdfa367373b
      security:
        - api_key: []
components:
  schemas:
    ValidationError:
      type: object
      description: Validation error response for invalid API inputs
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - VALIDATION_ERROR
              description: Error code for validation failures
            message:
              type: string
              description: Human-readable error summary
              example: Input validation failed
            details:
              type: array
              description: Array of specific validation errors
              items:
                type: object
                properties:
                  field:
                    type: string
                    description: Path to the invalid field (e.g., 'L_X', 'supports.0.2')
                  message:
                    type: string
                    description: Description of what's wrong with the field
                required:
                  - field
                  - message
          required:
            - code
            - message
      required:
        - error
      example:
        error:
          code: VALIDATION_ERROR
          message: Input validation failed
          details:
            - field: L_X
              message: Expected number, received string
            - field: supports
              message: At least 2 supports are required
    ErrorResponse:
      type: object
      description: >-
        Standard error envelope for handler errors. `code` is a stable
        machine-readable error code (e.g. NOT_FOUND, UPSTREAM_ERROR); `message`
        is human-readable and may change.
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: Machine-readable error code.
            message:
              type: string
              description: Human-readable error message.
          required:
            - code
            - message
      required:
        - error
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Send your API key as a bearer token: `Authorization: Bearer
        YOUR_API_KEY`. Every endpoint requires one.
    api_key:
      type: http
      scheme: bearer

````

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