{
  "openapi": "3.0.3",
  "info": {
    "title": "DeathByCaptcha HTTP API",
    "version": "2.0.0",
    "description": "REST API for solving CAPTCHAs programmatically. Upload a CAPTCHA image or token challenge and receive the solution. Supports image CAPTCHAs, reCAPTCHA v2/v3, Cloudflare Turnstile, GeeTest v3/v4, hCaptcha, TextCAPTCHA, Audio, and many more types.\n\n**Authentication** via HTTP Basic using your `username` and `password`, or `authtoken` as the username with an empty password. Success responses include a `status` field: `0x00` on success, `0xff` on error.",
    "termsOfService": "https://deathbycaptcha.com/terms-of-service",
    "contact": {
      "name": "DeathByCaptcha Support",
      "email": "help@deathbycaptcha.com"
    },
    "license": {
      "name": "DeathByCaptcha Terms of Service",
      "url": "https://deathbycaptcha.com/terms-of-service"
    }
  },
  "servers": [
    {
      "url": "https://api.dbcapi.me/api",
      "description": "Canonical DeathByCaptcha HTTP API endpoint"
    }
  ],
  "tags": [
    {
      "name": "User",
      "description": "Account balance and user details."
    },
    {
      "name": "Status",
      "description": "Server health, accuracy and solving speed."
    },
    {
      "name": "Captcha",
      "description": "Upload, poll, report and remove CAPTCHA challenges."
    },
    {
      "name": "Postback",
      "description": "Internal token OCR provider notification endpoint."
    }
  ],
  "paths": {
    "/": {
      "get": {
        "tags": ["User"],
        "summary": "Return account details and balance",
        "description": "Authenticates the current user and returns their ID, solving rate, balance and ban status.\n\nAlias: `/user`.",
        "operationId": "getUser",
        "security": [{"basicAuth": []}],
        "responses": {
          "200": {
            "description": "User account details.",
            "content": {
              "application/x-www-form-urlencoded": {
                "schema": { "$ref": "#/components/schemas/UserResponse" }
              },
              "application/json": {
                "schema": { "$ref": "#/components/schemas/UserResponse" }
              }
            }
          },
          "403": {
            "description": "Authentication failed or user banned.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      }
    },
    "/status": {
      "get": {
        "tags": ["Status"],
        "summary": "Return server status and accuracy",
        "description": "Returns whether the service is overloaded, today's solving accuracy, and the average solve time in seconds.",
        "operationId": "getStatus",
        "security": [],
        "responses": {
          "200": {
            "description": "Current server status.",
            "content": {
              "application/x-www-form-urlencoded": {
                "schema": { "$ref": "#/components/schemas/StatusResponse" }
              },
              "application/json": {
                "schema": { "$ref": "#/components/schemas/StatusResponse" }
              }
            }
          }
        }
      }
    },
    "/captcha": {
      "post": {
        "tags": ["Captcha"],
        "summary": "Upload a CAPTCHA for solving",
        "description": "Uploads a CAPTCHA image or token challenge. On success returns the CAPTCHA ID. The client then polls `/captcha/{id}` until the solution is ready.\n\nAlias: `/newrecaptcha` for reCAPTCHA v2/v3 token challenges.\n\n**CAPTCHA types** (`type` field): 0 normal, 1 confident, 2 recaptcha_coordinates, 3 recaptcha_image_group, 4 token_image_group (reCAPTCHA v2), 5 token_v3 (reCAPTCHA v3), 7 hcaptcha, 8 geetest_v3, 9 geetest_v4, 10 keycaptcha, 11 text_captcha, 12 turnstile, 13 audio, 14 lemin, 15 capy, 16 amazon_waf, 17 cybersiara, 18 mtcaptcha, 19 cutcaptcha, 20 friendly_captcha, 21 datadome, 23 tencent, 24 atb, 25 token_enterprise.",
        "operationId": "uploadCaptcha",
        "security": [{"basicAuth": []}],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": { "$ref": "#/components/schemas/CaptchaUploadRequest" },
              "encoding": {
                "captchafile": { "contentType": "image/png, image/jpeg, image/gif, image/webp", "style": "form" }
              }
            },
            "application/x-www-form-urlencoded": {
              "schema": { "$ref": "#/components/schemas/CaptchaUploadRequest" }
            }
          }
        },
        "responses": {
          "303": {
            "description": "CAPTCHA accepted. `Location` header contains `/captcha/{id}`.",
            "headers": {
              "Location": { "schema": { "type": "string", "example": "/captcha/1234567" } }
            },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/CaptchaResponse" }
              }
            }
          },
          "400": {
            "description": "Invalid or missing parameters.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "401": {
            "description": "Authentication failed.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "403": {
            "description": "Insufficient funds or banned user.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "501": {
            "description": "Invalid CAPTCHA image, unsupported CAPTCHA type, or blacklisted CAPTCHA.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "503": {
            "description": "Service overloaded or upload failed.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      }
    },
    "/captcha/{id}": {
      "get": {
        "tags": ["Captcha"],
        "summary": "Poll CAPTCHA status and solution",
        "description": "Returns the status and, once solved, the solution text. Poll every 1-2 seconds until `is_correct` is `true`. If the CAPTCHA is not ready, `text` is empty.",
        "operationId": "getCaptchaStatus",
        "security": [{"basicAuth": []}],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "CAPTCHA external ID returned by `/captcha`.",
            "schema": { "type": "integer", "example": 1234567 }
          }
        ],
        "responses": {
          "200": {
            "description": "CAPTCHA status and solution.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/CaptchaResponse" }
              }
            }
          },
          "404": {
            "description": "CAPTCHA not found or belongs to another user.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      }
    },
    "/captcha/{id}/report": {
      "post": {
        "tags": ["Captcha"],
        "summary": "Report an incorrectly solved CAPTCHA",
        "description": "Reports a CAPTCHA that was solved incorrectly to request a refund. Must be called only for CAPTCHAs owned by the authenticated user.",
        "operationId": "reportCaptcha",
        "security": [{"basicAuth": []}],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "CAPTCHA external ID to report.",
            "schema": { "type": "integer", "example": 1234567 }
          }
        ],
        "responses": {
          "200": {
            "description": "Report accepted.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ReportResponse" }
              }
            }
          },
          "404": {
            "description": "CAPTCHA not found or not owned by this user.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      }
    },
    "/captcha/{id}/remove": {
      "post": {
        "tags": ["Captcha"],
        "summary": "Remove an unsolved CAPTCHA",
        "description": "Deprecated stub. Does nothing but returns an empty response. Kept for API compatibility.",
        "operationId": "removeCaptcha",
        "security": [{"basicAuth": []}],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "CAPTCHA external ID to remove.",
            "schema": { "type": "integer", "example": 1234567 }
          }
        ],
        "responses": {
          "200": {
            "description": "Empty confirmation.",
            "content": {
              "application/json": {
                "schema": { "type": "object", "additionalProperties": true }
              }
            }
          }
        }
      }
    },
    "/newrecaptcha": {
      "post": {
        "tags": ["Captcha"],
        "summary": "Upload a reCAPTCHA token challenge",
        "description": "Alias of `/captcha` for reCAPTCHA v2/v3 token challenges. Accepts `type` = 4 (v2), 5 (v3) or 3 (image group) with the corresponding `token_params`/`banner` fields.",
        "operationId": "uploadRecaptcha",
        "security": [{"basicAuth": []}],
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": { "$ref": "#/components/schemas/CaptchaUploadRequest" }
            }
          }
        },
        "responses": {
          "303": {
            "description": "CAPTCHA accepted.",
            "headers": {
              "Location": { "schema": { "type": "string", "example": "/captcha/1234567" } }
            },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/CaptchaResponse" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/ErrorDefault" },
          "403": { "$ref": "#/components/responses/ErrorDefault" },
          "501": { "$ref": "#/components/responses/ErrorDefault" },
          "503": { "$ref": "#/components/responses/ErrorDefault" }
        }
      }
    },
    "/postback/{ocrid}": {
      "post": {
        "tags": ["Postback"],
        "summary": "Internal token OCR provider notification",
        "description": "Private endpoint used by the token OCR provider to submit solutions. Requires a secret OCR id in the path.",
        "operationId": "tokenOcrPostback",
        "security": [],
        "parameters": [
          {
            "name": "ocrid",
            "in": "path",
            "required": true,
            "description": "Internal OCR provider secret id.",
            "schema": { "type": "string" }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["id", "text"],
                "properties": {
                  "id": { "type": "integer", "description": "CAPTCHA id." },
                  "text": { "type": "string", "description": "Solved token/text." }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Notification processed.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "info": { "type": "string" }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Invalid OCR id.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "basicAuth": {
        "type": "http",
        "scheme": "basic",
        "description": "HTTP Basic authentication. Use your `username` and `password`, or `authtoken` as the username with an empty password."
      }
    },
    "schemas": {
      "UserResponse": {
        "type": "object",
        "properties": {
          "status": { "type": "integer", "format": "hex", "example": 0, "description": "0x00 on success, 0xff on error." },
          "user": { "type": "integer", "example": 12345, "description": "Authenticated user id." },
          "rate": { "type": "number", "example": 0.289, "description": "Cost per CAPTCHA in credits." },
          "balance": { "type": "number", "example": 12.345, "description": "Current account balance in credits." },
          "is_banned": { "type": "boolean", "example": false }
        }
      },
      "StatusResponse": {
        "type": "object",
        "properties": {
          "status": { "type": "integer", "format": "hex", "example": 0 },
          "is_service_overloaded": { "type": "boolean", "example": false, "description": "Whether the service is currently overloaded." },
          "todays_accuracy": { "type": "number", "example": 98.6, "description": "Today's solving accuracy percentage." },
          "solved_in": { "type": "integer", "example": 4, "description": "Average solve time in seconds." }
        }
      },
      "CaptchaUploadRequest": {
        "type": "object",
        "required": ["username", "password"],
        "properties": {
          "username": { "type": "string", "description": "DBC account username (or `authtoken`)." },
          "password": { "type": "string", "description": "DBC account password (empty if using authtoken)." },
          "type": {
            "type": "integer",
            "description": "CAPTCHA type id. See description above. 0 for image CAPTCHAs.",
            "example": 0
          },
          "captchafile": {
            "type": "string",
            "format": "binary",
            "description": "The CAPTCHA image (required for image types 0-3, 13, etc.)."
          },
          "language": { "type": "string", "enum": ["en", "ru"], "default": "en", "description": "CAPTCHA language." },
          "challenge": { "type": "string", "description": "Optional text challenge for reCAPTCHA image group." },
          "banner": { "type": "string", "format": "binary", "description": "Optional sample image for reCAPTCHA image group." },
          "banner_text": { "type": "string", "description": "Optional text hint for reCAPTCHA image group." },
          "vendor_id": { "type": "string", "description": "Optional sub-account / vendor id." },
          "token_params": { "type": "string", "description": "JSON string of token params for reCAPTCHA v2/v3 (challenge, sitekey, etc.)." },
          "hcaptcha_params": { "type": "string", "description": "JSON string of hCaptcha params." },
          "geetest_params": { "type": "string", "description": "JSON string of GeeTest v3/v4 params." },
          "turnstile_params": { "type": "string", "description": "JSON string of Cloudflare Turnstile params." },
          "textcaptcha": { "type": "string", "description": "Text CAPTCHA challenge text." },
          "keycaptcha_params": { "type": "string", "description": "JSON string for keyCAPTCHA." },
          "audio": { "type": "string", "format": "binary", "description": "Audio CAPTCHA file." },
          "lemin_params": { "type": "string", "description": "JSON string for LeMin." },
          "capy_params": { "type": "string", "description": "JSON string for CAPTCHA.Puzzle." },
          "waf_params": { "type": "string", "description": "JSON string for AWS WAF." },
          "siara_params": { "type": "string", "description": "JSON string for CyberSiara." },
          "mtcaptcha_params": { "type": "string", "description": "JSON string for MTCaptcha." },
          "cutcaptcha_params": { "type": "string", "description": "JSON string for CutCaptcha." },
          "friendly_params": { "type": "string", "description": "JSON string for Friendly Captcha." },
          "datadome_params": { "type": "string", "description": "JSON string for DataDome." },
          "tencent_params": { "type": "string", "description": "JSON string for Tencent Captcha." },
          "atb_params": { "type": "string", "description": "JSON string for ATB Captcha." },
          "token_enterprise_params": { "type": "string", "description": "JSON string for enterprise token challenges." }
        },
        "example": {
          "username": "YOUR_USERNAME",
          "password": "YOUR_PASSWORD",
          "type": 0,
          "language": "en",
          "captchafile": "<binary image>"
        }
      },
      "CaptchaResponse": {
        "type": "object",
        "properties": {
          "status": { "type": "integer", "format": "hex", "example": 0, "description": "0x00 on success, 0xff on error." },
          "captcha": { "type": "integer", "example": 1234567, "description": "CAPTCHA encrypted/external id." },
          "text": { "type": "string", "example": "a1B2c3", "description": "The solution text or token. Empty while solving." },
          "is_correct": { "type": "boolean", "example": false, "description": "Whether the solution is ready and was reported as correct." }
        },
        "example": {
          "status": 0,
          "captcha": 1234567,
          "text": "",
          "is_correct": false
        }
      },
      "ReportResponse": {
        "type": "object",
        "properties": {
          "status": { "type": "integer", "format": "hex", "example": 0 },
          "captcha_id": { "type": "integer", "example": 1234567 },
          "text": { "type": "string", "example": "a1B2c3" },
          "is_correct": { "type": "boolean", "example": false },
          "operator_id": { "type": "integer", "example": 9876 },
          "operator_email": { "type": "string", "example": "operator@example.com" }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "status": { "type": "integer", "format": "hex", "example": "0xff", "description": "0xff on error." },
          "error": { "type": "string", "description": "Machine-readable error code." }
        },
        "example": {
          "status": 255,
          "error": "invalid-captcha"
        }
      }
    },
    "responses": {
      "ErrorDefault": {
        "description": "Error response.",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ErrorResponse" }
          }
        }
      }
    }
  }
}