{ "openapi": "3.1.1", "jsonSchemaDialect": "https://spec.openapis.org/oas/3.1/dialect/base", "info": { "title": "easycaptcha.to public API", "version": "1.0.0", "description": "Customer integration API for task submission, results, feedback, account balance and extension downloads. Authenticated operations use Authorization: Bearer . Monetary values are decimal integer strings in microcents. All HTTP errors use RFC 9457 Problem Details.", "termsOfService": "https://www.easycaptcha.to/terms" }, "servers": [ { "url": "https://api.easycaptcha.to", "description": "Public API" } ], "externalDocs": { "description": "API reference", "url": "https://www.easycaptcha.to/docs/api" }, "security": [ { "APIKey": [] } ], "tags": [ { "name": "Tasks", "description": "Submit tasks, retrieve results and report feedback." }, { "name": "Account", "description": "Read available account credit." }, { "name": "Extensions", "description": "Retrieve release metadata and download links." } ], "paths": { "/v1/extensions": { "get": { "operationId": "listPublicExtensions", "tags": ["Extensions"], "summary": "List public extensions", "description": "List extensions available to the caller. Anonymous callers see only public extensions. A valid session applies account visibility and permission rules, including private extensions; unlisted extensions are listed for administrators.", "security": [], "parameters": [ { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Public extension page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExtensionPage" } } } }, "default": { "description": "RFC 9457 problem", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/task": { "post": { "operationId": "createTask", "tags": ["Tasks"], "summary": "Submit a task", "description": "Create one paid task. A charge is recorded before work is available to workers. The response waits at most hold seconds. Processing continues after the wait ends or the client disconnects. Never automatically repeat this POST after an ambiguous timeout. The default JSON body limit is 4 MiB. Enterprise tokens require account whitelisting.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTaskRequest" }, "examples": { "token": { "summary": "Token task", "value": { "type": "hcaptcha_token", "sitekey": "YOUR_SITEKEY", "url": "https://www.easycaptcha.to", "hold": 30 } }, "recognition": { "summary": "Nine-tile binary recognition challenge", "value": { "type": "hcaptcha_recognition", "task": { "request_type": "image_label_binary", "requester_question": { "en": "Please click each image containing a cat." }, "tasklist": [ { "task_key": "1", "datapoint_uri": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+jGZkAAAAASUVORK5CYII=" }, { "task_key": "2", "datapoint_uri": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+jGZkAAAAASUVORK5CYII=" }, { "task_key": "3", "datapoint_uri": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+jGZkAAAAASUVORK5CYII=" }, { "task_key": "4", "datapoint_uri": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+jGZkAAAAASUVORK5CYII=" }, { "task_key": "5", "datapoint_uri": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+jGZkAAAAASUVORK5CYII=" }, { "task_key": "6", "datapoint_uri": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+jGZkAAAAASUVORK5CYII=" }, { "task_key": "7", "datapoint_uri": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+jGZkAAAAASUVORK5CYII=" }, { "task_key": "8", "datapoint_uri": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+jGZkAAAAASUVORK5CYII=" }, { "task_key": "9", "datapoint_uri": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+jGZkAAAAASUVORK5CYII=" } ] } } }, "enterprise": { "summary": "Enterprise task with both pricing modes", "value": { "type": "hcaptcha_enterprise_token", "sitekey": "YOUR_SITEKEY", "url": "https://www.easycaptcha.to", "rqdata": "ENTERPRISE_REQUEST_DATA", "burst": true, "fast": true, "hold": 30 } } } } } }, "responses": { "200": { "description": "The task reached completed or failed during the hold. A failed task embeds its failure in error.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TerminalTask" }, "examples": { "token": { "value": { "task_id": "task_01m40t5ag0e008000000000001", "type": "hcaptcha_token", "status": "completed", "created_at": "2026-10-03T12:00:00Z", "completed_at": "2026-10-03T12:00:10Z", "expires_at": "2026-10-03T12:05:10Z", "result": { "token": "HCAPTCHA_TOKEN" }, "error": null } }, "recognition": { "value": { "task_id": "task_01m40t5ag0e008000000000001", "type": "hcaptcha_recognition", "status": "completed", "created_at": "2026-10-03T12:00:00Z", "completed_at": "2026-10-03T12:00:10Z", "expires_at": "2026-10-03T12:05:10Z", "result": { "1": true, "2": false, "3": false, "4": true, "5": false, "6": false, "7": false, "8": true, "9": false }, "error": null } }, "failed": { "value": { "task_id": "task_01m40t5ag0e008000000000001", "type": "hcaptcha_token", "status": "failed", "created_at": "2026-10-03T12:00:00Z", "completed_at": "2026-10-03T12:00:10Z", "expires_at": "2026-10-03T12:05:10Z", "result": null, "error": { "type": "https://e.easycaptcha.to/task_failed", "title": "Task failed", "detail": "No valid result was returned within the task time budget.", "instance": "request_01m40t5ag0e008000000000005", "code": "task_failed", "request_id": "request_01m40t5ag0e008000000000005" } } } } } } }, "202": { "description": "The task remains queued or running after hold.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PendingTask" }, "example": { "task_id": "task_01m40t5ag0e008000000000001", "type": "hcaptcha_token", "status": "queued", "created_at": "2026-10-03T12:00:00Z", "completed_at": null, "expires_at": null, "result": null, "error": null } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/InvalidCredentials" }, "402": { "$ref": "#/components/responses/InsufficientBalance" }, "403": { "$ref": "#/components/responses/Forbidden" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "504": { "$ref": "#/components/responses/GatewayTimeout" } }, "parameters": [ { "name": "X-Developer-Tag", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 64 }, "description": "Developer revenue-share tag. If also in the body, values must match. Applies only to this request." } ] } }, "/v1/task/{task_id}": { "parameters": [ { "$ref": "#/components/parameters/TaskID" } ], "get": { "operationId": "getTask", "tags": ["Tasks"], "summary": "Get a task", "description": "Return an immediate owned task snapshot without waiting. Completed or failed tasks remain available for five minutes by default. Save the result before expires_at. An unknown, expired or non-owned task returns the same task_not_found error.", "responses": { "200": { "description": "The current snapshot, including pending or failed tasks.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Task" }, "examples": { "token": { "value": { "task_id": "task_01m40t5ag0e008000000000001", "type": "hcaptcha_token", "status": "completed", "created_at": "2026-10-03T12:00:00Z", "completed_at": "2026-10-03T12:00:10Z", "expires_at": "2026-10-03T12:05:10Z", "result": { "token": "HCAPTCHA_TOKEN" }, "error": null } }, "recognition": { "value": { "task_id": "task_01m40t5ag0e008000000000001", "type": "hcaptcha_recognition", "status": "completed", "created_at": "2026-10-03T12:00:00Z", "completed_at": "2026-10-03T12:00:10Z", "expires_at": "2026-10-03T12:05:10Z", "result": { "1": true, "2": false, "3": false, "4": true, "5": false, "6": false, "7": false, "8": true, "9": false }, "error": null } }, "failed": { "value": { "task_id": "task_01m40t5ag0e008000000000001", "type": "hcaptcha_token", "status": "failed", "created_at": "2026-10-03T12:00:00Z", "completed_at": "2026-10-03T12:00:10Z", "expires_at": "2026-10-03T12:05:10Z", "result": null, "error": { "type": "https://e.easycaptcha.to/task_failed", "title": "Task failed", "detail": "No valid result was returned within the task time budget.", "instance": "request_01m40t5ag0e008000000000005", "code": "task_failed", "request_id": "request_01m40t5ag0e008000000000005" } } } } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/InvalidCredentials" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/TaskNotFound" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "504": { "$ref": "#/components/responses/GatewayTimeout" } } } }, "/v1/task/{task_id}/feedback": { "parameters": [ { "$ref": "#/components/parameters/TaskID" } ], "post": { "operationId": "submitTaskFeedback", "tags": ["Tasks"], "summary": "Report a task outcome", "description": "Report whether an owned, completed and still-retained task succeeded in use. Feedback is used to improve AI performance. Repeating identical feedback succeeds; changing a previous report conflicts.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedbackRequest" }, "examples": { "success": { "value": { "success": true } }, "failure": { "value": { "success": false } } } } } }, "responses": { "204": { "description": "Feedback recorded, or identical feedback was already recorded. No response body.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/InvalidCredentials" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/TaskNotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "504": { "$ref": "#/components/responses/GatewayTimeout" } } } }, "/v1/balance": { "get": { "operationId": "getBalance", "tags": ["Account"], "summary": "Get available balance", "description": "Return the authenticated account’s available USD credit as a signed decimal integer string in microcents. 1 USD = 100,000,000 microcents.", "responses": { "200": { "description": "Available account balance.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Balance" }, "example": { "currency": "USD", "balance_microcents": "100000000" } } } }, "401": { "$ref": "#/components/responses/InvalidCredentials" }, "403": { "$ref": "#/components/responses/Forbidden" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "504": { "$ref": "#/components/responses/GatewayTimeout" } } } }, "/v1/extensions/{extension_id}/version/@latest": { "parameters": [ { "$ref": "#/components/parameters/ExtensionID" } ], "get": { "operationId": "getLatestExtensionVersion", "tags": ["Extensions"], "summary": "Get the latest extension version", "security": [], "description": "Return the latest stable release with a temporary signed download link. Follow download_url before expires_at; obtain a fresh link after expiry.", "responses": { "200": { "description": "Selected release metadata and signed download link.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExtensionVersion" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/InvalidCredentials" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "504": { "$ref": "#/components/responses/GatewayTimeout" } } } }, "/v1/rates": { "get": { "operationId": "getRates", "tags": ["Account"], "summary": "Get your effective task rates", "description": "Current effective base rates and mode multipliers for the authenticated account, including custom pricing. Recognition has one group per nine binary tiles or per area/drag image. Multiply standard_microcents by the group count and selected mode multiplier, then round upward once to whole microcents. When both modes are enabled, apply burst_multiplier and fast_multiplier. Existing charges retain their original prices.", "responses": { "200": { "description": "Current effective account rates.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountRates" }, "example": { "currency": "USD", "rates": { "hcaptcha_recognition": { "standard_microcents": "10000" }, "hcaptcha_token": { "standard_microcents": "200000" }, "hcaptcha_enterprise_token": { "standard_microcents": "500000" } }, "burst_multiplier": 1.5, "fast_multiplier": 1.2 } } } }, "401": { "$ref": "#/components/responses/InvalidCredentials" }, "403": { "$ref": "#/components/responses/Forbidden" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "504": { "$ref": "#/components/responses/GatewayTimeout" } } } }, "/v1/task-history": { "get": { "operationId": "getTaskHistory", "tags": ["Account"], "summary": "Get recent task history", "description": "Latest 50 admitted tasks, newest first, created within the last seven days. Summaries contain no task payloads, solutions or tokens. Entries may disappear sooner when newer tasks exceed the 50-entry limit. No query parameters or request body. Costs are the original charges, not net spending after reversals.", "responses": { "200": { "description": "Recent task summaries.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskHistory" }, "example": { "currency": "USD", "items": [ { "task_id": "task_01m40t5ag0e008000000000001", "type": "hcaptcha_recognition", "status": "completed", "cost_microcents": "20000", "created_at": "2026-10-04T12:00:00Z", "completed_at": "2026-10-04T12:00:02Z" } ] } } } }, "401": { "$ref": "#/components/responses/InvalidCredentials" }, "403": { "$ref": "#/components/responses/Forbidden" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "504": { "$ref": "#/components/responses/GatewayTimeout" } } } }, "/v1/extensions/{extension_id}/releases": { "parameters": [ { "$ref": "#/components/parameters/ExtensionID" } ], "get": { "operationId": "getExtensionReleases", "tags": ["Extensions"], "summary": "Get available extension releases", "security": [], "description": "Return the latest stable release and the newest prerelease only when it is newer than stable. Each includes a temporary signed download link. Either field can be null; when no releases are available, both fields are null.", "responses": { "200": { "description": "Available stable and prerelease downloads.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExtensionReleases" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/InvalidCredentials" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "504": { "$ref": "#/components/responses/GatewayTimeout" } } } }, "/v1/extensions/{extension_id}/version/{version_id}": { "parameters": [ { "$ref": "#/components/parameters/ExtensionID" }, { "name": "version_id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ExtensionVersionID" } } ], "get": { "operationId": "getExtensionVersion", "tags": ["Extensions"], "summary": "Get an extension release", "security": [], "description": "Return metadata and a temporary signed download link for a specific release. Unavailable releases return 404. Follow download_url before expires_at; obtain a fresh link after expiry.", "responses": { "200": { "description": "Selected release metadata and signed download link.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExtensionVersion" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/InvalidCredentials" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGateway" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "504": { "$ref": "#/components/responses/GatewayTimeout" } } } } }, "components": { "securitySchemes": { "APIKey": { "type": "http", "scheme": "bearer", "description": "Customer API key: sk- followed by 43 unpadded base64url characters. Send it only in the Authorization header; never in a URL or request body." } }, "parameters": { "TaskID": { "name": "task_id", "in": "path", "required": true, "description": "Identifier returned by task submission.", "schema": { "$ref": "#/components/schemas/TaskID" } }, "ExtensionID": { "name": "extension_id", "in": "path", "required": true, "description": "Package identifier.", "schema": { "$ref": "#/components/schemas/ExtensionID" } } }, "headers": { "RequestID": { "description": "Canonical request TypeID for tracing. On an HTTP error it matches instance and request_id in the body.", "schema": { "$ref": "#/components/schemas/RequestID" } }, "NoStore": { "description": "Responses must not be cached.", "schema": { "type": "string", "const": "no-store" } }, "RetryAfter": { "description": "Delay in seconds before retrying, or an HTTP-date.", "schema": { "type": "string" }, "example": "1" }, "Authenticate": { "description": "Bearer authentication challenge.", "schema": { "type": "string" }, "example": "Bearer realm=\"easycaptcha\"" }, "Allow": { "description": "Comma-separated supported HTTP methods for the resource.", "schema": { "type": "string" }, "example": "GET, HEAD" } }, "schemas": { "TaskID": { "type": "string", "pattern": "^task_[0-7][0123456789abcdefghjkmnpqrstvwxyz]{9}[ef][0123456789abcdefghjkmnpqrstvwxyz]{2}[89abrstv][0123456789abcdefghjkmnpqrstvwxyz]{12}$", "description": "Canonical task TypeID with a UUIDv7 payload and the RFC UUID variant.", "examples": ["task_01m40t5ag0e008000000000001"] }, "RequestID": { "type": "string", "pattern": "^request_[0-7][0123456789abcdefghjkmnpqrstvwxyz]{9}[ef][0123456789abcdefghjkmnpqrstvwxyz]{2}[89abrstv][0123456789abcdefghjkmnpqrstvwxyz]{12}$", "description": "Canonical request TypeID with a UUIDv7 payload and the RFC UUID variant.", "examples": ["request_01m40t5ag0e008000000000005"] }, "ExtensionID": { "type": "string", "pattern": "^extension_[0-7][0123456789abcdefghjkmnpqrstvwxyz]{9}[ef][0123456789abcdefghjkmnpqrstvwxyz]{2}[89abrstv][0123456789abcdefghjkmnpqrstvwxyz]{12}$", "description": "Canonical extension TypeID with a UUIDv7 payload and the RFC UUID variant.", "examples": ["extension_01m40t5ag0e008000000000006"] }, "ExtensionVersionID": { "type": "string", "pattern": "^extension_version_[0-7][0123456789abcdefghjkmnpqrstvwxyz]{9}[ef][0123456789abcdefghjkmnpqrstvwxyz]{2}[89abrstv][0123456789abcdefghjkmnpqrstvwxyz]{12}$", "description": "Canonical extension_version TypeID with a UUIDv7 payload and the RFC UUID variant.", "examples": ["extension_version_01m40t5ag0e008000000000007"] }, "TaskType": { "type": "string", "enum": [ "hcaptcha_recognition", "hcaptcha_token", "hcaptcha_enterprise_token" ] }, "RecognitionTaskRequest": { "type": "object", "additionalProperties": false, "required": ["type", "task"], "properties": { "type": { "type": "string", "const": "hcaptcha_recognition" }, "task": { "$ref": "#/components/schemas/HCaptchaChallenge", "description": "The hCaptcha challenge object. Required fields, supported request types, task counts, image inputs, and drag entities are validated before admission. Additional challenge fields are preserved." }, "hold": { "type": "integer", "minimum": 0, "maximum": 30, "default": 0, "description": "Maximum seconds to wait for completion. Ending the wait or disconnecting does not cancel the task or change its lifetime." }, "burst": { "type": "boolean", "default": false, "description": "Allow task admission up to 5× the account’s normal weighted concurrency limit, at 1.5× the normal task price. No activation window or cooldown." }, "fast": { "type": "boolean", "default": false, "description": "Raise queue priority at 1.2× the normal task price. If burst is also enabled, both price multipliers apply. Fractional microcents round upward once." }, "developer_tag": { "type": "string", "maxLength": 64, "description": "Activated developer tag; credits 5% of net task spend to its owner daily." }, "sitekey": { "type": "string", "minLength": 1, "maxLength": 1024, "description": "Optional hCaptcha sitekey used for challenge distribution and outcome attribution. Reported by the caller; it does not affect authorization." }, "url": { "type": "string", "format": "uri", "maxLength": 8192, "description": "Optional HTTP(S) page URL for sitekey observations. Queries and fragments are removed from the durable catalog." } }, "description": "Billed per challenge group: nine binary tiles, one area-selection image, or one drag/drop image. Two or three groups cost 2× or 3× the base recognition price. Group count and burst/fast multipliers are applied before rounding upward once to a whole microcent." }, "TokenTaskRequest": { "type": "object", "additionalProperties": false, "required": ["type", "sitekey", "url"], "properties": { "type": { "type": "string", "const": "hcaptcha_token" }, "sitekey": { "type": "string", "minLength": 1, "maxLength": 1024, "pattern": "\\S", "description": "Site key for the target hCaptcha integration." }, "url": { "type": "string", "format": "uri", "pattern": "^https?://", "maxLength": 8192, "description": "HTTP(S) page URL with a host and without embedded credentials." }, "hold": { "type": "integer", "minimum": 0, "maximum": 30, "default": 0, "description": "Maximum seconds to wait for completion. Ending the wait or disconnecting does not cancel the task or change its lifetime." }, "burst": { "type": "boolean", "default": false, "description": "Allow task admission up to 5× the account’s normal weighted concurrency limit, at 1.5× the normal task price. No activation window or cooldown." }, "fast": { "type": "boolean", "default": false, "description": "Raise queue priority at 1.2× the normal task price. If burst is also enabled, both price multipliers apply. Fractional microcents round upward once." }, "proxy": { "$ref": "#/components/schemas/TokenProxy" }, "developer_tag": { "type": "string", "maxLength": 64, "description": "Activated developer tag; credits 5% of net task spend to its owner daily." } } }, "EnterpriseTaskRequest": { "type": "object", "additionalProperties": false, "required": ["type", "sitekey", "url", "rqdata"], "properties": { "type": { "type": "string", "const": "hcaptcha_enterprise_token" }, "sitekey": { "type": "string", "minLength": 1, "maxLength": 1024, "pattern": "\\S", "description": "Site key for the target hCaptcha integration." }, "url": { "type": "string", "format": "uri", "pattern": "^https?://", "maxLength": 8192, "description": "HTTP(S) page URL with a host and without embedded credentials." }, "rqdata": { "type": "string", "minLength": 1, "maxLength": 262144, "description": "Enterprise request data. Explicit account whitelisting is required for this task type." }, "hold": { "type": "integer", "minimum": 0, "maximum": 30, "default": 0, "description": "Maximum seconds to wait for completion. Ending the wait or disconnecting does not cancel the task or change its lifetime." }, "burst": { "type": "boolean", "default": false, "description": "Allow task admission up to 5× the account’s normal weighted concurrency limit, at 1.5× the normal task price. No activation window or cooldown." }, "fast": { "type": "boolean", "default": false, "description": "Raise queue priority at 1.2× the normal task price. If burst is also enabled, both price multipliers apply. Fractional microcents round upward once." }, "proxy": { "$ref": "#/components/schemas/TokenProxy" }, "developer_tag": { "type": "string", "maxLength": 64, "description": "Activated developer tag; credits 5% of net task spend to its owner daily." } } }, "CreateTaskRequest": { "oneOf": [ { "$ref": "#/components/schemas/RecognitionTaskRequest" }, { "$ref": "#/components/schemas/TokenTaskRequest" }, { "$ref": "#/components/schemas/EnterpriseTaskRequest" } ], "discriminator": { "propertyName": "type", "mapping": { "hcaptcha_recognition": "#/components/schemas/RecognitionTaskRequest", "hcaptcha_token": "#/components/schemas/TokenTaskRequest", "hcaptcha_enterprise_token": "#/components/schemas/EnterpriseTaskRequest" } } }, "RecognitionResult": { "description": "Transformed recognition result keyed by task_key. Binary values are booleans; area values are ordered selections; drag values include every entity in task order, retaining original coords for entities not moved. Failed worker groups map to null.", "anyOf": [ { "$ref": "#/components/schemas/RecognitionBinaryResult" }, { "$ref": "#/components/schemas/RecognitionAreaResult" }, { "$ref": "#/components/schemas/RecognitionDragResult" } ] }, "TokenResult": { "type": "object", "additionalProperties": false, "required": ["token"], "properties": { "token": { "type": "string", "minLength": 1, "pattern": "\\S", "description": "The completed hCaptcha token." } } }, "Problem": { "type": "object", "description": "RFC 9457 Problem Details. The status equals the HTTP response status. Unknown extension members may be added; clients should ignore them.", "required": [ "type", "title", "status", "detail", "instance", "code", "request_id" ], "properties": { "type": { "type": "string", "format": "uri", "pattern": "^https://e\\.easycaptcha\\.to/[a-z][a-z_]*$", "description": "Stable problem identifier. Use this field to classify errors." }, "title": { "type": "string", "description": "Stable human-readable summary." }, "detail": { "type": "string", "description": "Safe explanation of this occurrence." }, "instance": { "$ref": "#/components/schemas/RequestID", "description": "Request TypeID, identical to request_id. It is a relative URI reference, not a lookup URL." }, "code": { "type": "string", "pattern": "^[a-z][a-z_]*$", "description": "Stable short problem code; type is https://e.easycaptcha.to/." }, "request_id": { "$ref": "#/components/schemas/RequestID", "description": "The same canonical request TypeID as instance." }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "Actual HTTP response status." } }, "additionalProperties": true }, "EmbeddedProblem": { "type": "object", "description": "Stored task failure using the original failure request ID. Numeric HTTP status is omitted.", "required": [ "type", "title", "detail", "instance", "code", "request_id" ], "properties": { "type": { "type": "string", "format": "uri", "pattern": "^https://e\\.easycaptcha\\.to/[a-z][a-z_]*$", "description": "Stable problem identifier. Use this field to classify errors." }, "title": { "type": "string", "description": "Stable human-readable summary." }, "detail": { "type": "string", "description": "Safe explanation of this occurrence." }, "instance": { "$ref": "#/components/schemas/RequestID", "description": "Request TypeID, identical to request_id. It is a relative URI reference, not a lookup URL." }, "code": { "type": "string", "pattern": "^[a-z][a-z_]*$", "description": "Stable short problem code; type is https://e.easycaptcha.to/." }, "request_id": { "$ref": "#/components/schemas/RequestID", "description": "The same canonical request TypeID as instance." }, "status": false }, "additionalProperties": true }, "PendingTask": { "type": "object", "additionalProperties": false, "required": [ "task_id", "type", "status", "created_at", "completed_at", "expires_at", "result", "error" ], "properties": { "task_id": { "$ref": "#/components/schemas/TaskID" }, "type": { "$ref": "#/components/schemas/TaskType" }, "status": { "type": "string", "enum": ["queued", "running"] }, "created_at": { "type": "string", "format": "date-time", "pattern": "Z$", "description": "UTC RFC 3339 timestamp." }, "completed_at": { "type": "null" }, "expires_at": { "type": "null" }, "result": { "type": "null" }, "error": { "type": "null" } } }, "CompletedTask": { "type": "object", "additionalProperties": false, "required": [ "task_id", "type", "status", "created_at", "completed_at", "expires_at", "result", "error" ], "properties": { "task_id": { "$ref": "#/components/schemas/TaskID" }, "type": { "$ref": "#/components/schemas/TaskType" }, "status": { "type": "string", "enum": ["completed"] }, "created_at": { "type": "string", "format": "date-time", "pattern": "Z$", "description": "UTC RFC 3339 timestamp." }, "completed_at": { "type": "string", "format": "date-time", "pattern": "Z$", "description": "UTC RFC 3339 timestamp." }, "expires_at": { "type": "string", "format": "date-time", "pattern": "Z$", "description": "UTC RFC 3339 timestamp." }, "result": { "oneOf": [ { "$ref": "#/components/schemas/RecognitionResult" }, { "$ref": "#/components/schemas/TokenResult" } ] }, "error": { "type": "null" } }, "allOf": [ { "if": { "properties": { "type": { "const": "hcaptcha_recognition" } } }, "then": { "properties": { "result": { "$ref": "#/components/schemas/RecognitionResult" } } }, "else": { "properties": { "result": { "$ref": "#/components/schemas/TokenResult" } } } } ] }, "FailedTask": { "type": "object", "additionalProperties": false, "required": [ "task_id", "type", "status", "created_at", "completed_at", "expires_at", "result", "error" ], "properties": { "task_id": { "$ref": "#/components/schemas/TaskID" }, "type": { "$ref": "#/components/schemas/TaskType" }, "status": { "type": "string", "enum": ["failed"] }, "created_at": { "type": "string", "format": "date-time", "pattern": "Z$", "description": "UTC RFC 3339 timestamp." }, "completed_at": { "type": "string", "format": "date-time", "pattern": "Z$", "description": "UTC RFC 3339 timestamp." }, "expires_at": { "type": "string", "format": "date-time", "pattern": "Z$", "description": "UTC RFC 3339 timestamp." }, "result": { "type": "null" }, "error": { "$ref": "#/components/schemas/EmbeddedProblem" } } }, "Task": { "oneOf": [ { "$ref": "#/components/schemas/PendingTask" }, { "$ref": "#/components/schemas/CompletedTask" }, { "$ref": "#/components/schemas/FailedTask" } ], "description": "Task snapshot. Unavailable lifecycle fields are present as null. A failed task is a successful HTTP lookup with an embedded error." }, "TerminalTask": { "oneOf": [ { "$ref": "#/components/schemas/CompletedTask" }, { "$ref": "#/components/schemas/FailedTask" } ] }, "FeedbackRequest": { "type": "object", "additionalProperties": false, "required": ["success"], "properties": { "success": { "type": "boolean", "description": "Whether the completed task succeeded in use. Feedback is used to improve AI performance." } } }, "Balance": { "type": "object", "required": ["currency", "balance_microcents"], "additionalProperties": false, "properties": { "currency": { "type": "string", "const": "USD" }, "balance_microcents": { "type": "string", "pattern": "^(0|-?[1-9][0-9]*)$", "description": "Signed integer microcents. 1 USD = 100,000,000 microcents. Use integer or decimal arithmetic." } } }, "ExtensionInfo": { "type": "object", "required": ["extension_id", "name", "browser", "flags", "visibility", "permission_requirements", "latest_version_id", "created_at"], "properties": { "extension_id": { "$ref": "#/components/schemas/ExtensionID" }, "name": { "type": "string" }, "browser": { "type": "string", "enum": ["chromium", "firefox"] }, "flags": { "type": "array", "items": { "type": "string" } }, "visibility": { "type": "string", "enum": ["public", "unlisted", "private"] }, "permission_requirements": { "type": "array", "maxItems": 32, "items": { "type": "string" } }, "latest_version_id": { "anyOf": [{ "$ref": "#/components/schemas/ExtensionVersionID" }, { "type": "null" }] }, "created_at": { "type": "string", "format": "date-time" } } }, "ExtensionPage": { "type": "object", "required": ["items", "next_cursor"], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ExtensionInfo" } }, "next_cursor": { "type": ["string", "null"] } } }, "ExtensionVersion": { "type": "object", "required": [ "extension_version_id", "extension_id", "version", "browser", "filename", "size", "sha256", "release_notes", "download_url", "expires_at", "prerelease" ], "properties": { "extension_version_id": { "$ref": "#/components/schemas/ExtensionVersionID" }, "extension_id": { "$ref": "#/components/schemas/ExtensionID" }, "version": { "type": "string", "minLength": 1, "description": "SemVer version, such as 1.2.0 or 1.3.0-beta.1.", "maxLength": 128 }, "browser": { "type": "string", "enum": ["chromium", "firefox"], "description": "Target browser family." }, "filename": { "type": "string", "minLength": 1 }, "size": { "type": "integer", "minimum": 1, "format": "int64", "description": "Package size in bytes." }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Lowercase hexadecimal SHA-256 digest of the package." }, "release_notes": { "type": "string" }, "download_url": { "type": "string", "format": "uri", "pattern": "^https://", "description": "Temporary signed download URL. Treat the complete URL as a credential and avoid logging it." }, "expires_at": { "type": "string", "format": "date-time", "pattern": "Z$", "description": "UTC expiry of the signed download URL." }, "prerelease": { "type": "boolean", "description": "True when the SemVer version has a prerelease suffix." } }, "additionalProperties": false }, "HCaptchaImageInput": { "type": "string", "description": "Nonempty base64 image/video data URI. HTTP(S) and other remote media URLs are not accepted.", "pattern": "^data:(image|video)/[^,]+;base64,[A-Za-z0-9+/\\r\\n]+={0,2}$" }, "HCaptchaImageTask": { "type": "object", "additionalProperties": true, "required": ["task_key", "datapoint_uri"], "properties": { "task_key": { "type": "string", "minLength": 1, "description": "Original hCaptcha task identifier. Must be unique within tasklist." }, "datapoint_uri": { "$ref": "#/components/schemas/HCaptchaImageInput" } } }, "HCaptchaDragEntity": { "type": "object", "additionalProperties": true, "required": ["entity_id", "entity_uri", "size", "coords"], "properties": { "entity_id": { "type": "string", "minLength": 1, "description": "Original entity identifier. Must be unique within this task image." }, "entity_uri": { "$ref": "#/components/schemas/HCaptchaImageInput" }, "size": { "type": "array", "minItems": 2, "maxItems": 2, "items": { "type": "number", "exclusiveMinimum": 0 }, "description": "Positive finite width and height in pixels." }, "coords": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2, "description": "Original [x, y] coordinates, retained when the worker does not move this entity." } } }, "HCaptchaDragTask": { "allOf": [ { "$ref": "#/components/schemas/HCaptchaImageTask" }, { "type": "object", "required": ["entities"], "properties": { "entities": { "type": "array", "minItems": 1, "maxItems": 5, "items": { "$ref": "#/components/schemas/HCaptchaDragEntity" } } } } ] }, "HCaptchaChallenge": { "oneOf": [ { "$ref": "#/components/schemas/HCaptchaBinaryChallenge" }, { "$ref": "#/components/schemas/HCaptchaAreaSelectChallenge" }, { "$ref": "#/components/schemas/HCaptchaDragDropChallenge" } ], "discriminator": { "propertyName": "request_type", "mapping": { "image_label_binary": "#/components/schemas/HCaptchaBinaryChallenge", "image_label_area_select": "#/components/schemas/HCaptchaAreaSelectChallenge", "image_drag_drop": "#/components/schemas/HCaptchaDragDropChallenge" } } }, "HCaptchaBinaryChallenge": { "type": "object", "additionalProperties": true, "required": ["request_type", "requester_question", "tasklist"], "properties": { "request_type": { "type": "string", "const": "image_label_binary" }, "requester_question": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "object", "required": ["en"], "properties": { "en": { "type": "string", "minLength": 1 } }, "additionalProperties": { "type": "string" } } ], "description": "Nonblank question text, or localized strings with a nonblank English en entry." }, "requester_question_example": { "oneOf": [ { "$ref": "#/components/schemas/HCaptchaImageInput" }, { "type": "array", "items": { "$ref": "#/components/schemas/HCaptchaImageInput" } }, { "type": "string", "const": "" }, { "type": "null" } ], "description": "Optional example image or array of example images. May be omitted, null, an empty string, or an empty array." }, "tasklist": { "oneOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/HCaptchaImageTask" }, "minItems": 9, "maxItems": 9 }, { "type": "array", "items": { "$ref": "#/components/schemas/HCaptchaImageTask" }, "minItems": 18, "maxItems": 18 }, { "type": "array", "items": { "$ref": "#/components/schemas/HCaptchaImageTask" }, "minItems": 27, "maxItems": 27 } ] } } }, "HCaptchaAreaSelectChallenge": { "type": "object", "additionalProperties": true, "required": ["request_type", "requester_question", "tasklist"], "properties": { "request_type": { "type": "string", "const": "image_label_area_select" }, "requester_question": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "object", "required": ["en"], "properties": { "en": { "type": "string", "minLength": 1 } }, "additionalProperties": { "type": "string" } } ], "description": "Nonblank question text, or localized strings with a nonblank English en entry." }, "requester_question_example": { "oneOf": [ { "$ref": "#/components/schemas/HCaptchaImageInput" }, { "type": "array", "items": { "$ref": "#/components/schemas/HCaptchaImageInput" } }, { "type": "string", "const": "" }, { "type": "null" } ], "description": "Optional example image or array of example images. May be omitted, null, an empty string, or an empty array." }, "tasklist": { "type": "array", "items": { "$ref": "#/components/schemas/HCaptchaImageTask" }, "minItems": 1, "maxItems": 3 } } }, "HCaptchaDragDropChallenge": { "type": "object", "additionalProperties": true, "required": ["request_type", "requester_question", "tasklist"], "properties": { "request_type": { "type": "string", "const": "image_drag_drop" }, "requester_question": { "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "object", "required": ["en"], "properties": { "en": { "type": "string", "minLength": 1 } }, "additionalProperties": { "type": "string" } } ], "description": "Nonblank question text, or localized strings with a nonblank English en entry." }, "requester_question_example": { "oneOf": [ { "$ref": "#/components/schemas/HCaptchaImageInput" }, { "type": "array", "items": { "$ref": "#/components/schemas/HCaptchaImageInput" } }, { "type": "string", "const": "" }, { "type": "null" } ], "description": "Optional example image or array of example images. May be omitted, null, an empty string, or an empty array." }, "tasklist": { "type": "array", "items": { "$ref": "#/components/schemas/HCaptchaDragTask" }, "minItems": 1, "maxItems": 3 } } }, "RecognitionAreaSelection": { "type": "object", "additionalProperties": false, "required": ["entity_coords", "entity_name"], "properties": { "entity_coords": { "oneOf": [ { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 }, { "type": "array", "items": { "type": "number" }, "minItems": 4, "maxItems": 4 } ], "description": "Point [x, y], or rectangle [x, y, x+w, y+h], using absolute pixel coordinates in the source image/video/canvas." }, "entity_name": { "type": "integer", "minimum": 0, "description": "Zero-based click order within this task image." } } }, "RecognitionDragPlacement": { "type": "object", "additionalProperties": false, "required": ["entity_coords", "entity_name"], "properties": { "entity_coords": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2, "description": "Absolute [x, y] pixel coordinates for moved entities; original task coords for entities not moved." }, "entity_name": { "type": "string", "description": "Original task entity_id." } } }, "RecognitionBinaryResult": { "type": "object", "additionalProperties": { "type": ["boolean", "null"] }, "description": "Result keyed by original task_key. Failed groups produce null values." }, "RecognitionAreaResult": { "type": "object", "additionalProperties": { "type": ["array", "null"], "items": { "$ref": "#/components/schemas/RecognitionAreaSelection" } }, "description": "Result keyed by original task_key. Failed groups produce null values." }, "RecognitionDragResult": { "type": "object", "additionalProperties": { "type": ["array", "null"], "items": { "$ref": "#/components/schemas/RecognitionDragPlacement" } }, "description": "Result keyed by original task_key. Failed groups produce null values." }, "TaskRate": { "type": "object", "additionalProperties": false, "required": ["standard_microcents"], "properties": { "standard_microcents": { "type": "string", "pattern": "^[1-9][0-9]*$", "description": "Positive integer USD microcents. 1 USD = 100,000,000 microcents." } }, "description": "Base price for one recognition group or one token task, in integer USD microcents." }, "AccountRates": { "type": "object", "additionalProperties": false, "required": [ "currency", "rates", "burst_multiplier", "fast_multiplier" ], "properties": { "currency": { "type": "string", "const": "USD" }, "rates": { "type": "object", "additionalProperties": false, "required": [ "hcaptcha_recognition", "hcaptcha_token", "hcaptcha_enterprise_token" ], "properties": { "hcaptcha_recognition": { "$ref": "#/components/schemas/TaskRate" }, "hcaptcha_token": { "$ref": "#/components/schemas/TaskRate" }, "hcaptcha_enterprise_token": { "$ref": "#/components/schemas/TaskRate" } } }, "burst_multiplier": { "type": "number", "minimum": 0.0001, "maximum": 100, "description": "Burst price multiplier. The standard multiplier is 1.5." }, "fast_multiplier": { "type": "number", "minimum": 0.0001, "maximum": 100, "description": "Fast price multiplier. The standard multiplier is 1.2." } }, "description": "Current effective base rates and mode multipliers for the authenticated account, including custom pricing. Recognition has one group per nine binary tiles or per area/drag image. Multiply standard_microcents by the group count and selected mode multiplier, then round upward once to whole microcents. When both modes are enabled, apply burst_multiplier and fast_multiplier. Existing charges retain their original prices." }, "TaskHistoryEntry": { "type": "object", "additionalProperties": false, "required": [ "task_id", "type", "status", "cost_microcents", "created_at", "completed_at" ], "properties": { "task_id": { "$ref": "#/components/schemas/TaskID" }, "type": { "$ref": "#/components/schemas/TaskType" }, "status": { "type": "string", "enum": ["pending", "completed", "failed"], "description": "Pending covers queued/running tasks. Completed means a valid solution was accepted; failed means terminal failure." }, "cost_microcents": { "type": "string", "pattern": "^[1-9][0-9]*$", "description": "Original price charged at admission, including groups and mode multipliers. This is the gross charge, before any charge reversal." }, "created_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": ["string", "null"], "format": "date-time" } } }, "TaskHistory": { "type": "object", "additionalProperties": false, "required": ["currency", "items"], "properties": { "currency": { "type": "string", "const": "USD" }, "items": { "type": "array", "maxItems": 50, "items": { "$ref": "#/components/schemas/TaskHistoryEntry" } } }, "description": "Latest 50 admitted tasks, newest first, created within the last seven days. Summaries contain no task payloads, solutions or tokens. Entries may disappear sooner when newer tasks exceed the 50-entry limit." }, "ExtensionReleases": { "type": "object", "required": ["stable", "prerelease"], "additionalProperties": false, "properties": { "stable": { "anyOf": [ { "$ref": "#/components/schemas/ExtensionVersion" }, { "type": "null" } ], "description": "Latest stable release, or null if none is available." }, "prerelease": { "anyOf": [ { "$ref": "#/components/schemas/ExtensionVersion" }, { "type": "null" } ], "description": "Newest prerelease newer than stable, or null. Also available when no stable release exists." } } }, "TokenProxy": { "type": "object", "additionalProperties": false, "properties": { "scheme": { "type": "string", "enum": ["http", "https", "socks5"] }, "host": { "type": "string", "minLength": 1, "maxLength": 253 }, "port": { "type": "integer", "minimum": 1, "maximum": 65535 }, "username": { "type": "string", "maxLength": 1024 }, "password": { "type": "string", "maxLength": 1024 } }, "required": ["scheme", "host", "port"], "description": "Optional proxy passed to token workers for challenge traffic. Credentials are private." } }, "responses": { "InvalidRequest": { "description": "Invalid input, task type, identifier or JSON body.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Problem" }, { "properties": { "status": { "const": 400 } } } ] }, "example": { "type": "https://e.easycaptcha.to/invalid_request", "title": "Invalid request", "status": 400, "detail": "Invalid input, task type, identifier or JSON body.", "instance": "request_01m40t5ag0e008000000000005", "code": "invalid_request", "request_id": "request_01m40t5ag0e008000000000005" } } } }, "InvalidCredentials": { "description": "Missing, invalid or revoked API key.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "WWW-Authenticate": { "$ref": "#/components/headers/Authenticate" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Problem" }, { "properties": { "status": { "const": 401 } } } ] }, "example": { "type": "https://e.easycaptcha.to/invalid_credentials", "title": "Invalid credentials", "status": 401, "detail": "Missing, invalid or revoked API key.", "instance": "request_01m40t5ag0e008000000000005", "code": "invalid_credentials", "request_id": "request_01m40t5ag0e008000000000005" } } } }, "InsufficientBalance": { "description": "Available credit is insufficient for this task.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Problem" }, { "properties": { "status": { "const": 402 } } } ] }, "example": { "type": "https://e.easycaptcha.to/insufficient_balance", "title": "Insufficient balance", "status": 402, "detail": "Available credit is insufficient for this task.", "instance": "request_01m40t5ag0e008000000000005", "code": "insufficient_balance", "request_id": "request_01m40t5ag0e008000000000005" } } } }, "Forbidden": { "description": "Permission denied or the account is suspended. Enterprise token tasks require explicit whitelisting.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Problem" }, { "properties": { "status": { "const": 403 } } } ] }, "examples": { "permission": { "value": { "type": "https://e.easycaptcha.to/forbidden", "title": "Forbidden", "status": 403, "detail": "Permission denied or the account is suspended. Enterprise token tasks require explicit whitelisting.", "instance": "request_01m40t5ag0e008000000000005", "code": "forbidden", "request_id": "request_01m40t5ag0e008000000000005" } }, "suspended": { "value": { "type": "https://e.easycaptcha.to/account_suspended", "title": "Account suspended", "status": 403, "detail": "This account is suspended.", "instance": "request_01m40t5ag0e008000000000005", "code": "account_suspended", "request_id": "request_01m40t5ag0e008000000000005" } } } } } }, "NotFound": { "description": "The resource is unknown, unavailable or not owned by this account.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Problem" }, { "properties": { "status": { "const": 404 } } } ] }, "example": { "type": "https://e.easycaptcha.to/not_found", "title": "Not found", "status": 404, "detail": "The resource is unknown, unavailable or not owned by this account.", "instance": "request_01m40t5ag0e008000000000005", "code": "not_found", "request_id": "request_01m40t5ag0e008000000000005" } } } }, "MethodNotAllowed": { "description": "This method is not supported for the resource.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "Allow": { "$ref": "#/components/headers/Allow" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Problem" }, { "properties": { "status": { "const": 405 } } } ] }, "example": { "type": "https://e.easycaptcha.to/method_not_allowed", "title": "Method not allowed", "status": 405, "detail": "This method is not supported for the resource.", "instance": "request_01m40t5ag0e008000000000005", "code": "method_not_allowed", "request_id": "request_01m40t5ag0e008000000000005" } } } }, "Conflict": { "description": "A different feedback result has already been recorded, or the task has not completed.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Problem" }, { "properties": { "status": { "const": 409 } } } ] }, "example": { "type": "https://e.easycaptcha.to/conflict", "title": "Conflict", "status": 409, "detail": "A different feedback result has already been recorded, or the task has not completed.", "instance": "request_01m40t5ag0e008000000000005", "code": "conflict", "request_id": "request_01m40t5ag0e008000000000005" } } } }, "PayloadTooLarge": { "description": "The request body exceeds the configured size limit.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Problem" }, { "properties": { "status": { "const": 413 } } } ] }, "example": { "type": "https://e.easycaptcha.to/payload_too_large", "title": "Payload too large", "status": 413, "detail": "The request body exceeds the configured size limit.", "instance": "request_01m40t5ag0e008000000000005", "code": "payload_too_large", "request_id": "request_01m40t5ag0e008000000000005" } } } }, "UnsupportedMediaType": { "description": "Use application/json for JSON request bodies.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Problem" }, { "properties": { "status": { "const": 415 } } } ] }, "example": { "type": "https://e.easycaptcha.to/unsupported_media_type", "title": "Unsupported media type", "status": 415, "detail": "Use application/json for JSON request bodies.", "instance": "request_01m40t5ag0e008000000000005", "code": "unsupported_media_type", "request_id": "request_01m40t5ag0e008000000000005" } } } }, "RateLimited": { "description": "The account concurrency or request rate limit was reached.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Problem" }, { "properties": { "status": { "const": 429 } } } ] }, "example": { "type": "https://e.easycaptcha.to/rate_limited", "title": "Rate limited", "status": 429, "detail": "The account concurrency or request rate limit was reached.", "instance": "request_01m40t5ag0e008000000000005", "code": "rate_limited", "request_id": "request_01m40t5ag0e008000000000005" } } } }, "InternalError": { "description": "The request could not be completed. Private diagnostics are not returned.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Problem" }, { "properties": { "status": { "const": 500 } } } ] }, "example": { "type": "https://e.easycaptcha.to/internal_error", "title": "Internal error", "status": 500, "detail": "The request could not be completed. Private diagnostics are not returned.", "instance": "request_01m40t5ag0e008000000000005", "code": "internal_error", "request_id": "request_01m40t5ag0e008000000000005" } } } }, "BadGateway": { "description": "A required upstream returned an invalid response.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Problem" }, { "properties": { "status": { "const": 502 } } } ] }, "example": { "type": "https://e.easycaptcha.to/bad_gateway", "title": "Bad gateway", "status": 502, "detail": "A required upstream returned an invalid response.", "instance": "request_01m40t5ag0e008000000000005", "code": "bad_gateway", "request_id": "request_01m40t5ag0e008000000000005" } } } }, "ServiceUnavailable": { "description": "A required dependency cannot currently serve the request.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Problem" }, { "properties": { "status": { "const": 503 } } } ] }, "example": { "type": "https://e.easycaptcha.to/service_unavailable", "title": "Service unavailable", "status": 503, "detail": "A required dependency cannot currently serve the request.", "instance": "request_01m40t5ag0e008000000000005", "code": "service_unavailable", "request_id": "request_01m40t5ag0e008000000000005" } } } }, "GatewayTimeout": { "description": "A required upstream did not respond within its request timeout.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Problem" }, { "properties": { "status": { "const": 504 } } } ] }, "example": { "type": "https://e.easycaptcha.to/gateway_timeout", "title": "Gateway timeout", "status": 504, "detail": "A required upstream did not respond within its request timeout.", "instance": "request_01m40t5ag0e008000000000005", "code": "gateway_timeout", "request_id": "request_01m40t5ag0e008000000000005" } } } }, "TaskNotFound": { "description": "The task is unknown, expired or not owned by the authenticated account.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestID" }, "Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/problem+json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Problem" }, { "properties": { "status": { "const": 404 } } } ] }, "example": { "type": "https://e.easycaptcha.to/task_not_found", "title": "Task not found", "status": 404, "detail": "The task is unknown, expired or not owned by the authenticated account.", "instance": "request_01m40t5ag0e008000000000005", "code": "task_not_found", "request_id": "request_01m40t5ag0e008000000000005" } } } } } } }