# Encoding operations

All text uses UTF-8, including Chinese text and emoji. When safe, verify an encoding result with a decode round trip before returning it.

## Base64 and Base64URL

- Encode with `POST /v1/encoding/base64/encode` and fields `input`, `urlSafe`, and `padding`.
- Decode with `POST /v1/encoding/base64/decode` and fields `input` and `urlSafe`.

Use `urlSafe: true` for Base64URL. The decoder rejects invalid characters, impossible lengths, and invalid UTF-8 rather than silently discarding data.

## URL encoding

- Encode with `POST /v1/encoding/url/encode`.
- Decode with `POST /v1/encoding/url/decode`.

Pass `mode: "component"` for a query value or path segment and `mode: "uri"` for a complete URI. The default is `component`. Invalid percent escapes are errors and must not be repaired.

## Query parameters

Encode with `POST /v1/encoding/query/encode` and an object in `input`:

```json
{"input":{"q":"11DZ Tools","tag":["json","api"],"empty":null}}
```

Keys are sorted deterministically. Arrays become repeated parameters, `null` values are omitted, objects are compact JSON strings, and the response includes `pairCount`.

Decode with `POST /v1/encoding/query/decode` and a query string or complete URL in `input`. `+` becomes a space, repeated keys become arrays, and invalid percent escapes or UTF-8 are rejected. Encoding and decoding allow at most 10,000 pairs.

## Unicode escapes

- Encode with `POST /v1/encoding/unicode/encode` and string `input`. BMP code points become four-digit escapes such as `\u5927`; non-BMP code points use braced escapes such as `\u{1F600}`.
- Decode with `POST /v1/encoding/unicode/decode`. It accepts four-digit BMP escapes, adjacent valid UTF-16 surrogate-pair escapes such as `\uD83D\uDE00`, and braced Unicode scalar escapes such as `\u{1F600}`. Both emoji forms decode to the same scalar.

The decoder returns `INVALID_UNICODE_ESCAPE` for an isolated high or low surrogate, a reversed pair, a high surrogate followed by anything other than a low surrogate, values above `U+10FFFF`, malformed escapes, and backslash escapes other than `\u...`. Do not repair or reorder an invalid pair.