Skip to main content
ScrapingBuddy
Skip to content
ScrapingBuddyDevelopers
Dashboard
On this page Create and store a key

CAPTCHA API/Guides

Authentication

Connect your backend securely with a ScrapingBuddy API key.

Create and store a key

Create a key from Profile > API access while signed in. Store it in an environment variable such as SCRAPINGBUDDY_API_KEY. Use your deployment platform secret store in production.

API keys identify your account. Never include them in browser JavaScript, screenshots, uploaded challenges or support messages. If a key is exposed, revoke it in your account and replace it.

Authenticate every request

Send the key in the Authorization header using the Bearer scheme. Both POST and GET requests need this header. Do not put your key in a query string.

For task creation, also send Content-Type: application/json and a UUID v4 Idempotency-Key. GET polling does not require an idempotency header.

Example
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Idempotency-Key: 11111111-1111-4111-8111-111111111111

Use the customer API

All examples use the public customer API base URL below. Append /captcha/tasks to create or list tasks and /captcha/tasks/{id} to fetch one.

The dashboard uses separate internal routes. Do not copy those routes into your integration; use /api/v1. Your ScrapingBuddy key cannot be substituted with a 2Captcha key.

Example
https://www.scrapingbuddy.com/api/v1

Resolve a 401 response

Check that the Authorization header includes Bearer followed by one space and your complete key. Make sure the environment variable is loaded in the process making the request.

A missing, expired, revoked or invalid key returns HTTP 401. Fix the credentials before retrying; repeatedly sending the same invalid key will not help.

Manage API keysExplore API reference
CAPTCHA API v1
Getting startedIntroductionYour first taskAuthenticationPrepare image & audio inputs
Integration guidesPolling & safe retriesErrors & troubleshootingList tasks & usage
API keys Contact support

Explore the documentation

CAPTCHA APIIntroduction

Choose a CAPTCHA solution, create a task and retrieve its answer.

Integration guidesYour first task

Make one request, wait for the answer, and read your first result. Start with a text question so you do not need to prepare a file.

Integration guidesAuthentication

Connect your backend securely with a ScrapingBuddy API key.

Integration guidesPrepare image & audio inputs

Encode the original file correctly and stay within the limits for your solution.

Integration guidesPolling & safe retries

Follow a task to completion without creating duplicate work.

Integration guidesErrors & troubleshooting

Find out whether a request was rejected, a task failed, or you simply need to wait.

Integration guidesList tasks & usage

Retrieve your recent tasks and account-level usage summary.

CAPTCHA referenceCoordinates CAPTCHA

Send one image and get back the x/y click points requested by your instruction. Use this for image challenges where the answer is one or more points, such as “click the apple” or “

CAPTCHA referenceGrid CAPTCHA

Send separate tile images or one complete grid and get back the selected tile numbers. Use this for challenges that ask the user to select matching squares from a tiled image.

CAPTCHA referenceDrag & 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 matchi

CAPTCHA referenceBounding Box CAPTCHA

Send one image and get object boundaries as xMin, xMax, yMin, and yMax. Use this for challenges that ask the user to draw a box around an object or region.

CAPTCHA referenceNormal CAPTCHA

Send a CAPTCHA image and get back the text that should be typed. Use this for distorted image text challenges where the expected answer is a string.

CAPTCHA referenceText CAPTCHA

Send a plain text question and get back the answer text. Use this for human-readable questions, riddles, or text-only challenges that do not require an image upload.

CAPTCHA referenceRotate CAPTCHA

Send an image and get back the angle needed to rotate it into the correct position. Use this for challenges where an image must be turned until it is upright or aligned.

CAPTCHA referenceAudio CAPTCHA

Send an MP3 audio CAPTCHA and get back the transcribed text. Use this for audio challenges where the answer is the words or numbers spoken in the file.