{ "openapi": "3.1.0", "info": { "title": "Spamadin website spam API", "version": "1.0.0", "description": "Website-scoped contact-form and comment spam checks. Routine message bodies are not retained. Strict objects reject unknown fields. Keep bearer keys on your server." }, "servers": [ { "url": "https://spamadin.com" } ], "components": { "securitySchemes": { "accountKey": { "type": "http", "scheme": "bearer", "description": "Spamadin sp_live account API key. Reuse on every website. Keep it server-side." } } }, "paths": { "/api/v1/check": { "post": { "operationId": "checkSubmission", "description": "Server-side only. Body at most 32768 bytes; content at most 12000 characters. siteUrl declares the exact DNS hostname. New websites are registered within the plan limit; blocked websites are rejected. Use one UUID per original submission and the same UUID and payload on retries within 30 days. Preserve messages for review or degraded results. Evidence never establishes spam by itself.", "security": [ { "accountKey": [] } ], "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": false, "description": "UUID. Strongly recommended for safe retries. Use the form-token idempotencyKey if attaching its token.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "content": { "type": "string", "minLength": 1, "maxLength": 12000 }, "type": { "type": "string", "enum": [ "comment", "contact" ] }, "formId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "siteUrl": { "type": "string", "maxLength": 2048, "format": "uri" }, "context": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 200 }, "description": { "type": "string", "maxLength": 1000 }, "language": { "type": "string", "maxLength": 35 }, "tags": { "maxItems": 10, "type": "array", "items": { "type": "string", "maxLength": 50 } } }, "additionalProperties": false }, "signals": { "type": "object", "properties": { "elapsedMs": { "type": "integer", "minimum": 0, "maximum": 86400000 }, "honeypotFilled": { "type": "boolean" }, "formToken": { "type": "string", "minLength": 1, "maxLength": 1024 }, "browser": { "type": "object", "properties": { "version": { "type": "number", "const": 1 }, "jsExecuted": { "type": "boolean" }, "focusCount": { "type": "integer", "minimum": 0, "maximum": 1000 }, "editCount": { "type": "integer", "minimum": 0, "maximum": 10000 }, "pasteCount": { "type": "integer", "minimum": 0, "maximum": 1000 }, "keyboardUsed": { "type": "boolean" }, "pointerUsed": { "type": "boolean" }, "firstInteractionMs": { "type": "integer", "minimum": 0, "maximum": 86400000 } }, "required": [ "version", "jsExecuted" ], "additionalProperties": false }, "userAgent": { "type": "string", "maxLength": 512 }, "userIp": { "anyOf": [ { "type": "string", "format": "ipv4", "pattern": "^(?:(?:25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])\\.){3}(?:25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])$" }, { "type": "string", "format": "ipv6", "pattern": "^(([0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,7}:|([0-9a-fA-F]{1,4}:){1,6}:[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,5}(:[0-9a-fA-F]{1,4}){1,2}|([0-9a-fA-F]{1,4}:){1,4}(:[0-9a-fA-F]{1,4}){1,3}|([0-9a-fA-F]{1,4}:){1,3}(:[0-9a-fA-F]{1,4}){1,4}|([0-9a-fA-F]{1,4}:){1,2}(:[0-9a-fA-F]{1,4}){1,5}|[0-9a-fA-F]{1,4}:((:[0-9a-fA-F]{1,4}){1,6})|:((:[0-9a-fA-F]{1,4}){1,7}|:))$" } ] } }, "additionalProperties": false } }, "required": [ "content", "type", "siteUrl" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Completed request; inspect the response fields.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "verdict": { "type": "string", "enum": [ "allow", "review", "spam" ] }, "score": { "type": "integer", "minimum": 0, "maximum": 100 }, "reasons": { "type": "array", "items": { "type": "string" } }, "degraded": { "type": "boolean" }, "charged": { "type": "boolean" }, "policyVersion": { "type": "string" } }, "required": [ "id", "verdict", "score", "reasons", "degraded", "charged", "policyVersion" ], "additionalProperties": false } } } }, "400": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "402": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "415": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/api/v1/check/bulk": { "post": { "operationId": "checkSubmissions", "description": "1–20 items; distinct UUIDs within the batch, across websites in the account; all website limits and blocks are enforced. Maximum body 262144 bytes. Results remain in input order. Inspect every item status; HTTP 200 does not mean every item succeeded. Each completed non-degraded check consumes one check.", "security": [ { "accountKey": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "checks": { "minItems": 1, "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "submission": { "type": "object", "properties": { "content": { "type": "string", "minLength": 1, "maxLength": 12000 }, "type": { "type": "string", "enum": [ "comment", "contact" ] }, "formId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "siteUrl": { "type": "string", "maxLength": 2048, "format": "uri" }, "context": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 200 }, "description": { "type": "string", "maxLength": 1000 }, "language": { "type": "string", "maxLength": 35 }, "tags": { "maxItems": 10, "type": "array", "items": { "type": "string", "maxLength": 50 } } }, "additionalProperties": false }, "signals": { "type": "object", "properties": { "elapsedMs": { "type": "integer", "minimum": 0, "maximum": 86400000 }, "honeypotFilled": { "type": "boolean" }, "formToken": { "type": "string", "minLength": 1, "maxLength": 1024 }, "browser": { "type": "object", "properties": { "version": { "type": "number", "const": 1 }, "jsExecuted": { "type": "boolean" }, "focusCount": { "type": "integer", "minimum": 0, "maximum": 1000 }, "editCount": { "type": "integer", "minimum": 0, "maximum": 10000 }, "pasteCount": { "type": "integer", "minimum": 0, "maximum": 1000 }, "keyboardUsed": { "type": "boolean" }, "pointerUsed": { "type": "boolean" }, "firstInteractionMs": { "type": "integer", "minimum": 0, "maximum": 86400000 } }, "required": [ "version", "jsExecuted" ], "additionalProperties": false }, "userAgent": { "type": "string", "maxLength": 512 }, "userIp": { "anyOf": [ { "type": "string", "format": "ipv4", "pattern": "^(?:(?:25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])\\.){3}(?:25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])$" }, { "type": "string", "format": "ipv6", "pattern": "^(([0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,7}:|([0-9a-fA-F]{1,4}:){1,6}:[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,5}(:[0-9a-fA-F]{1,4}){1,2}|([0-9a-fA-F]{1,4}:){1,4}(:[0-9a-fA-F]{1,4}){1,3}|([0-9a-fA-F]{1,4}:){1,3}(:[0-9a-fA-F]{1,4}){1,4}|([0-9a-fA-F]{1,4}:){1,2}(:[0-9a-fA-F]{1,4}){1,5}|[0-9a-fA-F]{1,4}:((:[0-9a-fA-F]{1,4}){1,6})|:((:[0-9a-fA-F]{1,4}){1,7}|:))$" } ] } }, "additionalProperties": false } }, "required": [ "content", "type", "siteUrl" ], "additionalProperties": false } }, "required": [ "id", "submission" ], "additionalProperties": false } } }, "required": [ "checks" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Completed request; inspect the response fields.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "result": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "verdict": { "type": "string", "enum": [ "allow", "review", "spam" ] }, "score": { "type": "integer", "minimum": 0, "maximum": 100 }, "reasons": { "type": "array", "items": { "type": "string" } }, "degraded": { "type": "boolean" }, "charged": { "type": "boolean" }, "policyVersion": { "type": "string" } }, "required": [ "id", "verdict", "score", "reasons", "degraded", "charged", "policyVersion" ], "additionalProperties": false }, { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } ] } }, "required": [ "id", "status", "result" ], "additionalProperties": false } } }, "required": [ "results" ], "additionalProperties": false } } } }, "400": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "402": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "415": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/api/v1/form-token": { "post": { "operationId": "issueFormToken", "description": "Optional server-mediated browser evidence. Body at most 4096 bytes. Active website required; issuance is uncharged and limited to 60/minute per key. Return only these public fields to the browser. Token expires after 30 minutes. Submit token in signals.formToken with its idempotencyKey as the check UUID.", "security": [ { "accountKey": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "siteUrl": { "type": "string", "maxLength": 2048, "format": "uri" }, "type": { "type": "string", "enum": [ "comment", "contact" ] }, "formId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "siteUrl", "type" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Completed request; inspect the response fields.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "token": { "type": "string" }, "idempotencyKey": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "charged": { "type": "boolean", "const": false } }, "required": [ "token", "idempotencyKey", "expiresAt", "charged" ], "additionalProperties": false } } } }, "400": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "402": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "415": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/api/v1/reports/false-positive": { "post": { "operationId": "reportFalsePositive", "description": "Correct a completed check owned by this account to legitimate. Body at most 1024 bytes. Send the returned check id, not its Idempotency-Key. No message content, training consent, or check charge. Metadata normally expires after 30 days. Repeating the same report is safe; the latest correction wins. Invalidates website fingerprint decisions; does not instantly retrain a model.", "security": [ { "accountKey": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "id" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Completed request; inspect the response fields.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "received": { "type": "boolean", "const": true } }, "required": [ "received" ], "additionalProperties": false } } } }, "400": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "402": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "415": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/api/v1/reports/missed-spam": { "post": { "operationId": "reportMissedSpam", "description": "Correct a completed check owned by this account to spam. Body at most 1024 bytes. Send the returned check id, not its Idempotency-Key. No message content, training consent, or check charge. Metadata normally expires after 30 days. Repeating the same report is safe; the latest correction wins. Invalidates website fingerprint decisions; does not instantly retrain a model.", "security": [ { "accountKey": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "id" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Completed request; inspect the response fields.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "received": { "type": "boolean", "const": true } }, "required": [ "received" ], "additionalProperties": false } } } }, "400": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "402": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "415": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/api/v1/feedback": { "post": { "operationId": "correctCheck", "description": "Compatible combined correction endpoint. Same ownership and privacy rules as the two named reports.", "security": [ { "accountKey": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "label": { "type": "string", "enum": [ "legitimate", "spam" ] } }, "required": [ "id", "label" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Completed request; inspect the response fields.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "received": { "type": "boolean", "const": true } }, "required": [ "received" ], "additionalProperties": false } } } }, "400": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "402": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "415": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/api/v1/training": { "post": { "operationId": "shareImprovementExample", "description": "Separate explicit opt-in content sharing. Both consent acknowledgments must be true. Original completed check must be less than 30 days old and submission must match it. Minimized encrypted examples expire after 90 days, can be deleted, and are not an immediate model retraining. 500 examples/2 MiB per account; 16 KiB original message; 24 KiB minimized payload; request maximum 32 KiB. Global encrypted storage cap 2 GB.", "security": [ { "accountKey": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "checkId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "label": { "type": "string", "enum": [ "legitimate", "spam" ] }, "submission": { "type": "object", "properties": { "content": { "type": "string", "minLength": 1, "maxLength": 12000 }, "type": { "type": "string", "enum": [ "comment", "contact" ] }, "formId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "siteUrl": { "type": "string", "maxLength": 2048, "format": "uri" }, "context": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 200 }, "description": { "type": "string", "maxLength": 1000 }, "language": { "type": "string", "maxLength": 35 }, "tags": { "maxItems": 10, "type": "array", "items": { "type": "string", "maxLength": 50 } } }, "additionalProperties": false }, "signals": { "type": "object", "properties": { "elapsedMs": { "type": "integer", "minimum": 0, "maximum": 86400000 }, "honeypotFilled": { "type": "boolean" }, "formToken": { "type": "string", "minLength": 1, "maxLength": 1024 }, "browser": { "type": "object", "properties": { "version": { "type": "number", "const": 1 }, "jsExecuted": { "type": "boolean" }, "focusCount": { "type": "integer", "minimum": 0, "maximum": 1000 }, "editCount": { "type": "integer", "minimum": 0, "maximum": 10000 }, "pasteCount": { "type": "integer", "minimum": 0, "maximum": 1000 }, "keyboardUsed": { "type": "boolean" }, "pointerUsed": { "type": "boolean" }, "firstInteractionMs": { "type": "integer", "minimum": 0, "maximum": 86400000 } }, "required": [ "version", "jsExecuted" ], "additionalProperties": false }, "userAgent": { "type": "string", "maxLength": 512 }, "userIp": { "anyOf": [ { "type": "string", "format": "ipv4", "pattern": "^(?:(?:25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])\\.){3}(?:25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])$" }, { "type": "string", "format": "ipv6", "pattern": "^(([0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,7}:|([0-9a-fA-F]{1,4}:){1,6}:[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,5}(:[0-9a-fA-F]{1,4}){1,2}|([0-9a-fA-F]{1,4}:){1,4}(:[0-9a-fA-F]{1,4}){1,3}|([0-9a-fA-F]{1,4}:){1,3}(:[0-9a-fA-F]{1,4}){1,4}|([0-9a-fA-F]{1,4}:){1,2}(:[0-9a-fA-F]{1,4}){1,5}|[0-9a-fA-F]{1,4}:((:[0-9a-fA-F]{1,4}){1,6})|:((:[0-9a-fA-F]{1,4}){1,7}|:))$" } ] } }, "additionalProperties": false } }, "required": [ "content", "type", "siteUrl" ], "additionalProperties": false }, "consent": { "type": "object", "properties": { "authorizedToShare": { "type": "boolean", "const": true }, "useForSpamImprovement": { "type": "boolean", "const": true } }, "required": [ "authorizedToShare", "useForSpamImprovement" ], "additionalProperties": false } }, "required": [ "checkId", "label", "submission", "consent" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Completed request; inspect the response fields.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "received": { "type": "boolean", "const": true }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "checkId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "label": { "type": "string", "enum": [ "legitimate", "spam" ] }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "duplicate": { "type": "boolean" } }, "required": [ "received", "id", "checkId", "label", "expiresAt", "duplicate" ], "additionalProperties": false } } } }, "400": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "402": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "415": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } } } }, "get": { "operationId": "readImprovementExamples", "security": [ { "accountKey": [] } ], "description": "List unexpired references (50/page), or retrieve one minimized example. Supply id or after, never both.", "parameters": [ { "in": "query", "name": "id", "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "after", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Owned examples", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "anyOf": [ { "type": "object", "properties": { "examples": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "checkId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "label": { "type": "string", "enum": [ "legitimate", "spam" ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "id", "checkId", "label", "createdAt", "expiresAt" ], "additionalProperties": false } }, "next": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] } }, "required": [ "examples", "next" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "checkId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "label": { "type": "string", "enum": [ "legitimate", "spam" ] }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, "example": { "type": "object", "properties": { "content": { "type": "string", "minLength": 1, "maxLength": 12000 }, "type": { "type": "string", "enum": [ "contact", "comment" ] }, "context": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 200 }, "description": { "type": "string", "maxLength": 1000 }, "language": { "type": "string", "maxLength": 35 }, "tags": { "maxItems": 10, "type": "array", "items": { "type": "string", "maxLength": 50 } } }, "additionalProperties": false }, "website": { "type": "object", "properties": { "category": { "type": "string", "maxLength": 40 }, "description": { "type": "string", "maxLength": 1000 } }, "required": [ "category", "description" ], "additionalProperties": false }, "form": { "type": "object", "properties": { "purpose": { "type": "string", "maxLength": 40 }, "summary": { "type": "string", "maxLength": 600 } }, "required": [ "purpose", "summary" ], "additionalProperties": false } }, "required": [ "content", "type", "website" ], "additionalProperties": false } }, "required": [ "id", "checkId", "label", "expiresAt", "example" ], "additionalProperties": false } ] } } } }, "400": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "402": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "415": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } } } }, "delete": { "operationId": "withdrawImprovementExample", "security": [ { "accountKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "id" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Deleted owned example", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "deleted": { "type": "boolean", "const": true } }, "required": [ "deleted" ], "additionalProperties": false } } } }, "400": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "402": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "415": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/api/v1/wordpress/connect": { "post": { "operationId": "connectWordPressWebsite", "description": "Use the reusable sp_live account API key. Body at most 4096 bytes. Exact DNS hostname, no URL credentials. Adds a new website only within the active plan limit. Reconnecting an allowed website is idempotent. Blocked websites cannot reconnect automatically. Returns website metadata, never a new API key.", "security": [ { "accountKey": [] } ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "siteUrl": { "type": "string", "maxLength": 2048, "format": "uri" }, "name": { "type": "string", "minLength": 1, "maxLength": 60 }, "description": { "default": "", "type": "string", "maxLength": 1000 } }, "required": [ "siteUrl", "name", "description" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Completed request; inspect the response fields.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "domain": { "type": "string" }, "connected": { "type": "boolean", "const": true }, "charged": { "type": "boolean", "const": false } }, "required": [ "id", "domain", "connected", "charged" ], "additionalProperties": false } } } }, "400": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "402": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "415": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "Request not completed. Preserve the submission. On 429 honor Retry-After; retry transient failures with bounded backoff.", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } } } } } } }