{ "openapi": "3.1.0", "info": { "title": "PhoneCheck", "version": "0.2.1", "description": "Offline phone-number validation and formatting (libphonenumber metadata). No carrier/HLR/reachability lookup; numbers are not stored or logged. Anonymous ~20/min per IP; free key ~300/min, 1000/month.", "contact": { "email": "digitalpromohub.support@gmail.com" } }, "servers": [ { "url": "https://phonecheck.mike-tusa.workers.dev" } ], "security": [ {}, { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer" }, "apiKeyHeader": { "type": "apiKey", "in": "header", "name": "X-Api-Key" } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } }, "paths": { "/v1/parse": { "post": { "operationId": "parsePhoneNumber", "summary": "Validate and format one number (offline metadata; no carrier/HLR lookup)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "number": { "type": "string", "maxLength": 64 }, "defaultCountry": { "type": "string", "pattern": "^[A-Za-z]{2}$", "maxLength": 2 } }, "required": [ "number" ] } } } }, "responses": { "200": { "description": "Parsed (valid may be false)", "headers": { "x-phonecheck-plan": { "description": "Key plan (free or pro), keyed calls only", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Monthly quota, keyed calls only", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Calls left this month, keyed calls only", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "input": { "type": "string" }, "default_country": { "type": "string" }, "national_number": { "type": "string" }, "valid": { "type": "boolean" }, "possible": { "type": "boolean" }, "e164": { "type": "string" }, "international": { "type": "string" }, "national": { "type": "string" }, "rfc3966": { "type": "string" }, "country": { "type": "string" }, "country_name": { "type": "string" }, "calling_code": { "type": "string" }, "non_geographic": { "type": "boolean" }, "line_type": { "type": "string" }, "extension": { "type": "string" }, "reason": { "type": "string" }, "message": { "type": "string" } } } } } }, "400": { "description": "Bad input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "invalid_api_key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "body_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited, daily_capacity_reached or monthly_quota_exceeded", "headers": { "retry-after": { "description": "Seconds to wait", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Per-minute limit that was hit", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "storage_unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/bulk": { "post": { "operationId": "bulkParse", "summary": "Parse up to 500 numbers (Pro keys only; each number counts one call)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "numbers": { "type": "array", "maxItems": 500, "items": { "oneOf": [ { "type": "string", "maxLength": 64 }, { "type": "object", "properties": { "number": { "type": "string", "maxLength": 64 }, "defaultCountry": { "type": "string", "maxLength": 2 } } } ] } }, "defaultCountry": { "type": "string", "maxLength": 2 } }, "required": [ "numbers" ] } } } }, "responses": { "200": { "description": "Results", "headers": { "x-phonecheck-plan": { "description": "Key plan (free or pro), keyed calls only", "schema": { "type": "string" } }, "x-quota-limit": { "description": "Monthly quota, keyed calls only", "schema": { "type": "string" } }, "x-quota-remaining": { "description": "Calls left this month, keyed calls only", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "api_key_required or invalid_api_key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "paid_plan_required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "body_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited, daily_capacity_reached or monthly_quota_exceeded", "headers": { "retry-after": { "description": "Seconds to wait", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Per-minute limit that was hit", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "storage_unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/example/{country}": { "get": { "operationId": "exampleNumber", "summary": "Example (mobile) number for a region, for format testing only", "parameters": [ { "name": "country", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$", "maxLength": 2 } } ], "responses": { "200": { "description": "Example", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "invalid_api_key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "unknown_country", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited, daily_capacity_reached or monthly_quota_exceeded", "headers": { "retry-after": { "description": "Seconds to wait", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Per-minute limit that was hit", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/countries": { "get": { "operationId": "listCountries", "summary": "Supported regions", "responses": { "200": { "description": "Regions", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "invalid_api_key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited, daily_capacity_reached or monthly_quota_exceeded", "headers": { "retry-after": { "description": "Seconds to wait", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Per-minute limit that was hit", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/meta": { "get": { "operationId": "meta", "summary": "Service version, limits, disclaimer and privacy", "responses": { "200": { "description": "Meta", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "invalid_api_key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited, daily_capacity_reached or monthly_quota_exceeded", "headers": { "retry-after": { "description": "Seconds to wait", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Per-minute limit that was hit", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/mcp": { "post": { "operationId": "mcp", "summary": "MCP JSON-RPC 2.0 (Streamable HTTP, stateless). Protocol versions 2026-07-28, 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05. Max body 65536 bytes.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "JSON-RPC response (tool errors are results with isError)", "headers": { "retry-after": { "description": "Seconds to wait", "schema": { "type": "string" } }, "x-ratelimit-limit": { "description": "Per-minute limit that was hit", "schema": { "type": "string" } } } }, "202": { "description": "Notification or client response accepted" }, "400": { "description": "Parse error, invalid request, header mismatch or unsupported version" }, "401": { "description": "invalid_api_key (no WWW-Authenticate)" }, "403": { "description": "Origin not allowed" }, "404": { "description": "Unknown method (2026-07-28)" }, "413": { "description": "Body too large" }, "429": { "description": "Too many MCP requests", "headers": { "retry-after": { "description": "Seconds", "schema": { "type": "string" } } } }, "500": { "description": "Internal error" }, "503": { "description": "storage_unavailable" } } }, "get": { "operationId": "mcpGet", "summary": "Not supported (stateless, no SSE)", "responses": { "405": { "description": "Method not allowed", "headers": { "allow": { "schema": { "type": "string", "enum": [ "POST, OPTIONS" ] } } } } } }, "delete": { "operationId": "mcpDelete", "summary": "Not supported (no sessions)", "responses": { "405": { "description": "Method not allowed", "headers": { "allow": { "schema": { "type": "string", "enum": [ "POST, OPTIONS" ] } } } } } } }, "/v1/parse/{number}": { "get": { "operationId": "parseGet", "summary": "Disabled in production: numbers in URLs end up in logs. Use POST /v1/parse.", "parameters": [ { "name": "number", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64 } } ], "responses": { "405": { "description": "method_not_allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } } }