Drag & Drop CAPTCHA

Send a background image plus puzzle pieces and get destination coordinates for each piece.

Use this for visual puzzles where one or more draggable pieces must be placed into matching spaces.

01 / Prepare

Prepare the input

Send the full puzzle background separately from the draggable pieces. Put the pieces in the images array in a known order, and keep that order until you receive the result. Add an instruction if the intended placement is not obvious.

Each task reserves $0.015 from your wallet. Successful tasks cost 1.5 times the provider cost; unused reserved credit is returned. Failed tasks are not charged. Billing details

The result order matches the order of the images array.
A null entry means that piece was not moved. It is not a task failure or a point at (0, 0). Preserve its position in the array.
Keep the background and pieces cropped cleanly so the matching area is visible.

For the complete examples, prepare background.png, piece-1.png, piece-2.png, piece-3.png. You can change these filenames in the code.

File encoding & limits

02 / Request

Request parameters

POST/api/v1/captcha/tasks

Send the JSON object directly, without a task wrapper. Set kind to drag-drop. All fields below belong to the JSON body.

Required headers

Authorizationstringrequired: Bearer followed by your ScrapingBuddy API key. Keep it on your server.
Content-Typestringrequired: application/json.
Idempotency-KeyUUID v4required: Retain one generated UUID per new task. Do not submit the same task concurrently.

Authentication guide

kindstringrequired: Always drag-drop.
backgroundstringrequired: Puzzle background as Base64 or a data URL. JPEG, PNG, or GIF, up to 600 KB.
imagesstring[]required: 1 to 8 puzzle pieces in result order. Each JPEG, PNG, or GIF may be up to 600 KB; use Base64 or data URLs.
commentstringoptional: Explain how to place the pieces, in up to 1000 characters.

Decoded file limits use 1 KB = 1,000 bytes. The complete JSON payload must fit within 5,000,000 bytes after Base64 encoding.

POST /captcha/tasks

{
  "kind": "drag-drop",
  "background": "data:image/png;base64,iVBORw0KGgoAAA...",
  "images": [
    "BASE64_PIECE_1",
    "BASE64_PIECE_2",
    "BASE64_PIECE_3"
  ],
  "comment": "Drag each piece into the matching empty space."
}

Base64 values here are placeholders. The complete examples below encode your local files automatically.

Base URL https://www.scrapingbuddy.com/api/v1

03 / Result

Understand the result

Creation returns HTTP 201. Fetching the task returns HTTP 200. Both wrap the task in task; always check its status before reading the solution.

Each result entry belongs to the piece at the same array position. A null entry means that piece was not moved. Do not remove null entries before matching answers to pieces, because that would shift all later indexes.

solution.coordinates({x, y} | null)[]: One destination per piece, in images order, relative to the background. A null entry means that piece was not moved, not an error or the point (0, 0).

Shared task fields

idUUID: Save this ID to fetch the task or contact support.
statusstring: submitting or processing: wait. ready: use solution. failed: stop and read the error.
solutionobject | null: Null until a result is available. The shape depends on the CAPTCHA type.
errorCode / errorDescriptionstring | null: Task failure details. A failed task can still arrive with HTTP 200 or 201.
coststring | null: Provider-reported USD cost; not the customer debit.
chargedecimal string: Actual customer charge in USD: provider cost multiplied by 1.5. Zero before settlement or for legacy tasks.
billingStatusstring: reserved, charged, released, awaiting_credit, review, or legacy. A review requires support; awaiting_credit needs a top-up.
solveCountnumber | null: Provider-reported solving attempts when available.
createdAt / updatedAt / completedAttimestamp | null: Task timestamps; completedAt is null until the task has finished.
comment / requestMetastring / object: Saved instructions and input metadata. Raw files are not returned.

200 OK / selected fields

{
  "task": {
    "id": "11111111-1111-4111-8111-111111111111",
    "kind": "drag-drop",
    "status": "ready",
    "solution": {
      "coordinates": [
        {
          "x": 120,
          "y": 340
        },
        null,
        {
          "x": 210,
          "y": 90
        }
      ]
    },
    "solveCount": 1
  }
}

201 Created / selected fields

{
  "task": {
    "id": "11111111-1111-4111-8111-111111111111",
    "kind": "drag-drop",
    "status": "processing",
    "solution": null
  }
}

Task-level failure / HTTP 201 or 200

{
  "task": {
    "id": "11111111-1111-4111-8111-111111111111",
    "kind": "drag-drop",
    "status": "failed",
    "solution": null,
    "errorCode": "ERROR_CAPTCHA_UNSOLVABLE",
    "errorDescription": "Captcha task could not be solved."
  }
}

Read the solution / JavaScript

task.solution.coordinates.forEach((destination, index) => {
  if (destination === null) return;
  console.log({ piece: images[index], destination });
});

04 / Integrate

Complete examples

These Node.js and Python scripts prepare the input, create one task and poll until it is ready or failed. They stop waiting after approximately 3 minutes. A client timeout does not cancel the task.

Set SCRAPINGBUDDY_API_KEY in your server environment.
Place the input files beside your script, or update the filenames.
For Node.js, use version 20+ and save as solve.mjs. For Python, install requests and save as solve.py.
Run the script and retain the printed request and task IDs.

cURL shows task creation only. Use the GET example to retrieve its result.

solve.mjs / node solve.mjs

// Node.js 20+. Run: node solve.mjs
import { readFile } from "node:fs/promises";
import { randomUUID } from "node:crypto";

const base = "https://www.scrapingbuddy.com/api/v1";
if (!process.env.SCRAPINGBUDDY_API_KEY) throw new Error("Set SCRAPINGBUDDY_API_KEY.");
const auth = { Authorization: "Bearer " + process.env.SCRAPINGBUDDY_API_KEY };
const encode = async (path) => (await readFile(path)).toString("base64");
const body = {
  "kind": "drag-drop",
  "comment": "Drag each piece into the matching empty space."
};
body.background = await encode("background.png");
body.images = await Promise.all(["piece-1.png","piece-2.png","piece-3.png"].map(encode));

async function api(path, options = {}) {
  const response = await fetch(base + path, {
    ...options,
    headers: { ...auth, "Content-Type": "application/json", ...options.headers },
    signal: AbortSignal.timeout(30000),
  });
  const data = await response.json().catch(() => ({}));
  if (!response.ok) throw new Error(response.status + ": " + (data.error || response.statusText)
    + "; Retry-After: " + response.headers.get("Retry-After"));
  return data;
}

// Retain this ID; never retry POST concurrently or automatically after a timeout.
const requestId = randomUUID();
console.log("Request ID:", requestId);
const created = await api("/captcha/tasks", {
  method: "POST",
  headers: { "Idempotency-Key": requestId },
  body: JSON.stringify(body)
});

let task = created.task;
console.log("Task ID:", task.id);
const deadline = Date.now() + 180_000;
while (task.status === "submitting" || task.status === "processing") {
  if (Date.now() >= deadline) throw new Error("Still processing. Resume GET polling for " + task.id);
  await new Promise((resolve) => setTimeout(resolve, 6000));
  task = (await api("/captcha/tasks/" + task.id, { headers: {} })).task;
}

if (task.status !== "ready") throw new Error(task.errorCode + ": " + task.errorDescription);
console.log(task.solution);

solve.py / python solve.py

# Python 3. Install: pip install requests. Run: python solve.py
import base64, json, os, time, uuid, requests
from pathlib import Path

BASE = "https://www.scrapingbuddy.com/api/v1"
auth = {"Authorization": "Bearer " + os.environ["SCRAPINGBUDDY_API_KEY"]}
def encode(path):
    return base64.b64encode(Path(path).read_bytes()).decode("ascii")

body = json.loads(r'''{
  "kind": "drag-drop",
  "comment": "Drag each piece into the matching empty space."
}''')
body["background"] = encode("background.png")
body["images"] = [encode(path) for path in ["piece-1.png","piece-2.png","piece-3.png"]]

# Retain this ID; do not automatically retry POST after a timeout.
request_id = str(uuid.uuid4())
print("Request ID:", request_id)

response = requests.post(
    BASE + "/captcha/tasks",
    json=body,
    headers={**auth, "Content-Type": "application/json", "Idempotency-Key": request_id},
    timeout=30,
)
response.raise_for_status()
task = response.json()["task"]
print("Task ID:", task["id"])
deadline = time.monotonic() + 180

while task["status"] in ("submitting", "processing"):
    if time.monotonic() >= deadline:
        raise TimeoutError("Still processing. Resume GET polling for " + task["id"])
    time.sleep(6)
    poll = requests.get(BASE + "/captcha/tasks/" + task["id"], headers=auth, timeout=30)
    poll.raise_for_status()
    task = poll.json()["task"]

if task["status"] != "ready":
    raise RuntimeError(f"{task.get('errorCode')}: {task.get('errorDescription')}")
print(task["solution"])

Bash / create request only

# Keep your secret in an environment variable.
export SCRAPINGBUDDY_API_KEY="YOUR_API_KEY"

# Bash. Replace sample Base64 values before sending.
# Generate and retain one UUID v4 per new task; do not retry concurrently.
export TASK_IDEMPOTENCY_KEY="$(uuidgen)"

curl -X POST "https://www.scrapingbuddy.com/api/v1/captcha/tasks" \
  -H "Authorization: Bearer $SCRAPINGBUDDY_API_KEY" \
  -H "Idempotency-Key: $TASK_IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "kind": "drag-drop",
  "background": "data:image/png;base64,iVBORw0KGgoAAA...",
  "images": [
    "BASE64_PIECE_1",
    "BASE64_PIECE_2",
    "BASE64_PIECE_3"
  ],
  "comment": "Drag each piece into the matching empty space."
}'

When something goes wrong

Check whether you received an HTTP error or a task with status: failed. Fix validation errors before retrying. For HTTP 429, pause for Retry-After; all requests share the account limit of 60 per minute.

If creation times out, do not automatically submit another task. Keep your request ID and check the existing task or Usage first.

Errors & troubleshooting Polling & safe retries Contact support