API Reference

Base URL: https://api.agentcaptcha.com

Authentication

The solve endpoints use API key authentication via the X-API-Key header. Account management endpoints (keys, billing) use JWT Bearer tokens.

API Key authentication (for /v1/* endpoints):

curl -H "X-API-Key: ac-your-key-here" ...

JWT Bearer authentication (for /keys, /auth/me):

curl -H "Authorization: Bearer eyJ..." ...

MCP Setup

The fastest way to integrate AgentCaptcha — one command and your AI agent gets CAPTCHA solving superpowers.

Claude Code

claude mcp add agentcaptcha -- npx agentcaptcha-mcp

Then add your API key to Claude Code MCP environment settings:

AGENTCAPTCHA_API_KEY=ac-your-key-here

Cursor

// .cursor/mcp.json
{
  "mcpServers": {
    "agentcaptcha": {
      "command": "npx",
      "args": ["agentcaptcha-mcp"],
      "env": {
        "AGENTCAPTCHA_API_KEY": "ac-your-key-here"
      }
    }
  }
}

Available MCP Tools

captcha_solve(siteKey, pageUrl, captchaType?) → token
captcha_balance() → plan, used, remaining
captcha_types() → list of supported types

Endpoints

POST/v1/solveSubmit CAPTCHA (async)

Request body:

{ "siteKey": "6Le-abc", "pageUrl": "https://...", "captchaType": "recaptcha_v2" }

Response:

{ "taskId": "uuid", "status": "pending" }
GET/v1/result/:idPoll solve result

Response:

{ "status": "solved", "token": "03AGdBq...", "elapsed_ms": 6204 }
POST/v1/solve/syncSynchronous solve (120s timeout)

Request body:

{ "siteKey": "6Le-abc", "pageUrl": "https://...", "captchaType": "recaptcha_v2" }

Response:

{ "success": true, "token": "03AGdBq...", "elapsed_ms": 6204 }
GET/v1/balanceCheck usage and quota

Response:

{ "plan": "pro", "used_this_month": 423, "plan_limit": 5000, "remaining": 4577 }
GET/v1/typesList supported CAPTCHA types

Response:

{ "types": ["recaptcha_v2", "recaptcha_v3", "turnstile", "funcaptcha", "image_captcha"] }
POST/auth/signupRegister new account

Request body:

{ "email": "you@example.com", "password": "secret", "country": "US" }

Response:

{ "token": "eyJ...", "user": { "id": "...", "plan_id": "free" } }
POST/auth/loginLogin and get JWT

Request body:

{ "email": "you@example.com", "password": "secret" }

Response:

{ "token": "eyJ..." }
POST/keysCreate API key (JWT auth)

Request body:

{ "name": "Production" }

Response:

{ "key": "ac-abc123...", "prefix": "ac-abc123" }
GET/keysList API keys (JWT auth)

Response:

{ "keys": [{ "id": "...", "key_prefix": "ac-abc1...", "name": "Production" }] }
DELETE/keys/:idRevoke API key (JWT auth)

Response:

{ "success": true }

Error Codes

200Success
202Task accepted (async solve)
400Bad request — missing or invalid parameters
401Unauthorized — invalid or missing API key / JWT
402Payment required — quota exceeded
404Task not found
429Too many requests — rate limited
500Internal error — contact support

Full Examples

reCAPTCHA v2 — Python

import requests

token = requests.post(
    "https://api.agentcaptcha.com/v1/solve/sync",
    headers={"X-API-Key": "ac-your-key"},
    json={"siteKey": "6Le-abc", "pageUrl": "https://example.com", "captchaType": "recaptcha_v2"},
    timeout=130,
).json()["token"]

print(token[:30])  # 03AGdBq...

Turnstile — Node.js

const res = await fetch('https://api.agentcaptcha.com/v1/solve/sync', {
  method: 'POST',
  headers: { 'X-API-Key': 'ac-your-key', 'Content-Type': 'application/json' },
  body: JSON.stringify({ siteKey: '0x4AAA...', pageUrl: 'https://example.com', captchaType: 'turnstile' }),
  signal: AbortSignal.timeout(130_000),
});
const { token } = await res.json();