The DeathByCaptcha API Explained: Endpoints, Types, and Flow

The beginner articles got you solving your first CAPTCHA. Now it is time to understand the API properly so you can build reliable integrations. This article walks through the endpoints, the CAPTCHA type system, and the full request flow.

The Two API Styles

DeathByCaptcha exposes two ways to talk to it:

1. The REST API at api.dbcapi.me, which uses plain HTTP. It is easy to use with any language or even curl.
2. The socket API, used by the official client libraries. It is faster because it reuses a persistent connection, which matters when you solve many CAPTCHAs.

The official clients default to the socket API and fall back to HTTP if the socket connection fails.

The Full Request Flow

The flow has four steps:

1. Submit the CAPTCHA

curl --data-urlencode "username=YOUR_USERNAME" \
     --data-urlencode "password=YOUR_PASSWORD" \
     --data-urlencode "captchafile=captcha.png" \
     http://api.dbcapi.me/api/captcha

The response is JSON and contains a captcha object with a numeric captcha ID.

2. Poll until solved

curl --data-urlencode "username=YOUR_USERNAME" \
     --data-urlencode "password=YOUR_PASSWORD" \
     "http://api.dbcapi.me/api/captcha/CAPTCHA_ID"

When the CAPTCHA is still being solved, the response contains no text field. When it is done, text holds the answer.

3. Use the answer

Pass the token or text to your website automation.

4. Report bad solves (optional)

curl --data-urlencode "username=YOUR_USERNAME" \
     --data-urlencode "password=YOUR_PASSWORD" \
     -X POST http://api.dbcapi.me/api/captcha/CAPTCHA_ID/report

This teaches the service and helps future solves. Only report when the website rejected the answer.

The Type System

The REST API uses an integer type field to know what kind of CAPTCHA you are submitting. The most important ones:

Each type expects a different payload. For example, reCAPTCHA types take a JSON object with the sitekey and page URL, while image types take the file directly.

Client-Side Idioms

The official clients wrap the flow in a single call. With the Python client:

import deathbycaptcha

client = deathbycaptcha.SocketClient("user", "pass")

# image captcha
captcha = client.decode(open("captcha.png", "rb").read(), timeout=60)

# token captcha
captcha = client.decode({
    "googlekey": "SITE_KEY",
    "pageurl": "https://example.com",
}, type=4, timeout=60)

if captcha:
    print(captcha.text)

Behind the scenes the client submits, polls with exponential backoff, and honors the timeout you pass.

In Node.js the call looks like this:

const DBC = require('deathbycaptcha');
const fs = require('fs');

const client = new DBC.SocketClient('user', 'pass');

// image captcha
let captcha = await client.decode(fs.readFileSync('captcha.png'), 60);

// token captcha
captcha = await client.decode({
    googlekey: 'SITE_KEY',
    pageurl: 'https://example.com',
}, 60, 4);

if (captcha) {
    console.log(captcha.text);
}

And in C#:

using System;
using System.Collections;
using System.IO;
using DeathByCaptcha;

Client client = new DeathByCaptcha.HttpClient("user", "pass");

// image captcha
Captcha captcha = client.Decode(File.ReadAllBytes("captcha.png"), Client.DefaultTimeout);

// token captcha
string tokenParams = "{\"googlekey\":\"SITE_KEY\",\"pageurl\":\"https://example.com\"}";
captcha = client.Decode(Client.DefaultTimeout,
    new Hashtable { { "type", 4 }, { "token_params", tokenParams } });

if (captcha != null)
    Console.WriteLine(captcha.Text);

Reading the Response Object

The decoded object has useful fields:

• captcha: the numeric ID.
• text: the answer, when solved.
• is_correct: whether the answer was reported as correct.
• is_solved: whether the service produced an answer.

Key Takeaways

• Use the socket API for high throughput and the REST API for simple scripts.
• The flow is always submit, poll, use, and optionally report.
• The integer type selects the CAPTCHA engine and dictates the payload shape.
• Official clients collapse the flow into a single decode call.

Next up: how to pick the right CAPTCHA type for your specific use case.