API Overview

The uCaptcha API provides a unified interface for submitting CAPTCHA solving tasks across multiple providers. This page covers the fundamentals you need before making your first request.

Base URL

All API requests are made to:

https://api.ucaptcha.net

Request Format

All requests use the POST method with a JSON body. Set the Content-Type header to application/json.

curl -X POST https://api.ucaptcha.net/createTask \
  -H "Content-Type: application/json" \
  -d '{"clientKey": "YOUR_API_KEY", "task": { ... }}'

Authentication

Authentication is handled via the clientKey field in the JSON request body — not through HTTP headers. Include your API key in every request.

{
  "clientKey": "YOUR_API_KEY",
  ...
}

You can generate and manage API keys from your dashboard or the Telegram Mini App.

Response Format

All responses return JSON. Every response includes an errorId field:

• 0 — the request succeeded
• 1 — an error occurred

Success Response

{
  "errorId": 0,
  "taskId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing"
}

When a task is complete:

{
  "errorId": 0,
  "taskId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "ready",
  "solution": {
    "gRecaptchaResponse": "03AGdBq24PBCbwiDR..."
  }
}

Error Response

{
  "errorId": 1,
  "errorCode": "ERROR_KEY_DOES_NOT_EXIST",
  "errorDescription": "The API key you provided does not exist in our system."
}

See the full list of error codes on the Error Codes page.

Rate Limiting

The API enforces a rate limit of 10,000 requests per 10-second window per IP address.

Rate limit information is included in every response via HTTP headers:

Header	Description
X-RateLimit-Limit	Maximum requests allowed in the window
X-RateLimit-Remaining	Requests remaining in the current window
X-RateLimit-Reset	Unix timestamp when the window resets

When the limit is exceeded, the API returns HTTP 429 Too Many Requests.

Task Lifecycle

Every CAPTCHA task moves through the following statuses:

Status	Description
idle	Task has been created but not yet picked up by a provider
processing	Task is actively being solved
ready	Task completed successfully; solution is available
failed	Task failed; the provider could not solve the captcha

Tip

Poll getTaskResult every 5 seconds until the status is ready or failed. Alternatively, use callbacks to receive results via webhook.

Compatibility APIs

uCaptcha is a drop-in replacement for every major CAPTCHA solving service. Change only the base URL — all parameters, response formats, and error codes are identical.

Provider	Migration
2captcha / Anti-Captcha / CapSolver / CapMonster	See Legacy API and createTask — these formats are our primary API
DeathByCaptcha	See DeathByCaptcha API — /api/, /api/:id, /api/user
RiskByPass	See RiskByPass API — /task/submit, /task/result/:id, /api/user/balance

Endpoints

Endpoint	Description
createTask	Submit a new CAPTCHA solving task
getTaskResult	Poll for task status and retrieve the solution
getBalance	Check your account balance
feedbackTask	Report solution quality (valid or invalid)
Callbacks	Receive results via webhook instead of polling
Legacy API	2captcha-compatible /in.php and /res.php endpoints
DeathByCaptcha API	Drop-in DBC compatibility layer
RiskByPass API	Drop-in RiskByPass compatibility layer