---
title: "Use this when you want exact, auditable percentage math with a written-out formula."
method: POST
path: "/v1/percentage"
tags: ["finance"]
---

# Use this when you want exact, auditable percentage math with a written-out formula.

`POST /v1/percentage`

## Request

- Base URL: `https://api.clean.tools`
- URL: `https://api.clean.tools/v1/percentage`
- Auth: none declared

Use this when you want exact, auditable percentage math with a written-out formula. Three modes: "of" computes percent% of value (fields percent, value); "is-what" computes what percent x is of y (fields x, y; y must be non-zero); "change" computes the percent change from -> to (from must be non-zero) and reports direction as "increase" or "decrease". Returns the numeric result plus a human-readable formula string. Deterministic: same input, same output. Example: mode="change", from=200, to=250 -> result=25, direction="increase".

## Request body

- object
  - `mode` 'of' | 'is-what' | 'change', required: Which calculation to perform. "of" = percent% of value; "is-what" = x is what percent of y; "change" = percent change from -> to.
  - `percent` number: (mode "of") The percentage to apply, e.g. 15 for 15%.
  - `value` number: (mode "of") The base value that the percentage is taken of.
  - `x` number: (mode "is-what") The part value.
  - `y` number: (mode "is-what") The whole value; must be non-zero.
  - `from` number: (mode "change") The starting value; must be non-zero.
  - `to` number: (mode "change") The ending value.

## Response `200`

Structured tool result.

- object
  - `tool` string
  - `result` object
    - `mode` 'of' | 'is-what' | 'change', required: Which calculation was performed.
    - `result` number, required: The numeric answer: the computed amount (of), or the percent (is-what, change). May be negative for a decrease.
    - `formula` string, required: Human-readable statement of what was computed, e.g. "15% of 80".
    - `percent` number: (is-what and change modes) The percent, equal to result; present alongside result for those two modes.
    - `direction` 'increase' | 'decrease': (change mode only) Whether the change was an increase (result >= 0) or a decrease.

## Other responses

- `400`: Invalid input or the tool reported an error.
- `413`: Request body exceeds the 128 KB limit.
- `429`: Rate limit exceeded; the response carries Retry-After and RateLimit-* headers — honor them and add jitter.

---

[API](https://skmtc.dev/clean/apis/clean-tools-api.md) · [All operations](https://skmtc.dev/clean/apis/clean-tools-api/llms.txt) · [OpenAPI document](https://skmtc.dev/clean/apis/clean-tools-api/revisions/a24a01d2833c?raw)