# Endpoints [#endpoints]

Use this page to find the current route shape. Use the generated
[OpenAPI reference](/api/openapi-reference) for field-level request and
response detail.

## Current routes [#current-routes]

| Method | Path                                           | Purpose                                                        |
| ------ | ---------------------------------------------- | -------------------------------------------------------------- |
| `GET`  | `/api/health`                                  | Check the API process.                                         |
| `GET`  | `/api/docs`                                    | Open the generated Scalar reference viewer.                    |
| `GET`  | `/api/docs/openapi.json`                       | Read the generated OpenAPI document.                           |
| `GET`  | `/api/v1/jurisdictions`                        | List supported public API jurisdictions.                       |
| `GET`  | `/api/v1/tax-years`                            | List supported tax years, optionally filtered by jurisdiction. |
| `GET`  | `/api/v1/calculators`                          | List calculator catalog entries.                               |
| `GET`  | `/api/v1/calculators/:calculatorId`            | Get one calculator catalog entry.                              |
| `GET`  | `/api/v1/calculators/:calculatorId/schema`     | Get fact, rule and report schema metadata.                     |
| `POST` | `/api/v1/calculators/:calculatorId/calculate`  | Run one calculator through the calculator service.             |
| `GET`  | `/api/v1/calculators/:calculatorId/graph`      | Get graph edges and validation diagnostics.                    |
| `GET`  | `/api/v1/facts`                                | List canonical fact descriptors.                               |
| `GET`  | `/api/v1/rules`                                | List canonical rule descriptors.                               |
| `GET`  | `/api/v1/docs/navigation`                      | Read public documentation navigation.                          |
| `GET`  | `/api/v1/docs/page?path=/start/quickstart`     | Read one public page as JSON.                                  |
| `GET`  | `/api/v1/docs/search?term=Quickstart`          | Search public documentation.                                   |
| `GET`  | `/api/v1/docs/markdown?path=/start/quickstart` | Read one public page as Markdown.                              |

## Calculate [#calculate]

`POST /api/v1/calculators/:calculatorId/calculate` accepts a
`CalculatorRunRequest` payload and returns a `CalculatorRunResponse`.

```sh
curl -X POST \
  http://127.0.0.1:4000/api/v1/calculators/au.pay.take-home/calculate \
  -H 'content-type: application/json' \
  -d '{
    "facts": {
      "grossPay": {
        "_tag": "GrossPay",
        "amount": { "_tag": "Money", "cents": 346200, "currency": "AUD" },
        "period": "fortnightly"
      },
      "taxFreeThresholdClaimed": true
    },
    "jurisdiction": "AU",
    "taxYear": "2025-26"
  }'
```

Expected output includes `calculator.calculatorId: "au.pay.take-home"`,
`report._tag: "TakeHomePayReport"`, `report.withholdingsTotal.cents: 75600`
and `report.netPay.cents: 270600`.

If the request fails, read `CalculatorApiErrorEnvelope.error` and handle the
underlying `CalculatorServiceError`.

## Read public documentation [#read-public-documentation]

Use `path` to select a page address from navigation, such as
`/start/quickstart`. The path accepts up to 256 characters. The page route
returns the page title, description and Markdown in a JSON object. The Markdown
route returns the same page text with `content-type: text/markdown`.

```sh
curl 'http://127.0.0.1:4000/api/v1/docs/markdown?path=/start/quickstart'
```

Search with a `term` of 1 to 100 characters. Each search returns up to 20
results, with a page address, title and excerpt of up to 240 characters.
Use the navigation route to read the section and page links.

See [API errors](/api/errors) for missing-page and invalid-query replies.

## Related pages [#related-pages]

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