Documentation

Base URLhttps://api.capsolve.io

Authentication

Send your API key with every request, in the X-API-Key header or as a bearer token. Create keys in the dashboard; each account can have up to 10 active keys.

Headers

X-API-Key: YOUR_API_KEY
# or
Authorization: Bearer YOUR_API_KEY

For GET services the key can also be passed as the api_key query parameter. The header is preferred, because URLs are stored in logs and browser history.

Making a request

Each API is at https://api.capsolve.io/{service}. The method and parameters are listed on each API's page.

POST APIs take a JSON body (Content-Type: application/json, max 256 kb).
GET APIs take parameters in the query string.
Parameters that are not defined for the API are dropped.

GET https://api.capsolve.io/ lists the endpoints that are currently live.

Response format

The result is in data. meta.cost is the price charged for the request and meta.balance is your balance after it. The X-Request-Id header has the same value as meta.request_id.

Success

200

{
  "status": "success",
  "data": { },
  "meta": {
    "request_id": "req_Bw8v3K2k4sLb",
    "service": "service-name",
    "cost": 0.0008,
    "balance": 24.9992,
    "latency_ms": 312
  }
}

Error

4xx / 5xx

{
  "status": "error",
  "error": {
    "code": "invalid_params",
    "message": "'sitekey' is required"
  },
  "meta": {
    "request_id": "req_j1u4iKsRK01Y"
  }
}

Errors

Requests that end in an error are not charged.

Code	HTTP	Meaning
`missing_api_key`	401	No API key was sent.
`invalid_api_key`	401	The key does not exist or was revoked.
`account_disabled`	403	The account is disabled.
`unknown_service`	404	No API with that name.
`method_not_allowed`	405	Wrong HTTP method for this API.
`invalid_params`	400	A parameter is missing, has the wrong type or is not an allowed value.
`invalid_json`	400	The body is not valid JSON.
`payload_too_large`	413	The body is over 256 kb.
`insufficient_balance`	402	The balance is lower than the price of the request.
`rate_limited`	429	Over 1,200 requests per minute for the key, over the API's own limit, or too many invalid keys from one IP.
`service_unavailable`	503	The API is offline or not available yet.
`upstream_error`	502 / 422	The request could not be completed. 422 means the input was rejected.
`upstream_timeout`	504	No result within the time limit.
`too_many_tasks`	429	200 async tasks are already running.
`task_not_found`	404	No such task, or its result has expired.
`interrupted`	503	Task results only: the server restarted while the task was running.

Async tasks

Each API page shows its mode:

Sync: the response contains the result.
Async: the response contains a task ID; fetch the result later.
Both: sync by default; add ?async=1 or the header X-Async: 1 to create a task.

Create a task

Same request as sync. Returns 202; the price is reserved at this point.

202

{
  "status": "processing",
  "data": {
    "task_id": "task_3iICeoad1BAlL-EM",
    "poll_url": "https://api.capsolve.io/tasks/task_3iICeoad1BAlL-EM"
  },
  "meta": {
    "request_id": "req_PHci_SJIjeCL",
    "service": "service-name",
    "cost": 0.0008,
    "balance": 24.9992
  }
}

Get the result

GET/tasks/{task_id}

Use the same API key. ?wait=N (1–30) keeps the request open until the task finishes or N seconds pass. While running, status is processing; when finished the response has the same shape as a sync response.

Results are kept for 1 hour after the task finishes.
A failed task is refunded.
Up to 200 tasks can run at once per account.

Account

GET/account

Returns the balance and last 24 hours of usage for the key's account. Not charged.

Response

{
  "status": "success",
  "data": {
    "username": "your_handle",
    "balance": 24.9992,
    "requests_24h": 1342,
    "spend_24h": 1.0736,
    "plan": "pay-as-you-go"
  },
  "meta": {
    "request_id": "req_Bw8v3K2k4sLb"
  }
}