API reference

One endpoint answers image challenges. Send the challenge the way it was served to you, and get back the answer object ready to submit. JSON in, JSON out.

base url

https://api.xqroo.com

Authenticate every request with your key as a bearer token:

Authorization: Bearer hk_your_key

POST /solve

Send one challenge. The request fields depend on the challenge type.

Field	Required	Meaning
`question`	yes	The instruction text shown with the challenge.
`request_type`	yes	`image_label_binary`, `image_label_area_select`, or `image_drag_drop`.
`tiles`	yes	One entry per image: its `task_key` and the image as `image` (base64) or `url`.
`entities`	drag only	The draggable pieces: `entity_id` and its image as base64 or url.
`examples`	if shown	Any reference images shown with the challenge.

Send images either as raw base64 in image, or as an url and xqroo fetches it. URLs are faster — send them straight from the challenge, promptly, before they expire.

Response

200 OK

{
  "ok": true,
  "answer": { "<task_key>": … },
  "confidence": 0.98,
  "ms": 41,
  "id": "rq_1a2b3c"
}

answer is shaped for the challenge type:

Classify (image_label_binary): a verdict per tile, "true" or "false".
Locate (image_label_area_select): per tile, a list of points as [x, y] in the tile's own pixels.
Place (image_drag_drop): for each draggable piece, the position to drop it on.

Only answered challenges are billed. If xqroo can't answer, ok is false with an error, and nothing is charged.

POST /report

Optional, and free. Tell xqroo whether an answer passed. Reports improve accuracy on the challenges you actually send.

POST https://api.xqroo.com/report

{ "id": "rq_1a2b3c", "correct": true }

Use the id from the solve response. Send it from the same key, right after you check the result.

GET /status

Returns the account for your key: plan, today's usage, allowance left, balance, and when it resets. The same numbers you see on your account.

Errors

Code	Meaning
`401`	Missing or unknown key.
`429`	Nothing left — today's allowance is used up and the balance is empty.
`502`	Temporary — retry the request.

Get a key

Pick a plan, pay the crypto invoice, and your key is issued on confirmation. See plans