API — documentation

Calculator API

The same engine as the online calculator, callable from any language. One call, one result: send an expression, get the computed value.

To try it without coding: the online calculator

Endpoint

POST https://pemdasai.com/api/public/calc
  • Method: POST only. Body: JSON. Response: JSON.
  • CORS is open: callable from a web page hosted elsewhere, just like from a script or a terminal.

Authentication

Each call must be signed with your personal key, formatted pk_ followed by 48 hexadecimal characters. Send it in one of these two headers:

Authorization: Bearer pk_VOTRE_CLE
x-api-key: pk_VOTRE_CLE

Create my access key (sign-in required). A deleted key stops working immediately, and calls no longer work without a key.

Request body parameters

NameTypeRequiredDescription
exprstringrequired if exprs is absentExpression to compute, 1 to 2,000 characters. Full calculator syntax: operators + − × ÷ % ^ **, functions (sin, cos, sqrt, ln, max, min…), constants (pi, e, phi), factorial ! and variables.
exprsstring arrayrequired if expr is absent1 to 100 expressions, computed in a single call with the same scope. The response contains a « results » array in the same order.
scopeobjectoptionalVariable values: name in letters, digits or _ (max 32 characters, must not start with a digit), finite numeric value. Example: {"x": 4, "y": 2.5}. Missing variables default to 0.

Example full body: {"expr": "2 + 3 * x", "scope": {"x": 4}} — either a single computation or a batch via « exprs », never both.

Success responses — 200

Single computation:

{"result": 14}

Expression batch:

{"results": [5, 8, 4]}

Each success and error response carries an « x-ratelimit-remaining » header: the number of calls left in the current minute. Infinite (inf) or undefined (nan) results are returned as strings, since JSON cannot represent them.

Error responses

401Authentication header missing, or unknown or deleted key.

{"error": "Clé d'accès manquante ou invalide. Créez-en une sur pemdasai.com/cles-api."}

400Unreadable JSON body, or both « expr » and « exprs » missing or provided together.

{"error": "Corps JSON invalide."}

422Syntactically invalid expression, forbidden variable, or calculation error (division by zero, negative factorial…).

{"error": "Fin d'expression inattendue (position 4)"}

429More than 60 requests sent in the same minute with the same key.

{"error": "Trop de requêtes", "retryAfter": 12}

Header: retry-after: 12

Every calculation error returns a {"error": "…"} body explaining the problem and the faulty character's position in the expression.

Usage limit

  • 60 requests per minute, counted per access key. An « exprs » batch counts as one request, whatever its number of expressions.
  • Beyond that, a 429 response with « retryAfter » (seconds to wait) and a « retry-after » header. Read « x-ratelimit-remaining » to slow down before being blocked.

Complete examples

import requests

API_URL = "https://pemdasai.com/api/public/calc"
HEADERS = {"Authorization": "Bearer pk_VOTRE_CLE"}

# Un calcul simple, avec une variable
r = requests.post(API_URL, headers=HEADERS,
                  json={"expr": "2 + 3 * x", "scope": {"x": 4}})
print(r.json())   # {"result": 14}
# Calculs restants dans la minute :
print(r.headers.get("x-ratelimit-remaining"))   # 59

# Plusieurs expressions en un seul appel (100 max)
r = requests.post(API_URL, headers=HEADERS,
                  json={"exprs": ["x + 1", "x * 2", "sqrt(x^2)"],
                        "scope": {"x": 4}})
print(r.json())   # {"results": [5, 8, 4]}

Error handling:

r = requests.post(API_URL, headers=HEADERS, json={"expr": "1 /"})
if r.status_code == 200:
    print(r.json()["result"])
else:
    print(r.status_code, r.json()["error"])
    # 422 Fin d'expression inattendue (position 4)

# Quota dépassé : réessayez après « retryAfter » secondes
if r.status_code == 429:
    print("Nouvel essai dans", r.json()["retryAfter"], "s")

Important notes

  • « log » is the natural logarithm (ln in Python); « log10 » is base 10. « % » is the division remainder, not a percentage.
  • Expressions also accept × and ÷, and ** as the power operator (like Python); ^ is accepted too.
  • The full list of functions and constants is described on the calculator page. The same engine runs server-side, with no state between calls.
  • Keep your key secret: never put it in a public code repository or a visible web page.

A question about the API? Use the contact page — support answers within the day.