GET POST
/api/html/decode
MCP tool html_decode Decodes all 2,231 named entities of the HTML Living Standard plus decimal and hex numeric references, using the HTML parser rules (legacy entities without ; included).
Browser version (runs locally): HTML Entities.
Try it
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
input required | string | — | Text to convert. As a text/plain POST body it is used verbatim. |
mode | minimal | ascii | minimal | minimal: Escapes only & < > " ' — safe for HTML text and attributes. ascii: Minimal, plus every non-ASCII character as a numeric entity (&#x…;) |
Also accepted on every endpoint: format (json | text).
Parameters may come from the query string, a JSON object body, an urlencoded or multipart form,
or (for input) a text/plain body.
Global parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
format | json | text | json | json returns the documented object. text returns only the primary value as text/plain (see "Text output"). |
Response 200 application/json
| Field | Type | Description |
|---|---|---|
operation | "decode" | The direction performed. |
mode | "minimal" | "ascii" | The mode used (the default if none was given). |
output | string | The converted text. |
Text output (format=text, text/plain): The converted text only.
Errors
Errors are JSON: {"error": "<message>", "code": "<code>", "param": "<name>"?}.
| Status | Code | When |
|---|---|---|
422 | unprocessable_input | Never: unrecognised sequences are left unchanged. |
400 | missing_parameter | A required parameter is absent. |
400 | unknown_parameter | A parameter name is not in the table above (typos are rejected, not ignored). |
400 | invalid_parameter | A value has the wrong type, is out of range, or is not an allowed value. |
413 | payload_too_large | The request body exceeds 1 MiB. |
405 | method_not_allowed | A method other than GET, POST or OPTIONS. |
Behaviour
- Idempotent: the same arguments always return the same result.
-
Requires a client ID and secret (authentication). Each call is
recorded as one metadata row against your client ID; inputs and outputs are never stored or
logged. Responses carry
cache-control: no-store. - CORS: any origin may call this endpoint from a browser, using your credentials.
Examples
Responses below were produced by running each request through this code at build time. Long strings are shortened.
Named and numeric
curl 'https://util.caruana.me/api/html/decode?input=%26eacute%3Bt%26eacute%3B%20%26%238364%3B5%20%26hearts%3B'
Response 200
{
"operation": "decode",
"mode": "minimal",
"output": "été €5 ♥"
}
Same call as an MCP tools/call
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "html_decode",
"arguments": {
"input": "été €5 ♥"
}
}
}