# API overview

API release `0.2.0` exposes 30 deterministic `POST` operations under the stable `/v1` prefix. The public API origin is fixed at `https://api.tools.11dz.cn` and does not use an API key. `ELEVEN_DZ_API_BASE_URL` may point only to an explicit `localhost`, `127.0.0.1`, or `::1` origin for local development.

## Operations

| Task | Method and path |
| --- | --- |
| Format JSON | `POST /v1/json/format` |
| Validate JSON text | `POST /v1/json/validate` |
| Minify JSON | `POST /v1/json/minify` |
| Recursively sort JSON keys | `POST /v1/json/sort` |
| Structurally diff JSON | `POST /v1/json/diff` |
| Escape JSON string content | `POST /v1/json/escape` |
| Unescape JSON string content | `POST /v1/json/unescape` |
| Encode Base64 or Base64URL | `POST /v1/encoding/base64/encode` |
| Decode Base64 or Base64URL | `POST /v1/encoding/base64/decode` |
| Encode a URL value or URI | `POST /v1/encoding/url/encode` |
| Decode a URL value or URI | `POST /v1/encoding/url/decode` |
| Encode query parameters | `POST /v1/encoding/query/encode` |
| Decode query parameters | `POST /v1/encoding/query/decode` |
| Encode Unicode escapes | `POST /v1/encoding/unicode/encode` |
| Decode Unicode escapes | `POST /v1/encoding/unicode/decode` |
| Clean text | `POST /v1/text/clean` |
| Deduplicate or sort lines | `POST /v1/text/unique-sort` |
| Diff unique lines | `POST /v1/text/diff` |
| Split text | `POST /v1/text/split` |
| Merge text | `POST /v1/text/merge` |
| Reverse text | `POST /v1/text/reverse` |
| Count text metrics | `POST /v1/text/count` |
| Convert text case | `POST /v1/text/case` |
| Convert an integer base | `POST /v1/math/integer/base-convert` |
| Compute a SHA-2 digest | `POST /v1/crypto/hash` |
| Inspect a JWT without verification | `POST /v1/developer/jwt/decode` |
| Inspect integer bytes | `POST /v1/developer/bytes/inspect` |
| Convert Unix permissions | `POST /v1/developer/chmod/convert` |
| Encode IEEE 754 bytes | `POST /v1/developer/ieee754/encode` |
| Convert a UTC timestamp | `POST /v1/time/convert` |

The bundled client contains this exact allowlist. It rejects any other path before making a request, refuses redirects, defaults to a 15-second timeout, and does not permit a timeout longer than 15 seconds.

## Response envelope

A successful call returns HTTP 2xx and:

```json
{
  "ok": true,
  "data": {},
  "meta": { "requestId": "uuid", "apiVersion": "v1" }
}
```

A failed call returns a non-2xx status and a stable `error.code`:

```json
{
  "ok": false,
  "error": { "code": "STABLE_ERROR_CODE", "message": "...", "details": {} },
  "meta": { "requestId": "uuid", "apiVersion": "v1" }
}
```

Require both an HTTP success represented by the client exit status and `ok: true`. Preserve `error.code` and `meta.requestId` when explaining failures.

## Limits and failure handling

- The request body limit is 256 KiB.
- Serialized operation output is limited to 1 MiB; operation-specific count and depth limits can be lower.
- The client independently caps a complete API response at 4 MiB.
- A rate-limited response uses HTTP `429`; honor `Retry-After` and do not retry in a tight loop.
- Do not retry validation, input-limit, or sensitive-input errors without changing the request or obtaining the required user authorization.