API

Before implementing your own Death By Captcha HTTP API client, please seriously consider using socket API with one of our official clients listed above.

The API url is http://api.dbcapi.me/api/. The URL path changes depending on the action desired. All responses from requests made to the API have two common fields:

• status — request status. 0 if there were no errors during internal request processing, 255 otherwise.
• error — short explanation of the occurred error. Only returned when status is 255.

For details about correct URL path and other returned fields for a specific action, refer to its section below.

All API responses are returned URL-encoded by default. If JSON encoding is desired, include application/json in the Accept header of your request. Note that boolean true will be returned as 1 in URL-encoded responses and as true in JSON-encoded responses. Boolean false will be returned as 0 in URL-encoded responses and as false in JSON-encoded responses.

What are "normal captcha" challenges?

This form of CAPTCHA are image-based and requires entering a sequence of letters or numbers from a distorted image.

To upload a CAPTCHA, issue a multipart/form-data POST request to http://api.dbcapi.me/api/captcha. The request must contain the following fields:

• username — your Death By Captcha username.
• password — your Death By Captcha password.
• captchafile — the CAPTCHA image.

In case you are using token authentication:

• authtoken — your Death By Captcha authentication token.
• captchafile — the CAPTCHA image.

captchafile should be either raw CAPTCHA image file, or base64-encoded CAPTCHA image prepended with base64: prefix. Image file size is limited to less than 180 KB. When the image will be encoded in base64, the size should be lower than 120 KB. The supported image formats are JPG, PNG, GIF and BMP.

Here is the HTML form that does the trick:

<form action="http://api.dbcapi.me/api/captcha"method="post" enctype="multipart/form-data">
    <input type="text"     name="username" value="">
    <input type="password" name="password" value="">
    <input type="file"     name="captchafile">
</form>

Or using token authentication:

<form action="http://api.dbcapi.me/api/captcha"method="post" enctype="multipart/form-data">
    <input type="text"     name="authtoken" value="">
    <input type="file"     name="captchafile">
</form>

Here is cURL command equivalent:

curl --header 'Expect: ' -F username=YOUR_USERNAME  -F password=YOUR_PASSWORD  -F captchafile=@YOUR_CAPTCHA_FILENAME http://api.dbcapi.me/api/captcha

Or using token authentication:

curl --header 'Expect: ' -F authtoken=YOUR_AUTHTOKEN  -F captchafile=@YOUR_CAPTCHA_FILENAME http://api.dbcapi.me/api/captcha

base64-encoded captchafile field should look like this:

base64:R0lGODlhAQABAIABAAAAAP///yH5BAEAAAEALAAAAAABAAEAAAICTAEAOw==

You`ll get one of the following HTTP responses:

• 303 See Other if your CAPTCHA was successfully uploaded, Location HTTP header will point you to the uploaded CAPTCHA status page, you may follow the Location to get the uploaded CAPTCHA status. Also, the following fields will be returned:
  
  • captcha — id of the uploaded captcha.
  • is_correct — 1 if an answer has been identified for this captcha or it is still being processed, 0 if processing finished and no answer could be found.
  • text — captcha answer. An empty string means that the captcha is not solved yet.
  URL encoded example:

  status=0&captcha=123&is_correct=1&text=

  JSON encoded example:

  { "status": 0, "captcha": 123, "is_correct": 1, "text": "" }

• 403 Forbidden if your Death By Captcha credentials were rejected, or you don`t have enough credits.
• 400 Bad Request if your request did not follow the specification above, or the CAPTCHA was rejected for not being a valid image.
• 500 Internal Server Error if something happened on our side preventing you from uploading the CAPTCHA; if you are sure you are sending properly structured requests with valid CAPTCHA images but the problem persists, please contact our live support and tell them in details how to reproduce the issue.
• 503 Service Temporarily Unavailable when our service is overloaded, try again later.

At this point the CAPTCHA you`ve just uploaded may not be solved yet! If you did not receive the answer in the text key of the server response, you have to poll for it. Refer to Polling for uploaded CAPTCHA status for more details.

To get an uploaded CAPTCHA`s status, issue a GET request to http://api.dbcapi.me/api/captcha/%CAPTCHA_ID%, where %CAPTCHA_ID% is your uploaded CAPTCHA`s ID acquired while uploading the CAPTCHA. You don`t have to supply your Death By Captcha credentials this time. The response will be a HTTP 200 OK response with the same fields described for the 303 See Other response of the Uploading a CAPTCHA section.

If the captcha is not solved yet, the text key will come empty. You will have to keep on polling for this answer. Example responses:

• URL-encoded response of a correctly solved CAPTCHA

  status=0&captcha=1234&is_correct=1&text=tyrone+slothrop

• JSON-encoded response of a correctly solved CAPTCHA

  { "captcha": 1234, "is_correct": true,"status": 0, "text": "tyrone slothrop" }

• JSON-encoded response of an incorrectly solved CAPTCHA

  { "captcha": 1234, "is_correct": false, "status": 0, "text": "?" }

• JSON-encoded response of an inexistent captcha

  { "captcha": 0, "status": 0 }

  If you get this response, confirm that the CAPTCHA id you are using to poll for the answer is the same one returned when it was uploaded. If the problem persists, feel free to contact us.

Please don`t poll for a CAPTCHA status more than once in a couple of seconds.
This is considered abusive and might get you banned.
Conserve your and our bandwidth.

If you think your CAPTCHA was solved incorrectly, report it to Death By Captcha to get your money back. To do so, issue a POST request to http://api.dbcapi.me/api/captcha/%CAPTCHA_ID%/report with the following fields:

• username — your Death By Captcha username.
• password — your Death By Captcha password.

Or using authentication token:

• authtoken — your Death By Captcha authentication token.

The response will be:

• 200 OK if report was completed. In this case, your credits will be refunded. The response body will be the same as for a poll (or upload) but the is_correct field will be 0. Example:

  { "captcha": 1234, "is_correct": false,"status": 0, "text": "tyrone slothrop" }

• 503 Service Unavailable if report could not be completed. This might be because:
  1) captcha corresponding to the provided id was not uploaded by the user reporting it;
  2) your user is banned;
  3) report was made more than an hour after if was uploaded. In this case, you won`t be refunded.

Abusing this feature will get you banned!

To check your credit balance, issue a GET or POST request to http://api.dbcapi.me/api with the following fields:

• username — your Death By Captcha username.
• password — your Death By Captcha password.

Or using authentication token:

• authtoken — your Death By Captcha authentication token.

On successful authentication, you`ll get 200 OK response with your Death By Captcha account details, either URL- or JSON-encoded, with the following fields:

• user — your Death By Captcha account ID;
• rate — how much we charge you for one correctly solved CAPTCHA, in US¢;
• balance — your current credit balance, in US¢.
• is_banned — 1 if user is banned, 0 if not.

Example JSON-encoded response:

{ "is_banned": false, "status": 0, "rate": 0.139,"balance": 455.23, "user": 43122 }