API Quickstart

The API is built around one idea: every calculator is reachable at a single endpoint. You send the tool id and its inputs as JSON, and you receive a structured JSON result. Once you have made one call, you can make them all, because the shape is consistent.

1. Make a request

Send a POST to /api/v1/calculator/{tool_id} with a JSON body of parameters and your API key in the header. For example, the Abjad calculator:

POST /api/v1/calculator/abjad
Content-Type: application/json
X-API-Key: your_api_key

{ "text": "احمد" }

2. Read the response

You get back JSON with a result object containing the calculated values. For the Abjad calculator that is the Kabir (full) and Saghir (reduced) totals, the per-letter breakdown, and the dominant element and ruling planet. Chart tools also return the geometry needed to draw a wheel or grid. Alongside the result you get usage metadata, such as how many calls you have left this period.

3. Handle the everyday cases

• Always parse the JSON rather than matching on raw text, so small formatting differences never break your integration.
• Cache a result for a given name or birth date, because it does not change. This saves calls and keeps your pages fast.
• Check the HTTP status and the error body so you can show a helpful message when an input is wrong.

You can make a small number of calls without a key to test, and create a production key when you are ready. See Authentication and API keys next, then the full endpoints reference.