API overview

Use the HTTP API when the calculation should run on a server, the caller uses another language or you need an OpenAPI contract. A browser can also use the SDK's browser-safe entrypoints to calculate on the device. Compare the choices in Choose SDK or HTTP API.

Use HTTP when

Runtime model

The API does not own tax logic. It decodes transport input, calls the same calculator service as an in-process SDK consumer, then returns the service result or an HTTP error envelope.

HTTP calculate

HTTP caller
  -> @taxkit/api-http route contract
    -> CalculatorApiHandlerLive
      -> PublicCalculatorService.calculate
        -> CalculationEngine
      -> CalculatorApiErrorEnvelope for expected service errors

The calculate route calls PublicCalculatorService.calculate directly. The service validates facts against the selected calculator, so a payload accepted by the generic HTTP schema can fail if it is for a different calculator.

Request model

Calculation requests use CalculatorRunRequest:

{
  "facts": {
    "grossPay": {
      "_tag": "GrossPay",
      "amount": { "_tag": "Money", "cents": 346200, "currency": "AUD" },
      "period": "fortnightly"
    },
    "taxFreeThresholdClaimed": true
  },
  "jurisdiction": "AU",
  "taxYear": "2025-26"
}

Use canonical tagged values such as GrossPay and Money where the owning schema requires them. The generated OpenAPI document shows supported facts.anyOf shapes for the current public calculators.

Related pages

• Endpoints
• Errors
• OpenAPI reference
• Build a browser app with the HTTP API

Read this page as Markdown