Mathify REST API and OpenAPI: Use Calculators from Scripts and GPT Actions

Short answer: Mathify mirrors its calculator tools as a plain web API. Send a POST request with a JSON body to https://mathify.one/api/mcp/rest/run_calculator, and you get back the result, the inputs used, a canonical URL and a citation line. The same endpoints are described in an OpenAPI 3.1 file at https://mathify.one/openapi.json, which you can import into any tool that reads OpenAPI.

When should I use REST instead of MCP?

Both routes expose the same four tools. The choice depends on what your software speaks:

• MCP suits assistants that can connect to a remote MCP server. See the connection guide.
• REST suits scripts, spreadsheets, backend jobs and tools that import an OpenAPI description, such as the Actions feature in custom GPT builders where available.

REST needs no session and no handshake. One request in, one JSON document out.

What endpoints are there?

Every tool has one endpoint, and every endpoint takes POST:

• /api/mcp/rest/search_calculators finds calculators by a plain-language query.
• /api/mcp/rest/get_calculator_schema returns the inputs a calculator expects.
• /api/mcp/rest/run_calculator runs a calculator.
• /api/mcp/rest/explain_calculator returns the documented formula, example and FAQ without running anything.

The request body is the tool's arguments directly. You do not wrap it in a JSON-RPC envelope. Cross-origin browser requests are allowed, because the responses carry permissive CORS headers.

What does a working curl call look like?

This request asks for 15 percent of 850:

curl -s -X POST https://mathify.one/api/mcp/rest/run_calculator -H 'Content-Type: application/json' -d '{"id":"math/percentage","args":{"value1":15,"value2":850,"calculationType":"basic"},"locale":"en"}'

We parsed this request body and ran it through the route code in the repository. It returns HTTP 200 and a JSON document that includes:

• id: math/percentage
• result: an object with value 127.5
• formattedResult: 127.5
• inputs: the values actually used, value1 15, value2 850 and calculationType basic
• citation: Source: Mathify - Percentage Calculator, https://mathify.one/en/math/percentage
• canonicalUrl: the clean page address to link to
• url: the page address with the inputs added as query parameters

To pull out just the answer, pipe the output through jq -r .formattedResult.

Field names are not the same for every calculator. The percentage calculator takes value1, value2 and calculationType, while the simple interest calculator takes principal, rate, time and timeUnit. Always fetch the schema first:

curl -s -X POST https://mathify.one/api/mcp/rest/get_calculator_schema -H 'Content-Type: application/json' -d '{"id":"math/percentage"}'

And to find a calculator when you do not know its id:

curl -s -X POST https://mathify.one/api/mcp/rest/search_calculators -H 'Content-Type: application/json' -d '{"query":"bmi","limit":2}'

In the search response, each candidate has an id in category/slug form, a page url and a callable flag. Only calculators with callable set to true can be run through run_calculator. The set of runnable calculators grows over time, so read the flag instead of assuming.

Another worked example

Simple interest on 1,000 at 5 percent a year for 2 years is 1,000 times 0.05 times 2, which is 100. The total is 1,100. Sent as {"id":"simple-interest","args":{"principal":1000,"rate":5,"time":2,"timeUnit":"years"}}, the route returned 100 as the interest and 1,100 as the total.

The calculator documents its day-count rule in its formula: months are divided by 12 and days by 365. So 1,000 at 5 percent for 90 days gives 12.33 in interest, not the figure you would get with a 360-day year. When your answer is compared with a bank's, conventions like this explain most differences. You can check the same case on the Simple Interest Calculator.

How do I use the OpenAPI file with GPT Actions?

The OpenAPI document describes each endpoint, its request schema and its responses. The exact buttons vary by product, but the pattern is the same:

1. In your GPT or agent builder, find the Actions or tools section and choose to add an action from an OpenAPI schema.
2. Import from the URL https://mathify.one/openapi.json, or paste the file's contents.
3. Set authentication to none.
4. In the instructions, tell the assistant to search, read the schema, run, and then show the citation and canonical URL to the user.
5. Test with a question whose answer you already know, such as 15 percent of 850.

Each operation in the file is marked as not consequential for builders that support that flag, since every call is read-only. If your builder is not able to import OpenAPI 3.1, you may need to convert or trim the file.

What errors can come back?

• 400 with an error message and a code such as unknown_calculator, invalid_inputs or ambiguous_id. An ambiguous id includes a candidates list of ids to retry.
• 404 when the tool name in the URL does not exist.
• 413 when the body is over 16 KB.
• 429 when you hit the rate limit. The response includes a Retry-After header and a retry value in seconds. The default in the code is 60 requests a minute per IP address.
• 504 when a call exceeds its 5 second budget.

An unknown id such as nope returns 400 with the message that the id is unknown and a hint to use the search tool first.

Common mistakes

• Wrapping the body in JSON-RPC. The REST endpoints expect the plain arguments.
• Sending numbers as formatted text. Use 850, not "$850.00".
• Guessing field names. Read the schema for each calculator.
• Ignoring the citation. If you display a result to people, show the citation and link so they can verify it.
• Hard-coding counts. The number of runnable calculators changes. A GET request to https://mathify.one/api/mcp with an Accept: application/json header reports the current figures.

Key takeaways

• One POST endpoint per tool, with the arguments as the body.
• Results include inputs, a citation and a canonical URL.
• The OpenAPI file at /openapi.json can be imported where supported.
• Respect the rate limit and handle 400, 429 and 504 responses.

FAQ

Do I need an API key?

No key is required. Calls are rate limited per IP address, so heavy use from one address will be slowed.

Is my data stored?

The code logs one line per call with the tool, calculator id, client name, duration and outcome. By design it does not log IP addresses, arguments or results. Calls are still processed on a server, so avoid sending anything you consider confidential.

Can I call it from a browser page?

Yes. The endpoints allow cross-origin requests, so a fetch call from a page on another domain can read the response.

Why did I get a link but no number?

That calculator exists as a page but cannot be run through the API. The error includes the page URL so you can send the user there.

Can I rely on the numbers for contracts or filings?

Treat them as informational. Confirm figures that carry legal or financial weight with the relevant provider or a professional.