# API reference (v1)

Base URL: `https://tttkmbb.com/api/v1`. All responses are JSON (UTF-8) with `Access-Control-Allow-Origin: *`. No authentication. Version is part of the path; field meanings never change within a version.

## Endpoints

| Method | Path | operationId | Purpose |
| --- | --- | --- | --- |
| GET | `/api/v1` | `get_api_index` | Endpoint index |
| GET | `/api/v1/status` | `get_service_status` | Service status, version, counts |
| GET | `/api/v1/categories` | `list_calculator_categories` | Categories with counts |
| GET | `/api/v1/calculators?category=&query=` | `list_calculators` | List calculators (optionally filtered) |
| GET | `/api/v1/search?query=` | `search_calculators` | Ranked search over names, tags and descriptions |
| GET | `/api/v1/calculators/{calculator_id}` | `get_calculator_schema` | Full definition: inputs, outputs, formula, sources, examples |
| GET | `/api/v1/calculate/{calculator_id}?…` | `calculate_<id>` | Run a calculator with query parameters |
| POST | `/api/v1/calculate/{calculator_id}` | `run_calculator` | Run with JSON body `{"inputs": {…}}` (or a flat object) |
| GET | `/api/v1/convert?value=&from_unit=&to_unit=` | `convert_units` | Convert between any two units of the same quantity |
| GET | `/api/v1/units` | `list_units` | All supported units by quantity |
| GET | `/api/v1/tasks/{task_id}` | `get_task` | Re-derive a completed calculation from a content-addressed task id |

## Parameters

Parameter names are descriptive snake_case with the unit in the name where relevant (`weight_kg`, `annual_rate_percent`). Percentages are plain percent numbers (6.5 means 6.5 %). Dates are ISO 8601 (`2026-09-23`). Lists are comma-separated in query strings (`values=1,2,3`) or JSON arrays in POST bodies. Unknown parameters are ignored and reported in `warnings`.

## Content negotiation

Each calculator also exists as HTML (`/{category}/{id}`), Markdown (`/{category}/{id}.md`) and JSON definition (`/{category}/{id}.json`). Adding query parameters to the `.json` URL returns the calculation result.

## Versioning

- Current: `v1`. Breaking changes will ship as `/api/v2` with `v1` kept for at least 12 months.
- Every response carries `"version": "v1"`; MCP tool names and input schemas are stable within a version.

See also: [response format](https://tttkmbb.com/docs/response-format.md), [errors](https://tttkmbb.com/docs/errors.md), [rate limits](https://tttkmbb.com/docs/rate-limits.md), [OpenAPI](https://tttkmbb.com/openapi.json).