# API reference [#api-reference]

Use this page when you need the current HTTP route list and the generated
reference source.

## Generated reference [#generated-reference]

The endpoint contract is generated from `@taxkit/api-http`.

```txt
GET /api/docs
GET /api/docs/openapi.json
```

Use `/api/docs/openapi.json` as the field-level source of truth for generated
clients and endpoint reference pages.

## Current routes [#current-routes]

| Method | Path                                          | Use                                                          |
| ------ | --------------------------------------------- | ------------------------------------------------------------ |
| `GET`  | `/api/health`                                 | Check the API process.                                       |
| `GET`  | `/api/v1/jurisdictions`                       | List supported public jurisdictions.                         |
| `GET`  | `/api/v1/tax-years`                           | List supported calculator tax years.                         |
| `GET`  | `/api/v1/calculators`                         | List public calculator catalogue entries.                    |
| `GET`  | `/api/v1/calculators/:calculatorId`           | Read one calculator metadata entry.                          |
| `GET`  | `/api/v1/calculators/:calculatorId/schema`    | Read input facts, output facts and rules for one calculator. |
| `POST` | `/api/v1/calculators/:calculatorId/calculate` | Run one calculator with a `CalculatorRunRequest`.            |
| `GET`  | `/api/v1/calculators/:calculatorId/graph`     | Read the calculator fact and rule graph.                     |
| `GET`  | `/api/v1/facts`                               | List public fact descriptor metadata.                        |
| `GET`  | `/api/v1/rules`                               | List public rule descriptor metadata.                        |

## Calculate route [#calculate-route]

The calculate route calls the calculator service directly.

```ts
Production: HTTP calculate

HTTP caller
  -> @taxkit/api-http route contract
    -> CalculatorApiHandlerLive
      -> PublicCalculatorService.calculate
        -> CalculationEngine
      -> CalculatorApiErrorEnvelope for CalculatorServiceError
```

## Owning sources [#owning-sources]

* API definition: [`packages/api/http/src/api.ts`](https://github.com/crcorbett/taxkit/blob/a151e51e8a30247526fa93412df046955846eca4/packages/api/http/src/api.ts)
* Calculator group: [`packages/api/http/src/groups/calculators.ts`](https://github.com/crcorbett/taxkit/blob/a151e51e8a30247526fa93412df046955846eca4/packages/api/http/src/groups/calculators.ts)
* API runtime: [`apps/api/src/server.ts`](https://github.com/crcorbett/taxkit/blob/a151e51e8a30247526fa93412df046955846eca4/apps/api/src/server.ts)

## Used by [#used-by]

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