{ "openapi": "3.1.0", "info": { "title": "SurSolver API", "version": "1.0.0", "summary": "Captcha solving API", "description": "", "contact": { "name": "SurSolver", "email": "support@sursolver.com", "url": "https://sursolver.com" }, "termsOfService": "https://sursolver.com/terms" }, "servers": [ { "url": "https://api.sursolver.com", "description": "Production" } ], "tags": [ { "name": "Tasks", "description": "Captcha solve submission and retrieval." }, { "name": "Captchas", "description": "" }, { "name": "Catalog", "description": "Public billable-service price list (unauthenticated)." }, { "name": "Account", "description": "Profile, dashboard, usage, balance." }, { "name": "Deposits", "description": "Deposit addresses and status checks authenticated with your API key." } ], "x-scalar-navigation": { "type": "document", "id": "default", "name": "default", "title": "SurSolver API", "children": [ { "type": "tag", "id": "default/tag/tasks", "name": "Tasks", "title": "Tasks", "isGroup": false, "children": [ { "type": "operation", "id": "default/tag/tasks/POST/createTask", "title": "Create a task", "method": "post", "path": "/createTask", "ref": "#/paths/~1createTask/post", "children": [ { "type": "example", "id": "default/tag/tasks/POST/createTask/example/recaptcha_v2", "name": "recaptcha_v2", "title": "reCAPTCHA v2" }, { "type": "example", "id": "default/tag/tasks/POST/createTask/example/recaptcha_v2_enterprise", "name": "recaptcha_v2_enterprise", "title": "reCAPTCHA v2 Enterprise" }, { "type": "example", "id": "default/tag/tasks/POST/createTask/example/recaptcha_v3", "name": "recaptcha_v3", "title": "reCAPTCHA v3" }, { "type": "example", "id": "default/tag/tasks/POST/createTask/example/recaptcha_v3_enterprise", "name": "recaptcha_v3_enterprise", "title": "reCAPTCHA v3 Enterprise" }, { "type": "example", "id": "default/tag/tasks/POST/createTask/example/turnstile", "name": "turnstile", "title": "Cloudflare Turnstile" }, { "type": "example", "id": "default/tag/tasks/POST/createTask/example/cloudflare_challenge", "name": "cloudflare_challenge", "title": "Cloudflare Challenge" }, { "type": "example", "id": "default/tag/tasks/POST/createTask/example/vercel", "name": "vercel", "title": "Vercel" }, { "type": "example", "id": "default/tag/tasks/POST/createTask/example/friendlycaptcha", "name": "friendlycaptcha", "title": "FriendlyCaptcha" }, { "type": "example", "id": "default/tag/tasks/POST/createTask/example/altcha", "name": "altcha", "title": "Altcha" }, { "type": "example", "id": "default/tag/tasks/POST/createTask/example/prosopo", "name": "prosopo", "title": "Prosopo" }, { "type": "example", "id": "default/tag/tasks/POST/createTask/example/captchafox", "name": "captchafox", "title": "CaptchaFox" }, { "type": "example", "id": "default/tag/tasks/POST/createTask/example/geetest", "name": "geetest", "title": "GeeTest" }, { "type": "example", "id": "default/tag/tasks/POST/createTask/example/mtcaptcha", "name": "mtcaptcha", "title": "MTCaptcha" }, { "type": "example", "id": "default/tag/tasks/POST/createTask/example/akamai", "name": "akamai", "title": "Akamai" }, { "type": "example", "id": "default/tag/tasks/POST/createTask/example/datadome", "name": "datadome", "title": "DataDome" }, { "type": "example", "id": "default/tag/tasks/POST/createTask/example/px_invisible", "name": "px_invisible", "title": "PerimeterX" } ] }, { "type": "operation", "id": "default/tag/tasks/POST/getTaskResult", "title": "Get a task result", "method": "post", "path": "/getTaskResult", "ref": "#/paths/~1getTaskResult/post", "children": [ { "type": "example", "id": "default/tag/tasks/POST/getTaskResult/example/poll", "name": "poll", "title": "Poll a task" } ] } ] }, { "type": "tag", "id": "default/tag/captchas", "name": "Captchas", "title": "Captchas", "isGroup": false, "children": [ { "type": "operation", "id": "default/tag/captchas/POST/turnstile", "title": "Turnstile", "method": "post", "path": "/createTask", "ref": "#/components/pathItems/turnstile/post", "children": [ { "type": "example", "id": "default/tag/captchas/POST/turnstile/example/turnstile", "title": "Turnstile", "name": "turnstile" } ] }, { "type": "operation", "id": "default/tag/captchas/POST/recaptcha-v2", "title": "reCAPTCHA v2", "method": "post", "path": "/createTask", "ref": "#/components/pathItems/recaptcha_v2/post", "children": [ { "type": "example", "id": "default/tag/captchas/POST/recaptcha-v2/example/recaptcha_v2", "title": "reCAPTCHA v2", "name": "recaptcha_v2" } ] }, { "type": "operation", "id": "default/tag/captchas/POST/recaptcha-v3", "title": "reCAPTCHA v3", "method": "post", "path": "/createTask", "ref": "#/components/pathItems/recaptcha_v3/post", "children": [ { "type": "example", "id": "default/tag/captchas/POST/recaptcha-v3/example/recaptcha_v3", "title": "reCAPTCHA v3", "name": "recaptcha_v3" } ] } ] }, { "type": "tag", "id": "default/tag/catalog", "name": "Catalog", "title": "Catalog", "isGroup": false, "children": [ { "type": "operation", "id": "default/tag/catalog/GET/v1/services", "title": "Public service catalog", "method": "get", "path": "/v1/services", "ref": "#/paths/~1v1~1services/get", "children": [] }, { "type": "operation", "id": "default/tag/catalog/GET/v1/task-types", "title": "Accepted task types", "method": "get", "path": "/v1/task-types", "ref": "#/paths/~1v1~1task-types/get", "children": [] } ] }, { "type": "tag", "id": "default/tag/account", "name": "Account", "title": "Account", "isGroup": false, "children": [ { "type": "operation", "id": "default/tag/account/POST/getBalance", "title": "Get the balance", "method": "post", "path": "/getBalance", "ref": "#/paths/~1getBalance/post", "children": [ { "type": "example", "id": "default/tag/account/POST/getBalance/example/balance", "name": "balance", "title": "balance" } ] } ] }, { "type": "tag", "id": "default/tag/deposits", "name": "Deposits", "title": "Deposits", "isGroup": false, "children": [ { "type": "operation", "id": "default/tag/deposits/GET/v1/deposits/currencies", "title": "List deposit coins and networks", "method": "get", "path": "/v1/deposits/currencies", "ref": "#/paths/~1v1~1deposits~1currencies/get", "children": [] }, { "type": "operation", "id": "default/tag/deposits/POST/v1/deposits", "title": "Create a deposit", "method": "post", "path": "/v1/deposits", "ref": "#/paths/~1v1~1deposits/post", "children": [] }, { "type": "operation", "id": "default/tag/deposits/POST/v1/deposits/{id}/sync", "title": "Check a deposit", "method": "post", "path": "/v1/deposits/{id}/sync", "ref": "#/paths/~1v1~1deposits~1{id}~1sync/post", "children": [] } ] } ] }, "security": [], "paths": { "/v1/deposits/currencies": { "get": { "tags": [ "Deposits" ], "operationId": "depositCurrencies", "summary": "List deposit coins and networks", "description": "Select a coin and one of its networks. minimum_amount is the current minimum USD amount.", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Available coin/network pairs and USD minimum.", "content": { "application/json": { "schema": { "allOf": [ { "allOf": [ { "type": "object", "required": [ "success" ], "properties": { "success": { "type": "boolean", "const": true }, "data": { "description": "The response data." } } }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "coins" ], "properties": { "coins": { "type": "array", "items": { "type": "object", "required": [ "coin", "name", "networks" ], "properties": { "coin": { "type": "string" }, "name": { "type": "string" }, "networks": { "type": "array", "items": { "type": "object", "required": [ "network", "pay_currency" ], "properties": { "network": { "type": "string" }, "pay_currency": { "type": "string" } } } } } } } } } } } ] }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "minimum_amount" ], "properties": { "minimum_amount": { "type": "string", "pattern": "^-?\\d+(\\.\\d{1,6})?$", "description": "Price in US dollars, as a decimal string.", "examples": [ "0.001" ] } } } } } ] } } } }, "401": { "description": "Invalid API key." }, "502": { "description": "Currency catalog unavailable." } } } }, "/v1/deposits": { "post": { "tags": [ "Deposits" ], "operationId": "createDeposit", "summary": "Create a deposit", "description": "Send coin, network and a USD amount string. Transfer pay_amount to pay_address on the selected network; include payin_extra_id when present. Creating an address does not credit your balance.", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "amount", "coin", "network" ], "properties": { "amount": { "allOf": [ { "type": "string", "pattern": "^-?\\d+(\\.\\d{1,6})?$", "description": "Price in US dollars, as a decimal string.", "examples": [ "0.001" ] } ], "description": "Positive USD decimal string. See the current minimum in GET /v1/deposits/currencies." }, "coin": { "type": "string", "description": "Coin ticker, case-insensitive, e.g. USDT or btc." }, "network": { "type": "string", "description": "Network label, case-insensitive, e.g. TRC20; aliases TRX/ERC20-ETH/BSC-BEP20 accepted." } } }, "example": { "coin": "USDT", "network": "TRC20", "amount": "25.00" } } } }, "responses": { "201": { "description": "Deposit address and amount.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "required": [ "success" ], "properties": { "success": { "type": "boolean", "const": true }, "data": { "description": "The response data." } } }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "id", "order_id", "status", "price_amount", "price_currency", "coin", "network", "pay_currency", "pay_address", "pay_amount", "provider_payment_id", "expires_at", "payin_extra_id" ], "properties": { "id": { "type": "integer" }, "order_id": { "type": "string" }, "provider": { "type": "string" }, "provider_payment_id": { "type": "integer" }, "status": { "type": "string" }, "price_amount": { "type": "string", "pattern": "^-?\\d+(\\.\\d{1,6})?$", "description": "Price in US dollars, as a decimal string.", "examples": [ "0.001" ] }, "price_currency": { "type": "string" }, "coin": { "type": "string", "description": "Canonical coin label the pair resolved to." }, "network": { "type": "string", "description": "Canonical network label the pair resolved to." }, "pay_currency": { "type": "string" }, "pay_address": { "type": "string" }, "payin_extra_id": { "type": [ "string", "null" ], "maxLength": 256, "description": "Required deposit memo or destination tag supplied by the provider; preserve leading zeros." }, "pay_amount": { "type": "string" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "End of the pending window; this does not invalidate the payment address." }, "created_at": { "type": "string", "format": "date-time" } } } } } ] } } } }, "400": { "description": "Invalid amount or coin/network pair." }, "401": { "description": "Invalid API key." }, "429": { "description": "Too many deposit requests." }, "502": { "description": "Payment provider unavailable." }, "503": { "description": "Deposits or throttling unavailable." } } } }, "/v1/deposits/{id}/sync": { "post": { "tags": [ "Deposits" ], "operationId": "syncDeposit", "summary": "Check a deposit", "description": "Refresh a deposit owned by your account. Poll no faster than every 10 seconds. credited is true only when this call added credit; credited_at indicates credit already applied. Finished payments credit the account once. Missing and foreign ids both return 404.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Deposit status and credit state.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "required": [ "success" ], "properties": { "success": { "type": "boolean", "const": true }, "data": { "description": "The response data." } } }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "id", "status", "credited" ], "properties": { "id": { "type": "integer" }, "order_id": { "type": "string" }, "status": { "type": "string" }, "ipn_status": { "type": "string" }, "credited": { "type": "boolean" }, "credited_at": { "type": [ "string", "null" ], "format": "date-time" }, "balance_after": { "type": [ "string", "null" ], "description": "Wallet balance only when this call credited." } } } } } ] } } } }, "400": { "description": "Invalid deposit id." }, "401": { "description": "Invalid API key." }, "404": { "description": "Deposit not found." }, "502": { "description": "Status provider unavailable." } } } }, "/v1/services": { "get": { "tags": [ "Catalog" ], "operationId": "listServices", "summary": "Public service catalog", "description": "Active services and prices in USD.", "security": [], "responses": { "200": { "description": "Catalog.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "required": [ "success" ], "properties": { "success": { "type": "boolean", "const": true }, "data": { "description": "The response data." } } }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "services" ], "properties": { "services": { "type": "array", "items": { "type": "object", "required": [ "id", "slug", "display_name", "price_per_request", "status", "avg_latency_ms" ], "properties": { "id": { "type": "integer" }, "slug": { "type": "string" }, "display_name": { "type": "string" }, "price_per_request": { "type": "string", "pattern": "^-?\\d+(\\.\\d{1,6})?$", "description": "Price in US dollars, as a decimal string.", "examples": [ "0.001" ] }, "status": { "type": "string", "enum": [ "active", "maintenance", "inactive" ] }, "avg_latency_ms": { "type": [ "integer", "null" ], "description": "Mean solve latency (ms) over the trailing 30 days; null without telemetry." } } } } } } } } ] } } } } } } }, "/v1/task-types": { "get": { "tags": [ "Catalog" ], "operationId": "listTaskTypes", "summary": "Accepted task types", "description": "Accepted task types, input fields, solution fields and error codes.", "security": [], "responses": { "200": { "description": "Task types.", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "required": [ "success" ], "properties": { "success": { "type": "boolean", "const": true }, "data": { "description": "The response data." } } }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "task_types", "error_codes" ], "properties": { "task_types": { "type": "array", "items": { "type": "object", "required": [ "display_name", "task_type", "task_type_proxyless", "aliases", "proxy", "required", "any_of", "optional", "solution_keys" ], "description": "One accepted `task.type`. Fields not listed here are not part of the contract.", "properties": { "display_name": { "type": "string", "examples": [ "reCAPTCHA v2" ] }, "page_slug": { "type": [ "string", "null" ], "description": "Slug of the guide at /solvers/ for this type, when it has one." }, "task_type": { "type": "string", "description": "Canonical `task.type` (the proxy-capable name when the type has a proxyless sibling).", "examples": [ "ReCaptchaV2Task" ] }, "task_type_proxyless": { "type": [ "string", "null" ], "description": "Proxyless sibling name; null when the type has none.", "examples": [ "ReCaptchaV2TaskProxyLess" ] }, "aliases": { "type": "array", "description": "Other accepted spellings of `task.type`.", "items": { "type": "string" } }, "proxy": { "type": "string", "enum": [ "none", "optional", "required" ], "description": "Whether the type takes a proxy." }, "required": { "type": "array", "description": "Required task fields; each inner array lists the accepted spellings of one field (the first is canonical).", "items": { "type": "array", "items": { "type": "string" } } }, "any_of": { "type": "array", "description": "Alternative groups of which at least one must be supplied.", "items": { "type": "array", "items": { "type": "string" } } }, "optional": { "type": "array", "description": "Optional task fields.", "items": { "type": "string" } }, "solution_keys": { "type": "array", "description": "Keys the `solution` object can contain; a given result carries the ones the solver produced.", "items": { "type": "string" } } } } }, "error_codes": { "type": "array", "description": "Every `errorCode` the task endpoints can return.", "items": { "type": "string" } } } } } } ] } } } } } } }, "/createTask": { "post": { "tags": [ "Tasks" ], "operationId": "createTask", "summary": "Create a task", "description": "Returns a `taskId`. Use it with `getTaskResult`. Each submission creates a new charged task.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "clientKey", "task" ], "properties": { "clientKey": { "type": "string", "description": "Your API key (`ssk_live_…`), created in the dashboard." }, "task": { "type": "object", "required": [ "type" ], "additionalProperties": true, "description": "Task parameters for the selected `type`.", "properties": { "type": { "type": "string", "description": "Captcha type, for example `ReCaptchaV2TaskProxyLess`. See `GET /v1/task-types`.", "examples": [ "ReCaptchaV2TaskProxyLess", "AntiTurnstileTaskProxyLess", "AntiCloudflareTask" ] }, "websiteURL": { "type": "string", "description": "Full URL of the page showing the captcha." }, "websiteKey": { "type": "string", "description": "Site key of the widget on that page." }, "pageAction": { "type": "string", "description": "reCAPTCHA v3 `action` value, when set." }, "proxy": { "type": "string", "description": "Proxy URL (`http://user:password@host:port`) or `user:password:host:port`. Alternatively use the split proxy fields." }, "proxyType": { "type": "string", "enum": [ "http", "https", "socks4", "socks5" ], "default": "http", "description": "Protocol for the split proxy fields." }, "proxyAddress": { "type": "string", "description": "Proxy hostname or IP address." }, "proxyPort": { "oneOf": [ { "type": "integer" }, { "type": "string", "pattern": "^[0-9]+$" } ], "description": "Proxy port.", "examples": [ 8080, "8080" ] }, "proxyLogin": { "type": "string", "description": "Proxy username, if authentication is required." }, "proxyPassword": { "type": "string", "format": "password", "description": "Proxy password, if authentication is required." } } }, "appId": { "type": "string", "description": "Optional referral app ID (`app_…`)." } } }, "examples": { "recaptcha_v2": { "summary": "reCAPTCHA v2", "value": { "clientKey": "ssk_live_…", "task": { "type": "ReCaptchaV2TaskProxyLess", "websiteURL": "https://example.com/login", "websiteKey": "6Le..." } } }, "recaptcha_v2_enterprise": { "summary": "reCAPTCHA v2 Enterprise", "value": { "clientKey": "ssk_live_…", "task": { "type": "ReCaptchaV2EnterpriseTaskProxyLess", "websiteURL": "https://example.com/login", "websiteKey": "6Le..." } } }, "recaptcha_v3": { "summary": "reCAPTCHA v3", "value": { "clientKey": "ssk_live_…", "task": { "type": "ReCaptchaV3TaskProxyLess", "websiteURL": "https://example.com/login", "websiteKey": "6Le..." } } }, "recaptcha_v3_enterprise": { "summary": "reCAPTCHA v3 Enterprise", "value": { "clientKey": "ssk_live_…", "task": { "type": "ReCaptchaV3EnterpriseTaskProxyLess", "websiteURL": "https://example.com/login", "websiteKey": "6Le..." } } }, "turnstile": { "summary": "Cloudflare Turnstile", "value": { "clientKey": "ssk_live_…", "task": { "type": "TurnstileTokenProxyLess", "websiteURL": "https://example.com/login", "websiteKey": "0x4AAAA..." } } }, "cloudflare_challenge": { "summary": "Cloudflare Challenge", "value": { "clientKey": "ssk_live_…", "task": { "type": "AntiCloudflareTask", "websiteURL": "https://example.com/login", "proxyType": "http", "proxyAddress": "proxy.example.com", "proxyPort": 8080, "proxyLogin": "YOUR_PROXY_LOGIN", "proxyPassword": "YOUR_PROXY_PASSWORD" } } }, "vercel": { "summary": "Vercel", "value": { "clientKey": "ssk_live_…", "task": { "type": "VercelToken", "websiteURL": "https://example.com/login", "proxyType": "http", "proxyAddress": "proxy.example.com", "proxyPort": 8080, "proxyLogin": "YOUR_PROXY_LOGIN", "proxyPassword": "YOUR_PROXY_PASSWORD" } } }, "friendlycaptcha": { "summary": "FriendlyCaptcha", "value": { "clientKey": "ssk_live_…", "task": { "type": "FriendlyCaptchaTaskProxyless", "websiteURL": "https://example.com/login", "websiteKey": "FC..." } } }, "altcha": { "summary": "Altcha", "value": { "clientKey": "ssk_live_…", "task": { "type": "AltchaTaskProxyless", "websiteURL": "https://example.com/login", "challengeURL": "https://example.com/challenge" } } }, "prosopo": { "summary": "Prosopo", "value": { "clientKey": "ssk_live_…", "task": { "type": "ProsopoTaskProxyless", "websiteURL": "https://example.com/login", "websiteKey": "YOUR_SITE_KEY" } } }, "captchafox": { "summary": "CaptchaFox", "value": { "clientKey": "ssk_live_…", "task": { "type": "CaptchaFoxTask", "websiteURL": "https://example.com/login", "websiteKey": "YOUR_SITE_KEY", "proxyType": "http", "proxyAddress": "proxy.example.com", "proxyPort": 8080, "proxyLogin": "YOUR_PROXY_LOGIN", "proxyPassword": "YOUR_PROXY_PASSWORD" } } }, "geetest": { "summary": "GeeTest", "value": { "clientKey": "ssk_live_…", "task": { "type": "GeeTestTaskProxyLess", "websiteURL": "https://example.com/login", "gt": "YOUR_GT", "challenge": "YOUR_CHALLENGE" } } }, "mtcaptcha": { "summary": "MTCaptcha", "value": { "clientKey": "ssk_live_…", "task": { "type": "MtCaptchaTaskProxyLess", "websiteURL": "https://example.com/login", "websiteKey": "MTPublic-..." } } }, "akamai": { "summary": "Akamai", "value": { "clientKey": "ssk_live_…", "task": { "type": "AkamaiCookie", "websiteURL": "https://example.com/login", "proxyType": "http", "proxyAddress": "proxy.example.com", "proxyPort": 8080, "proxyLogin": "YOUR_PROXY_LOGIN", "proxyPassword": "YOUR_PROXY_PASSWORD" } } }, "datadome": { "summary": "DataDome", "value": { "clientKey": "ssk_live_…", "task": { "type": "DatadomeSliderTask", "websiteURL": "https://example.com/login", "captchaUrl": "https://example.com/captcha", "proxyType": "http", "proxyAddress": "proxy.example.com", "proxyPort": 8080, "proxyLogin": "YOUR_PROXY_LOGIN", "proxyPassword": "YOUR_PROXY_PASSWORD" } } }, "px_invisible": { "summary": "PerimeterX", "value": { "clientKey": "ssk_live_…", "task": { "type": "AntiPerimeterXTask", "websiteURL": "https://example.com/login", "pxAppId": "YOUR_PX_APP_ID", "proxyType": "http", "proxyAddress": "proxy.example.com", "proxyPort": 8080, "proxyLogin": "YOUR_PROXY_LOGIN", "proxyPassword": "YOUR_PROXY_PASSWORD" } } } } } } }, "responses": { "200": { "description": "Task accepted (`errorId: 0`, `status: \"idle\"`) or an error (`errorId: 1`).", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "errorId", "taskId", "status" ], "properties": { "errorId": { "type": "integer", "const": 0 }, "taskId": { "type": "string", "pattern": "^tsk_[0-9a-f]{24}$", "description": "Task id: `tsk_` followed by 24 hex characters.", "examples": [ "tsk_9c1f4e2a7b0d5e6f7a8b9c0d" ] }, "status": { "type": "string", "const": "idle", "description": "Queued — poll getTaskResult next." } } }, { "type": "object", "required": [ "errorId", "errorCode", "errorDescription" ], "properties": { "errorId": { "type": "integer", "const": 1 }, "errorCode": { "type": "string", "description": "ERROR_KEY_DOES_NOT_EXIST · ERROR_WRONG_CLIENT_KEY · ERROR_ZERO_BALANCE · ERROR_NO_SLOT_AVAILABLE · ERROR_TYPE_NOT_SUPPORTED · ERROR_TASK_NOT_FOUND · ERROR_TASK_EXPIRED · ERROR_TASK_TIMEOUT · ERROR_FAILED · ERROR_INVALID_REQUEST · ERROR_INTERNAL_ERROR", "examples": [ "ERROR_KEY_DOES_NOT_EXIST" ] }, "errorDescription": { "type": "string" } } } ] } } } } } } }, "/getTaskResult": { "post": { "tags": [ "Tasks" ], "operationId": "getTaskResult", "summary": "Get a task result", "description": "Poll every 3 seconds until `status` is `ready`. The result is in `solution`. Execution timeout returns `ERROR_TASK_TIMEOUT`; results expire after 30 minutes. See [Task lifecycle](/docs/guides/task-lifecycle).", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "clientKey", "taskId" ], "properties": { "clientKey": { "type": "string", "description": "Raw API key, same credential as createTask." }, "taskId": { "type": "string", "description": "The `taskId` returned by `POST /createTask`: `tsk_` followed by 24 hex characters.", "examples": [ "tsk_9c1f4e2a7b0d5e6f7a8b9c0d" ] } } }, "examples": { "poll": { "summary": "Poll a task", "value": { "clientKey": "ssk_live_…", "taskId": "tsk_9c1f4e2a7b0d5e6f7a8b9c0d" } } } } } }, "responses": { "200": { "description": "Still processing, ready with a `solution`, or an error (`errorId: 1`).", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "errorId", "status" ], "properties": { "errorId": { "type": "integer", "const": 0 }, "status": { "type": "string", "const": "processing" } } }, { "type": "object", "required": [ "errorId", "status", "solution" ], "properties": { "errorId": { "type": "integer", "const": 0 }, "status": { "type": "string", "const": "ready" }, "solution": { "description": "Per-type `solution` object; one branch per distinct set of solution keys. A key is required only when every type with that set always returns it, and `userAgent` is present only when the solver reports one.", "anyOf": [ { "type": "object", "required": [ "gRecaptchaResponse" ], "description": "reCAPTCHA v2 / v3, including the Enterprise variants.", "properties": { "gRecaptchaResponse": { "type": "string", "description": "Value for `g-recaptcha-response`." }, "userAgent": { "type": "string", "description": "Present only when the solver reports one; send it with the consuming request." } } }, { "type": "object", "required": [ "token" ], "description": "Token types without cookies: Cloudflare Turnstile, FriendlyCaptcha, Prosopo, CaptchaFox and MTCaptcha.", "properties": { "token": { "type": "string", "description": "The token to place in the page (e.g. `cf-turnstile-response` for Turnstile)." }, "userAgent": { "type": "string", "description": "Present only when the solver reports one; send it with the consuming request." } } }, { "type": "object", "required": [ "cookies" ], "description": "Cookie-producing token types: Cloudflare Challenge, Vercel, DataDome, PerimeterX. `cookies` is the output; `token` appears when the solver reports one.", "properties": { "token": { "type": "string", "description": "Present only when the solver reports one." }, "cookies": { "type": "array", "description": "Cookies to replay with the same user agent and exit IP.", "items": { "type": "object", "properties": { "name": { "type": "string" }, "value": { "type": "string" }, "domain": { "type": "string" }, "path": { "type": "string" } } } }, "userAgent": { "type": "string", "description": "Present only when the solver reports one; send it with the consuming request." } } }, { "type": "object", "required": [ "token" ], "description": "Altcha.", "properties": { "token": { "type": "string", "description": "The token to place in the page." } } }, { "type": "object", "required": [], "description": "GeeTest: v3 answers `challenge` / `validate` / `seccode`; v4 answers `lot_number`, `pass_token`, `gen_time` and `captcha_output`; no key is present in both shapes.", "properties": { "challenge": { "type": "string", "description": "GeeTest v3 challenge." }, "validate": { "type": "string", "description": "GeeTest v3 validate." }, "seccode": { "type": "string", "description": "GeeTest v3 seccode." }, "captcha_id": { "type": "string", "description": "GeeTest v4 captcha id." }, "lot_number": { "type": "string", "description": "GeeTest v4 lot number." }, "pass_token": { "type": "string", "description": "GeeTest v4 pass token." }, "gen_time": { "type": "string", "description": "GeeTest v4 generation time." }, "captcha_output": { "type": "string", "description": "GeeTest v4 captcha output." } } }, { "type": "object", "required": [ "cookies" ], "description": "Akamai (managed cookie): the cookie jar is the output.", "properties": { "cookies": { "type": "array", "description": "Cookies to replay with the same user agent and exit IP.", "items": { "type": "object", "properties": { "name": { "type": "string" }, "value": { "type": "string" }, "domain": { "type": "string" }, "path": { "type": "string" } } } }, "userAgent": { "type": "string", "description": "Present only when the solver reports one; send it with the consuming request." } } } ] } } }, { "type": "object", "required": [ "errorId", "errorCode", "errorDescription" ], "properties": { "errorId": { "type": "integer", "const": 1 }, "errorCode": { "type": "string", "description": "ERROR_KEY_DOES_NOT_EXIST · ERROR_WRONG_CLIENT_KEY · ERROR_ZERO_BALANCE · ERROR_NO_SLOT_AVAILABLE · ERROR_TYPE_NOT_SUPPORTED · ERROR_TASK_NOT_FOUND · ERROR_TASK_EXPIRED · ERROR_TASK_TIMEOUT · ERROR_FAILED · ERROR_INVALID_REQUEST · ERROR_INTERNAL_ERROR", "examples": [ "ERROR_KEY_DOES_NOT_EXIST" ] }, "errorDescription": { "type": "string" } } } ] }, "examples": { "recaptcha_v2": { "summary": "reCAPTCHA v2 (ready)", "value": { "errorId": 0, "status": "ready", "solution": { "gRecaptchaResponse": "", "userAgent": "" } } }, "recaptcha_v2_enterprise": { "summary": "reCAPTCHA v2 Enterprise (ready)", "value": { "errorId": 0, "status": "ready", "solution": { "gRecaptchaResponse": "", "userAgent": "" } } }, "recaptcha_v3": { "summary": "reCAPTCHA v3 (ready)", "value": { "errorId": 0, "status": "ready", "solution": { "gRecaptchaResponse": "", "userAgent": "" } } }, "recaptcha_v3_enterprise": { "summary": "reCAPTCHA v3 Enterprise (ready)", "value": { "errorId": 0, "status": "ready", "solution": { "gRecaptchaResponse": "", "userAgent": "" } } }, "turnstile": { "summary": "Cloudflare Turnstile (ready)", "value": { "errorId": 0, "status": "ready", "solution": { "token": "", "userAgent": "" } } }, "cloudflare_challenge": { "summary": "Cloudflare Challenge (ready)", "value": { "errorId": 0, "status": "ready", "solution": { "token": "", "cookies": "", "userAgent": "" } } }, "vercel": { "summary": "Vercel (ready)", "value": { "errorId": 0, "status": "ready", "solution": { "token": "", "cookies": "", "userAgent": "" } } }, "friendlycaptcha": { "summary": "FriendlyCaptcha (ready)", "value": { "errorId": 0, "status": "ready", "solution": { "token": "", "userAgent": "" } } }, "altcha": { "summary": "Altcha (ready)", "value": { "errorId": 0, "status": "ready", "solution": { "token": "" } } }, "prosopo": { "summary": "Prosopo (ready)", "value": { "errorId": 0, "status": "ready", "solution": { "token": "", "userAgent": "" } } }, "captchafox": { "summary": "CaptchaFox (ready)", "value": { "errorId": 0, "status": "ready", "solution": { "token": "", "userAgent": "" } } }, "geetest": { "summary": "GeeTest (ready)", "value": { "errorId": 0, "status": "ready", "solution": { "challenge": "", "validate": "", "seccode": "", "captcha_id": "", "lot_number": "", "pass_token": "", "gen_time": "", "captcha_output": "" } } }, "mtcaptcha": { "summary": "MTCaptcha (ready)", "value": { "errorId": 0, "status": "ready", "solution": { "token": "", "userAgent": "" } } }, "akamai": { "summary": "Akamai (ready)", "value": { "errorId": 0, "status": "ready", "solution": { "cookies": "", "userAgent": "" } } }, "datadome": { "summary": "DataDome (ready)", "value": { "errorId": 0, "status": "ready", "solution": { "token": "", "cookies": "", "userAgent": "" } } }, "px_invisible": { "summary": "PerimeterX (ready)", "value": { "errorId": 0, "status": "ready", "solution": { "token": "", "cookies": "", "userAgent": "" } } }, "processing": { "summary": "Still processing", "value": { "errorId": 0, "status": "processing" } } } } } } } } }, "/getBalance": { "post": { "tags": [ "Account" ], "operationId": "getBalance", "summary": "Get the balance", "description": "Returns the account cash balance in USD. Package quota is shown in the dashboard.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "clientKey" ], "properties": { "clientKey": { "type": "string", "description": "Your API key." } } }, "examples": { "balance": { "value": { "clientKey": "ssk_live_…" } } } } } }, "responses": { "200": { "description": "`{\"errorId\": 0, \"balance\": 9.987}` or an error (`errorId: 1`).", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "errorId", "balance" ], "properties": { "errorId": { "type": "integer", "const": 0 }, "balance": { "type": "number", "description": "Cash balance of the key's owner, in USD.", "examples": [ 9.987 ] } } }, { "type": "object", "required": [ "errorId", "errorCode", "errorDescription" ], "properties": { "errorId": { "type": "integer", "const": 1 }, "errorCode": { "type": "string", "description": "ERROR_KEY_DOES_NOT_EXIST · ERROR_WRONG_CLIENT_KEY · ERROR_ZERO_BALANCE · ERROR_NO_SLOT_AVAILABLE · ERROR_TYPE_NOT_SUPPORTED · ERROR_TASK_NOT_FOUND · ERROR_TASK_EXPIRED · ERROR_TASK_TIMEOUT · ERROR_FAILED · ERROR_INVALID_REQUEST · ERROR_INTERNAL_ERROR", "examples": [ "ERROR_KEY_DOES_NOT_EXIST" ] }, "errorDescription": { "type": "string" } } } ] } } } } } } } }, "components": { "pathItems": { "turnstile": { "post": { "tags": [ "Captchas" ], "operationId": "createTask_turnstile", "summary": "Turnstile", "description": "Submit a task and collect its result with getTaskResult.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "clientKey", "task" ], "properties": { "clientKey": { "type": "string", "description": "Your API key (`ssk_live_…`), created in the dashboard." }, "task": { "type": "object", "required": [ "type", "websiteURL", "websiteKey" ], "additionalProperties": true, "description": "Task parameters for the selected `type`.", "properties": { "type": { "type": "string", "description": "Task type for Turnstile.", "examples": [ "ReCaptchaV2TaskProxyLess", "AntiTurnstileTaskProxyLess", "AntiCloudflareTask" ], "enum": [ "TurnstileToken", "TurnstileTokenProxyLess", "TurnstileTask", "TurnstileTaskProxyless", "AntiTurnstileTaskProxyLess" ] }, "proxy": { "type": "string", "description": "Proxy URL (`http://user:password@host:port`) or `user:password:host:port`. Alternatively use the split proxy fields." }, "proxyType": { "type": "string", "enum": [ "http", "https", "socks4", "socks5" ], "default": "http", "description": "Protocol for the split proxy fields." }, "proxyAddress": { "type": "string", "description": "Proxy hostname or IP address." }, "proxyPort": { "oneOf": [ { "type": "integer" }, { "type": "string", "pattern": "^[0-9]+$" } ], "description": "Proxy port.", "examples": [ 8080, "8080" ] }, "proxyLogin": { "type": "string", "description": "Proxy username, if authentication is required." }, "proxyPassword": { "type": "string", "format": "password", "description": "Proxy password, if authentication is required." }, "websiteURL": { "type": "string", "description": "Full URL of the page showing the captcha." }, "websiteKey": { "type": "string", "description": "Site key of the widget on that page." }, "action": {}, "cData": {}, "chlPageData": {}, "userAgent": {} } }, "appId": { "type": "string", "description": "Optional referral app ID (`app_…`)." } } }, "examples": { "turnstile": { "summary": "Turnstile", "value": { "clientKey": "ssk_live_…", "task": { "type": "TurnstileTokenProxyLess", "websiteURL": "https://example.com/login", "websiteKey": "0x4AAAA..." } } } } } } }, "responses": { "200": { "description": "Task accepted (`errorId: 0`, `status: \"idle\"`) or an error (`errorId: 1`).", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "errorId", "taskId", "status" ], "properties": { "errorId": { "type": "integer", "const": 0 }, "taskId": { "type": "string", "pattern": "^tsk_[0-9a-f]{24}$", "description": "Task id: `tsk_` followed by 24 hex characters.", "examples": [ "tsk_9c1f4e2a7b0d5e6f7a8b9c0d" ] }, "status": { "type": "string", "const": "idle", "description": "Queued — poll getTaskResult next." } } }, { "type": "object", "required": [ "errorId", "errorCode", "errorDescription" ], "properties": { "errorId": { "type": "integer", "const": 1 }, "errorCode": { "type": "string", "description": "ERROR_KEY_DOES_NOT_EXIST · ERROR_WRONG_CLIENT_KEY · ERROR_ZERO_BALANCE · ERROR_NO_SLOT_AVAILABLE · ERROR_TYPE_NOT_SUPPORTED · ERROR_TASK_NOT_FOUND · ERROR_TASK_EXPIRED · ERROR_TASK_TIMEOUT · ERROR_FAILED · ERROR_INVALID_REQUEST · ERROR_INTERNAL_ERROR", "examples": [ "ERROR_KEY_DOES_NOT_EXIST" ] }, "errorDescription": { "type": "string" } } } ] } } } } } } }, "recaptcha_v2": { "post": { "tags": [ "Captchas" ], "operationId": "createTask_recaptcha_v2", "summary": "reCAPTCHA v2", "description": "Submit a task and collect its result with getTaskResult.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "clientKey", "task" ], "properties": { "clientKey": { "type": "string", "description": "Your API key (`ssk_live_…`), created in the dashboard." }, "task": { "type": "object", "required": [ "type", "websiteURL", "websiteKey" ], "additionalProperties": true, "description": "Task parameters for the selected `type`.", "properties": { "type": { "type": "string", "description": "Task type for reCAPTCHA v2.", "examples": [ "ReCaptchaV2TaskProxyLess", "AntiTurnstileTaskProxyLess", "AntiCloudflareTask" ], "enum": [ "ReCaptchaV2Task", "ReCaptchaV2TaskProxyLess", "ReCaptchaV2", "ReCaptchaV2Token" ] }, "proxy": { "type": "string", "description": "Proxy URL (`http://user:password@host:port`) or `user:password:host:port`. Alternatively use the split proxy fields." }, "proxyType": { "type": "string", "enum": [ "http", "https", "socks4", "socks5" ], "default": "http", "description": "Protocol for the split proxy fields." }, "proxyAddress": { "type": "string", "description": "Proxy hostname or IP address." }, "proxyPort": { "oneOf": [ { "type": "integer" }, { "type": "string", "pattern": "^[0-9]+$" } ], "description": "Proxy port.", "examples": [ 8080, "8080" ] }, "proxyLogin": { "type": "string", "description": "Proxy username, if authentication is required." }, "proxyPassword": { "type": "string", "format": "password", "description": "Proxy password, if authentication is required." }, "websiteURL": { "type": "string", "description": "Full URL of the page showing the captcha." }, "websiteKey": { "type": "string", "description": "Site key of the widget on that page." }, "isInvisible": {}, "recaptchaDataSValue": {}, "apiDomain": {}, "userAgent": {}, "cookies": {} } }, "appId": { "type": "string", "description": "Optional referral app ID (`app_…`)." } } }, "examples": { "recaptcha_v2": { "summary": "reCAPTCHA v2", "value": { "clientKey": "ssk_live_…", "task": { "type": "ReCaptchaV2TaskProxyLess", "websiteURL": "https://example.com/login", "websiteKey": "6Le..." } } } } } } }, "responses": { "200": { "description": "Task accepted (`errorId: 0`, `status: \"idle\"`) or an error (`errorId: 1`).", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "errorId", "taskId", "status" ], "properties": { "errorId": { "type": "integer", "const": 0 }, "taskId": { "type": "string", "pattern": "^tsk_[0-9a-f]{24}$", "description": "Task id: `tsk_` followed by 24 hex characters.", "examples": [ "tsk_9c1f4e2a7b0d5e6f7a8b9c0d" ] }, "status": { "type": "string", "const": "idle", "description": "Queued — poll getTaskResult next." } } }, { "type": "object", "required": [ "errorId", "errorCode", "errorDescription" ], "properties": { "errorId": { "type": "integer", "const": 1 }, "errorCode": { "type": "string", "description": "ERROR_KEY_DOES_NOT_EXIST · ERROR_WRONG_CLIENT_KEY · ERROR_ZERO_BALANCE · ERROR_NO_SLOT_AVAILABLE · ERROR_TYPE_NOT_SUPPORTED · ERROR_TASK_NOT_FOUND · ERROR_TASK_EXPIRED · ERROR_TASK_TIMEOUT · ERROR_FAILED · ERROR_INVALID_REQUEST · ERROR_INTERNAL_ERROR", "examples": [ "ERROR_KEY_DOES_NOT_EXIST" ] }, "errorDescription": { "type": "string" } } } ] } } } } } } }, "recaptcha_v3": { "post": { "tags": [ "Captchas" ], "operationId": "createTask_recaptcha_v3", "summary": "reCAPTCHA v3", "description": "Submit a task and collect its result with getTaskResult.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "clientKey", "task" ], "properties": { "clientKey": { "type": "string", "description": "Your API key (`ssk_live_…`), created in the dashboard." }, "task": { "type": "object", "required": [ "type", "websiteURL", "websiteKey" ], "additionalProperties": true, "description": "Task parameters for the selected `type`.", "properties": { "type": { "type": "string", "description": "Task type for reCAPTCHA v3.", "examples": [ "ReCaptchaV2TaskProxyLess", "AntiTurnstileTaskProxyLess", "AntiCloudflareTask" ], "enum": [ "ReCaptchaV3Task", "ReCaptchaV3TaskProxyLess", "ReCaptchaV3", "ReCaptchaV3Token" ] }, "proxy": { "type": "string", "description": "Proxy URL (`http://user:password@host:port`) or `user:password:host:port`. Alternatively use the split proxy fields." }, "proxyType": { "type": "string", "enum": [ "http", "https", "socks4", "socks5" ], "default": "http", "description": "Protocol for the split proxy fields." }, "proxyAddress": { "type": "string", "description": "Proxy hostname or IP address." }, "proxyPort": { "oneOf": [ { "type": "integer" }, { "type": "string", "pattern": "^[0-9]+$" } ], "description": "Proxy port.", "examples": [ 8080, "8080" ] }, "proxyLogin": { "type": "string", "description": "Proxy username, if authentication is required." }, "proxyPassword": { "type": "string", "format": "password", "description": "Proxy password, if authentication is required." }, "websiteURL": { "type": "string", "description": "Full URL of the page showing the captcha." }, "websiteKey": { "type": "string", "description": "Site key of the widget on that page." }, "pageAction": { "type": "string", "description": "reCAPTCHA v3 `action` value, when set." }, "minScore": {}, "apiDomain": {}, "userAgent": {}, "cookies": {} } }, "appId": { "type": "string", "description": "Optional referral app ID (`app_…`)." } } }, "examples": { "recaptcha_v3": { "summary": "reCAPTCHA v3", "value": { "clientKey": "ssk_live_…", "task": { "type": "ReCaptchaV3TaskProxyLess", "websiteURL": "https://example.com/login", "websiteKey": "6Le..." } } } } } } }, "responses": { "200": { "description": "Task accepted (`errorId: 0`, `status: \"idle\"`) or an error (`errorId: 1`).", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "errorId", "taskId", "status" ], "properties": { "errorId": { "type": "integer", "const": 0 }, "taskId": { "type": "string", "pattern": "^tsk_[0-9a-f]{24}$", "description": "Task id: `tsk_` followed by 24 hex characters.", "examples": [ "tsk_9c1f4e2a7b0d5e6f7a8b9c0d" ] }, "status": { "type": "string", "const": "idle", "description": "Queued — poll getTaskResult next." } } }, { "type": "object", "required": [ "errorId", "errorCode", "errorDescription" ], "properties": { "errorId": { "type": "integer", "const": 1 }, "errorCode": { "type": "string", "description": "ERROR_KEY_DOES_NOT_EXIST · ERROR_WRONG_CLIENT_KEY · ERROR_ZERO_BALANCE · ERROR_NO_SLOT_AVAILABLE · ERROR_TYPE_NOT_SUPPORTED · ERROR_TASK_NOT_FOUND · ERROR_TASK_EXPIRED · ERROR_TASK_TIMEOUT · ERROR_FAILED · ERROR_INVALID_REQUEST · ERROR_INTERNAL_ERROR", "examples": [ "ERROR_KEY_DOES_NOT_EXIST" ] }, "errorDescription": { "type": "string" } } } ] } } } } } } } }, "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Your API key (`ssk_live_…`)." } } } }