Developer reference

Calculation API

Version 1 exposes the same deterministic engine operations used by calculator pages. Send JSON with an explicit mode and units; responses include version and request metadata.

Request contract

Send POST requests with Content-Type: application/json. Anonymous request policy is provisional. Bodies are read incrementally with a 16 KB limit before schema and operation-specific complexity validation.

`POST /api/v1/formula`

Parse and normalize a molecular formula.

Request

{
  "formula": "C8H10N4O2"
}

Response data

{
  "canonicalFormula": "C8H10N4O2",
  "charge": "0",
  "elements": {
    "C": "8",
    "H": "10",
    "N": "4",
    "O": "2"
  },
  "explicitNuclides": {},
  "totalAtoms": "24",
  "versions": {
    "formulaEngine": "0.1.0"
  }
}

`POST /api/v1/molecular-weight`

Calculate average, exact, monoisotopic, and nominal formula masses.

Request

{
  "formula": "C8H10N4O2"
}

Response data

{
  "averageMolecularMass": "194.194",
  "dataVersions": {
    "PubChem-periodic-table+NIST-isotopes": "2026-08-28"
  },
  "elementMassPercentages": {
    "C": "49.480416490725769076",
    "H": "5.1906856030567370774",
    "N": "28.851560810323696922",
    "O": "16.477337095893796925"
  },
  "exactMass": "194.08037557916",
  "molarMassGramsPerMole": "194.194",
  "monoisotopicMass": "194.08037557916",
  "nominalMass": "194",
  "totalAtoms": "24",
  "versions": {
    "formulaEngine": "0.1.0"
  }
}

`POST /api/v1/balance`

Balance a reaction using exact rational conservation.

Request

{
  "equation": "H2 + O2 -> H2O"
}

Response data

{
  "coefficients": [
    "2",
    "1",
    "2"
  ],
  "equation": "2 H2 + O2 → 2 H2O",
  "rowLabels": [
    "H",
    "O"
  ],
  "rows": [
    [
      "2",
      "0",
      "-2"
    ],
    [
      "0",
      "2",
      "-1"
    ]
  ],
  "versions": {
    "equationEngine": "0.1.0"
  }
}

`POST /api/v1/molarity`

Solve one explicit molarity mode with typed units.

Request

{
  "amountUnit": "mol",
  "mode": "moles-volume",
  "moles": "1",
  "volume": "2",
  "volumeUnit": "L"
}

Response data

{
  "molarityMolesPerLiter": "0.5",
  "moles": "1",
  "steps": [
    "Normalized amount to moles and volume to liters.",
    "Applied M = n / V to the moles-volume solve mode."
  ],
  "versions": {
    "solutionEngine": "0.1.0",
    "unitEngine": "0.1.0"
  },
  "volumeLiters": "2"
}

`POST /api/v1/dilution`

Solve one unknown in C1V1 = C2V2.

Request

{
  "concentrationUnit": "M",
  "finalConcentration": "1",
  "finalVolume": "10",
  "stockConcentration": "10",
  "unknown": "stockVolume",
  "volumeUnit": "L"
}

Response data

{
  "diluentVolumeLiters": "9",
  "finalConcentrationMolesPerLiter": "1",
  "finalVolumeLiters": "10",
  "stockConcentrationMolesPerLiter": "10",
  "stockVolumeLiters": "1",
  "steps": [
    "Normalized concentration and volume units.",
    "Solved stockVolume from C1V1 = C2V2.",
    "Computed diluent as final volume minus stock volume."
  ],
  "versions": {
    "solutionEngine": "0.1.0",
    "unitEngine": "0.1.0"
  }
}

`POST /api/v1/stoichiometry`

Normalize mixed reactant quantities and find the limiting reagent.

Request

{
  "equation": "H2 + O2 -> H2O",
  "productIndex": 0,
  "reactants": [
    {
      "quantity": {
        "mode": "mass",
        "unit": "g",
        "value": "4.032"
      },
      "speciesIndex": 0
    },
    {
      "quantity": {
        "mode": "moles",
        "unit": "mol",
        "value": "2"
      },
      "speciesIndex": 1
    }
  ]
}

Response data

{
  "availableExtentMoles": "1",
  "coefficients": [
    "2",
    "1",
    "2"
  ],
  "equation": "2 H2 + O2 → 2 H2O",
  "excess": [
    {
      "remainingMoles": "1",
      "speciesIndex": 1
    }
  ],
  "limitingReactantIndexes": [
    0
  ],
  "maximumProductMoles": "2",
  "productIndex": 0,
  "versions": {
    "constants": "9.0",
    "equationEngine": "0.1.0",
    "stoichiometryEngine": "0.1.0"
  }
}

Error envelope

Expected input or chemistry issues return a 4xx response. Unexpected failures return a request ID without a stack trace.

{
  "error": {
    "code": "validation_failed",
    "issues": [
      {
        "message": "Formula is required.",
        "path": [
          "formula"
        ]
      }
    ],
    "message": "Request validation failed.",
    "requestId": "00000000-0000-4000-8000-000000000000"
  }
}