API

API reference

Every tool is an HTTP endpoint, an MCP tool and an A2A skill. This reference is generated from the code that validates requests, so parameter types, limits and response fields are exactly what the server enforces. Each endpoint page can also run a live request.

Endpoint MCP tool / A2A skill Tool Summary
/api/url/encode url_encode URL Encode / Decode Percent-encode text (RFC 3986).
/api/url/decode url_decode URL Encode / Decode Decode percent-encoded text.
/api/base64/encode base64_encode Base64 Encode text as Base64 (RFC 4648).
/api/base64/decode base64_decode Base64 Decode Base64 to UTF-8 text.
/api/html/encode html_encode HTML Entities Escape text for HTML.
/api/html/decode html_decode HTML Entities Decode HTML entities.
/api/hex/encode hex_encode Hex Text to hexadecimal UTF-8 bytes.
/api/hex/decode hex_decode Hex Hexadecimal bytes to text.
/api/punycode/encode punycode_encode Punycode / IDN Unicode domain to ASCII (IDNA / RFC 3492).
/api/punycode/decode punycode_decode Punycode / IDN ASCII (xn--) domain to Unicode.
/api/hash hash Hash Generator Digest data with one or more hash algorithms.
/api/hash/verify hash_verify File Hash Verification Check data against an expected hash or a checksum list.
/api/fingerprint fingerprint Fingerprints Fingerprint SSH keys, X.509 certificates, SPKI public keys, and OpenPGP keys.
/api/cert/decode cert_decode Certificate Decoder Decode X.509 certificates, chains, and certificate requests.
/api/tls/check tls_check TLS Checker Connect to a host and check the certificate chain it presents: trust, host name, expiry, protocol.
/api/jwt/decode jwt_decode JWT Inspector Decode a JWT, check its claims and algorithm, and optionally verify it with a public key.
/api/url/parse url_parse URL Parser Split a URL into its parts with the WHATWG URL parser browsers use.
/api/uuid/generate uuid_generate UUID Generator & Inspector Generate random (v4) or time-ordered (v7) UUIDs, up to 1000 at a time.
/api/uuid/inspect uuid_inspect UUID Generator & Inspector Read a UUID’s version, variant and embedded timestamp, clock sequence and node.
/api/text/inspect text_inspect Text Inspector Exact counts of characters, bytes, words and lines; find substrings; reveal invisible characters.
/api/time/now time_now Time & Time Zones The current instant from the server clock, in one or more time zones.
/api/time/convert time_convert Time & Time Zones Parse a date-time or Unix timestamp and show it in other zones and formats.
/api/time/diff time_diff Time & Time Zones Elapsed time and calendar difference between two instants, DST-aware.
/api/time/add time_add Time & Time Zones Add or subtract an ISO 8601 duration to an instant, calendar-aware in a time zone.
/api/cron/explain cron_explain Cron Explainer Validate a cron expression, describe it in English, and list its next run times in a zone.
/api/diff text_diff Text Diff Diff two texts by line, word or character: unified diff, structured changes, and stats.
/api/json/format json_format JSON Format & Validate Check that text is valid JSON (RFC 8259), pretty-print or minify it, and find duplicate keys.
/api/json/schema/validate json_schema_validate JSON Schema Validator Validate a JSON instance against a JSON Schema (draft 2020-12, 2019-09, 7, 6 or 4) and list every error with JSON Pointers.
/api/convert/json-to-yaml json_to_yaml YAML Format & Validate Convert JSON to YAML 1.2, quoting strings that YAML 1.1 parsers would misread.
/api/convert/yaml-to-json yaml_to_json YAML Format & Validate Convert YAML to JSON under pinned YAML 1.2 core-schema rules, with line/column errors and YAML 1.1 pitfall warnings.
/api/json/query json_query JMESPath Query Evaluate a JMESPath expression against JSON and return the result, its type and pretty JSON.
/api/yaml/format yaml_format YAML Format & Validate Check YAML against yamllint’s rules (same rule IDs) and return the findings with positions, plus a comment-preserving formatted copy.
/api/json/lint json_lint JSON Format & Validate Validate JSON strictly and report every lint finding with its position.
/api/csv/format csv_format CSV Validate & Format Check CSV against RFC 4180, detect the delimiter and header, infer column types, list every problem with its position, and rewrite it consistently.
/api/convert/csv-to-json csv_to_json CSV Validate & Format Convert CSV to a JSON array of objects (keyed by the header) or of arrays, optionally typing numbers and booleans.
/api/convert/json-to-csv json_to_csv CSV Validate & Format Convert a JSON array of objects or of arrays to CSV, with the union of keys as the header.
/api/toml/format toml_format TOML Format & Validate Check that text is valid TOML 1.0, list problems with line and column, and re-format it with comments kept.
/api/convert/toml-to-json toml_to_json TOML Format & Validate Convert a TOML 1.0 document to JSON, with line and column for any error.
/api/convert/json-to-toml json_to_toml TOML Format & Validate Convert a JSON object to a TOML 1.0 document.
/api/tools/request tool_request Request a Tool Ask for a new deterministic tool to be added to this service, describing the job and an example.
/api/tools/requests tool_requests Request a Tool See the tool requests you have made with these credentials and what became of each.

Machine-readable: /openapi.json (OpenAPI 3.1) · MCP: https://util.caruana.me/mcp · A2A: https://util.caruana.me/.well-known/agent-card.json

Conventions

  • Base URL: https://util.caruana.me. HTTPS only.
  • Authentication: a client ID and secret on every call, as HTTP Basic or a bearer token. Agents register themselves; people use a form. See Authentication.
  • Methods: every endpoint accepts GET and POST; OPTIONS answers CORS preflight.
  • Parameters are read from the query string and, for POST, merged with the body. The body can be a JSON object (application/json; typed values such as numbers and arrays are accepted), a form ( application/x-www-form-urlencoded or multipart/form-data), a raw upload (application/octet-stream, for endpoints that take binary data), or a text/plain body used as input.
  • Validation is strict: unknown parameter names are rejected ( unknown_parameter), so typos surface immediately.
  • Lists are comma-separated in query strings and forms, or JSON arrays in JSON bodies.
  • Limits: 1 MiB request bodies; 60 requests per minute per client; a per-IP limit at Cloudflare's edge.
  • Responses are application/json with cache-control: no-store, x-content-type-options: nosniff and referrer-policy: no-referrer.
  • CORS: access-control-allow-origin: *, with authorization allowed, so browser apps can call the API with their own credentials.

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").

Errors

Errors have a non-2xx status and a JSON body:

{ "error": "Invalid mode: must be one of component, uri, form.", "code": "invalid_parameter", "param": "mode" }
Code Status Meaning
missing_parameter 400 A required parameter is absent.
unknown_parameter 400 A parameter name the endpoint does not define. Typos are rejected, not ignored.
invalid_parameter 400 Wrong type, out of range, not an allowed value, or an unparsable body.
unauthenticated 401 No credentials, wrong credentials, or an expired bearer token.
credentials_expired 401 The client has expired; the message says whether and until when it can be renewed.
revoked 403 The credentials were revoked by the service owner.
verification_failed 403 The human check on the credentials form failed.
renewal_refused 403 More than 90 days past expiry, or revoked.
not_found 404 No endpoint at that path.
method_not_allowed 405 Use GET or POST.
payload_too_large 413 Body over 1 MiB.
unprocessable_input 422 Valid parameters, but the input cannot be processed (malformed encoding, not a certificate, …).
rate_limited 429 More than your per-minute limit (default 60). Retry after 60 seconds.
internal_error 500 A bug. The message never contains your input.
upstream_error 502 A backing service (the TLS checker) failed or timed out.
service_unavailable 503 A required service is not configured on this deployment.

Security and privacy

  • The API is not the page. Tool pages compute locally in your browser; the API, by definition, sends your input to the server. Each endpoint states exactly what the server receives.
  • No secrets, ever. No endpoint accepts or creates passwords, private keys or HMAC keys. Those tools exist only on the pages, which run locally. The one exception is your own client_secret: shown once, stored only as a SHA-256 hash.
  • Inputs and outputs are never stored or logged. What is recorded: your client record, and one metadata row per call (operation, time, transport, status, error code, duration, byte sizes, country), kept 90 days.
  • What Cloudflare sees: as the host, Cloudflare terminates TLS and processes request metadata (IP address, the full URL including the query string, headers) under its own policies. Put inputs in POST bodies.

See Security & privacy for the full model and how to verify it.