Native REST v1

Own REST API (/v1)

Plain HTTP API: real status codes, integer micro-dollar amounts, idempotency header, long-polling. Errors have the body {"error": "<CODE>", "detail": "…"}: 400 bad parameters, 401 bad key, 402 zero balance, 403 host not served or account blocked, 404 unknown task, 429 rate limit or no free slot, 501 type not supported, 503 solver temporarily unavailable. A body that fails schema validation gets 422 with FastAPI's {"detail": [...]} format.

POST/v1/tasks

Headers: Authorization: Bearer <key>, optional Idempotency-Key: <uuid> (same key → identical task returned, no second charge).

Body Fields: type ("turnstile" | "cloudflare_challenge"), url, optional sitekey, action, cdata, user_agent, proxy: { scheme, host, port, username, password } — required for cloudflare_challenge, must be omitted for turnstile (rejected with 400), timeout_s (10–600, default 120, per attempt).

curl -X POST https://api.floweno.com/v1/tasks \
  -H "Authorization: Bearer flw_live_YOUR_API_KEY" \
  -H "Idempotency-Key: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "cloudflare_challenge",
    "url": "https://example.com/protected",
    "proxy": {
      "scheme": "http",
      "host": "203.0.113.10",
      "port": 8080,
      "username": "user",
      "password": "pwd"
    },
    "timeout_s": 120
  }'

Response (HTTP 201 Created):

{
  "task_id": "7f3c2a1e-9b4d-4c6a-8e21-5d0f3b9a7c14",
  "type": "cloudflare_challenge",
  "status": "queued",
  "cost_micro": 1300,          // reserved now, charged only on success
  "charged": false,
  "units": 1,
  "error_code": null,
  "progress": null,
  "result": null,
  "created_at": "2026-10-09T08:31:24.512Z",
  "finished_at": null
}

GET/v1/tasks/{task_id}?wait=0..60

Retrieve task status. The ?wait=0..60 query parameter supports HTTP long-polling: the server will hold the HTTP connection open up to N seconds until the task reaches done or failed, reducing network polling overhead.

// Example Response (HTTP 200 OK). "result" is the solver's record as is:
{
  "task_id": "7f3c2a1e-9b4d-4c6a-8e21-5d0f3b9a7c14",
  "type": "cloudflare_challenge",
  "status": "done",
  "cost_micro": 1300,
  "charged": true,
  "units": 1,
  "error_code": null,
  "progress": null,
  "result": {
    "solver": "nokk",                  // "nokk" or "chrome"
    "token": null,                     // Turnstile only
    "cf_clearance": "07fA81b...",
    "cookies": { "cf_clearance": "07fA81b...", "...": "..." },
    "user_agent": "Mozilla/5.0 ... Chrome/151.0.0.0 Safari/537.36",
    "domain": ".example.com",
    "expires": 1791600000,
    "binding": {
      "requires_same_exit_ip": true,
      "requires_ja3_match": true,
      "chrome_major": 151,             // 151 from nokk, 154 from Chrome
      "user_agent": "Mozilla/5.0 ... Chrome/151.0.0.0 Safari/537.36"
    }
    // plus informational fields: mode, url, proxy (no credentials), params, elapsed
  },
  "created_at": "2026-10-09T08:31:24.512Z",
  "finished_at": "2026-10-09T08:31:38.004Z"
}

GET/v1/balance

Returns integer micro-dollar account wallet status ($1.00 USD = 1,000,000 micro-dollars).

// Response (HTTP 200 OK):
{
  "balance_micro": 50000000,     // total balance ($50.00)
  "held_micro": 2600,            // reserved for 2 challenges in progress ($0.0026)
  "available_micro": 49997400    // available for new tasks
}