# API overview [#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](/start/choose-sdk-or-api).

## Use HTTP when [#use-http-when]

| Caller need                                | Use                                         |
| ------------------------------------------ | ------------------------------------------- |
| Server-side TypeScript calculation         | [Plain SDK](/sdk/plain-sdk)                 |
| Effect application or in-process transport | [Effect SDK](/sdk/effect-sdk)               |
| Browser calculation on a server            | HTTP API                                    |
| Browser calculation on the device          | [Plain SDK](/sdk/plain-sdk)                 |
| Non-TypeScript caller                      | HTTP API                                    |
| Generated endpoint contract                | [OpenAPI reference](/api/openapi-reference) |

## Runtime model [#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.

```ts
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 [#request-model]

Calculation requests use `CalculatorRunRequest`:

```json
{
  "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 [#related-pages]

* [Endpoints](/api/endpoints)
* [Errors](/api/errors)
* [OpenAPI reference](/api/openapi-reference)
* [Build a browser app with the HTTP API](/guides/build-a-browser-app-with-the-http-api)