API reference

URL: Encode

Percent-encode text (RFC 3986).

GET POST /api/url/encode MCP tool url_encode

Percent-encodes the UTF-8 bytes of input. component matches JavaScript encodeURIComponent, uri matches encodeURI, and form is application/x-www-form-urlencoded (spaces become +).

Browser version (runs locally): URL Encode / Decode.

Try it
Credentials
Remember these credentials

Not saved: you will paste them again next time.

No credentials yet? Get a client ID and secret. They are sent only to this site, in an Authorization: Basic header.

POST /api/url/encode with a JSON body

Parameters

Parameter Type Default Description
input required string — Text to convert. As a text/plain POST body it is used verbatim.
mode component | uri | form component component: encodeURIComponent — escapes everything except A–Z a–z 0–9 - _ . ! ~ * ' ( ). uri: encodeURI — keeps URL structure (: / ? # & = etc.) intact. form: application/x-www-form-urlencoded — like Component, but spaces become +

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 "encode" The direction performed.
mode "component" | "uri" | "form" 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 The input contains characters that cannot be encoded (for example a lone UTF-16 surrogate).
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.

Encode a query value

curl 'https://util.caruana.me/api/url/encode?input=hello%20world%20%26%20friends'

Response 200

{
  "operation": "encode",
  "mode": "component",
  "output": "hello%20world%20%26%20friends"
}
Same call as an MCP tools/call
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "url_encode",
    "arguments": {
      "input": "hello world & friends"
    }
  }
}

Form encoding

curl 'https://util.caruana.me/api/url/encode?input=a%20b%2Bc&mode=form'

Response 200

{
  "operation": "encode",
  "mode": "form",
  "output": "a+b%2Bc"
}
Same call as an MCP tools/call
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "url_encode",
    "arguments": {
      "input": "a b+c",
      "mode": "form"
    }
  }
}