Private API · Reference

Build against the solver interface.

Create a task, poll its state, and retrieve the completed token through a compact JSON API designed for authorized enterprise integrations.

Base URL https://bruxsolver.org JSON requests Header authentication

POST /createTask
Reserve a solve task BOTH /getResult
Poll task state GET /balance
Read remaining solves

Getting started

Authentication

Every API endpoint requires the assigned key in the x-api-key request header. The homepage and this documentation page are the only public routes.

Required headerHTTP

x-api-key: YOUR_API_KEY
Content-Type: application/json

Inspect the JSON body. Application-level failures are returned with success: false. They currently use HTTP status 200, so HTTP status alone does not confirm success.

Tasks

POST

`/createTask`

Validates the configured target, reserves one balance unit, and creates a processing task. The returned task ID is used to poll for completion.

JSON body

Field	Requirement	Description
`proxy`	Optional	Optional proxy string accepted for client compatibility.
`sitekey`	Required	Must exactly match the configured test-space sitekey.
`href`	Required	Must exactly match the configured VFS login URL.
`rqdata`	Optional	Accepted for client compatibility.
`pow_type`	Optional	Accepted values are `hsw`, `hsj`, and `hsl`.
`sandbox`	Optional	Boolean option accepted for client compatibility.

Example request

Create an HSW taskcURL

curl -X POST "https://bruxsolver.org/createTask" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "sitekey": "9278ebd4-da60-402a-ac8a-e604bc4ac524",
    "href": "https://visa.vfsglobal.com/tur/tr/fra/login",
    "rqdata": "optional-rqdata",
    "pow_type": "hsw",
    "sandbox": true
  }'

Processing response

SuccessJSON

{
  "api_key_prefix": "abc123...",
  "remaining_solves": 2,
  "status": "processing",
  "success": true,
  "task_id": "0123456789abcdef0123456789abcdef",
  "useragent": "Mozilla/5.0 ...",
  "uuid": "0123456789abcdef0123456789abcdef"
}

Polling

GET · POST

`/getResult`

Returns the current task state. Use task_id or uuid as a query parameter for GET, or include either field in a JSON body for POST.

GET example

Poll by task IDcURL

curl "https://bruxsolver.org/getResult?task_id=0123456789abcdef0123456789abcdef" \
  -H "x-api-key: YOUR_API_KEY"

POST example

Poll by UUID aliascURL

curl -X POST "https://bruxsolver.org/getResult" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"uuid": "0123456789abcdef0123456789abcdef"}'

Still processing

PendingJSON

{
  "status": "processing",
  "success": true,
  "task_id": "0123456789abcdef0123456789abcdef",
  "uuid": "0123456789abcdef0123456789abcdef"
}

When complete, the response contains the token in both token and solution, together with elapsed time and remaining balance.

Account

GET

`/balance`

Returns the number of solve credits currently available to the configured API key.

RequestcURL

curl "https://bruxsolver.org/balance" \
  -H "x-api-key: YOUR_API_KEY"

ResponseJSON

{
  "api_key_prefix": "abc123...",
  "remaining_solves": 3,
  "success": true
}

Failure handling

Errors

Always branch on success and inspect error_code when it is false.

Error shapeJSON

{
  "error_code": "INSUFFICIENT_BALANCE",
  "message": "No solves remaining",
  "status": "failed",
  "success": false
}

Code	Meaning
`MISSING_API_KEY`	The `x-api-key` header was not supplied.
`INVALID_API_KEY`	The supplied key is not authorized.
`INVALID_REQUEST`	The request body is not a JSON object.
`INVALID_HREF`	The requested URL does not match the configured target.
`THREAD_LIMIT_REACHED`	The single task slot is already occupied.
`INSUFFICIENT_BALANCE`	No solve credits remain.
`MISSING_TASK_ID`	Neither `task_id` nor `uuid` was supplied.
`TASK_NOT_FOUND`	The task does not exist or has expired.

Operating contract

Limits and lifecycle

1 concurrent task

A processing task occupies the single available task slot until it reaches a final state.

15-minute retention

Tasks are removed after 15 minutes. Retrieve results before expiration.

Balance on acceptance

One solve is deducted when a valid task is accepted, not when its token is retrieved.

JSON contract

Read success, status, and error_code from every response.