{ "openapi": "3.1.0", "info": { "title": "Caruana Utilities API", "version": "0.4.0", "description": "Stateless developer utilities. No authentication. Inputs are processed in memory and not stored or logged by the service. Request bodies are limited to 1 MiB. Every operation is also an MCP tool at https://util.caruana.me/mcp.", "license": { "name": "All rights reserved" } }, "servers": [ { "url": "https://util.caruana.me" } ], "paths": { "/api/url/encode": { "get": { "summary": "Percent-encode text (RFC 3986).", "description": "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 `+`).\n\nPrivacy: The server receives the `input` text and `mode`, converts it in memory inside the request, and returns the result. Your input is not stored or logged; only the per-call metadata row (operation, time, status, sizes) is recorded. Send secrets in a POST body, not the query string: URLs are recorded in Cloudflare request logs, proxies, and shell history.", "tags": [ "url" ], "responses": { "200": { "description": "Success. With format=text, text/plain is returned instead of JSON.", "content": { "application/json": { "schema": { "type": "object", "description": "", "properties": { "operation": { "type": "string", "const": "encode", "description": "The direction performed." }, "mode": { "type": "string", "description": "The mode used (the default if none was given).", "enum": [ "component", "uri", "form" ] }, "output": { "type": "string", "description": "The converted text." } }, "required": [ "operation", "mode", "output" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "The converted text only." } } } }, "400": { "description": "missing_parameter / unknown_parameter / invalid_parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The input contains characters that cannot be encoded (for example a lone UTF-16 surrogate).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "url_encode_get", "parameters": [ { "name": "input", "in": "query", "required": true, "description": "Text to convert. As a text/plain POST body it is used verbatim.", "schema": { "description": "Text to convert. As a text/plain POST body it is used verbatim.", "type": "string" } }, { "name": "mode", "in": "query", "required": false, "description": "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 +", "schema": { "description": "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 +", "type": "string", "enum": [ "component", "uri", "form" ], "default": "component" } }, { "name": "format", "in": "query", "required": false, "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "schema": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } } ] }, "post": { "summary": "Percent-encode text (RFC 3986).", "description": "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 `+`).\n\nPrivacy: The server receives the `input` text and `mode`, converts it in memory inside the request, and returns the result. Your input is not stored or logged; only the per-call metadata row (operation, time, status, sizes) is recorded. Send secrets in a POST body, not the query string: URLs are recorded in Cloudflare request logs, proxies, and shell history.", "tags": [ "url" ], "responses": { "200": { "description": "Success. With format=text, text/plain is returned instead of JSON.", "content": { "application/json": { "schema": { "type": "object", "description": "", "properties": { "operation": { "type": "string", "const": "encode", "description": "The direction performed." }, "mode": { "type": "string", "description": "The mode used (the default if none was given).", "enum": [ "component", "uri", "form" ] }, "output": { "type": "string", "description": "The converted text." } }, "required": [ "operation", "mode", "output" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "The converted text only." } } } }, "400": { "description": "missing_parameter / unknown_parameter / invalid_parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The input contains characters that cannot be encoded (for example a lone UTF-16 surrogate).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "url_encode", "parameters": [ { "name": "format", "in": "query", "required": false, "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "schema": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "input": { "description": "Text to convert. As a text/plain POST body it is used verbatim.", "type": "string" }, "mode": { "description": "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 +", "type": "string", "enum": [ "component", "uri", "form" ], "default": "component" }, "format": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } }, "required": [ "input" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "The body is used as the `input` parameter." } } } } } }, "/api/url/decode": { "get": { "summary": "Decode percent-encoded text.", "description": "Decodes `%XX` sequences as UTF-8. In `form` mode `+` is first turned into a space.\n\nPrivacy: The server receives the `input` text and `mode`, converts it in memory inside the request, and returns the result. Your input is not stored or logged; only the per-call metadata row (operation, time, status, sizes) is recorded. Send secrets in a POST body, not the query string: URLs are recorded in Cloudflare request logs, proxies, and shell history.", "tags": [ "url" ], "responses": { "200": { "description": "Success. With format=text, text/plain is returned instead of JSON.", "content": { "application/json": { "schema": { "type": "object", "description": "", "properties": { "operation": { "type": "string", "const": "decode", "description": "The direction performed." }, "mode": { "type": "string", "description": "The mode used (the default if none was given).", "enum": [ "component", "uri", "form" ] }, "output": { "type": "string", "description": "The converted text." } }, "required": [ "operation", "mode", "output" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "The converted text only." } } } }, "400": { "description": "missing_parameter / unknown_parameter / invalid_parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "A `%` is not followed by two hex digits, or the bytes are not valid UTF-8.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "url_decode_get", "parameters": [ { "name": "input", "in": "query", "required": true, "description": "Text to convert. As a text/plain POST body it is used verbatim.", "schema": { "description": "Text to convert. As a text/plain POST body it is used verbatim.", "type": "string" } }, { "name": "mode", "in": "query", "required": false, "description": "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 +", "schema": { "description": "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 +", "type": "string", "enum": [ "component", "uri", "form" ], "default": "component" } }, { "name": "format", "in": "query", "required": false, "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "schema": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } } ] }, "post": { "summary": "Decode percent-encoded text.", "description": "Decodes `%XX` sequences as UTF-8. In `form` mode `+` is first turned into a space.\n\nPrivacy: The server receives the `input` text and `mode`, converts it in memory inside the request, and returns the result. Your input is not stored or logged; only the per-call metadata row (operation, time, status, sizes) is recorded. Send secrets in a POST body, not the query string: URLs are recorded in Cloudflare request logs, proxies, and shell history.", "tags": [ "url" ], "responses": { "200": { "description": "Success. With format=text, text/plain is returned instead of JSON.", "content": { "application/json": { "schema": { "type": "object", "description": "", "properties": { "operation": { "type": "string", "const": "decode", "description": "The direction performed." }, "mode": { "type": "string", "description": "The mode used (the default if none was given).", "enum": [ "component", "uri", "form" ] }, "output": { "type": "string", "description": "The converted text." } }, "required": [ "operation", "mode", "output" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "The converted text only." } } } }, "400": { "description": "missing_parameter / unknown_parameter / invalid_parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "A `%` is not followed by two hex digits, or the bytes are not valid UTF-8.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "url_decode", "parameters": [ { "name": "format", "in": "query", "required": false, "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "schema": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "input": { "description": "Text to convert. As a text/plain POST body it is used verbatim.", "type": "string" }, "mode": { "description": "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 +", "type": "string", "enum": [ "component", "uri", "form" ], "default": "component" }, "format": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } }, "required": [ "input" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "The body is used as the `input` parameter." } } } } } }, "/api/base64/encode": { "get": { "summary": "Encode text as Base64 (RFC 4648).", "description": "Encodes the UTF-8 bytes of `input`. `standard` uses `+/` with `=` padding; `url` uses `-_` without padding.\n\nPrivacy: The server receives the `input` text and `mode`, converts it in memory inside the request, and returns the result. Your input is not stored or logged; only the per-call metadata row (operation, time, status, sizes) is recorded. Send secrets in a POST body, not the query string: URLs are recorded in Cloudflare request logs, proxies, and shell history.", "tags": [ "base64" ], "responses": { "200": { "description": "Success. With format=text, text/plain is returned instead of JSON.", "content": { "application/json": { "schema": { "type": "object", "description": "", "properties": { "operation": { "type": "string", "const": "encode", "description": "The direction performed." }, "mode": { "type": "string", "description": "The mode used (the default if none was given).", "enum": [ "standard", "url" ] }, "output": { "type": "string", "description": "The converted text." } }, "required": [ "operation", "mode", "output" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "The converted text only." } } } }, "400": { "description": "missing_parameter / unknown_parameter / invalid_parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "base64_encode_get", "parameters": [ { "name": "input", "in": "query", "required": true, "description": "Text to convert. As a text/plain POST body it is used verbatim.", "schema": { "description": "Text to convert. As a text/plain POST body it is used verbatim.", "type": "string" } }, { "name": "mode", "in": "query", "required": false, "description": "standard: RFC 4648 §4 — A–Z a–z 0–9 + / with = padding. url: RFC 4648 §5 — - and _ instead of + and /, no padding (JWT style)", "schema": { "description": "standard: RFC 4648 §4 — A–Z a–z 0–9 + / with = padding. url: RFC 4648 §5 — - and _ instead of + and /, no padding (JWT style)", "type": "string", "enum": [ "standard", "url" ], "default": "standard" } }, { "name": "format", "in": "query", "required": false, "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "schema": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } } ] }, "post": { "summary": "Encode text as Base64 (RFC 4648).", "description": "Encodes the UTF-8 bytes of `input`. `standard` uses `+/` with `=` padding; `url` uses `-_` without padding.\n\nPrivacy: The server receives the `input` text and `mode`, converts it in memory inside the request, and returns the result. Your input is not stored or logged; only the per-call metadata row (operation, time, status, sizes) is recorded. Send secrets in a POST body, not the query string: URLs are recorded in Cloudflare request logs, proxies, and shell history.", "tags": [ "base64" ], "responses": { "200": { "description": "Success. With format=text, text/plain is returned instead of JSON.", "content": { "application/json": { "schema": { "type": "object", "description": "", "properties": { "operation": { "type": "string", "const": "encode", "description": "The direction performed." }, "mode": { "type": "string", "description": "The mode used (the default if none was given).", "enum": [ "standard", "url" ] }, "output": { "type": "string", "description": "The converted text." } }, "required": [ "operation", "mode", "output" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "The converted text only." } } } }, "400": { "description": "missing_parameter / unknown_parameter / invalid_parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "base64_encode", "parameters": [ { "name": "format", "in": "query", "required": false, "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "schema": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "input": { "description": "Text to convert. As a text/plain POST body it is used verbatim.", "type": "string" }, "mode": { "description": "standard: RFC 4648 §4 — A–Z a–z 0–9 + / with = padding. url: RFC 4648 §5 — - and _ instead of + and /, no padding (JWT style)", "type": "string", "enum": [ "standard", "url" ], "default": "standard" }, "format": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } }, "required": [ "input" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "The body is used as the `input` parameter." } } } } } }, "/api/base64/decode": { "get": { "summary": "Decode Base64 to UTF-8 text.", "description": "Accepts either alphabet, with or without padding, and ignores whitespace. `mode` does not change decoding.\n\nPrivacy: The server receives the `input` text and `mode`, converts it in memory inside the request, and returns the result. Your input is not stored or logged; only the per-call metadata row (operation, time, status, sizes) is recorded. Send secrets in a POST body, not the query string: URLs are recorded in Cloudflare request logs, proxies, and shell history.", "tags": [ "base64" ], "responses": { "200": { "description": "Success. With format=text, text/plain is returned instead of JSON.", "content": { "application/json": { "schema": { "type": "object", "description": "", "properties": { "operation": { "type": "string", "const": "decode", "description": "The direction performed." }, "mode": { "type": "string", "description": "The mode used (the default if none was given).", "enum": [ "standard", "url" ] }, "output": { "type": "string", "description": "The converted text." } }, "required": [ "operation", "mode", "output" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "The converted text only." } } } }, "400": { "description": "missing_parameter / unknown_parameter / invalid_parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The input is not Base64, or the decoded bytes are not valid UTF-8 (binary data).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "base64_decode_get", "parameters": [ { "name": "input", "in": "query", "required": true, "description": "Text to convert. As a text/plain POST body it is used verbatim.", "schema": { "description": "Text to convert. As a text/plain POST body it is used verbatim.", "type": "string" } }, { "name": "mode", "in": "query", "required": false, "description": "standard: RFC 4648 §4 — A–Z a–z 0–9 + / with = padding. url: RFC 4648 §5 — - and _ instead of + and /, no padding (JWT style)", "schema": { "description": "standard: RFC 4648 §4 — A–Z a–z 0–9 + / with = padding. url: RFC 4648 §5 — - and _ instead of + and /, no padding (JWT style)", "type": "string", "enum": [ "standard", "url" ], "default": "standard" } }, { "name": "format", "in": "query", "required": false, "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "schema": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } } ] }, "post": { "summary": "Decode Base64 to UTF-8 text.", "description": "Accepts either alphabet, with or without padding, and ignores whitespace. `mode` does not change decoding.\n\nPrivacy: The server receives the `input` text and `mode`, converts it in memory inside the request, and returns the result. Your input is not stored or logged; only the per-call metadata row (operation, time, status, sizes) is recorded. Send secrets in a POST body, not the query string: URLs are recorded in Cloudflare request logs, proxies, and shell history.", "tags": [ "base64" ], "responses": { "200": { "description": "Success. With format=text, text/plain is returned instead of JSON.", "content": { "application/json": { "schema": { "type": "object", "description": "", "properties": { "operation": { "type": "string", "const": "decode", "description": "The direction performed." }, "mode": { "type": "string", "description": "The mode used (the default if none was given).", "enum": [ "standard", "url" ] }, "output": { "type": "string", "description": "The converted text." } }, "required": [ "operation", "mode", "output" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "The converted text only." } } } }, "400": { "description": "missing_parameter / unknown_parameter / invalid_parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The input is not Base64, or the decoded bytes are not valid UTF-8 (binary data).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "base64_decode", "parameters": [ { "name": "format", "in": "query", "required": false, "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "schema": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "input": { "description": "Text to convert. As a text/plain POST body it is used verbatim.", "type": "string" }, "mode": { "description": "standard: RFC 4648 §4 — A–Z a–z 0–9 + / with = padding. url: RFC 4648 §5 — - and _ instead of + and /, no padding (JWT style)", "type": "string", "enum": [ "standard", "url" ], "default": "standard" }, "format": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } }, "required": [ "input" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "The body is used as the `input` parameter." } } } } } }, "/api/html/encode": { "get": { "summary": "Escape text for HTML.", "description": "`minimal` escapes `& < > \" '`, which is sufficient inside element content and quoted attributes. `ascii` additionally writes every non-ASCII code point as `&#x…;`.\n\nPrivacy: The server receives the `input` text and `mode`, converts it in memory inside the request, and returns the result. Your input is not stored or logged; only the per-call metadata row (operation, time, status, sizes) is recorded. Send secrets in a POST body, not the query string: URLs are recorded in Cloudflare request logs, proxies, and shell history.", "tags": [ "html" ], "responses": { "200": { "description": "Success. With format=text, text/plain is returned instead of JSON.", "content": { "application/json": { "schema": { "type": "object", "description": "", "properties": { "operation": { "type": "string", "const": "encode", "description": "The direction performed." }, "mode": { "type": "string", "description": "The mode used (the default if none was given).", "enum": [ "minimal", "ascii" ] }, "output": { "type": "string", "description": "The converted text." } }, "required": [ "operation", "mode", "output" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "The converted text only." } } } }, "400": { "description": "missing_parameter / unknown_parameter / invalid_parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "html_encode_get", "parameters": [ { "name": "input", "in": "query", "required": true, "description": "Text to convert. As a text/plain POST body it is used verbatim.", "schema": { "description": "Text to convert. As a text/plain POST body it is used verbatim.", "type": "string" } }, { "name": "mode", "in": "query", "required": false, "description": "minimal: Escapes only & < > \" ' — safe for HTML text and attributes. ascii: Minimal, plus every non-ASCII character as a numeric entity (&#x…;)", "schema": { "description": "minimal: Escapes only & < > \" ' — safe for HTML text and attributes. ascii: Minimal, plus every non-ASCII character as a numeric entity (&#x…;)", "type": "string", "enum": [ "minimal", "ascii" ], "default": "minimal" } }, { "name": "format", "in": "query", "required": false, "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "schema": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } } ] }, "post": { "summary": "Escape text for HTML.", "description": "`minimal` escapes `& < > \" '`, which is sufficient inside element content and quoted attributes. `ascii` additionally writes every non-ASCII code point as `&#x…;`.\n\nPrivacy: The server receives the `input` text and `mode`, converts it in memory inside the request, and returns the result. Your input is not stored or logged; only the per-call metadata row (operation, time, status, sizes) is recorded. Send secrets in a POST body, not the query string: URLs are recorded in Cloudflare request logs, proxies, and shell history.", "tags": [ "html" ], "responses": { "200": { "description": "Success. With format=text, text/plain is returned instead of JSON.", "content": { "application/json": { "schema": { "type": "object", "description": "", "properties": { "operation": { "type": "string", "const": "encode", "description": "The direction performed." }, "mode": { "type": "string", "description": "The mode used (the default if none was given).", "enum": [ "minimal", "ascii" ] }, "output": { "type": "string", "description": "The converted text." } }, "required": [ "operation", "mode", "output" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "The converted text only." } } } }, "400": { "description": "missing_parameter / unknown_parameter / invalid_parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "html_encode", "parameters": [ { "name": "format", "in": "query", "required": false, "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "schema": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "input": { "description": "Text to convert. As a text/plain POST body it is used verbatim.", "type": "string" }, "mode": { "description": "minimal: Escapes only & < > \" ' — safe for HTML text and attributes. ascii: Minimal, plus every non-ASCII character as a numeric entity (&#x…;)", "type": "string", "enum": [ "minimal", "ascii" ], "default": "minimal" }, "format": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } }, "required": [ "input" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "The body is used as the `input` parameter." } } } } } }, "/api/html/decode": { "get": { "summary": "Decode HTML entities.", "description": "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).\n\nPrivacy: The server receives the `input` text and `mode`, converts it in memory inside the request, and returns the result. Your input is not stored or logged; only the per-call metadata row (operation, time, status, sizes) is recorded. Send secrets in a POST body, not the query string: URLs are recorded in Cloudflare request logs, proxies, and shell history.", "tags": [ "html" ], "responses": { "200": { "description": "Success. With format=text, text/plain is returned instead of JSON.", "content": { "application/json": { "schema": { "type": "object", "description": "", "properties": { "operation": { "type": "string", "const": "decode", "description": "The direction performed." }, "mode": { "type": "string", "description": "The mode used (the default if none was given).", "enum": [ "minimal", "ascii" ] }, "output": { "type": "string", "description": "The converted text." } }, "required": [ "operation", "mode", "output" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "The converted text only." } } } }, "400": { "description": "missing_parameter / unknown_parameter / invalid_parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Never: unrecognised sequences are left unchanged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "html_decode_get", "parameters": [ { "name": "input", "in": "query", "required": true, "description": "Text to convert. As a text/plain POST body it is used verbatim.", "schema": { "description": "Text to convert. As a text/plain POST body it is used verbatim.", "type": "string" } }, { "name": "mode", "in": "query", "required": false, "description": "minimal: Escapes only & < > \" ' — safe for HTML text and attributes. ascii: Minimal, plus every non-ASCII character as a numeric entity (&#x…;)", "schema": { "description": "minimal: Escapes only & < > \" ' — safe for HTML text and attributes. ascii: Minimal, plus every non-ASCII character as a numeric entity (&#x…;)", "type": "string", "enum": [ "minimal", "ascii" ], "default": "minimal" } }, { "name": "format", "in": "query", "required": false, "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "schema": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } } ] }, "post": { "summary": "Decode HTML entities.", "description": "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).\n\nPrivacy: The server receives the `input` text and `mode`, converts it in memory inside the request, and returns the result. Your input is not stored or logged; only the per-call metadata row (operation, time, status, sizes) is recorded. Send secrets in a POST body, not the query string: URLs are recorded in Cloudflare request logs, proxies, and shell history.", "tags": [ "html" ], "responses": { "200": { "description": "Success. With format=text, text/plain is returned instead of JSON.", "content": { "application/json": { "schema": { "type": "object", "description": "", "properties": { "operation": { "type": "string", "const": "decode", "description": "The direction performed." }, "mode": { "type": "string", "description": "The mode used (the default if none was given).", "enum": [ "minimal", "ascii" ] }, "output": { "type": "string", "description": "The converted text." } }, "required": [ "operation", "mode", "output" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "The converted text only." } } } }, "400": { "description": "missing_parameter / unknown_parameter / invalid_parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Never: unrecognised sequences are left unchanged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "html_decode", "parameters": [ { "name": "format", "in": "query", "required": false, "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "schema": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "input": { "description": "Text to convert. As a text/plain POST body it is used verbatim.", "type": "string" }, "mode": { "description": "minimal: Escapes only & < > \" ' — safe for HTML text and attributes. ascii: Minimal, plus every non-ASCII character as a numeric entity (&#x…;)", "type": "string", "enum": [ "minimal", "ascii" ], "default": "minimal" }, "format": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } }, "required": [ "input" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "The body is used as the `input` parameter." } } } } } }, "/api/hex/encode": { "get": { "summary": "Text to hexadecimal UTF-8 bytes.", "description": "Writes each UTF-8 byte of `input` as two lowercase hex digits in the chosen layout.\n\nPrivacy: The server receives the `input` text and `mode`, converts it in memory inside the request, and returns the result. Your input is not stored or logged; only the per-call metadata row (operation, time, status, sizes) is recorded. Send secrets in a POST body, not the query string: URLs are recorded in Cloudflare request logs, proxies, and shell history.", "tags": [ "hex" ], "responses": { "200": { "description": "Success. With format=text, text/plain is returned instead of JSON.", "content": { "application/json": { "schema": { "type": "object", "description": "", "properties": { "operation": { "type": "string", "const": "encode", "description": "The direction performed." }, "mode": { "type": "string", "description": "The mode used (the default if none was given).", "enum": [ "plain", "spaced", "escaped", "prefixed" ] }, "output": { "type": "string", "description": "The converted text." } }, "required": [ "operation", "mode", "output" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "The converted text only." } } } }, "400": { "description": "missing_parameter / unknown_parameter / invalid_parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "hex_encode_get", "parameters": [ { "name": "input", "in": "query", "required": true, "description": "Text to convert. As a text/plain POST body it is used verbatim.", "schema": { "description": "Text to convert. As a text/plain POST body it is used verbatim.", "type": "string" } }, { "name": "mode", "in": "query", "required": false, "description": "plain: 48656c6c6f — contiguous lowercase hex. spaced: 48 65 6c 6c 6f — one byte per pair. escaped: \\x48\\x65\\x6c — C, Python, and shell string escapes. prefixed: 0x48, 0x65, 0x6c — array-literal style", "schema": { "description": "plain: 48656c6c6f — contiguous lowercase hex. spaced: 48 65 6c 6c 6f — one byte per pair. escaped: \\x48\\x65\\x6c — C, Python, and shell string escapes. prefixed: 0x48, 0x65, 0x6c — array-literal style", "type": "string", "enum": [ "plain", "spaced", "escaped", "prefixed" ], "default": "plain" } }, { "name": "format", "in": "query", "required": false, "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "schema": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } } ] }, "post": { "summary": "Text to hexadecimal UTF-8 bytes.", "description": "Writes each UTF-8 byte of `input` as two lowercase hex digits in the chosen layout.\n\nPrivacy: The server receives the `input` text and `mode`, converts it in memory inside the request, and returns the result. Your input is not stored or logged; only the per-call metadata row (operation, time, status, sizes) is recorded. Send secrets in a POST body, not the query string: URLs are recorded in Cloudflare request logs, proxies, and shell history.", "tags": [ "hex" ], "responses": { "200": { "description": "Success. With format=text, text/plain is returned instead of JSON.", "content": { "application/json": { "schema": { "type": "object", "description": "", "properties": { "operation": { "type": "string", "const": "encode", "description": "The direction performed." }, "mode": { "type": "string", "description": "The mode used (the default if none was given).", "enum": [ "plain", "spaced", "escaped", "prefixed" ] }, "output": { "type": "string", "description": "The converted text." } }, "required": [ "operation", "mode", "output" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "The converted text only." } } } }, "400": { "description": "missing_parameter / unknown_parameter / invalid_parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "hex_encode", "parameters": [ { "name": "format", "in": "query", "required": false, "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "schema": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "input": { "description": "Text to convert. As a text/plain POST body it is used verbatim.", "type": "string" }, "mode": { "description": "plain: 48656c6c6f — contiguous lowercase hex. spaced: 48 65 6c 6c 6f — one byte per pair. escaped: \\x48\\x65\\x6c — C, Python, and shell string escapes. prefixed: 0x48, 0x65, 0x6c — array-literal style", "type": "string", "enum": [ "plain", "spaced", "escaped", "prefixed" ], "default": "plain" }, "format": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } }, "required": [ "input" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "The body is used as the `input` parameter." } } } } } }, "/api/hex/decode": { "get": { "summary": "Hexadecimal bytes to text.", "description": "Accepts any mix of plain, spaced, `\\x`, `0x`, comma, and colon separated hex, in either case.\n\nPrivacy: The server receives the `input` text and `mode`, converts it in memory inside the request, and returns the result. Your input is not stored or logged; only the per-call metadata row (operation, time, status, sizes) is recorded. Send secrets in a POST body, not the query string: URLs are recorded in Cloudflare request logs, proxies, and shell history.", "tags": [ "hex" ], "responses": { "200": { "description": "Success. With format=text, text/plain is returned instead of JSON.", "content": { "application/json": { "schema": { "type": "object", "description": "", "properties": { "operation": { "type": "string", "const": "decode", "description": "The direction performed." }, "mode": { "type": "string", "description": "The mode used (the default if none was given).", "enum": [ "plain", "spaced", "escaped", "prefixed" ] }, "output": { "type": "string", "description": "The converted text." } }, "required": [ "operation", "mode", "output" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "The converted text only." } } } }, "400": { "description": "missing_parameter / unknown_parameter / invalid_parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "An odd number of hex digits, a non-hex character, or bytes that are not valid UTF-8.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "hex_decode_get", "parameters": [ { "name": "input", "in": "query", "required": true, "description": "Text to convert. As a text/plain POST body it is used verbatim.", "schema": { "description": "Text to convert. As a text/plain POST body it is used verbatim.", "type": "string" } }, { "name": "mode", "in": "query", "required": false, "description": "plain: 48656c6c6f — contiguous lowercase hex. spaced: 48 65 6c 6c 6f — one byte per pair. escaped: \\x48\\x65\\x6c — C, Python, and shell string escapes. prefixed: 0x48, 0x65, 0x6c — array-literal style", "schema": { "description": "plain: 48656c6c6f — contiguous lowercase hex. spaced: 48 65 6c 6c 6f — one byte per pair. escaped: \\x48\\x65\\x6c — C, Python, and shell string escapes. prefixed: 0x48, 0x65, 0x6c — array-literal style", "type": "string", "enum": [ "plain", "spaced", "escaped", "prefixed" ], "default": "plain" } }, { "name": "format", "in": "query", "required": false, "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "schema": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } } ] }, "post": { "summary": "Hexadecimal bytes to text.", "description": "Accepts any mix of plain, spaced, `\\x`, `0x`, comma, and colon separated hex, in either case.\n\nPrivacy: The server receives the `input` text and `mode`, converts it in memory inside the request, and returns the result. Your input is not stored or logged; only the per-call metadata row (operation, time, status, sizes) is recorded. Send secrets in a POST body, not the query string: URLs are recorded in Cloudflare request logs, proxies, and shell history.", "tags": [ "hex" ], "responses": { "200": { "description": "Success. With format=text, text/plain is returned instead of JSON.", "content": { "application/json": { "schema": { "type": "object", "description": "", "properties": { "operation": { "type": "string", "const": "decode", "description": "The direction performed." }, "mode": { "type": "string", "description": "The mode used (the default if none was given).", "enum": [ "plain", "spaced", "escaped", "prefixed" ] }, "output": { "type": "string", "description": "The converted text." } }, "required": [ "operation", "mode", "output" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "The converted text only." } } } }, "400": { "description": "missing_parameter / unknown_parameter / invalid_parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "An odd number of hex digits, a non-hex character, or bytes that are not valid UTF-8.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "hex_decode", "parameters": [ { "name": "format", "in": "query", "required": false, "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "schema": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "input": { "description": "Text to convert. As a text/plain POST body it is used verbatim.", "type": "string" }, "mode": { "description": "plain: 48656c6c6f — contiguous lowercase hex. spaced: 48 65 6c 6c 6f — one byte per pair. escaped: \\x48\\x65\\x6c — C, Python, and shell string escapes. prefixed: 0x48, 0x65, 0x6c — array-literal style", "type": "string", "enum": [ "plain", "spaced", "escaped", "prefixed" ], "default": "plain" }, "format": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } }, "required": [ "input" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "The body is used as the `input` parameter." } } } } } }, "/api/punycode/encode": { "get": { "summary": "Unicode domain to ASCII (IDNA / RFC 3492).", "description": "`domain` converts each non-ASCII label to `xn--` form (dots and email local parts preserved). `raw` applies bare RFC 3492 Punycode with no prefix.\n\nPrivacy: The server receives the `input` text and `mode`, converts it in memory inside the request, and returns the result. Your input is not stored or logged; only the per-call metadata row (operation, time, status, sizes) is recorded. Send secrets in a POST body, not the query string: URLs are recorded in Cloudflare request logs, proxies, and shell history.", "tags": [ "punycode" ], "responses": { "200": { "description": "Success. With format=text, text/plain is returned instead of JSON.", "content": { "application/json": { "schema": { "type": "object", "description": "", "properties": { "operation": { "type": "string", "const": "encode", "description": "The direction performed." }, "mode": { "type": "string", "description": "The mode used (the default if none was given).", "enum": [ "domain", "raw" ] }, "output": { "type": "string", "description": "The converted text." } }, "required": [ "operation", "mode", "output" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "The converted text only." } } } }, "400": { "description": "missing_parameter / unknown_parameter / invalid_parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The input contains characters that cannot be encoded (for example a lone UTF-16 surrogate).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "punycode_encode_get", "parameters": [ { "name": "input", "in": "query", "required": true, "description": "Text to convert. As a text/plain POST body it is used verbatim.", "schema": { "description": "Text to convert. As a text/plain POST body it is used verbatim.", "type": "string" } }, { "name": "mode", "in": "query", "required": false, "description": "domain: Converts each label of a domain or email: münchen.de ↔ xn--mnchen-3ya.de. raw: Bare RFC 3492 Punycode with no xn-- prefix: münchen ↔ mnchen-3ya", "schema": { "description": "domain: Converts each label of a domain or email: münchen.de ↔ xn--mnchen-3ya.de. raw: Bare RFC 3492 Punycode with no xn-- prefix: münchen ↔ mnchen-3ya", "type": "string", "enum": [ "domain", "raw" ], "default": "domain" } }, { "name": "format", "in": "query", "required": false, "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "schema": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } } ] }, "post": { "summary": "Unicode domain to ASCII (IDNA / RFC 3492).", "description": "`domain` converts each non-ASCII label to `xn--` form (dots and email local parts preserved). `raw` applies bare RFC 3492 Punycode with no prefix.\n\nPrivacy: The server receives the `input` text and `mode`, converts it in memory inside the request, and returns the result. Your input is not stored or logged; only the per-call metadata row (operation, time, status, sizes) is recorded. Send secrets in a POST body, not the query string: URLs are recorded in Cloudflare request logs, proxies, and shell history.", "tags": [ "punycode" ], "responses": { "200": { "description": "Success. With format=text, text/plain is returned instead of JSON.", "content": { "application/json": { "schema": { "type": "object", "description": "", "properties": { "operation": { "type": "string", "const": "encode", "description": "The direction performed." }, "mode": { "type": "string", "description": "The mode used (the default if none was given).", "enum": [ "domain", "raw" ] }, "output": { "type": "string", "description": "The converted text." } }, "required": [ "operation", "mode", "output" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "The converted text only." } } } }, "400": { "description": "missing_parameter / unknown_parameter / invalid_parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The input contains characters that cannot be encoded (for example a lone UTF-16 surrogate).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "punycode_encode", "parameters": [ { "name": "format", "in": "query", "required": false, "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "schema": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "input": { "description": "Text to convert. As a text/plain POST body it is used verbatim.", "type": "string" }, "mode": { "description": "domain: Converts each label of a domain or email: münchen.de ↔ xn--mnchen-3ya.de. raw: Bare RFC 3492 Punycode with no xn-- prefix: münchen ↔ mnchen-3ya", "type": "string", "enum": [ "domain", "raw" ], "default": "domain" }, "format": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } }, "required": [ "input" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "The body is used as the `input` parameter." } } } } } }, "/api/punycode/decode": { "get": { "summary": "ASCII (xn--) domain to Unicode.", "description": "`domain` decodes each `xn--` label. `raw` decodes a bare Punycode string.\n\nPrivacy: The server receives the `input` text and `mode`, converts it in memory inside the request, and returns the result. Your input is not stored or logged; only the per-call metadata row (operation, time, status, sizes) is recorded. Send secrets in a POST body, not the query string: URLs are recorded in Cloudflare request logs, proxies, and shell history.", "tags": [ "punycode" ], "responses": { "200": { "description": "Success. With format=text, text/plain is returned instead of JSON.", "content": { "application/json": { "schema": { "type": "object", "description": "", "properties": { "operation": { "type": "string", "const": "decode", "description": "The direction performed." }, "mode": { "type": "string", "description": "The mode used (the default if none was given).", "enum": [ "domain", "raw" ] }, "output": { "type": "string", "description": "The converted text." } }, "required": [ "operation", "mode", "output" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "The converted text only." } } } }, "400": { "description": "missing_parameter / unknown_parameter / invalid_parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The input is not valid Punycode.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "punycode_decode_get", "parameters": [ { "name": "input", "in": "query", "required": true, "description": "Text to convert. As a text/plain POST body it is used verbatim.", "schema": { "description": "Text to convert. As a text/plain POST body it is used verbatim.", "type": "string" } }, { "name": "mode", "in": "query", "required": false, "description": "domain: Converts each label of a domain or email: münchen.de ↔ xn--mnchen-3ya.de. raw: Bare RFC 3492 Punycode with no xn-- prefix: münchen ↔ mnchen-3ya", "schema": { "description": "domain: Converts each label of a domain or email: münchen.de ↔ xn--mnchen-3ya.de. raw: Bare RFC 3492 Punycode with no xn-- prefix: münchen ↔ mnchen-3ya", "type": "string", "enum": [ "domain", "raw" ], "default": "domain" } }, { "name": "format", "in": "query", "required": false, "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "schema": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } } ] }, "post": { "summary": "ASCII (xn--) domain to Unicode.", "description": "`domain` decodes each `xn--` label. `raw` decodes a bare Punycode string.\n\nPrivacy: The server receives the `input` text and `mode`, converts it in memory inside the request, and returns the result. Your input is not stored or logged; only the per-call metadata row (operation, time, status, sizes) is recorded. Send secrets in a POST body, not the query string: URLs are recorded in Cloudflare request logs, proxies, and shell history.", "tags": [ "punycode" ], "responses": { "200": { "description": "Success. With format=text, text/plain is returned instead of JSON.", "content": { "application/json": { "schema": { "type": "object", "description": "", "properties": { "operation": { "type": "string", "const": "decode", "description": "The direction performed." }, "mode": { "type": "string", "description": "The mode used (the default if none was given).", "enum": [ "domain", "raw" ] }, "output": { "type": "string", "description": "The converted text." } }, "required": [ "operation", "mode", "output" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "The converted text only." } } } }, "400": { "description": "missing_parameter / unknown_parameter / invalid_parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The input is not valid Punycode.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "punycode_decode", "parameters": [ { "name": "format", "in": "query", "required": false, "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "schema": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "input": { "description": "Text to convert. As a text/plain POST body it is used verbatim.", "type": "string" }, "mode": { "description": "domain: Converts each label of a domain or email: münchen.de ↔ xn--mnchen-3ya.de. raw: Bare RFC 3492 Punycode with no xn-- prefix: münchen ↔ mnchen-3ya", "type": "string", "enum": [ "domain", "raw" ], "default": "domain" }, "format": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } }, "required": [ "input" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "The body is used as the `input` parameter." } } } } } }, "/api/hash": { "get": { "summary": "Digest data with one or more hash algorithms.", "description": "Computes MD5, SHA-1, SHA-256, SHA-384, SHA-512, SHA3-256, SHA3-512, BLAKE2b-512, BLAKE3 digests of the data. MD5 and SHA-1 are broken for collision resistance: use them only to match existing checksums. HMAC is deliberately not offered by the API, because it needs a secret key and this server never accepts secrets; compute HMACs on the page, which runs locally.\n\nPrivacy: The server receives the data, hashes it in memory inside the request, and returns only digests. Your input is not stored or logged; only the per-call metadata row (operation, time, status, sizes) is recorded. Do not send secrets: hashing a secret on any server shares it with that server; use the page, which hashes locally.", "tags": [ "hash" ], "responses": { "200": { "description": "Success. With format=text, text/plain is returned instead of JSON.", "content": { "application/json": { "schema": { "type": "object", "description": "", "properties": { "bytes": { "type": "integer", "description": "Length of the hashed data in bytes." }, "encoding": { "type": "string", "description": "Encoding of the values in `hashes`.", "enum": [ "hex", "base64" ] }, "hashes": { "type": "object", "description": "Digest per algorithm ID, in request order.", "additionalProperties": { "type": "string", "description": "Digest in the requested encoding." } } }, "required": [ "bytes", "encoding", "hashes" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "With one algorithm, the bare digest. With several, one ` ` line per algorithm." } } } }, "400": { "description": "missing_parameter / unknown_parameter / More than one data source is given.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "hash_get", "parameters": [ { "name": "input", "in": "query", "required": false, "description": "Data as UTF-8 text. Use exactly one of input, input_base64, or a file upload.", "schema": { "description": "Data as UTF-8 text. Use exactly one of input, input_base64, or a file upload.", "type": "string" } }, { "name": "input_base64", "in": "query", "required": false, "description": "Data as Base64 (either alphabet), for binary content over JSON or MCP.", "schema": { "description": "Data as Base64 (either alphabet), for binary content over JSON or MCP.", "type": "string" } }, { "name": "algorithm", "in": "query", "required": false, "description": "Comma-separated algorithm IDs, or all. IDs: md5, sha1, sha256, sha384, sha512, sha3-256, sha3-512, blake2b, blake3.", "style": "form", "explode": false, "schema": { "description": "Comma-separated algorithm IDs, or all. IDs: md5, sha1, sha256, sha384, sha512, sha3-256, sha3-512, blake2b, blake3.", "type": "array", "items": { "type": "string", "enum": [ "all", "md5", "sha1", "sha256", "sha384", "sha512", "sha3-256", "sha3-512", "blake2b", "blake3" ] }, "default": "all" } }, { "name": "encoding", "in": "query", "required": false, "description": "Digest output encoding: lowercase hex or standard Base64 with padding.", "schema": { "description": "Digest output encoding: lowercase hex or standard Base64 with padding.", "type": "string", "enum": [ "hex", "base64" ], "default": "hex" } }, { "name": "format", "in": "query", "required": false, "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "schema": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } } ] }, "post": { "summary": "Digest data with one or more hash algorithms.", "description": "Computes MD5, SHA-1, SHA-256, SHA-384, SHA-512, SHA3-256, SHA3-512, BLAKE2b-512, BLAKE3 digests of the data. MD5 and SHA-1 are broken for collision resistance: use them only to match existing checksums. HMAC is deliberately not offered by the API, because it needs a secret key and this server never accepts secrets; compute HMACs on the page, which runs locally.\n\nPrivacy: The server receives the data, hashes it in memory inside the request, and returns only digests. Your input is not stored or logged; only the per-call metadata row (operation, time, status, sizes) is recorded. Do not send secrets: hashing a secret on any server shares it with that server; use the page, which hashes locally.", "tags": [ "hash" ], "responses": { "200": { "description": "Success. With format=text, text/plain is returned instead of JSON.", "content": { "application/json": { "schema": { "type": "object", "description": "", "properties": { "bytes": { "type": "integer", "description": "Length of the hashed data in bytes." }, "encoding": { "type": "string", "description": "Encoding of the values in `hashes`.", "enum": [ "hex", "base64" ] }, "hashes": { "type": "object", "description": "Digest per algorithm ID, in request order.", "additionalProperties": { "type": "string", "description": "Digest in the requested encoding." } } }, "required": [ "bytes", "encoding", "hashes" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "With one algorithm, the bare digest. With several, one ` ` line per algorithm." } } } }, "400": { "description": "missing_parameter / unknown_parameter / More than one data source is given.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "hash", "parameters": [ { "name": "format", "in": "query", "required": false, "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "schema": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "input": { "description": "Data as UTF-8 text. Use exactly one of input, input_base64, or a file upload.", "type": "string" }, "input_base64": { "description": "Data as Base64 (either alphabet), for binary content over JSON or MCP.", "type": "string" }, "algorithm": { "description": "Comma-separated algorithm IDs, or all. IDs: md5, sha1, sha256, sha384, sha512, sha3-256, sha3-512, blake2b, blake3.", "type": "array", "items": { "type": "string", "enum": [ "all", "md5", "sha1", "sha256", "sha384", "sha512", "sha3-256", "sha3-512", "blake2b", "blake3" ] }, "default": "all" }, "encoding": { "description": "Digest output encoding: lowercase hex or standard Base64 with padding.", "type": "string", "enum": [ "hex", "base64" ], "default": "hex" }, "format": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } }, "required": [], "additionalProperties": false } }, "multipart/form-data": { "schema": { "type": "object", "properties": { "input": { "description": "Data as UTF-8 text. Use exactly one of input, input_base64, or a file upload.", "type": "string" }, "input_base64": { "description": "Data as Base64 (either alphabet), for binary content over JSON or MCP.", "type": "string" }, "algorithm": { "description": "Comma-separated algorithm IDs, or all. IDs: md5, sha1, sha256, sha384, sha512, sha3-256, sha3-512, blake2b, blake3.", "type": "array", "items": { "type": "string", "enum": [ "all", "md5", "sha1", "sha256", "sha384", "sha512", "sha3-256", "sha3-512", "blake2b", "blake3" ] }, "default": "all" }, "encoding": { "description": "Digest output encoding: lowercase hex or standard Base64 with padding.", "type": "string", "enum": [ "hex", "base64" ], "default": "hex" }, "format": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" }, "file": { "type": "string", "format": "binary", "description": "File to process (first file field is used)." } }, "required": [], "additionalProperties": false } }, "application/octet-stream": { "schema": { "type": "string", "format": "binary" } }, "text/plain": { "schema": { "type": "string", "description": "The body is used as the `input` parameter." } } } } } }, "/api/hash/verify": { "get": { "summary": "Check data against an expected hash or a checksum list.", "description": "Hashes the data with every algorithm whose digest length matches the expected hash (for 64 hex digits: SHA-256, SHA3-256 and BLAKE3) and reports whether any matches. `expected` may be hex, Base64, SRI (`sha384-…`), prefixed (`sha256:…`), or a whole GNU/BSD checksum file, in which case the line for `filename` (or the uploaded file name) is used. A mismatch is a successful response with `match: false`.\n\nPrivacy: The server receives the data and the expected hash, hashes the data in memory, and returns the comparison. Your input is not stored or logged; only the per-call metadata row (operation, time, status, sizes) is recorded. Uploading a file means the server sees its full contents: for private or large files use the page, which hashes locally.", "tags": [ "hash-verify" ], "responses": { "200": { "description": "Success. With format=text, text/plain is returned instead of JSON.", "content": { "application/json": { "schema": { "type": "object", "description": "", "properties": { "match": { "type": "boolean", "description": "True when a computed digest equals the expected hash." }, "algorithm": { "type": [ "string", "null" ], "description": "Algorithm ID that matched, or null." }, "expected": { "type": "string", "description": "Expected digest normalised to lowercase hex." }, "actual": { "type": "object", "description": "Computed digest for each candidate algorithm.", "additionalProperties": { "type": "string", "description": "Lowercase hex digest." } }, "filename": { "type": [ "string", "null" ], "description": "File name used to select a checksum-list line." }, "bytes": { "type": "integer", "description": "Length of the data in bytes." } }, "required": [ "match", "algorithm", "expected", "actual", "filename", "bytes" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "`OK ` or `MISMATCH`." } } } }, "400": { "description": "missing_parameter / unknown_parameter / invalid_parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`expected` is not a recognisable hash, or a checksum list has no line for the file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "hash_verify_get", "parameters": [ { "name": "input", "in": "query", "required": false, "description": "Data as UTF-8 text. Use exactly one of input, input_base64, or a file upload.", "schema": { "description": "Data as UTF-8 text. Use exactly one of input, input_base64, or a file upload.", "type": "string" } }, { "name": "input_base64", "in": "query", "required": false, "description": "Data as Base64 (either alphabet), for binary content over JSON or MCP.", "schema": { "description": "Data as Base64 (either alphabet), for binary content over JSON or MCP.", "type": "string" } }, { "name": "expected", "in": "query", "required": true, "description": "Expected hash in any supported form, or the contents of a checksum file.", "schema": { "description": "Expected hash in any supported form, or the contents of a checksum file.", "type": "string" } }, { "name": "filename", "in": "query", "required": false, "description": "Which checksum-list line to use. Defaults to the uploaded file name. Directory parts are ignored.", "schema": { "description": "Which checksum-list line to use. Defaults to the uploaded file name. Directory parts are ignored.", "type": "string" } }, { "name": "format", "in": "query", "required": false, "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "schema": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } } ] }, "post": { "summary": "Check data against an expected hash or a checksum list.", "description": "Hashes the data with every algorithm whose digest length matches the expected hash (for 64 hex digits: SHA-256, SHA3-256 and BLAKE3) and reports whether any matches. `expected` may be hex, Base64, SRI (`sha384-…`), prefixed (`sha256:…`), or a whole GNU/BSD checksum file, in which case the line for `filename` (or the uploaded file name) is used. A mismatch is a successful response with `match: false`.\n\nPrivacy: The server receives the data and the expected hash, hashes the data in memory, and returns the comparison. Your input is not stored or logged; only the per-call metadata row (operation, time, status, sizes) is recorded. Uploading a file means the server sees its full contents: for private or large files use the page, which hashes locally.", "tags": [ "hash-verify" ], "responses": { "200": { "description": "Success. With format=text, text/plain is returned instead of JSON.", "content": { "application/json": { "schema": { "type": "object", "description": "", "properties": { "match": { "type": "boolean", "description": "True when a computed digest equals the expected hash." }, "algorithm": { "type": [ "string", "null" ], "description": "Algorithm ID that matched, or null." }, "expected": { "type": "string", "description": "Expected digest normalised to lowercase hex." }, "actual": { "type": "object", "description": "Computed digest for each candidate algorithm.", "additionalProperties": { "type": "string", "description": "Lowercase hex digest." } }, "filename": { "type": [ "string", "null" ], "description": "File name used to select a checksum-list line." }, "bytes": { "type": "integer", "description": "Length of the data in bytes." } }, "required": [ "match", "algorithm", "expected", "actual", "filename", "bytes" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "`OK ` or `MISMATCH`." } } } }, "400": { "description": "missing_parameter / unknown_parameter / invalid_parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`expected` is not a recognisable hash, or a checksum list has no line for the file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "hash_verify", "parameters": [ { "name": "format", "in": "query", "required": false, "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "schema": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "input": { "description": "Data as UTF-8 text. Use exactly one of input, input_base64, or a file upload.", "type": "string" }, "input_base64": { "description": "Data as Base64 (either alphabet), for binary content over JSON or MCP.", "type": "string" }, "expected": { "description": "Expected hash in any supported form, or the contents of a checksum file.", "type": "string" }, "filename": { "description": "Which checksum-list line to use. Defaults to the uploaded file name. Directory parts are ignored.", "type": "string" }, "format": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } }, "required": [ "expected" ], "additionalProperties": false } }, "multipart/form-data": { "schema": { "type": "object", "properties": { "input": { "description": "Data as UTF-8 text. Use exactly one of input, input_base64, or a file upload.", "type": "string" }, "input_base64": { "description": "Data as Base64 (either alphabet), for binary content over JSON or MCP.", "type": "string" }, "expected": { "description": "Expected hash in any supported form, or the contents of a checksum file.", "type": "string" }, "filename": { "description": "Which checksum-list line to use. Defaults to the uploaded file name. Directory parts are ignored.", "type": "string" }, "format": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" }, "file": { "type": "string", "format": "binary", "description": "File to process (first file field is used)." } }, "required": [ "expected" ], "additionalProperties": false } }, "application/octet-stream": { "schema": { "type": "string", "format": "binary" } }, "text/plain": { "schema": { "type": "string", "description": "The body is used as the `input` parameter." } } } } } }, "/api/fingerprint": { "get": { "summary": "Fingerprint SSH keys, X.509 certificates, SPKI public keys, and OpenPGP keys.", "description": "Finds every public key in `input` and returns its fingerprints in the formats other tools print. SSH: `ssh-keygen -l` SHA256 and MD5. Certificates: `openssl x509 -fingerprint` SHA-1 and SHA-256 over the DER, plus the RFC 7469 SPKI pin. PEM public keys: SHA-256 over the SubjectPublicKeyInfo. Where an equivalent exists, the SSH fingerprint of the same key is included, so you can confirm that a certificate and an SSH key share a key. OpenPGP: v4 (SHA-1) and v6 (SHA-256) fingerprints and key IDs for the primary key and subkeys. Private keys are refused.\n\nPrivacy: The server receives the public key text, computes fingerprints in memory, and returns them. Public keys are not secret, but the input is not stored or logged (only the per-call metadata row is recorded). If the input contains a private key, the server rejects it before parsing; treat a private key sent anywhere you do not control as exposed.", "tags": [ "fingerprint" ], "responses": { "200": { "description": "Success. With format=text, text/plain is returned instead of JSON.", "content": { "application/json": { "schema": { "type": "object", "description": "", "properties": { "items": { "type": "array", "items": { "description": "One entry per key found, discriminated by `kind`.", "anyOf": [ { "type": "object", "description": "", "properties": { "kind": { "type": "string", "const": "ssh", "description": "SSH public key." }, "type": { "type": "string", "description": "Key type, e.g. `ssh-ed25519`." }, "bits": { "type": [ "integer", "null" ], "description": "Key size." }, "comment": { "type": "string", "description": "Trailing comment, often user@host." }, "ssh": { "type": "object", "description": "", "properties": { "sha256": { "type": "string", "description": "`SHA256:` + unpadded Base64, as printed by `ssh-keygen -l`." }, "md5": { "type": "string", "description": "`MD5:` + colon hex, as printed by `ssh-keygen -E md5 -l`." } }, "required": [ "sha256", "md5" ], "additionalProperties": false } }, "required": [ "kind", "type", "bits", "comment", "ssh" ], "additionalProperties": false }, { "type": "object", "description": "", "properties": { "kind": { "type": "string", "const": "certificate", "description": "X.509 certificate." }, "subject": { "type": "string", "description": "Subject DN." }, "sha1": { "type": "string", "description": "SHA-1 of DER, colon hex." }, "sha256": { "type": "string", "description": "SHA-256 of DER, colon hex." }, "spkiSha256": { "type": "string", "description": "RFC 7469 pin." }, "ssh": { "type": [ "object", "null" ], "description": "", "properties": { "sha256": { "type": "string", "description": "`SHA256:` + unpadded Base64, as printed by `ssh-keygen -l`." }, "md5": { "type": "string", "description": "`MD5:` + colon hex, as printed by `ssh-keygen -E md5 -l`." } }, "required": [ "sha256", "md5" ], "additionalProperties": false } }, "required": [ "kind", "subject", "sha1", "sha256", "spkiSha256", "ssh" ], "additionalProperties": false }, { "type": "object", "description": "", "properties": { "kind": { "type": "string", "const": "public-key", "description": "PEM SubjectPublicKeyInfo." }, "algorithm": { "type": "string", "description": "Key algorithm." }, "spkiSha256Hex": { "type": "string", "description": "SHA-256 of the SPKI DER, colon hex." }, "spkiSha256": { "type": "string", "description": "RFC 7469 pin." }, "ssh": { "type": [ "object", "null" ], "description": "", "properties": { "sha256": { "type": "string", "description": "`SHA256:` + unpadded Base64, as printed by `ssh-keygen -l`." }, "md5": { "type": "string", "description": "`MD5:` + colon hex, as printed by `ssh-keygen -E md5 -l`." } }, "required": [ "sha256", "md5" ], "additionalProperties": false } }, "required": [ "kind", "algorithm", "spkiSha256Hex", "spkiSha256", "ssh" ], "additionalProperties": false }, { "type": "object", "description": "", "properties": { "kind": { "type": "string", "const": "pgp", "description": "OpenPGP public key." }, "userIds": { "type": "array", "items": { "type": "string", "description": "User ID packet text." }, "description": "User IDs (not verified against self-signatures)." }, "keys": { "type": "array", "items": { "type": "object", "description": "", "properties": { "role": { "type": "string", "description": "`primary` or `subkey`.", "enum": [ "primary", "subkey" ] }, "version": { "type": "integer", "description": "Key packet version (4, 5 or 6)." }, "fingerprint": { "type": "string", "description": "Uppercase hex fingerprint." }, "grouped": { "type": "string", "description": "Fingerprint in groups of four, as GnuPG prints it." }, "keyId": { "type": "string", "description": "Key ID: last 8 bytes (v4) or first 8 bytes (v5/v6) of the fingerprint." }, "algorithm": { "type": "string", "description": "Public key algorithm." }, "bits": { "type": [ "integer", "null" ], "description": "Key size." }, "created": { "type": "string", "description": "Key creation time, ISO 8601.", "format": "date-time" } }, "required": [ "role", "version", "fingerprint", "grouped", "keyId", "algorithm", "bits", "created" ], "additionalProperties": false }, "description": "Primary key and subkeys." } }, "required": [ "kind", "userIds", "keys" ], "additionalProperties": false } ] }, "description": "Keys found, in input order by format." } }, "required": [ "items" ], "additionalProperties": false } } } }, "400": { "description": "missing_parameter / unknown_parameter / invalid_parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "No public key is found, a key is malformed, or the input contains a private key (which is refused without being parsed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "fingerprint_get", "parameters": [ { "name": "input", "in": "query", "required": true, "description": "One or more SSH public key lines, RFC 4716 blocks, PEM CERTIFICATE / PUBLIC KEY blocks, or an armored PGP public key block.", "schema": { "description": "One or more SSH public key lines, RFC 4716 blocks, PEM CERTIFICATE / PUBLIC KEY blocks, or an armored PGP public key block.", "type": "string" } }, { "name": "format", "in": "query", "required": false, "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "schema": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } } ] }, "post": { "summary": "Fingerprint SSH keys, X.509 certificates, SPKI public keys, and OpenPGP keys.", "description": "Finds every public key in `input` and returns its fingerprints in the formats other tools print. SSH: `ssh-keygen -l` SHA256 and MD5. Certificates: `openssl x509 -fingerprint` SHA-1 and SHA-256 over the DER, plus the RFC 7469 SPKI pin. PEM public keys: SHA-256 over the SubjectPublicKeyInfo. Where an equivalent exists, the SSH fingerprint of the same key is included, so you can confirm that a certificate and an SSH key share a key. OpenPGP: v4 (SHA-1) and v6 (SHA-256) fingerprints and key IDs for the primary key and subkeys. Private keys are refused.\n\nPrivacy: The server receives the public key text, computes fingerprints in memory, and returns them. Public keys are not secret, but the input is not stored or logged (only the per-call metadata row is recorded). If the input contains a private key, the server rejects it before parsing; treat a private key sent anywhere you do not control as exposed.", "tags": [ "fingerprint" ], "responses": { "200": { "description": "Success. With format=text, text/plain is returned instead of JSON.", "content": { "application/json": { "schema": { "type": "object", "description": "", "properties": { "items": { "type": "array", "items": { "description": "One entry per key found, discriminated by `kind`.", "anyOf": [ { "type": "object", "description": "", "properties": { "kind": { "type": "string", "const": "ssh", "description": "SSH public key." }, "type": { "type": "string", "description": "Key type, e.g. `ssh-ed25519`." }, "bits": { "type": [ "integer", "null" ], "description": "Key size." }, "comment": { "type": "string", "description": "Trailing comment, often user@host." }, "ssh": { "type": "object", "description": "", "properties": { "sha256": { "type": "string", "description": "`SHA256:` + unpadded Base64, as printed by `ssh-keygen -l`." }, "md5": { "type": "string", "description": "`MD5:` + colon hex, as printed by `ssh-keygen -E md5 -l`." } }, "required": [ "sha256", "md5" ], "additionalProperties": false } }, "required": [ "kind", "type", "bits", "comment", "ssh" ], "additionalProperties": false }, { "type": "object", "description": "", "properties": { "kind": { "type": "string", "const": "certificate", "description": "X.509 certificate." }, "subject": { "type": "string", "description": "Subject DN." }, "sha1": { "type": "string", "description": "SHA-1 of DER, colon hex." }, "sha256": { "type": "string", "description": "SHA-256 of DER, colon hex." }, "spkiSha256": { "type": "string", "description": "RFC 7469 pin." }, "ssh": { "type": [ "object", "null" ], "description": "", "properties": { "sha256": { "type": "string", "description": "`SHA256:` + unpadded Base64, as printed by `ssh-keygen -l`." }, "md5": { "type": "string", "description": "`MD5:` + colon hex, as printed by `ssh-keygen -E md5 -l`." } }, "required": [ "sha256", "md5" ], "additionalProperties": false } }, "required": [ "kind", "subject", "sha1", "sha256", "spkiSha256", "ssh" ], "additionalProperties": false }, { "type": "object", "description": "", "properties": { "kind": { "type": "string", "const": "public-key", "description": "PEM SubjectPublicKeyInfo." }, "algorithm": { "type": "string", "description": "Key algorithm." }, "spkiSha256Hex": { "type": "string", "description": "SHA-256 of the SPKI DER, colon hex." }, "spkiSha256": { "type": "string", "description": "RFC 7469 pin." }, "ssh": { "type": [ "object", "null" ], "description": "", "properties": { "sha256": { "type": "string", "description": "`SHA256:` + unpadded Base64, as printed by `ssh-keygen -l`." }, "md5": { "type": "string", "description": "`MD5:` + colon hex, as printed by `ssh-keygen -E md5 -l`." } }, "required": [ "sha256", "md5" ], "additionalProperties": false } }, "required": [ "kind", "algorithm", "spkiSha256Hex", "spkiSha256", "ssh" ], "additionalProperties": false }, { "type": "object", "description": "", "properties": { "kind": { "type": "string", "const": "pgp", "description": "OpenPGP public key." }, "userIds": { "type": "array", "items": { "type": "string", "description": "User ID packet text." }, "description": "User IDs (not verified against self-signatures)." }, "keys": { "type": "array", "items": { "type": "object", "description": "", "properties": { "role": { "type": "string", "description": "`primary` or `subkey`.", "enum": [ "primary", "subkey" ] }, "version": { "type": "integer", "description": "Key packet version (4, 5 or 6)." }, "fingerprint": { "type": "string", "description": "Uppercase hex fingerprint." }, "grouped": { "type": "string", "description": "Fingerprint in groups of four, as GnuPG prints it." }, "keyId": { "type": "string", "description": "Key ID: last 8 bytes (v4) or first 8 bytes (v5/v6) of the fingerprint." }, "algorithm": { "type": "string", "description": "Public key algorithm." }, "bits": { "type": [ "integer", "null" ], "description": "Key size." }, "created": { "type": "string", "description": "Key creation time, ISO 8601.", "format": "date-time" } }, "required": [ "role", "version", "fingerprint", "grouped", "keyId", "algorithm", "bits", "created" ], "additionalProperties": false }, "description": "Primary key and subkeys." } }, "required": [ "kind", "userIds", "keys" ], "additionalProperties": false } ] }, "description": "Keys found, in input order by format." } }, "required": [ "items" ], "additionalProperties": false } } } }, "400": { "description": "missing_parameter / unknown_parameter / invalid_parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "No public key is found, a key is malformed, or the input contains a private key (which is refused without being parsed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "fingerprint", "parameters": [ { "name": "format", "in": "query", "required": false, "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "schema": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "input": { "description": "One or more SSH public key lines, RFC 4716 blocks, PEM CERTIFICATE / PUBLIC KEY blocks, or an armored PGP public key block.", "type": "string" }, "format": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } }, "required": [ "input" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "The body is used as the `input` parameter." } } } } } }, "/api/cert/decode": { "get": { "summary": "Decode X.509 certificates, chains, and certificate requests.", "description": "Decodes every certificate (PEM, DER, Base64 DER, or PKCS#7 bundle) and CSR in the input. For chains it checks, for each adjacent pair, that the issuer name matches and that the signature verifies with the next certificate's key. With `hostname` it reports which certificates cover that name under RFC 6125 wildcard rules. It does not establish trust: there is no root store, and revocation (OCSP/CRL) is not checked.\n\nPrivacy: The server receives the certificate data, decodes it in memory, and returns the decoded fields. Certificates and CSRs are public by design, but the input is not stored or logged (only the per-call metadata row is recorded). The server makes no network requests (it does not fetch OCSP, CRLs or issuer certificates). Private keys in the input are rejected.", "tags": [ "cert" ], "responses": { "200": { "description": "Success. With format=text, text/plain is returned instead of JSON.", "content": { "application/json": { "schema": { "type": "object", "description": "", "properties": { "certificates": { "type": "array", "items": { "type": "object", "description": "", "properties": { "subject": { "type": "string", "description": "Subject distinguished name (RFC 4514 string)." }, "issuer": { "type": "string", "description": "Issuer distinguished name." }, "serialNumber": { "type": "string", "description": "Serial number as colon-separated uppercase hex." }, "signatureAlgorithm": { "type": "string", "description": "Signature algorithm, e.g. `RSA PKCS#1 v1.5 with SHA-256`." }, "validity": { "type": "object", "description": "", "properties": { "notBefore": { "type": "string", "description": "ISO 8601 UTC.", "format": "date-time" }, "notAfter": { "type": "string", "description": "ISO 8601 UTC.", "format": "date-time" }, "status": { "type": "string", "description": "Relative to `at` (default: now).", "enum": [ "valid", "expired", "not-yet-valid" ] }, "daysRemaining": { "type": "integer", "description": "Whole days until notAfter; negative once expired." } }, "required": [ "notBefore", "notAfter", "status", "daysRemaining" ], "additionalProperties": false }, "publicKey": { "type": "object", "description": "", "properties": { "algorithm": { "type": "string", "description": "`RSA`, `EC`, `Ed25519`, `X25519`, or the algorithm OID name." }, "bits": { "type": [ "integer", "null" ], "description": "Key size in bits (RSA modulus, EC field size)." }, "curve": { "type": [ "string", "null" ], "description": "Named curve for EC keys (`P-256`, …)." }, "spkiSha256": { "type": "string", "description": "RFC 7469 pin: Base64(SHA-256(SubjectPublicKeyInfo))." } }, "required": [ "algorithm", "bits", "curve", "spkiSha256" ], "additionalProperties": false }, "subjectAltNames": { "type": "array", "items": { "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "`dns`, `ip`, `email`, `url`, `dn`, …" }, "value": { "type": "string", "description": "The name." } }, "required": [ "type", "value" ], "additionalProperties": false }, "description": "Subject alternative names." }, "keyUsage": { "type": "array", "items": { "type": "string", "description": "RFC 5280 key usage bit name." }, "description": "Key usage extension bits." }, "extendedKeyUsage": { "type": "array", "items": { "type": "string", "description": "Purpose name, or OID if unknown." }, "description": "Extended key usage purposes." }, "basicConstraints": { "type": [ "object", "null" ], "description": "", "properties": { "ca": { "type": "boolean", "description": "Whether this is a CA certificate." }, "pathLength": { "type": [ "integer", "null" ], "description": "Max intermediate CAs below this one." } }, "required": [ "ca", "pathLength" ], "additionalProperties": false }, "subjectKeyId": { "type": [ "string", "null" ], "description": "Subject key identifier, hex." }, "authorityKeyId": { "type": [ "string", "null" ], "description": "Authority key identifier, hex." }, "ocsp": { "type": "array", "items": { "type": "string", "description": "URL" }, "description": "OCSP responder URLs (AIA)." }, "caIssuers": { "type": "array", "items": { "type": "string", "description": "URL" }, "description": "Issuer certificate URLs (AIA)." }, "crlDistributionPoints": { "type": "array", "items": { "type": "string", "description": "URL" }, "description": "CRL URLs." }, "policies": { "type": "array", "items": { "type": "string", "description": "Policy name or OID." }, "description": "Certificate policies (DV/OV/EV are named)." }, "embeddedScts": { "type": "boolean", "description": "True when Certificate Transparency SCTs are embedded." }, "selfSigned": { "type": "boolean", "description": "True when subject equals issuer and the signature verifies with its own key." }, "fingerprints": { "type": "object", "description": "", "properties": { "sha1": { "type": "string", "description": "SHA-1 of the DER, colon hex." }, "sha256": { "type": "string", "description": "SHA-256 of the DER, colon hex." } }, "required": [ "sha1", "sha256" ], "additionalProperties": false }, "pem": { "type": "string", "description": "The certificate re-encoded as PEM." } }, "required": [ "subject", "issuer", "serialNumber", "signatureAlgorithm", "validity", "publicKey", "subjectAltNames", "keyUsage", "extendedKeyUsage", "basicConstraints", "subjectKeyId", "authorityKeyId", "ocsp", "caIssuers", "crlDistributionPoints", "policies", "embeddedScts", "selfSigned", "fingerprints", "pem" ], "additionalProperties": false }, "description": "Certificates in input order (leaf first in a well-ordered chain)." }, "chain": { "type": "object", "description": "", "properties": { "links": { "type": "array", "items": { "type": "object", "description": "", "properties": { "child": { "type": "integer", "description": "Index of the certificate." }, "parent": { "type": "integer", "description": "Index of the next certificate." }, "issuerNameMatches": { "type": "boolean", "description": "child.issuer equals parent.subject." }, "signatureValid": { "type": "boolean", "description": "child's signature verifies with parent's public key." } }, "required": [ "child", "parent", "issuerNameMatches", "signatureValid" ], "additionalProperties": false }, "description": "One link per adjacent pair." }, "ordered": { "type": "boolean", "description": "Every link matches by name and signature." }, "endsAtSelfSigned": { "type": "boolean", "description": "The last certificate is self-signed (a root)." }, "notes": { "type": "array", "items": { "type": "string", "description": "Plain-language finding." }, "description": "Problems and observations about the chain." } }, "required": [ "links", "ordered", "endsAtSelfSigned", "notes" ], "additionalProperties": false }, "requests": { "type": "array", "items": { "type": "object", "description": "", "properties": { "subject": { "type": "string", "description": "Requested subject DN." }, "signatureAlgorithm": { "type": "string", "description": "Signature algorithm." }, "signatureValid": { "type": "boolean", "description": "The CSR self-signature verifies (proves possession of the private key)." }, "publicKey": { "type": "object", "description": "", "properties": { "algorithm": { "type": "string", "description": "`RSA`, `EC`, `Ed25519`, `X25519`, or the algorithm OID name." }, "bits": { "type": [ "integer", "null" ], "description": "Key size in bits (RSA modulus, EC field size)." }, "curve": { "type": [ "string", "null" ], "description": "Named curve for EC keys (`P-256`, …)." }, "spkiSha256": { "type": "string", "description": "RFC 7469 pin: Base64(SHA-256(SubjectPublicKeyInfo))." } }, "required": [ "algorithm", "bits", "curve", "spkiSha256" ], "additionalProperties": false }, "subjectAltNames": { "type": "array", "items": { "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "`dns`, `ip`, `email`, `url`, `dn`, …" }, "value": { "type": "string", "description": "The name." } }, "required": [ "type", "value" ], "additionalProperties": false }, "description": "Subject alternative names." }, "pem": { "type": "string", "description": "The request re-encoded as PEM." } }, "required": [ "subject", "signatureAlgorithm", "signatureValid", "publicKey", "subjectAltNames", "pem" ], "additionalProperties": false }, "description": "Certificate signing requests (PKCS#10)." }, "hostname": { "type": [ "object", "null" ], "description": "", "properties": { "name": { "type": "string", "description": "Host name checked." }, "coveredBy": { "type": "array", "items": { "type": "integer", "description": "Certificate index." }, "description": "Certificates whose DNS SANs match." } }, "required": [ "name", "coveredBy" ], "additionalProperties": false } }, "required": [ "certificates", "chain", "requests", "hostname" ], "additionalProperties": false } } } }, "400": { "description": "missing_parameter / unknown_parameter / `at` is not a valid date, or more than one data source is given.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "No certificate or CSR is found, the data is malformed, or the input contains a private key (refused).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "cert_decode_get", "parameters": [ { "name": "input", "in": "query", "required": false, "description": "PEM text (one or more blocks) or Base64 DER. Use exactly one of input, input_base64, or a file upload (.pem, .crt, .cer, .der, .p7b, .csr).", "schema": { "description": "PEM text (one or more blocks) or Base64 DER. Use exactly one of input, input_base64, or a file upload (.pem, .crt, .cer, .der, .p7b, .csr).", "type": "string" } }, { "name": "input_base64", "in": "query", "required": false, "description": "Data as Base64 (either alphabet), for binary content over JSON or MCP.", "schema": { "description": "Data as Base64 (either alphabet), for binary content over JSON or MCP.", "type": "string" } }, { "name": "hostname", "in": "query", "required": false, "description": "Report whether each certificate's DNS SANs cover this host name.", "schema": { "description": "Report whether each certificate's DNS SANs cover this host name.", "type": "string" } }, { "name": "at", "in": "query", "required": false, "description": "Evaluate validity at this ISO 8601 time instead of now, e.g. 2026-01-01T00:00:00Z.", "schema": { "description": "Evaluate validity at this ISO 8601 time instead of now, e.g. 2026-01-01T00:00:00Z.", "type": "string" } }, { "name": "format", "in": "query", "required": false, "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "schema": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } } ] }, "post": { "summary": "Decode X.509 certificates, chains, and certificate requests.", "description": "Decodes every certificate (PEM, DER, Base64 DER, or PKCS#7 bundle) and CSR in the input. For chains it checks, for each adjacent pair, that the issuer name matches and that the signature verifies with the next certificate's key. With `hostname` it reports which certificates cover that name under RFC 6125 wildcard rules. It does not establish trust: there is no root store, and revocation (OCSP/CRL) is not checked.\n\nPrivacy: The server receives the certificate data, decodes it in memory, and returns the decoded fields. Certificates and CSRs are public by design, but the input is not stored or logged (only the per-call metadata row is recorded). The server makes no network requests (it does not fetch OCSP, CRLs or issuer certificates). Private keys in the input are rejected.", "tags": [ "cert" ], "responses": { "200": { "description": "Success. With format=text, text/plain is returned instead of JSON.", "content": { "application/json": { "schema": { "type": "object", "description": "", "properties": { "certificates": { "type": "array", "items": { "type": "object", "description": "", "properties": { "subject": { "type": "string", "description": "Subject distinguished name (RFC 4514 string)." }, "issuer": { "type": "string", "description": "Issuer distinguished name." }, "serialNumber": { "type": "string", "description": "Serial number as colon-separated uppercase hex." }, "signatureAlgorithm": { "type": "string", "description": "Signature algorithm, e.g. `RSA PKCS#1 v1.5 with SHA-256`." }, "validity": { "type": "object", "description": "", "properties": { "notBefore": { "type": "string", "description": "ISO 8601 UTC.", "format": "date-time" }, "notAfter": { "type": "string", "description": "ISO 8601 UTC.", "format": "date-time" }, "status": { "type": "string", "description": "Relative to `at` (default: now).", "enum": [ "valid", "expired", "not-yet-valid" ] }, "daysRemaining": { "type": "integer", "description": "Whole days until notAfter; negative once expired." } }, "required": [ "notBefore", "notAfter", "status", "daysRemaining" ], "additionalProperties": false }, "publicKey": { "type": "object", "description": "", "properties": { "algorithm": { "type": "string", "description": "`RSA`, `EC`, `Ed25519`, `X25519`, or the algorithm OID name." }, "bits": { "type": [ "integer", "null" ], "description": "Key size in bits (RSA modulus, EC field size)." }, "curve": { "type": [ "string", "null" ], "description": "Named curve for EC keys (`P-256`, …)." }, "spkiSha256": { "type": "string", "description": "RFC 7469 pin: Base64(SHA-256(SubjectPublicKeyInfo))." } }, "required": [ "algorithm", "bits", "curve", "spkiSha256" ], "additionalProperties": false }, "subjectAltNames": { "type": "array", "items": { "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "`dns`, `ip`, `email`, `url`, `dn`, …" }, "value": { "type": "string", "description": "The name." } }, "required": [ "type", "value" ], "additionalProperties": false }, "description": "Subject alternative names." }, "keyUsage": { "type": "array", "items": { "type": "string", "description": "RFC 5280 key usage bit name." }, "description": "Key usage extension bits." }, "extendedKeyUsage": { "type": "array", "items": { "type": "string", "description": "Purpose name, or OID if unknown." }, "description": "Extended key usage purposes." }, "basicConstraints": { "type": [ "object", "null" ], "description": "", "properties": { "ca": { "type": "boolean", "description": "Whether this is a CA certificate." }, "pathLength": { "type": [ "integer", "null" ], "description": "Max intermediate CAs below this one." } }, "required": [ "ca", "pathLength" ], "additionalProperties": false }, "subjectKeyId": { "type": [ "string", "null" ], "description": "Subject key identifier, hex." }, "authorityKeyId": { "type": [ "string", "null" ], "description": "Authority key identifier, hex." }, "ocsp": { "type": "array", "items": { "type": "string", "description": "URL" }, "description": "OCSP responder URLs (AIA)." }, "caIssuers": { "type": "array", "items": { "type": "string", "description": "URL" }, "description": "Issuer certificate URLs (AIA)." }, "crlDistributionPoints": { "type": "array", "items": { "type": "string", "description": "URL" }, "description": "CRL URLs." }, "policies": { "type": "array", "items": { "type": "string", "description": "Policy name or OID." }, "description": "Certificate policies (DV/OV/EV are named)." }, "embeddedScts": { "type": "boolean", "description": "True when Certificate Transparency SCTs are embedded." }, "selfSigned": { "type": "boolean", "description": "True when subject equals issuer and the signature verifies with its own key." }, "fingerprints": { "type": "object", "description": "", "properties": { "sha1": { "type": "string", "description": "SHA-1 of the DER, colon hex." }, "sha256": { "type": "string", "description": "SHA-256 of the DER, colon hex." } }, "required": [ "sha1", "sha256" ], "additionalProperties": false }, "pem": { "type": "string", "description": "The certificate re-encoded as PEM." } }, "required": [ "subject", "issuer", "serialNumber", "signatureAlgorithm", "validity", "publicKey", "subjectAltNames", "keyUsage", "extendedKeyUsage", "basicConstraints", "subjectKeyId", "authorityKeyId", "ocsp", "caIssuers", "crlDistributionPoints", "policies", "embeddedScts", "selfSigned", "fingerprints", "pem" ], "additionalProperties": false }, "description": "Certificates in input order (leaf first in a well-ordered chain)." }, "chain": { "type": "object", "description": "", "properties": { "links": { "type": "array", "items": { "type": "object", "description": "", "properties": { "child": { "type": "integer", "description": "Index of the certificate." }, "parent": { "type": "integer", "description": "Index of the next certificate." }, "issuerNameMatches": { "type": "boolean", "description": "child.issuer equals parent.subject." }, "signatureValid": { "type": "boolean", "description": "child's signature verifies with parent's public key." } }, "required": [ "child", "parent", "issuerNameMatches", "signatureValid" ], "additionalProperties": false }, "description": "One link per adjacent pair." }, "ordered": { "type": "boolean", "description": "Every link matches by name and signature." }, "endsAtSelfSigned": { "type": "boolean", "description": "The last certificate is self-signed (a root)." }, "notes": { "type": "array", "items": { "type": "string", "description": "Plain-language finding." }, "description": "Problems and observations about the chain." } }, "required": [ "links", "ordered", "endsAtSelfSigned", "notes" ], "additionalProperties": false }, "requests": { "type": "array", "items": { "type": "object", "description": "", "properties": { "subject": { "type": "string", "description": "Requested subject DN." }, "signatureAlgorithm": { "type": "string", "description": "Signature algorithm." }, "signatureValid": { "type": "boolean", "description": "The CSR self-signature verifies (proves possession of the private key)." }, "publicKey": { "type": "object", "description": "", "properties": { "algorithm": { "type": "string", "description": "`RSA`, `EC`, `Ed25519`, `X25519`, or the algorithm OID name." }, "bits": { "type": [ "integer", "null" ], "description": "Key size in bits (RSA modulus, EC field size)." }, "curve": { "type": [ "string", "null" ], "description": "Named curve for EC keys (`P-256`, …)." }, "spkiSha256": { "type": "string", "description": "RFC 7469 pin: Base64(SHA-256(SubjectPublicKeyInfo))." } }, "required": [ "algorithm", "bits", "curve", "spkiSha256" ], "additionalProperties": false }, "subjectAltNames": { "type": "array", "items": { "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "`dns`, `ip`, `email`, `url`, `dn`, …" }, "value": { "type": "string", "description": "The name." } }, "required": [ "type", "value" ], "additionalProperties": false }, "description": "Subject alternative names." }, "pem": { "type": "string", "description": "The request re-encoded as PEM." } }, "required": [ "subject", "signatureAlgorithm", "signatureValid", "publicKey", "subjectAltNames", "pem" ], "additionalProperties": false }, "description": "Certificate signing requests (PKCS#10)." }, "hostname": { "type": [ "object", "null" ], "description": "", "properties": { "name": { "type": "string", "description": "Host name checked." }, "coveredBy": { "type": "array", "items": { "type": "integer", "description": "Certificate index." }, "description": "Certificates whose DNS SANs match." } }, "required": [ "name", "coveredBy" ], "additionalProperties": false } }, "required": [ "certificates", "chain", "requests", "hostname" ], "additionalProperties": false } } } }, "400": { "description": "missing_parameter / unknown_parameter / `at` is not a valid date, or more than one data source is given.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "No certificate or CSR is found, the data is malformed, or the input contains a private key (refused).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "cert_decode", "parameters": [ { "name": "format", "in": "query", "required": false, "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "schema": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "input": { "description": "PEM text (one or more blocks) or Base64 DER. Use exactly one of input, input_base64, or a file upload (.pem, .crt, .cer, .der, .p7b, .csr).", "type": "string" }, "input_base64": { "description": "Data as Base64 (either alphabet), for binary content over JSON or MCP.", "type": "string" }, "hostname": { "description": "Report whether each certificate's DNS SANs cover this host name.", "type": "string" }, "at": { "description": "Evaluate validity at this ISO 8601 time instead of now, e.g. 2026-01-01T00:00:00Z.", "type": "string" }, "format": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } }, "required": [], "additionalProperties": false } }, "multipart/form-data": { "schema": { "type": "object", "properties": { "input": { "description": "PEM text (one or more blocks) or Base64 DER. Use exactly one of input, input_base64, or a file upload (.pem, .crt, .cer, .der, .p7b, .csr).", "type": "string" }, "input_base64": { "description": "Data as Base64 (either alphabet), for binary content over JSON or MCP.", "type": "string" }, "hostname": { "description": "Report whether each certificate's DNS SANs cover this host name.", "type": "string" }, "at": { "description": "Evaluate validity at this ISO 8601 time instead of now, e.g. 2026-01-01T00:00:00Z.", "type": "string" }, "format": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" }, "file": { "type": "string", "format": "binary", "description": "File to process (first file field is used)." } }, "required": [], "additionalProperties": false } }, "application/octet-stream": { "schema": { "type": "string", "format": "binary" } }, "text/plain": { "schema": { "type": "string", "description": "The body is used as the `input` parameter." } } } } } }, "/api/tls/check": { "get": { "summary": "Connect to a host and check the certificate chain it presents: trust, host name, expiry, protocol.", "description": "Connects to `host:port` with OpenSSL 3, using SNI, and verifies the presented chain against the Mozilla root store, including host name verification (RFC 6125). It reports OpenSSL's verdict and every verify error with its chain depth, plus the negotiated protocol, cipher and key-exchange group. The chain is then decoded exactly as `cert_decode` would, with ordering, signature and expiry notes. Only direct TLS is supported (no STARTTLS). Revocation (OCSP/CRL) is not checked.\n\nPrivacy: The server receives the host name and port, and forwards them to the TLS checker operated by this service, which connects to that host. Nothing else is sent, and nothing is stored or logged apart from the per-call metadata row. The target host sees a TLS connection from the checker's network, not from you.", "tags": [ "tls" ], "responses": { "200": { "description": "Success. With format=text, text/plain is returned instead of JSON.", "content": { "application/json": { "schema": { "type": "object", "description": "", "properties": { "host": { "type": "string", "description": "Host as requested." }, "port": { "type": "integer", "description": "Port connected to." }, "address": { "type": "string", "description": "IP address actually connected to (DNS is resolved once, then pinned)." }, "servername": { "type": [ "string", "null" ], "description": "SNI and verification name used." }, "trusted": { "type": "boolean", "description": "True when OpenSSL verified the chain to a Mozilla root and the host name matched." }, "verification": { "type": "object", "description": "", "properties": { "ok": { "type": "boolean", "description": "Same as `trusted`." }, "code": { "type": [ "integer", "null" ], "description": "OpenSSL verify return code (0 = ok; 10 expired; 18/19 self-signed; 20 unknown issuer; 62 host name mismatch)." }, "message": { "type": [ "string", "null" ], "description": "OpenSSL's description of that code." }, "errors": { "type": "array", "items": { "type": "object", "description": "", "properties": { "code": { "type": "integer", "description": "OpenSSL verify error number." }, "message": { "type": "string", "description": "Description." }, "depth": { "type": [ "integer", "null" ], "description": "Chain position: 0 is the leaf." } }, "required": [ "code", "message", "depth" ], "additionalProperties": false }, "description": "Every verification error OpenSSL reported." } }, "required": [ "ok", "code", "message", "errors" ], "additionalProperties": false }, "protocol": { "type": [ "string", "null" ], "description": "Negotiated protocol, e.g. `TLSv1.3`." }, "cipher": { "type": [ "string", "null" ], "description": "Negotiated cipher suite." }, "key_exchange_group": { "type": [ "string", "null" ], "description": "Key exchange group, e.g. `X25519MLKEM768` (post-quantum hybrid) or `X25519`." }, "peer_signature_type": { "type": [ "string", "null" ], "description": "Signature scheme the server used in the handshake." }, "handshake_ms": { "type": "integer", "description": "Connection and handshake time from the checker." }, "certificates": { "type": "array", "items": { "type": "object", "description": "", "properties": { "subject": { "type": "string", "description": "Subject distinguished name (RFC 4514 string)." }, "issuer": { "type": "string", "description": "Issuer distinguished name." }, "serialNumber": { "type": "string", "description": "Serial number as colon-separated uppercase hex." }, "signatureAlgorithm": { "type": "string", "description": "Signature algorithm, e.g. `RSA PKCS#1 v1.5 with SHA-256`." }, "validity": { "type": "object", "description": "", "properties": { "notBefore": { "type": "string", "description": "ISO 8601 UTC.", "format": "date-time" }, "notAfter": { "type": "string", "description": "ISO 8601 UTC.", "format": "date-time" }, "status": { "type": "string", "description": "Relative to `at` (default: now).", "enum": [ "valid", "expired", "not-yet-valid" ] }, "daysRemaining": { "type": "integer", "description": "Whole days until notAfter; negative once expired." } }, "required": [ "notBefore", "notAfter", "status", "daysRemaining" ], "additionalProperties": false }, "publicKey": { "type": "object", "description": "", "properties": { "algorithm": { "type": "string", "description": "`RSA`, `EC`, `Ed25519`, `X25519`, or the algorithm OID name." }, "bits": { "type": [ "integer", "null" ], "description": "Key size in bits (RSA modulus, EC field size)." }, "curve": { "type": [ "string", "null" ], "description": "Named curve for EC keys (`P-256`, …)." }, "spkiSha256": { "type": "string", "description": "RFC 7469 pin: Base64(SHA-256(SubjectPublicKeyInfo))." } }, "required": [ "algorithm", "bits", "curve", "spkiSha256" ], "additionalProperties": false }, "subjectAltNames": { "type": "array", "items": { "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "`dns`, `ip`, `email`, `url`, `dn`, …" }, "value": { "type": "string", "description": "The name." } }, "required": [ "type", "value" ], "additionalProperties": false }, "description": "Subject alternative names." }, "keyUsage": { "type": "array", "items": { "type": "string", "description": "RFC 5280 key usage bit name." }, "description": "Key usage extension bits." }, "extendedKeyUsage": { "type": "array", "items": { "type": "string", "description": "Purpose name, or OID if unknown." }, "description": "Extended key usage purposes." }, "basicConstraints": { "type": [ "object", "null" ], "description": "", "properties": { "ca": { "type": "boolean", "description": "Whether this is a CA certificate." }, "pathLength": { "type": [ "integer", "null" ], "description": "Max intermediate CAs below this one." } }, "required": [ "ca", "pathLength" ], "additionalProperties": false }, "subjectKeyId": { "type": [ "string", "null" ], "description": "Subject key identifier, hex." }, "authorityKeyId": { "type": [ "string", "null" ], "description": "Authority key identifier, hex." }, "ocsp": { "type": "array", "items": { "type": "string", "description": "URL" }, "description": "OCSP responder URLs (AIA)." }, "caIssuers": { "type": "array", "items": { "type": "string", "description": "URL" }, "description": "Issuer certificate URLs (AIA)." }, "crlDistributionPoints": { "type": "array", "items": { "type": "string", "description": "URL" }, "description": "CRL URLs." }, "policies": { "type": "array", "items": { "type": "string", "description": "Policy name or OID." }, "description": "Certificate policies (DV/OV/EV are named)." }, "embeddedScts": { "type": "boolean", "description": "True when Certificate Transparency SCTs are embedded." }, "selfSigned": { "type": "boolean", "description": "True when subject equals issuer and the signature verifies with its own key." }, "fingerprints": { "type": "object", "description": "", "properties": { "sha1": { "type": "string", "description": "SHA-1 of the DER, colon hex." }, "sha256": { "type": "string", "description": "SHA-256 of the DER, colon hex." } }, "required": [ "sha1", "sha256" ], "additionalProperties": false }, "pem": { "type": "string", "description": "The certificate re-encoded as PEM." } }, "required": [ "subject", "issuer", "serialNumber", "signatureAlgorithm", "validity", "publicKey", "subjectAltNames", "keyUsage", "extendedKeyUsage", "basicConstraints", "subjectKeyId", "authorityKeyId", "ocsp", "caIssuers", "crlDistributionPoints", "policies", "embeddedScts", "selfSigned", "fingerprints", "pem" ], "additionalProperties": false }, "description": "The chain as presented, leaf first, decoded." }, "notes": { "type": "array", "items": { "type": "string", "description": "Finding." }, "description": "Chain observations from the decoder (order, gaps, expiry, host-name coverage)." }, "checked_at": { "type": "string", "description": "When the check ran.", "format": "date-time" } }, "required": [ "host", "port", "address", "servername", "trusted", "verification", "protocol", "cipher", "key_exchange_group", "peer_signature_type", "handshake_ms", "certificates", "notes", "checked_at" ], "additionalProperties": false } } } }, "400": { "description": "missing_parameter / unknown_parameter / The host is not a DNS name or IP address, or the port is not allowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The host does not resolve, resolves to a non-public address, refuses the connection, or does not speak TLS.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The TLS checker failed or timed out (10 s).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The TLS checker is not configured on this deployment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "tls_check_get", "parameters": [ { "name": "host", "in": "query", "required": true, "description": "Public DNS name or IP address. Private, loopback, link-local, CGNAT and documentation addresses are refused, both as given and after DNS resolution.", "schema": { "description": "Public DNS name or IP address. Private, loopback, link-local, CGNAT and documentation addresses are refused, both as given and after DNS resolution.", "type": "string" } }, { "name": "port", "in": "query", "required": false, "description": "TCP port. Only ports that speak TLS directly are allowed.", "schema": { "description": "TCP port. Only ports that speak TLS directly are allowed.", "type": "integer", "enum": [ 443, 8443, 465, 636, 853, 993, 995, 5061 ], "default": 443 } }, { "name": "servername", "in": "query", "required": false, "description": "SNI and verification name, if different from host (for example when host is an IP address).", "schema": { "description": "SNI and verification name, if different from host (for example when host is an IP address).", "type": "string" } }, { "name": "format", "in": "query", "required": false, "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "schema": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } } ] }, "post": { "summary": "Connect to a host and check the certificate chain it presents: trust, host name, expiry, protocol.", "description": "Connects to `host:port` with OpenSSL 3, using SNI, and verifies the presented chain against the Mozilla root store, including host name verification (RFC 6125). It reports OpenSSL's verdict and every verify error with its chain depth, plus the negotiated protocol, cipher and key-exchange group. The chain is then decoded exactly as `cert_decode` would, with ordering, signature and expiry notes. Only direct TLS is supported (no STARTTLS). Revocation (OCSP/CRL) is not checked.\n\nPrivacy: The server receives the host name and port, and forwards them to the TLS checker operated by this service, which connects to that host. Nothing else is sent, and nothing is stored or logged apart from the per-call metadata row. The target host sees a TLS connection from the checker's network, not from you.", "tags": [ "tls" ], "responses": { "200": { "description": "Success. With format=text, text/plain is returned instead of JSON.", "content": { "application/json": { "schema": { "type": "object", "description": "", "properties": { "host": { "type": "string", "description": "Host as requested." }, "port": { "type": "integer", "description": "Port connected to." }, "address": { "type": "string", "description": "IP address actually connected to (DNS is resolved once, then pinned)." }, "servername": { "type": [ "string", "null" ], "description": "SNI and verification name used." }, "trusted": { "type": "boolean", "description": "True when OpenSSL verified the chain to a Mozilla root and the host name matched." }, "verification": { "type": "object", "description": "", "properties": { "ok": { "type": "boolean", "description": "Same as `trusted`." }, "code": { "type": [ "integer", "null" ], "description": "OpenSSL verify return code (0 = ok; 10 expired; 18/19 self-signed; 20 unknown issuer; 62 host name mismatch)." }, "message": { "type": [ "string", "null" ], "description": "OpenSSL's description of that code." }, "errors": { "type": "array", "items": { "type": "object", "description": "", "properties": { "code": { "type": "integer", "description": "OpenSSL verify error number." }, "message": { "type": "string", "description": "Description." }, "depth": { "type": [ "integer", "null" ], "description": "Chain position: 0 is the leaf." } }, "required": [ "code", "message", "depth" ], "additionalProperties": false }, "description": "Every verification error OpenSSL reported." } }, "required": [ "ok", "code", "message", "errors" ], "additionalProperties": false }, "protocol": { "type": [ "string", "null" ], "description": "Negotiated protocol, e.g. `TLSv1.3`." }, "cipher": { "type": [ "string", "null" ], "description": "Negotiated cipher suite." }, "key_exchange_group": { "type": [ "string", "null" ], "description": "Key exchange group, e.g. `X25519MLKEM768` (post-quantum hybrid) or `X25519`." }, "peer_signature_type": { "type": [ "string", "null" ], "description": "Signature scheme the server used in the handshake." }, "handshake_ms": { "type": "integer", "description": "Connection and handshake time from the checker." }, "certificates": { "type": "array", "items": { "type": "object", "description": "", "properties": { "subject": { "type": "string", "description": "Subject distinguished name (RFC 4514 string)." }, "issuer": { "type": "string", "description": "Issuer distinguished name." }, "serialNumber": { "type": "string", "description": "Serial number as colon-separated uppercase hex." }, "signatureAlgorithm": { "type": "string", "description": "Signature algorithm, e.g. `RSA PKCS#1 v1.5 with SHA-256`." }, "validity": { "type": "object", "description": "", "properties": { "notBefore": { "type": "string", "description": "ISO 8601 UTC.", "format": "date-time" }, "notAfter": { "type": "string", "description": "ISO 8601 UTC.", "format": "date-time" }, "status": { "type": "string", "description": "Relative to `at` (default: now).", "enum": [ "valid", "expired", "not-yet-valid" ] }, "daysRemaining": { "type": "integer", "description": "Whole days until notAfter; negative once expired." } }, "required": [ "notBefore", "notAfter", "status", "daysRemaining" ], "additionalProperties": false }, "publicKey": { "type": "object", "description": "", "properties": { "algorithm": { "type": "string", "description": "`RSA`, `EC`, `Ed25519`, `X25519`, or the algorithm OID name." }, "bits": { "type": [ "integer", "null" ], "description": "Key size in bits (RSA modulus, EC field size)." }, "curve": { "type": [ "string", "null" ], "description": "Named curve for EC keys (`P-256`, …)." }, "spkiSha256": { "type": "string", "description": "RFC 7469 pin: Base64(SHA-256(SubjectPublicKeyInfo))." } }, "required": [ "algorithm", "bits", "curve", "spkiSha256" ], "additionalProperties": false }, "subjectAltNames": { "type": "array", "items": { "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "`dns`, `ip`, `email`, `url`, `dn`, …" }, "value": { "type": "string", "description": "The name." } }, "required": [ "type", "value" ], "additionalProperties": false }, "description": "Subject alternative names." }, "keyUsage": { "type": "array", "items": { "type": "string", "description": "RFC 5280 key usage bit name." }, "description": "Key usage extension bits." }, "extendedKeyUsage": { "type": "array", "items": { "type": "string", "description": "Purpose name, or OID if unknown." }, "description": "Extended key usage purposes." }, "basicConstraints": { "type": [ "object", "null" ], "description": "", "properties": { "ca": { "type": "boolean", "description": "Whether this is a CA certificate." }, "pathLength": { "type": [ "integer", "null" ], "description": "Max intermediate CAs below this one." } }, "required": [ "ca", "pathLength" ], "additionalProperties": false }, "subjectKeyId": { "type": [ "string", "null" ], "description": "Subject key identifier, hex." }, "authorityKeyId": { "type": [ "string", "null" ], "description": "Authority key identifier, hex." }, "ocsp": { "type": "array", "items": { "type": "string", "description": "URL" }, "description": "OCSP responder URLs (AIA)." }, "caIssuers": { "type": "array", "items": { "type": "string", "description": "URL" }, "description": "Issuer certificate URLs (AIA)." }, "crlDistributionPoints": { "type": "array", "items": { "type": "string", "description": "URL" }, "description": "CRL URLs." }, "policies": { "type": "array", "items": { "type": "string", "description": "Policy name or OID." }, "description": "Certificate policies (DV/OV/EV are named)." }, "embeddedScts": { "type": "boolean", "description": "True when Certificate Transparency SCTs are embedded." }, "selfSigned": { "type": "boolean", "description": "True when subject equals issuer and the signature verifies with its own key." }, "fingerprints": { "type": "object", "description": "", "properties": { "sha1": { "type": "string", "description": "SHA-1 of the DER, colon hex." }, "sha256": { "type": "string", "description": "SHA-256 of the DER, colon hex." } }, "required": [ "sha1", "sha256" ], "additionalProperties": false }, "pem": { "type": "string", "description": "The certificate re-encoded as PEM." } }, "required": [ "subject", "issuer", "serialNumber", "signatureAlgorithm", "validity", "publicKey", "subjectAltNames", "keyUsage", "extendedKeyUsage", "basicConstraints", "subjectKeyId", "authorityKeyId", "ocsp", "caIssuers", "crlDistributionPoints", "policies", "embeddedScts", "selfSigned", "fingerprints", "pem" ], "additionalProperties": false }, "description": "The chain as presented, leaf first, decoded." }, "notes": { "type": "array", "items": { "type": "string", "description": "Finding." }, "description": "Chain observations from the decoder (order, gaps, expiry, host-name coverage)." }, "checked_at": { "type": "string", "description": "When the check ran.", "format": "date-time" } }, "required": [ "host", "port", "address", "servername", "trusted", "verification", "protocol", "cipher", "key_exchange_group", "peer_signature_type", "handshake_ms", "certificates", "notes", "checked_at" ], "additionalProperties": false } } } }, "400": { "description": "missing_parameter / unknown_parameter / The host is not a DNS name or IP address, or the port is not allowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The host does not resolve, resolves to a non-public address, refuses the connection, or does not speak TLS.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The TLS checker failed or timed out (10 s).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The TLS checker is not configured on this deployment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "tls_check", "parameters": [ { "name": "format", "in": "query", "required": false, "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "schema": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "host": { "description": "Public DNS name or IP address. Private, loopback, link-local, CGNAT and documentation addresses are refused, both as given and after DNS resolution.", "type": "string" }, "port": { "description": "TCP port. Only ports that speak TLS directly are allowed.", "type": "integer", "enum": [ 443, 8443, 465, 636, 853, 993, 995, 5061 ], "default": 443 }, "servername": { "description": "SNI and verification name, if different from host (for example when host is an IP address).", "type": "string" }, "format": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } }, "required": [ "host" ], "additionalProperties": false } } } } } }, "/api/jwt/decode": { "get": { "summary": "Decode a JWT, check its claims and algorithm, and optionally verify it with a public key.", "description": "Decodes a compact JWS (RFC 7515/7519): header, payload, and the registered claims, with `exp`, `nbf` and `iat` as ISO times and seconds relative to `at`. Flags expired, not-yet-valid, `alg: none`, weak or unusual algorithms, and a missing `exp`. A compact JWE (5 segments) is recognised and its header shown, but it cannot be decrypted. With `key`, verifies the signature using a PUBLIC key only: a JWK, a JWKS (selected by the token `kid`), a `PUBLIC KEY` PEM, or a `CERTIFICATE` PEM. HS256/HS384/HS512 cannot be verified here because they need a shared secret, which this service never accepts. The server never fetches keys: pass the JWKS JSON itself, not its URL. Decoding is not verification: never trust claims from a token whose `verification.outcome` is not `valid`.\n\nPrivacy: The server receives the token and, if given, a public key. It decodes and verifies them in memory and returns the result; the input is not stored or logged (only the per-call metadata row is recorded). The server makes no network requests (it never fetches `jku`, `x5u` or JWKS URLs). Tokens are bearer credentials: a token that has not expired grants access to whoever holds it, so prefer the page (which decodes in your browser) for live production tokens, or send tokens that are expired or from test systems.", "tags": [ "jwt" ], "responses": { "200": { "description": "Success. With format=text, text/plain is returned instead of JSON.", "content": { "application/json": { "schema": { "type": "object", "description": "", "properties": { "format": { "type": "string", "description": "`JWS` (signed, 3 segments) or `JWE` (encrypted, 5 segments).", "enum": [ "JWS", "JWE" ] }, "header": { "type": "object", "description": "The decoded (protected) JOSE header, exactly as sent.", "additionalProperties": true }, "payload": { "type": [ "object", "null" ], "description": "The decoded claims set. Null for a JWE or when the payload is not a JSON object.", "additionalProperties": true }, "payloadText": { "type": [ "string", "null" ], "description": "The payload as text when it is UTF-8 but not a JSON object (a JWS that is not a JWT)." }, "algorithm": { "type": "object", "description": "", "properties": { "alg": { "type": [ "string", "null" ], "description": "The header `alg`." }, "family": { "type": "string", "description": "Algorithm family. `unknown` for JWE or unregistered values.", "enum": [ "HMAC", "RSASSA-PKCS1-v1_5", "RSASSA-PSS", "ECDSA", "EdDSA", "ML-DSA", "none", "unknown" ] }, "registered": { "type": "boolean", "description": "True when `alg` is a registered JWS algorithm known to this tool." }, "symmetric": { "type": "boolean", "description": "True for HS256/HS384/HS512 (shared-secret HMAC)." }, "enc": { "type": [ "string", "null" ], "description": "JWE content encryption (`enc`), for encrypted tokens." } }, "required": [ "alg", "family", "registered", "symmetric", "enc" ], "additionalProperties": false }, "segments": { "type": "object", "description": "", "properties": { "count": { "type": "integer", "description": "Number of dot-separated segments: 3 or 5." }, "headerBytes": { "type": "integer", "description": "Decoded header length in bytes." }, "payloadBytes": { "type": [ "integer", "null" ], "description": "Decoded payload length in bytes (JWS only)." }, "signatureBytes": { "type": [ "integer", "null" ], "description": "Decoded signature length in bytes (JWS only)." } }, "required": [ "count", "headerBytes", "payloadBytes", "signatureBytes" ], "additionalProperties": false }, "claims": { "type": "object", "description": "RFC 7519 §4.1 registered claims. Null when absent or of the wrong type (a warning explains).", "properties": { "iss": { "type": [ "string", "null" ], "description": "Issuer." }, "sub": { "type": [ "string", "null" ], "description": "Subject." }, "aud": { "type": [ "array", "null" ], "items": { "type": "string", "description": "Audience." }, "description": "Audience, always as an array (a single string becomes one item)." }, "jti": { "type": [ "string", "null" ], "description": "JWT ID." }, "exp": { "type": [ "object", "null" ], "description": "A registered time claim, or null when absent or not a number.", "properties": { "value": { "type": "number", "description": "The NumericDate as given: seconds since 1970-01-01T00:00:00Z." }, "iso": { "type": [ "string", "null" ], "description": "The same instant as ISO 8601 UTC (null if out of range)." }, "secondsFromAt": { "type": "number", "description": "value minus the reference time `at`, in seconds. Negative: in the past. Positive: in the future." } }, "required": [ "value", "iso", "secondsFromAt" ], "additionalProperties": false }, "nbf": { "type": [ "object", "null" ], "description": "A registered time claim, or null when absent or not a number.", "properties": { "value": { "type": "number", "description": "The NumericDate as given: seconds since 1970-01-01T00:00:00Z." }, "iso": { "type": [ "string", "null" ], "description": "The same instant as ISO 8601 UTC (null if out of range)." }, "secondsFromAt": { "type": "number", "description": "value minus the reference time `at`, in seconds. Negative: in the past. Positive: in the future." } }, "required": [ "value", "iso", "secondsFromAt" ], "additionalProperties": false }, "iat": { "type": [ "object", "null" ], "description": "A registered time claim, or null when absent or not a number.", "properties": { "value": { "type": "number", "description": "The NumericDate as given: seconds since 1970-01-01T00:00:00Z." }, "iso": { "type": [ "string", "null" ], "description": "The same instant as ISO 8601 UTC (null if out of range)." }, "secondsFromAt": { "type": "number", "description": "value minus the reference time `at`, in seconds. Negative: in the past. Positive: in the future." } }, "required": [ "value", "iso", "secondsFromAt" ], "additionalProperties": false } }, "required": [ "iss", "sub", "aud", "jti", "exp", "nbf", "iat" ], "additionalProperties": false }, "at": { "type": "string", "description": "Reference time used for the time checks, ISO 8601 UTC.", "format": "date-time" }, "clockTolerance": { "type": "integer", "description": "Seconds of leeway applied to exp, nbf and iat." }, "status": { "type": "object", "description": "Machine-readable flags. Each true flag also has a sentence in `warnings`.", "properties": { "expired": { "type": "boolean", "description": "`exp` is at or before `at` (minus tolerance), per RFC 7519 §4.1.4." }, "notYetValid": { "type": "boolean", "description": "`nbf` is after `at` (plus tolerance)." }, "issuedInFuture": { "type": "boolean", "description": "`iat` is after `at` (plus tolerance): clock skew or forgery." }, "missingExp": { "type": "boolean", "description": "The token is a JWT but has no `exp`." }, "algNone": { "type": "boolean", "description": "`alg` is `none`: unsecured, anyone can forge it." }, "weakAlgorithm": { "type": "boolean", "description": "`alg` is `none` or names SHA-1/MD5 (e.g. `RS1`, `HS1`)." }, "unusualAlgorithm": { "type": "boolean", "description": "`alg` is unregistered (including wrong case), or rarely deployed (ES256K, Ed448, ML-DSA)." }, "symmetric": { "type": "boolean", "description": "HMAC: verification needs a shared secret, never accepted here." }, "encrypted": { "type": "boolean", "description": "The token is a JWE." }, "signatureVerified": { "type": [ "boolean", "null" ], "description": "Result of signature verification; null when no `key` was given." } }, "required": [ "expired", "notYetValid", "issuedInFuture", "missingExp", "algNone", "weakAlgorithm", "unusualAlgorithm", "symmetric", "encrypted", "signatureVerified" ], "additionalProperties": false }, "verification": { "type": "object", "description": "", "properties": { "outcome": { "type": "string", "description": "`not-requested` (no key), `valid`, `invalid-signature` (the key does not match), or `unverifiable` (see `error`).", "enum": [ "not-requested", "valid", "invalid-signature", "unverifiable" ] }, "valid": { "type": "boolean", "description": "True only when the signature verified." }, "keySource": { "description": "How `key` was read; null when no key was given.", "anyOf": [ { "type": "string", "description": "How `key` was read; null when no key was given.", "enum": [ "jwk", "jwks", "spki-pem", "x509-pem" ] }, { "type": "null" } ] }, "kid": { "type": [ "string", "null" ], "description": "kid of the JWK that was used (JWK/JWKS only)." }, "keyType": { "type": [ "string", "null" ], "description": "The key used, e.g. `EC P-256`, `RSA 2048-bit`, `Ed25519`." }, "candidates": { "type": "integer", "description": "Number of keys that were compatible and tried." }, "error": { "type": [ "string", "null" ], "description": "Why verification failed or could not run, and how to fix it." } }, "required": [ "outcome", "valid", "keySource", "kid", "keyType", "candidates", "error" ], "additionalProperties": false }, "warnings": { "type": "array", "items": { "type": "string", "description": "Plain-language finding." }, "description": "Problems and observations, most important first." } }, "required": [ "format", "header", "payload", "payloadText", "algorithm", "segments", "claims", "at", "clockTolerance", "status", "verification", "warnings" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "The decoded payload as pretty-printed JSON (`null` for a JWE)." } } } }, "400": { "description": "missing_parameter / unknown_parameter / `at` is not a date; or `key` is malformed, a URL, an unsupported format, a private key, or a symmetric secret (all refused).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The token does not have 3 or 5 segments, a segment is not base64url, or the header is not a JSON object. The message names the segment and the fix.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "jwt_decode_get", "parameters": [ { "name": "token", "in": "query", "required": true, "description": "The compact JWT (header.payload.signature, or 5 segments for JWE). A leading Bearer , surrounding quotes and embedded whitespace are removed, with a warning.", "schema": { "description": "The compact JWT (header.payload.signature, or 5 segments for JWE). A leading Bearer , surrounding quotes and embedded whitespace are removed, with a warning.", "type": "string" } }, { "name": "key", "in": "query", "required": false, "description": "Optional PUBLIC key to verify the signature: a JWK JSON object, a JWKS JSON ({\"keys\":[...]}), a PUBLIC KEY PEM, or a CERTIFICATE PEM. Private keys and symmetric (kty: oct) keys are refused. URLs are refused: fetch the JWKS yourself and pass its JSON.", "schema": { "description": "Optional PUBLIC key to verify the signature: a JWK JSON object, a JWKS JSON ({\"keys\":[...]}), a PUBLIC KEY PEM, or a CERTIFICATE PEM. Private keys and symmetric (kty: oct) keys are refused. URLs are refused: fetch the JWKS yourself and pass its JSON.", "type": "string" } }, { "name": "at", "in": "query", "required": false, "description": "Reference time for exp/nbf/iat, ISO 8601, e.g. 2026-01-01T00:30:00Z. Default: now.", "schema": { "description": "Reference time for exp/nbf/iat, ISO 8601, e.g. 2026-01-01T00:30:00Z. Default: now.", "type": "string" } }, { "name": "clock_tolerance", "in": "query", "required": false, "description": "Leeway in seconds for clock skew when evaluating exp, nbf and iat.", "schema": { "description": "Leeway in seconds for clock skew when evaluating exp, nbf and iat.", "type": "integer", "default": 0, "minimum": 0, "maximum": 86400 } }, { "name": "format", "in": "query", "required": false, "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "schema": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } } ] }, "post": { "summary": "Decode a JWT, check its claims and algorithm, and optionally verify it with a public key.", "description": "Decodes a compact JWS (RFC 7515/7519): header, payload, and the registered claims, with `exp`, `nbf` and `iat` as ISO times and seconds relative to `at`. Flags expired, not-yet-valid, `alg: none`, weak or unusual algorithms, and a missing `exp`. A compact JWE (5 segments) is recognised and its header shown, but it cannot be decrypted. With `key`, verifies the signature using a PUBLIC key only: a JWK, a JWKS (selected by the token `kid`), a `PUBLIC KEY` PEM, or a `CERTIFICATE` PEM. HS256/HS384/HS512 cannot be verified here because they need a shared secret, which this service never accepts. The server never fetches keys: pass the JWKS JSON itself, not its URL. Decoding is not verification: never trust claims from a token whose `verification.outcome` is not `valid`.\n\nPrivacy: The server receives the token and, if given, a public key. It decodes and verifies them in memory and returns the result; the input is not stored or logged (only the per-call metadata row is recorded). The server makes no network requests (it never fetches `jku`, `x5u` or JWKS URLs). Tokens are bearer credentials: a token that has not expired grants access to whoever holds it, so prefer the page (which decodes in your browser) for live production tokens, or send tokens that are expired or from test systems.", "tags": [ "jwt" ], "responses": { "200": { "description": "Success. With format=text, text/plain is returned instead of JSON.", "content": { "application/json": { "schema": { "type": "object", "description": "", "properties": { "format": { "type": "string", "description": "`JWS` (signed, 3 segments) or `JWE` (encrypted, 5 segments).", "enum": [ "JWS", "JWE" ] }, "header": { "type": "object", "description": "The decoded (protected) JOSE header, exactly as sent.", "additionalProperties": true }, "payload": { "type": [ "object", "null" ], "description": "The decoded claims set. Null for a JWE or when the payload is not a JSON object.", "additionalProperties": true }, "payloadText": { "type": [ "string", "null" ], "description": "The payload as text when it is UTF-8 but not a JSON object (a JWS that is not a JWT)." }, "algorithm": { "type": "object", "description": "", "properties": { "alg": { "type": [ "string", "null" ], "description": "The header `alg`." }, "family": { "type": "string", "description": "Algorithm family. `unknown` for JWE or unregistered values.", "enum": [ "HMAC", "RSASSA-PKCS1-v1_5", "RSASSA-PSS", "ECDSA", "EdDSA", "ML-DSA", "none", "unknown" ] }, "registered": { "type": "boolean", "description": "True when `alg` is a registered JWS algorithm known to this tool." }, "symmetric": { "type": "boolean", "description": "True for HS256/HS384/HS512 (shared-secret HMAC)." }, "enc": { "type": [ "string", "null" ], "description": "JWE content encryption (`enc`), for encrypted tokens." } }, "required": [ "alg", "family", "registered", "symmetric", "enc" ], "additionalProperties": false }, "segments": { "type": "object", "description": "", "properties": { "count": { "type": "integer", "description": "Number of dot-separated segments: 3 or 5." }, "headerBytes": { "type": "integer", "description": "Decoded header length in bytes." }, "payloadBytes": { "type": [ "integer", "null" ], "description": "Decoded payload length in bytes (JWS only)." }, "signatureBytes": { "type": [ "integer", "null" ], "description": "Decoded signature length in bytes (JWS only)." } }, "required": [ "count", "headerBytes", "payloadBytes", "signatureBytes" ], "additionalProperties": false }, "claims": { "type": "object", "description": "RFC 7519 §4.1 registered claims. Null when absent or of the wrong type (a warning explains).", "properties": { "iss": { "type": [ "string", "null" ], "description": "Issuer." }, "sub": { "type": [ "string", "null" ], "description": "Subject." }, "aud": { "type": [ "array", "null" ], "items": { "type": "string", "description": "Audience." }, "description": "Audience, always as an array (a single string becomes one item)." }, "jti": { "type": [ "string", "null" ], "description": "JWT ID." }, "exp": { "type": [ "object", "null" ], "description": "A registered time claim, or null when absent or not a number.", "properties": { "value": { "type": "number", "description": "The NumericDate as given: seconds since 1970-01-01T00:00:00Z." }, "iso": { "type": [ "string", "null" ], "description": "The same instant as ISO 8601 UTC (null if out of range)." }, "secondsFromAt": { "type": "number", "description": "value minus the reference time `at`, in seconds. Negative: in the past. Positive: in the future." } }, "required": [ "value", "iso", "secondsFromAt" ], "additionalProperties": false }, "nbf": { "type": [ "object", "null" ], "description": "A registered time claim, or null when absent or not a number.", "properties": { "value": { "type": "number", "description": "The NumericDate as given: seconds since 1970-01-01T00:00:00Z." }, "iso": { "type": [ "string", "null" ], "description": "The same instant as ISO 8601 UTC (null if out of range)." }, "secondsFromAt": { "type": "number", "description": "value minus the reference time `at`, in seconds. Negative: in the past. Positive: in the future." } }, "required": [ "value", "iso", "secondsFromAt" ], "additionalProperties": false }, "iat": { "type": [ "object", "null" ], "description": "A registered time claim, or null when absent or not a number.", "properties": { "value": { "type": "number", "description": "The NumericDate as given: seconds since 1970-01-01T00:00:00Z." }, "iso": { "type": [ "string", "null" ], "description": "The same instant as ISO 8601 UTC (null if out of range)." }, "secondsFromAt": { "type": "number", "description": "value minus the reference time `at`, in seconds. Negative: in the past. Positive: in the future." } }, "required": [ "value", "iso", "secondsFromAt" ], "additionalProperties": false } }, "required": [ "iss", "sub", "aud", "jti", "exp", "nbf", "iat" ], "additionalProperties": false }, "at": { "type": "string", "description": "Reference time used for the time checks, ISO 8601 UTC.", "format": "date-time" }, "clockTolerance": { "type": "integer", "description": "Seconds of leeway applied to exp, nbf and iat." }, "status": { "type": "object", "description": "Machine-readable flags. Each true flag also has a sentence in `warnings`.", "properties": { "expired": { "type": "boolean", "description": "`exp` is at or before `at` (minus tolerance), per RFC 7519 §4.1.4." }, "notYetValid": { "type": "boolean", "description": "`nbf` is after `at` (plus tolerance)." }, "issuedInFuture": { "type": "boolean", "description": "`iat` is after `at` (plus tolerance): clock skew or forgery." }, "missingExp": { "type": "boolean", "description": "The token is a JWT but has no `exp`." }, "algNone": { "type": "boolean", "description": "`alg` is `none`: unsecured, anyone can forge it." }, "weakAlgorithm": { "type": "boolean", "description": "`alg` is `none` or names SHA-1/MD5 (e.g. `RS1`, `HS1`)." }, "unusualAlgorithm": { "type": "boolean", "description": "`alg` is unregistered (including wrong case), or rarely deployed (ES256K, Ed448, ML-DSA)." }, "symmetric": { "type": "boolean", "description": "HMAC: verification needs a shared secret, never accepted here." }, "encrypted": { "type": "boolean", "description": "The token is a JWE." }, "signatureVerified": { "type": [ "boolean", "null" ], "description": "Result of signature verification; null when no `key` was given." } }, "required": [ "expired", "notYetValid", "issuedInFuture", "missingExp", "algNone", "weakAlgorithm", "unusualAlgorithm", "symmetric", "encrypted", "signatureVerified" ], "additionalProperties": false }, "verification": { "type": "object", "description": "", "properties": { "outcome": { "type": "string", "description": "`not-requested` (no key), `valid`, `invalid-signature` (the key does not match), or `unverifiable` (see `error`).", "enum": [ "not-requested", "valid", "invalid-signature", "unverifiable" ] }, "valid": { "type": "boolean", "description": "True only when the signature verified." }, "keySource": { "description": "How `key` was read; null when no key was given.", "anyOf": [ { "type": "string", "description": "How `key` was read; null when no key was given.", "enum": [ "jwk", "jwks", "spki-pem", "x509-pem" ] }, { "type": "null" } ] }, "kid": { "type": [ "string", "null" ], "description": "kid of the JWK that was used (JWK/JWKS only)." }, "keyType": { "type": [ "string", "null" ], "description": "The key used, e.g. `EC P-256`, `RSA 2048-bit`, `Ed25519`." }, "candidates": { "type": "integer", "description": "Number of keys that were compatible and tried." }, "error": { "type": [ "string", "null" ], "description": "Why verification failed or could not run, and how to fix it." } }, "required": [ "outcome", "valid", "keySource", "kid", "keyType", "candidates", "error" ], "additionalProperties": false }, "warnings": { "type": "array", "items": { "type": "string", "description": "Plain-language finding." }, "description": "Problems and observations, most important first." } }, "required": [ "format", "header", "payload", "payloadText", "algorithm", "segments", "claims", "at", "clockTolerance", "status", "verification", "warnings" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "The decoded payload as pretty-printed JSON (`null` for a JWE)." } } } }, "400": { "description": "missing_parameter / unknown_parameter / `at` is not a date; or `key` is malformed, a URL, an unsupported format, a private key, or a symmetric secret (all refused).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The token does not have 3 or 5 segments, a segment is not base64url, or the header is not a JSON object. The message names the segment and the fix.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "jwt_decode", "parameters": [ { "name": "format", "in": "query", "required": false, "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "schema": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "description": "The compact JWT (header.payload.signature, or 5 segments for JWE). A leading Bearer , surrounding quotes and embedded whitespace are removed, with a warning.", "type": "string" }, "key": { "description": "Optional PUBLIC key to verify the signature: a JWK JSON object, a JWKS JSON ({\"keys\":[...]}), a PUBLIC KEY PEM, or a CERTIFICATE PEM. Private keys and symmetric (kty: oct) keys are refused. URLs are refused: fetch the JWKS yourself and pass its JSON.", "type": "string" }, "at": { "description": "Reference time for exp/nbf/iat, ISO 8601, e.g. 2026-01-01T00:30:00Z. Default: now.", "type": "string" }, "clock_tolerance": { "description": "Leeway in seconds for clock skew when evaluating exp, nbf and iat.", "type": "integer", "default": 0, "minimum": 0, "maximum": 86400 }, "format": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } }, "required": [ "token" ], "additionalProperties": false } } } } } }, "/api/url/parse": { "get": { "summary": "Split a URL into its parts with the WHATWG URL parser browsers use.", "description": "Parses a URL exactly as browsers and Cloudflare Workers do (WHATWG URL Standard) and returns every component: scheme, username, host in ASCII and Unicode forms, port and default port, origin, path segments decoded, query parameters as an ordered list (duplicates kept), and fragment. It classifies the host (domain, IPv4, IPv6, localhost, private or other special-purpose range) without resolving DNS. A password, if present, is never returned: `hasPassword` is true and `href` shows `***` instead. With `base`, a relative reference is resolved first.\n\nPrivacy: The server receives the URL (and base), parses it in memory, and returns its parts. Your input is not stored or logged; only the per-call metadata row (operation, time, status, sizes) is recorded. Passwords in the URL are never echoed back: they are replaced by `***`. The server does not resolve the host or contact it.", "tags": [ "url-parse" ], "responses": { "200": { "description": "Success. With format=text, text/plain is returned instead of JSON.", "content": { "application/json": { "schema": { "type": "object", "description": "", "properties": { "href": { "type": "string", "description": "The normalized URL (WHATWG serialization). If the input had a password, it is replaced by `***`." }, "hrefRedacted": { "type": "boolean", "description": "True when `href` had its password replaced." }, "resolvedAgainstBase": { "type": "boolean", "description": "True when the input was relative and was resolved against `base`." }, "protocol": { "type": "string", "description": "Scheme with the colon, e.g. `https:`." }, "scheme": { "type": "string", "description": "Scheme without the colon, lowercase." }, "special": { "type": "boolean", "description": "A WHATWG special scheme (http, https, ws, wss, ftp, file)." }, "username": { "type": "object", "description": "", "properties": { "raw": { "type": "string", "description": "As serialized in the normalized URL (percent-encoded)." }, "decoded": { "type": [ "string", "null" ], "description": "Percent-decoded as UTF-8; null if an escape is not valid UTF-8." } }, "required": [ "raw", "decoded" ], "additionalProperties": false }, "hasPassword": { "type": "boolean", "description": "True when the URL contains a password. The password is never returned." }, "host": { "type": "string", "description": "Host plus `:port` when a non-default port is present (ASCII)." }, "hostname": { "type": "string", "description": "Host without port, ASCII (Punycode) form. IPv6 includes brackets." }, "hostnameUnicode": { "type": "string", "description": "Host with xn-- labels decoded to Unicode (equal to hostname otherwise)." }, "hostType": { "type": "string", "description": "`domain`, `ipv4`, `ipv6`, `opaque` (host of a non-special scheme), `empty` (e.g. file:///), or `none` (no authority, e.g. mailto:).", "enum": [ "domain", "ipv4", "ipv6", "opaque", "empty", "none" ] }, "idn": { "type": "boolean", "description": "True when any host label is an xn-- (internationalized) label." }, "ip": { "type": [ "object", "null" ], "description": "", "properties": { "version": { "type": "integer", "description": "4 or 6.", "enum": [ 4, 6 ] }, "address": { "type": "string", "description": "Address as normalized by the URL parser (no brackets)." }, "expanded": { "type": "string", "description": "IPv6: all eight 4-digit groups. IPv4: dotted decimal." }, "range": { "type": "string", "description": "Special-purpose range (IANA registries), or `public`.", "enum": [ "public", "private", "loopback", "link-local", "unspecified", "shared", "multicast", "broadcast", "documentation", "benchmarking", "reserved", "unique-local", "ipv4-mapped", "nat64", "site-local" ] }, "mappedIpv4": { "type": [ "string", "null" ], "description": "Embedded IPv4 address for ::ffff:0:0/96 and 64:ff9b::/96." } }, "required": [ "version", "address", "expanded", "range", "mappedIpv4" ], "additionalProperties": false }, "isLocalhost": { "type": "boolean", "description": "`localhost`, `*.localhost` (RFC 6761), or a loopback IP." }, "isPrivate": { "type": "boolean", "description": "IP in RFC 1918, RFC 6598 shared (100.64/10), fc00::/7 or fec0::/10 (including IPv4-mapped forms)." }, "isPublic": { "type": [ "boolean", "null" ], "description": "True for a global unicast IP; false for any special-purpose IP or localhost; null for a domain name (it is not resolved)." }, "port": { "type": [ "integer", "null" ], "description": "Explicit non-default port, or null." }, "defaultPort": { "type": [ "integer", "null" ], "description": "Default port of the scheme (http 80, https 443, ws 80, wss 443, ftp 21)." }, "effectivePort": { "type": [ "integer", "null" ], "description": "port ?? defaultPort: the port a client would connect to." }, "origin": { "type": [ "string", "null" ], "description": "scheme://host[:port]; null for opaque origins (file:, data:, mailto:, …)." }, "pathname": { "type": "string", "description": "Path as serialized (percent-encoded)." }, "opaquePath": { "type": "boolean", "description": "True for URLs like `mailto:a@b` whose path is not a /-separated list." }, "pathSegments": { "type": "array", "items": { "type": "object", "description": "", "properties": { "raw": { "type": "string", "description": "As serialized in the normalized URL (percent-encoded)." }, "decoded": { "type": [ "string", "null" ], "description": "Percent-decoded as UTF-8; null if an escape is not valid UTF-8." } }, "required": [ "raw", "decoded" ], "additionalProperties": false }, "description": "Path segments split on `/`; empty for opaque paths." }, "search": { "type": "string", "description": "Query string including `?`, or empty." }, "query": { "type": "array", "items": { "type": "object", "description": "", "properties": { "name": { "type": "string", "description": "Decoded name (application/x-www-form-urlencoded: `+` is a space)." }, "value": { "type": "string", "description": "Decoded value; empty string when there is no `=`." }, "rawName": { "type": "string", "description": "Name as it appears in the URL." }, "rawValue": { "type": [ "string", "null" ], "description": "Value as it appears in the URL; null when there is no `=`." } }, "required": [ "name", "value", "rawName", "rawValue" ], "additionalProperties": false }, "description": "Query parameters in order. Duplicate names are kept as separate entries." }, "hash": { "type": "string", "description": "Fragment including `#`, or empty." }, "fragment": { "type": [ "object", "null" ], "description": "", "properties": { "raw": { "type": "string", "description": "As serialized in the normalized URL (percent-encoded)." }, "decoded": { "type": [ "string", "null" ], "description": "Percent-decoded as UTF-8; null if an escape is not valid UTF-8." } }, "required": [ "raw", "decoded" ], "additionalProperties": false }, "warnings": { "type": "array", "items": { "type": "string", "description": "Plain-language finding." }, "description": "Normalizations applied and risks found." } }, "required": [ "href", "hrefRedacted", "resolvedAgainstBase", "protocol", "scheme", "special", "username", "hasPassword", "host", "hostname", "hostnameUnicode", "hostType", "idn", "ip", "isLocalhost", "isPrivate", "isPublic", "port", "defaultPort", "effectivePort", "origin", "pathname", "opaquePath", "pathSegments", "search", "query", "hash", "fragment", "warnings" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "The normalized `href` (password redacted)." } } } }, "400": { "description": "missing_parameter / unknown_parameter / invalid_parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`input` is not a valid URL (the message suggests the likely cause: no scheme, bad host character, bad port), or `base` is not a valid absolute URL.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "url_parse_get", "parameters": [ { "name": "input", "in": "query", "required": true, "description": "The URL, absolute (https://…), or relative (../a?b=1) when base is given.", "schema": { "description": "The URL, absolute (https://…), or relative (../a?b=1) when base is given.", "type": "string" } }, { "name": "base", "in": "query", "required": false, "description": "Absolute base URL for resolving a relative input (RFC 3986 §5 as refined by WHATWG). Ignored when input is absolute.", "schema": { "description": "Absolute base URL for resolving a relative input (RFC 3986 §5 as refined by WHATWG). Ignored when input is absolute.", "type": "string" } }, { "name": "format", "in": "query", "required": false, "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "schema": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } } ] }, "post": { "summary": "Split a URL into its parts with the WHATWG URL parser browsers use.", "description": "Parses a URL exactly as browsers and Cloudflare Workers do (WHATWG URL Standard) and returns every component: scheme, username, host in ASCII and Unicode forms, port and default port, origin, path segments decoded, query parameters as an ordered list (duplicates kept), and fragment. It classifies the host (domain, IPv4, IPv6, localhost, private or other special-purpose range) without resolving DNS. A password, if present, is never returned: `hasPassword` is true and `href` shows `***` instead. With `base`, a relative reference is resolved first.\n\nPrivacy: The server receives the URL (and base), parses it in memory, and returns its parts. Your input is not stored or logged; only the per-call metadata row (operation, time, status, sizes) is recorded. Passwords in the URL are never echoed back: they are replaced by `***`. The server does not resolve the host or contact it.", "tags": [ "url-parse" ], "responses": { "200": { "description": "Success. With format=text, text/plain is returned instead of JSON.", "content": { "application/json": { "schema": { "type": "object", "description": "", "properties": { "href": { "type": "string", "description": "The normalized URL (WHATWG serialization). If the input had a password, it is replaced by `***`." }, "hrefRedacted": { "type": "boolean", "description": "True when `href` had its password replaced." }, "resolvedAgainstBase": { "type": "boolean", "description": "True when the input was relative and was resolved against `base`." }, "protocol": { "type": "string", "description": "Scheme with the colon, e.g. `https:`." }, "scheme": { "type": "string", "description": "Scheme without the colon, lowercase." }, "special": { "type": "boolean", "description": "A WHATWG special scheme (http, https, ws, wss, ftp, file)." }, "username": { "type": "object", "description": "", "properties": { "raw": { "type": "string", "description": "As serialized in the normalized URL (percent-encoded)." }, "decoded": { "type": [ "string", "null" ], "description": "Percent-decoded as UTF-8; null if an escape is not valid UTF-8." } }, "required": [ "raw", "decoded" ], "additionalProperties": false }, "hasPassword": { "type": "boolean", "description": "True when the URL contains a password. The password is never returned." }, "host": { "type": "string", "description": "Host plus `:port` when a non-default port is present (ASCII)." }, "hostname": { "type": "string", "description": "Host without port, ASCII (Punycode) form. IPv6 includes brackets." }, "hostnameUnicode": { "type": "string", "description": "Host with xn-- labels decoded to Unicode (equal to hostname otherwise)." }, "hostType": { "type": "string", "description": "`domain`, `ipv4`, `ipv6`, `opaque` (host of a non-special scheme), `empty` (e.g. file:///), or `none` (no authority, e.g. mailto:).", "enum": [ "domain", "ipv4", "ipv6", "opaque", "empty", "none" ] }, "idn": { "type": "boolean", "description": "True when any host label is an xn-- (internationalized) label." }, "ip": { "type": [ "object", "null" ], "description": "", "properties": { "version": { "type": "integer", "description": "4 or 6.", "enum": [ 4, 6 ] }, "address": { "type": "string", "description": "Address as normalized by the URL parser (no brackets)." }, "expanded": { "type": "string", "description": "IPv6: all eight 4-digit groups. IPv4: dotted decimal." }, "range": { "type": "string", "description": "Special-purpose range (IANA registries), or `public`.", "enum": [ "public", "private", "loopback", "link-local", "unspecified", "shared", "multicast", "broadcast", "documentation", "benchmarking", "reserved", "unique-local", "ipv4-mapped", "nat64", "site-local" ] }, "mappedIpv4": { "type": [ "string", "null" ], "description": "Embedded IPv4 address for ::ffff:0:0/96 and 64:ff9b::/96." } }, "required": [ "version", "address", "expanded", "range", "mappedIpv4" ], "additionalProperties": false }, "isLocalhost": { "type": "boolean", "description": "`localhost`, `*.localhost` (RFC 6761), or a loopback IP." }, "isPrivate": { "type": "boolean", "description": "IP in RFC 1918, RFC 6598 shared (100.64/10), fc00::/7 or fec0::/10 (including IPv4-mapped forms)." }, "isPublic": { "type": [ "boolean", "null" ], "description": "True for a global unicast IP; false for any special-purpose IP or localhost; null for a domain name (it is not resolved)." }, "port": { "type": [ "integer", "null" ], "description": "Explicit non-default port, or null." }, "defaultPort": { "type": [ "integer", "null" ], "description": "Default port of the scheme (http 80, https 443, ws 80, wss 443, ftp 21)." }, "effectivePort": { "type": [ "integer", "null" ], "description": "port ?? defaultPort: the port a client would connect to." }, "origin": { "type": [ "string", "null" ], "description": "scheme://host[:port]; null for opaque origins (file:, data:, mailto:, …)." }, "pathname": { "type": "string", "description": "Path as serialized (percent-encoded)." }, "opaquePath": { "type": "boolean", "description": "True for URLs like `mailto:a@b` whose path is not a /-separated list." }, "pathSegments": { "type": "array", "items": { "type": "object", "description": "", "properties": { "raw": { "type": "string", "description": "As serialized in the normalized URL (percent-encoded)." }, "decoded": { "type": [ "string", "null" ], "description": "Percent-decoded as UTF-8; null if an escape is not valid UTF-8." } }, "required": [ "raw", "decoded" ], "additionalProperties": false }, "description": "Path segments split on `/`; empty for opaque paths." }, "search": { "type": "string", "description": "Query string including `?`, or empty." }, "query": { "type": "array", "items": { "type": "object", "description": "", "properties": { "name": { "type": "string", "description": "Decoded name (application/x-www-form-urlencoded: `+` is a space)." }, "value": { "type": "string", "description": "Decoded value; empty string when there is no `=`." }, "rawName": { "type": "string", "description": "Name as it appears in the URL." }, "rawValue": { "type": [ "string", "null" ], "description": "Value as it appears in the URL; null when there is no `=`." } }, "required": [ "name", "value", "rawName", "rawValue" ], "additionalProperties": false }, "description": "Query parameters in order. Duplicate names are kept as separate entries." }, "hash": { "type": "string", "description": "Fragment including `#`, or empty." }, "fragment": { "type": [ "object", "null" ], "description": "", "properties": { "raw": { "type": "string", "description": "As serialized in the normalized URL (percent-encoded)." }, "decoded": { "type": [ "string", "null" ], "description": "Percent-decoded as UTF-8; null if an escape is not valid UTF-8." } }, "required": [ "raw", "decoded" ], "additionalProperties": false }, "warnings": { "type": "array", "items": { "type": "string", "description": "Plain-language finding." }, "description": "Normalizations applied and risks found." } }, "required": [ "href", "hrefRedacted", "resolvedAgainstBase", "protocol", "scheme", "special", "username", "hasPassword", "host", "hostname", "hostnameUnicode", "hostType", "idn", "ip", "isLocalhost", "isPrivate", "isPublic", "port", "defaultPort", "effectivePort", "origin", "pathname", "opaquePath", "pathSegments", "search", "query", "hash", "fragment", "warnings" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "The normalized `href` (password redacted)." } } } }, "400": { "description": "missing_parameter / unknown_parameter / invalid_parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`input` is not a valid URL (the message suggests the likely cause: no scheme, bad host character, bad port), or `base` is not a valid absolute URL.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "url_parse", "parameters": [ { "name": "format", "in": "query", "required": false, "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "schema": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "input": { "description": "The URL, absolute (https://…), or relative (../a?b=1) when base is given.", "type": "string" }, "base": { "description": "Absolute base URL for resolving a relative input (RFC 3986 §5 as refined by WHATWG). Ignored when input is absolute.", "type": "string" }, "format": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } }, "required": [ "input" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "The body is used as the `input` parameter." } } } } } }, "/api/uuid/generate": { "get": { "summary": "Generate random (v4) or time-ordered (v7) UUIDs, up to 1000 at a time.", "description": "Generates RFC 9562 UUIDs. Version 4: 122 random bits from `crypto.randomUUID()`. Version 7: a 48-bit Unix millisecond timestamp, then a 42-bit counter (randomly seeded each millisecond, incremented within it) and 32 fresh random bits, so every batch is strictly increasing in both byte and string order. UUIDs are identifiers, not secrets: do not use them as passwords, API keys, session tokens or capability URLs, even though v4 uses a CSPRNG.\n\nPrivacy: The server receives only the options (version, count, format), generates the UUIDs in memory with the Web Crypto CSPRNG, and returns them. Your input is not stored or logged; only the per-call metadata row (operation, time, status, sizes) is recorded. UUIDs are identifiers, not secrets: never use one as a password, token or key.", "tags": [ "uuid" ], "responses": { "200": { "description": "Success. With format=text, text/plain is returned instead of JSON.", "content": { "application/json": { "schema": { "type": "object", "description": "", "properties": { "version": { "type": "integer", "description": "UUID version generated.", "enum": [ 4, 7 ] }, "format": { "type": "string", "description": "Output format.", "enum": [ "canonical", "uppercase", "no-hyphens", "braces", "urn" ] }, "count": { "type": "integer", "description": "Number of UUIDs." }, "uuids": { "type": "array", "items": { "type": "string", "description": "A UUID in the requested format." }, "description": "The UUIDs, in generation order (for v7, also ascending order)." } }, "required": [ "version", "format", "count", "uuids" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "One UUID per line." } } } }, "400": { "description": "missing_parameter / unknown_parameter / `version` is not 4 or 7, `count` is outside 1–1000, or `format` is unknown.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "uuid_generate_get", "parameters": [ { "name": "version", "in": "query", "required": false, "description": "4 (random) or 7 (time-ordered; sorts by creation time, good for database keys).", "schema": { "description": "4 (random) or 7 (time-ordered; sorts by creation time, good for database keys).", "type": "string", "enum": [ "4", "7" ], "default": "4" } }, { "name": "count", "in": "query", "required": false, "description": "How many UUIDs to return, 1 to 1000.", "schema": { "description": "How many UUIDs to return, 1 to 1000.", "type": "integer", "default": 1, "minimum": 1, "maximum": 1000 } }, { "name": "format", "in": "query", "required": false, "description": "canonical (lowercase 8-4-4-4-12), uppercase, no-hyphens (32 hex), braces ({…}), or urn (urn:uuid:…).", "schema": { "description": "canonical (lowercase 8-4-4-4-12), uppercase, no-hyphens (32 hex), braces ({…}), or urn (urn:uuid:…).", "type": "string", "enum": [ "canonical", "uppercase", "no-hyphens", "braces", "urn" ], "default": "canonical" } }, { "name": "format", "in": "query", "required": false, "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "schema": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } } ] }, "post": { "summary": "Generate random (v4) or time-ordered (v7) UUIDs, up to 1000 at a time.", "description": "Generates RFC 9562 UUIDs. Version 4: 122 random bits from `crypto.randomUUID()`. Version 7: a 48-bit Unix millisecond timestamp, then a 42-bit counter (randomly seeded each millisecond, incremented within it) and 32 fresh random bits, so every batch is strictly increasing in both byte and string order. UUIDs are identifiers, not secrets: do not use them as passwords, API keys, session tokens or capability URLs, even though v4 uses a CSPRNG.\n\nPrivacy: The server receives only the options (version, count, format), generates the UUIDs in memory with the Web Crypto CSPRNG, and returns them. Your input is not stored or logged; only the per-call metadata row (operation, time, status, sizes) is recorded. UUIDs are identifiers, not secrets: never use one as a password, token or key.", "tags": [ "uuid" ], "responses": { "200": { "description": "Success. With format=text, text/plain is returned instead of JSON.", "content": { "application/json": { "schema": { "type": "object", "description": "", "properties": { "version": { "type": "integer", "description": "UUID version generated.", "enum": [ 4, 7 ] }, "format": { "type": "string", "description": "Output format.", "enum": [ "canonical", "uppercase", "no-hyphens", "braces", "urn" ] }, "count": { "type": "integer", "description": "Number of UUIDs." }, "uuids": { "type": "array", "items": { "type": "string", "description": "A UUID in the requested format." }, "description": "The UUIDs, in generation order (for v7, also ascending order)." } }, "required": [ "version", "format", "count", "uuids" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "One UUID per line." } } } }, "400": { "description": "missing_parameter / unknown_parameter / `version` is not 4 or 7, `count` is outside 1–1000, or `format` is unknown.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "uuid_generate", "parameters": [ { "name": "format", "in": "query", "required": false, "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "schema": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "description": "4 (random) or 7 (time-ordered; sorts by creation time, good for database keys).", "type": "string", "enum": [ "4", "7" ], "default": "4" }, "count": { "description": "How many UUIDs to return, 1 to 1000.", "type": "integer", "default": 1, "minimum": 1, "maximum": 1000 }, "format": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } }, "required": [], "additionalProperties": false } } } } } }, "/api/uuid/inspect": { "get": { "summary": "Read a UUID’s version, variant and embedded timestamp, clock sequence and node.", "description": "Parses a UUID written as 8-4-4-4-12 hex, 32 hex digits, `{…}` or `urn:uuid:…` (any case) and reports its RFC 9562 variant and version, whether it is the Nil or Max UUID, and the fields its version defines: the timestamp of v1, v6 and v7 as ISO 8601 (v1/v6 to 100 ns), and the clock sequence and node of v1 and v6. It also returns the UUID in every common format.\n\nPrivacy: The server receives the UUID, decodes its fields in memory, and returns them. Your input is not stored or logged; only the per-call metadata row (operation, time, status, sizes) is recorded. Note that a v1 UUID may embed the MAC address of the machine that generated it.", "tags": [ "uuid" ], "responses": { "200": { "description": "Success. With format=text, text/plain is returned instead of JSON.", "content": { "application/json": { "schema": { "type": "object", "description": "", "properties": { "input": { "type": "object", "description": "", "properties": { "format": { "type": "string", "description": "Form the input was written in.", "enum": [ "canonical", "uppercase", "no-hyphens", "braces", "urn", "mixed-case" ] }, "normalized": { "type": "boolean", "description": "True when the input differs from the canonical form." } }, "required": [ "format", "normalized" ], "additionalProperties": false }, "canonical": { "type": "string", "description": "Lowercase 8-4-4-4-12 form (RFC 9562 §4)." }, "hex": { "type": "string", "description": "32 lowercase hex digits." }, "formats": { "type": "object", "description": "", "properties": { "canonical": { "type": "string", "description": "8-4-4-4-12 lowercase." }, "uppercase": { "type": "string", "description": "8-4-4-4-12 uppercase." }, "noHyphens": { "type": "string", "description": "32 hex digits." }, "braces": { "type": "string", "description": "{8-4-4-4-12} (Microsoft GUID style)." }, "urn": { "type": "string", "description": "urn:uuid:8-4-4-4-12 (RFC 9562 §4)." } }, "required": [ "canonical", "uppercase", "noHyphens", "braces", "urn" ], "additionalProperties": false }, "special": { "description": "`nil` (all zeros), `max` (all ones), or null.", "anyOf": [ { "type": "string", "description": "`nil` (all zeros), `max` (all ones), or null.", "enum": [ "nil", "max" ] }, { "type": "null" } ] }, "variant": { "type": "string", "description": "Variant from the top bits of octet 8 (RFC 9562 §4.1).", "enum": [ "NCS", "RFC 9562", "Microsoft", "Reserved (future)" ] }, "variantBits": { "type": "string", "description": "The variant bits: `0`, `10`, `110` or `111`." }, "version": { "type": [ "integer", "null" ], "description": "Version (top 4 bits of octet 6), only for the RFC 9562 variant and not nil/max." }, "versionName": { "type": [ "string", "null" ], "description": "e.g. `Unix Epoch time-based` for 7." }, "timestamp": { "type": [ "object", "null" ], "description": "", "properties": { "iso": { "type": "string", "description": "ISO 8601 UTC, millisecond precision." }, "isoExact": { "type": "string", "description": "ISO 8601 UTC at the native precision (7 fractional digits for v1/v6)." }, "unixMs": { "type": "integer", "description": "Milliseconds since 1970-01-01T00:00:00Z (floored for v1/v6)." }, "precision": { "type": "string", "description": "Native precision.", "enum": [ "100ns", "1ms" ] }, "gregorian100ns": { "type": [ "string", "null" ], "description": "v1/v6: 100 ns intervals since 1582-10-15T00:00:00Z, as a decimal string." } }, "required": [ "iso", "isoExact", "unixMs", "precision", "gregorian100ns" ], "additionalProperties": false }, "clockSequence": { "type": [ "integer", "null" ], "description": "v1/v6: 14-bit clock sequence." }, "node": { "type": [ "string", "null" ], "description": "v1/v6: 48-bit node as colon-separated uppercase hex." }, "nodeIsRandom": { "type": [ "boolean", "null" ], "description": "v1/v6: the multicast bit is set, marking a random node rather than a MAC address." }, "notes": { "type": "array", "items": { "type": "string", "description": "Plain-language note." }, "description": "What the version encodes and any anomalies." } }, "required": [ "input", "canonical", "hex", "formats", "special", "variant", "variantBits", "version", "versionName", "timestamp", "clockSequence", "node", "nodeIsRandom", "notes" ], "additionalProperties": false } } } }, "400": { "description": "missing_parameter / unknown_parameter / invalid_parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The input is not a UUID. The message gives the bad character or the digit count found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "uuid_inspect_get", "parameters": [ { "name": "input", "in": "query", "required": true, "description": "One UUID in any accepted form, e.g. 017f22e2-79b0-7cc3-98c4-dc0c0c07398f.", "schema": { "description": "One UUID in any accepted form, e.g. 017f22e2-79b0-7cc3-98c4-dc0c0c07398f.", "type": "string" } }, { "name": "format", "in": "query", "required": false, "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "schema": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } } ] }, "post": { "summary": "Read a UUID’s version, variant and embedded timestamp, clock sequence and node.", "description": "Parses a UUID written as 8-4-4-4-12 hex, 32 hex digits, `{…}` or `urn:uuid:…` (any case) and reports its RFC 9562 variant and version, whether it is the Nil or Max UUID, and the fields its version defines: the timestamp of v1, v6 and v7 as ISO 8601 (v1/v6 to 100 ns), and the clock sequence and node of v1 and v6. It also returns the UUID in every common format.\n\nPrivacy: The server receives the UUID, decodes its fields in memory, and returns them. Your input is not stored or logged; only the per-call metadata row (operation, time, status, sizes) is recorded. Note that a v1 UUID may embed the MAC address of the machine that generated it.", "tags": [ "uuid" ], "responses": { "200": { "description": "Success. With format=text, text/plain is returned instead of JSON.", "content": { "application/json": { "schema": { "type": "object", "description": "", "properties": { "input": { "type": "object", "description": "", "properties": { "format": { "type": "string", "description": "Form the input was written in.", "enum": [ "canonical", "uppercase", "no-hyphens", "braces", "urn", "mixed-case" ] }, "normalized": { "type": "boolean", "description": "True when the input differs from the canonical form." } }, "required": [ "format", "normalized" ], "additionalProperties": false }, "canonical": { "type": "string", "description": "Lowercase 8-4-4-4-12 form (RFC 9562 §4)." }, "hex": { "type": "string", "description": "32 lowercase hex digits." }, "formats": { "type": "object", "description": "", "properties": { "canonical": { "type": "string", "description": "8-4-4-4-12 lowercase." }, "uppercase": { "type": "string", "description": "8-4-4-4-12 uppercase." }, "noHyphens": { "type": "string", "description": "32 hex digits." }, "braces": { "type": "string", "description": "{8-4-4-4-12} (Microsoft GUID style)." }, "urn": { "type": "string", "description": "urn:uuid:8-4-4-4-12 (RFC 9562 §4)." } }, "required": [ "canonical", "uppercase", "noHyphens", "braces", "urn" ], "additionalProperties": false }, "special": { "description": "`nil` (all zeros), `max` (all ones), or null.", "anyOf": [ { "type": "string", "description": "`nil` (all zeros), `max` (all ones), or null.", "enum": [ "nil", "max" ] }, { "type": "null" } ] }, "variant": { "type": "string", "description": "Variant from the top bits of octet 8 (RFC 9562 §4.1).", "enum": [ "NCS", "RFC 9562", "Microsoft", "Reserved (future)" ] }, "variantBits": { "type": "string", "description": "The variant bits: `0`, `10`, `110` or `111`." }, "version": { "type": [ "integer", "null" ], "description": "Version (top 4 bits of octet 6), only for the RFC 9562 variant and not nil/max." }, "versionName": { "type": [ "string", "null" ], "description": "e.g. `Unix Epoch time-based` for 7." }, "timestamp": { "type": [ "object", "null" ], "description": "", "properties": { "iso": { "type": "string", "description": "ISO 8601 UTC, millisecond precision." }, "isoExact": { "type": "string", "description": "ISO 8601 UTC at the native precision (7 fractional digits for v1/v6)." }, "unixMs": { "type": "integer", "description": "Milliseconds since 1970-01-01T00:00:00Z (floored for v1/v6)." }, "precision": { "type": "string", "description": "Native precision.", "enum": [ "100ns", "1ms" ] }, "gregorian100ns": { "type": [ "string", "null" ], "description": "v1/v6: 100 ns intervals since 1582-10-15T00:00:00Z, as a decimal string." } }, "required": [ "iso", "isoExact", "unixMs", "precision", "gregorian100ns" ], "additionalProperties": false }, "clockSequence": { "type": [ "integer", "null" ], "description": "v1/v6: 14-bit clock sequence." }, "node": { "type": [ "string", "null" ], "description": "v1/v6: 48-bit node as colon-separated uppercase hex." }, "nodeIsRandom": { "type": [ "boolean", "null" ], "description": "v1/v6: the multicast bit is set, marking a random node rather than a MAC address." }, "notes": { "type": "array", "items": { "type": "string", "description": "Plain-language note." }, "description": "What the version encodes and any anomalies." } }, "required": [ "input", "canonical", "hex", "formats", "special", "variant", "variantBits", "version", "versionName", "timestamp", "clockSequence", "node", "nodeIsRandom", "notes" ], "additionalProperties": false } } } }, "400": { "description": "missing_parameter / unknown_parameter / invalid_parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The input is not a UUID. The message gives the bad character or the digit count found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "uuid_inspect", "parameters": [ { "name": "format", "in": "query", "required": false, "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "schema": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "input": { "description": "One UUID in any accepted form, e.g. 017f22e2-79b0-7cc3-98c4-dc0c0c07398f.", "type": "string" }, "format": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } }, "required": [ "input" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "The body is used as the `input` parameter." } } } } } }, "/api/text/inspect": { "get": { "summary": "Exact counts of characters, bytes, words and lines; find substrings; reveal invisible characters.", "description": "Counts text the ways software disagrees about: grapheme clusters (what people see as characters), code points, UTF-16 code units (JavaScript length) and UTF-8 bytes; lines with their line-ending style; words and sentences (Intl.Segmenter); and letters, digits, whitespace and punctuation by Unicode property. With `find`, counts occurrences of a substring or character and returns each position (e.g. `find=r` in `strawberry` is 3). It also reports invisible and deceptive characters with positions: zero-width characters, bidirectional controls (Trojan Source, CVE-2021-42574), unusual spaces such as NBSP, BOM, control characters, Unicode tag characters (hidden-prompt smuggling), and Latin look-alikes in mixed-script words. Use this instead of counting characters yourself.\n\nPrivacy: The server receives the text (and the search string), analyses it in memory, and returns counts and positions. Your input is not stored or logged; only the per-call metadata row (operation, time, status, sizes) is recorded. For private text use the page, which does the same analysis in your browser.", "tags": [ "text" ], "responses": { "200": { "description": "Success. With format=text, text/plain is returned instead of JSON.", "content": { "application/json": { "schema": { "type": "object", "description": "", "properties": { "locale": { "type": "string", "description": "Locale used by Intl.Segmenter after resolution." }, "counts": { "type": "object", "description": "", "properties": { "graphemes": { "type": "integer", "description": "Extended grapheme clusters (UAX #29): what a person counts as characters." }, "codePoints": { "type": "integer", "description": "Unicode code points (a lone surrogate counts as one)." }, "utf16CodeUnits": { "type": "integer", "description": "UTF-16 code units: JavaScript `length`, Java `length()`." }, "utf8Bytes": { "type": "integer", "description": "Bytes when encoded as UTF-8 (lone surrogates as U+FFFD, 3 bytes)." }, "words": { "type": "integer", "description": "Word segments with isWordLike (letters/numbers/ideographs; not punctuation or spaces)." }, "sentences": { "type": "integer", "description": "Sentence segments containing a non-whitespace character." }, "lines": { "type": "integer", "description": "Lines: 0 for empty text; a final line break does not start a new line." }, "lineBreaks": { "type": "integer", "description": "LF + CRLF + CR line breaks (CRLF counts once)." }, "nonEmptyLines": { "type": "integer", "description": "Lines with at least one character." } }, "required": [ "graphemes", "codePoints", "utf16CodeUnits", "utf8Bytes", "words", "sentences", "lines", "lineBreaks", "nonEmptyLines" ], "additionalProperties": false }, "lineEndings": { "type": "object", "description": "", "properties": { "style": { "type": "string", "description": "`none`, `LF`, `CRLF`, `CR`, or `mixed`.", "enum": [ "none", "LF", "CRLF", "CR", "mixed" ] }, "lf": { "type": "integer", "description": "Bare LF count." }, "crlf": { "type": "integer", "description": "CRLF count." }, "cr": { "type": "integer", "description": "Bare CR count." }, "endsWithLineBreak": { "type": "boolean", "description": "The text ends with LF, CRLF or CR." } }, "required": [ "style", "lf", "crlf", "cr", "endsWithLineBreak" ], "additionalProperties": false }, "characterClasses": { "type": "object", "description": "Counts of code points by Unicode property (emoji counts grapheme clusters).", "properties": { "letters": { "type": "integer", "description": "\\p{L}" }, "uppercase": { "type": "integer", "description": "\\p{Lu}" }, "lowercase": { "type": "integer", "description": "\\p{Ll}" }, "marks": { "type": "integer", "description": "\\p{M} (combining marks, including variation selectors)" }, "digits": { "type": "integer", "description": "\\p{Nd} (decimal digits in any script)" }, "numbers": { "type": "integer", "description": "\\p{N} (digits plus letter-like and other numerals)" }, "punctuation": { "type": "integer", "description": "\\p{P}" }, "symbols": { "type": "integer", "description": "\\p{S}" }, "whitespace": { "type": "integer", "description": "\\p{White_Space} (includes line breaks and tabs)" }, "spaces": { "type": "integer", "description": "\\p{Zs} (space separators, including NBSP)" }, "control": { "type": "integer", "description": "\\p{Cc} (includes tab, LF, CR)" }, "format": { "type": "integer", "description": "\\p{Cf} (invisible format characters)" }, "emoji": { "type": "integer", "description": "Grapheme clusters containing an \\p{Extended_Pictographic} character." } }, "required": [ "letters", "uppercase", "lowercase", "marks", "digits", "numbers", "punctuation", "symbols", "whitespace", "spaces", "control", "format", "emoji" ], "additionalProperties": false }, "normalization": { "type": "object", "description": "", "properties": { "isNFC": { "type": "boolean", "description": "The text is unchanged by NFC normalization." }, "isNFD": { "type": "boolean", "description": "The text is unchanged by NFD normalization." }, "isNFKC": { "type": "boolean", "description": "The text is unchanged by NFKC normalization." } }, "required": [ "isNFC", "isNFD", "isNFKC" ], "additionalProperties": false }, "occurrences": { "type": [ "object", "null" ], "description": "", "properties": { "find": { "type": "string", "description": "The searched string." }, "caseSensitive": { "type": "boolean", "description": "Whether case was significant." }, "count": { "type": "integer", "description": "Non-overlapping matches, scanning left to right." }, "overlappingCount": { "type": "integer", "description": "Matches starting at every code point (e.g. \"aa\" in \"aaa\" is 2)." }, "positions": { "type": "array", "items": { "type": "object", "description": "", "properties": { "match": { "type": "string", "description": "The matched text (differs from `find` only in case)." }, "splitsGrapheme": { "type": "boolean", "description": "The match starts or ends inside a grapheme cluster (e.g. `e` in e + U+0301)." }, "utf16Index": { "type": "integer", "description": "0-based offset in UTF-16 code units (JavaScript string index)." }, "codePointIndex": { "type": "integer", "description": "0-based offset in Unicode code points." }, "graphemeIndex": { "type": "integer", "description": "0-based index of the grapheme cluster (user-perceived character)." }, "line": { "type": "integer", "description": "1-based line number (lines end at LF, CRLF or CR)." }, "column": { "type": "integer", "description": "1-based column, counted in code points." } }, "required": [ "match", "splitsGrapheme", "utf16Index", "codePointIndex", "graphemeIndex", "line", "column" ], "additionalProperties": false }, "description": "Position of each non-overlapping match (first 1000)." }, "truncated": { "type": "boolean", "description": "More than 1000 matches; positions lists the first ones." } }, "required": [ "find", "caseSensitive", "count", "overlappingCount", "positions", "truncated" ], "additionalProperties": false }, "invisible": { "type": "object", "description": "", "properties": { "total": { "type": "integer", "description": "Total findings, including those beyond the list limit." }, "byKind": { "type": "object", "description": "Findings per kind (kinds with zero are omitted).", "additionalProperties": { "type": "integer", "description": "Count." } }, "findings": { "type": "array", "items": { "type": "object", "description": "", "properties": { "kind": { "type": "string", "description": "Category of the finding.", "enum": [ "bom", "zero-width", "bidi-control", "bidi-mark", "unusual-space", "control", "line-separator", "tag", "variation-selector", "invisible-format", "invisible-letter", "replacement", "lone-surrogate", "private-use", "confusable" ] }, "codePoint": { "type": "string", "description": "U+XXXX." }, "name": { "type": "string", "description": "Unicode character name where known, else empty." }, "looksLike": { "type": [ "string", "null" ], "description": "For `confusable`: the ASCII character it imitates." }, "utf16Index": { "type": "integer", "description": "0-based offset in UTF-16 code units (JavaScript string index)." }, "codePointIndex": { "type": "integer", "description": "0-based offset in Unicode code points." }, "graphemeIndex": { "type": "integer", "description": "0-based index of the grapheme cluster (user-perceived character)." }, "line": { "type": "integer", "description": "1-based line number (lines end at LF, CRLF or CR)." }, "column": { "type": "integer", "description": "1-based column, counted in code points." } }, "required": [ "kind", "codePoint", "name", "looksLike", "utf16Index", "codePointIndex", "graphemeIndex", "line", "column" ], "additionalProperties": false }, "description": "Invisible, bidirectional, control and look-alike characters in text order (first 1000)." }, "truncated": { "type": "boolean", "description": "More than 1000 findings." }, "bidiUnterminatedLines": { "type": "array", "items": { "type": "integer", "description": "Line number." }, "description": "Lines where a bidi embedding, override or isolate is still open at the end (Trojan Source, CVE-2021-42574)." }, "mixedScriptWords": { "type": "array", "items": { "type": "object", "description": "", "properties": { "word": { "type": "string", "description": "The word." }, "scripts": { "type": "array", "items": { "type": "string", "description": "Script name." }, "description": "Scripts mixed in the word." }, "utf16Index": { "type": "integer", "description": "Start offset in UTF-16 code units." }, "line": { "type": "integer", "description": "1-based line." } }, "required": [ "word", "scripts", "utf16Index", "line" ], "additionalProperties": false }, "description": "Words mixing Latin with Cyrillic, Greek or Armenian letters." } }, "required": [ "total", "byKind", "findings", "truncated", "bidiUnterminatedLines", "mixedScriptWords" ], "additionalProperties": false }, "breakdown": { "type": [ "object", "null" ], "description": "", "properties": { "entries": { "type": "array", "items": { "type": "object", "description": "", "properties": { "codePointIndex": { "type": "integer", "description": "0-based code point index." }, "utf16Index": { "type": "integer", "description": "0-based UTF-16 offset." }, "graphemeIndex": { "type": "integer", "description": "Grapheme cluster this code point belongs to." }, "char": { "type": "string", "description": "The character itself." }, "codePoint": { "type": "string", "description": "U+XXXX." }, "utf8": { "type": "string", "description": "UTF-8 bytes as space-separated uppercase hex." }, "utf16": { "type": "string", "description": "UTF-16 code units as space-separated uppercase hex." }, "category": { "type": "string", "description": "Unicode General_Category, e.g. `Lu`, `Ll`, `Nd`, `Zs`, `Cf`." }, "script": { "type": [ "string", "null" ], "description": "Unicode Script property, e.g. `Latin`; null if not one of the scripts checked." }, "name": { "type": [ "string", "null" ], "description": "Unicode name for controls, spaces and invisible characters; null otherwise." } }, "required": [ "codePointIndex", "utf16Index", "graphemeIndex", "char", "codePoint", "utf8", "utf16", "category", "script", "name" ], "additionalProperties": false }, "description": "One entry per code point." }, "truncated": { "type": "boolean", "description": "The text has more code points than were broken down." } }, "required": [ "entries", "truncated" ], "additionalProperties": false }, "warnings": { "type": "array", "items": { "type": "string", "description": "Plain-language finding." }, "description": "Security-relevant findings and anomalies." } }, "required": [ "locale", "counts", "lineEndings", "characterClasses", "normalization", "occurrences", "invisible", "breakdown", "warnings" ], "additionalProperties": false } } } }, "400": { "description": "missing_parameter / unknown_parameter / `locale` is not a valid BCP 47 tag, `find` is empty, `breakdown` is out of range, or `input` is longer than 20,000 UTF-16 code units (split it and add the counts).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "text_inspect_get", "parameters": [ { "name": "input", "in": "query", "required": true, "description": "The text, up to 20,000 UTF-16 code units. Sent as-is: no trimming or normalization.", "schema": { "description": "The text, up to 20,000 UTF-16 code units. Sent as-is: no trimming or normalization.", "type": "string" } }, { "name": "find", "in": "query", "required": false, "description": "A substring or single character to count and locate. Matched literally (not a regex) and without Unicode normalization.", "schema": { "description": "A substring or single character to count and locate. Matched literally (not a regex) and without Unicode normalization.", "type": "string" } }, { "name": "case_sensitive", "in": "query", "required": false, "description": "Whether find is case-sensitive. When false, Unicode simple case folding is used (R matches r).", "schema": { "description": "Whether find is case-sensitive. When false, Unicode simple case folding is used (R matches r).", "type": "boolean", "default": true } }, { "name": "breakdown", "in": "query", "required": false, "description": "Return a per-code-point breakdown (U+XXXX, UTF-8 hex, category, script) of the first N code points. 0 (default) for none; at most 2000.", "schema": { "description": "Return a per-code-point breakdown (U+XXXX, UTF-8 hex, category, script) of the first N code points. 0 (default) for none; at most 2000.", "type": "integer", "default": 0, "minimum": 0, "maximum": 2000 } }, { "name": "locale", "in": "query", "required": false, "description": "BCP 47 locale for word and sentence segmentation, e.g. en, th, ja. Default: the runtime default.", "schema": { "description": "BCP 47 locale for word and sentence segmentation, e.g. en, th, ja. Default: the runtime default.", "type": "string" } }, { "name": "format", "in": "query", "required": false, "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "schema": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } } ] }, "post": { "summary": "Exact counts of characters, bytes, words and lines; find substrings; reveal invisible characters.", "description": "Counts text the ways software disagrees about: grapheme clusters (what people see as characters), code points, UTF-16 code units (JavaScript length) and UTF-8 bytes; lines with their line-ending style; words and sentences (Intl.Segmenter); and letters, digits, whitespace and punctuation by Unicode property. With `find`, counts occurrences of a substring or character and returns each position (e.g. `find=r` in `strawberry` is 3). It also reports invisible and deceptive characters with positions: zero-width characters, bidirectional controls (Trojan Source, CVE-2021-42574), unusual spaces such as NBSP, BOM, control characters, Unicode tag characters (hidden-prompt smuggling), and Latin look-alikes in mixed-script words. Use this instead of counting characters yourself.\n\nPrivacy: The server receives the text (and the search string), analyses it in memory, and returns counts and positions. Your input is not stored or logged; only the per-call metadata row (operation, time, status, sizes) is recorded. For private text use the page, which does the same analysis in your browser.", "tags": [ "text" ], "responses": { "200": { "description": "Success. With format=text, text/plain is returned instead of JSON.", "content": { "application/json": { "schema": { "type": "object", "description": "", "properties": { "locale": { "type": "string", "description": "Locale used by Intl.Segmenter after resolution." }, "counts": { "type": "object", "description": "", "properties": { "graphemes": { "type": "integer", "description": "Extended grapheme clusters (UAX #29): what a person counts as characters." }, "codePoints": { "type": "integer", "description": "Unicode code points (a lone surrogate counts as one)." }, "utf16CodeUnits": { "type": "integer", "description": "UTF-16 code units: JavaScript `length`, Java `length()`." }, "utf8Bytes": { "type": "integer", "description": "Bytes when encoded as UTF-8 (lone surrogates as U+FFFD, 3 bytes)." }, "words": { "type": "integer", "description": "Word segments with isWordLike (letters/numbers/ideographs; not punctuation or spaces)." }, "sentences": { "type": "integer", "description": "Sentence segments containing a non-whitespace character." }, "lines": { "type": "integer", "description": "Lines: 0 for empty text; a final line break does not start a new line." }, "lineBreaks": { "type": "integer", "description": "LF + CRLF + CR line breaks (CRLF counts once)." }, "nonEmptyLines": { "type": "integer", "description": "Lines with at least one character." } }, "required": [ "graphemes", "codePoints", "utf16CodeUnits", "utf8Bytes", "words", "sentences", "lines", "lineBreaks", "nonEmptyLines" ], "additionalProperties": false }, "lineEndings": { "type": "object", "description": "", "properties": { "style": { "type": "string", "description": "`none`, `LF`, `CRLF`, `CR`, or `mixed`.", "enum": [ "none", "LF", "CRLF", "CR", "mixed" ] }, "lf": { "type": "integer", "description": "Bare LF count." }, "crlf": { "type": "integer", "description": "CRLF count." }, "cr": { "type": "integer", "description": "Bare CR count." }, "endsWithLineBreak": { "type": "boolean", "description": "The text ends with LF, CRLF or CR." } }, "required": [ "style", "lf", "crlf", "cr", "endsWithLineBreak" ], "additionalProperties": false }, "characterClasses": { "type": "object", "description": "Counts of code points by Unicode property (emoji counts grapheme clusters).", "properties": { "letters": { "type": "integer", "description": "\\p{L}" }, "uppercase": { "type": "integer", "description": "\\p{Lu}" }, "lowercase": { "type": "integer", "description": "\\p{Ll}" }, "marks": { "type": "integer", "description": "\\p{M} (combining marks, including variation selectors)" }, "digits": { "type": "integer", "description": "\\p{Nd} (decimal digits in any script)" }, "numbers": { "type": "integer", "description": "\\p{N} (digits plus letter-like and other numerals)" }, "punctuation": { "type": "integer", "description": "\\p{P}" }, "symbols": { "type": "integer", "description": "\\p{S}" }, "whitespace": { "type": "integer", "description": "\\p{White_Space} (includes line breaks and tabs)" }, "spaces": { "type": "integer", "description": "\\p{Zs} (space separators, including NBSP)" }, "control": { "type": "integer", "description": "\\p{Cc} (includes tab, LF, CR)" }, "format": { "type": "integer", "description": "\\p{Cf} (invisible format characters)" }, "emoji": { "type": "integer", "description": "Grapheme clusters containing an \\p{Extended_Pictographic} character." } }, "required": [ "letters", "uppercase", "lowercase", "marks", "digits", "numbers", "punctuation", "symbols", "whitespace", "spaces", "control", "format", "emoji" ], "additionalProperties": false }, "normalization": { "type": "object", "description": "", "properties": { "isNFC": { "type": "boolean", "description": "The text is unchanged by NFC normalization." }, "isNFD": { "type": "boolean", "description": "The text is unchanged by NFD normalization." }, "isNFKC": { "type": "boolean", "description": "The text is unchanged by NFKC normalization." } }, "required": [ "isNFC", "isNFD", "isNFKC" ], "additionalProperties": false }, "occurrences": { "type": [ "object", "null" ], "description": "", "properties": { "find": { "type": "string", "description": "The searched string." }, "caseSensitive": { "type": "boolean", "description": "Whether case was significant." }, "count": { "type": "integer", "description": "Non-overlapping matches, scanning left to right." }, "overlappingCount": { "type": "integer", "description": "Matches starting at every code point (e.g. \"aa\" in \"aaa\" is 2)." }, "positions": { "type": "array", "items": { "type": "object", "description": "", "properties": { "match": { "type": "string", "description": "The matched text (differs from `find` only in case)." }, "splitsGrapheme": { "type": "boolean", "description": "The match starts or ends inside a grapheme cluster (e.g. `e` in e + U+0301)." }, "utf16Index": { "type": "integer", "description": "0-based offset in UTF-16 code units (JavaScript string index)." }, "codePointIndex": { "type": "integer", "description": "0-based offset in Unicode code points." }, "graphemeIndex": { "type": "integer", "description": "0-based index of the grapheme cluster (user-perceived character)." }, "line": { "type": "integer", "description": "1-based line number (lines end at LF, CRLF or CR)." }, "column": { "type": "integer", "description": "1-based column, counted in code points." } }, "required": [ "match", "splitsGrapheme", "utf16Index", "codePointIndex", "graphemeIndex", "line", "column" ], "additionalProperties": false }, "description": "Position of each non-overlapping match (first 1000)." }, "truncated": { "type": "boolean", "description": "More than 1000 matches; positions lists the first ones." } }, "required": [ "find", "caseSensitive", "count", "overlappingCount", "positions", "truncated" ], "additionalProperties": false }, "invisible": { "type": "object", "description": "", "properties": { "total": { "type": "integer", "description": "Total findings, including those beyond the list limit." }, "byKind": { "type": "object", "description": "Findings per kind (kinds with zero are omitted).", "additionalProperties": { "type": "integer", "description": "Count." } }, "findings": { "type": "array", "items": { "type": "object", "description": "", "properties": { "kind": { "type": "string", "description": "Category of the finding.", "enum": [ "bom", "zero-width", "bidi-control", "bidi-mark", "unusual-space", "control", "line-separator", "tag", "variation-selector", "invisible-format", "invisible-letter", "replacement", "lone-surrogate", "private-use", "confusable" ] }, "codePoint": { "type": "string", "description": "U+XXXX." }, "name": { "type": "string", "description": "Unicode character name where known, else empty." }, "looksLike": { "type": [ "string", "null" ], "description": "For `confusable`: the ASCII character it imitates." }, "utf16Index": { "type": "integer", "description": "0-based offset in UTF-16 code units (JavaScript string index)." }, "codePointIndex": { "type": "integer", "description": "0-based offset in Unicode code points." }, "graphemeIndex": { "type": "integer", "description": "0-based index of the grapheme cluster (user-perceived character)." }, "line": { "type": "integer", "description": "1-based line number (lines end at LF, CRLF or CR)." }, "column": { "type": "integer", "description": "1-based column, counted in code points." } }, "required": [ "kind", "codePoint", "name", "looksLike", "utf16Index", "codePointIndex", "graphemeIndex", "line", "column" ], "additionalProperties": false }, "description": "Invisible, bidirectional, control and look-alike characters in text order (first 1000)." }, "truncated": { "type": "boolean", "description": "More than 1000 findings." }, "bidiUnterminatedLines": { "type": "array", "items": { "type": "integer", "description": "Line number." }, "description": "Lines where a bidi embedding, override or isolate is still open at the end (Trojan Source, CVE-2021-42574)." }, "mixedScriptWords": { "type": "array", "items": { "type": "object", "description": "", "properties": { "word": { "type": "string", "description": "The word." }, "scripts": { "type": "array", "items": { "type": "string", "description": "Script name." }, "description": "Scripts mixed in the word." }, "utf16Index": { "type": "integer", "description": "Start offset in UTF-16 code units." }, "line": { "type": "integer", "description": "1-based line." } }, "required": [ "word", "scripts", "utf16Index", "line" ], "additionalProperties": false }, "description": "Words mixing Latin with Cyrillic, Greek or Armenian letters." } }, "required": [ "total", "byKind", "findings", "truncated", "bidiUnterminatedLines", "mixedScriptWords" ], "additionalProperties": false }, "breakdown": { "type": [ "object", "null" ], "description": "", "properties": { "entries": { "type": "array", "items": { "type": "object", "description": "", "properties": { "codePointIndex": { "type": "integer", "description": "0-based code point index." }, "utf16Index": { "type": "integer", "description": "0-based UTF-16 offset." }, "graphemeIndex": { "type": "integer", "description": "Grapheme cluster this code point belongs to." }, "char": { "type": "string", "description": "The character itself." }, "codePoint": { "type": "string", "description": "U+XXXX." }, "utf8": { "type": "string", "description": "UTF-8 bytes as space-separated uppercase hex." }, "utf16": { "type": "string", "description": "UTF-16 code units as space-separated uppercase hex." }, "category": { "type": "string", "description": "Unicode General_Category, e.g. `Lu`, `Ll`, `Nd`, `Zs`, `Cf`." }, "script": { "type": [ "string", "null" ], "description": "Unicode Script property, e.g. `Latin`; null if not one of the scripts checked." }, "name": { "type": [ "string", "null" ], "description": "Unicode name for controls, spaces and invisible characters; null otherwise." } }, "required": [ "codePointIndex", "utf16Index", "graphemeIndex", "char", "codePoint", "utf8", "utf16", "category", "script", "name" ], "additionalProperties": false }, "description": "One entry per code point." }, "truncated": { "type": "boolean", "description": "The text has more code points than were broken down." } }, "required": [ "entries", "truncated" ], "additionalProperties": false }, "warnings": { "type": "array", "items": { "type": "string", "description": "Plain-language finding." }, "description": "Security-relevant findings and anomalies." } }, "required": [ "locale", "counts", "lineEndings", "characterClasses", "normalization", "occurrences", "invisible", "breakdown", "warnings" ], "additionalProperties": false } } } }, "400": { "description": "missing_parameter / unknown_parameter / `locale` is not a valid BCP 47 tag, `find` is empty, `breakdown` is out of range, or `input` is longer than 20,000 UTF-16 code units (split it and add the counts).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "text_inspect", "parameters": [ { "name": "format", "in": "query", "required": false, "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "schema": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "input": { "description": "The text, up to 20,000 UTF-16 code units. Sent as-is: no trimming or normalization.", "type": "string" }, "find": { "description": "A substring or single character to count and locate. Matched literally (not a regex) and without Unicode normalization.", "type": "string" }, "case_sensitive": { "description": "Whether find is case-sensitive. When false, Unicode simple case folding is used (R matches r).", "type": "boolean", "default": true }, "breakdown": { "description": "Return a per-code-point breakdown (U+XXXX, UTF-8 hex, category, script) of the first N code points. 0 (default) for none; at most 2000.", "type": "integer", "default": 0, "minimum": 0, "maximum": 2000 }, "locale": { "description": "BCP 47 locale for word and sentence segmentation, e.g. en, th, ja. Default: the runtime default.", "type": "string" }, "format": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } }, "required": [ "input" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "The body is used as the `input` parameter." } } } } } }, "/api/time/now": { "get": { "summary": "The current instant from the server clock, in one or more time zones.", "description": "Returns the current time from the server's clock when the request is processed (millisecond resolution) as UTC, Unix seconds and milliseconds, and, for each requested zone, the local ISO 8601 time with offset, weekday, ISO week, day of year, zone abbreviation, UTC offset and whether DST is in effect. Use it instead of guessing today's date.\n\nPrivacy: The server receives only the zone names and format options, reads its own clock, and returns the result. Your input is not stored or logged; only the per-call metadata row (operation, time, status, sizes) is recorded.", "tags": [ "time" ], "responses": { "200": { "description": "Success. With format=text, text/plain is returned instead of JSON.", "content": { "application/json": { "schema": { "type": "object", "description": "", "properties": { "instant": { "type": "object", "description": "", "properties": { "utc": { "type": "string", "description": "The instant in UTC, ISO 8601 with `Z`." }, "unix_seconds": { "type": "integer", "description": "Whole seconds since 1970-01-01T00:00:00Z, rounded down (floor)." }, "unix_milliseconds": { "type": "integer", "description": "Milliseconds since 1970-01-01T00:00:00Z." } }, "required": [ "utc", "unix_seconds", "unix_milliseconds" ], "additionalProperties": false }, "zones": { "type": "array", "items": { "type": "object", "description": "", "properties": { "zone": { "type": "string", "description": "Zone name as resolved: IANA name (letter case corrected), `UTC`, or `UTC±HH:MM`." }, "iso": { "type": "string", "description": "ISO 8601 / RFC 3339 with the UTC offset (`Z` for UTC). Milliseconds appear only when non-zero." }, "local": { "type": "string", "description": "Wall-clock date-time in the zone without an offset, `YYYY-MM-DDTHH:mm:ss[.SSS]`." }, "date": { "type": "string", "description": "Local calendar date, `YYYY-MM-DD`." }, "time": { "type": "string", "description": "Local time, `HH:mm:ss` (24-hour), with `.SSS` only when milliseconds are non-zero." }, "offset": { "type": "string", "description": "UTC offset, `±HH:MM`." }, "offset_minutes": { "type": "integer", "description": "UTC offset in minutes (east positive), e.g. -240 for UTC-04:00." }, "abbreviation": { "type": "string", "description": "Short zone name as Intl (en-US) prints it: `EDT`, `PST`, or `GMT+2` where English has no common abbreviation." }, "offset_name": { "type": "string", "description": "Long zone name, e.g. `Eastern Daylight Time`." }, "dst": { "type": "boolean", "description": "True when daylight saving time is in effect at this instant." }, "weekday": { "type": "string", "description": "English weekday name, e.g. `Tuesday`." }, "weekday_number": { "type": "integer", "description": "ISO 8601 weekday: 1 = Monday … 7 = Sunday.", "minimum": 1, "maximum": 7 }, "iso_week": { "type": "string", "description": "ISO 8601 week, `YYYY-Www` (the week-numbering year can differ from the calendar year near 1 January)." }, "iso_week_year": { "type": "integer", "description": "ISO 8601 week-numbering year." }, "iso_week_number": { "type": "integer", "description": "ISO 8601 week number, 1-53.", "minimum": 1, "maximum": 53 }, "day_of_year": { "type": "integer", "description": "Ordinal day of the year, 1-366.", "minimum": 1, "maximum": 366 }, "formatted": { "type": "object", "description": "Extra renderings requested with `formats` (keyed by format name) and `pattern` (key `pattern`). Empty when none were requested.", "additionalProperties": { "type": "string", "description": "The time in that format." } } }, "required": [ "zone", "iso", "local", "date", "time", "offset", "offset_minutes", "abbreviation", "offset_name", "dst", "weekday", "weekday_number", "iso_week", "iso_week_year", "iso_week_number", "day_of_year", "formatted" ], "additionalProperties": false }, "description": "One entry per requested zone, in request order." }, "warnings": { "type": "array", "items": { "type": "string", "description": "Plain-language warning." }, "description": "Warnings about the zones given (fixed offsets, legacy or inverted names)." } }, "required": [ "instant", "zones", "warnings" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "The ISO 8601 time in each requested zone, one per line." } } } }, "400": { "description": "missing_parameter / unknown_parameter / A zone is unknown, an abbreviation, or `local`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "time_now_get", "parameters": [ { "name": "zones", "in": "query", "required": false, "description": "Comma-separated (or JSON array) zones: IANA names (America/New_York, Europe/Paris, Asia/Tokyo), UTC, or fixed offsets (+05:30, UTC-03:00). Abbreviations like PST or CET are rejected as ambiguous. At most 20.", "style": "form", "explode": false, "schema": { "description": "Comma-separated (or JSON array) zones: IANA names (America/New_York, Europe/Paris, Asia/Tokyo), UTC, or fixed offsets (+05:30, UTC-03:00). Abbreviations like PST or CET are rejected as ambiguous. At most 20.", "type": "array", "items": { "type": "string" }, "default": "UTC" } }, { "name": "formats", "in": "query", "required": false, "description": "Extra renderings added to each zone's formatted map: rfc2822 (Tue, 13 Oct 2026 14:30:00 +0200), http (HTTP-date, always GMT), sql (2026-10-13 14:30:00.000 +02:00), iso_basic (20261013T143000+0200), iso_week_date (2026-W42-2), iso_ordinal (2026-286), human (Tuesday, October 13, 2026 at 2:30:00 PM GMT+2).", "style": "form", "explode": false, "schema": { "description": "Extra renderings added to each zone's formatted map: rfc2822 (Tue, 13 Oct 2026 14:30:00 +0200), http (HTTP-date, always GMT), sql (2026-10-13 14:30:00.000 +02:00), iso_basic (20261013T143000+0200), iso_week_date (2026-W42-2), iso_ordinal (2026-286), human (Tuesday, October 13, 2026 at 2:30:00 PM GMT+2).", "type": "array", "items": { "type": "string", "enum": [ "rfc2822", "http", "sql", "iso_basic", "iso_week_date", "iso_ordinal", "human" ] } } }, { "name": "pattern", "in": "query", "required": false, "description": "Custom format using Luxon tokens (e.g. yyyy-MM-dd HH:mm ZZZZ; quote literal text in single quotes). Added to formatted.pattern. English names.", "schema": { "description": "Custom format using Luxon tokens (e.g. yyyy-MM-dd HH:mm ZZZZ; quote literal text in single quotes). Added to formatted.pattern. English names.", "type": "string" } }, { "name": "format", "in": "query", "required": false, "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "schema": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } } ] }, "post": { "summary": "The current instant from the server clock, in one or more time zones.", "description": "Returns the current time from the server's clock when the request is processed (millisecond resolution) as UTC, Unix seconds and milliseconds, and, for each requested zone, the local ISO 8601 time with offset, weekday, ISO week, day of year, zone abbreviation, UTC offset and whether DST is in effect. Use it instead of guessing today's date.\n\nPrivacy: The server receives only the zone names and format options, reads its own clock, and returns the result. Your input is not stored or logged; only the per-call metadata row (operation, time, status, sizes) is recorded.", "tags": [ "time" ], "responses": { "200": { "description": "Success. With format=text, text/plain is returned instead of JSON.", "content": { "application/json": { "schema": { "type": "object", "description": "", "properties": { "instant": { "type": "object", "description": "", "properties": { "utc": { "type": "string", "description": "The instant in UTC, ISO 8601 with `Z`." }, "unix_seconds": { "type": "integer", "description": "Whole seconds since 1970-01-01T00:00:00Z, rounded down (floor)." }, "unix_milliseconds": { "type": "integer", "description": "Milliseconds since 1970-01-01T00:00:00Z." } }, "required": [ "utc", "unix_seconds", "unix_milliseconds" ], "additionalProperties": false }, "zones": { "type": "array", "items": { "type": "object", "description": "", "properties": { "zone": { "type": "string", "description": "Zone name as resolved: IANA name (letter case corrected), `UTC`, or `UTC±HH:MM`." }, "iso": { "type": "string", "description": "ISO 8601 / RFC 3339 with the UTC offset (`Z` for UTC). Milliseconds appear only when non-zero." }, "local": { "type": "string", "description": "Wall-clock date-time in the zone without an offset, `YYYY-MM-DDTHH:mm:ss[.SSS]`." }, "date": { "type": "string", "description": "Local calendar date, `YYYY-MM-DD`." }, "time": { "type": "string", "description": "Local time, `HH:mm:ss` (24-hour), with `.SSS` only when milliseconds are non-zero." }, "offset": { "type": "string", "description": "UTC offset, `±HH:MM`." }, "offset_minutes": { "type": "integer", "description": "UTC offset in minutes (east positive), e.g. -240 for UTC-04:00." }, "abbreviation": { "type": "string", "description": "Short zone name as Intl (en-US) prints it: `EDT`, `PST`, or `GMT+2` where English has no common abbreviation." }, "offset_name": { "type": "string", "description": "Long zone name, e.g. `Eastern Daylight Time`." }, "dst": { "type": "boolean", "description": "True when daylight saving time is in effect at this instant." }, "weekday": { "type": "string", "description": "English weekday name, e.g. `Tuesday`." }, "weekday_number": { "type": "integer", "description": "ISO 8601 weekday: 1 = Monday … 7 = Sunday.", "minimum": 1, "maximum": 7 }, "iso_week": { "type": "string", "description": "ISO 8601 week, `YYYY-Www` (the week-numbering year can differ from the calendar year near 1 January)." }, "iso_week_year": { "type": "integer", "description": "ISO 8601 week-numbering year." }, "iso_week_number": { "type": "integer", "description": "ISO 8601 week number, 1-53.", "minimum": 1, "maximum": 53 }, "day_of_year": { "type": "integer", "description": "Ordinal day of the year, 1-366.", "minimum": 1, "maximum": 366 }, "formatted": { "type": "object", "description": "Extra renderings requested with `formats` (keyed by format name) and `pattern` (key `pattern`). Empty when none were requested.", "additionalProperties": { "type": "string", "description": "The time in that format." } } }, "required": [ "zone", "iso", "local", "date", "time", "offset", "offset_minutes", "abbreviation", "offset_name", "dst", "weekday", "weekday_number", "iso_week", "iso_week_year", "iso_week_number", "day_of_year", "formatted" ], "additionalProperties": false }, "description": "One entry per requested zone, in request order." }, "warnings": { "type": "array", "items": { "type": "string", "description": "Plain-language warning." }, "description": "Warnings about the zones given (fixed offsets, legacy or inverted names)." } }, "required": [ "instant", "zones", "warnings" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "The ISO 8601 time in each requested zone, one per line." } } } }, "400": { "description": "missing_parameter / unknown_parameter / A zone is unknown, an abbreviation, or `local`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "time_now", "parameters": [ { "name": "format", "in": "query", "required": false, "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "schema": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "zones": { "description": "Comma-separated (or JSON array) zones: IANA names (America/New_York, Europe/Paris, Asia/Tokyo), UTC, or fixed offsets (+05:30, UTC-03:00). Abbreviations like PST or CET are rejected as ambiguous. At most 20.", "type": "array", "items": { "type": "string" }, "default": "UTC" }, "formats": { "description": "Extra renderings added to each zone's formatted map: rfc2822 (Tue, 13 Oct 2026 14:30:00 +0200), http (HTTP-date, always GMT), sql (2026-10-13 14:30:00.000 +02:00), iso_basic (20261013T143000+0200), iso_week_date (2026-W42-2), iso_ordinal (2026-286), human (Tuesday, October 13, 2026 at 2:30:00 PM GMT+2).", "type": "array", "items": { "type": "string", "enum": [ "rfc2822", "http", "sql", "iso_basic", "iso_week_date", "iso_ordinal", "human" ] } }, "pattern": { "description": "Custom format using Luxon tokens (e.g. yyyy-MM-dd HH:mm ZZZZ; quote literal text in single quotes). Added to formatted.pattern. English names.", "type": "string" }, "format": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } }, "required": [], "additionalProperties": false } } } } } }, "/api/time/convert": { "get": { "summary": "Parse a date-time or Unix timestamp and show it in other zones and formats.", "description": "Parses `input` and returns the instant in UTC, as Unix seconds and milliseconds, and in each zone of `zones`. The response says exactly how the input was read: the detected format, the inferred timestamp unit (with what the other units would have meant), and, for a wall-clock time without an offset, the zone used and whether that local time was unique, skipped by a DST gap, or repeated in a DST overlap.\n\nPrivacy: The server receives the date-time string and zone names, converts them in memory, and returns the result. Your input is not stored or logged; only the per-call metadata row (operation, time, status, sizes) is recorded.", "tags": [ "time" ], "responses": { "200": { "description": "Success. With format=text, text/plain is returned instead of JSON.", "content": { "application/json": { "schema": { "type": "object", "description": "", "properties": { "input": { "type": "object", "description": "", "properties": { "input": { "type": "string", "description": "The input as received (trimmed)." }, "format": { "type": "string", "description": "How the input was parsed.", "enum": [ "now", "iso8601", "rfc2822", "http-date", "unix" ] }, "unit": { "type": [ "string", "null" ], "description": "Unit of a Unix timestamp (`seconds`, `milliseconds`, `microseconds`, `nanoseconds`); null for other formats." }, "unit_auto_detected": { "type": "boolean", "description": "True when the timestamp unit was inferred from its magnitude." }, "has_offset": { "type": "boolean", "description": "False when the input was a wall-clock time without a UTC offset, resolved in `local_zone`." }, "local_zone": { "type": [ "string", "null" ], "description": "Zone used to resolve a wall-clock input; null otherwise." }, "local_time": { "type": [ "string", "null" ], "description": "For wall-clock input: `unique`, `gap` (did not exist; DST jump forward) or `overlap` (occurred twice; DST jump back). Null otherwise." }, "notes": { "type": "array", "items": { "type": "string", "description": "Plain-language note." }, "description": "Every assumption made: auto-detected units and their alternatives, the zone used for wall-clock input, DST resolution, truncated precision." } }, "required": [ "input", "format", "unit", "unit_auto_detected", "has_offset", "local_zone", "local_time", "notes" ], "additionalProperties": false }, "instant": { "type": "object", "description": "", "properties": { "utc": { "type": "string", "description": "The instant in UTC, ISO 8601 with `Z`." }, "unix_seconds": { "type": "integer", "description": "Whole seconds since 1970-01-01T00:00:00Z, rounded down (floor)." }, "unix_milliseconds": { "type": "integer", "description": "Milliseconds since 1970-01-01T00:00:00Z." } }, "required": [ "utc", "unix_seconds", "unix_milliseconds" ], "additionalProperties": false }, "zones": { "type": "array", "items": { "type": "object", "description": "", "properties": { "zone": { "type": "string", "description": "Zone name as resolved: IANA name (letter case corrected), `UTC`, or `UTC±HH:MM`." }, "iso": { "type": "string", "description": "ISO 8601 / RFC 3339 with the UTC offset (`Z` for UTC). Milliseconds appear only when non-zero." }, "local": { "type": "string", "description": "Wall-clock date-time in the zone without an offset, `YYYY-MM-DDTHH:mm:ss[.SSS]`." }, "date": { "type": "string", "description": "Local calendar date, `YYYY-MM-DD`." }, "time": { "type": "string", "description": "Local time, `HH:mm:ss` (24-hour), with `.SSS` only when milliseconds are non-zero." }, "offset": { "type": "string", "description": "UTC offset, `±HH:MM`." }, "offset_minutes": { "type": "integer", "description": "UTC offset in minutes (east positive), e.g. -240 for UTC-04:00." }, "abbreviation": { "type": "string", "description": "Short zone name as Intl (en-US) prints it: `EDT`, `PST`, or `GMT+2` where English has no common abbreviation." }, "offset_name": { "type": "string", "description": "Long zone name, e.g. `Eastern Daylight Time`." }, "dst": { "type": "boolean", "description": "True when daylight saving time is in effect at this instant." }, "weekday": { "type": "string", "description": "English weekday name, e.g. `Tuesday`." }, "weekday_number": { "type": "integer", "description": "ISO 8601 weekday: 1 = Monday … 7 = Sunday.", "minimum": 1, "maximum": 7 }, "iso_week": { "type": "string", "description": "ISO 8601 week, `YYYY-Www` (the week-numbering year can differ from the calendar year near 1 January)." }, "iso_week_year": { "type": "integer", "description": "ISO 8601 week-numbering year." }, "iso_week_number": { "type": "integer", "description": "ISO 8601 week number, 1-53.", "minimum": 1, "maximum": 53 }, "day_of_year": { "type": "integer", "description": "Ordinal day of the year, 1-366.", "minimum": 1, "maximum": 366 }, "formatted": { "type": "object", "description": "Extra renderings requested with `formats` (keyed by format name) and `pattern` (key `pattern`). Empty when none were requested.", "additionalProperties": { "type": "string", "description": "The time in that format." } } }, "required": [ "zone", "iso", "local", "date", "time", "offset", "offset_minutes", "abbreviation", "offset_name", "dst", "weekday", "weekday_number", "iso_week", "iso_week_year", "iso_week_number", "day_of_year", "formatted" ], "additionalProperties": false }, "description": "One entry per requested zone, in request order." }, "warnings": { "type": "array", "items": { "type": "string", "description": "Plain-language warning." }, "description": "Warnings about the zones given (fixed offsets, legacy or inverted names)." } }, "required": [ "input", "instant", "zones", "warnings" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "The ISO 8601 time in each requested zone, one per line." } } } }, "400": { "description": "missing_parameter / unknown_parameter / A zone is unknown or an abbreviation, or `unit` is given for non-numeric input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`input` is not a recognised format, is an impossible date (`2026-02-30`), is outside ±8.64e15 ms of 1970, has no offset and no `from_zone`, or falls in a DST gap/overlap with `disambiguation=reject`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "time_convert_get", "parameters": [ { "name": "input", "in": "query", "required": true, "description": "ISO 8601 / RFC 3339 (2026-10-13T14:30:00Z, 2026-10-13T14:30:00+02:00, 2026-10-13 14:30, 2026-10-13, 2026-W42-2, with an optional RFC 9557 [Zone/Name] suffix), RFC 2822, HTTP-date (IMF-fixdate, RFC 850, asctime), a Unix timestamp (seconds, milliseconds, microseconds or nanoseconds; decimals allowed), or now.", "schema": { "description": "ISO 8601 / RFC 3339 (2026-10-13T14:30:00Z, 2026-10-13T14:30:00+02:00, 2026-10-13 14:30, 2026-10-13, 2026-W42-2, with an optional RFC 9557 [Zone/Name] suffix), RFC 2822, HTTP-date (IMF-fixdate, RFC 850, asctime), a Unix timestamp (seconds, milliseconds, microseconds or nanoseconds; decimals allowed), or now.", "type": "string" } }, { "name": "unit", "in": "query", "required": false, "description": "Unit of a numeric Unix timestamp. auto infers it from the magnitude: below 10^11 seconds, below 10^14 milliseconds, below 10^17 microseconds, otherwise nanoseconds. Only valid with numeric input.", "schema": { "description": "Unit of a numeric Unix timestamp. auto infers it from the magnitude: below 10^11 seconds, below 10^14 milliseconds, below 10^17 microseconds, otherwise nanoseconds. Only valid with numeric input.", "type": "string", "enum": [ "auto", "seconds", "milliseconds", "microseconds", "nanoseconds" ], "default": "auto" } }, { "name": "from_zone", "in": "query", "required": false, "description": "Zone in which to read an input that has no UTC offset (2026-03-08T02:30). Required for such input; ignored when the input carries an offset or a Unix timestamp.", "schema": { "description": "Zone in which to read an input that has no UTC offset (2026-03-08T02:30). Required for such input; ignored when the input carries an offset or a Unix timestamp.", "type": "string" } }, { "name": "disambiguation", "in": "query", "required": false, "description": "How to resolve a wall-clock time that falls in a DST gap or overlap (same meaning as in JavaScript Temporal). compatible: gap → shift forward by the gap length, overlap → earlier instant. earlier / later: pick that instant (in a gap, the instant before or after the gap). reject: fail with 422.", "schema": { "description": "How to resolve a wall-clock time that falls in a DST gap or overlap (same meaning as in JavaScript Temporal). compatible: gap → shift forward by the gap length, overlap → earlier instant. earlier / later: pick that instant (in a gap, the instant before or after the gap). reject: fail with 422.", "type": "string", "enum": [ "compatible", "earlier", "later", "reject" ], "default": "compatible" } }, { "name": "zones", "in": "query", "required": false, "description": "Comma-separated (or JSON array) zones to show the instant in: IANA names, UTC, or fixed offsets such as +05:30. At most 20.", "style": "form", "explode": false, "schema": { "description": "Comma-separated (or JSON array) zones to show the instant in: IANA names, UTC, or fixed offsets such as +05:30. At most 20.", "type": "array", "items": { "type": "string" }, "default": "UTC" } }, { "name": "formats", "in": "query", "required": false, "description": "Extra renderings added to each zone's formatted map: rfc2822 (Tue, 13 Oct 2026 14:30:00 +0200), http (HTTP-date, always GMT), sql (2026-10-13 14:30:00.000 +02:00), iso_basic (20261013T143000+0200), iso_week_date (2026-W42-2), iso_ordinal (2026-286), human (Tuesday, October 13, 2026 at 2:30:00 PM GMT+2).", "style": "form", "explode": false, "schema": { "description": "Extra renderings added to each zone's formatted map: rfc2822 (Tue, 13 Oct 2026 14:30:00 +0200), http (HTTP-date, always GMT), sql (2026-10-13 14:30:00.000 +02:00), iso_basic (20261013T143000+0200), iso_week_date (2026-W42-2), iso_ordinal (2026-286), human (Tuesday, October 13, 2026 at 2:30:00 PM GMT+2).", "type": "array", "items": { "type": "string", "enum": [ "rfc2822", "http", "sql", "iso_basic", "iso_week_date", "iso_ordinal", "human" ] } } }, { "name": "pattern", "in": "query", "required": false, "description": "Custom format using Luxon tokens (e.g. yyyy-MM-dd HH:mm ZZZZ; quote literal text in single quotes). Added to formatted.pattern. English names.", "schema": { "description": "Custom format using Luxon tokens (e.g. yyyy-MM-dd HH:mm ZZZZ; quote literal text in single quotes). Added to formatted.pattern. English names.", "type": "string" } }, { "name": "format", "in": "query", "required": false, "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "schema": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } } ] }, "post": { "summary": "Parse a date-time or Unix timestamp and show it in other zones and formats.", "description": "Parses `input` and returns the instant in UTC, as Unix seconds and milliseconds, and in each zone of `zones`. The response says exactly how the input was read: the detected format, the inferred timestamp unit (with what the other units would have meant), and, for a wall-clock time without an offset, the zone used and whether that local time was unique, skipped by a DST gap, or repeated in a DST overlap.\n\nPrivacy: The server receives the date-time string and zone names, converts them in memory, and returns the result. Your input is not stored or logged; only the per-call metadata row (operation, time, status, sizes) is recorded.", "tags": [ "time" ], "responses": { "200": { "description": "Success. With format=text, text/plain is returned instead of JSON.", "content": { "application/json": { "schema": { "type": "object", "description": "", "properties": { "input": { "type": "object", "description": "", "properties": { "input": { "type": "string", "description": "The input as received (trimmed)." }, "format": { "type": "string", "description": "How the input was parsed.", "enum": [ "now", "iso8601", "rfc2822", "http-date", "unix" ] }, "unit": { "type": [ "string", "null" ], "description": "Unit of a Unix timestamp (`seconds`, `milliseconds`, `microseconds`, `nanoseconds`); null for other formats." }, "unit_auto_detected": { "type": "boolean", "description": "True when the timestamp unit was inferred from its magnitude." }, "has_offset": { "type": "boolean", "description": "False when the input was a wall-clock time without a UTC offset, resolved in `local_zone`." }, "local_zone": { "type": [ "string", "null" ], "description": "Zone used to resolve a wall-clock input; null otherwise." }, "local_time": { "type": [ "string", "null" ], "description": "For wall-clock input: `unique`, `gap` (did not exist; DST jump forward) or `overlap` (occurred twice; DST jump back). Null otherwise." }, "notes": { "type": "array", "items": { "type": "string", "description": "Plain-language note." }, "description": "Every assumption made: auto-detected units and their alternatives, the zone used for wall-clock input, DST resolution, truncated precision." } }, "required": [ "input", "format", "unit", "unit_auto_detected", "has_offset", "local_zone", "local_time", "notes" ], "additionalProperties": false }, "instant": { "type": "object", "description": "", "properties": { "utc": { "type": "string", "description": "The instant in UTC, ISO 8601 with `Z`." }, "unix_seconds": { "type": "integer", "description": "Whole seconds since 1970-01-01T00:00:00Z, rounded down (floor)." }, "unix_milliseconds": { "type": "integer", "description": "Milliseconds since 1970-01-01T00:00:00Z." } }, "required": [ "utc", "unix_seconds", "unix_milliseconds" ], "additionalProperties": false }, "zones": { "type": "array", "items": { "type": "object", "description": "", "properties": { "zone": { "type": "string", "description": "Zone name as resolved: IANA name (letter case corrected), `UTC`, or `UTC±HH:MM`." }, "iso": { "type": "string", "description": "ISO 8601 / RFC 3339 with the UTC offset (`Z` for UTC). Milliseconds appear only when non-zero." }, "local": { "type": "string", "description": "Wall-clock date-time in the zone without an offset, `YYYY-MM-DDTHH:mm:ss[.SSS]`." }, "date": { "type": "string", "description": "Local calendar date, `YYYY-MM-DD`." }, "time": { "type": "string", "description": "Local time, `HH:mm:ss` (24-hour), with `.SSS` only when milliseconds are non-zero." }, "offset": { "type": "string", "description": "UTC offset, `±HH:MM`." }, "offset_minutes": { "type": "integer", "description": "UTC offset in minutes (east positive), e.g. -240 for UTC-04:00." }, "abbreviation": { "type": "string", "description": "Short zone name as Intl (en-US) prints it: `EDT`, `PST`, or `GMT+2` where English has no common abbreviation." }, "offset_name": { "type": "string", "description": "Long zone name, e.g. `Eastern Daylight Time`." }, "dst": { "type": "boolean", "description": "True when daylight saving time is in effect at this instant." }, "weekday": { "type": "string", "description": "English weekday name, e.g. `Tuesday`." }, "weekday_number": { "type": "integer", "description": "ISO 8601 weekday: 1 = Monday … 7 = Sunday.", "minimum": 1, "maximum": 7 }, "iso_week": { "type": "string", "description": "ISO 8601 week, `YYYY-Www` (the week-numbering year can differ from the calendar year near 1 January)." }, "iso_week_year": { "type": "integer", "description": "ISO 8601 week-numbering year." }, "iso_week_number": { "type": "integer", "description": "ISO 8601 week number, 1-53.", "minimum": 1, "maximum": 53 }, "day_of_year": { "type": "integer", "description": "Ordinal day of the year, 1-366.", "minimum": 1, "maximum": 366 }, "formatted": { "type": "object", "description": "Extra renderings requested with `formats` (keyed by format name) and `pattern` (key `pattern`). Empty when none were requested.", "additionalProperties": { "type": "string", "description": "The time in that format." } } }, "required": [ "zone", "iso", "local", "date", "time", "offset", "offset_minutes", "abbreviation", "offset_name", "dst", "weekday", "weekday_number", "iso_week", "iso_week_year", "iso_week_number", "day_of_year", "formatted" ], "additionalProperties": false }, "description": "One entry per requested zone, in request order." }, "warnings": { "type": "array", "items": { "type": "string", "description": "Plain-language warning." }, "description": "Warnings about the zones given (fixed offsets, legacy or inverted names)." } }, "required": [ "input", "instant", "zones", "warnings" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "The ISO 8601 time in each requested zone, one per line." } } } }, "400": { "description": "missing_parameter / unknown_parameter / A zone is unknown or an abbreviation, or `unit` is given for non-numeric input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`input` is not a recognised format, is an impossible date (`2026-02-30`), is outside ±8.64e15 ms of 1970, has no offset and no `from_zone`, or falls in a DST gap/overlap with `disambiguation=reject`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "time_convert", "parameters": [ { "name": "format", "in": "query", "required": false, "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "schema": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "input": { "description": "ISO 8601 / RFC 3339 (2026-10-13T14:30:00Z, 2026-10-13T14:30:00+02:00, 2026-10-13 14:30, 2026-10-13, 2026-W42-2, with an optional RFC 9557 [Zone/Name] suffix), RFC 2822, HTTP-date (IMF-fixdate, RFC 850, asctime), a Unix timestamp (seconds, milliseconds, microseconds or nanoseconds; decimals allowed), or now.", "type": "string" }, "unit": { "description": "Unit of a numeric Unix timestamp. auto infers it from the magnitude: below 10^11 seconds, below 10^14 milliseconds, below 10^17 microseconds, otherwise nanoseconds. Only valid with numeric input.", "type": "string", "enum": [ "auto", "seconds", "milliseconds", "microseconds", "nanoseconds" ], "default": "auto" }, "from_zone": { "description": "Zone in which to read an input that has no UTC offset (2026-03-08T02:30). Required for such input; ignored when the input carries an offset or a Unix timestamp.", "type": "string" }, "disambiguation": { "description": "How to resolve a wall-clock time that falls in a DST gap or overlap (same meaning as in JavaScript Temporal). compatible: gap → shift forward by the gap length, overlap → earlier instant. earlier / later: pick that instant (in a gap, the instant before or after the gap). reject: fail with 422.", "type": "string", "enum": [ "compatible", "earlier", "later", "reject" ], "default": "compatible" }, "zones": { "description": "Comma-separated (or JSON array) zones to show the instant in: IANA names, UTC, or fixed offsets such as +05:30. At most 20.", "type": "array", "items": { "type": "string" }, "default": "UTC" }, "formats": { "description": "Extra renderings added to each zone's formatted map: rfc2822 (Tue, 13 Oct 2026 14:30:00 +0200), http (HTTP-date, always GMT), sql (2026-10-13 14:30:00.000 +02:00), iso_basic (20261013T143000+0200), iso_week_date (2026-W42-2), iso_ordinal (2026-286), human (Tuesday, October 13, 2026 at 2:30:00 PM GMT+2).", "type": "array", "items": { "type": "string", "enum": [ "rfc2822", "http", "sql", "iso_basic", "iso_week_date", "iso_ordinal", "human" ] } }, "pattern": { "description": "Custom format using Luxon tokens (e.g. yyyy-MM-dd HH:mm ZZZZ; quote literal text in single quotes). Added to formatted.pattern. English names.", "type": "string" }, "format": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } }, "required": [ "input" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "The body is used as the `input` parameter." } } } } } }, "/api/time/diff": { "get": { "summary": "Elapsed time and calendar difference between two instants, DST-aware.", "description": "Computes `end` minus `start`. `total` is exact elapsed time (a day is 86,400,000 ms). `calendar` is the breakdown in years, months, days, hours, minutes, seconds and milliseconds as a calendar in `zone` sees it, counted forward from the earlier instant: adding it to the earlier instant with `time_add` in the same zone gives the later instant exactly. Across a DST change the two differ: 12:00 to 12:00 the next day is `P1D` on the calendar but 23 or 25 hours elapsed. `calendar_days` counts midnights crossed in `zone`.\n\nPrivacy: The server receives the two date-time strings and the zone name, computes the difference in memory, and returns it. Your input is not stored or logged; only the per-call metadata row (operation, time, status, sizes) is recorded.", "tags": [ "time" ], "responses": { "200": { "description": "Success. With format=text, text/plain is returned instead of JSON.", "content": { "application/json": { "schema": { "type": "object", "description": "", "properties": { "start": { "type": "object", "description": "", "properties": { "interpretation": { "type": "object", "description": "", "properties": { "input": { "type": "string", "description": "The input as received (trimmed)." }, "format": { "type": "string", "description": "How the input was parsed.", "enum": [ "now", "iso8601", "rfc2822", "http-date", "unix" ] }, "unit": { "type": [ "string", "null" ], "description": "Unit of a Unix timestamp (`seconds`, `milliseconds`, `microseconds`, `nanoseconds`); null for other formats." }, "unit_auto_detected": { "type": "boolean", "description": "True when the timestamp unit was inferred from its magnitude." }, "has_offset": { "type": "boolean", "description": "False when the input was a wall-clock time without a UTC offset, resolved in `local_zone`." }, "local_zone": { "type": [ "string", "null" ], "description": "Zone used to resolve a wall-clock input; null otherwise." }, "local_time": { "type": [ "string", "null" ], "description": "For wall-clock input: `unique`, `gap` (did not exist; DST jump forward) or `overlap` (occurred twice; DST jump back). Null otherwise." }, "notes": { "type": "array", "items": { "type": "string", "description": "Plain-language note." }, "description": "Every assumption made: auto-detected units and their alternatives, the zone used for wall-clock input, DST resolution, truncated precision." } }, "required": [ "input", "format", "unit", "unit_auto_detected", "has_offset", "local_zone", "local_time", "notes" ], "additionalProperties": false }, "instant": { "type": "object", "description": "", "properties": { "utc": { "type": "string", "description": "The instant in UTC, ISO 8601 with `Z`." }, "unix_seconds": { "type": "integer", "description": "Whole seconds since 1970-01-01T00:00:00Z, rounded down (floor)." }, "unix_milliseconds": { "type": "integer", "description": "Milliseconds since 1970-01-01T00:00:00Z." } }, "required": [ "utc", "unix_seconds", "unix_milliseconds" ], "additionalProperties": false }, "local": { "type": "object", "description": "The start instant in `zone`.", "properties": { "zone": { "type": "string", "description": "Zone name as resolved: IANA name (letter case corrected), `UTC`, or `UTC±HH:MM`." }, "iso": { "type": "string", "description": "ISO 8601 / RFC 3339 with the UTC offset (`Z` for UTC). Milliseconds appear only when non-zero." }, "local": { "type": "string", "description": "Wall-clock date-time in the zone without an offset, `YYYY-MM-DDTHH:mm:ss[.SSS]`." }, "date": { "type": "string", "description": "Local calendar date, `YYYY-MM-DD`." }, "time": { "type": "string", "description": "Local time, `HH:mm:ss` (24-hour), with `.SSS` only when milliseconds are non-zero." }, "offset": { "type": "string", "description": "UTC offset, `±HH:MM`." }, "offset_minutes": { "type": "integer", "description": "UTC offset in minutes (east positive), e.g. -240 for UTC-04:00." }, "abbreviation": { "type": "string", "description": "Short zone name as Intl (en-US) prints it: `EDT`, `PST`, or `GMT+2` where English has no common abbreviation." }, "offset_name": { "type": "string", "description": "Long zone name, e.g. `Eastern Daylight Time`." }, "dst": { "type": "boolean", "description": "True when daylight saving time is in effect at this instant." }, "weekday": { "type": "string", "description": "English weekday name, e.g. `Tuesday`." }, "weekday_number": { "type": "integer", "description": "ISO 8601 weekday: 1 = Monday … 7 = Sunday.", "minimum": 1, "maximum": 7 }, "iso_week": { "type": "string", "description": "ISO 8601 week, `YYYY-Www` (the week-numbering year can differ from the calendar year near 1 January)." }, "iso_week_year": { "type": "integer", "description": "ISO 8601 week-numbering year." }, "iso_week_number": { "type": "integer", "description": "ISO 8601 week number, 1-53.", "minimum": 1, "maximum": 53 }, "day_of_year": { "type": "integer", "description": "Ordinal day of the year, 1-366.", "minimum": 1, "maximum": 366 }, "formatted": { "type": "object", "description": "Extra renderings requested with `formats` (keyed by format name) and `pattern` (key `pattern`). Empty when none were requested.", "additionalProperties": { "type": "string", "description": "The time in that format." } } }, "required": [ "zone", "iso", "local", "date", "time", "offset", "offset_minutes", "abbreviation", "offset_name", "dst", "weekday", "weekday_number", "iso_week", "iso_week_year", "iso_week_number", "day_of_year", "formatted" ], "additionalProperties": false } }, "required": [ "interpretation", "instant", "local" ], "additionalProperties": false }, "end": { "type": "object", "description": "", "properties": { "interpretation": { "type": "object", "description": "", "properties": { "input": { "type": "string", "description": "The input as received (trimmed)." }, "format": { "type": "string", "description": "How the input was parsed.", "enum": [ "now", "iso8601", "rfc2822", "http-date", "unix" ] }, "unit": { "type": [ "string", "null" ], "description": "Unit of a Unix timestamp (`seconds`, `milliseconds`, `microseconds`, `nanoseconds`); null for other formats." }, "unit_auto_detected": { "type": "boolean", "description": "True when the timestamp unit was inferred from its magnitude." }, "has_offset": { "type": "boolean", "description": "False when the input was a wall-clock time without a UTC offset, resolved in `local_zone`." }, "local_zone": { "type": [ "string", "null" ], "description": "Zone used to resolve a wall-clock input; null otherwise." }, "local_time": { "type": [ "string", "null" ], "description": "For wall-clock input: `unique`, `gap` (did not exist; DST jump forward) or `overlap` (occurred twice; DST jump back). Null otherwise." }, "notes": { "type": "array", "items": { "type": "string", "description": "Plain-language note." }, "description": "Every assumption made: auto-detected units and their alternatives, the zone used for wall-clock input, DST resolution, truncated precision." } }, "required": [ "input", "format", "unit", "unit_auto_detected", "has_offset", "local_zone", "local_time", "notes" ], "additionalProperties": false }, "instant": { "type": "object", "description": "", "properties": { "utc": { "type": "string", "description": "The instant in UTC, ISO 8601 with `Z`." }, "unix_seconds": { "type": "integer", "description": "Whole seconds since 1970-01-01T00:00:00Z, rounded down (floor)." }, "unix_milliseconds": { "type": "integer", "description": "Milliseconds since 1970-01-01T00:00:00Z." } }, "required": [ "utc", "unix_seconds", "unix_milliseconds" ], "additionalProperties": false }, "local": { "type": "object", "description": "The end instant in `zone`.", "properties": { "zone": { "type": "string", "description": "Zone name as resolved: IANA name (letter case corrected), `UTC`, or `UTC±HH:MM`." }, "iso": { "type": "string", "description": "ISO 8601 / RFC 3339 with the UTC offset (`Z` for UTC). Milliseconds appear only when non-zero." }, "local": { "type": "string", "description": "Wall-clock date-time in the zone without an offset, `YYYY-MM-DDTHH:mm:ss[.SSS]`." }, "date": { "type": "string", "description": "Local calendar date, `YYYY-MM-DD`." }, "time": { "type": "string", "description": "Local time, `HH:mm:ss` (24-hour), with `.SSS` only when milliseconds are non-zero." }, "offset": { "type": "string", "description": "UTC offset, `±HH:MM`." }, "offset_minutes": { "type": "integer", "description": "UTC offset in minutes (east positive), e.g. -240 for UTC-04:00." }, "abbreviation": { "type": "string", "description": "Short zone name as Intl (en-US) prints it: `EDT`, `PST`, or `GMT+2` where English has no common abbreviation." }, "offset_name": { "type": "string", "description": "Long zone name, e.g. `Eastern Daylight Time`." }, "dst": { "type": "boolean", "description": "True when daylight saving time is in effect at this instant." }, "weekday": { "type": "string", "description": "English weekday name, e.g. `Tuesday`." }, "weekday_number": { "type": "integer", "description": "ISO 8601 weekday: 1 = Monday … 7 = Sunday.", "minimum": 1, "maximum": 7 }, "iso_week": { "type": "string", "description": "ISO 8601 week, `YYYY-Www` (the week-numbering year can differ from the calendar year near 1 January)." }, "iso_week_year": { "type": "integer", "description": "ISO 8601 week-numbering year." }, "iso_week_number": { "type": "integer", "description": "ISO 8601 week number, 1-53.", "minimum": 1, "maximum": 53 }, "day_of_year": { "type": "integer", "description": "Ordinal day of the year, 1-366.", "minimum": 1, "maximum": 366 }, "formatted": { "type": "object", "description": "Extra renderings requested with `formats` (keyed by format name) and `pattern` (key `pattern`). Empty when none were requested.", "additionalProperties": { "type": "string", "description": "The time in that format." } } }, "required": [ "zone", "iso", "local", "date", "time", "offset", "offset_minutes", "abbreviation", "offset_name", "dst", "weekday", "weekday_number", "iso_week", "iso_week_year", "iso_week_number", "day_of_year", "formatted" ], "additionalProperties": false } }, "required": [ "interpretation", "instant", "local" ], "additionalProperties": false }, "zone": { "type": "string", "description": "Zone used for the calendar breakdown." }, "sign": { "type": "integer", "description": "1 when end is after start, -1 when before, 0 when equal.", "enum": [ -1, 0, 1 ] }, "direction": { "type": "string", "description": "`forward` (end after start), `backward`, or `same`.", "enum": [ "forward", "backward", "same" ] }, "total": { "type": "object", "description": "", "properties": { "milliseconds": { "type": "integer", "description": "Exact elapsed milliseconds, end - start (signed)." }, "seconds": { "type": "number", "description": "Elapsed seconds (signed, may be fractional)." }, "minutes": { "type": "number", "description": "Elapsed minutes (signed, may be fractional)." }, "hours": { "type": "number", "description": "Elapsed hours (signed, may be fractional)." }, "days": { "type": "number", "description": "Elapsed time in 24-hour days (signed, may be fractional)." }, "weeks": { "type": "number", "description": "Elapsed time in 7-day weeks (signed, may be fractional)." } }, "required": [ "milliseconds", "seconds", "minutes", "hours", "days", "weeks" ], "additionalProperties": false }, "calendar": { "type": "object", "description": "Calendar breakdown in `zone`, magnitudes only (see `sign`), from the earlier to the later instant.", "properties": { "years": { "type": "integer", "description": "Whole years.", "minimum": 0 }, "months": { "type": "integer", "description": "Whole months after the years, 0-11.", "minimum": 0, "maximum": 11 }, "days": { "type": "integer", "description": "Whole days after the months.", "minimum": 0 }, "hours": { "type": "integer", "description": "Hours after the days, 0-23 except across DST.", "minimum": 0 }, "minutes": { "type": "integer", "description": "Minutes, 0-59.", "minimum": 0, "maximum": 59 }, "seconds": { "type": "integer", "description": "Seconds, 0-59.", "minimum": 0, "maximum": 59 }, "milliseconds": { "type": "integer", "description": "Milliseconds, 0-999.", "minimum": 0, "maximum": 999 } }, "required": [ "years", "months", "days", "hours", "minutes", "seconds", "milliseconds" ], "additionalProperties": false }, "calendar_days": { "type": "integer", "description": "Signed difference between the two local calendar dates in `zone` (end date minus start date), ignoring time of day." }, "iso_duration": { "type": "string", "description": "The calendar breakdown as an ISO 8601 duration, prefixed with `-` when end is before start, e.g. `P1M2DT3H`, `-P1D`, `PT0S`." }, "iso_duration_exact": { "type": "string", "description": "Exact elapsed time as an ISO 8601 duration in hours, minutes and seconds only, e.g. `PT23H`." }, "human": { "type": "string", "description": "English summary of the calendar breakdown, e.g. `1 month, 2 days later`." }, "warnings": { "type": "array", "items": { "type": "string", "description": "Plain-language warning." }, "description": "Warnings about the zones given (fixed offsets, legacy or inverted names)." } }, "required": [ "start", "end", "zone", "sign", "direction", "total", "calendar", "calendar_days", "iso_duration", "iso_duration_exact", "human", "warnings" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "The calendar ISO 8601 duration (`iso_duration`)." } } } }, "400": { "description": "missing_parameter / unknown_parameter / `zone` is unknown or an abbreviation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`start` or `end` cannot be parsed, is out of range, or falls in a DST gap/overlap with `disambiguation=reject`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "time_diff_get", "parameters": [ { "name": "start", "in": "query", "required": true, "description": "Start instant. ISO 8601 / RFC 3339 (2026-10-13T14:30:00Z, 2026-10-13T14:30:00+02:00, 2026-10-13 14:30, 2026-10-13, 2026-W42-2, with an optional RFC 9557 [Zone/Name] suffix), RFC 2822, HTTP-date (IMF-fixdate, RFC 850, asctime), a Unix timestamp (seconds, milliseconds, microseconds or nanoseconds; decimals allowed), or now.", "schema": { "description": "Start instant. ISO 8601 / RFC 3339 (2026-10-13T14:30:00Z, 2026-10-13T14:30:00+02:00, 2026-10-13 14:30, 2026-10-13, 2026-W42-2, with an optional RFC 9557 [Zone/Name] suffix), RFC 2822, HTTP-date (IMF-fixdate, RFC 850, asctime), a Unix timestamp (seconds, milliseconds, microseconds or nanoseconds; decimals allowed), or now.", "type": "string" } }, { "name": "end", "in": "query", "required": true, "description": "End instant, same formats as start.", "schema": { "description": "End instant, same formats as start.", "type": "string" } }, { "name": "zone", "in": "query", "required": false, "description": "Zone for the calendar breakdown and calendar_days, and for reading start/end that have no UTC offset. IANA name, UTC, or fixed offset.", "schema": { "description": "Zone for the calendar breakdown and calendar_days, and for reading start/end that have no UTC offset. IANA name, UTC, or fixed offset.", "type": "string", "default": "UTC" } }, { "name": "unit", "in": "query", "required": false, "description": "Unit of a numeric Unix timestamp. auto infers it from the magnitude: below 10^11 seconds, below 10^14 milliseconds, below 10^17 microseconds, otherwise nanoseconds. Only valid with numeric input.", "schema": { "description": "Unit of a numeric Unix timestamp. auto infers it from the magnitude: below 10^11 seconds, below 10^14 milliseconds, below 10^17 microseconds, otherwise nanoseconds. Only valid with numeric input.", "type": "string", "enum": [ "auto", "seconds", "milliseconds", "microseconds", "nanoseconds" ], "default": "auto" } }, { "name": "disambiguation", "in": "query", "required": false, "description": "How to resolve a wall-clock time that falls in a DST gap or overlap (same meaning as in JavaScript Temporal). compatible: gap → shift forward by the gap length, overlap → earlier instant. earlier / later: pick that instant (in a gap, the instant before or after the gap). reject: fail with 422.", "schema": { "description": "How to resolve a wall-clock time that falls in a DST gap or overlap (same meaning as in JavaScript Temporal). compatible: gap → shift forward by the gap length, overlap → earlier instant. earlier / later: pick that instant (in a gap, the instant before or after the gap). reject: fail with 422.", "type": "string", "enum": [ "compatible", "earlier", "later", "reject" ], "default": "compatible" } }, { "name": "format", "in": "query", "required": false, "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "schema": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } } ] }, "post": { "summary": "Elapsed time and calendar difference between two instants, DST-aware.", "description": "Computes `end` minus `start`. `total` is exact elapsed time (a day is 86,400,000 ms). `calendar` is the breakdown in years, months, days, hours, minutes, seconds and milliseconds as a calendar in `zone` sees it, counted forward from the earlier instant: adding it to the earlier instant with `time_add` in the same zone gives the later instant exactly. Across a DST change the two differ: 12:00 to 12:00 the next day is `P1D` on the calendar but 23 or 25 hours elapsed. `calendar_days` counts midnights crossed in `zone`.\n\nPrivacy: The server receives the two date-time strings and the zone name, computes the difference in memory, and returns it. Your input is not stored or logged; only the per-call metadata row (operation, time, status, sizes) is recorded.", "tags": [ "time" ], "responses": { "200": { "description": "Success. With format=text, text/plain is returned instead of JSON.", "content": { "application/json": { "schema": { "type": "object", "description": "", "properties": { "start": { "type": "object", "description": "", "properties": { "interpretation": { "type": "object", "description": "", "properties": { "input": { "type": "string", "description": "The input as received (trimmed)." }, "format": { "type": "string", "description": "How the input was parsed.", "enum": [ "now", "iso8601", "rfc2822", "http-date", "unix" ] }, "unit": { "type": [ "string", "null" ], "description": "Unit of a Unix timestamp (`seconds`, `milliseconds`, `microseconds`, `nanoseconds`); null for other formats." }, "unit_auto_detected": { "type": "boolean", "description": "True when the timestamp unit was inferred from its magnitude." }, "has_offset": { "type": "boolean", "description": "False when the input was a wall-clock time without a UTC offset, resolved in `local_zone`." }, "local_zone": { "type": [ "string", "null" ], "description": "Zone used to resolve a wall-clock input; null otherwise." }, "local_time": { "type": [ "string", "null" ], "description": "For wall-clock input: `unique`, `gap` (did not exist; DST jump forward) or `overlap` (occurred twice; DST jump back). Null otherwise." }, "notes": { "type": "array", "items": { "type": "string", "description": "Plain-language note." }, "description": "Every assumption made: auto-detected units and their alternatives, the zone used for wall-clock input, DST resolution, truncated precision." } }, "required": [ "input", "format", "unit", "unit_auto_detected", "has_offset", "local_zone", "local_time", "notes" ], "additionalProperties": false }, "instant": { "type": "object", "description": "", "properties": { "utc": { "type": "string", "description": "The instant in UTC, ISO 8601 with `Z`." }, "unix_seconds": { "type": "integer", "description": "Whole seconds since 1970-01-01T00:00:00Z, rounded down (floor)." }, "unix_milliseconds": { "type": "integer", "description": "Milliseconds since 1970-01-01T00:00:00Z." } }, "required": [ "utc", "unix_seconds", "unix_milliseconds" ], "additionalProperties": false }, "local": { "type": "object", "description": "The start instant in `zone`.", "properties": { "zone": { "type": "string", "description": "Zone name as resolved: IANA name (letter case corrected), `UTC`, or `UTC±HH:MM`." }, "iso": { "type": "string", "description": "ISO 8601 / RFC 3339 with the UTC offset (`Z` for UTC). Milliseconds appear only when non-zero." }, "local": { "type": "string", "description": "Wall-clock date-time in the zone without an offset, `YYYY-MM-DDTHH:mm:ss[.SSS]`." }, "date": { "type": "string", "description": "Local calendar date, `YYYY-MM-DD`." }, "time": { "type": "string", "description": "Local time, `HH:mm:ss` (24-hour), with `.SSS` only when milliseconds are non-zero." }, "offset": { "type": "string", "description": "UTC offset, `±HH:MM`." }, "offset_minutes": { "type": "integer", "description": "UTC offset in minutes (east positive), e.g. -240 for UTC-04:00." }, "abbreviation": { "type": "string", "description": "Short zone name as Intl (en-US) prints it: `EDT`, `PST`, or `GMT+2` where English has no common abbreviation." }, "offset_name": { "type": "string", "description": "Long zone name, e.g. `Eastern Daylight Time`." }, "dst": { "type": "boolean", "description": "True when daylight saving time is in effect at this instant." }, "weekday": { "type": "string", "description": "English weekday name, e.g. `Tuesday`." }, "weekday_number": { "type": "integer", "description": "ISO 8601 weekday: 1 = Monday … 7 = Sunday.", "minimum": 1, "maximum": 7 }, "iso_week": { "type": "string", "description": "ISO 8601 week, `YYYY-Www` (the week-numbering year can differ from the calendar year near 1 January)." }, "iso_week_year": { "type": "integer", "description": "ISO 8601 week-numbering year." }, "iso_week_number": { "type": "integer", "description": "ISO 8601 week number, 1-53.", "minimum": 1, "maximum": 53 }, "day_of_year": { "type": "integer", "description": "Ordinal day of the year, 1-366.", "minimum": 1, "maximum": 366 }, "formatted": { "type": "object", "description": "Extra renderings requested with `formats` (keyed by format name) and `pattern` (key `pattern`). Empty when none were requested.", "additionalProperties": { "type": "string", "description": "The time in that format." } } }, "required": [ "zone", "iso", "local", "date", "time", "offset", "offset_minutes", "abbreviation", "offset_name", "dst", "weekday", "weekday_number", "iso_week", "iso_week_year", "iso_week_number", "day_of_year", "formatted" ], "additionalProperties": false } }, "required": [ "interpretation", "instant", "local" ], "additionalProperties": false }, "end": { "type": "object", "description": "", "properties": { "interpretation": { "type": "object", "description": "", "properties": { "input": { "type": "string", "description": "The input as received (trimmed)." }, "format": { "type": "string", "description": "How the input was parsed.", "enum": [ "now", "iso8601", "rfc2822", "http-date", "unix" ] }, "unit": { "type": [ "string", "null" ], "description": "Unit of a Unix timestamp (`seconds`, `milliseconds`, `microseconds`, `nanoseconds`); null for other formats." }, "unit_auto_detected": { "type": "boolean", "description": "True when the timestamp unit was inferred from its magnitude." }, "has_offset": { "type": "boolean", "description": "False when the input was a wall-clock time without a UTC offset, resolved in `local_zone`." }, "local_zone": { "type": [ "string", "null" ], "description": "Zone used to resolve a wall-clock input; null otherwise." }, "local_time": { "type": [ "string", "null" ], "description": "For wall-clock input: `unique`, `gap` (did not exist; DST jump forward) or `overlap` (occurred twice; DST jump back). Null otherwise." }, "notes": { "type": "array", "items": { "type": "string", "description": "Plain-language note." }, "description": "Every assumption made: auto-detected units and their alternatives, the zone used for wall-clock input, DST resolution, truncated precision." } }, "required": [ "input", "format", "unit", "unit_auto_detected", "has_offset", "local_zone", "local_time", "notes" ], "additionalProperties": false }, "instant": { "type": "object", "description": "", "properties": { "utc": { "type": "string", "description": "The instant in UTC, ISO 8601 with `Z`." }, "unix_seconds": { "type": "integer", "description": "Whole seconds since 1970-01-01T00:00:00Z, rounded down (floor)." }, "unix_milliseconds": { "type": "integer", "description": "Milliseconds since 1970-01-01T00:00:00Z." } }, "required": [ "utc", "unix_seconds", "unix_milliseconds" ], "additionalProperties": false }, "local": { "type": "object", "description": "The end instant in `zone`.", "properties": { "zone": { "type": "string", "description": "Zone name as resolved: IANA name (letter case corrected), `UTC`, or `UTC±HH:MM`." }, "iso": { "type": "string", "description": "ISO 8601 / RFC 3339 with the UTC offset (`Z` for UTC). Milliseconds appear only when non-zero." }, "local": { "type": "string", "description": "Wall-clock date-time in the zone without an offset, `YYYY-MM-DDTHH:mm:ss[.SSS]`." }, "date": { "type": "string", "description": "Local calendar date, `YYYY-MM-DD`." }, "time": { "type": "string", "description": "Local time, `HH:mm:ss` (24-hour), with `.SSS` only when milliseconds are non-zero." }, "offset": { "type": "string", "description": "UTC offset, `±HH:MM`." }, "offset_minutes": { "type": "integer", "description": "UTC offset in minutes (east positive), e.g. -240 for UTC-04:00." }, "abbreviation": { "type": "string", "description": "Short zone name as Intl (en-US) prints it: `EDT`, `PST`, or `GMT+2` where English has no common abbreviation." }, "offset_name": { "type": "string", "description": "Long zone name, e.g. `Eastern Daylight Time`." }, "dst": { "type": "boolean", "description": "True when daylight saving time is in effect at this instant." }, "weekday": { "type": "string", "description": "English weekday name, e.g. `Tuesday`." }, "weekday_number": { "type": "integer", "description": "ISO 8601 weekday: 1 = Monday … 7 = Sunday.", "minimum": 1, "maximum": 7 }, "iso_week": { "type": "string", "description": "ISO 8601 week, `YYYY-Www` (the week-numbering year can differ from the calendar year near 1 January)." }, "iso_week_year": { "type": "integer", "description": "ISO 8601 week-numbering year." }, "iso_week_number": { "type": "integer", "description": "ISO 8601 week number, 1-53.", "minimum": 1, "maximum": 53 }, "day_of_year": { "type": "integer", "description": "Ordinal day of the year, 1-366.", "minimum": 1, "maximum": 366 }, "formatted": { "type": "object", "description": "Extra renderings requested with `formats` (keyed by format name) and `pattern` (key `pattern`). Empty when none were requested.", "additionalProperties": { "type": "string", "description": "The time in that format." } } }, "required": [ "zone", "iso", "local", "date", "time", "offset", "offset_minutes", "abbreviation", "offset_name", "dst", "weekday", "weekday_number", "iso_week", "iso_week_year", "iso_week_number", "day_of_year", "formatted" ], "additionalProperties": false } }, "required": [ "interpretation", "instant", "local" ], "additionalProperties": false }, "zone": { "type": "string", "description": "Zone used for the calendar breakdown." }, "sign": { "type": "integer", "description": "1 when end is after start, -1 when before, 0 when equal.", "enum": [ -1, 0, 1 ] }, "direction": { "type": "string", "description": "`forward` (end after start), `backward`, or `same`.", "enum": [ "forward", "backward", "same" ] }, "total": { "type": "object", "description": "", "properties": { "milliseconds": { "type": "integer", "description": "Exact elapsed milliseconds, end - start (signed)." }, "seconds": { "type": "number", "description": "Elapsed seconds (signed, may be fractional)." }, "minutes": { "type": "number", "description": "Elapsed minutes (signed, may be fractional)." }, "hours": { "type": "number", "description": "Elapsed hours (signed, may be fractional)." }, "days": { "type": "number", "description": "Elapsed time in 24-hour days (signed, may be fractional)." }, "weeks": { "type": "number", "description": "Elapsed time in 7-day weeks (signed, may be fractional)." } }, "required": [ "milliseconds", "seconds", "minutes", "hours", "days", "weeks" ], "additionalProperties": false }, "calendar": { "type": "object", "description": "Calendar breakdown in `zone`, magnitudes only (see `sign`), from the earlier to the later instant.", "properties": { "years": { "type": "integer", "description": "Whole years.", "minimum": 0 }, "months": { "type": "integer", "description": "Whole months after the years, 0-11.", "minimum": 0, "maximum": 11 }, "days": { "type": "integer", "description": "Whole days after the months.", "minimum": 0 }, "hours": { "type": "integer", "description": "Hours after the days, 0-23 except across DST.", "minimum": 0 }, "minutes": { "type": "integer", "description": "Minutes, 0-59.", "minimum": 0, "maximum": 59 }, "seconds": { "type": "integer", "description": "Seconds, 0-59.", "minimum": 0, "maximum": 59 }, "milliseconds": { "type": "integer", "description": "Milliseconds, 0-999.", "minimum": 0, "maximum": 999 } }, "required": [ "years", "months", "days", "hours", "minutes", "seconds", "milliseconds" ], "additionalProperties": false }, "calendar_days": { "type": "integer", "description": "Signed difference between the two local calendar dates in `zone` (end date minus start date), ignoring time of day." }, "iso_duration": { "type": "string", "description": "The calendar breakdown as an ISO 8601 duration, prefixed with `-` when end is before start, e.g. `P1M2DT3H`, `-P1D`, `PT0S`." }, "iso_duration_exact": { "type": "string", "description": "Exact elapsed time as an ISO 8601 duration in hours, minutes and seconds only, e.g. `PT23H`." }, "human": { "type": "string", "description": "English summary of the calendar breakdown, e.g. `1 month, 2 days later`." }, "warnings": { "type": "array", "items": { "type": "string", "description": "Plain-language warning." }, "description": "Warnings about the zones given (fixed offsets, legacy or inverted names)." } }, "required": [ "start", "end", "zone", "sign", "direction", "total", "calendar", "calendar_days", "iso_duration", "iso_duration_exact", "human", "warnings" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "The calendar ISO 8601 duration (`iso_duration`)." } } } }, "400": { "description": "missing_parameter / unknown_parameter / `zone` is unknown or an abbreviation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`start` or `end` cannot be parsed, is out of range, or falls in a DST gap/overlap with `disambiguation=reject`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "time_diff", "parameters": [ { "name": "format", "in": "query", "required": false, "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "schema": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "start": { "description": "Start instant. ISO 8601 / RFC 3339 (2026-10-13T14:30:00Z, 2026-10-13T14:30:00+02:00, 2026-10-13 14:30, 2026-10-13, 2026-W42-2, with an optional RFC 9557 [Zone/Name] suffix), RFC 2822, HTTP-date (IMF-fixdate, RFC 850, asctime), a Unix timestamp (seconds, milliseconds, microseconds or nanoseconds; decimals allowed), or now.", "type": "string" }, "end": { "description": "End instant, same formats as start.", "type": "string" }, "zone": { "description": "Zone for the calendar breakdown and calendar_days, and for reading start/end that have no UTC offset. IANA name, UTC, or fixed offset.", "type": "string", "default": "UTC" }, "unit": { "description": "Unit of a numeric Unix timestamp. auto infers it from the magnitude: below 10^11 seconds, below 10^14 milliseconds, below 10^17 microseconds, otherwise nanoseconds. Only valid with numeric input.", "type": "string", "enum": [ "auto", "seconds", "milliseconds", "microseconds", "nanoseconds" ], "default": "auto" }, "disambiguation": { "description": "How to resolve a wall-clock time that falls in a DST gap or overlap (same meaning as in JavaScript Temporal). compatible: gap → shift forward by the gap length, overlap → earlier instant. earlier / later: pick that instant (in a gap, the instant before or after the gap). reject: fail with 422.", "type": "string", "enum": [ "compatible", "earlier", "later", "reject" ], "default": "compatible" }, "format": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } }, "required": [ "start", "end" ], "additionalProperties": false } } } } } }, "/api/time/add": { "get": { "summary": "Add or subtract an ISO 8601 duration to an instant, calendar-aware in a time zone.", "description": "Applies the duration the way JavaScript Temporal does (`ZonedDateTime.add`): years, months, weeks and days move the wall-clock date in `zone` and keep the wall-clock time, so `P1D` across a DST change lands at the same local time (23 or 25 hours later); a day of the month that does not exist is clamped to the last day (Jan 31 + `P1M` = Feb 28/29); then hours, minutes, seconds and milliseconds are added as exact elapsed time (`PT24H` is always 86,400 s). If the intermediate wall-clock time falls in a DST gap or overlap it is resolved with `disambiguation` and reported in `notes`.\n\nPrivacy: The server receives the date-time, duration and zone name, computes the result in memory, and returns it. Your input is not stored or logged; only the per-call metadata row (operation, time, status, sizes) is recorded.", "tags": [ "time" ], "responses": { "200": { "description": "Success. With format=text, text/plain is returned instead of JSON.", "content": { "application/json": { "schema": { "type": "object", "description": "", "properties": { "start": { "type": "object", "description": "", "properties": { "interpretation": { "type": "object", "description": "", "properties": { "input": { "type": "string", "description": "The input as received (trimmed)." }, "format": { "type": "string", "description": "How the input was parsed.", "enum": [ "now", "iso8601", "rfc2822", "http-date", "unix" ] }, "unit": { "type": [ "string", "null" ], "description": "Unit of a Unix timestamp (`seconds`, `milliseconds`, `microseconds`, `nanoseconds`); null for other formats." }, "unit_auto_detected": { "type": "boolean", "description": "True when the timestamp unit was inferred from its magnitude." }, "has_offset": { "type": "boolean", "description": "False when the input was a wall-clock time without a UTC offset, resolved in `local_zone`." }, "local_zone": { "type": [ "string", "null" ], "description": "Zone used to resolve a wall-clock input; null otherwise." }, "local_time": { "type": [ "string", "null" ], "description": "For wall-clock input: `unique`, `gap` (did not exist; DST jump forward) or `overlap` (occurred twice; DST jump back). Null otherwise." }, "notes": { "type": "array", "items": { "type": "string", "description": "Plain-language note." }, "description": "Every assumption made: auto-detected units and their alternatives, the zone used for wall-clock input, DST resolution, truncated precision." } }, "required": [ "input", "format", "unit", "unit_auto_detected", "has_offset", "local_zone", "local_time", "notes" ], "additionalProperties": false }, "instant": { "type": "object", "description": "", "properties": { "utc": { "type": "string", "description": "The instant in UTC, ISO 8601 with `Z`." }, "unix_seconds": { "type": "integer", "description": "Whole seconds since 1970-01-01T00:00:00Z, rounded down (floor)." }, "unix_milliseconds": { "type": "integer", "description": "Milliseconds since 1970-01-01T00:00:00Z." } }, "required": [ "utc", "unix_seconds", "unix_milliseconds" ], "additionalProperties": false }, "local": { "type": "object", "description": "The start instant in `zone`.", "properties": { "zone": { "type": "string", "description": "Zone name as resolved: IANA name (letter case corrected), `UTC`, or `UTC±HH:MM`." }, "iso": { "type": "string", "description": "ISO 8601 / RFC 3339 with the UTC offset (`Z` for UTC). Milliseconds appear only when non-zero." }, "local": { "type": "string", "description": "Wall-clock date-time in the zone without an offset, `YYYY-MM-DDTHH:mm:ss[.SSS]`." }, "date": { "type": "string", "description": "Local calendar date, `YYYY-MM-DD`." }, "time": { "type": "string", "description": "Local time, `HH:mm:ss` (24-hour), with `.SSS` only when milliseconds are non-zero." }, "offset": { "type": "string", "description": "UTC offset, `±HH:MM`." }, "offset_minutes": { "type": "integer", "description": "UTC offset in minutes (east positive), e.g. -240 for UTC-04:00." }, "abbreviation": { "type": "string", "description": "Short zone name as Intl (en-US) prints it: `EDT`, `PST`, or `GMT+2` where English has no common abbreviation." }, "offset_name": { "type": "string", "description": "Long zone name, e.g. `Eastern Daylight Time`." }, "dst": { "type": "boolean", "description": "True when daylight saving time is in effect at this instant." }, "weekday": { "type": "string", "description": "English weekday name, e.g. `Tuesday`." }, "weekday_number": { "type": "integer", "description": "ISO 8601 weekday: 1 = Monday … 7 = Sunday.", "minimum": 1, "maximum": 7 }, "iso_week": { "type": "string", "description": "ISO 8601 week, `YYYY-Www` (the week-numbering year can differ from the calendar year near 1 January)." }, "iso_week_year": { "type": "integer", "description": "ISO 8601 week-numbering year." }, "iso_week_number": { "type": "integer", "description": "ISO 8601 week number, 1-53.", "minimum": 1, "maximum": 53 }, "day_of_year": { "type": "integer", "description": "Ordinal day of the year, 1-366.", "minimum": 1, "maximum": 366 }, "formatted": { "type": "object", "description": "Extra renderings requested with `formats` (keyed by format name) and `pattern` (key `pattern`). Empty when none were requested.", "additionalProperties": { "type": "string", "description": "The time in that format." } } }, "required": [ "zone", "iso", "local", "date", "time", "offset", "offset_minutes", "abbreviation", "offset_name", "dst", "weekday", "weekday_number", "iso_week", "iso_week_year", "iso_week_number", "day_of_year", "formatted" ], "additionalProperties": false } }, "required": [ "interpretation", "instant", "local" ], "additionalProperties": false }, "duration": { "type": "object", "description": "", "properties": { "iso": { "type": "string", "description": "The duration applied, normalised ISO 8601 (sign included; `subtract` folded in)." }, "sign": { "type": "integer", "description": "1 to add, -1 to subtract.", "enum": [ -1, 1 ] }, "years": { "type": "integer", "description": "Years (magnitude).", "minimum": 0 }, "months": { "type": "integer", "description": "Months (magnitude).", "minimum": 0 }, "weeks": { "type": "integer", "description": "Weeks (magnitude).", "minimum": 0 }, "days": { "type": "integer", "description": "Days (magnitude).", "minimum": 0 }, "hours": { "type": "integer", "description": "Hours (magnitude).", "minimum": 0 }, "minutes": { "type": "integer", "description": "Minutes (magnitude).", "minimum": 0 }, "seconds": { "type": "integer", "description": "Seconds (magnitude).", "minimum": 0 }, "milliseconds": { "type": "integer", "description": "Milliseconds (magnitude).", "minimum": 0 } }, "required": [ "iso", "sign", "years", "months", "weeks", "days", "hours", "minutes", "seconds", "milliseconds" ], "additionalProperties": false }, "zone": { "type": "string", "description": "Zone used." }, "result": { "type": "object", "description": "", "properties": { "instant": { "type": "object", "description": "", "properties": { "utc": { "type": "string", "description": "The instant in UTC, ISO 8601 with `Z`." }, "unix_seconds": { "type": "integer", "description": "Whole seconds since 1970-01-01T00:00:00Z, rounded down (floor)." }, "unix_milliseconds": { "type": "integer", "description": "Milliseconds since 1970-01-01T00:00:00Z." } }, "required": [ "utc", "unix_seconds", "unix_milliseconds" ], "additionalProperties": false }, "local": { "type": "object", "description": "The result in `zone`.", "properties": { "zone": { "type": "string", "description": "Zone name as resolved: IANA name (letter case corrected), `UTC`, or `UTC±HH:MM`." }, "iso": { "type": "string", "description": "ISO 8601 / RFC 3339 with the UTC offset (`Z` for UTC). Milliseconds appear only when non-zero." }, "local": { "type": "string", "description": "Wall-clock date-time in the zone without an offset, `YYYY-MM-DDTHH:mm:ss[.SSS]`." }, "date": { "type": "string", "description": "Local calendar date, `YYYY-MM-DD`." }, "time": { "type": "string", "description": "Local time, `HH:mm:ss` (24-hour), with `.SSS` only when milliseconds are non-zero." }, "offset": { "type": "string", "description": "UTC offset, `±HH:MM`." }, "offset_minutes": { "type": "integer", "description": "UTC offset in minutes (east positive), e.g. -240 for UTC-04:00." }, "abbreviation": { "type": "string", "description": "Short zone name as Intl (en-US) prints it: `EDT`, `PST`, or `GMT+2` where English has no common abbreviation." }, "offset_name": { "type": "string", "description": "Long zone name, e.g. `Eastern Daylight Time`." }, "dst": { "type": "boolean", "description": "True when daylight saving time is in effect at this instant." }, "weekday": { "type": "string", "description": "English weekday name, e.g. `Tuesday`." }, "weekday_number": { "type": "integer", "description": "ISO 8601 weekday: 1 = Monday … 7 = Sunday.", "minimum": 1, "maximum": 7 }, "iso_week": { "type": "string", "description": "ISO 8601 week, `YYYY-Www` (the week-numbering year can differ from the calendar year near 1 January)." }, "iso_week_year": { "type": "integer", "description": "ISO 8601 week-numbering year." }, "iso_week_number": { "type": "integer", "description": "ISO 8601 week number, 1-53.", "minimum": 1, "maximum": 53 }, "day_of_year": { "type": "integer", "description": "Ordinal day of the year, 1-366.", "minimum": 1, "maximum": 366 }, "formatted": { "type": "object", "description": "Extra renderings requested with `formats` (keyed by format name) and `pattern` (key `pattern`). Empty when none were requested.", "additionalProperties": { "type": "string", "description": "The time in that format." } } }, "required": [ "zone", "iso", "local", "date", "time", "offset", "offset_minutes", "abbreviation", "offset_name", "dst", "weekday", "weekday_number", "iso_week", "iso_week_year", "iso_week_number", "day_of_year", "formatted" ], "additionalProperties": false } }, "required": [ "instant", "local" ], "additionalProperties": false }, "elapsed_milliseconds": { "type": "integer", "description": "Exact elapsed time from start to result (signed)." }, "local_time": { "type": [ "string", "null" ], "description": "Status of the wall-clock time reached by the calendar part: `unique`, `gap` or `overlap`; null when the duration has no calendar part." }, "notes": { "type": "array", "items": { "type": "string", "description": "Plain-language note." }, "description": "What happened: day-of-month clamping, DST offset changes, gap/overlap resolution." }, "warnings": { "type": "array", "items": { "type": "string", "description": "Plain-language warning." }, "description": "Warnings about the zones given (fixed offsets, legacy or inverted names)." } }, "required": [ "start", "duration", "zone", "result", "elapsed_milliseconds", "local_time", "notes", "warnings" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "The result as ISO 8601 in `zone`." } } } }, "400": { "description": "missing_parameter / unknown_parameter / `zone` is unknown, both or neither of `duration` and `amount` are given, or `amount` lacks `amount_unit`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`input` or `duration` cannot be parsed (e.g. `P1.5D`), the result is out of range, or a gap/overlap is hit with `disambiguation=reject`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "time_add_get", "parameters": [ { "name": "input", "in": "query", "required": true, "description": "Start instant. ISO 8601 / RFC 3339 (2026-10-13T14:30:00Z, 2026-10-13T14:30:00+02:00, 2026-10-13 14:30, 2026-10-13, 2026-W42-2, with an optional RFC 9557 [Zone/Name] suffix), RFC 2822, HTTP-date (IMF-fixdate, RFC 850, asctime), a Unix timestamp (seconds, milliseconds, microseconds or nanoseconds; decimals allowed), or now.", "schema": { "description": "Start instant. ISO 8601 / RFC 3339 (2026-10-13T14:30:00Z, 2026-10-13T14:30:00+02:00, 2026-10-13 14:30, 2026-10-13, 2026-W42-2, with an optional RFC 9557 [Zone/Name] suffix), RFC 2822, HTTP-date (IMF-fixdate, RFC 850, asctime), a Unix timestamp (seconds, milliseconds, microseconds or nanoseconds; decimals allowed), or now.", "type": "string" } }, { "name": "duration", "in": "query", "required": false, "description": "ISO 8601 duration: P1D, PT36H, P1Y2M10DT2H30M, P2W, -P1M (negative subtracts), PT1.5H. Fractions only on the smallest of hours/minutes/seconds, to millisecond precision. Use either duration or amount + amount_unit.", "schema": { "description": "ISO 8601 duration: P1D, PT36H, P1Y2M10DT2H30M, P2W, -P1M (negative subtracts), PT1.5H. Fractions only on the smallest of hours/minutes/seconds, to millisecond precision. Use either duration or amount + amount_unit.", "type": "string" } }, { "name": "amount", "in": "query", "required": false, "description": "Signed whole number of amount_unit to add (negative subtracts). Alternative to duration.", "schema": { "description": "Signed whole number of amount_unit to add (negative subtracts). Alternative to duration.", "type": "integer" } }, { "name": "amount_unit", "in": "query", "required": false, "description": "Unit of amount. Required with amount.", "schema": { "description": "Unit of amount. Required with amount.", "type": "string", "enum": [ "years", "months", "weeks", "days", "hours", "minutes", "seconds", "milliseconds" ] } }, { "name": "subtract", "in": "query", "required": false, "description": "Subtract the duration instead of adding it (negates it).", "schema": { "description": "Subtract the duration instead of adding it (negates it).", "type": "boolean", "default": false } }, { "name": "zone", "in": "query", "required": false, "description": "Zone whose calendar and wall clock govern years/months/weeks/days, used for reading an input without offset, and for the output. The offset inside input does not choose the zone: pass America/New_York to get New York DST behaviour.", "schema": { "description": "Zone whose calendar and wall clock govern years/months/weeks/days, used for reading an input without offset, and for the output. The offset inside input does not choose the zone: pass America/New_York to get New York DST behaviour.", "type": "string", "default": "UTC" } }, { "name": "unit", "in": "query", "required": false, "description": "Unit of a numeric Unix timestamp. auto infers it from the magnitude: below 10^11 seconds, below 10^14 milliseconds, below 10^17 microseconds, otherwise nanoseconds. Only valid with numeric input.", "schema": { "description": "Unit of a numeric Unix timestamp. auto infers it from the magnitude: below 10^11 seconds, below 10^14 milliseconds, below 10^17 microseconds, otherwise nanoseconds. Only valid with numeric input.", "type": "string", "enum": [ "auto", "seconds", "milliseconds", "microseconds", "nanoseconds" ], "default": "auto" } }, { "name": "disambiguation", "in": "query", "required": false, "description": "How to resolve a wall-clock time that falls in a DST gap or overlap (same meaning as in JavaScript Temporal). compatible: gap → shift forward by the gap length, overlap → earlier instant. earlier / later: pick that instant (in a gap, the instant before or after the gap). reject: fail with 422.", "schema": { "description": "How to resolve a wall-clock time that falls in a DST gap or overlap (same meaning as in JavaScript Temporal). compatible: gap → shift forward by the gap length, overlap → earlier instant. earlier / later: pick that instant (in a gap, the instant before or after the gap). reject: fail with 422.", "type": "string", "enum": [ "compatible", "earlier", "later", "reject" ], "default": "compatible" } }, { "name": "format", "in": "query", "required": false, "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "schema": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } } ] }, "post": { "summary": "Add or subtract an ISO 8601 duration to an instant, calendar-aware in a time zone.", "description": "Applies the duration the way JavaScript Temporal does (`ZonedDateTime.add`): years, months, weeks and days move the wall-clock date in `zone` and keep the wall-clock time, so `P1D` across a DST change lands at the same local time (23 or 25 hours later); a day of the month that does not exist is clamped to the last day (Jan 31 + `P1M` = Feb 28/29); then hours, minutes, seconds and milliseconds are added as exact elapsed time (`PT24H` is always 86,400 s). If the intermediate wall-clock time falls in a DST gap or overlap it is resolved with `disambiguation` and reported in `notes`.\n\nPrivacy: The server receives the date-time, duration and zone name, computes the result in memory, and returns it. Your input is not stored or logged; only the per-call metadata row (operation, time, status, sizes) is recorded.", "tags": [ "time" ], "responses": { "200": { "description": "Success. With format=text, text/plain is returned instead of JSON.", "content": { "application/json": { "schema": { "type": "object", "description": "", "properties": { "start": { "type": "object", "description": "", "properties": { "interpretation": { "type": "object", "description": "", "properties": { "input": { "type": "string", "description": "The input as received (trimmed)." }, "format": { "type": "string", "description": "How the input was parsed.", "enum": [ "now", "iso8601", "rfc2822", "http-date", "unix" ] }, "unit": { "type": [ "string", "null" ], "description": "Unit of a Unix timestamp (`seconds`, `milliseconds`, `microseconds`, `nanoseconds`); null for other formats." }, "unit_auto_detected": { "type": "boolean", "description": "True when the timestamp unit was inferred from its magnitude." }, "has_offset": { "type": "boolean", "description": "False when the input was a wall-clock time without a UTC offset, resolved in `local_zone`." }, "local_zone": { "type": [ "string", "null" ], "description": "Zone used to resolve a wall-clock input; null otherwise." }, "local_time": { "type": [ "string", "null" ], "description": "For wall-clock input: `unique`, `gap` (did not exist; DST jump forward) or `overlap` (occurred twice; DST jump back). Null otherwise." }, "notes": { "type": "array", "items": { "type": "string", "description": "Plain-language note." }, "description": "Every assumption made: auto-detected units and their alternatives, the zone used for wall-clock input, DST resolution, truncated precision." } }, "required": [ "input", "format", "unit", "unit_auto_detected", "has_offset", "local_zone", "local_time", "notes" ], "additionalProperties": false }, "instant": { "type": "object", "description": "", "properties": { "utc": { "type": "string", "description": "The instant in UTC, ISO 8601 with `Z`." }, "unix_seconds": { "type": "integer", "description": "Whole seconds since 1970-01-01T00:00:00Z, rounded down (floor)." }, "unix_milliseconds": { "type": "integer", "description": "Milliseconds since 1970-01-01T00:00:00Z." } }, "required": [ "utc", "unix_seconds", "unix_milliseconds" ], "additionalProperties": false }, "local": { "type": "object", "description": "The start instant in `zone`.", "properties": { "zone": { "type": "string", "description": "Zone name as resolved: IANA name (letter case corrected), `UTC`, or `UTC±HH:MM`." }, "iso": { "type": "string", "description": "ISO 8601 / RFC 3339 with the UTC offset (`Z` for UTC). Milliseconds appear only when non-zero." }, "local": { "type": "string", "description": "Wall-clock date-time in the zone without an offset, `YYYY-MM-DDTHH:mm:ss[.SSS]`." }, "date": { "type": "string", "description": "Local calendar date, `YYYY-MM-DD`." }, "time": { "type": "string", "description": "Local time, `HH:mm:ss` (24-hour), with `.SSS` only when milliseconds are non-zero." }, "offset": { "type": "string", "description": "UTC offset, `±HH:MM`." }, "offset_minutes": { "type": "integer", "description": "UTC offset in minutes (east positive), e.g. -240 for UTC-04:00." }, "abbreviation": { "type": "string", "description": "Short zone name as Intl (en-US) prints it: `EDT`, `PST`, or `GMT+2` where English has no common abbreviation." }, "offset_name": { "type": "string", "description": "Long zone name, e.g. `Eastern Daylight Time`." }, "dst": { "type": "boolean", "description": "True when daylight saving time is in effect at this instant." }, "weekday": { "type": "string", "description": "English weekday name, e.g. `Tuesday`." }, "weekday_number": { "type": "integer", "description": "ISO 8601 weekday: 1 = Monday … 7 = Sunday.", "minimum": 1, "maximum": 7 }, "iso_week": { "type": "string", "description": "ISO 8601 week, `YYYY-Www` (the week-numbering year can differ from the calendar year near 1 January)." }, "iso_week_year": { "type": "integer", "description": "ISO 8601 week-numbering year." }, "iso_week_number": { "type": "integer", "description": "ISO 8601 week number, 1-53.", "minimum": 1, "maximum": 53 }, "day_of_year": { "type": "integer", "description": "Ordinal day of the year, 1-366.", "minimum": 1, "maximum": 366 }, "formatted": { "type": "object", "description": "Extra renderings requested with `formats` (keyed by format name) and `pattern` (key `pattern`). Empty when none were requested.", "additionalProperties": { "type": "string", "description": "The time in that format." } } }, "required": [ "zone", "iso", "local", "date", "time", "offset", "offset_minutes", "abbreviation", "offset_name", "dst", "weekday", "weekday_number", "iso_week", "iso_week_year", "iso_week_number", "day_of_year", "formatted" ], "additionalProperties": false } }, "required": [ "interpretation", "instant", "local" ], "additionalProperties": false }, "duration": { "type": "object", "description": "", "properties": { "iso": { "type": "string", "description": "The duration applied, normalised ISO 8601 (sign included; `subtract` folded in)." }, "sign": { "type": "integer", "description": "1 to add, -1 to subtract.", "enum": [ -1, 1 ] }, "years": { "type": "integer", "description": "Years (magnitude).", "minimum": 0 }, "months": { "type": "integer", "description": "Months (magnitude).", "minimum": 0 }, "weeks": { "type": "integer", "description": "Weeks (magnitude).", "minimum": 0 }, "days": { "type": "integer", "description": "Days (magnitude).", "minimum": 0 }, "hours": { "type": "integer", "description": "Hours (magnitude).", "minimum": 0 }, "minutes": { "type": "integer", "description": "Minutes (magnitude).", "minimum": 0 }, "seconds": { "type": "integer", "description": "Seconds (magnitude).", "minimum": 0 }, "milliseconds": { "type": "integer", "description": "Milliseconds (magnitude).", "minimum": 0 } }, "required": [ "iso", "sign", "years", "months", "weeks", "days", "hours", "minutes", "seconds", "milliseconds" ], "additionalProperties": false }, "zone": { "type": "string", "description": "Zone used." }, "result": { "type": "object", "description": "", "properties": { "instant": { "type": "object", "description": "", "properties": { "utc": { "type": "string", "description": "The instant in UTC, ISO 8601 with `Z`." }, "unix_seconds": { "type": "integer", "description": "Whole seconds since 1970-01-01T00:00:00Z, rounded down (floor)." }, "unix_milliseconds": { "type": "integer", "description": "Milliseconds since 1970-01-01T00:00:00Z." } }, "required": [ "utc", "unix_seconds", "unix_milliseconds" ], "additionalProperties": false }, "local": { "type": "object", "description": "The result in `zone`.", "properties": { "zone": { "type": "string", "description": "Zone name as resolved: IANA name (letter case corrected), `UTC`, or `UTC±HH:MM`." }, "iso": { "type": "string", "description": "ISO 8601 / RFC 3339 with the UTC offset (`Z` for UTC). Milliseconds appear only when non-zero." }, "local": { "type": "string", "description": "Wall-clock date-time in the zone without an offset, `YYYY-MM-DDTHH:mm:ss[.SSS]`." }, "date": { "type": "string", "description": "Local calendar date, `YYYY-MM-DD`." }, "time": { "type": "string", "description": "Local time, `HH:mm:ss` (24-hour), with `.SSS` only when milliseconds are non-zero." }, "offset": { "type": "string", "description": "UTC offset, `±HH:MM`." }, "offset_minutes": { "type": "integer", "description": "UTC offset in minutes (east positive), e.g. -240 for UTC-04:00." }, "abbreviation": { "type": "string", "description": "Short zone name as Intl (en-US) prints it: `EDT`, `PST`, or `GMT+2` where English has no common abbreviation." }, "offset_name": { "type": "string", "description": "Long zone name, e.g. `Eastern Daylight Time`." }, "dst": { "type": "boolean", "description": "True when daylight saving time is in effect at this instant." }, "weekday": { "type": "string", "description": "English weekday name, e.g. `Tuesday`." }, "weekday_number": { "type": "integer", "description": "ISO 8601 weekday: 1 = Monday … 7 = Sunday.", "minimum": 1, "maximum": 7 }, "iso_week": { "type": "string", "description": "ISO 8601 week, `YYYY-Www` (the week-numbering year can differ from the calendar year near 1 January)." }, "iso_week_year": { "type": "integer", "description": "ISO 8601 week-numbering year." }, "iso_week_number": { "type": "integer", "description": "ISO 8601 week number, 1-53.", "minimum": 1, "maximum": 53 }, "day_of_year": { "type": "integer", "description": "Ordinal day of the year, 1-366.", "minimum": 1, "maximum": 366 }, "formatted": { "type": "object", "description": "Extra renderings requested with `formats` (keyed by format name) and `pattern` (key `pattern`). Empty when none were requested.", "additionalProperties": { "type": "string", "description": "The time in that format." } } }, "required": [ "zone", "iso", "local", "date", "time", "offset", "offset_minutes", "abbreviation", "offset_name", "dst", "weekday", "weekday_number", "iso_week", "iso_week_year", "iso_week_number", "day_of_year", "formatted" ], "additionalProperties": false } }, "required": [ "instant", "local" ], "additionalProperties": false }, "elapsed_milliseconds": { "type": "integer", "description": "Exact elapsed time from start to result (signed)." }, "local_time": { "type": [ "string", "null" ], "description": "Status of the wall-clock time reached by the calendar part: `unique`, `gap` or `overlap`; null when the duration has no calendar part." }, "notes": { "type": "array", "items": { "type": "string", "description": "Plain-language note." }, "description": "What happened: day-of-month clamping, DST offset changes, gap/overlap resolution." }, "warnings": { "type": "array", "items": { "type": "string", "description": "Plain-language warning." }, "description": "Warnings about the zones given (fixed offsets, legacy or inverted names)." } }, "required": [ "start", "duration", "zone", "result", "elapsed_milliseconds", "local_time", "notes", "warnings" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "The result as ISO 8601 in `zone`." } } } }, "400": { "description": "missing_parameter / unknown_parameter / `zone` is unknown, both or neither of `duration` and `amount` are given, or `amount` lacks `amount_unit`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`input` or `duration` cannot be parsed (e.g. `P1.5D`), the result is out of range, or a gap/overlap is hit with `disambiguation=reject`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "time_add", "parameters": [ { "name": "format", "in": "query", "required": false, "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "schema": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "input": { "description": "Start instant. ISO 8601 / RFC 3339 (2026-10-13T14:30:00Z, 2026-10-13T14:30:00+02:00, 2026-10-13 14:30, 2026-10-13, 2026-W42-2, with an optional RFC 9557 [Zone/Name] suffix), RFC 2822, HTTP-date (IMF-fixdate, RFC 850, asctime), a Unix timestamp (seconds, milliseconds, microseconds or nanoseconds; decimals allowed), or now.", "type": "string" }, "duration": { "description": "ISO 8601 duration: P1D, PT36H, P1Y2M10DT2H30M, P2W, -P1M (negative subtracts), PT1.5H. Fractions only on the smallest of hours/minutes/seconds, to millisecond precision. Use either duration or amount + amount_unit.", "type": "string" }, "amount": { "description": "Signed whole number of amount_unit to add (negative subtracts). Alternative to duration.", "type": "integer" }, "amount_unit": { "description": "Unit of amount. Required with amount.", "type": "string", "enum": [ "years", "months", "weeks", "days", "hours", "minutes", "seconds", "milliseconds" ] }, "subtract": { "description": "Subtract the duration instead of adding it (negates it).", "type": "boolean", "default": false }, "zone": { "description": "Zone whose calendar and wall clock govern years/months/weeks/days, used for reading an input without offset, and for the output. The offset inside input does not choose the zone: pass America/New_York to get New York DST behaviour.", "type": "string", "default": "UTC" }, "unit": { "description": "Unit of a numeric Unix timestamp. auto infers it from the magnitude: below 10^11 seconds, below 10^14 milliseconds, below 10^17 microseconds, otherwise nanoseconds. Only valid with numeric input.", "type": "string", "enum": [ "auto", "seconds", "milliseconds", "microseconds", "nanoseconds" ], "default": "auto" }, "disambiguation": { "description": "How to resolve a wall-clock time that falls in a DST gap or overlap (same meaning as in JavaScript Temporal). compatible: gap → shift forward by the gap length, overlap → earlier instant. earlier / later: pick that instant (in a gap, the instant before or after the gap). reject: fail with 422.", "type": "string", "enum": [ "compatible", "earlier", "later", "reject" ], "default": "compatible" }, "format": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } }, "required": [ "input" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "The body is used as the `input` parameter." } } } } } }, "/api/cron/explain": { "get": { "summary": "Validate a cron expression, describe it in English, and list its next run times in a zone.", "description": "Accepts the 5-field crontab form (minute hour day-of-month month day-of-week), a 6-field form whose first field is seconds, and the macros @yearly, @annually, @monthly, @weekly, @daily, @midnight, @hourly. Returns an English description, a field-by-field breakdown with the expanded values, the day-matching rule in effect, and the next run times after `from` in `zone`. Day-of-month and day-of-week follow Vixie cron: when both are restricted a day matches if EITHER matches (`0 0 13 * 5` runs on every 13th AND every Friday); a field starting with `*` (such as `*/2`) counts as unrestricted, and then a day must match both. Errors name the offending field.\n\nPrivacy: The server receives the cron expression, zone and start time, evaluates them in memory, and returns the result. Your input is not stored or logged; only the per-call metadata row (operation, time, status, sizes) is recorded.", "tags": [ "cron" ], "responses": { "200": { "description": "Success. With format=text, text/plain is returned instead of JSON.", "content": { "application/json": { "schema": { "type": "object", "description": "", "properties": { "expression": { "type": "string", "description": "The expression with whitespace collapsed." }, "normalized": { "type": "string", "description": "5- or 6-field form actually evaluated (macros expanded)." }, "macro": { "type": [ "string", "null" ], "description": "The macro used, lower-cased (e.g. `@daily`), or null." }, "dialect": { "type": "string", "description": "`five-field` (standard crontab) or `six-field-seconds`.", "enum": [ "five-field", "six-field-seconds" ] }, "description": { "type": "string", "description": "English description from cronstrue, 24-hour clock. For the day fields, `day_rule` is authoritative." }, "day_rule": { "type": "object", "description": "", "properties": { "rule": { "type": "string", "description": "How days are selected: `every-day`, `day-of-month` only, `day-of-week` only, `either` (OR: both restricted), or `both` (AND: one starts with `*` but still narrows).", "enum": [ "every-day", "day-of-month", "day-of-week", "either", "both" ] }, "explanation": { "type": "string", "description": "The rule in plain English for this expression." } }, "required": [ "rule", "explanation" ], "additionalProperties": false }, "fields": { "type": "array", "items": { "type": "object", "description": "", "properties": { "field": { "type": "string", "description": "Field name.", "enum": [ "second", "minute", "hour", "day-of-month", "month", "day-of-week" ] }, "raw": { "type": "string", "description": "The field as written." }, "values": { "type": "array", "items": { "type": "integer", "description": "A matching value." }, "description": "Expanded matching values, ascending. Day-of-week uses 0-6 (Sunday = 0). `L` and `#` constraints are described in `description`, not listed." }, "unrestricted": { "type": "boolean", "description": "True for `*` (and, in the day fields, anything starting with `*`, or `?`), per Vixie cron." }, "description": { "type": "string", "description": "What the field selects, in English." } }, "required": [ "field", "raw", "values", "unrestricted", "description" ], "additionalProperties": false }, "description": "One entry per field, in expression order (seconds first only for 6-field expressions)." }, "timezone": { "type": "string", "description": "Zone the schedule was evaluated in." }, "from": { "type": "string", "description": "Start of the search (exclusive), ISO 8601 in `timezone`." }, "next": { "type": "array", "items": { "type": "object", "description": "", "properties": { "iso": { "type": "string", "description": "Run time, ISO 8601 with the offset in `timezone`." }, "utc": { "type": "string", "description": "Run time in UTC." }, "unix_seconds": { "type": "integer", "description": "Run time as Unix seconds." }, "local": { "type": "string", "description": "Wall-clock time in `timezone`, without offset." }, "weekday": { "type": "string", "description": "English weekday in `timezone`." }, "dst_shifted": { "type": "boolean", "description": "True when the scheduled wall-clock time did not exist (DST gap) and the run is shown at the shifted time." } }, "required": [ "iso", "utc", "unix_seconds", "local", "weekday", "dst_shifted" ], "additionalProperties": false }, "description": "Upcoming run times, ascending. Empty when the schedule never fires." }, "warnings": { "type": "array", "items": { "type": "string", "description": "Plain-language warning." }, "description": "Portability and scheduling warnings: 6-field or Quartz-style syntax, DST shifts, schedules that never run, zone caveats." } }, "required": [ "expression", "normalized", "macro", "dialect", "description", "day_rule", "fields", "timezone", "from", "next", "warnings" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "The upcoming run times, one ISO 8601 time per line." } } } }, "400": { "description": "missing_parameter / unknown_parameter / `zone` is unknown or an abbreviation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The expression has the wrong number of fields, a value out of range (the message names the field), unsupported syntax (`H`, `W`, `@reboot`, unknown macros), or day fields no date can satisfy (`0 0 30 2 *`); or `from` cannot be parsed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "cron_explain_get", "parameters": [ { "name": "expression", "in": "query", "required": true, "description": "Cron expression, e.g. */15 9-17 * * 1-5, 0 0 1 * *, 30 0 9 * * MON (6 fields: seconds first), or @daily. Month and weekday names (JAN, MON) are case-insensitive; 0 and 7 are both Sunday.", "schema": { "description": "Cron expression, e.g. */15 9-17 * * 1-5, 0 0 1 * *, 30 0 9 * * MON (6 fields: seconds first), or @daily. Month and weekday names (JAN, MON) are case-insensitive; 0 and 7 are both Sunday.", "type": "string" } }, { "name": "zone", "in": "query", "required": false, "description": "Zone in which the schedule is evaluated (the cron daemon's zone, or CRON_TZ / Kubernetes timeZone): IANA name, UTC, or fixed offset.", "schema": { "description": "Zone in which the schedule is evaluated (the cron daemon's zone, or CRON_TZ / Kubernetes timeZone): IANA name, UTC, or fixed offset.", "type": "string", "default": "UTC" } }, { "name": "from", "in": "query", "required": false, "description": "List runs strictly after this instant (default: now). ISO 8601, RFC 2822, HTTP-date, Unix timestamp, or now; a time without offset is read in zone.", "schema": { "description": "List runs strictly after this instant (default: now). ISO 8601, RFC 2822, HTTP-date, Unix timestamp, or now; a time without offset is read in zone.", "type": "string" } }, { "name": "count", "in": "query", "required": false, "description": "Number of upcoming run times to return (1-50).", "schema": { "description": "Number of upcoming run times to return (1-50).", "type": "integer", "default": 5, "minimum": 1, "maximum": 50 } }, { "name": "format", "in": "query", "required": false, "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "schema": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } } ] }, "post": { "summary": "Validate a cron expression, describe it in English, and list its next run times in a zone.", "description": "Accepts the 5-field crontab form (minute hour day-of-month month day-of-week), a 6-field form whose first field is seconds, and the macros @yearly, @annually, @monthly, @weekly, @daily, @midnight, @hourly. Returns an English description, a field-by-field breakdown with the expanded values, the day-matching rule in effect, and the next run times after `from` in `zone`. Day-of-month and day-of-week follow Vixie cron: when both are restricted a day matches if EITHER matches (`0 0 13 * 5` runs on every 13th AND every Friday); a field starting with `*` (such as `*/2`) counts as unrestricted, and then a day must match both. Errors name the offending field.\n\nPrivacy: The server receives the cron expression, zone and start time, evaluates them in memory, and returns the result. Your input is not stored or logged; only the per-call metadata row (operation, time, status, sizes) is recorded.", "tags": [ "cron" ], "responses": { "200": { "description": "Success. With format=text, text/plain is returned instead of JSON.", "content": { "application/json": { "schema": { "type": "object", "description": "", "properties": { "expression": { "type": "string", "description": "The expression with whitespace collapsed." }, "normalized": { "type": "string", "description": "5- or 6-field form actually evaluated (macros expanded)." }, "macro": { "type": [ "string", "null" ], "description": "The macro used, lower-cased (e.g. `@daily`), or null." }, "dialect": { "type": "string", "description": "`five-field` (standard crontab) or `six-field-seconds`.", "enum": [ "five-field", "six-field-seconds" ] }, "description": { "type": "string", "description": "English description from cronstrue, 24-hour clock. For the day fields, `day_rule` is authoritative." }, "day_rule": { "type": "object", "description": "", "properties": { "rule": { "type": "string", "description": "How days are selected: `every-day`, `day-of-month` only, `day-of-week` only, `either` (OR: both restricted), or `both` (AND: one starts with `*` but still narrows).", "enum": [ "every-day", "day-of-month", "day-of-week", "either", "both" ] }, "explanation": { "type": "string", "description": "The rule in plain English for this expression." } }, "required": [ "rule", "explanation" ], "additionalProperties": false }, "fields": { "type": "array", "items": { "type": "object", "description": "", "properties": { "field": { "type": "string", "description": "Field name.", "enum": [ "second", "minute", "hour", "day-of-month", "month", "day-of-week" ] }, "raw": { "type": "string", "description": "The field as written." }, "values": { "type": "array", "items": { "type": "integer", "description": "A matching value." }, "description": "Expanded matching values, ascending. Day-of-week uses 0-6 (Sunday = 0). `L` and `#` constraints are described in `description`, not listed." }, "unrestricted": { "type": "boolean", "description": "True for `*` (and, in the day fields, anything starting with `*`, or `?`), per Vixie cron." }, "description": { "type": "string", "description": "What the field selects, in English." } }, "required": [ "field", "raw", "values", "unrestricted", "description" ], "additionalProperties": false }, "description": "One entry per field, in expression order (seconds first only for 6-field expressions)." }, "timezone": { "type": "string", "description": "Zone the schedule was evaluated in." }, "from": { "type": "string", "description": "Start of the search (exclusive), ISO 8601 in `timezone`." }, "next": { "type": "array", "items": { "type": "object", "description": "", "properties": { "iso": { "type": "string", "description": "Run time, ISO 8601 with the offset in `timezone`." }, "utc": { "type": "string", "description": "Run time in UTC." }, "unix_seconds": { "type": "integer", "description": "Run time as Unix seconds." }, "local": { "type": "string", "description": "Wall-clock time in `timezone`, without offset." }, "weekday": { "type": "string", "description": "English weekday in `timezone`." }, "dst_shifted": { "type": "boolean", "description": "True when the scheduled wall-clock time did not exist (DST gap) and the run is shown at the shifted time." } }, "required": [ "iso", "utc", "unix_seconds", "local", "weekday", "dst_shifted" ], "additionalProperties": false }, "description": "Upcoming run times, ascending. Empty when the schedule never fires." }, "warnings": { "type": "array", "items": { "type": "string", "description": "Plain-language warning." }, "description": "Portability and scheduling warnings: 6-field or Quartz-style syntax, DST shifts, schedules that never run, zone caveats." } }, "required": [ "expression", "normalized", "macro", "dialect", "description", "day_rule", "fields", "timezone", "from", "next", "warnings" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "The upcoming run times, one ISO 8601 time per line." } } } }, "400": { "description": "missing_parameter / unknown_parameter / `zone` is unknown or an abbreviation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The expression has the wrong number of fields, a value out of range (the message names the field), unsupported syntax (`H`, `W`, `@reboot`, unknown macros), or day fields no date can satisfy (`0 0 30 2 *`); or `from` cannot be parsed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "cron_explain", "parameters": [ { "name": "format", "in": "query", "required": false, "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "schema": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expression": { "description": "Cron expression, e.g. */15 9-17 * * 1-5, 0 0 1 * *, 30 0 9 * * MON (6 fields: seconds first), or @daily. Month and weekday names (JAN, MON) are case-insensitive; 0 and 7 are both Sunday.", "type": "string" }, "zone": { "description": "Zone in which the schedule is evaluated (the cron daemon's zone, or CRON_TZ / Kubernetes timeZone): IANA name, UTC, or fixed offset.", "type": "string", "default": "UTC" }, "from": { "description": "List runs strictly after this instant (default: now). ISO 8601, RFC 2822, HTTP-date, Unix timestamp, or now; a time without offset is read in zone.", "type": "string" }, "count": { "description": "Number of upcoming run times to return (1-50).", "type": "integer", "default": 5, "minimum": 1, "maximum": 50 }, "format": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } }, "required": [ "expression" ], "additionalProperties": false } } } } } }, "/api/diff": { "get": { "summary": "Diff two texts by line, word or character: unified diff, structured changes, and stats.", "description": "Compares `before` with `after` using jsdiff (Myers' O(ND) algorithm). `changes` is the full sequence of added, removed and unchanged pieces at the chosen granularity; concatenating the unchanged and removed values gives `before`, unchanged and added gives `after` (when ignoring whitespace or case, unchanged pieces are taken from `after`). `unified` and `hunks` are always a line-level unified diff (GNU `diff -u` format) with `context` lines, whatever the mode. `identical` is true when no differences remain under the chosen options; `exact_match` compares the raw strings. Limits: 200,000 characters per text; at most 5000 differing lines, or 2000 differing words or characters.\n\nPrivacy: The server receives both texts in full, compares them in memory, and returns the differences. Your input is not stored or logged; only the per-call metadata row (operation, time, status, sizes) is recorded. For confidential text use the page, which compares in your browser and sends nothing.", "tags": [ "diff" ], "responses": { "200": { "description": "Success. With format=text, text/plain is returned instead of JSON.", "content": { "application/json": { "schema": { "type": "object", "description": "", "properties": { "identical": { "type": "boolean", "description": "True when the texts have no differences under the chosen options." }, "exact_match": { "type": "boolean", "description": "True when `before` and `after` are byte-for-byte equal strings." }, "mode": { "type": "string", "description": "Granularity used.", "enum": [ "lines", "words", "characters" ] }, "unit": { "type": "string", "description": "Unit of counts in `stats` and `changes`.", "enum": [ "line", "word", "character" ] }, "options": { "type": "object", "description": "", "properties": { "ignore_whitespace": { "type": "boolean", "description": "As requested." }, "ignore_case": { "type": "boolean", "description": "As requested." }, "context": { "type": "integer", "description": "Context lines used." }, "from_label": { "type": "string", "description": "`---` label used." }, "to_label": { "type": "string", "description": "`+++` label used." } }, "required": [ "ignore_whitespace", "ignore_case", "context", "from_label", "to_label" ], "additionalProperties": false }, "stats": { "type": "object", "description": "", "properties": { "added": { "type": "integer", "description": "Total added, in units of `unit` (lines, words, or Unicode code points).", "minimum": 0 }, "removed": { "type": "integer", "description": "Total removed, in units of `unit` (lines, words, or Unicode code points).", "minimum": 0 }, "unchanged": { "type": "integer", "description": "Total unchanged, in units of `unit` (lines, words, or Unicode code points).", "minimum": 0 }, "change_blocks": { "type": "integer", "description": "Number of contiguous runs of added and/or removed pieces.", "minimum": 0 }, "lines_added": { "type": "integer", "description": "`+` lines in the unified diff (what diffstat counts).", "minimum": 0 }, "lines_removed": { "type": "integer", "description": "`-` lines in the unified diff.", "minimum": 0 }, "chars_added": { "type": "integer", "description": "Unicode code points in added pieces.", "minimum": 0 }, "chars_removed": { "type": "integer", "description": "Unicode code points in removed pieces.", "minimum": 0 } }, "required": [ "added", "removed", "unchanged", "change_blocks", "lines_added", "lines_removed", "chars_added", "chars_removed" ], "additionalProperties": false }, "changes": { "type": "array", "items": { "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "Kind of piece.", "enum": [ "added", "removed", "unchanged" ] }, "value": { "type": "string", "description": "The text of the piece, including its line breaks and whitespace." }, "count": { "type": "integer", "description": "Size of the piece, in units of `unit` (lines, words, or Unicode code points).", "minimum": 0 } }, "required": [ "type", "value", "count" ], "additionalProperties": false }, "description": "Every piece of both texts in order. A replacement appears as `removed` followed by `added`." }, "hunks": { "type": "array", "items": { "type": "object", "description": "", "properties": { "header": { "type": "string", "description": "Hunk header, e.g. `@@ -1,3 +1,4 @@`." }, "before_start": { "type": "integer", "description": "First line in `before` (1-based; 0 when the hunk has no `before` lines)." }, "before_lines": { "type": "integer", "description": "Number of `before` lines in the hunk." }, "after_start": { "type": "integer", "description": "First line in `after` (1-based; 0 when the hunk has no `after` lines)." }, "after_lines": { "type": "integer", "description": "Number of `after` lines in the hunk." }, "lines": { "type": "array", "items": { "type": "string", "description": "Line prefixed with ` ` (context), `-` (removed) or `+` (added), without its line break; or `\\ No newline at end of file`." }, "description": "Lines of the hunk." } }, "required": [ "header", "before_start", "before_lines", "after_start", "after_lines", "lines" ], "additionalProperties": false }, "description": "Line-level hunks of the unified diff. Empty when identical." }, "unified": { "type": "string", "description": "Unified diff text: `--- from_label`, `+++ to_label`, then the hunks. Empty string when identical." } }, "required": [ "identical", "exact_match", "mode", "unit", "options", "stats", "changes", "hunks", "unified" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "The unified diff (empty when identical)." } } } }, "400": { "description": "missing_parameter / unknown_parameter / A text exceeds the length limit, or `context` is out of range.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The texts differ in more than the edit limit for the mode, `ignore_whitespace` is used with `characters` mode, or a label contains a line break.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "text_diff_get", "parameters": [ { "name": "before", "in": "query", "required": true, "description": "The original text.", "schema": { "description": "The original text.", "type": "string" } }, { "name": "after", "in": "query", "required": true, "description": "The changed text.", "schema": { "description": "The changed text.", "type": "string" } }, { "name": "mode", "in": "query", "required": false, "description": "Granularity of changes and stats: lines, words (runs of letters/digits/underscore; each punctuation mark is its own token), or characters (Unicode code points).", "schema": { "description": "Granularity of changes and stats: lines, words (runs of letters/digits/underscore; each punctuation mark is its own token), or characters (Unicode code points).", "type": "string", "enum": [ "lines", "words", "characters" ], "default": "lines" } }, { "name": "ignore_whitespace", "in": "query", "required": false, "description": "lines: compare lines with leading and trailing whitespace trimmed. words: ignore differences in the whitespace between words. Not supported in characters mode (422).", "schema": { "description": "lines: compare lines with leading and trailing whitespace trimmed. words: ignore differences in the whitespace between words. Not supported in characters mode (422).", "type": "boolean", "default": false } }, { "name": "ignore_case", "in": "query", "required": false, "description": "Compare case-insensitively (JavaScript toLowerCase), in every mode and in the unified diff.", "schema": { "description": "Compare case-insensitively (JavaScript toLowerCase), in every mode and in the unified diff.", "type": "boolean", "default": false } }, { "name": "context", "in": "query", "required": false, "description": "Unchanged lines shown around each change in unified and hunks (GNU diff default: 3).", "schema": { "description": "Unchanged lines shown around each change in unified and hunks (GNU diff default: 3).", "type": "integer", "default": 3, "minimum": 0, "maximum": 1000 } }, { "name": "from_label", "in": "query", "required": false, "description": "Label for the --- header line of the unified diff, e.g. a file name a/src/app.ts.", "schema": { "description": "Label for the --- header line of the unified diff, e.g. a file name a/src/app.ts.", "type": "string", "default": "before" } }, { "name": "to_label", "in": "query", "required": false, "description": "Label for the +++ header line of the unified diff.", "schema": { "description": "Label for the +++ header line of the unified diff.", "type": "string", "default": "after" } }, { "name": "format", "in": "query", "required": false, "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "schema": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } } ] }, "post": { "summary": "Diff two texts by line, word or character: unified diff, structured changes, and stats.", "description": "Compares `before` with `after` using jsdiff (Myers' O(ND) algorithm). `changes` is the full sequence of added, removed and unchanged pieces at the chosen granularity; concatenating the unchanged and removed values gives `before`, unchanged and added gives `after` (when ignoring whitespace or case, unchanged pieces are taken from `after`). `unified` and `hunks` are always a line-level unified diff (GNU `diff -u` format) with `context` lines, whatever the mode. `identical` is true when no differences remain under the chosen options; `exact_match` compares the raw strings. Limits: 200,000 characters per text; at most 5000 differing lines, or 2000 differing words or characters.\n\nPrivacy: The server receives both texts in full, compares them in memory, and returns the differences. Your input is not stored or logged; only the per-call metadata row (operation, time, status, sizes) is recorded. For confidential text use the page, which compares in your browser and sends nothing.", "tags": [ "diff" ], "responses": { "200": { "description": "Success. With format=text, text/plain is returned instead of JSON.", "content": { "application/json": { "schema": { "type": "object", "description": "", "properties": { "identical": { "type": "boolean", "description": "True when the texts have no differences under the chosen options." }, "exact_match": { "type": "boolean", "description": "True when `before` and `after` are byte-for-byte equal strings." }, "mode": { "type": "string", "description": "Granularity used.", "enum": [ "lines", "words", "characters" ] }, "unit": { "type": "string", "description": "Unit of counts in `stats` and `changes`.", "enum": [ "line", "word", "character" ] }, "options": { "type": "object", "description": "", "properties": { "ignore_whitespace": { "type": "boolean", "description": "As requested." }, "ignore_case": { "type": "boolean", "description": "As requested." }, "context": { "type": "integer", "description": "Context lines used." }, "from_label": { "type": "string", "description": "`---` label used." }, "to_label": { "type": "string", "description": "`+++` label used." } }, "required": [ "ignore_whitespace", "ignore_case", "context", "from_label", "to_label" ], "additionalProperties": false }, "stats": { "type": "object", "description": "", "properties": { "added": { "type": "integer", "description": "Total added, in units of `unit` (lines, words, or Unicode code points).", "minimum": 0 }, "removed": { "type": "integer", "description": "Total removed, in units of `unit` (lines, words, or Unicode code points).", "minimum": 0 }, "unchanged": { "type": "integer", "description": "Total unchanged, in units of `unit` (lines, words, or Unicode code points).", "minimum": 0 }, "change_blocks": { "type": "integer", "description": "Number of contiguous runs of added and/or removed pieces.", "minimum": 0 }, "lines_added": { "type": "integer", "description": "`+` lines in the unified diff (what diffstat counts).", "minimum": 0 }, "lines_removed": { "type": "integer", "description": "`-` lines in the unified diff.", "minimum": 0 }, "chars_added": { "type": "integer", "description": "Unicode code points in added pieces.", "minimum": 0 }, "chars_removed": { "type": "integer", "description": "Unicode code points in removed pieces.", "minimum": 0 } }, "required": [ "added", "removed", "unchanged", "change_blocks", "lines_added", "lines_removed", "chars_added", "chars_removed" ], "additionalProperties": false }, "changes": { "type": "array", "items": { "type": "object", "description": "", "properties": { "type": { "type": "string", "description": "Kind of piece.", "enum": [ "added", "removed", "unchanged" ] }, "value": { "type": "string", "description": "The text of the piece, including its line breaks and whitespace." }, "count": { "type": "integer", "description": "Size of the piece, in units of `unit` (lines, words, or Unicode code points).", "minimum": 0 } }, "required": [ "type", "value", "count" ], "additionalProperties": false }, "description": "Every piece of both texts in order. A replacement appears as `removed` followed by `added`." }, "hunks": { "type": "array", "items": { "type": "object", "description": "", "properties": { "header": { "type": "string", "description": "Hunk header, e.g. `@@ -1,3 +1,4 @@`." }, "before_start": { "type": "integer", "description": "First line in `before` (1-based; 0 when the hunk has no `before` lines)." }, "before_lines": { "type": "integer", "description": "Number of `before` lines in the hunk." }, "after_start": { "type": "integer", "description": "First line in `after` (1-based; 0 when the hunk has no `after` lines)." }, "after_lines": { "type": "integer", "description": "Number of `after` lines in the hunk." }, "lines": { "type": "array", "items": { "type": "string", "description": "Line prefixed with ` ` (context), `-` (removed) or `+` (added), without its line break; or `\\ No newline at end of file`." }, "description": "Lines of the hunk." } }, "required": [ "header", "before_start", "before_lines", "after_start", "after_lines", "lines" ], "additionalProperties": false }, "description": "Line-level hunks of the unified diff. Empty when identical." }, "unified": { "type": "string", "description": "Unified diff text: `--- from_label`, `+++ to_label`, then the hunks. Empty string when identical." } }, "required": [ "identical", "exact_match", "mode", "unit", "options", "stats", "changes", "hunks", "unified" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "The unified diff (empty when identical)." } } } }, "400": { "description": "missing_parameter / unknown_parameter / A text exceeds the length limit, or `context` is out of range.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The texts differ in more than the edit limit for the mode, `ignore_whitespace` is used with `characters` mode, or a label contains a line break.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "text_diff", "parameters": [ { "name": "format", "in": "query", "required": false, "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "schema": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "before": { "description": "The original text.", "type": "string" }, "after": { "description": "The changed text.", "type": "string" }, "mode": { "description": "Granularity of changes and stats: lines, words (runs of letters/digits/underscore; each punctuation mark is its own token), or characters (Unicode code points).", "type": "string", "enum": [ "lines", "words", "characters" ], "default": "lines" }, "ignore_whitespace": { "description": "lines: compare lines with leading and trailing whitespace trimmed. words: ignore differences in the whitespace between words. Not supported in characters mode (422).", "type": "boolean", "default": false }, "ignore_case": { "description": "Compare case-insensitively (JavaScript toLowerCase), in every mode and in the unified diff.", "type": "boolean", "default": false }, "context": { "description": "Unchanged lines shown around each change in unified and hunks (GNU diff default: 3).", "type": "integer", "default": 3, "minimum": 0, "maximum": 1000 }, "from_label": { "description": "Label for the --- header line of the unified diff, e.g. a file name a/src/app.ts.", "type": "string", "default": "before" }, "to_label": { "description": "Label for the +++ header line of the unified diff.", "type": "string", "default": "after" }, "format": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } }, "required": [ "before", "after" ], "additionalProperties": false } } } } } }, "/api/json/format": { "get": { "summary": "Check that text is valid JSON (RFC 8259), pretty-print or minify it, and find duplicate keys.", "description": "Parses `input` strictly as RFC 8259 JSON and reports the first syntax error with line, column, offset, JSON Pointer and an excerpt; messages name the usual mistakes (trailing commas, single quotes, unquoted keys, comments, NaN, leading zeros) and say how to fix them. Invalid JSON is a successful response with `valid: false`, so check `valid`. For valid JSON it returns the document re-indented or minified, optionally with keys sorted, plus statistics. Only whitespace (and, with `sort_keys`, member order) changes: strings and numbers are copied exactly as written, so `1.0`, `1e5` and 20-digit integers survive. Duplicate keys, which JSON.parse silently collapses, are listed with JSON Pointers; the output keeps the last value at the first position, as JSON.parse does. Nesting deeper than 500 levels is rejected.\n\nPrivacy: The server receives the JSON text, processes it in memory inside the request, and returns the result. Your input is not stored or logged; only the per-call metadata row (operation, time, status, sizes) is recorded. The server makes no network requests. For confidential documents use the page, which does the same work in your browser and sends nothing.", "tags": [ "json" ], "responses": { "200": { "description": "Success. With format=text, text/plain is returned instead of JSON.", "content": { "application/json": { "schema": { "type": "object", "description": "", "properties": { "valid": { "type": "boolean", "description": "True when `input` is one well-formed JSON value." }, "error": { "type": [ "object", "null" ], "description": "The first syntax error.", "properties": { "message": { "type": "string", "description": "What is wrong and how to fix it." }, "line": { "type": "integer", "description": "1-based line number." }, "column": { "type": "integer", "description": "1-based column, counted in Unicode code points." }, "offset": { "type": "integer", "description": "0-based offset from the start of the input, in Unicode code points." }, "pointer": { "type": "string", "description": "JSON Pointer (RFC 6901) of the value being read when the error was found; `\"\"` is the root." }, "excerpt": { "type": "string", "description": "The offending line (windowed to about 80 characters, tabs shown as spaces) and a second line with a caret under the error." } }, "required": [ "message", "line", "column", "offset", "pointer", "excerpt" ], "additionalProperties": false }, "type": { "type": [ "string", "null" ], "description": "Type of the top-level value: object, array, string, number, boolean or null." }, "output": { "type": [ "string", "null" ], "description": "The formatted JSON; null when invalid." }, "duplicateKeys": { "type": "array", "items": { "type": "object", "description": "", "properties": { "key": { "type": "string", "description": "The repeated key." }, "pointer": { "type": "string", "description": "JSON Pointer of the repeated member." }, "line": { "type": "integer", "description": "1-based line number." }, "column": { "type": "integer", "description": "1-based column, counted in Unicode code points." }, "offset": { "type": "integer", "description": "0-based offset of the repeat, in code points." }, "firstLine": { "type": "integer", "description": "Line of the first occurrence." }, "firstColumn": { "type": "integer", "description": "Column of the first occurrence." } }, "required": [ "key", "pointer", "line", "column", "offset", "firstLine", "firstColumn" ], "additionalProperties": false }, "description": "Every repeated key after its first occurrence in the same object." }, "warnings": { "type": "array", "items": { "type": "object", "description": "", "properties": { "message": { "type": "string", "description": "Plain-language finding." }, "pointer": { "type": "string", "description": "JSON Pointer of the value concerned." }, "line": { "type": "integer", "description": "1-based line number." }, "column": { "type": "integer", "description": "1-based column, counted in Unicode code points." }, "offset": { "type": "integer", "description": "0-based offset in code points." } }, "required": [ "message", "pointer", "line", "column", "offset" ], "additionalProperties": false }, "description": "Valid-but-risky findings: integers beyond 2^53 − 1, numbers that overflow a double, unpaired surrogate escapes, duplicate keys. At most 100 are listed." }, "stats": { "type": [ "object", "null" ], "description": "Counts for valid input; null when invalid.", "properties": { "depth": { "type": "integer", "description": "Maximum nesting depth: 0 for a scalar, 1 for a flat object or array." }, "objects": { "type": "integer", "description": "Number of objects." }, "arrays": { "type": "integer", "description": "Number of arrays." }, "members": { "type": "integer", "description": "Number of object members, duplicates included." }, "strings": { "type": "integer", "description": "Number of string values (keys are not counted)." }, "numbers": { "type": "integer", "description": "Number of numbers." }, "booleans": { "type": "integer", "description": "Number of true/false values." }, "nulls": { "type": "integer", "description": "Number of nulls." }, "inputBytes": { "type": "integer", "description": "Size of `input` in UTF-8 bytes." }, "outputBytes": { "type": "integer", "description": "Size of `output` in UTF-8 bytes." } }, "required": [ "depth", "objects", "arrays", "members", "strings", "numbers", "booleans", "nulls", "inputBytes", "outputBytes" ], "additionalProperties": false } }, "required": [ "valid", "error", "type", "output", "duplicateKeys", "warnings", "stats" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "The formatted JSON, or for invalid input one line: `invalid: line L, column C: message`." } } } }, "400": { "description": "missing_parameter / unknown_parameter / `input` is longer than 500,000 characters, or `indent` is not one of the listed values. Invalid JSON is NOT an error: it returns 200 with `valid: false`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "json_format_get", "parameters": [ { "name": "input", "in": "query", "required": true, "description": "The JSON text. Send it as a string field ({\"input\": \"{\\\"a\\\":1}\"}) or as a raw text/plain POST body. A byte order mark is reported as an error.", "schema": { "description": "The JSON text. Send it as a string field ({\"input\": \"{\\\"a\\\":1}\"}) or as a raw text/plain POST body. A byte order mark is reported as an error.", "type": "string" } }, { "name": "indent", "in": "query", "required": false, "description": "JSON output indentation: 2 or 4 spaces, tab, or none for minified output (no whitespace at all).", "schema": { "description": "JSON output indentation: 2 or 4 spaces, tab, or none for minified output (no whitespace at all).", "type": "string", "enum": [ "2", "4", "tab", "none" ], "default": "2" } }, { "name": "sort_keys", "in": "query", "required": false, "description": "Sort object keys recursively, by UTF-16 code units (the order RFC 8785 uses). Array order never changes.", "schema": { "description": "Sort object keys recursively, by UTF-16 code units (the order RFC 8785 uses). Array order never changes.", "type": "boolean", "default": false } }, { "name": "format", "in": "query", "required": false, "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "schema": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } } ] }, "post": { "summary": "Check that text is valid JSON (RFC 8259), pretty-print or minify it, and find duplicate keys.", "description": "Parses `input` strictly as RFC 8259 JSON and reports the first syntax error with line, column, offset, JSON Pointer and an excerpt; messages name the usual mistakes (trailing commas, single quotes, unquoted keys, comments, NaN, leading zeros) and say how to fix them. Invalid JSON is a successful response with `valid: false`, so check `valid`. For valid JSON it returns the document re-indented or minified, optionally with keys sorted, plus statistics. Only whitespace (and, with `sort_keys`, member order) changes: strings and numbers are copied exactly as written, so `1.0`, `1e5` and 20-digit integers survive. Duplicate keys, which JSON.parse silently collapses, are listed with JSON Pointers; the output keeps the last value at the first position, as JSON.parse does. Nesting deeper than 500 levels is rejected.\n\nPrivacy: The server receives the JSON text, processes it in memory inside the request, and returns the result. Your input is not stored or logged; only the per-call metadata row (operation, time, status, sizes) is recorded. The server makes no network requests. For confidential documents use the page, which does the same work in your browser and sends nothing.", "tags": [ "json" ], "responses": { "200": { "description": "Success. With format=text, text/plain is returned instead of JSON.", "content": { "application/json": { "schema": { "type": "object", "description": "", "properties": { "valid": { "type": "boolean", "description": "True when `input` is one well-formed JSON value." }, "error": { "type": [ "object", "null" ], "description": "The first syntax error.", "properties": { "message": { "type": "string", "description": "What is wrong and how to fix it." }, "line": { "type": "integer", "description": "1-based line number." }, "column": { "type": "integer", "description": "1-based column, counted in Unicode code points." }, "offset": { "type": "integer", "description": "0-based offset from the start of the input, in Unicode code points." }, "pointer": { "type": "string", "description": "JSON Pointer (RFC 6901) of the value being read when the error was found; `\"\"` is the root." }, "excerpt": { "type": "string", "description": "The offending line (windowed to about 80 characters, tabs shown as spaces) and a second line with a caret under the error." } }, "required": [ "message", "line", "column", "offset", "pointer", "excerpt" ], "additionalProperties": false }, "type": { "type": [ "string", "null" ], "description": "Type of the top-level value: object, array, string, number, boolean or null." }, "output": { "type": [ "string", "null" ], "description": "The formatted JSON; null when invalid." }, "duplicateKeys": { "type": "array", "items": { "type": "object", "description": "", "properties": { "key": { "type": "string", "description": "The repeated key." }, "pointer": { "type": "string", "description": "JSON Pointer of the repeated member." }, "line": { "type": "integer", "description": "1-based line number." }, "column": { "type": "integer", "description": "1-based column, counted in Unicode code points." }, "offset": { "type": "integer", "description": "0-based offset of the repeat, in code points." }, "firstLine": { "type": "integer", "description": "Line of the first occurrence." }, "firstColumn": { "type": "integer", "description": "Column of the first occurrence." } }, "required": [ "key", "pointer", "line", "column", "offset", "firstLine", "firstColumn" ], "additionalProperties": false }, "description": "Every repeated key after its first occurrence in the same object." }, "warnings": { "type": "array", "items": { "type": "object", "description": "", "properties": { "message": { "type": "string", "description": "Plain-language finding." }, "pointer": { "type": "string", "description": "JSON Pointer of the value concerned." }, "line": { "type": "integer", "description": "1-based line number." }, "column": { "type": "integer", "description": "1-based column, counted in Unicode code points." }, "offset": { "type": "integer", "description": "0-based offset in code points." } }, "required": [ "message", "pointer", "line", "column", "offset" ], "additionalProperties": false }, "description": "Valid-but-risky findings: integers beyond 2^53 − 1, numbers that overflow a double, unpaired surrogate escapes, duplicate keys. At most 100 are listed." }, "stats": { "type": [ "object", "null" ], "description": "Counts for valid input; null when invalid.", "properties": { "depth": { "type": "integer", "description": "Maximum nesting depth: 0 for a scalar, 1 for a flat object or array." }, "objects": { "type": "integer", "description": "Number of objects." }, "arrays": { "type": "integer", "description": "Number of arrays." }, "members": { "type": "integer", "description": "Number of object members, duplicates included." }, "strings": { "type": "integer", "description": "Number of string values (keys are not counted)." }, "numbers": { "type": "integer", "description": "Number of numbers." }, "booleans": { "type": "integer", "description": "Number of true/false values." }, "nulls": { "type": "integer", "description": "Number of nulls." }, "inputBytes": { "type": "integer", "description": "Size of `input` in UTF-8 bytes." }, "outputBytes": { "type": "integer", "description": "Size of `output` in UTF-8 bytes." } }, "required": [ "depth", "objects", "arrays", "members", "strings", "numbers", "booleans", "nulls", "inputBytes", "outputBytes" ], "additionalProperties": false } }, "required": [ "valid", "error", "type", "output", "duplicateKeys", "warnings", "stats" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "The formatted JSON, or for invalid input one line: `invalid: line L, column C: message`." } } } }, "400": { "description": "missing_parameter / unknown_parameter / `input` is longer than 500,000 characters, or `indent` is not one of the listed values. Invalid JSON is NOT an error: it returns 200 with `valid: false`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "json_format", "parameters": [ { "name": "format", "in": "query", "required": false, "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "schema": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "input": { "description": "The JSON text. Send it as a string field ({\"input\": \"{\\\"a\\\":1}\"}) or as a raw text/plain POST body. A byte order mark is reported as an error.", "type": "string" }, "indent": { "description": "JSON output indentation: 2 or 4 spaces, tab, or none for minified output (no whitespace at all).", "type": "string", "enum": [ "2", "4", "tab", "none" ], "default": "2" }, "sort_keys": { "description": "Sort object keys recursively, by UTF-16 code units (the order RFC 8785 uses). Array order never changes.", "type": "boolean", "default": false }, "format": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } }, "required": [ "input" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "The body is used as the `input` parameter." } } } } } }, "/api/json/schema/validate": { "get": { "summary": "Validate a JSON instance against a JSON Schema (draft 2020-12, 2019-09, 7, 6 or 4) and list every error with JSON Pointers.", "description": "Validates `instance` against `schema` with @cfworker/json-schema (an interpreter: no code generation). The draft comes from `draft`, else from the schema's `$schema`, else 2020-12. Returns `valid` and, for an invalid instance, each error with the instance location and keyword location as JSON Pointers, the location of the keyword in the schema document (after following `$ref`), and a message; `leaf: false` marks summary errors (from `properties`, `items`, `$ref`, `anyOf`, …) that are followed by the specific errors beneath them. An invalid instance is a successful response with `valid: false`. Before validating, the schema is checked for usability (keyword types, regular expressions, unresolved references); problems are a 422 error. Only local references resolve: `$ref` to a remote URL is never fetched (the server makes no network requests); embed such schemas under `$defs` with their `$id`. `format` is asserted for the formats listed in the docs. `$dynamicRef` is not supported. At most 1000 errors are returned.\n\nPrivacy: The server receives the schema and the instance, processes it in memory inside the request, and returns the result. Your input is not stored or logged; only the per-call metadata row (operation, time, status, sizes) is recorded. The server makes no network requests. For confidential documents use the page, which does the same work in your browser and sends nothing.", "tags": [ "json-schema" ], "responses": { "200": { "description": "Success. With format=text, text/plain is returned instead of JSON.", "content": { "application/json": { "schema": { "type": "object", "description": "", "properties": { "valid": { "type": "boolean", "description": "True when the instance satisfies the schema." }, "draft": { "type": "string", "description": "The draft used.", "enum": [ "2020-12", "2019-09", "7", "4" ] }, "draftSource": { "type": "string", "description": "Where the draft came from.", "enum": [ "parameter", "$schema", "default" ] }, "errorCount": { "type": "integer", "description": "Total number of errors, including any beyond the listed maximum." }, "errors": { "type": "array", "items": { "type": "object", "description": "", "properties": { "instanceLocation": { "type": "string", "description": "JSON Pointer to the failing value in the instance; `\"\"` is the whole document." }, "keyword": { "type": "string", "description": "The schema keyword that failed, e.g. `type`, `required`, `minimum`; `false` for a false schema." }, "keywordLocation": { "type": "string", "description": "Evaluation path through the schema as a JSON Pointer; a `$ref` segment marks a followed reference." }, "schemaLocation": { "type": [ "string", "null" ], "description": "JSON Pointer to the keyword in the schema document, after following `$ref`; null if it cannot be resolved (`$recursiveRef`)." }, "message": { "type": "string", "description": "What is wrong." }, "leaf": { "type": "boolean", "description": "False for a summary error that is followed by the more specific errors that caused it." } }, "required": [ "instanceLocation", "keyword", "keywordLocation", "schemaLocation", "message", "leaf" ], "additionalProperties": false }, "description": "Errors in evaluation order (at most 1000)." }, "warnings": { "type": "array", "items": { "type": "object", "description": "", "properties": { "source": { "type": "string", "description": "Which document the warning is about.", "enum": [ "schema", "instance" ] }, "pointer": { "type": "string", "description": "JSON Pointer in that document." }, "message": { "type": "string", "description": "Ignored or unknown keywords, unchecked formats, draft mismatches, duplicate keys, lossy numbers." } }, "required": [ "source", "pointer", "message" ], "additionalProperties": false }, "description": "Things that did not stop validation but may not do what you expect." } }, "required": [ "valid", "draft", "draftSource", "errorCount", "errors", "warnings" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "`valid`, or `invalid` followed by one line per leaf error: ` `." } } } }, "400": { "description": "missing_parameter / unknown_parameter / `schema` or `instance` exceeds its length limit, or `draft` is not a listed value.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`schema` or `instance` is not valid JSON (the message gives line, column and offset), or the schema is not usable: a keyword has the wrong type, a regular expression does not compile, a `$ref` does not resolve locally, the draft is 3, or `$ref` cycles never reach the instance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "json_schema_validate_get", "parameters": [ { "name": "schema", "in": "query", "required": true, "description": "The JSON Schema, as JSON text (an object or a boolean).", "schema": { "description": "The JSON Schema, as JSON text (an object or a boolean).", "type": "string" } }, { "name": "instance", "in": "query", "required": true, "description": "The JSON document to validate, as JSON text.", "schema": { "description": "The JSON document to validate, as JSON text.", "type": "string" } }, { "name": "draft", "in": "query", "required": false, "description": "auto uses the draft named by the schema's $schema (draft 6 is validated as 7) and 2020-12 if there is none. Otherwise 2020-12, 2019-09, 7 or 4 overrides $schema.", "schema": { "description": "auto uses the draft named by the schema's $schema (draft 6 is validated as 7) and 2020-12 if there is none. Otherwise 2020-12, 2019-09, 7 or 4 overrides $schema.", "type": "string", "enum": [ "auto", "2020-12", "2019-09", "7", "4" ], "default": "auto" } }, { "name": "all_errors", "in": "query", "required": false, "description": "true reports every error. false stops at the first failing keyword (faster; valid is the same either way).", "schema": { "description": "true reports every error. false stops at the first failing keyword (faster; valid is the same either way).", "type": "boolean", "default": true } }, { "name": "format", "in": "query", "required": false, "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "schema": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } } ] }, "post": { "summary": "Validate a JSON instance against a JSON Schema (draft 2020-12, 2019-09, 7, 6 or 4) and list every error with JSON Pointers.", "description": "Validates `instance` against `schema` with @cfworker/json-schema (an interpreter: no code generation). The draft comes from `draft`, else from the schema's `$schema`, else 2020-12. Returns `valid` and, for an invalid instance, each error with the instance location and keyword location as JSON Pointers, the location of the keyword in the schema document (after following `$ref`), and a message; `leaf: false` marks summary errors (from `properties`, `items`, `$ref`, `anyOf`, …) that are followed by the specific errors beneath them. An invalid instance is a successful response with `valid: false`. Before validating, the schema is checked for usability (keyword types, regular expressions, unresolved references); problems are a 422 error. Only local references resolve: `$ref` to a remote URL is never fetched (the server makes no network requests); embed such schemas under `$defs` with their `$id`. `format` is asserted for the formats listed in the docs. `$dynamicRef` is not supported. At most 1000 errors are returned.\n\nPrivacy: The server receives the schema and the instance, processes it in memory inside the request, and returns the result. Your input is not stored or logged; only the per-call metadata row (operation, time, status, sizes) is recorded. The server makes no network requests. For confidential documents use the page, which does the same work in your browser and sends nothing.", "tags": [ "json-schema" ], "responses": { "200": { "description": "Success. With format=text, text/plain is returned instead of JSON.", "content": { "application/json": { "schema": { "type": "object", "description": "", "properties": { "valid": { "type": "boolean", "description": "True when the instance satisfies the schema." }, "draft": { "type": "string", "description": "The draft used.", "enum": [ "2020-12", "2019-09", "7", "4" ] }, "draftSource": { "type": "string", "description": "Where the draft came from.", "enum": [ "parameter", "$schema", "default" ] }, "errorCount": { "type": "integer", "description": "Total number of errors, including any beyond the listed maximum." }, "errors": { "type": "array", "items": { "type": "object", "description": "", "properties": { "instanceLocation": { "type": "string", "description": "JSON Pointer to the failing value in the instance; `\"\"` is the whole document." }, "keyword": { "type": "string", "description": "The schema keyword that failed, e.g. `type`, `required`, `minimum`; `false` for a false schema." }, "keywordLocation": { "type": "string", "description": "Evaluation path through the schema as a JSON Pointer; a `$ref` segment marks a followed reference." }, "schemaLocation": { "type": [ "string", "null" ], "description": "JSON Pointer to the keyword in the schema document, after following `$ref`; null if it cannot be resolved (`$recursiveRef`)." }, "message": { "type": "string", "description": "What is wrong." }, "leaf": { "type": "boolean", "description": "False for a summary error that is followed by the more specific errors that caused it." } }, "required": [ "instanceLocation", "keyword", "keywordLocation", "schemaLocation", "message", "leaf" ], "additionalProperties": false }, "description": "Errors in evaluation order (at most 1000)." }, "warnings": { "type": "array", "items": { "type": "object", "description": "", "properties": { "source": { "type": "string", "description": "Which document the warning is about.", "enum": [ "schema", "instance" ] }, "pointer": { "type": "string", "description": "JSON Pointer in that document." }, "message": { "type": "string", "description": "Ignored or unknown keywords, unchecked formats, draft mismatches, duplicate keys, lossy numbers." } }, "required": [ "source", "pointer", "message" ], "additionalProperties": false }, "description": "Things that did not stop validation but may not do what you expect." } }, "required": [ "valid", "draft", "draftSource", "errorCount", "errors", "warnings" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "`valid`, or `invalid` followed by one line per leaf error: ` `." } } } }, "400": { "description": "missing_parameter / unknown_parameter / `schema` or `instance` exceeds its length limit, or `draft` is not a listed value.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`schema` or `instance` is not valid JSON (the message gives line, column and offset), or the schema is not usable: a keyword has the wrong type, a regular expression does not compile, a `$ref` does not resolve locally, the draft is 3, or `$ref` cycles never reach the instance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "json_schema_validate", "parameters": [ { "name": "format", "in": "query", "required": false, "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "schema": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "schema": { "description": "The JSON Schema, as JSON text (an object or a boolean).", "type": "string" }, "instance": { "description": "The JSON document to validate, as JSON text.", "type": "string" }, "draft": { "description": "auto uses the draft named by the schema's $schema (draft 6 is validated as 7) and 2020-12 if there is none. Otherwise 2020-12, 2019-09, 7 or 4 overrides $schema.", "type": "string", "enum": [ "auto", "2020-12", "2019-09", "7", "4" ], "default": "auto" }, "all_errors": { "description": "true reports every error. false stops at the first failing keyword (faster; valid is the same either way).", "type": "boolean", "default": true }, "format": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } }, "required": [ "schema", "instance" ], "additionalProperties": false } } } } } }, "/api/convert/json-to-yaml": { "get": { "summary": "Convert JSON to YAML 1.2, quoting strings that YAML 1.1 parsers would misread.", "description": "Parses `input` strictly as JSON and writes it as a YAML 1.2 document (block style, no `---` marker, no line folding). Key order is kept unless `sort_keys` is set; integers keep every digit; `1.0` stays `1.0`. Strings that a YAML 1.1 parser would read as something else (`yes`, `no`, `on`, `off`, `y`, `n`, `0755`, `1:20`, `2024-01-01`, `<<`, …) or that YAML 1.2 would read as a number, boolean or null are double-quoted, so the output means the same under both versions. Multi-line strings use literal block scalars (`|`). Duplicate keys keep the last value, with a warning.\n\nPrivacy: The server receives the JSON text, processes it in memory inside the request, and returns the result. Your input is not stored or logged; only the per-call metadata row (operation, time, status, sizes) is recorded. The server makes no network requests. For confidential documents use the page, which does the same work in your browser and sends nothing.", "tags": [ "yaml" ], "responses": { "200": { "description": "Success. With format=text, text/plain is returned instead of JSON.", "content": { "application/json": { "schema": { "type": "object", "description": "", "properties": { "yaml": { "type": "string", "description": "The YAML document, ending with a newline." }, "warnings": { "type": "array", "items": { "type": "object", "description": "", "properties": { "message": { "type": "string", "description": "Plain-language finding." }, "pointer": { "type": "string", "description": "JSON Pointer of the value concerned." }, "line": { "type": "integer", "description": "1-based line number." }, "column": { "type": "integer", "description": "1-based column, counted in Unicode code points." }, "offset": { "type": "integer", "description": "0-based offset in code points." } }, "required": [ "message", "pointer", "line", "column", "offset" ], "additionalProperties": false }, "description": "Valid-but-risky findings: integers beyond 2^53 − 1, numbers that overflow a double, unpaired surrogate escapes, duplicate keys. At most 100 are listed." } }, "required": [ "yaml", "warnings" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "The YAML document." } } } }, "400": { "description": "missing_parameter / unknown_parameter / `input` is longer than 100,000 characters, or `indent` is outside 2–8.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`input` is not valid JSON; the message gives the line, column and offset and how to fix it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "json_to_yaml_get", "parameters": [ { "name": "input", "in": "query", "required": true, "description": "The JSON text, as a string field or a raw text/plain POST body.", "schema": { "description": "The JSON text, as a string field or a raw text/plain POST body.", "type": "string" } }, { "name": "indent", "in": "query", "required": false, "description": "Spaces per YAML indentation level.", "schema": { "description": "Spaces per YAML indentation level.", "type": "integer", "default": 2, "minimum": 2, "maximum": 8 } }, { "name": "sort_keys", "in": "query", "required": false, "description": "Sort object keys recursively, by UTF-16 code units (the order RFC 8785 uses). Array order never changes.", "schema": { "description": "Sort object keys recursively, by UTF-16 code units (the order RFC 8785 uses). Array order never changes.", "type": "boolean", "default": false } }, { "name": "format", "in": "query", "required": false, "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "schema": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } } ] }, "post": { "summary": "Convert JSON to YAML 1.2, quoting strings that YAML 1.1 parsers would misread.", "description": "Parses `input` strictly as JSON and writes it as a YAML 1.2 document (block style, no `---` marker, no line folding). Key order is kept unless `sort_keys` is set; integers keep every digit; `1.0` stays `1.0`. Strings that a YAML 1.1 parser would read as something else (`yes`, `no`, `on`, `off`, `y`, `n`, `0755`, `1:20`, `2024-01-01`, `<<`, …) or that YAML 1.2 would read as a number, boolean or null are double-quoted, so the output means the same under both versions. Multi-line strings use literal block scalars (`|`). Duplicate keys keep the last value, with a warning.\n\nPrivacy: The server receives the JSON text, processes it in memory inside the request, and returns the result. Your input is not stored or logged; only the per-call metadata row (operation, time, status, sizes) is recorded. The server makes no network requests. For confidential documents use the page, which does the same work in your browser and sends nothing.", "tags": [ "yaml" ], "responses": { "200": { "description": "Success. With format=text, text/plain is returned instead of JSON.", "content": { "application/json": { "schema": { "type": "object", "description": "", "properties": { "yaml": { "type": "string", "description": "The YAML document, ending with a newline." }, "warnings": { "type": "array", "items": { "type": "object", "description": "", "properties": { "message": { "type": "string", "description": "Plain-language finding." }, "pointer": { "type": "string", "description": "JSON Pointer of the value concerned." }, "line": { "type": "integer", "description": "1-based line number." }, "column": { "type": "integer", "description": "1-based column, counted in Unicode code points." }, "offset": { "type": "integer", "description": "0-based offset in code points." } }, "required": [ "message", "pointer", "line", "column", "offset" ], "additionalProperties": false }, "description": "Valid-but-risky findings: integers beyond 2^53 − 1, numbers that overflow a double, unpaired surrogate escapes, duplicate keys. At most 100 are listed." } }, "required": [ "yaml", "warnings" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "The YAML document." } } } }, "400": { "description": "missing_parameter / unknown_parameter / `input` is longer than 100,000 characters, or `indent` is outside 2–8.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`input` is not valid JSON; the message gives the line, column and offset and how to fix it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "json_to_yaml", "parameters": [ { "name": "format", "in": "query", "required": false, "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "schema": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "input": { "description": "The JSON text, as a string field or a raw text/plain POST body.", "type": "string" }, "indent": { "description": "Spaces per YAML indentation level.", "type": "integer", "default": 2, "minimum": 2, "maximum": 8 }, "sort_keys": { "description": "Sort object keys recursively, by UTF-16 code units (the order RFC 8785 uses). Array order never changes.", "type": "boolean", "default": false }, "format": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } }, "required": [ "input" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "The body is used as the `input` parameter." } } } } } }, "/api/convert/yaml-to-json": { "get": { "summary": "Convert YAML to JSON under pinned YAML 1.2 core-schema rules, with line/column errors and YAML 1.1 pitfall warnings.", "description": "Parses `input` as YAML 1.2 with the core schema, whatever any `%YAML` directive says, so `yes`/`no`/`on`/`off` are strings, `0755` is the decimal 755, and dates stay strings; each such value gets a warning because YAML 1.1 parsers read them differently. Duplicate keys are an error. Aliases are expanded, with at most 1,000 expansions and 200,000 output values (billion-laughs protection); recursive aliases are an error. `<<` merge keys are applied unless `merge_keys` is false. `.inf`/`.nan` and complex (collection) keys are errors; non-string scalar keys become strings with a warning. Tags outside the core schema (`!!binary`, `!!timestamp`, `!Ref`, …) follow `custom_tags`. Errors give line, column and code.\n\nPrivacy: The server receives the YAML text, processes it in memory inside the request, and returns the result. Your input is not stored or logged; only the per-call metadata row (operation, time, status, sizes) is recorded. The server makes no network requests. For confidential documents use the page, which does the same work in your browser and sends nothing.", "tags": [ "yaml" ], "responses": { "200": { "description": "Success. With format=text, text/plain is returned instead of JSON.", "content": { "application/json": { "schema": { "type": "object", "description": "", "properties": { "json": { "type": "string", "description": "The JSON text, formatted per `indent`." }, "value": { "description": "The same data as a JSON value." }, "documentCount": { "type": "integer", "description": "Number of YAML documents in the input." }, "warnings": { "type": "array", "items": { "type": "object", "description": "", "properties": { "message": { "type": "string", "description": "Plain-language finding." }, "line": { "type": "integer", "description": "1-based line number." }, "column": { "type": "integer", "description": "1-based column, counted in Unicode code points." }, "pointer": { "type": "string", "description": "JSON Pointer of the value in the output." } }, "required": [ "message", "line", "column", "pointer" ], "additionalProperties": false }, "description": "YAML 1.1/1.2 ambiguities, converted keys, extra documents, large integers. At most 100 are listed." } }, "required": [ "json", "value", "documentCount", "warnings" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "The JSON text." } } } }, "400": { "description": "missing_parameter / unknown_parameter / `input` is longer than 30,000 characters (YAML parsing is the slowest step; use the page for larger files), or an option is not a listed value.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The YAML does not parse (the message gives line, column and the library error code), has duplicate keys, uses a value with no JSON equivalent, a custom tag with `custom_tags=error`, a recursive alias, or exceeds the alias or size limits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "yaml_to_json_get", "parameters": [ { "name": "input", "in": "query", "required": true, "description": "The YAML text, as a string field or a raw text/plain POST body.", "schema": { "description": "The YAML text, as a string field or a raw text/plain POST body.", "type": "string" } }, { "name": "documents", "in": "query", "required": false, "description": "first converts the first document (with a warning if there are more; no documents gives null). all returns a JSON array with one element per document.", "schema": { "description": "first converts the first document (with a warning if there are more; no documents gives null). all returns a JSON array with one element per document.", "type": "string", "enum": [ "first", "all" ], "default": "first" } }, { "name": "indent", "in": "query", "required": false, "description": "JSON output indentation: 2 or 4 spaces, tab, or none for minified output (no whitespace at all).", "schema": { "description": "JSON output indentation: 2 or 4 spaces, tab, or none for minified output (no whitespace at all).", "type": "string", "enum": [ "2", "4", "tab", "none" ], "default": "2" } }, { "name": "sort_keys", "in": "query", "required": false, "description": "Sort object keys recursively, by UTF-16 code units (the order RFC 8785 uses). Array order never changes.", "schema": { "description": "Sort object keys recursively, by UTF-16 code units (the order RFC 8785 uses). Array order never changes.", "type": "boolean", "default": false } }, { "name": "merge_keys", "in": "query", "required": false, "description": "Apply << merge keys (YAML 1.1 feature, common in Compose and CI files). false keeps << as an ordinary key.", "schema": { "description": "Apply << merge keys (YAML 1.1 feature, common in Compose and CI files). false keeps << as an ordinary key.", "type": "boolean", "default": true } }, { "name": "custom_tags", "in": "query", "required": false, "description": "Values with a tag outside the core schema: error rejects them; drop keeps the value and discards the tag; wrap produces {\"\": value}, e.g. {\"!Ref\": \"MyBucket\"}.", "schema": { "description": "Values with a tag outside the core schema: error rejects them; drop keeps the value and discards the tag; wrap produces {\"\": value}, e.g. {\"!Ref\": \"MyBucket\"}.", "type": "string", "enum": [ "error", "drop", "wrap" ], "default": "error" } }, { "name": "format", "in": "query", "required": false, "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "schema": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } } ] }, "post": { "summary": "Convert YAML to JSON under pinned YAML 1.2 core-schema rules, with line/column errors and YAML 1.1 pitfall warnings.", "description": "Parses `input` as YAML 1.2 with the core schema, whatever any `%YAML` directive says, so `yes`/`no`/`on`/`off` are strings, `0755` is the decimal 755, and dates stay strings; each such value gets a warning because YAML 1.1 parsers read them differently. Duplicate keys are an error. Aliases are expanded, with at most 1,000 expansions and 200,000 output values (billion-laughs protection); recursive aliases are an error. `<<` merge keys are applied unless `merge_keys` is false. `.inf`/`.nan` and complex (collection) keys are errors; non-string scalar keys become strings with a warning. Tags outside the core schema (`!!binary`, `!!timestamp`, `!Ref`, …) follow `custom_tags`. Errors give line, column and code.\n\nPrivacy: The server receives the YAML text, processes it in memory inside the request, and returns the result. Your input is not stored or logged; only the per-call metadata row (operation, time, status, sizes) is recorded. The server makes no network requests. For confidential documents use the page, which does the same work in your browser and sends nothing.", "tags": [ "yaml" ], "responses": { "200": { "description": "Success. With format=text, text/plain is returned instead of JSON.", "content": { "application/json": { "schema": { "type": "object", "description": "", "properties": { "json": { "type": "string", "description": "The JSON text, formatted per `indent`." }, "value": { "description": "The same data as a JSON value." }, "documentCount": { "type": "integer", "description": "Number of YAML documents in the input." }, "warnings": { "type": "array", "items": { "type": "object", "description": "", "properties": { "message": { "type": "string", "description": "Plain-language finding." }, "line": { "type": "integer", "description": "1-based line number." }, "column": { "type": "integer", "description": "1-based column, counted in Unicode code points." }, "pointer": { "type": "string", "description": "JSON Pointer of the value in the output." } }, "required": [ "message", "line", "column", "pointer" ], "additionalProperties": false }, "description": "YAML 1.1/1.2 ambiguities, converted keys, extra documents, large integers. At most 100 are listed." } }, "required": [ "json", "value", "documentCount", "warnings" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "The JSON text." } } } }, "400": { "description": "missing_parameter / unknown_parameter / `input` is longer than 30,000 characters (YAML parsing is the slowest step; use the page for larger files), or an option is not a listed value.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The YAML does not parse (the message gives line, column and the library error code), has duplicate keys, uses a value with no JSON equivalent, a custom tag with `custom_tags=error`, a recursive alias, or exceeds the alias or size limits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "yaml_to_json", "parameters": [ { "name": "format", "in": "query", "required": false, "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "schema": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "input": { "description": "The YAML text, as a string field or a raw text/plain POST body.", "type": "string" }, "documents": { "description": "first converts the first document (with a warning if there are more; no documents gives null). all returns a JSON array with one element per document.", "type": "string", "enum": [ "first", "all" ], "default": "first" }, "indent": { "description": "JSON output indentation: 2 or 4 spaces, tab, or none for minified output (no whitespace at all).", "type": "string", "enum": [ "2", "4", "tab", "none" ], "default": "2" }, "sort_keys": { "description": "Sort object keys recursively, by UTF-16 code units (the order RFC 8785 uses). Array order never changes.", "type": "boolean", "default": false }, "merge_keys": { "description": "Apply << merge keys (YAML 1.1 feature, common in Compose and CI files). false keeps << as an ordinary key.", "type": "boolean", "default": true }, "custom_tags": { "description": "Values with a tag outside the core schema: error rejects them; drop keeps the value and discards the tag; wrap produces {\"\": value}, e.g. {\"!Ref\": \"MyBucket\"}.", "type": "string", "enum": [ "error", "drop", "wrap" ], "default": "error" }, "format": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } }, "required": [ "input" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "The body is used as the `input` parameter." } } } } } }, "/api/json/query": { "get": { "summary": "Evaluate a JMESPath expression against JSON and return the result, its type and pretty JSON.", "description": "Evaluates `expression` against `input` with @jmespath-community/jmespath (JMESPath Community Edition): the original JMESPath language plus `let` expressions, `$` for the root, arithmetic (`+ - * / % //`), the ternary `? :` operator, and extra functions such as `items`, `from_items`, `group_by`, `zip`, `find_first`, `pad_left`, `split`, `replace`, `trim`. A path that does not exist gives `null` (not an error). Syntax errors give the column of the offending token; unknown functions are reported before evaluation; type errors (for example `length` of a number) are reported with the function position.\n\nPrivacy: The server receives the JSON document and the expression, processes it in memory inside the request, and returns the result. Your input is not stored or logged; only the per-call metadata row (operation, time, status, sizes) is recorded. The server makes no network requests. For confidential documents use the page, which does the same work in your browser and sends nothing.", "tags": [ "json-query" ], "responses": { "200": { "description": "Success. With format=text, text/plain is returned instead of JSON.", "content": { "application/json": { "schema": { "type": "object", "description": "", "properties": { "result": { "description": "The result as a JSON value (null when nothing matched)." }, "type": { "type": "string", "description": "JSON type of the result.", "enum": [ "object", "array", "string", "number", "boolean", "null" ] }, "json": { "type": "string", "description": "The result as JSON text, formatted per `indent`." }, "warnings": { "type": "array", "items": { "type": "object", "description": "", "properties": { "message": { "type": "string", "description": "Plain-language finding." }, "pointer": { "type": "string", "description": "JSON Pointer of the value concerned." }, "line": { "type": "integer", "description": "1-based line number." }, "column": { "type": "integer", "description": "1-based column, counted in Unicode code points." }, "offset": { "type": "integer", "description": "0-based offset in code points." } }, "required": [ "message", "pointer", "line", "column", "offset" ], "additionalProperties": false }, "description": "Valid-but-risky findings: integers beyond 2^53 − 1, numbers that overflow a double, unpaired surrogate escapes, duplicate keys. At most 100 are listed." } }, "required": [ "result", "type", "json", "warnings" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "The result as JSON text." } } } }, "400": { "description": "missing_parameter / unknown_parameter / `input` exceeds 500,000 characters or `expression` exceeds 2,048.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`input` is not valid JSON (line, column and offset given); `expression` has a syntax error (column given) or calls an unknown function; or evaluation fails (a function received the wrong type, division by zero, a slice step of 0).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "json_query_get", "parameters": [ { "name": "input", "in": "query", "required": true, "description": "The JSON document, as JSON text (string field or raw text/plain POST body).", "schema": { "description": "The JSON document, as JSON text (string field or raw text/plain POST body).", "type": "string" } }, { "name": "expression", "in": "query", "required": true, "description": "The JMESPath expression, e.g. sort_by(items, &price)[-1].name. JSON literals are written between backtick characters; raw strings go in single quotes.", "schema": { "description": "The JMESPath expression, e.g. sort_by(items, &price)[-1].name. JSON literals are written between backtick characters; raw strings go in single quotes.", "type": "string" } }, { "name": "indent", "in": "query", "required": false, "description": "JSON output indentation: 2 or 4 spaces, tab, or none for minified output (no whitespace at all).", "schema": { "description": "JSON output indentation: 2 or 4 spaces, tab, or none for minified output (no whitespace at all).", "type": "string", "enum": [ "2", "4", "tab", "none" ], "default": "2" } }, { "name": "format", "in": "query", "required": false, "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "schema": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } } ] }, "post": { "summary": "Evaluate a JMESPath expression against JSON and return the result, its type and pretty JSON.", "description": "Evaluates `expression` against `input` with @jmespath-community/jmespath (JMESPath Community Edition): the original JMESPath language plus `let` expressions, `$` for the root, arithmetic (`+ - * / % //`), the ternary `? :` operator, and extra functions such as `items`, `from_items`, `group_by`, `zip`, `find_first`, `pad_left`, `split`, `replace`, `trim`. A path that does not exist gives `null` (not an error). Syntax errors give the column of the offending token; unknown functions are reported before evaluation; type errors (for example `length` of a number) are reported with the function position.\n\nPrivacy: The server receives the JSON document and the expression, processes it in memory inside the request, and returns the result. Your input is not stored or logged; only the per-call metadata row (operation, time, status, sizes) is recorded. The server makes no network requests. For confidential documents use the page, which does the same work in your browser and sends nothing.", "tags": [ "json-query" ], "responses": { "200": { "description": "Success. With format=text, text/plain is returned instead of JSON.", "content": { "application/json": { "schema": { "type": "object", "description": "", "properties": { "result": { "description": "The result as a JSON value (null when nothing matched)." }, "type": { "type": "string", "description": "JSON type of the result.", "enum": [ "object", "array", "string", "number", "boolean", "null" ] }, "json": { "type": "string", "description": "The result as JSON text, formatted per `indent`." }, "warnings": { "type": "array", "items": { "type": "object", "description": "", "properties": { "message": { "type": "string", "description": "Plain-language finding." }, "pointer": { "type": "string", "description": "JSON Pointer of the value concerned." }, "line": { "type": "integer", "description": "1-based line number." }, "column": { "type": "integer", "description": "1-based column, counted in Unicode code points." }, "offset": { "type": "integer", "description": "0-based offset in code points." } }, "required": [ "message", "pointer", "line", "column", "offset" ], "additionalProperties": false }, "description": "Valid-but-risky findings: integers beyond 2^53 − 1, numbers that overflow a double, unpaired surrogate escapes, duplicate keys. At most 100 are listed." } }, "required": [ "result", "type", "json", "warnings" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "The result as JSON text." } } } }, "400": { "description": "missing_parameter / unknown_parameter / `input` exceeds 500,000 characters or `expression` exceeds 2,048.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`input` is not valid JSON (line, column and offset given); `expression` has a syntax error (column given) or calls an unknown function; or evaluation fails (a function received the wrong type, division by zero, a slice step of 0).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "json_query", "parameters": [ { "name": "format", "in": "query", "required": false, "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "schema": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "input": { "description": "The JSON document, as JSON text (string field or raw text/plain POST body).", "type": "string" }, "expression": { "description": "The JMESPath expression, e.g. sort_by(items, &price)[-1].name. JSON literals are written between backtick characters; raw strings go in single quotes.", "type": "string" }, "indent": { "description": "JSON output indentation: 2 or 4 spaces, tab, or none for minified output (no whitespace at all).", "type": "string", "enum": [ "2", "4", "tab", "none" ], "default": "2" }, "format": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } }, "required": [ "input", "expression" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "The body is used as the `input` parameter." } } } } } }, "/api/yaml/format": { "get": { "summary": "Check YAML against yamllint’s rules (same rule IDs) and return the findings with positions, plus a comment-preserving formatted copy.", "description": "Parses `input` as YAML 1.2 (core schema) and reports every finding with its rule, severity, line, column and offset. Rules follow yamllint's default set and names: `syntax`, `key-duplicates`, `anchors`, `braces`, `brackets`, `colons`, `commas`, `comments`, `comments-indentation`, `document-start`, `empty-lines`, `empty-values`, `hyphens`, `indentation`, `line-length`, `new-line-at-end-of-file`, `new-lines`, `octal-values`, `quoted-strings`, `trailing-spaces`, `truthy`, `byte-order-mark`. Errors (`syntax`, `key-duplicates`, an alias without an anchor) make the document invalid; everything else is a warning or info. An invalid document is still a 200 response, with `valid: false`, the findings, and `formatted` and `value` set to null. When the YAML is valid, `formatted` is the document re-written with the chosen indentation, one space after colons and hyphens, no padding inside `{}`/`[]`, at most one blank line in a row, LF line breaks and a final newline. Comments, anchors, tags, key order, block scalars and the text of numbers are kept; quotes are removed only where the plain form means the same string in YAML 1.2 and 1.1 (`\"yes\"`, `\"0755\"`, `\"null\"` stay quoted). The formatted text is re-parsed and compared with the input before it is returned, so it always has the same value. `value` is the data as JSON: the first document's value, or an array of all documents when there are several (merge keys applied, at most 1,000 alias expansions).\n\nPrivacy: The server receives the YAML text and the options, processes them in memory inside the request, and returns the result. Your input is not stored or logged; only the per-call metadata row (operation, time, status, sizes) is recorded. The server makes no network requests. For confidential documents use the page, which does the same work in your browser and sends nothing.", "tags": [ "yaml" ], "responses": { "200": { "description": "Success. With format=text, text/plain is returned instead of JSON.", "content": { "application/json": { "schema": { "type": "object", "description": "", "properties": { "valid": { "type": "boolean", "description": "True when there are no `error` findings: the YAML parses, has no duplicate keys and every alias has an anchor." }, "summary": { "type": "object", "description": "", "properties": { "valid": { "type": "boolean", "description": "True when there are no `error` findings." }, "errors": { "type": "integer", "description": "Number of errors." }, "warnings": { "type": "integer", "description": "Number of warnings." }, "infos": { "type": "integer", "description": "Number of informational findings." } }, "required": [ "valid", "errors", "warnings", "infos" ], "additionalProperties": false }, "diagnostics": { "type": "array", "items": { "type": "object", "description": "One lint finding.", "properties": { "rule": { "type": "string", "description": "Rule ID, e.g. `syntax`, `duplicate-keys`, `trailing-spaces`." }, "severity": { "type": "string", "description": "`error` makes the document invalid; `warning` and `info` are style.", "enum": [ "error", "warning", "info" ] }, "message": { "type": "string", "description": "What is wrong and how to fix it." }, "line": { "type": "integer", "description": "1-based line where the problem starts." }, "column": { "type": "integer", "description": "1-based column (Unicode code points)." }, "offset": { "type": "integer", "description": "0-based UTF-16 offset into the input." }, "endLine": { "type": "integer", "description": "1-based end line, when the problem spans a range." }, "endColumn": { "type": "integer", "description": "1-based end column." }, "endOffset": { "type": "integer", "description": "0-based end offset." } }, "required": [ "rule", "severity", "message", "line", "column", "offset" ], "additionalProperties": false }, "description": "Findings in document order." }, "documents": { "type": "integer", "description": "Number of YAML documents in the input (0 for an empty or comment-only input)." }, "formatted": { "type": [ "string", "null" ], "description": "The formatted YAML, ending with a newline (empty for an empty input); null when the YAML is invalid." }, "value": { "description": "The data as JSON: the first document’s value, or an array of every document’s value when there are several; null when invalid. Integers beyond 2^53 − 1 lose precision; `.inf` and `.nan` become null." } }, "required": [ "valid", "summary", "diagnostics", "documents", "formatted", "value" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "The formatted YAML; when the YAML is invalid, one finding per line (`line:column severity rule message`)." } } } }, "400": { "description": "missing_parameter / unknown_parameter / `input` is longer than 15,000 characters (use the page for larger files), or an option is not a listed value.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "yaml_format_get", "parameters": [ { "name": "input", "in": "query", "required": true, "description": "The YAML text, as a string field or a raw text/plain POST body.", "schema": { "description": "The YAML text, as a string field or a raw text/plain POST body.", "type": "string" } }, { "name": "indent", "in": "query", "required": false, "description": "Spaces per indentation level, for the indentation rule and the formatted output.", "schema": { "description": "Spaces per indentation level, for the indentation rule and the formatted output.", "type": "integer", "enum": [ 2, 4 ], "default": 2 } }, { "name": "indent_sequences", "in": "query", "required": false, "description": "How a sequence under a mapping key is indented: indented (key: then - item), flush (- item at the key’s column), or consistent (either, as long as the whole file does the same; the first one decides). yamllint’s indent-sequences.", "schema": { "description": "How a sequence under a mapping key is indented: indented (key: then - item), flush (- item at the key’s column), or consistent (either, as long as the whole file does the same; the first one decides). yamllint’s indent-sequences.", "type": "string", "enum": [ "consistent", "indented", "flush" ], "default": "consistent" } }, { "name": "max_line_length", "in": "query", "required": false, "description": "Longest allowed line, in characters, for the line-length rule; 0 turns the rule off. The default is 120 (yamllint’s is 80, which most Kubernetes and CI files exceed).", "schema": { "description": "Longest allowed line, in characters, for the line-length rule; 0 turns the rule off. The default is 120 (yamllint’s is 80, which most Kubernetes and CI files exceed).", "type": "integer", "default": 120, "minimum": 0, "maximum": 1000 } }, { "name": "document_start", "in": "query", "required": false, "description": "require: every document starts with ---. forbid: the first document has no ---. ignore: either. Applies to the findings and the formatted output.", "schema": { "description": "require: every document starts with ---. forbid: the first document has no ---. ignore: either. Applies to the findings and the formatted output.", "type": "string", "enum": [ "ignore", "require", "forbid" ], "default": "ignore" } }, { "name": "quote_style", "in": "query", "required": false, "description": "single or double: quoted values should use that quote character (quoted-strings rule), and the formatter converts them. any: no check, and the formatter removes quotes that are not needed.", "schema": { "description": "single or double: quoted values should use that quote character (quoted-strings rule), and the formatter converts them. any: no check, and the formatter removes quotes that are not needed.", "type": "string", "enum": [ "any", "single", "double" ], "default": "any" } }, { "name": "format", "in": "query", "required": false, "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "schema": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } } ] }, "post": { "summary": "Check YAML against yamllint’s rules (same rule IDs) and return the findings with positions, plus a comment-preserving formatted copy.", "description": "Parses `input` as YAML 1.2 (core schema) and reports every finding with its rule, severity, line, column and offset. Rules follow yamllint's default set and names: `syntax`, `key-duplicates`, `anchors`, `braces`, `brackets`, `colons`, `commas`, `comments`, `comments-indentation`, `document-start`, `empty-lines`, `empty-values`, `hyphens`, `indentation`, `line-length`, `new-line-at-end-of-file`, `new-lines`, `octal-values`, `quoted-strings`, `trailing-spaces`, `truthy`, `byte-order-mark`. Errors (`syntax`, `key-duplicates`, an alias without an anchor) make the document invalid; everything else is a warning or info. An invalid document is still a 200 response, with `valid: false`, the findings, and `formatted` and `value` set to null. When the YAML is valid, `formatted` is the document re-written with the chosen indentation, one space after colons and hyphens, no padding inside `{}`/`[]`, at most one blank line in a row, LF line breaks and a final newline. Comments, anchors, tags, key order, block scalars and the text of numbers are kept; quotes are removed only where the plain form means the same string in YAML 1.2 and 1.1 (`\"yes\"`, `\"0755\"`, `\"null\"` stay quoted). The formatted text is re-parsed and compared with the input before it is returned, so it always has the same value. `value` is the data as JSON: the first document's value, or an array of all documents when there are several (merge keys applied, at most 1,000 alias expansions).\n\nPrivacy: The server receives the YAML text and the options, processes them in memory inside the request, and returns the result. Your input is not stored or logged; only the per-call metadata row (operation, time, status, sizes) is recorded. The server makes no network requests. For confidential documents use the page, which does the same work in your browser and sends nothing.", "tags": [ "yaml" ], "responses": { "200": { "description": "Success. With format=text, text/plain is returned instead of JSON.", "content": { "application/json": { "schema": { "type": "object", "description": "", "properties": { "valid": { "type": "boolean", "description": "True when there are no `error` findings: the YAML parses, has no duplicate keys and every alias has an anchor." }, "summary": { "type": "object", "description": "", "properties": { "valid": { "type": "boolean", "description": "True when there are no `error` findings." }, "errors": { "type": "integer", "description": "Number of errors." }, "warnings": { "type": "integer", "description": "Number of warnings." }, "infos": { "type": "integer", "description": "Number of informational findings." } }, "required": [ "valid", "errors", "warnings", "infos" ], "additionalProperties": false }, "diagnostics": { "type": "array", "items": { "type": "object", "description": "One lint finding.", "properties": { "rule": { "type": "string", "description": "Rule ID, e.g. `syntax`, `duplicate-keys`, `trailing-spaces`." }, "severity": { "type": "string", "description": "`error` makes the document invalid; `warning` and `info` are style.", "enum": [ "error", "warning", "info" ] }, "message": { "type": "string", "description": "What is wrong and how to fix it." }, "line": { "type": "integer", "description": "1-based line where the problem starts." }, "column": { "type": "integer", "description": "1-based column (Unicode code points)." }, "offset": { "type": "integer", "description": "0-based UTF-16 offset into the input." }, "endLine": { "type": "integer", "description": "1-based end line, when the problem spans a range." }, "endColumn": { "type": "integer", "description": "1-based end column." }, "endOffset": { "type": "integer", "description": "0-based end offset." } }, "required": [ "rule", "severity", "message", "line", "column", "offset" ], "additionalProperties": false }, "description": "Findings in document order." }, "documents": { "type": "integer", "description": "Number of YAML documents in the input (0 for an empty or comment-only input)." }, "formatted": { "type": [ "string", "null" ], "description": "The formatted YAML, ending with a newline (empty for an empty input); null when the YAML is invalid." }, "value": { "description": "The data as JSON: the first document’s value, or an array of every document’s value when there are several; null when invalid. Integers beyond 2^53 − 1 lose precision; `.inf` and `.nan` become null." } }, "required": [ "valid", "summary", "diagnostics", "documents", "formatted", "value" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "The formatted YAML; when the YAML is invalid, one finding per line (`line:column severity rule message`)." } } } }, "400": { "description": "missing_parameter / unknown_parameter / `input` is longer than 15,000 characters (use the page for larger files), or an option is not a listed value.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "yaml_format", "parameters": [ { "name": "format", "in": "query", "required": false, "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "schema": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "input": { "description": "The YAML text, as a string field or a raw text/plain POST body.", "type": "string" }, "indent": { "description": "Spaces per indentation level, for the indentation rule and the formatted output.", "type": "integer", "enum": [ 2, 4 ], "default": 2 }, "indent_sequences": { "description": "How a sequence under a mapping key is indented: indented (key: then - item), flush (- item at the key’s column), or consistent (either, as long as the whole file does the same; the first one decides). yamllint’s indent-sequences.", "type": "string", "enum": [ "consistent", "indented", "flush" ], "default": "consistent" }, "max_line_length": { "description": "Longest allowed line, in characters, for the line-length rule; 0 turns the rule off. The default is 120 (yamllint’s is 80, which most Kubernetes and CI files exceed).", "type": "integer", "default": 120, "minimum": 0, "maximum": 1000 }, "document_start": { "description": "require: every document starts with ---. forbid: the first document has no ---. ignore: either. Applies to the findings and the formatted output.", "type": "string", "enum": [ "ignore", "require", "forbid" ], "default": "ignore" }, "quote_style": { "description": "single or double: quoted values should use that quote character (quoted-strings rule), and the formatter converts them. any: no check, and the formatter removes quotes that are not needed.", "type": "string", "enum": [ "any", "single", "double" ], "default": "any" }, "format": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } }, "required": [ "input" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "The body is used as the `input` parameter." } } } } } }, "/api/json/lint": { "get": { "summary": "Validate JSON strictly and report every lint finding with its position.", "description": "Parses `input` as strict RFC 8259 JSON and runs the lint rules: `syntax`, `duplicate-keys`, `number-precision`, `string-encoding`, `indent-style`, `indent`, `trailing-spaces`, `final-newline`, `line-endings`, `byte-order-mark`, `line-length`. Every finding has a rule ID, severity, message, line, column and offset. Invalid JSON is a 200 response with `valid: false`. Use `json_format` for the formatted output and statistics.\n\nPrivacy: The server receives the JSON text, lints it in memory and returns the findings. Your input is not stored or logged; only the per-call metadata row (operation, time, status, sizes) is recorded.", "tags": [ "json" ], "responses": { "200": { "description": "Success. With format=text, text/plain is returned instead of JSON.", "content": { "application/json": { "schema": { "type": "object", "description": "", "properties": { "valid": { "type": "boolean", "description": "No error findings." }, "summary": { "type": "object", "description": "", "properties": { "valid": { "type": "boolean", "description": "True when there are no `error` findings." }, "errors": { "type": "integer", "description": "Number of errors." }, "warnings": { "type": "integer", "description": "Number of warnings." }, "infos": { "type": "integer", "description": "Number of informational findings." } }, "required": [ "valid", "errors", "warnings", "infos" ], "additionalProperties": false }, "diagnostics": { "type": "array", "items": { "type": "object", "description": "One lint finding.", "properties": { "rule": { "type": "string", "description": "Rule ID, e.g. `syntax`, `duplicate-keys`, `trailing-spaces`." }, "severity": { "type": "string", "description": "`error` makes the document invalid; `warning` and `info` are style.", "enum": [ "error", "warning", "info" ] }, "message": { "type": "string", "description": "What is wrong and how to fix it." }, "line": { "type": "integer", "description": "1-based line where the problem starts." }, "column": { "type": "integer", "description": "1-based column (Unicode code points)." }, "offset": { "type": "integer", "description": "0-based UTF-16 offset into the input." }, "endLine": { "type": "integer", "description": "1-based end line, when the problem spans a range." }, "endColumn": { "type": "integer", "description": "1-based end column." }, "endOffset": { "type": "integer", "description": "0-based end offset." } }, "required": [ "rule", "severity", "message", "line", "column", "offset" ], "additionalProperties": false }, "description": "Findings in document order." } }, "required": [ "valid", "summary", "diagnostics" ], "additionalProperties": false } } } }, "400": { "description": "missing_parameter / unknown_parameter / invalid_parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "json_lint_get", "parameters": [ { "name": "input", "in": "query", "required": true, "description": "JSON text, up to 500,000 characters.", "schema": { "description": "JSON text, up to 500,000 characters.", "type": "string" } }, { "name": "indent", "in": "query", "required": false, "description": "Expected indentation unit for the indent rule.", "schema": { "description": "Expected indentation unit for the indent rule.", "type": "string", "enum": [ "2", "4", "tab", "none" ], "default": "2" } }, { "name": "max_line_length", "in": "query", "required": false, "description": "Limit for the line-length rule; 0 disables it.", "schema": { "description": "Limit for the line-length rule; 0 disables it.", "type": "integer", "default": 120, "minimum": 0, "maximum": 10000 } }, { "name": "format", "in": "query", "required": false, "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "schema": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } } ] }, "post": { "summary": "Validate JSON strictly and report every lint finding with its position.", "description": "Parses `input` as strict RFC 8259 JSON and runs the lint rules: `syntax`, `duplicate-keys`, `number-precision`, `string-encoding`, `indent-style`, `indent`, `trailing-spaces`, `final-newline`, `line-endings`, `byte-order-mark`, `line-length`. Every finding has a rule ID, severity, message, line, column and offset. Invalid JSON is a 200 response with `valid: false`. Use `json_format` for the formatted output and statistics.\n\nPrivacy: The server receives the JSON text, lints it in memory and returns the findings. Your input is not stored or logged; only the per-call metadata row (operation, time, status, sizes) is recorded.", "tags": [ "json" ], "responses": { "200": { "description": "Success. With format=text, text/plain is returned instead of JSON.", "content": { "application/json": { "schema": { "type": "object", "description": "", "properties": { "valid": { "type": "boolean", "description": "No error findings." }, "summary": { "type": "object", "description": "", "properties": { "valid": { "type": "boolean", "description": "True when there are no `error` findings." }, "errors": { "type": "integer", "description": "Number of errors." }, "warnings": { "type": "integer", "description": "Number of warnings." }, "infos": { "type": "integer", "description": "Number of informational findings." } }, "required": [ "valid", "errors", "warnings", "infos" ], "additionalProperties": false }, "diagnostics": { "type": "array", "items": { "type": "object", "description": "One lint finding.", "properties": { "rule": { "type": "string", "description": "Rule ID, e.g. `syntax`, `duplicate-keys`, `trailing-spaces`." }, "severity": { "type": "string", "description": "`error` makes the document invalid; `warning` and `info` are style.", "enum": [ "error", "warning", "info" ] }, "message": { "type": "string", "description": "What is wrong and how to fix it." }, "line": { "type": "integer", "description": "1-based line where the problem starts." }, "column": { "type": "integer", "description": "1-based column (Unicode code points)." }, "offset": { "type": "integer", "description": "0-based UTF-16 offset into the input." }, "endLine": { "type": "integer", "description": "1-based end line, when the problem spans a range." }, "endColumn": { "type": "integer", "description": "1-based end column." }, "endOffset": { "type": "integer", "description": "0-based end offset." } }, "required": [ "rule", "severity", "message", "line", "column", "offset" ], "additionalProperties": false }, "description": "Findings in document order." } }, "required": [ "valid", "summary", "diagnostics" ], "additionalProperties": false } } } }, "400": { "description": "missing_parameter / unknown_parameter / invalid_parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "json_lint", "parameters": [ { "name": "format", "in": "query", "required": false, "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "schema": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "input": { "description": "JSON text, up to 500,000 characters.", "type": "string" }, "indent": { "description": "Expected indentation unit for the indent rule.", "type": "string", "enum": [ "2", "4", "tab", "none" ], "default": "2" }, "max_line_length": { "description": "Limit for the line-length rule; 0 disables it.", "type": "integer", "default": 120, "minimum": 0, "maximum": 10000 }, "format": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } }, "required": [ "input" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "The body is used as the `input` parameter." } } } } } }, "/api/csv/format": { "get": { "summary": "Check CSV against RFC 4180, detect the delimiter and header, infer column types, list every problem with its position, and rewrite it consistently.", "description": "Parses `input` as RFC 4180 CSV, also accepting semicolon, tab and pipe delimiters and LF or CR line breaks. Reports every problem as a diagnostic with a stable rule ID, severity, line, column and offset: unclosed quotes, stray quotes, text after a closing quote, rows with the wrong number of fields (errors); empty and duplicate header names, padded delimiters, blank lines, mixed line endings (warnings); and mixed column types, inconsistent quoting, trailing delimiters and values a spreadsheet could run as formulas (info). Invalid CSV is a successful response with `valid: false`, so check `valid`. `formatted` is the data rewritten with one delimiter, one quoting style and one line ending, blank lines and the byte-order mark removed, ending with a line break; it is null only when an unclosed quote makes the structure unknowable. Rows themselves are not returned: `preview` holds the first 20 data rows. At most 100 diagnostics are listed per rule, then one summarising the rest.\n\nPrivacy: The server receives the CSV text, processes it in memory inside the request, and returns the result. Your input is not stored or logged; only the per-call metadata row (operation, time, status, sizes) is recorded. The server makes no network requests. For confidential data use the page, which does the same work in your browser and sends nothing.", "tags": [ "csv" ], "responses": { "200": { "description": "Success. With format=text, text/plain is returned instead of JSON.", "content": { "application/json": { "schema": { "type": "object", "description": "", "properties": { "valid": { "type": "boolean", "description": "True when there are no `error` diagnostics." }, "summary": { "type": "object", "description": "", "properties": { "valid": { "type": "boolean", "description": "True when there are no `error` findings." }, "errors": { "type": "integer", "description": "Number of errors." }, "warnings": { "type": "integer", "description": "Number of warnings." }, "infos": { "type": "integer", "description": "Number of informational findings." } }, "required": [ "valid", "errors", "warnings", "infos" ], "additionalProperties": false }, "diagnostics": { "type": "array", "items": { "type": "object", "description": "One lint finding.", "properties": { "rule": { "type": "string", "description": "Rule ID, e.g. `syntax`, `duplicate-keys`, `trailing-spaces`." }, "severity": { "type": "string", "description": "`error` makes the document invalid; `warning` and `info` are style.", "enum": [ "error", "warning", "info" ] }, "message": { "type": "string", "description": "What is wrong and how to fix it." }, "line": { "type": "integer", "description": "1-based line where the problem starts." }, "column": { "type": "integer", "description": "1-based column (Unicode code points)." }, "offset": { "type": "integer", "description": "0-based UTF-16 offset into the input." }, "endLine": { "type": "integer", "description": "1-based end line, when the problem spans a range." }, "endColumn": { "type": "integer", "description": "1-based end column." }, "endOffset": { "type": "integer", "description": "0-based end offset." } }, "required": [ "rule", "severity", "message", "line", "column", "offset" ], "additionalProperties": false }, "description": "Findings in document order." }, "dialect": { "type": "object", "description": "How the input was read.", "properties": { "delimiter": { "type": "string", "description": "The delimiter used to read the input (a tab is `\"\\t\"`).", "enum": [ ",", ";", "\t", "|" ] }, "delimiterDetected": { "type": "boolean", "description": "True when the delimiter was detected rather than given (false when detection fell back to comma)." }, "lineEnding": { "type": "string", "description": "Line breaks between rows (line breaks inside quoted values are not counted).", "enum": [ "lf", "crlf", "cr", "mixed", "none" ] }, "hasHeader": { "type": "boolean", "description": "True when the first row is treated as the header." }, "headerDetected": { "type": "boolean", "description": "True when that decision came from the heuristic (`header=auto`)." }, "bom": { "type": "boolean", "description": "True when the input starts with a byte-order mark." } }, "required": [ "delimiter", "delimiterDetected", "lineEnding", "hasHeader", "headerDetected", "bom" ], "additionalProperties": false }, "header": { "type": [ "array", "null" ], "items": { "type": "string", "description": "Header name." }, "description": "The header row; null when there is none." }, "columnCount": { "type": "integer", "description": "Expected fields per row: the header length, or the most common row length." }, "rowCount": { "type": "integer", "description": "Data rows (the header is not counted)." }, "columns": { "type": "array", "items": { "type": "object", "description": "", "properties": { "name": { "type": "string", "description": "Header name, or `Column N` without a header." }, "type": { "type": "string", "description": "Inferred type of the non-empty values: `integer`, `number` (integers and decimals), `boolean` (true/false), `date` (YYYY-MM-DD), `datetime` (ISO 8601), `text`, `mixed`, or `empty` when every value is empty.", "enum": [ "empty", "integer", "number", "boolean", "date", "datetime", "text", "mixed" ] }, "empty": { "type": "integer", "description": "Empty (or missing) values." }, "distinct": { "type": "integer", "description": "Distinct non-empty values." }, "maxLength": { "type": "integer", "description": "Longest value, in Unicode code points." } }, "required": [ "name", "type", "empty", "distinct", "maxLength" ], "additionalProperties": false }, "description": "One entry per column." }, "preview": { "type": "array", "items": { "type": "array", "items": { "type": "string", "description": "A value." }, "description": "One row." }, "description": "The first 20 data rows." }, "formatted": { "type": [ "string", "null" ], "description": "The normalised CSV; null when an unclosed quote makes the structure unknowable." } }, "required": [ "valid", "summary", "diagnostics", "dialect", "header", "columnCount", "rowCount", "columns", "preview", "formatted" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "The formatted CSV when valid; otherwise one line per error: `line L, column C: [rule] message`." } } } }, "400": { "description": "missing_parameter / unknown_parameter / `input` is longer than 100,000 characters, or an option is not a listed value. Invalid CSV is NOT an error: it returns 200 with `valid: false`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "csv_format_get", "parameters": [ { "name": "input", "in": "query", "required": true, "description": "The CSV text. Send it as a string field or as a raw text/plain POST body.", "schema": { "description": "The CSV text. Send it as a string field or as a raw text/plain POST body.", "type": "string" } }, { "name": "delimiter", "in": "query", "required": false, "description": "Field delimiter of the input: comma, semicolon, tab or pipe. auto picks the one that gives the most consistent field count over the first 50 records, ignoring quoted text, and falls back to comma.", "schema": { "description": "Field delimiter of the input: comma, semicolon, tab or pipe. auto picks the one that gives the most consistent field count over the first 50 records, ignoring quoted text, and falls back to comma.", "type": "string", "enum": [ "auto", "comma", "semicolon", "tab", "pipe" ], "default": "auto" } }, { "name": "header", "in": "query", "required": false, "description": "Whether the first row is a header. auto says yes when its values are all text (no numbers, booleans or dates), all different, and none repeats in its column below.", "schema": { "description": "Whether the first row is a header. auto says yes when its values are all text (no numbers, booleans or dates), all different, and none repeats in its column below.", "type": "string", "enum": [ "auto", "yes", "no" ], "default": "auto" } }, { "name": "trim_fields", "in": "query", "required": false, "description": "Remove spaces and tabs around unquoted values. Quoted values are always kept exactly.", "schema": { "description": "Remove spaces and tabs around unquoted values. Quoted values are always kept exactly.", "type": "boolean", "default": false } }, { "name": "quoting", "in": "query", "required": false, "description": "minimal quotes only values that need it (a delimiter, quote or line break, or leading/trailing whitespace); all quotes every value; nonnumeric quotes everything except numbers.", "schema": { "description": "minimal quotes only values that need it (a delimiter, quote or line break, or leading/trailing whitespace); all quotes every value; nonnumeric quotes everything except numbers.", "type": "string", "enum": [ "minimal", "all", "nonnumeric" ], "default": "minimal" } }, { "name": "line_ending", "in": "query", "required": false, "description": "Line break written after every row. crlf is what RFC 4180 specifies; lf is what most tools write, and every reader accepts both.", "schema": { "description": "Line break written after every row. crlf is what RFC 4180 specifies; lf is what most tools write, and every reader accepts both.", "type": "string", "enum": [ "lf", "crlf" ], "default": "lf" } }, { "name": "output_delimiter", "in": "query", "required": false, "description": "Delimiter for the formatted output; same keeps the input delimiter.", "schema": { "description": "Delimiter for the formatted output; same keeps the input delimiter.", "type": "string", "enum": [ "same", "comma", "semicolon", "tab", "pipe" ], "default": "same" } }, { "name": "format", "in": "query", "required": false, "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "schema": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } } ] }, "post": { "summary": "Check CSV against RFC 4180, detect the delimiter and header, infer column types, list every problem with its position, and rewrite it consistently.", "description": "Parses `input` as RFC 4180 CSV, also accepting semicolon, tab and pipe delimiters and LF or CR line breaks. Reports every problem as a diagnostic with a stable rule ID, severity, line, column and offset: unclosed quotes, stray quotes, text after a closing quote, rows with the wrong number of fields (errors); empty and duplicate header names, padded delimiters, blank lines, mixed line endings (warnings); and mixed column types, inconsistent quoting, trailing delimiters and values a spreadsheet could run as formulas (info). Invalid CSV is a successful response with `valid: false`, so check `valid`. `formatted` is the data rewritten with one delimiter, one quoting style and one line ending, blank lines and the byte-order mark removed, ending with a line break; it is null only when an unclosed quote makes the structure unknowable. Rows themselves are not returned: `preview` holds the first 20 data rows. At most 100 diagnostics are listed per rule, then one summarising the rest.\n\nPrivacy: The server receives the CSV text, processes it in memory inside the request, and returns the result. Your input is not stored or logged; only the per-call metadata row (operation, time, status, sizes) is recorded. The server makes no network requests. For confidential data use the page, which does the same work in your browser and sends nothing.", "tags": [ "csv" ], "responses": { "200": { "description": "Success. With format=text, text/plain is returned instead of JSON.", "content": { "application/json": { "schema": { "type": "object", "description": "", "properties": { "valid": { "type": "boolean", "description": "True when there are no `error` diagnostics." }, "summary": { "type": "object", "description": "", "properties": { "valid": { "type": "boolean", "description": "True when there are no `error` findings." }, "errors": { "type": "integer", "description": "Number of errors." }, "warnings": { "type": "integer", "description": "Number of warnings." }, "infos": { "type": "integer", "description": "Number of informational findings." } }, "required": [ "valid", "errors", "warnings", "infos" ], "additionalProperties": false }, "diagnostics": { "type": "array", "items": { "type": "object", "description": "One lint finding.", "properties": { "rule": { "type": "string", "description": "Rule ID, e.g. `syntax`, `duplicate-keys`, `trailing-spaces`." }, "severity": { "type": "string", "description": "`error` makes the document invalid; `warning` and `info` are style.", "enum": [ "error", "warning", "info" ] }, "message": { "type": "string", "description": "What is wrong and how to fix it." }, "line": { "type": "integer", "description": "1-based line where the problem starts." }, "column": { "type": "integer", "description": "1-based column (Unicode code points)." }, "offset": { "type": "integer", "description": "0-based UTF-16 offset into the input." }, "endLine": { "type": "integer", "description": "1-based end line, when the problem spans a range." }, "endColumn": { "type": "integer", "description": "1-based end column." }, "endOffset": { "type": "integer", "description": "0-based end offset." } }, "required": [ "rule", "severity", "message", "line", "column", "offset" ], "additionalProperties": false }, "description": "Findings in document order." }, "dialect": { "type": "object", "description": "How the input was read.", "properties": { "delimiter": { "type": "string", "description": "The delimiter used to read the input (a tab is `\"\\t\"`).", "enum": [ ",", ";", "\t", "|" ] }, "delimiterDetected": { "type": "boolean", "description": "True when the delimiter was detected rather than given (false when detection fell back to comma)." }, "lineEnding": { "type": "string", "description": "Line breaks between rows (line breaks inside quoted values are not counted).", "enum": [ "lf", "crlf", "cr", "mixed", "none" ] }, "hasHeader": { "type": "boolean", "description": "True when the first row is treated as the header." }, "headerDetected": { "type": "boolean", "description": "True when that decision came from the heuristic (`header=auto`)." }, "bom": { "type": "boolean", "description": "True when the input starts with a byte-order mark." } }, "required": [ "delimiter", "delimiterDetected", "lineEnding", "hasHeader", "headerDetected", "bom" ], "additionalProperties": false }, "header": { "type": [ "array", "null" ], "items": { "type": "string", "description": "Header name." }, "description": "The header row; null when there is none." }, "columnCount": { "type": "integer", "description": "Expected fields per row: the header length, or the most common row length." }, "rowCount": { "type": "integer", "description": "Data rows (the header is not counted)." }, "columns": { "type": "array", "items": { "type": "object", "description": "", "properties": { "name": { "type": "string", "description": "Header name, or `Column N` without a header." }, "type": { "type": "string", "description": "Inferred type of the non-empty values: `integer`, `number` (integers and decimals), `boolean` (true/false), `date` (YYYY-MM-DD), `datetime` (ISO 8601), `text`, `mixed`, or `empty` when every value is empty.", "enum": [ "empty", "integer", "number", "boolean", "date", "datetime", "text", "mixed" ] }, "empty": { "type": "integer", "description": "Empty (or missing) values." }, "distinct": { "type": "integer", "description": "Distinct non-empty values." }, "maxLength": { "type": "integer", "description": "Longest value, in Unicode code points." } }, "required": [ "name", "type", "empty", "distinct", "maxLength" ], "additionalProperties": false }, "description": "One entry per column." }, "preview": { "type": "array", "items": { "type": "array", "items": { "type": "string", "description": "A value." }, "description": "One row." }, "description": "The first 20 data rows." }, "formatted": { "type": [ "string", "null" ], "description": "The normalised CSV; null when an unclosed quote makes the structure unknowable." } }, "required": [ "valid", "summary", "diagnostics", "dialect", "header", "columnCount", "rowCount", "columns", "preview", "formatted" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "The formatted CSV when valid; otherwise one line per error: `line L, column C: [rule] message`." } } } }, "400": { "description": "missing_parameter / unknown_parameter / `input` is longer than 100,000 characters, or an option is not a listed value. Invalid CSV is NOT an error: it returns 200 with `valid: false`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "csv_format", "parameters": [ { "name": "format", "in": "query", "required": false, "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "schema": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "input": { "description": "The CSV text. Send it as a string field or as a raw text/plain POST body.", "type": "string" }, "delimiter": { "description": "Field delimiter of the input: comma, semicolon, tab or pipe. auto picks the one that gives the most consistent field count over the first 50 records, ignoring quoted text, and falls back to comma.", "type": "string", "enum": [ "auto", "comma", "semicolon", "tab", "pipe" ], "default": "auto" }, "header": { "description": "Whether the first row is a header. auto says yes when its values are all text (no numbers, booleans or dates), all different, and none repeats in its column below.", "type": "string", "enum": [ "auto", "yes", "no" ], "default": "auto" }, "trim_fields": { "description": "Remove spaces and tabs around unquoted values. Quoted values are always kept exactly.", "type": "boolean", "default": false }, "quoting": { "description": "minimal quotes only values that need it (a delimiter, quote or line break, or leading/trailing whitespace); all quotes every value; nonnumeric quotes everything except numbers.", "type": "string", "enum": [ "minimal", "all", "nonnumeric" ], "default": "minimal" }, "line_ending": { "description": "Line break written after every row. crlf is what RFC 4180 specifies; lf is what most tools write, and every reader accepts both.", "type": "string", "enum": [ "lf", "crlf" ], "default": "lf" }, "output_delimiter": { "description": "Delimiter for the formatted output; same keeps the input delimiter.", "type": "string", "enum": [ "same", "comma", "semicolon", "tab", "pipe" ], "default": "same" }, "format": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } }, "required": [ "input" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "The body is used as the `input` parameter." } } } } } }, "/api/convert/csv-to-json": { "get": { "summary": "Convert CSV to a JSON array of objects (keyed by the header) or of arrays, optionally typing numbers and booleans.", "description": "Reads `input` exactly as `/api/csv/format` does (same delimiter and header detection) and converts it to JSON. `shape=objects` gives one object per row, keyed by the header names (an empty name becomes `column_N`; a repeated name gets `_2`, `_3`, …). `shape=arrays` gives one array per row, the header row first. `auto` is objects when there is a header. Without `types` every value is a string, exactly as written. With `types`, a column whose values are all integers or numbers becomes JSON numbers (every digit kept, even beyond 2^53), a true/false column becomes booleans, and empty values become `null`; text, date and mixed columns stay strings. CSV with errors (see the format operation) is rejected rather than guessed at.\n\nPrivacy: The server receives the CSV text, processes it in memory inside the request, and returns the result. Your input is not stored or logged; only the per-call metadata row (operation, time, status, sizes) is recorded. The server makes no network requests. For confidential data use the page, which does the same work in your browser and sends nothing.", "tags": [ "csv" ], "responses": { "200": { "description": "Success. With format=text, text/plain is returned instead of JSON.", "content": { "application/json": { "schema": { "type": "object", "description": "", "properties": { "json": { "type": "string", "description": "The JSON text (2-space indentation)." }, "value": { "description": "The same data as a JSON value." }, "shape": { "type": "string", "description": "The shape used.", "enum": [ "objects", "arrays" ] }, "header": { "type": [ "array", "null" ], "items": { "type": "string", "description": "Header name." }, "description": "The header row; null when there is none." }, "rowCount": { "type": "integer", "description": "Data rows converted." }, "columns": { "type": "array", "items": { "type": "object", "description": "", "properties": { "name": { "type": "string", "description": "Header name, or `Column N` without a header." }, "type": { "type": "string", "description": "Inferred type of the non-empty values: `integer`, `number` (integers and decimals), `boolean` (true/false), `date` (YYYY-MM-DD), `datetime` (ISO 8601), `text`, `mixed`, or `empty` when every value is empty.", "enum": [ "empty", "integer", "number", "boolean", "date", "datetime", "text", "mixed" ] }, "empty": { "type": "integer", "description": "Empty (or missing) values." }, "distinct": { "type": "integer", "description": "Distinct non-empty values." }, "maxLength": { "type": "integer", "description": "Longest value, in Unicode code points." } }, "required": [ "name", "type", "empty", "distinct", "maxLength" ], "additionalProperties": false }, "description": "One entry per column." }, "dialect": { "type": "object", "description": "How the input was read.", "properties": { "delimiter": { "type": "string", "description": "The delimiter used to read the input (a tab is `\"\\t\"`).", "enum": [ ",", ";", "\t", "|" ] }, "delimiterDetected": { "type": "boolean", "description": "True when the delimiter was detected rather than given (false when detection fell back to comma)." }, "lineEnding": { "type": "string", "description": "Line breaks between rows (line breaks inside quoted values are not counted).", "enum": [ "lf", "crlf", "cr", "mixed", "none" ] }, "hasHeader": { "type": "boolean", "description": "True when the first row is treated as the header." }, "headerDetected": { "type": "boolean", "description": "True when that decision came from the heuristic (`header=auto`)." }, "bom": { "type": "boolean", "description": "True when the input starts with a byte-order mark." } }, "required": [ "delimiter", "delimiterDetected", "lineEnding", "hasHeader", "headerDetected", "bom" ], "additionalProperties": false } }, "required": [ "json", "value", "shape", "header", "rowCount", "columns", "dialect" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "The JSON text." } } } }, "400": { "description": "missing_parameter / unknown_parameter / `input` is longer than 50,000 characters, or an option is not a listed value.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The CSV has an error (unclosed or stray quote, text after a quote, a row with the wrong number of fields; the message gives line and column), or `shape=objects` and there is no header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "csv_to_json_get", "parameters": [ { "name": "input", "in": "query", "required": true, "description": "The CSV text. Send it as a string field or as a raw text/plain POST body.", "schema": { "description": "The CSV text. Send it as a string field or as a raw text/plain POST body.", "type": "string" } }, { "name": "delimiter", "in": "query", "required": false, "description": "Field delimiter of the input: comma, semicolon, tab or pipe. auto picks the one that gives the most consistent field count over the first 50 records, ignoring quoted text, and falls back to comma.", "schema": { "description": "Field delimiter of the input: comma, semicolon, tab or pipe. auto picks the one that gives the most consistent field count over the first 50 records, ignoring quoted text, and falls back to comma.", "type": "string", "enum": [ "auto", "comma", "semicolon", "tab", "pipe" ], "default": "auto" } }, { "name": "header", "in": "query", "required": false, "description": "Whether the first row is a header. auto says yes when its values are all text (no numbers, booleans or dates), all different, and none repeats in its column below.", "schema": { "description": "Whether the first row is a header. auto says yes when its values are all text (no numbers, booleans or dates), all different, and none repeats in its column below.", "type": "string", "enum": [ "auto", "yes", "no" ], "default": "auto" } }, { "name": "trim_fields", "in": "query", "required": false, "description": "Remove spaces and tabs around unquoted values. Quoted values are always kept exactly.", "schema": { "description": "Remove spaces and tabs around unquoted values. Quoted values are always kept exactly.", "type": "boolean", "default": false } }, { "name": "shape", "in": "query", "required": false, "description": "objects (needs a header), arrays, or auto: objects when there is a header, arrays otherwise.", "schema": { "description": "objects (needs a header), arrays, or auto: objects when there is a header, arrays otherwise.", "type": "string", "enum": [ "auto", "objects", "arrays" ], "default": "auto" } }, { "name": "types", "in": "query", "required": false, "description": "Convert number and boolean columns to JSON numbers and booleans, and empty values to null.", "schema": { "description": "Convert number and boolean columns to JSON numbers and booleans, and empty values to null.", "type": "boolean", "default": false } }, { "name": "format", "in": "query", "required": false, "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "schema": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } } ] }, "post": { "summary": "Convert CSV to a JSON array of objects (keyed by the header) or of arrays, optionally typing numbers and booleans.", "description": "Reads `input` exactly as `/api/csv/format` does (same delimiter and header detection) and converts it to JSON. `shape=objects` gives one object per row, keyed by the header names (an empty name becomes `column_N`; a repeated name gets `_2`, `_3`, …). `shape=arrays` gives one array per row, the header row first. `auto` is objects when there is a header. Without `types` every value is a string, exactly as written. With `types`, a column whose values are all integers or numbers becomes JSON numbers (every digit kept, even beyond 2^53), a true/false column becomes booleans, and empty values become `null`; text, date and mixed columns stay strings. CSV with errors (see the format operation) is rejected rather than guessed at.\n\nPrivacy: The server receives the CSV text, processes it in memory inside the request, and returns the result. Your input is not stored or logged; only the per-call metadata row (operation, time, status, sizes) is recorded. The server makes no network requests. For confidential data use the page, which does the same work in your browser and sends nothing.", "tags": [ "csv" ], "responses": { "200": { "description": "Success. With format=text, text/plain is returned instead of JSON.", "content": { "application/json": { "schema": { "type": "object", "description": "", "properties": { "json": { "type": "string", "description": "The JSON text (2-space indentation)." }, "value": { "description": "The same data as a JSON value." }, "shape": { "type": "string", "description": "The shape used.", "enum": [ "objects", "arrays" ] }, "header": { "type": [ "array", "null" ], "items": { "type": "string", "description": "Header name." }, "description": "The header row; null when there is none." }, "rowCount": { "type": "integer", "description": "Data rows converted." }, "columns": { "type": "array", "items": { "type": "object", "description": "", "properties": { "name": { "type": "string", "description": "Header name, or `Column N` without a header." }, "type": { "type": "string", "description": "Inferred type of the non-empty values: `integer`, `number` (integers and decimals), `boolean` (true/false), `date` (YYYY-MM-DD), `datetime` (ISO 8601), `text`, `mixed`, or `empty` when every value is empty.", "enum": [ "empty", "integer", "number", "boolean", "date", "datetime", "text", "mixed" ] }, "empty": { "type": "integer", "description": "Empty (or missing) values." }, "distinct": { "type": "integer", "description": "Distinct non-empty values." }, "maxLength": { "type": "integer", "description": "Longest value, in Unicode code points." } }, "required": [ "name", "type", "empty", "distinct", "maxLength" ], "additionalProperties": false }, "description": "One entry per column." }, "dialect": { "type": "object", "description": "How the input was read.", "properties": { "delimiter": { "type": "string", "description": "The delimiter used to read the input (a tab is `\"\\t\"`).", "enum": [ ",", ";", "\t", "|" ] }, "delimiterDetected": { "type": "boolean", "description": "True when the delimiter was detected rather than given (false when detection fell back to comma)." }, "lineEnding": { "type": "string", "description": "Line breaks between rows (line breaks inside quoted values are not counted).", "enum": [ "lf", "crlf", "cr", "mixed", "none" ] }, "hasHeader": { "type": "boolean", "description": "True when the first row is treated as the header." }, "headerDetected": { "type": "boolean", "description": "True when that decision came from the heuristic (`header=auto`)." }, "bom": { "type": "boolean", "description": "True when the input starts with a byte-order mark." } }, "required": [ "delimiter", "delimiterDetected", "lineEnding", "hasHeader", "headerDetected", "bom" ], "additionalProperties": false } }, "required": [ "json", "value", "shape", "header", "rowCount", "columns", "dialect" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "The JSON text." } } } }, "400": { "description": "missing_parameter / unknown_parameter / `input` is longer than 50,000 characters, or an option is not a listed value.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The CSV has an error (unclosed or stray quote, text after a quote, a row with the wrong number of fields; the message gives line and column), or `shape=objects` and there is no header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "csv_to_json", "parameters": [ { "name": "format", "in": "query", "required": false, "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "schema": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "input": { "description": "The CSV text. Send it as a string field or as a raw text/plain POST body.", "type": "string" }, "delimiter": { "description": "Field delimiter of the input: comma, semicolon, tab or pipe. auto picks the one that gives the most consistent field count over the first 50 records, ignoring quoted text, and falls back to comma.", "type": "string", "enum": [ "auto", "comma", "semicolon", "tab", "pipe" ], "default": "auto" }, "header": { "description": "Whether the first row is a header. auto says yes when its values are all text (no numbers, booleans or dates), all different, and none repeats in its column below.", "type": "string", "enum": [ "auto", "yes", "no" ], "default": "auto" }, "trim_fields": { "description": "Remove spaces and tabs around unquoted values. Quoted values are always kept exactly.", "type": "boolean", "default": false }, "shape": { "description": "objects (needs a header), arrays, or auto: objects when there is a header, arrays otherwise.", "type": "string", "enum": [ "auto", "objects", "arrays" ], "default": "auto" }, "types": { "description": "Convert number and boolean columns to JSON numbers and booleans, and empty values to null.", "type": "boolean", "default": false }, "format": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } }, "required": [ "input" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "The body is used as the `input` parameter." } } } } } }, "/api/convert/json-to-csv": { "get": { "summary": "Convert a JSON array of objects or of arrays to CSV, with the union of keys as the header.", "description": "Parses `input` strictly as JSON. An array of objects becomes one row per object, with a header made of every key in first-seen order (a missing key gives an empty cell); a single object becomes one row. An array of arrays becomes one row per array, with no header. Strings are written as they are, numbers exactly as written in the JSON (`1.0` and 20-digit integers survive), booleans as `true`/`false`, `null` as an empty cell, and nested objects or arrays as compact JSON text (listed in `notes`). Values are quoted per `quoting`.\n\nPrivacy: The server receives the JSON text, processes it in memory inside the request, and returns the result. Your input is not stored or logged; only the per-call metadata row (operation, time, status, sizes) is recorded. The server makes no network requests. For confidential data use the page, which does the same work in your browser and sends nothing.", "tags": [ "csv" ], "responses": { "200": { "description": "Success. With format=text, text/plain is returned instead of JSON.", "content": { "application/json": { "schema": { "type": "object", "description": "", "properties": { "csv": { "type": "string", "description": "The CSV text, ending with a line break (empty for an empty array)." }, "header": { "type": [ "array", "null" ], "items": { "type": "string", "description": "Header name." }, "description": "The header row; null when there is none." }, "rowCount": { "type": "integer", "description": "Data rows written." }, "columnCount": { "type": "integer", "description": "Columns (the longest row, for arrays of arrays)." }, "notes": { "type": "array", "items": { "type": "string", "description": "A note." }, "description": "What was adapted: nested values written as JSON, missing keys, ragged arrays." } }, "required": [ "csv", "header", "rowCount", "columnCount", "notes" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "The CSV text." } } } }, "400": { "description": "missing_parameter / unknown_parameter / `input` is longer than 200,000 characters, or an option is not a listed value.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`input` is not valid JSON (line and column given), or is not an array of objects, an array of arrays, or an object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "json_to_csv_get", "parameters": [ { "name": "input", "in": "query", "required": true, "description": "The JSON text: an array of objects, an array of arrays, or one object. Send it as a string field or as a raw text/plain POST body.", "schema": { "description": "The JSON text: an array of objects, an array of arrays, or one object. Send it as a string field or as a raw text/plain POST body.", "type": "string" } }, { "name": "delimiter", "in": "query", "required": false, "description": "Delimiter for the output: comma, semicolon, tab or pipe.", "schema": { "description": "Delimiter for the output: comma, semicolon, tab or pipe.", "type": "string", "enum": [ "comma", "semicolon", "tab", "pipe" ], "default": "comma" } }, { "name": "header", "in": "query", "required": false, "description": "Write the header row (arrays of objects only).", "schema": { "description": "Write the header row (arrays of objects only).", "type": "boolean", "default": true } }, { "name": "quoting", "in": "query", "required": false, "description": "minimal quotes only values that need it (a delimiter, quote or line break, or leading/trailing whitespace); all quotes every value; nonnumeric quotes everything except numbers.", "schema": { "description": "minimal quotes only values that need it (a delimiter, quote or line break, or leading/trailing whitespace); all quotes every value; nonnumeric quotes everything except numbers.", "type": "string", "enum": [ "minimal", "all", "nonnumeric" ], "default": "minimal" } }, { "name": "line_ending", "in": "query", "required": false, "description": "Line break written after every row. crlf is what RFC 4180 specifies; lf is what most tools write, and every reader accepts both.", "schema": { "description": "Line break written after every row. crlf is what RFC 4180 specifies; lf is what most tools write, and every reader accepts both.", "type": "string", "enum": [ "lf", "crlf" ], "default": "lf" } }, { "name": "format", "in": "query", "required": false, "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "schema": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } } ] }, "post": { "summary": "Convert a JSON array of objects or of arrays to CSV, with the union of keys as the header.", "description": "Parses `input` strictly as JSON. An array of objects becomes one row per object, with a header made of every key in first-seen order (a missing key gives an empty cell); a single object becomes one row. An array of arrays becomes one row per array, with no header. Strings are written as they are, numbers exactly as written in the JSON (`1.0` and 20-digit integers survive), booleans as `true`/`false`, `null` as an empty cell, and nested objects or arrays as compact JSON text (listed in `notes`). Values are quoted per `quoting`.\n\nPrivacy: The server receives the JSON text, processes it in memory inside the request, and returns the result. Your input is not stored or logged; only the per-call metadata row (operation, time, status, sizes) is recorded. The server makes no network requests. For confidential data use the page, which does the same work in your browser and sends nothing.", "tags": [ "csv" ], "responses": { "200": { "description": "Success. With format=text, text/plain is returned instead of JSON.", "content": { "application/json": { "schema": { "type": "object", "description": "", "properties": { "csv": { "type": "string", "description": "The CSV text, ending with a line break (empty for an empty array)." }, "header": { "type": [ "array", "null" ], "items": { "type": "string", "description": "Header name." }, "description": "The header row; null when there is none." }, "rowCount": { "type": "integer", "description": "Data rows written." }, "columnCount": { "type": "integer", "description": "Columns (the longest row, for arrays of arrays)." }, "notes": { "type": "array", "items": { "type": "string", "description": "A note." }, "description": "What was adapted: nested values written as JSON, missing keys, ragged arrays." } }, "required": [ "csv", "header", "rowCount", "columnCount", "notes" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "The CSV text." } } } }, "400": { "description": "missing_parameter / unknown_parameter / `input` is longer than 200,000 characters, or an option is not a listed value.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`input` is not valid JSON (line and column given), or is not an array of objects, an array of arrays, or an object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "json_to_csv", "parameters": [ { "name": "format", "in": "query", "required": false, "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "schema": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "input": { "description": "The JSON text: an array of objects, an array of arrays, or one object. Send it as a string field or as a raw text/plain POST body.", "type": "string" }, "delimiter": { "description": "Delimiter for the output: comma, semicolon, tab or pipe.", "type": "string", "enum": [ "comma", "semicolon", "tab", "pipe" ], "default": "comma" }, "header": { "description": "Write the header row (arrays of objects only).", "type": "boolean", "default": true }, "quoting": { "description": "minimal quotes only values that need it (a delimiter, quote or line break, or leading/trailing whitespace); all quotes every value; nonnumeric quotes everything except numbers.", "type": "string", "enum": [ "minimal", "all", "nonnumeric" ], "default": "minimal" }, "line_ending": { "description": "Line break written after every row. crlf is what RFC 4180 specifies; lf is what most tools write, and every reader accepts both.", "type": "string", "enum": [ "lf", "crlf" ], "default": "lf" }, "format": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } }, "required": [ "input" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "The body is used as the `input` parameter." } } } } } }, "/api/toml/format": { "get": { "summary": "Check that text is valid TOML 1.0, list problems with line and column, and re-format it with comments kept.", "description": "Parses `input` as TOML 1.0.0 and returns every finding as a diagnostic with a rule ID, severity, line, column and offset: syntax errors, duplicate keys and tables, integers beyond 64 bits (errors); TOML 1.1-only syntax, inconsistent indentation, trailing spaces, mixed line endings (warnings); unnecessary key quotes, split or out-of-order tables, long inline tables, empty tables, long lines (info). Only the first syntax error is reported. An invalid document is a successful response with `valid: false`, so check `valid`. For a valid document it also returns the canonical formatting and the data as JSON. Formatting keeps every comment and never changes the data: keys are written `key = value` with one space around `=`, indentation and trailing spaces are removed, there is one blank line before each table header, arrays longer than `max_line_length` are broken one element per line, and the text ends with one line break. Strings, numbers and dates are copied as written. In `value`, integers beyond ±(2^53 − 1) are decimal strings, `inf`/`nan` are the strings `\"inf\"`, `\"-inf\"` and `\"nan\"`, and dates and times are ISO 8601 strings.\n\nPrivacy: The server receives the TOML text, processes it in memory inside the request, and returns the result. Your input is not stored or logged; only the per-call metadata row (operation, time, status, sizes) is recorded. The server makes no network requests. For confidential documents use the page, which does the same work in your browser and sends nothing.", "tags": [ "toml" ], "responses": { "200": { "description": "Success. With format=text, text/plain is returned instead of JSON.", "content": { "application/json": { "schema": { "type": "object", "description": "", "properties": { "valid": { "type": "boolean", "description": "True when there are no `error` findings." }, "summary": { "type": "object", "description": "", "properties": { "valid": { "type": "boolean", "description": "True when there are no `error` findings." }, "errors": { "type": "integer", "description": "Number of errors." }, "warnings": { "type": "integer", "description": "Number of warnings." }, "infos": { "type": "integer", "description": "Number of informational findings." } }, "required": [ "valid", "errors", "warnings", "infos" ], "additionalProperties": false }, "diagnostics": { "type": "array", "items": { "type": "object", "description": "One lint finding.", "properties": { "rule": { "type": "string", "description": "Rule ID, e.g. `syntax`, `duplicate-keys`, `trailing-spaces`." }, "severity": { "type": "string", "description": "`error` makes the document invalid; `warning` and `info` are style.", "enum": [ "error", "warning", "info" ] }, "message": { "type": "string", "description": "What is wrong and how to fix it." }, "line": { "type": "integer", "description": "1-based line where the problem starts." }, "column": { "type": "integer", "description": "1-based column (Unicode code points)." }, "offset": { "type": "integer", "description": "0-based UTF-16 offset into the input." }, "endLine": { "type": "integer", "description": "1-based end line, when the problem spans a range." }, "endColumn": { "type": "integer", "description": "1-based end column." }, "endOffset": { "type": "integer", "description": "0-based end offset." } }, "required": [ "rule", "severity", "message", "line", "column", "offset" ], "additionalProperties": false }, "description": "Findings in document order." }, "formatted": { "type": [ "string", "null" ], "description": "The formatted document, comments kept; null when invalid." }, "value": { "description": "The document as JSON (see the value mapping in the docs); null when invalid." }, "stats": { "type": "object", "description": "Counts for a valid document; all zero when invalid.", "properties": { "tables": { "type": "integer", "description": "Tables below the root: [table] sections, dotted-key tables, inline tables and each [[array]] element." }, "keys": { "type": "integer", "description": "Keys in all tables." }, "arrays": { "type": "integer", "description": "Arrays, including arrays of tables." }, "depth": { "type": "integer", "description": "Nesting depth: 1 for a flat document, one more per level of table or array." } }, "required": [ "tables", "keys", "arrays", "depth" ], "additionalProperties": false } }, "required": [ "valid", "summary", "diagnostics", "formatted", "value", "stats" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "The formatted TOML, or for invalid input one line: `invalid: line L, column C: message`." } } } }, "400": { "description": "missing_parameter / unknown_parameter / `input` is longer than 50,000 characters, or an option is out of range. Invalid TOML is NOT an error: it returns 200 with `valid: false`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "toml_format_get", "parameters": [ { "name": "input", "in": "query", "required": true, "description": "The TOML text. Send it as a string field or as a raw text/plain POST body.", "schema": { "description": "The TOML text. Send it as a string field or as a raw text/plain POST body.", "type": "string" } }, { "name": "indent", "in": "query", "required": false, "description": "Spaces per level for arrays that are broken over several lines.", "schema": { "description": "Spaces per level for arrays that are broken over several lines.", "type": "integer", "default": 2, "minimum": 1, "maximum": 8 } }, { "name": "max_line_length", "in": "query", "required": false, "description": "Arrays longer than this are broken one element per line, and longer lines are reported (line-length). 0 turns both off.", "schema": { "description": "Arrays longer than this are broken one element per line, and longer lines are reported (line-length). 0 turns both off.", "type": "integer", "default": 120, "minimum": 0, "maximum": 1000 } }, { "name": "sort_keys", "in": "query", "required": false, "description": "Sort keys within each table, by UTF-16 code units. Tables keep their order (the order of [[array]] tables is data).", "schema": { "description": "Sort keys within each table, by UTF-16 code units. Tables keep their order (the order of [[array]] tables is data).", "type": "boolean", "default": false } }, { "name": "format", "in": "query", "required": false, "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "schema": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } } ] }, "post": { "summary": "Check that text is valid TOML 1.0, list problems with line and column, and re-format it with comments kept.", "description": "Parses `input` as TOML 1.0.0 and returns every finding as a diagnostic with a rule ID, severity, line, column and offset: syntax errors, duplicate keys and tables, integers beyond 64 bits (errors); TOML 1.1-only syntax, inconsistent indentation, trailing spaces, mixed line endings (warnings); unnecessary key quotes, split or out-of-order tables, long inline tables, empty tables, long lines (info). Only the first syntax error is reported. An invalid document is a successful response with `valid: false`, so check `valid`. For a valid document it also returns the canonical formatting and the data as JSON. Formatting keeps every comment and never changes the data: keys are written `key = value` with one space around `=`, indentation and trailing spaces are removed, there is one blank line before each table header, arrays longer than `max_line_length` are broken one element per line, and the text ends with one line break. Strings, numbers and dates are copied as written. In `value`, integers beyond ±(2^53 − 1) are decimal strings, `inf`/`nan` are the strings `\"inf\"`, `\"-inf\"` and `\"nan\"`, and dates and times are ISO 8601 strings.\n\nPrivacy: The server receives the TOML text, processes it in memory inside the request, and returns the result. Your input is not stored or logged; only the per-call metadata row (operation, time, status, sizes) is recorded. The server makes no network requests. For confidential documents use the page, which does the same work in your browser and sends nothing.", "tags": [ "toml" ], "responses": { "200": { "description": "Success. With format=text, text/plain is returned instead of JSON.", "content": { "application/json": { "schema": { "type": "object", "description": "", "properties": { "valid": { "type": "boolean", "description": "True when there are no `error` findings." }, "summary": { "type": "object", "description": "", "properties": { "valid": { "type": "boolean", "description": "True when there are no `error` findings." }, "errors": { "type": "integer", "description": "Number of errors." }, "warnings": { "type": "integer", "description": "Number of warnings." }, "infos": { "type": "integer", "description": "Number of informational findings." } }, "required": [ "valid", "errors", "warnings", "infos" ], "additionalProperties": false }, "diagnostics": { "type": "array", "items": { "type": "object", "description": "One lint finding.", "properties": { "rule": { "type": "string", "description": "Rule ID, e.g. `syntax`, `duplicate-keys`, `trailing-spaces`." }, "severity": { "type": "string", "description": "`error` makes the document invalid; `warning` and `info` are style.", "enum": [ "error", "warning", "info" ] }, "message": { "type": "string", "description": "What is wrong and how to fix it." }, "line": { "type": "integer", "description": "1-based line where the problem starts." }, "column": { "type": "integer", "description": "1-based column (Unicode code points)." }, "offset": { "type": "integer", "description": "0-based UTF-16 offset into the input." }, "endLine": { "type": "integer", "description": "1-based end line, when the problem spans a range." }, "endColumn": { "type": "integer", "description": "1-based end column." }, "endOffset": { "type": "integer", "description": "0-based end offset." } }, "required": [ "rule", "severity", "message", "line", "column", "offset" ], "additionalProperties": false }, "description": "Findings in document order." }, "formatted": { "type": [ "string", "null" ], "description": "The formatted document, comments kept; null when invalid." }, "value": { "description": "The document as JSON (see the value mapping in the docs); null when invalid." }, "stats": { "type": "object", "description": "Counts for a valid document; all zero when invalid.", "properties": { "tables": { "type": "integer", "description": "Tables below the root: [table] sections, dotted-key tables, inline tables and each [[array]] element." }, "keys": { "type": "integer", "description": "Keys in all tables." }, "arrays": { "type": "integer", "description": "Arrays, including arrays of tables." }, "depth": { "type": "integer", "description": "Nesting depth: 1 for a flat document, one more per level of table or array." } }, "required": [ "tables", "keys", "arrays", "depth" ], "additionalProperties": false } }, "required": [ "valid", "summary", "diagnostics", "formatted", "value", "stats" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "The formatted TOML, or for invalid input one line: `invalid: line L, column C: message`." } } } }, "400": { "description": "missing_parameter / unknown_parameter / `input` is longer than 50,000 characters, or an option is out of range. Invalid TOML is NOT an error: it returns 200 with `valid: false`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "toml_format", "parameters": [ { "name": "format", "in": "query", "required": false, "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "schema": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "input": { "description": "The TOML text. Send it as a string field or as a raw text/plain POST body.", "type": "string" }, "indent": { "description": "Spaces per level for arrays that are broken over several lines.", "type": "integer", "default": 2, "minimum": 1, "maximum": 8 }, "max_line_length": { "description": "Arrays longer than this are broken one element per line, and longer lines are reported (line-length). 0 turns both off.", "type": "integer", "default": 120, "minimum": 0, "maximum": 1000 }, "sort_keys": { "description": "Sort keys within each table, by UTF-16 code units. Tables keep their order (the order of [[array]] tables is data).", "type": "boolean", "default": false }, "format": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } }, "required": [ "input" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "The body is used as the `input` parameter." } } } } } }, "/api/convert/toml-to-json": { "get": { "summary": "Convert a TOML 1.0 document to JSON, with line and column for any error.", "description": "Parses `input` as TOML 1.0.0 and returns the same data as JSON text and as a JSON value. Tables become objects and keep their order. Integers within ±(2^53 − 1) are numbers; larger ones are decimal strings so no digit is lost. `inf`, `-inf` and `nan` become the strings `\"inf\"`, `\"-inf\"` and `\"nan\"`. An offset date-time becomes an ISO 8601 string with its offset (`1979-05-27T07:32:00.000-08:00`); a local date-time, date or time becomes its TOML text (`1979-05-27T07:32:00.000`, `1979-05-27`, `07:32:00.000`). Fractional seconds are written to the millisecond. Comments are dropped: JSON has none.\n\nPrivacy: The server receives the TOML text, processes it in memory inside the request, and returns the result. Your input is not stored or logged; only the per-call metadata row (operation, time, status, sizes) is recorded. The server makes no network requests. For confidential documents use the page, which does the same work in your browser and sends nothing.", "tags": [ "toml" ], "responses": { "200": { "description": "Success. With format=text, text/plain is returned instead of JSON.", "content": { "application/json": { "schema": { "type": "object", "description": "", "properties": { "json": { "type": "string", "description": "The JSON text." }, "value": { "description": "The same data as a JSON value." } }, "required": [ "json", "value" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "The JSON text." } } } }, "400": { "description": "missing_parameter / unknown_parameter / `input` is longer than 200,000 characters, or `indent` is outside 0–8.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The TOML is invalid (syntax error, duplicate key or table, integer beyond 64 bits); the message gives the line and column.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "toml_to_json_get", "parameters": [ { "name": "input", "in": "query", "required": true, "description": "The TOML text, as a string field or a raw text/plain POST body.", "schema": { "description": "The TOML text, as a string field or a raw text/plain POST body.", "type": "string" } }, { "name": "indent", "in": "query", "required": false, "description": "Spaces per JSON indentation level; 0 gives minified JSON.", "schema": { "description": "Spaces per JSON indentation level; 0 gives minified JSON.", "type": "integer", "default": 2, "minimum": 0, "maximum": 8 } }, { "name": "format", "in": "query", "required": false, "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "schema": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } } ] }, "post": { "summary": "Convert a TOML 1.0 document to JSON, with line and column for any error.", "description": "Parses `input` as TOML 1.0.0 and returns the same data as JSON text and as a JSON value. Tables become objects and keep their order. Integers within ±(2^53 − 1) are numbers; larger ones are decimal strings so no digit is lost. `inf`, `-inf` and `nan` become the strings `\"inf\"`, `\"-inf\"` and `\"nan\"`. An offset date-time becomes an ISO 8601 string with its offset (`1979-05-27T07:32:00.000-08:00`); a local date-time, date or time becomes its TOML text (`1979-05-27T07:32:00.000`, `1979-05-27`, `07:32:00.000`). Fractional seconds are written to the millisecond. Comments are dropped: JSON has none.\n\nPrivacy: The server receives the TOML text, processes it in memory inside the request, and returns the result. Your input is not stored or logged; only the per-call metadata row (operation, time, status, sizes) is recorded. The server makes no network requests. For confidential documents use the page, which does the same work in your browser and sends nothing.", "tags": [ "toml" ], "responses": { "200": { "description": "Success. With format=text, text/plain is returned instead of JSON.", "content": { "application/json": { "schema": { "type": "object", "description": "", "properties": { "json": { "type": "string", "description": "The JSON text." }, "value": { "description": "The same data as a JSON value." } }, "required": [ "json", "value" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "The JSON text." } } } }, "400": { "description": "missing_parameter / unknown_parameter / `input` is longer than 200,000 characters, or `indent` is outside 0–8.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The TOML is invalid (syntax error, duplicate key or table, integer beyond 64 bits); the message gives the line and column.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "toml_to_json", "parameters": [ { "name": "format", "in": "query", "required": false, "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "schema": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "input": { "description": "The TOML text, as a string field or a raw text/plain POST body.", "type": "string" }, "indent": { "description": "Spaces per JSON indentation level; 0 gives minified JSON.", "type": "integer", "default": 2, "minimum": 0, "maximum": 8 }, "format": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } }, "required": [ "input" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "The body is used as the `input` parameter." } } } } } }, "/api/convert/json-to-toml": { "get": { "summary": "Convert a JSON object to a TOML 1.0 document.", "description": "Parses `input` strictly as JSON and writes it as TOML 1.0.0. The top level must be an object. Strings, booleans and numbers become key = value pairs (numbers are copied as written, so `1.0` stays a float); non-empty objects become [table] sections and arrays of objects become [[array]] tables; objects inside other arrays become inline tables; an empty object is `{}`. Within each table, plain keys come first, then sub-tables. Keys that are not bare (A–Z, a–z, 0–9, _ and -) are quoted. TOML has no null, so a null anywhere is an error that names its JSON Pointer; so is an integer beyond 64 bits. The result is formatted like `/api/toml/format` output.\n\nPrivacy: The server receives the JSON text, processes it in memory inside the request, and returns the result. Your input is not stored or logged; only the per-call metadata row (operation, time, status, sizes) is recorded. The server makes no network requests. For confidential documents use the page, which does the same work in your browser and sends nothing.", "tags": [ "toml" ], "responses": { "200": { "description": "Success. With format=text, text/plain is returned instead of JSON.", "content": { "application/json": { "schema": { "type": "object", "description": "", "properties": { "toml": { "type": "string", "description": "The TOML document, ending with a line break (empty for `{}`)." } }, "required": [ "toml" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "The TOML document." } } } }, "400": { "description": "missing_parameter / unknown_parameter / `input` is longer than 200,000 characters, or an option is out of range.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`input` is not valid JSON (the message gives line and column), the top level is not an object, or a value cannot be written as TOML: a null, an integer beyond 64 bits, or a string with an unpaired surrogate. The message names the JSON Pointer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "json_to_toml_get", "parameters": [ { "name": "input", "in": "query", "required": true, "description": "The JSON text (an object), as a string field or a raw text/plain POST body.", "schema": { "description": "The JSON text (an object), as a string field or a raw text/plain POST body.", "type": "string" } }, { "name": "indent", "in": "query", "required": false, "description": "Spaces per level for arrays that are broken over several lines.", "schema": { "description": "Spaces per level for arrays that are broken over several lines.", "type": "integer", "default": 2, "minimum": 1, "maximum": 8 } }, { "name": "max_line_length", "in": "query", "required": false, "description": "Arrays longer than this are broken one element per line, and longer lines are reported (line-length). 0 turns both off.", "schema": { "description": "Arrays longer than this are broken one element per line, and longer lines are reported (line-length). 0 turns both off.", "type": "integer", "default": 120, "minimum": 0, "maximum": 1000 } }, { "name": "sort_keys", "in": "query", "required": false, "description": "Sort keys in every table and inline table, by UTF-16 code units. Array order never changes.", "schema": { "description": "Sort keys in every table and inline table, by UTF-16 code units. Array order never changes.", "type": "boolean", "default": false } }, { "name": "format", "in": "query", "required": false, "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "schema": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } } ] }, "post": { "summary": "Convert a JSON object to a TOML 1.0 document.", "description": "Parses `input` strictly as JSON and writes it as TOML 1.0.0. The top level must be an object. Strings, booleans and numbers become key = value pairs (numbers are copied as written, so `1.0` stays a float); non-empty objects become [table] sections and arrays of objects become [[array]] tables; objects inside other arrays become inline tables; an empty object is `{}`. Within each table, plain keys come first, then sub-tables. Keys that are not bare (A–Z, a–z, 0–9, _ and -) are quoted. TOML has no null, so a null anywhere is an error that names its JSON Pointer; so is an integer beyond 64 bits. The result is formatted like `/api/toml/format` output.\n\nPrivacy: The server receives the JSON text, processes it in memory inside the request, and returns the result. Your input is not stored or logged; only the per-call metadata row (operation, time, status, sizes) is recorded. The server makes no network requests. For confidential documents use the page, which does the same work in your browser and sends nothing.", "tags": [ "toml" ], "responses": { "200": { "description": "Success. With format=text, text/plain is returned instead of JSON.", "content": { "application/json": { "schema": { "type": "object", "description": "", "properties": { "toml": { "type": "string", "description": "The TOML document, ending with a line break (empty for `{}`)." } }, "required": [ "toml" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "The TOML document." } } } }, "400": { "description": "missing_parameter / unknown_parameter / `input` is longer than 200,000 characters, or an option is out of range.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`input` is not valid JSON (the message gives line and column), the top level is not an object, or a value cannot be written as TOML: a null, an integer beyond 64 bits, or a string with an unpaired surrogate. The message names the JSON Pointer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "json_to_toml", "parameters": [ { "name": "format", "in": "query", "required": false, "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "schema": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "input": { "description": "The JSON text (an object), as a string field or a raw text/plain POST body.", "type": "string" }, "indent": { "description": "Spaces per level for arrays that are broken over several lines.", "type": "integer", "default": 2, "minimum": 1, "maximum": 8 }, "max_line_length": { "description": "Arrays longer than this are broken one element per line, and longer lines are reported (line-length). 0 turns both off.", "type": "integer", "default": 120, "minimum": 0, "maximum": 1000 }, "sort_keys": { "description": "Sort keys in every table and inline table, by UTF-16 code units. Array order never changes.", "type": "boolean", "default": false }, "format": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } }, "required": [ "input" ], "additionalProperties": false } }, "text/plain": { "schema": { "type": "string", "description": "The body is used as the `input` parameter." } } } } } }, "/api/tools/request": { "get": { "summary": "Ask for a new deterministic tool to be added to this service, describing the job and an example.", "description": "Records a request for a new tool. Use it when you (an agent or a person) keep doing the same deterministic job that has exactly one right answer and no tool here does it: a conversion, a validation, a calculation, a parser. Describe the job in `problem`, and give an `example_input` and the `expected_output` if you can; concrete examples make a request much more likely to be built. Requests are reviewed by the owner; check progress with `tool_requests`. A request is a suggestion, not an order, and nothing is guaranteed. Each client can submit up to 20 requests per 24 hours.\n\nPrivacy: Unlike the other operations, the server stores what you send here (title, problem, examples and category), with your client ID and the time, so the request can be reviewed and answered. It is not shared with other clients, except that a request marked planned, building or shipped may appear by title as related to similar requests. Do not include secrets or personal data. Only the per-call metadata row is logged.", "tags": [ "request" ], "responses": { "200": { "description": "Success. With format=text, text/plain is returned instead of JSON.", "content": { "application/json": { "schema": { "type": "object", "description": "", "properties": { "request_id": { "type": "string", "description": "Identifier of the request, e.g. `tr_…`." }, "status": { "type": "string", "description": "Always `received` for a new request.", "enum": [ "received" ] }, "created_at": { "type": "string", "description": "When it was recorded (ISO 8601 UTC)." }, "related": { "type": "array", "items": { "type": "object", "description": "", "properties": { "title": { "type": "string", "description": "Title of a similar request." }, "status": { "type": "string", "description": "`received` (not reviewed yet), `planned`, `building`, `shipped` (see `shipped_url`), `declined` or `duplicate` (see `status_note`).", "enum": [ "received", "planned", "building", "shipped", "declined", "duplicate" ] }, "url": { "type": [ "string", "null" ], "description": "The shipped tool, when there is one." } }, "required": [ "title", "status", "url" ], "additionalProperties": false }, "description": "Similar requests already planned, building or shipped. A shipped one may already do the job." }, "next": { "type": "string", "description": "How to follow the request up." } }, "required": [ "request_id", "status", "created_at", "related", "next" ], "additionalProperties": false } } } }, "400": { "description": "missing_parameter / unknown_parameter / A field is empty, too long, or not an allowed value.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 20 requests in 24 hours.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "tool_request_get", "parameters": [ { "name": "title", "in": "query", "required": true, "description": "Short name for the tool, e.g. \"IBAN validator\" or \"Semantic version compare\".", "schema": { "description": "Short name for the tool, e.g. \"IBAN validator\" or \"Semantic version compare\".", "type": "string" } }, { "name": "problem", "in": "query", "required": true, "description": "What you need done, why, and how you do it today. Say if you are an agent and what you are working on.", "schema": { "description": "What you need done, why, and how you do it today. Say if you are an agent and what you are working on.", "type": "string" } }, { "name": "example_input", "in": "query", "required": false, "description": "A sample input the tool would receive (no secrets or personal data).", "schema": { "description": "A sample input the tool would receive (no secrets or personal data).", "type": "string" } }, { "name": "expected_output", "in": "query", "required": false, "description": "What the tool should return for example_input.", "schema": { "description": "What the tool should return for example_input.", "type": "string" } }, { "name": "category", "in": "query", "required": false, "description": "Closest existing category, or Other.", "schema": { "description": "Closest existing category, or Other.", "type": "string", "enum": [ "Encoding", "Hashing", "Keys & Certificates", "Inspect & Identify", "Text & Data", "Time & Scheduling", "Other" ] } }, { "name": "format", "in": "query", "required": false, "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "schema": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } } ] }, "post": { "summary": "Ask for a new deterministic tool to be added to this service, describing the job and an example.", "description": "Records a request for a new tool. Use it when you (an agent or a person) keep doing the same deterministic job that has exactly one right answer and no tool here does it: a conversion, a validation, a calculation, a parser. Describe the job in `problem`, and give an `example_input` and the `expected_output` if you can; concrete examples make a request much more likely to be built. Requests are reviewed by the owner; check progress with `tool_requests`. A request is a suggestion, not an order, and nothing is guaranteed. Each client can submit up to 20 requests per 24 hours.\n\nPrivacy: Unlike the other operations, the server stores what you send here (title, problem, examples and category), with your client ID and the time, so the request can be reviewed and answered. It is not shared with other clients, except that a request marked planned, building or shipped may appear by title as related to similar requests. Do not include secrets or personal data. Only the per-call metadata row is logged.", "tags": [ "request" ], "responses": { "200": { "description": "Success. With format=text, text/plain is returned instead of JSON.", "content": { "application/json": { "schema": { "type": "object", "description": "", "properties": { "request_id": { "type": "string", "description": "Identifier of the request, e.g. `tr_…`." }, "status": { "type": "string", "description": "Always `received` for a new request.", "enum": [ "received" ] }, "created_at": { "type": "string", "description": "When it was recorded (ISO 8601 UTC)." }, "related": { "type": "array", "items": { "type": "object", "description": "", "properties": { "title": { "type": "string", "description": "Title of a similar request." }, "status": { "type": "string", "description": "`received` (not reviewed yet), `planned`, `building`, `shipped` (see `shipped_url`), `declined` or `duplicate` (see `status_note`).", "enum": [ "received", "planned", "building", "shipped", "declined", "duplicate" ] }, "url": { "type": [ "string", "null" ], "description": "The shipped tool, when there is one." } }, "required": [ "title", "status", "url" ], "additionalProperties": false }, "description": "Similar requests already planned, building or shipped. A shipped one may already do the job." }, "next": { "type": "string", "description": "How to follow the request up." } }, "required": [ "request_id", "status", "created_at", "related", "next" ], "additionalProperties": false } } } }, "400": { "description": "missing_parameter / unknown_parameter / A field is empty, too long, or not an allowed value.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "More than 20 requests in 24 hours.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "tool_request", "parameters": [ { "name": "format", "in": "query", "required": false, "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "schema": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "description": "Short name for the tool, e.g. \"IBAN validator\" or \"Semantic version compare\".", "type": "string" }, "problem": { "description": "What you need done, why, and how you do it today. Say if you are an agent and what you are working on.", "type": "string" }, "example_input": { "description": "A sample input the tool would receive (no secrets or personal data).", "type": "string" }, "expected_output": { "description": "What the tool should return for example_input.", "type": "string" }, "category": { "description": "Closest existing category, or Other.", "type": "string", "enum": [ "Encoding", "Hashing", "Keys & Certificates", "Inspect & Identify", "Text & Data", "Time & Scheduling", "Other" ] }, "format": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } }, "required": [ "title", "problem" ], "additionalProperties": false } } } } } }, "/api/tools/requests": { "get": { "summary": "See the tool requests you have made with these credentials and what became of each.", "description": "Returns every tool request made with your client ID, newest first, with its current status and the owner's note. When a request is `shipped`, `shipped_url` points at the new tool. Requests made through the web form are not linked to a client and do not appear here.\n\nPrivacy: The server reads the tool requests stored under your client ID and returns them. Nothing you send is stored.", "tags": [ "request" ], "responses": { "200": { "description": "Success. With format=text, text/plain is returned instead of JSON.", "content": { "application/json": { "schema": { "type": "object", "description": "", "properties": { "requests": { "type": "array", "items": { "type": "object", "description": "", "properties": { "request_id": { "type": "string", "description": "Identifier of the request." }, "title": { "type": "string", "description": "Title as submitted." }, "status": { "type": "string", "description": "`received` (not reviewed yet), `planned`, `building`, `shipped` (see `shipped_url`), `declined` or `duplicate` (see `status_note`).", "enum": [ "received", "planned", "building", "shipped", "declined", "duplicate" ] }, "status_note": { "type": [ "string", "null" ], "description": "The owner's note, if any." }, "shipped_url": { "type": [ "string", "null" ], "description": "The tool, once shipped." }, "created_at": { "type": "string", "description": "When it was submitted." }, "updated_at": { "type": "string", "description": "When its status last changed." } }, "required": [ "request_id", "title", "status", "status_note", "shipped_url", "created_at", "updated_at" ], "additionalProperties": false }, "description": "Your requests, newest first." } }, "required": [ "requests" ], "additionalProperties": false } } } }, "400": { "description": "missing_parameter / unknown_parameter / invalid_parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "tool_requests_get", "parameters": [ { "name": "format", "in": "query", "required": false, "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "schema": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } } ] }, "post": { "summary": "See the tool requests you have made with these credentials and what became of each.", "description": "Returns every tool request made with your client ID, newest first, with its current status and the owner's note. When a request is `shipped`, `shipped_url` points at the new tool. Requests made through the web form are not linked to a client and do not appear here.\n\nPrivacy: The server reads the tool requests stored under your client ID and returns them. Nothing you send is stored.", "tags": [ "request" ], "responses": { "200": { "description": "Success. With format=text, text/plain is returned instead of JSON.", "content": { "application/json": { "schema": { "type": "object", "description": "", "properties": { "requests": { "type": "array", "items": { "type": "object", "description": "", "properties": { "request_id": { "type": "string", "description": "Identifier of the request." }, "title": { "type": "string", "description": "Title as submitted." }, "status": { "type": "string", "description": "`received` (not reviewed yet), `planned`, `building`, `shipped` (see `shipped_url`), `declined` or `duplicate` (see `status_note`).", "enum": [ "received", "planned", "building", "shipped", "declined", "duplicate" ] }, "status_note": { "type": [ "string", "null" ], "description": "The owner's note, if any." }, "shipped_url": { "type": [ "string", "null" ], "description": "The tool, once shipped." }, "created_at": { "type": "string", "description": "When it was submitted." }, "updated_at": { "type": "string", "description": "When its status last changed." } }, "required": [ "request_id", "title", "status", "status_note", "shipped_url", "created_at", "updated_at" ], "additionalProperties": false }, "description": "Your requests, newest first." } }, "required": [ "requests" ], "additionalProperties": false } } } }, "400": { "description": "missing_parameter / unknown_parameter / invalid_parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "tool_requests", "parameters": [ { "name": "format", "in": "query", "required": false, "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "schema": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "format": { "description": "json returns the documented object. text returns only the primary value as text/plain (see \"Text output\").", "type": "string", "enum": [ "json", "text" ], "default": "json" } }, "required": [], "additionalProperties": false } } } } } } }, "components": { "schemas": { "Error": { "type": "object", "required": [ "error", "code" ], "properties": { "error": { "type": "string", "description": "Human-readable explanation." }, "code": { "type": "string", "enum": [ "missing_parameter", "unknown_parameter", "invalid_parameter", "unauthenticated", "credentials_expired", "revoked", "verification_failed", "renewal_refused", "not_found", "method_not_allowed", "payload_too_large", "unprocessable_input", "rate_limited", "internal_error", "upstream_error", "service_unavailable" ], "description": "Machine-readable error code." }, "param": { "type": "string", "description": "The parameter at fault, when there is one." } } } } } }