API overview

The public API is an open JSON API that runs the calculators on the server. There is no authentication, no API key is needed, and the endpoints can be called directly from the browser.


Base URL	`https://api.mirac-ozdemir.com`
Public endpoints	`https://api.mirac-ozdemir.com/v1/public/…`
Format	JSON, UTF-8 (`Content-Type: application/json`)
Authentication	None
Machine-readable contract	`/openapi.json` (OpenAPI 3.1)
Status	api.mirac-ozdemir.com

Endpoints

Operation	Endpoint	What it does
`listTools`	`GET /v1/public/tools`	Lists published tools, paginated.
`searchTools`	`GET /v1/public/search`	Searches the tools.
`listCategories`	`GET /v1/public/categories`	Returns the category tree.
`getToolByKey`	`GET /v1/public/tools/by-key/{key}`	Gets a tool definition by `key`.
`calculateByKey`	`POST /v1/public/tools/by-key/{key}/calculate`	Calculates (recommended endpoint).
`getToolBySlug`	`GET /v1/public/tools/by-slug/{locale}/{slug}`	Resolves a tool from its website address.
`calculateTool`	`POST /v1/public/tools/{toolId}/calculate`	Calculates by `toolId`.

The parameters and response schemas of every endpoint are in the API Reference, generated automatically from the contract.

Versioning

The path contains the API version (/v1). Backward-compatible changes (new fields, new optional parameters) are made in the same version; your clients should ignore fields they do not know. Breaking changes are released as a new version (/v2). The API version is independent of the tools’ own versions (versionNumber).

Response envelopes

Successful responses contain data (and meta when needed); errors contain error:

{ "data": { … }, "meta": { … } }
{ "data": [ … ], "meta": { "page": 1, "pageSize": 20, "total": 100, "totalPages": 5 } }
{ "error": { "code": "VALIDATION_ERROR", "message": "…", "details": { … } }, "requestId": "…" }

List endpoints are paginated: page (≥ 1) and pageSize (1–100; at most 50 for search). For the full list of error codes, see the Errors page.

Request ID

Every response carries an X-Request-Id header; error bodies also contain requestId. You can send your own ID in the X-Request-Id header ([A-Za-z0-9._:-], 8–128 characters); if it is invalid, the server generates a new one. Include this value in support requests.

CORS

Public endpoints are open to all origins:

Access-Control-Allow-Origin: *; no cookies or credentials are used.
Allowed methods are GET, POST, OPTIONS; allowed request headers are Content-Type and X-Request-Id.
Readable response headers: X-Request-Id, Retry-After, RateLimit-Limit, RateLimit-Remaining.
Preflight responses are cached for 24 hours.

So you can call directly from your browser app without setting up a proxy.

Caching

Read endpoints (GET) return cacheable responses:

Cache-Control: public, max-age=5, s-maxage=30, stale-while-revalidate=300

Calculation responses come back with Cache-Control: no-store. Cache tool definitions and the category tree on your side too; you do not need to re-read them every time before a calculation. When a definition changes, the version check lets you know (Calculation).

Limits

For fair use there are per-IP limits (60 requests per minute for calculation and search), the body cannot exceed 16 KB, and requests time out after 15 seconds. Details: Rate limits.

Tool discoveryListing, search and categories.

Tool definitionInput, output and UI schemas.