Four endpoints, one header.

How this API is shaped

Two vendors, 2 of them live today, and one rule that decides the shape of every endpoint below. It is worth thirty seconds, because once you have it you can predict what each route does without reading its section.

One thing is common to all of them, and it is the thing most likely to cost you a solve: every answer is bound to the session that will use it. Tokens and cookies are minted against an IP, they are single-use, and they live for minutes. Send them from the same egress, on the same session, with the user agent the response gave you — and never cache one.

The full-network Kasada solve: we fetch the challenge page and script through your proxy, run the protection script, post the result and hand back a finished token bundle. Nothing about the chain is yours to build.

Submit returns in about a millisecond with a task id. Collect the result by polling, or register a webhook and skip polling entirely. There is no synchronous version — see how this API is shaped for why, and the transformer if you would rather own the network yourself and get an answer in one call.

Body

Poll as fast as every 100ms. That is a floor we support rather than a limit we tolerate: this endpoint reads one row, is never billed, and exists so you can collect a result the moment it lands. At 1,000 polls per second per key, that floor covers 100 tasks in flight at once — well past the highest concurrency tier. Polling is metered separately from submissions, so checking on work in progress can never consume the allowance you need to submit more of it.

$ curl -X POST https://app.getsolvr.io/api/tasks \
    -H "X-API-Key: solv_live_9f2c…" \
    -d '{"target":"https://www.example.com/"}'

{
  "task_id": "3f6a1c02-7b19-4f5e-9a2d-0c8e1b4d5a77",
  "status":  "queued"
}

202 · still working
{ "task_id": "3f6a…", "status": "processing" }

200 · solved
{ "task_id": "3f6a…", "status": "success",
  "solution": { … }, "latency_ms": 5240 }

200 · failed
{ "task_id": "3f6a…", "status": "failed",
  "kind": "bad_fingerprint", "error": "…" }

A task that is still queued or running returns 202 with status processing, including while it is being retried internally after backpressure. You never see a transient error, and a failed task returns 200 with a typed kind, not an HTTP error. An unknown id returns 404 with kind not_found.

Solution fields

bundles are ip-bound, single-use and live for minutes. we strip them within 72h.

The opposite division of labour to /api/tasks. You make every network request, from your own proxy, TLS session and cookie jar. We do the one part you can't: run the protection script. You get back the exact request to POST, so the token is minted against your egress IP rather than ours.

That matters because tokens are IP-bound. On the full solve you have to keep our session and yours aligned; here there is only ever one session, and it is yours. A transform is roughly 150-250ms and moves no proxy bandwidth through us, which is why it costs $0.001 against $0.002 for a full solve. It is the right endpoint if you already run a browser-grade HTTP stack — and the wrong one if you don't, because everything either side of the transform is yours to build.

Body

body limit 8MB, measured after decompression. this is the one endpoint here with a large body, so check your own client's limits too.
send Content-Encoding: gzip if your stack can — script source compresses about five to one and at this size it is worth it. deflate works too; br and zstd do not, and are refused with a 415 rather than silently mangled.
responses are compressed whenever you send Accept-Encoding, in whatever you ask for.

$ curl -X POST https://app.getsolvr.io/api/kasada/payload \
    -H "X-API-Key: solv_live_9f2c…" \
    -H "Content-Type: application/json" \
    -d '{
      "script_content": "…the ips.js you fetched…",
      "script_url": "https://www.example.com/149e/2d20/ips.js?x-kpsdk-v=j-1.2.661",
      "version": "j-1.2.661"
    }'

{
  "task_id": "9c1e4a7b-2f60-4d13-8ba5-7e0d2c9f1a34",
  "status": "success",
  "transform": {
    "target":  "www.example.com",
    "version": "j-1.2.661",
    "tl_url":  "https://www.example.com/149e/2d20/tl",
    "headers": {
      "x-kpsdk-ct": "…",
      "x-kpsdk-dt": "…",
      "x-kpsdk-im": "…",
      "x-kpsdk-v":  "j-1.2.661"
    },
    "payload": "<base64>",
    "user_agent": "Mozilla/5.0 …",
    "accept_language": "en",
    "timezone": "America/New_York"
  }
}

What you do around us

One session throughout. The session that fetched the page and script must be the session that POSTs the payload and then calls the protected endpoint — same IP, same cookie jar, same TLS fingerprint. Swap any of them and the token is being presented from an address it was never minted for.

Failures here

A narrower set than a solve's, because the network is yours: nothing here can fail on a burned proxy IP or an unreachable target. Those failures still exist — they are just yours to see and handle now.

billed $0.001 per delivered transform, on delivery only, same as a solve.
same concurrency allowance as solves, drawn from one pool. a slot is held only while the call runs, so at ~200ms a transform returns it roughly 25x faster than a solve does — the same tier simply goes much further here.

Mints a fresh x-kpsdk-cd proof-of-work for a token you already hold. Kasada wants a new one on every request to a protected endpoint — replay one across requests and it goes stale and starts failing — so scraping ten thousand pages means ten thousand calls here.

Which is exactly why it costs nothing. Billing per proof would put a price on doing this properly and quietly reward the customer who replays a stale one until it breaks. It is a few hundred hashes with no network behind them, so there is nothing here worth charging you for. It does not decrement your balance and it does not appear on your invoice.

Body

$ curl -X POST https://app.getsolvr.io/api/kasada/cd \
    -H "X-API-Key: solv_live_9f2c…" \
    -H "Content-Type: application/json" \
    -d '{
      "target": "https://www.example.com/",
      "ct": "0KZ2Vr83HIoF0KYB2i3gZNiU39X6…",
      "st": 1786477464392
    }'

{
  "status": "success",
  "target": "www.example.com",
  "cd": {
    "workTime": 1786477507766,
    "id":       "c0ce36a178fc32…",
    "answers":  [1, 7],
    "duration": 18.2,
    "d":        89,
    "st":       1786477464392,
    "rst":      1786477464481
  }
}

Send the cd object JSON-encoded as the x-kpsdk-cd header, next to your current x-kpsdk-ct.

free does not mean unauthenticated: the call still needs your key, and is rate limited per key at 200/s — roughly 2x the ceiling on submissions, because one proof per protected request is the intended pattern.

DataDome throws three different things at a scraper, and this one endpoint solves all three. You fetch whatever it threw, send it here, and get back the exact request to replay from your own session — which is what mints the datadome cookie against your egress rather than ours.

One route rather than three, switched on type, because you do not know which challenge you are about to meet until you meet it. DataDome picks; the branch belongs on a field, not on a URL. There is no proxy field and no task to poll — see how this API is shaped.

The three types

Body

2MB per field, measured after decompression.
send Content-Encoding: gzip if your stack can — a captured page compresses about five to one. deflate works too; br and zstd do not, and are refused with a 415 rather than silently mangled.

$ curl -X POST https://app.getsolvr.io/api/datadome/solve \
    -H "X-API-Key: solv_live_9f2c…" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "interstitial",
      "device_link": "https://geo.captcha-delivery.com/interstitial/?initialCid=…",
      "html": "…the page you just fetched…"
    }'

{
  "task_id": "9c1e4a7b-2f60-4d13-8ba5-7e0d2c9f1a34",
  "status": "success",
  "type":   "interstitial",
  "solution": {
    "payload":  "…url-encoded form body…",
    "post_url": "https://geo.captcha-delivery.com/interstitial/",
    "headers": { … send all of these … },
    "user_agent": "Mozilla/5.0 …"
  }
}

What comes back

Three shapes, because the replays are three different actions. Each one carries only the fields its own type needs, so there is nothing to test for null.

Things that are not our fault, and not yours either

Failures here

Billing is the same rule as everywhere else on this API: you pay for a returned solve and nothing else. A 4xx, a 5xx and backpressure all cost nothing.

Everything else

Current balance and the live per-provider price, including any promotion you qualify for. Free to call and never billed.

{
  "balance":        "42.5000",
  "balance_micros": 42500000,
  "currency":       "USD",
  "providers": {
    "kasada": {
      "price_per_solve":      "0.002000",
      "base_price_per_solve": "0.002000",
      "solves_remaining":     21250,
      "free":                 false
    }
  }
}

money is integer micro-dollars: 1 USD = 1,000,000 micros. a solve is 2,000 of them. balance_micros is the authoritative figure; balance is a rendering of it.
when a promotion applies, each provider also carries a promotion object with name, discount_percent and ends_at.

Errors

Every failure carries a machine-readable kind alongside a human message, so you can branch on the cause instead of parsing prose. None of these are billed.

HTTP status on the synchronous routes

The two are read differently, and the difference is worth knowing before you write the error handling. A collected task reports its failure as 200 with a failed status — the poll succeeded; the solve is what did not. The synchronous routes have nothing to poll, so they map the kind onto the status directly:

Webhooks

Register an https endpoint in your dashboard and we POST signed JSON as things happen. Solve events fire for async tasks only, since a synchronous call already returned you the answer.

Verifying a delivery

The timestamp is inside the signed string, so a captured request cannot be replayed later with a fresh one. Compare in constant time and reject anything older than about five minutes.

Solvr-Event:     task.completed
Solvr-Delivery:  8c1d4e77-2a90-4b13-bf65-…
Solvr-Signature: t=1699999999,v1=<hex>
Content-Type:    application/json

import hmac, hashlib, time

t, v1 = parse(headers["Solvr-Signature"])
if abs(time.time() - int(t)) > 300:
    raise Reject("stale")

expected = hmac.new(
    secret.encode(),
    f"{t}.{raw_body}".encode(),
    hashlib.sha256,
).hexdigest()

if not hmac.compare_digest(expected, v1):
    raise Reject("bad signature")

Respond 2xx within 15 seconds. Anything else is retried at 10s, 1m, 5m, 30m and 2h. After 15 consecutive failures the endpoint is suspended until you re-enable it. Use Solvr-Delivery to deduplicate: a retry reuses the same id.

We run a remote Model Context Protocol server, so an agent that hits a Kasada wall mid-task can solve it and carry on instead of failing. Works with any MCP client: Claude Code, Claude Desktop, Cursor, Codex, Copilot.

There is no separate credential: it authenticates with the same API key, and the same concurrency, balance and revocation rules apply.

Connect

$ claude mcp add --transport http getsolvr \
    https://app.getsolvr.io/mcp \
    --header "X-API-Key: solv_live_9f2c…"

{
  "mcpServers": {
    "getsolvr": {
      "type": "http",
      "url": "https://app.getsolvr.io/mcp",
      "headers": {
        "X-API-Key": "solv_live_9f2c…"
      }
    }
  }
}

Tools

The server ships instructions telling the agent when to reach for a solve, that failures are free to retry, and that bundles are IP-bound and single use, so it generally does the right thing without being told.

there is also a plain-text summary of this page at /llms.txt for agents that just want to read the docs.