API Reference

Tiger Captcha solves Facebook captchas through a simple, asynchronous JSON API. Submit a task, get a taskId instantly, then poll for the result or receive it by webhook.

• Content type: application/json on every request.

Authentication

Every request is authenticated with your account API key, sent as clientKey in the JSON body. Create and manage keys from your dashboard.

{ "clientKey": "tc_live_your_api_key", "task": { } }

The solve flow

• 1. Create — POST /createTask with the image → get a taskId.
• 2. Wait — poll POST /getTaskResult every ~1s or receive a webhook.
• 3. Read — when status is ready, take the answer from solution.text.

Quick start

A full create-and-poll loop in your language of choice:

import base64, time, requests

GATEWAY = "https://api.tigercaptcha.com"
API_KEY = "tc_live_your_api_key"

def solve(path):
    b64 = base64.b64encode(open(path, "rb").read()).decode()
    task = requests.post(f"{GATEWAY}/createTask", json={
        "clientKey": API_KEY,
        "task": {"type": "FacebookCaptchaImage", "body": b64},
    }).json()
    task_id = task["taskId"]
    while True:
        r = requests.post(f"{GATEWAY}/getTaskResult", json={
            "clientKey": API_KEY, "taskId": task_id}).json()
        if r.get("status") == "ready": return r["solution"]["text"]
        if r.get("status") == "error": raise RuntimeError(r.get("errorDescription"))
        time.sleep(1)

print(solve("captcha.png"))

import { readFileSync } from "fs";
const GATEWAY = "https://api.tigercaptcha.com", API_KEY = "tc_live_your_api_key";

async function solve(path) {
  const body = readFileSync(path).toString("base64");
  const { taskId } = await (await fetch(`${GATEWAY}/createTask`, {
    method: "POST", headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ clientKey: API_KEY, task: { type: "FacebookCaptchaImage", body } }),
  })).json();
  for (;;) {
    const r = await (await fetch(`${GATEWAY}/getTaskResult`, {
      method: "POST", headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ clientKey: API_KEY, taskId }),
    })).json();
    if (r.status === "ready") return r.solution.text;
    if (r.status === "error") throw new Error(r.errorDescription);
    await new Promise(s => setTimeout(s, 1000));
  }
}
console.log(await solve("captcha.png"));

# 1) create
curl -s -X POST https://api.tigercaptcha.com/createTask \
  -H 'Content-Type: application/json' \
  -d "{\"clientKey\":\"tc_live_...\",\"task\":{\"type\":\"FacebookCaptchaImage\",\"body\":\"$(base64 -w0 captcha.png)\"}}"
# -> {"errorId":0,"taskId":"a1b2c3..."}

# 2) poll
curl -s -X POST https://api.tigercaptcha.com/getTaskResult \
  -H 'Content-Type: application/json' \
  -d '{"clientKey":"tc_live_...","taskId":"a1b2c3..."}'
# -> {"errorId":0,"status":"ready","solution":{"text":"AB12CD"}}

Create task

Submit a Facebook captcha. Returns a taskId instantly. The task.type selects how you supply the image.

Body parameters

Response 200 OK

{ "errorId": 0, "taskId": "a1b2c3d4e5f6…" }

Solve by image

Send the captcha itself as base64 in task.body with type FacebookCaptchaImage. This is what a Facebook captcha looks like — and what you get back:

→ apgXfK

Request

{
  "clientKey": "tc_live_your_api_key",
  "task": {
    "type": "FacebookCaptchaImage",
    "body": "/9j/4AAQSkZJRgABAQEAYABgAAD…"   // base64 of the image above
  }
}

Then poll getTaskResult — or add a callbackUrl — and read solution.text ("apgXfK").

Solve by URL

Give us a public image URL with type FacebookCaptchaUrl and our worker fetches it. The image bytes never touch your side — handy when you already have the captcha's URL, and lighter on bandwidth.

A Facebook captcha URL typically looks like this:

https://www.facebook.com/captcha/tfbimage/?bd=EiIGSNX…&db=2&tk=AYjq9Rf…

Request

{
  "clientKey": "tc_live_your_api_key",
  "task": {
    "type": "FacebookCaptchaUrl",
    "url": "https://www.facebook.com/captcha/tfbimage/?bd=EiIGSNX…"
  }
}

Webhooks

Add a callbackUrl to createTask and we'll POST the result to it the moment the task finishes — no polling needed. getTaskResult still works, so you can use either or both.

Content-Type: application/json
X-Tiger-Task-Id: a1b2c3…
X-Tiger-Signature: sha256=<hmac>

{ "taskId": "a1b2c3…", "status": "ready", "solution": { "text": "AB12CD" } }

• On failure the body is { "status": "error", "errorCode": …, "errorDescription": … }.
• Verify it's from us: X-Tiger-Signature is sha256= + HMAC-SHA256 of the raw body, keyed by your API key.
• callbackUrl must be a public http(s) URL. We retry with backoff, then give up — the result stays fetchable by taskId.

import hmac, hashlib
expected = "sha256=" + hmac.new(API_KEY.encode(), request.body, hashlib.sha256).hexdigest()
# constant-time compare vs the X-Tiger-Signature header

Get task result

Fetch a task's state by taskId. Poll until the status is no longer processing.

Still working

{ "errorId": 0, "status": "processing" }

Solved

{ "errorId": 0, "status": "ready", "solution": { "text": "AB12CD" } }

Failed

{ "errorId": 1, "status": "error",
  "errorCode": "ERROR_SOLVE_FAILED", "errorDescription": "Internal solver error" }

Get balance

Read your account balance and plan details. Works even for a zero-balance or unverified account — only an unknown key is rejected.

{ "clientKey": "tc_live_your_api_key" }

{
  "errorId": 0,
  "balance": 12.35,
  "currency": "USD",
  "plan": "Pay-As-You-Go",
  "status": "active",
  "emailVerified": true,
  "subscription": null,
  "pricePer1000": 1.0,
  "concurrency": 10,
  "rps": 15
}

Plan limits

Each key has a concurrency (max tasks in flight at once) and a requests-per-second cap set by your plan — call getBalance to read them. Exceeding either returns 429:

• ERROR_RATE_LIMIT — too many createTask calls per second. Honour Retry-After.
• ERROR_CONCURRENCY_LIMIT — too many tasks still unfinished. Retrieve results (that frees a slot) before submitting more, or upgrade for more threads.

A concurrency slot frees the instant a task reaches ready or error.

Error codes

Every response carries an errorId — 0 means success. Failures also include a machine-readable errorCode and a human errorDescription.

Need help? Create an account to get your API key and start solving.