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

# Bulk Calculate

> Create and solve up to 100 sheets in one project in a single call. The request is accepted whole or rejected whole: if any item is invalid, `422` lists every item's errors and nothing is created. On `201` the sheets are being created and solved; poll the `Location` header until `state` is `completed` or `failed`. One batch runs per project at a time: a request while one is running returns `409` naming the batch to poll.



## OpenAPI

````yaml api/openapi.json POST /v1/sheets/bulk-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/sheets/bulk-calculate:
    post:
      tags:
        - Templates
      summary: Bulk Calculate
      description: >-
        Create and solve up to 100 sheets in one project in a single call. The
        request is accepted whole or rejected whole: if any item is invalid,
        `422` lists every item's errors and nothing is created. On `201` the
        sheets are being created and solved; poll the `Location` header until
        `state` is `completed` or `failed`. One batch runs per project at a
        time: a request while one is running returns `409` naming the batch to
        poll.
      operationId: bulk-calculate-sheets
      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`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkCalculateRequest'
      responses:
        '201':
          description: The batch was accepted and is being processed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchStatus'
              examples:
                accepted:
                  summary: Three items accepted
                  value:
                    batchId: 5ab97d3e-0030-4eaa-8c40-99057f2051f6
                    type: bulk-calculate
                    state: processing
                    progressPercent: 0
                    projectId: 56b9335c-6859-4978-a6ec-33d780599c23
                    itemCount: 3
                    summary:
                      total: 3
                      solved: 0
                      errored: 0
                      stale: 0
                      checkErrored: 0
                      pending: 3
                    createdAt: '2026-10-19T08:20:27.895Z'
                    completedAt: null
                    durationSeconds: null
                    error: null
                    items: null
          headers:
            Location:
              description: >-
                Where to poll for the batch's status: `GET
                /v1/projects/{projectId}/batches/{batchId}`. Present while the
                batch is still running.
              schema:
                type: string
            Retry-After:
              description: >-
                Seconds to wait before polling again. Present while the batch is
                still running.
              schema:
                type: integer
        '400':
          description: The request body is not valid JSON.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
              examples:
                invalid_json:
                  summary: Request body is not valid JSON
                  value:
                    error:
                      code: VALIDATION_ERROR
                      message: Invalid JSON in request body.
        '401':
          description: Unauthorized — missing or invalid API key.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              examples:
                unauthorized:
                  summary: Missing or invalid API key
                  value:
                    type: https://httpproblems.com/http-status/401
                    title: Unauthorized
                    status: 401
                    detail: No Authorization Header
                    instance: /v1/sheets/bulk-calculate
                    trace:
                      timestamp: '2026-09-23T04:45:09.937Z'
                      requestId: 52d271c1-8ab2-43f5-bb30-6ae1fa19d049
                      buildId: 61df8eb1-785b-4400-b31c-18f30edb3f5e
                      rayId: a3f6e5f90d2b41c5
        '404':
          description: The project does not exist, or is not accessible with this API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                not_found:
                  summary: >-
                    Project does not exist, or is not accessible with this API
                    key
                  value:
                    error:
                      code: NOT_FOUND
                      message: project not found
        '409':
          description: >-
            A batch is already running for this project. Poll it and retry once
            it is terminal.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchRequestError'
              examples:
                batch_in_progress:
                  summary: A batch is already running for this project
                  value:
                    error:
                      code: BATCH_IN_PROGRESS
                      message: This project already has a bulk calculation in progress.
                      details:
                        - field: batchId
                          message: 5ab97d3e-0030-4eaa-8c40-99057f2051f6
        '422':
          description: >-
            The request was rejected and nothing was created: an item or field
            failed validation, `items` exceeded the cap, or the project is
            archived.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchRequestError'
              examples:
                validation_error:
                  summary: Two items invalid, every problem reported in one pass
                  value:
                    error:
                      code: VALIDATION_ERROR
                      message: Invalid bulk calculate request.
                      details:
                        - field: items[1].templateCode
                          message: No template found with that code.
                        - field: items[2].attributes
                          message: attributes must be a JSON object.
                too_many_items:
                  summary: More than 100 items
                  value:
                    error:
                      code: TOO_MANY_ITEMS
                      message: Invalid bulk calculate request.
                      details:
                        - field: items
                          message: Too many items (maximum 100).
      security:
        - api_key: []
components:
  schemas:
    BulkCalculateRequest:
      type: object
      description: A batch of sheets to create and solve in one project.
      required:
        - projectId
        - items
      properties:
        projectId:
          type: string
          format: uuid
          description: Project the sheets are created in.
        items:
          type: array
          minItems: 1
          maxItems: 100
          items:
            $ref: '#/components/schemas/BulkCalculateItem'
          description: >-
            The sheets to create and solve, 1 to 100. Reported back in this
            order.
    BatchStatus:
      type: object
      description: >-
        A bulk-calculate batch. The same body is returned when the batch is
        accepted and on every poll; `items` is `null` until `state` is terminal.
        Clients must tolerate `state` values not listed here.
      required:
        - batchId
        - type
        - state
        - progressPercent
        - projectId
        - itemCount
        - summary
        - createdAt
        - completedAt
        - durationSeconds
        - error
        - items
      properties:
        batchId:
          type: string
          format: uuid
          description: Identifier to poll.
        type:
          type: string
          description: Always `bulk-calculate`.
        state:
          type: string
          description: >-
            `processing` while sheets are being created and solved. `completed`
            once every item has an outcome; items that could not be solved carry
            their own `error`, so a completed batch can have `summary.solved` of
            0. `failed` when the batch itself could not run, or when it stopped
            before finishing and will not resume (see `error`). Treat an
            unrecognised value as still in progress.
        progressPercent:
          type: integer
          minimum: 0
          maximum: 100
          description: >-
            Whole-number share of the batch's own sheets solved so far, 0 to
            100, while `processing`. Set to 100 when the batch reaches
            `completed`, whatever `summary.solved` is; read `summary` for the
            outcome. Frozen where it stopped when `failed`.
        projectId:
          type: string
          format: uuid
        itemCount:
          type: integer
          description: Number of items requested.
        summary:
          type: object
          required:
            - total
            - solved
            - errored
            - stale
            - checkErrored
            - pending
          description: >-
            Counts over the items. `pending` is `total - solved - errored -
            stale` and is 0 once the batch is terminal, where every item is
            solved or carries an `error`. The three non-solved counters answer
            different questions and are never folded together, because the
            remedy differs: `errored` counts items the batch could not produce
            results for, where retrying is the fix; `stale` counts items it did
            solve whose inputs have changed since, where nothing failed and
            re-solving the sheet is the fix; `checkErrored` counts items that
            solved but whose governing check produced no verdict, and those are
            also counted in `solved`. To confirm every item is usable, check
            `errored`, `stale` and `checkErrored` are all 0. `state` is the
            completion signal. While `processing` the counts are progress, and
            `pending` can read 0 in the moments between the last sheet solving
            and the batch reaching a terminal state; do not use it to detect
            completion. On a terminal batch the counters are recomputed from the
            sheets' current state on every poll, so the same `batchId` can
            report different counts later if its sheets are edited or deleted.
          properties:
            total:
              type: integer
            solved:
              type: integer
            errored:
              type: integer
              description: >-
                Items the batch could not produce results for: the solver
                refused the sheet, the sheet is gone, or the batch stopped
                before reaching it. Retrying is the remedy.
            stale:
              type: integer
              description: >-
                Items the batch solved whose inputs have changed since, so the
                stored results no longer describe them. Not a failure — usually
                the caller edited the sheet themselves — and counted separately
                from `errored` so their own edit is not reported back as a batch
                failure. Re-solve the sheet, or resubmit the item.
            checkErrored:
              type: integer
              description: >-
                Items that solved but whose governing check produced no verdict:
                the items whose `summaryCheckStatus` is `error`. Counted
                separately from `errored`, and never folded into it: these items
                have current results, they just have no verdict to read.
            pending:
              type: integer
        createdAt:
          type: string
          format: date-time
        completedAt:
          type:
            - string
            - 'null'
          format: date-time
          description: '`null` until the batch is terminal.'
        durationSeconds:
          type:
            - number
            - 'null'
          description: >-
            How long the batch took. Set when the batch reached a terminal state
            and the duration was recorded; `null` otherwise. A batch the worker
            had to mark failed as a last resort can be `failed` with
            `durationSeconds` null.
        error:
          oneOf:
            - $ref: '#/components/schemas/BatchError'
            - type: 'null'
          description: >-
            Why the batch itself failed. Set when the batch failed and the
            reason was recorded; `null` otherwise. A batch the worker had to
            mark failed as a last resort can be `failed` with `error` null.
        items:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/BatchItem'
          description: >-
            One entry per requested item, in request order. `null` until the
            batch is terminal.
    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
    ProblemDetails:
      type: object
      description: >-
        RFC 7807 (`application/problem+json`) error returned by the API gateway
        before a request reaches the handler — currently authentication failures
        (401). Note this differs from the `{ error: { code, message, details }
        }` envelope returned by the handler for validation and not-found errors.
      properties:
        type:
          type: string
          format: uri
          description: URI identifying the problem type.
        title:
          type: string
          description: Short, human-readable summary of the problem type.
        status:
          type: integer
          description: HTTP status code.
        detail:
          type: string
          description: Human-readable explanation specific to this occurrence.
        instance:
          type: string
          description: The request path that produced the error.
        trace:
          type: object
          description: >-
            Gateway trace metadata for support (timestamp, requestId, buildId,
            rayId).
      required:
        - type
        - title
        - status
        - detail
    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
    BatchRequestError:
      type: object
      description: >-
        Why a bulk-calculate request was rejected. `code` says which rule the
        request broke, in the same `error` envelope every other rejected request
        returns.
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: >-
                Machine-readable reason the request was rejected.
                `VALIDATION_ERROR`: an item or a top-level field failed
                validation; each per-item `details[].field` is prefixed
                `items[i].` for the item it belongs to, and a top-level field
                such as `projectId` is unprefixed. `TOO_MANY_ITEMS`: `items`
                exceeded the cap. `BATCH_IN_PROGRESS`: another batch is already
                running for this project, and `details` carries one entry,
                `field: "batchId"`, whose `message` is that batch's id. Clients
                must tolerate codes not listed here.
            message:
              type: string
              description: Human-readable error summary.
            details:
              type: array
              description: >-
                One entry per reason the request was rejected. Absent when there
                is nothing to name.
              items:
                type: object
                properties:
                  field:
                    type: string
                    description: >-
                      What the entry is about: an item's own field as
                      `items[i].attributes`, a top-level request field as
                      `projectId`, or `batchId` when another batch is already
                      running.
                  message:
                    type: string
                    description: >-
                      What is wrong with that field, or the id of the batch to
                      poll when another batch is already running.
                required:
                  - field
                  - message
          required:
            - code
            - message
      required:
        - error
    BulkCalculateItem:
      type: object
      description: >-
        One sheet to create and solve. `templateCode` and `attributes` are what
        `POST /v1/templates/{code}/calculate` takes; `ref` is echoed on the
        item's status so results can be matched back without relying on order.
      required:
        - templateCode
        - attributes
      properties:
        ref:
          type: string
          maxLength: 64
          description: >-
            Your own identifier for this item, echoed on its status. Must be
            unique within the batch when given.
        templateCode:
          type: string
          description: Template to create the sheet from.
        name:
          type: string
          description: >-
            Sheet name. Defaults to the template name plus the item's `ref` or
            position.
        preset:
          type: string
          description: A preset code of the template to apply before `attributes`.
        attributes:
          type: object
          additionalProperties: true
          description: >-
            Input values keyed by widget reference ID, as for a single
            calculate. Required on every item: unlike a single calculate, a
            batch item that sends none is refused.
    BatchError:
      type: object
      required:
        - code
        - message
      description: >-
        A batch-level failure. `code` is `VALIDATION_CHANGED` when a template
        became unavailable between acceptance and processing, `BATCH_FAILED`
        when the batch could not be run, or `BATCH_ABANDONED` when it stopped
        before finishing and will not resume — resubmit its items. Treat an
        unrecognised code as a failure to retry.
      properties:
        code:
          type: string
        message:
          type: string
    BatchItem:
      type: object
      description: >-
        One requested item's outcome: the sheet as `GET /v1/sheets/{sheetId}`
        returns it, plus `ref`, and `error` when it has no results. `inputs` is
        absent both when the sheet was never created (`sheetId` is `null`) and
        when its template is no longer accessible. `sheetUrl` is absent only
        when the sheet was never created.
      required:
        - ref
        - sheetId
        - projectId
        - templateCode
        - status
      properties:
        ref:
          type:
            - string
            - 'null'
          description: The `ref` sent for this item, or `null` if none was.
        sheetId:
          type:
            - string
            - 'null'
          format: uuid
          description: '`null` when no sheet was created for this item.'
        projectId:
          type: string
          format: uuid
        templateCode:
          type: string
        status:
          type: string
          enum:
            - solved
            - unsolved
          description: >-
            `solved` when `results` were computed from the inputs the sheet
            holds now. Any item that is not `solved` carries `error`.
        inputs:
          type: object
          additionalProperties: true
          description: As on `GET /v1/sheets/{sheetId}`.
        sheetUrl:
          type: string
          format: uri
          description: Link to the sheet in the Calcs.com app.
        passed:
          type:
            - boolean
            - 'null'
          deprecated: true
          description: >-
            Deprecated: read `summaryCheckStatus` for the verdict. `passed` is
            not this batch's verdict: a failing calculation can report `true`,
            even on its first solve, or `null`. Present when solved.
        results:
          type: object
          additionalProperties: true
          description: As on `GET /v1/sheets/{sheetId}`. Present when solved.
        summaryCheck:
          type:
            - number
            - boolean
          description: >-
            Value of the template's governing check for the last solve. Absent
            when the check could not be evaluated (`summaryCheckStatus` is
            `error`). A template that defines no governing check reports `true`
            here, so read the verdict from `summaryCheckStatus`, which tells the
            two apart (`not_evaluated`).
        summaryCheckReferenceId:
          type: string
          description: Reference ID of the widget `summaryCheck` came from.
        summaryCheckError:
          type: boolean
          description: >-
            Whether the governing check could not be evaluated. A check in error
            has no verdict and carries no `summaryCheck`; the item is still
            reported as solved, and `summary.checkErrored` counts it.
        summaryCheckFailReasons:
          type: array
          items:
            type: string
          description: >-
            Why the governing check failed. Present only when the check
            evaluated and failed; absent when it passed and when it errored.
        summaryCheckStatus:
          type: string
          enum:
            - pass
            - fail
            - error
            - not_evaluated
          description: >-
            Verdict of the template's governing check for the last solve.
            `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. Present
            when solved.
        warnings:
          type: array
          description: >-
            Non-fatal findings against the attributes sent for this item, as a
            single calculate reports them. Absent when there is nothing to
            report, and withheld on an item whose template is no longer
            accessible.
          items:
            type: object
            properties:
              field:
                type: string
                description: The attribute key that was not applied.
              message:
                type: string
                description: What was wrong with it.
              type:
                type: string
                description: >-
                  Machine-readable reason: `unknown_field` for a key matching no
                  widget on the template, `null_value` for an explicit `null`
                  (skipped, not treated as a clear).
        error:
          $ref: '#/components/schemas/BatchItemError'
    BatchItemError:
      type: object
      required:
        - code
        - message
      description: >-
        Why one item has no results. `SOLVE_FAILED`: the solver could not answer
        this sheet. `RESULTS_STALE`: the batch solved this sheet, but its inputs
        have changed since (edited in the app, patched through the API, the
        project's defaults changed, or the sheet was upgraded), so the results
        no longer match. Solve the sheet again or resubmit the item.
        `SHEET_UNAVAILABLE`: the item has no sheet to report, either because it
        was deleted after the batch ran or because the batch died before
        creating it without recording a reason. `TEMPLATE_NOT_FOUND`: the
        template is no longer accessible with this API key. A batch-level code
        (`BATCH_FAILED`, `VALIDATION_CHANGED`, `BATCH_ABANDONED`) appears here
        when the batch stopped before this item was finished. Treat an
        unrecognised code as a failure.
      properties:
        code:
          type: string
        message:
          type: string
  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.