{ "openapi": "3.1.0", "info": { "title": "JsonMend API", "version": "0.1.3", "summary": "Repair broken JSON from LLM output and validate it against a JSON Schema. Returns valid JSON plus the fixes applied.", "description": "Free JSON API behind https://jsonmend.mike-tusa.workers.dev. No key needed for light use (about 10 requests/min and 30/day per IP). A free API key (POST /api/v1/keys) allows about 30/min and 1,000/month. There are no X-RateLimit-* headers; a 429 carries Retry-After. Pure computation: nothing is fetched, inputs are not stored. AI agents can also use the remote MCP server at https://jsonmend.mike-tusa.workers.dev/mcp (see /llms.txt).", "contact": { "name": "JsonMend", "email": "digitalpromohub.support@gmail.com", "url": "https://jsonmend.mike-tusa.workers.dev/" } }, "servers": [ { "url": "https://jsonmend.mike-tusa.workers.dev" } ], "externalDocs": { "description": "Human-readable API docs", "url": "https://jsonmend.mike-tusa.workers.dev/docs" }, "tags": [ { "name": "json" }, { "name": "keys" }, { "name": "meta" }, { "name": "mcp" } ], "components": { "securitySchemes": { "apiKeyHeader": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Free key (`jm_` + 32 characters). Optional on /api/v1/repair, /api/v1/validate and /mcp." }, "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Same key as apiKeyHeader, as `Authorization: Bearer jm_…`. X-API-Key wins when both are sent." } }, "schemas": { "Error": { "type": "object", "required": [ "ok", "error" ], "properties": { "ok": { "const": false }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "position": { "type": "integer", "description": "Character offset in the input where repair failed (unrepairable only)" } } } } }, "Fix": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "removed_bom", "stripped_code_fence", "removed_surrounding_text", "removed_leading_text", "removed_trailing_text", "extra_closing_brackets", "wrapped_multiple_values", "comments", "single_quotes", "smart_quotes", "unquoted_keys", "unquoted_strings", "trailing_commas", "extra_commas", "missing_commas", "missing_colons", "python_literals", "non_json_literals", "invalid_numbers", "control_characters", "truncated", "other_syntax_fixes" ] }, "message": { "type": "string" }, "count": { "type": "integer", "minimum": 2 } } }, "Warning": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "SchemaError": { "type": "object", "required": [ "path", "keyword", "schemaPath", "message" ], "properties": { "path": { "type": "string", "description": "JSON Pointer to the failing value (\"\" = root)" }, "keyword": { "type": "string" }, "schemaPath": { "type": "string" }, "message": { "type": "string" } } }, "Validation": { "type": "object", "required": [ "valid", "errorCount", "errorsTruncated", "errors", "draft", "coerced", "coercions" ], "properties": { "valid": { "type": "boolean" }, "errorCount": { "type": "integer", "description": "Errors found; a lower bound when errorsTruncated is true" }, "errorsTruncated": { "type": "boolean", "description": "true when the validator produced more than 5,000 raw errors and only the first 5,000 were examined" }, "errors": { "type": "array", "maxItems": 50, "items": { "$ref": "#/components/schemas/SchemaError" } }, "draft": { "type": "string", "enum": [ "2020-12", "2019-09", "7", "4" ] }, "coerced": { "type": "boolean" }, "coercions": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "from": { "type": "string" }, "to": { "type": "string" } } } } } }, "RepairResult": { "type": "object", "required": [ "ok", "changed", "inputWasValid", "values", "fixes", "warnings", "json", "text", "format", "inputBytes", "outputBytes" ], "properties": { "ok": { "const": true }, "changed": { "type": "boolean" }, "inputWasValid": { "type": "boolean" }, "values": { "type": "integer", "description": "Top-level values found; more than 1 = wrapped in an array" }, "fixes": { "type": "array", "items": { "$ref": "#/components/schemas/Fix" } }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/Warning" } }, "json": { "description": "The repaired value (any JSON type; coerced when coerce was used)" }, "text": { "type": "string", "description": "The repaired JSON as text, in the requested format" }, "format": { "type": "string", "enum": [ "compact", "pretty", "preserve" ] }, "inputBytes": { "type": "integer" }, "outputBytes": { "type": "integer" }, "schema": { "$ref": "#/components/schemas/Validation" } } }, "ValidateResult": { "type": "object", "required": [ "ok", "valid", "errorCount", "errorsTruncated", "errors", "draft", "coerced", "coercions", "repaired", "fixes", "warnings", "json" ], "properties": { "ok": { "const": true }, "valid": { "type": "boolean" }, "errorCount": { "type": "integer", "description": "Errors found; a lower bound when errorsTruncated is true" }, "errorsTruncated": { "type": "boolean", "description": "true when the validator produced more than 5,000 raw errors and only the first 5,000 were examined" }, "errors": { "type": "array", "maxItems": 50, "items": { "$ref": "#/components/schemas/SchemaError" } }, "draft": { "type": "string", "enum": [ "2020-12", "2019-09", "7", "4" ] }, "coerced": { "type": "boolean" }, "coercions": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "from": { "type": "string" }, "to": { "type": "string" } } } }, "repaired": { "type": "boolean" }, "fixes": { "type": "array", "items": { "$ref": "#/components/schemas/Fix" } }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/Warning" } }, "json": { "description": "The validated value (after repair and coercion)" } } }, "JsonRpcMessage": { "type": "object", "required": [ "jsonrpc" ], "properties": { "jsonrpc": { "const": "2.0" }, "id": { "type": [ "string", "integer" ] }, "method": { "type": "string" }, "params": { "type": "object" } } } } }, "paths": { "/api/v1/repair": { "post": { "tags": [ "json" ], "operationId": "repairJson", "summary": "Repair broken JSON and list the fixes (optionally validate against a schema)", "description": "Turn broken JSON text (for example LLM output with code fences, comments or trailing commas) into valid JSON and list every fix made.", "security": [ {}, { "apiKeyHeader": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "input" ], "additionalProperties": false, "properties": { "input": { "type": "string", "maxLength": 102400, "description": "Raw (possibly broken) JSON text, max 102,400 bytes UTF-8" }, "format": { "type": "string", "enum": [ "compact", "pretty", "preserve" ], "default": "compact" }, "schema": { "type": [ "object", "boolean" ], "description": "JSON Schema (max 32,768 bytes). Only local $refs." }, "coerce": { "type": "boolean", "default": false }, "draft": { "type": "string", "enum": [ "2020-12", "2019-09", "7", "4" ] } } } }, "text/plain": { "schema": { "type": "string", "maxLength": 102400, "description": "The raw input itself (options: ?format=compact|pretty|preserve)" } } } }, "parameters": [ { "name": "format", "in": "query", "required": false, "description": "Only for text/plain bodies", "schema": { "type": "string", "enum": [ "compact", "pretty", "preserve" ] } } ], "responses": { "200": { "description": "Repaired (or passed-through) JSON with the fixes applied", "headers": { "x-jsonmend-plan": { "description": "`anonymous` or `key`", "schema": { "type": "string", "enum": [ "anonymous", "key" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepairResult" } } } }, "400": { "description": "`invalid_json` (body is not a JSON object), `invalid_arguments`, `invalid_schema` (schema unusable, e.g. bad regex or unresolved $ref) or `empty_input`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "`invalid_api_key`: a key was sent but is unknown or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "`method_not_allowed`", "headers": { "Allow": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "`payload_too_large` (body over 262,144 bytes), `input_too_large` (input over 102,400 bytes) or `schema_too_large` (over 32,768 bytes)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`no_json_found`, `unrepairable` (with `position` when known), `too_deep` (nesting over 256) or `schema_too_complex` (schema loops without descending into the data, applies over 10,000 subschemas to one value, or checking needs over 200,000 steps). Failures found while repairing or validating count as a request; the up-front checks (schema loop/size, `data` depth) do not.", "headers": { "x-jsonmend-plan": { "description": "`anonymous` or `key`", "schema": { "type": "string", "enum": [ "anonymous", "key" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited` (per-minute), `ip_daily_quota`, `key_quota_exceeded`, `issuer_quota_exceeded` or `daily_cap_reached` (service-wide daily allowance)", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`internal_error`. Note: pathological schemas (e.g. catastrophic regex `pattern`s) can instead be stopped by the platform per-request CPU limit, which returns a 5xx without this JSON body; such requests still count.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`not_configured` (deployment missing its HASH_PEPPER secret)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/validate": { "post": { "tags": [ "json" ], "operationId": "validateJson", "summary": "Validate JSON text or a parsed value against a JSON Schema", "description": "Check JSON text (repaired first if broken) or an already-parsed value against a JSON Schema, optionally coercing types to match.", "security": [ {}, { "apiKeyHeader": [] }, { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "schema" ], "additionalProperties": false, "properties": { "schema": { "type": [ "object", "boolean" ], "description": "JSON Schema (max 32,768 bytes). Only local $refs." }, "input": { "type": "string", "maxLength": 102400, "description": "Raw (possibly broken) JSON text, max 102,400 bytes UTF-8" }, "data": { "description": "Already-parsed JSON value (instead of input)" }, "coerce": { "type": "boolean", "default": false }, "draft": { "type": "string", "enum": [ "2020-12", "2019-09", "7", "4" ] } } } } } }, "responses": { "200": { "description": "Validation result (a schema mismatch is still 200, with valid: false)", "headers": { "x-jsonmend-plan": { "description": "`anonymous` or `key`", "schema": { "type": "string", "enum": [ "anonymous", "key" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidateResult" } } } }, "400": { "description": "`invalid_json` (body is not a JSON object), `invalid_arguments`, `invalid_schema` (schema unusable, e.g. bad regex or unresolved $ref) or `empty_input`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "`invalid_api_key`: a key was sent but is unknown or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "`method_not_allowed`", "headers": { "Allow": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "`payload_too_large` (body over 262,144 bytes), `input_too_large` (input over 102,400 bytes) or `schema_too_large` (over 32,768 bytes)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`no_json_found`, `unrepairable` (with `position` when known), `too_deep` (nesting over 256) or `schema_too_complex` (schema loops without descending into the data, applies over 10,000 subschemas to one value, or checking needs over 200,000 steps). Failures found while repairing or validating count as a request; the up-front checks (schema loop/size, `data` depth) do not.", "headers": { "x-jsonmend-plan": { "description": "`anonymous` or `key`", "schema": { "type": "string", "enum": [ "anonymous", "key" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited` (per-minute), `ip_daily_quota`, `key_quota_exceeded`, `issuer_quota_exceeded` or `daily_cap_reached` (service-wide daily allowance)", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "`internal_error`. Note: pathological schemas (e.g. catastrophic regex `pattern`s) can instead be stopped by the platform per-request CPU limit, which returns a 5xx without this JSON body; such requests still count.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`not_configured` (deployment missing its HASH_PEPPER secret)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/keys": { "post": { "tags": [ "keys" ], "operationId": "createKey", "summary": "Get a free API key (shown once; JSON only; no CORS)", "description": "Create a free key for higher limits (about 30/min and 1,000/month); only its hash is stored.", "security": [ {} ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "maxLength": 254, "description": "Optional, unverified contact info" } } } } } }, "responses": { "201": { "description": "Key created", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "apiKey", "keyId" ], "properties": { "ok": { "const": true }, "apiKey": { "type": "string", "pattern": "^jm_[A-Za-z0-9]{32}$" }, "keyId": { "type": "string" }, "plan": { "const": "free" }, "monthlyQuota": { "type": "integer" }, "perMinute": { "type": "integer" }, "note": { "type": "string" } } } } } }, "400": { "description": "`invalid_json` or `invalid_email`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "`cross_origin_forbidden`: requests from other websites are refused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "`method_not_allowed`", "headers": { "Allow": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "`payload_too_large`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "`unsupported_media_type`: send application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "`rate_limited`, `key_issue_limit` (at most 3 keys per IP per day) or `daily_cap_reached`", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`not_configured` or `unavailable`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/usage": { "get": { "tags": [ "keys" ], "operationId": "usage", "summary": "This month's usage for your key", "description": "See how many requests your key has used this month and how many remain.", "security": [ { "apiKeyHeader": [] }, { "bearerAuth": [] } ], "responses": { "200": { "description": "Usage (approximate, batched counters)", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": true }, "keyId": { "type": "string" }, "plan": { "type": "string" }, "monthlyQuota": { "type": "integer" }, "usedThisMonth": { "type": "integer" }, "remainingThisMonth": { "type": "integer" }, "perMinute": { "type": "integer" }, "resetsAt": { "type": "string", "format": "date-time" }, "note": { "type": "string" } } } } } }, "401": { "description": "`missing_api_key` or `invalid_api_key`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "`method_not_allowed`", "headers": { "Allow": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "`not_configured`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/health": { "get": { "tags": [ "meta" ], "operationId": "health", "summary": "Service status and deployed version", "description": "Check that the service is up and which version is deployed.", "security": [ {} ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok", "service", "version" ], "properties": { "ok": { "const": true }, "service": { "const": "jsonmend" }, "version": { "type": "string", "examples": [ "0.1.3" ] }, "environment": { "type": "string" }, "time": { "type": "string", "format": "date-time" } } } } } }, "405": { "description": "`method_not_allowed`", "headers": { "Allow": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/mcp": { "post": { "tags": [ "mcp" ], "operationId": "mcp", "summary": "Remote MCP server (Streamable HTTP, JSON-RPC 2.0)", "description": "Model Context Protocol endpoint. Stateless, JSON responses only (no SSE, no Mcp-Session-Id). Supported protocol versions: 2026-07-28, 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05. Modern (2026-07-28) requests carry params._meta and the MCP-Protocol-Version, Mcp-Method and Mcp-Name headers; legacy clients use initialize. Tools: repair_json, validate_json. Same keys and limits as the JSON API; each tools/call counts as one request. Body max 262144 bytes; legacy batches max 10 messages with at most one tools/call.", "security": [ {}, { "apiKeyHeader": [] }, { "bearerAuth": [] } ], "parameters": [ { "name": "MCP-Protocol-Version", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "2026-07-28", "2025-11-25", "2025-06-18", "2025-03-26", "2024-11-05" ] } }, { "name": "Mcp-Method", "in": "header", "required": false, "description": "Required for 2026-07-28; must equal the body method", "schema": { "type": "string" } }, { "name": "Mcp-Name", "in": "header", "required": false, "description": "Required for 2026-07-28 tools/call; must equal params.name", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/JsonRpcMessage" }, { "type": "array", "maxItems": 10, "items": { "$ref": "#/components/schemas/JsonRpcMessage" } } ] } } } }, "responses": { "200": { "description": "JSON-RPC response (or batch of responses). Tool failures, including rate limits and unrepairable input, are results with isError: true.", "headers": { "x-jsonmend-plan": { "description": "`anonymous` or `key`", "schema": { "type": "string", "enum": [ "anonymous", "key" ] } }, "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": [ "object", "array" ] } } } }, "202": { "description": "Notification(s) accepted; no body" }, "400": { "description": "Parse error (-32700), invalid request (-32600), header mismatch (-32020), unsupported protocol version (-32022) or missing _meta (-32602)", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Invalid API key (JSON-RPC error, data.code = invalid_api_key)", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "Origin header present but not allowed", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "Unknown method in a 2026-07-28 request (-32601)", "content": { "application/json": { "schema": { "type": "object" } } } }, "413": { "description": "Body larger than the cap", "content": { "application/json": { "schema": { "type": "object" } } } }, "429": { "description": "Too many non-tool MCP messages from this IP", "headers": { "Retry-After": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object" } } } }, "500": { "description": "Unexpected internal error (`internal_error`); per-message failures are JSON-RPC -32603 inside a 200 response instead", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Deployment missing its HASH_PEPPER secret (`not_configured`)", "content": { "application/json": { "schema": { "type": "object" } } } } } }, "get": { "tags": [ "mcp" ], "operationId": "mcp_get_not_allowed", "summary": "Not supported (stateless server: no SSE stream, no sessions)", "responses": { "405": { "description": "Always 405 with `Allow: POST, OPTIONS` and a JSON-RPC error body", "headers": { "Allow": { "schema": { "type": "string", "const": "POST, OPTIONS" } } }, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "delete": { "tags": [ "mcp" ], "operationId": "mcp_delete_not_allowed", "summary": "Not supported (stateless server: no SSE stream, no sessions)", "responses": { "405": { "description": "Always 405 with `Allow: POST, OPTIONS` and a JSON-RPC error body", "headers": { "Allow": { "schema": { "type": "string", "const": "POST, OPTIONS" } } }, "content": { "application/json": { "schema": { "type": "object" } } } } } } } } }