canonical: https://jentic.com/apis/math.tools/math-tools

# Math Tools Numbers API

The Numbers API by math.tools provides a focused set of math utilities exposed as REST endpoints, including number-of-the-day, number facts, random-number generation, ordinal and cardinal spelling, base conversion, alternative numeral systems (Egyptian, Chinese, Roman), prime checks, and pi digits. Each endpoint is a small computation rather than a heavy mathematical engine, which makes it well suited to embedding inside chat experiences, educational tools, and small utilities. Authentication uses the `X-Mathtools-Api-Secret` header.

## For AI agents

Spell numbers as words, convert between bases and numeral systems, generate random numbers, and run prime/factor checks via small math utility endpoints.

## Scope

Does not perform symbolic algebra, calculus, or arbitrary-expression evaluation - use for small number utilities (spelling, base/numeral conversion, primality, facts) only.

## Capabilities

- Spell a number as its cardinal or ordinal English form
- Convert a number between binary, octal, decimal, and hexadecimal bases
- Convert numbers to alternative numeral systems including Roman, Egyptian, and Chinese
- Generate random numbers within a configurable range
- Check whether a number is prime and look up its factors
- Retrieve a fun fact for a specific number or the number of the day
- Return digits of pi to a requested precision

## Use cases

### Educational Math Widgets

Educational sites and homework apps embed small interactive widgets that demonstrate base conversion, prime checks, and number spelling. The Numbers API returns the computed result in a single GET so the widget can render the answer without shipping a math library to the client. Each call typically completes in under 200ms.

Example prompt: Call `GET `/numbers/cardinal`?number=1234` and render the spelled-out form '1234' for the student.

### Trivia and Chat Bot Number Facts

Trivia bots and conversational assistants enrich number-related queries with the 'number of the day' and per-number facts. The Numbers API's `/numbers/fact` and `/numbers/nod` endpoints return short text snippets ready to drop into a reply, removing the need to build a fact corpus from scratch.

Example prompt: Call `GET `/numbers/fact`?number=42` and quote the returned fact in the chat reply.

### Numeral System Converter

Tools that teach historical numeral systems (Roman, Egyptian, Chinese) need authoritative conversions between Hindu-Arabic numerals and the target system. The Numbers API exposes each numeral system as a dedicated endpoint, returning the converted glyphs without requiring local font handling beyond rendering Unicode.

Example prompt: Call `GET `/numbers/numeral/roman`?number=2026` and render the result 'MMXXVI' in the converter UI.

### AI Agent Number Helper

An AI assistant occasionally needs to spell a check amount, convert a hex colour value, or verify whether a value is prime - operations LLMs can do unreliably for large inputs. Jentic exposes the Numbers API behind intent-based discovery so the agent offloads these computations to a deterministic service and stores the API key securely.

Example prompt: Search Jentic for 'spell number as words', load the `/numbers/cardinal` schema, and execute it with number=1234 to return the spelled form deterministically.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/numbers/cardinal` | Spell a number as its cardinal English form |
| GET | `/numbers/ordinal` | Spell a number as its ordinal English form |
| GET | `/numbers/fact` | Retrieve a fact for a number |
| GET | `/numbers/nod` | Number of the day |
| GET | `/numbers/random` | Generate a random number |
| GET | `/numbers/numeral/roman` | Convert a number to Roman numerals |
| GET | `/numbers/numeral/egyptian` | Convert a number to Egyptian numerals |
| GET | `/numbers/numeral/chinese` | Convert a number to Chinese numerals |

## Key resources

- **Number of the Day** — Daily curated number with a fact.
- **Number Facts** — Per-number trivia facts.
- **Number Generation** — Random number generation within a configurable range.
- **Spell** — Cardinal and ordinal English spelling of integers.
- **Base Conversion** — Convert numbers between binary, octal, decimal, and hexadecimal.
- **Numeral Systems** — Convert numbers to Roman, Egyptian, and Chinese numeral systems.
- **Prime** — Primality checks and prime-related lookups.
- **PI** — Digits of pi to requested precision.
- **Number Checks** — Property checks (prime, perfect, etc.).

## Why Jentic

- **Setup:** Wiring the Numbers API by hand means reading its secret-key request header scheme, pointing at the api.math.tools host, and mapping each utility to its query parameters yourself. Through Jentic you install once, import the Numbers API from the API Directory, store the secret once, and your agent calls it.
- **Permission scoping:** The Numbers API takes its inputs as query parameters rather than resource ids in the URL path, so you limit the agent to the operations it needs, such as spelling a number or converting it to a Roman numeral. It calls only the operations you allow, and nothing else is reachable.
- **Credential handling:** Your math.tools API secret is stored once, encrypted, by your own Jentic One instance and injected into the request header at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'spell a number as words' or 'convert a number to Roman numerals', and Jentic returns the matching Numbers API operation with its query schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **AI Number API** — Another small number-utility API in the catalogue with a similar lightweight surface.
- **Randommer API** — Randommer offers random data generation utilities (numbers, names, identifiers).
- **API Ninjas** — API Ninjas hosts a collection of small utility APIs commonly used together.

## FAQ

### What authentication does the Numbers API use?

math.tools authenticates via the `X-Mathtools-Api-Secret` header. Through Jentic, the secret is stored encrypted in your Jentic One instance and applied to the request header at execution time so the agent never sees the raw value.

### Can I convert numbers between bases with the Numbers API?

Yes. The `/numbers/cardinal` and `/numbers/ordinal` endpoints handle spelling, while the base-conversion endpoints under `/numbers/numeral/...` convert between binary, octal, decimal, hex, and historical systems like Roman, Egyptian, and Chinese.

### What are the rate limits for the Numbers API?

math.tools does not publish hard rate limits in the spec. Treat it as a small utility API and apply conservative client-side throttling (a few requests per second per key) until you have confirmed quotas with the math.tools team.

### How do I spell a number through Jentic?

Run `pip install jentic`, then use Jentic's search with the query 'spell number as words'. Jentic loads the `/numbers/cardinal` operation schema and your agent executes it with the integer to spell - the API secret is applied automatically.

### Does the Numbers API support Roman numerals?

Yes. `GET `/numbers/numeral/roman`` converts an integer to its Roman numeral form, and the parallel `/numbers/numeral/egyptian` and `/numbers/numeral/chinese` endpoints handle other historical numeral systems.

### Can I check whether a number is prime?

Yes. The endpoints under `/numbers/prime/...` cover primality checks; combine them with the broader `/numbers/check/...` endpoints for related properties such as factorisation.

### Can I limit what my agent is allowed to do with the Numbers API?

Yes. Because you run Jentic One yourself, your own rules decide which Numbers API operations and credentials the agent may use. Since every operation takes its inputs as query parameters rather than resource ids in the path, you can allow just the endpoints you need, such as spelling a number with `/numbers/cardinal` or converting one with `/numbers/numeral/roman`, and leave the rest unreachable. The agent calls only the operations you permit, and your math.tools secret is applied at request time without ever entering its context.