# OpenAPI reference [#openapi-reference]

Use generated OpenAPI for endpoint paths, parameters, request bodies and
response schemas. Narrative API pages explain when to use HTTP, how errors
work and how the API relates to the SDK.

## Generated source [#generated-source]

The current API package generates the OpenAPI document from
`@taxkit/api-http` route definitions. The API app serves it at:

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

The local Scalar viewer is served at:

```txt
GET /api/docs
```

## Smoke check [#smoke-check]

Run the API locally, then fetch the generated document:

```sh
bun run --filter=api start
curl http://127.0.0.1:4000/api/docs/openapi.json
```

The document should include the calculate path and `CalculatorRunRequest`
payload schema. Use this generated document for clients and endpoint reference
pages rather than copying endpoint fields by hand.

```txt
/api/v1/calculators/{calculatorId}/calculate
CalculatorRunRequest
```

## Review the contract in the repository [#review-the-contract-in-the-repository]

You can also read the
[checked OpenAPI snapshot](https://github.com/crcorbett/taxkit/blob/a151e51e8a30247526fa93412df046955846eca4/packages/api/http/__snapshots__/openapi.json).
The API package's snapshot test regenerates the contract from its route
definitions. Run it when changing an endpoint:

```sh
bun run --filter=@taxkit/api-http test:openapi
```

## Related pages [#related-pages]

* [Endpoints](/api/endpoints)
* [API overview](/api/overview)
* [API and SDK architecture](https://github.com/crcorbett/taxkit/blob/a151e51e8a30247526fa93412df046955846eca4/docs/architecture/api-and-sdk.md)