SolveHub REST API Reference: Tasks, Prices, Balance, Webhooks

This document is based on the current HTTP routes, application services, and task parameter validation. The production base URL is https://www.tiam.codes, and all paths below are relative to it; the local default is http://127.0.0.1:8080, and production must use HTTPS. All keys, email addresses, and domains in the examples are placeholders. Response times use RFC 3339, and amounts are integer USD micro-USD (micros): 1 USD = 1,000,000 micros. Live values from GET /v1/prices are authoritative for prices, and the sale price is frozen for each task at creation time.

General Conventions

Regular API calls use Authorization: Bearer <API_KEY>; JSON write requests use Content-Type: application/json. The customer web portal uses the solvehub_portal cookie with HttpOnly and SameSite=Strict; non-GET/HEAD requests authenticated by cookie must include X-SolveHub-Portal: 1. Login, registration, and logout requests also require this header. Bearer takes precedence over the cookie: do not let the browser unintentionally attach an Authorization header for another Key.

Every response carries X-Request-ID, which support can use to locate an issue. Failure responses are usually {"error":"ERROR_CODE"}, not the success response format; 204 has no response body. The request body accepts only a single JSON object, and unknown top-level fields usually return 400 INVALID_JSON. JSON request bodies are limited to 1 MiB, except task creation and the compatibility endpoints, which allow up to 8 MiB.

API Key scopes are tasks (tasks, usage), billing (balance, ledger, recharge Keys, historical orders), and account (account profile, Key metadata, Webhooks, session list). Creating, modifying, or revoking Keys, changing the contact email, and ending sessions on other devices additionally require an email/password account session; even a Key with the account scope cannot perform these sensitive changes. Some grace endpoints accept expired Keys, such as balance, recharge Key redemption, renewal records, and support tickets; an expired Key cannot create tasks, nor can it authorize a paid renewal with its own credentials. A frozen account cannot run new tasks, redeem recharge Keys, or perform similar operations. Support tickets use the authenticated customer identity and have no separate scope.

The unauthenticated GET /healthz returns {"status":"ok"}, meaning the API process is alive; GET /readyz returns {"status":"ready"}, meaning the database and migration markers are available, and returns 503 DATABASE_UNAVAILABLE on failure. Neither endpoint guarantees that task processing capacity is available.

Identity and Sessions

Registration and binding flow: POST /v1/portal/register/email requests an email code → POST /v1/portal/register registers the email/password account with that code → POST /v1/portal/session/account logs in → POST /v1/portal/account/bind-key pastes the API Key issued by the operator, and the account then belongs to that Key's customer. One account corresponds to one customer and can manage that customer's multiple Keys; each customer can bind only one email account. While unbound, all endpoints other than session, security settings, and binding endpoints return 403 ACCOUNT_UNBOUND. Customers who already have a Key but no email account can still log in with the Key and bind an email on the "Security" page (see account/claim).

Passwords must be 12–128 Unicode characters, contain at least 6 distinct characters, and must not contain the email address; mixing in special characters is not required. The session view contains authMethod,sessionId,customerId,customerName,customerStatus,keyId,keyLabel,scopes,keyExpiresAt,keyExpired,expiresAt,idleTimeoutSeconds; authMethod is account for account sessions and api_key for Key sessions. Sessions expire 24 hours after sign-in. An account session is independent of any particular API Key; a Key session becomes invalid when that Key is revoked. A TOTP code cannot be reused within the same time step. Failed logins are limited per IP and per account; when you receive 429 LOGIN_THROTTLED, honor Retry-After. The login email of existing accounts is unverified by default and must be verified on the console "Security" page before self-service password recovery is possible. If you lose your authenticator, you can use a single-use recovery code to log in, disable 2FA, or reset your password together with an email code sent to the verified login email; if the recovery codes are also lost, contact an administrator for identity verification. Recovery codes are visible only when enabling or regenerating them, and should not be pasted into support tickets, chats, or logs.

Handling a leaked Key: If you still hold a password account session, use POST /v1/portal/keys/{id}/compromise (account scope) to revoke the leaked Key in an emergency; this endpoint can revoke the last Key, whereas the regular DELETE /v1/keys/{id} cannot. Then review GET /v1/portal/sessions, GET /v1/ledger, and the task list, revoke suspicious sessions, and create a replacement Key; if necessary, contact the operator to freeze the customer. An expired leaked Key can no longer pay for a renewal with its own credentials. A leaked Key that has not been revoked can still create tasks within its safety limits, so revoke it immediately once a leak is discovered. An attacker who holds only the leaked Key without an account session cannot call the emergency endpoint, but revocation propagation is affected by multi-instance caching, so you should still contact the operator as soon as possible.

New-user Trial Credit (Telegram Binding)

After registering an email/password account you can bind and verify one Telegram account under Console → Security → Bind Telegram. Once verified, the platform credits 0.10 USD of trial balance to your wallet in one go; the balance can be spent on the API without topping up.

Rules:

• Deduplication uses the numeric Telegram user_id: one Telegram account can bind only one SolveHub account, and one account can bind only one Telegram account.
• Binding cannot be undone: after verification, re-binding or registering again cannot claim the trial credit a second time.
• The bot replies in the console UI language: send {"locale":"zh|en|ja"} to bind; without it the Telegram client language is used, falling back to English.
• The trial balance never expires, but it only covers 1 concurrent task. Verification tightens max_active to 1 for that customer, so the next task can only be submitted after the previous one finishes. Any top-up (recharge code, Cregis deposit, settled order or positive adjustment) removes this system-managed limit and restores the default global concurrency; limits set manually by operations are left untouched.
• The credit is written as one credit ledger entry (note "New-user Telegram verification reward") with a unique reference, so repeated triggers never double-credit.
• An unbound account (status: unbound) becomes active after successful verification and can then create keys on the "API Key" page (or receive one from operations when customerKeyCreation is false).

Account and API Keys

The notification email and the login email are verified separately, and they do not share verification status even if the addresses are the same. An unverified notification email does not receive announcements, support ticket replies, Key reminders, or financial emails; business emails queued but not yet delivered to the old address are discarded after the address changes. Emails already sent cannot be recalled. Key-only customers must first bind an email and password themselves on the "Security" page using a Key with the account scope before they can set and verify a notification email.

APIKeyMeta contains keyId,label,hint,status,scopes,ipAllowlist,expiresAt,lastUsedAt,lastUsedIp,createdBy,createdAt,revokedAt,version,spendLimit24hMicros,spendFreezeHourMicros,spendFrozenAt,viewable; viewable means the server has stored the Key's encrypted plaintext, which can be viewed in an account session after second-factor verification; the plaintext is deleted as soon as the Key is revoked. expiresAt:null means the Key does not expire; the status is active, expired, or revoked. A non-empty spendFrozenAt means task creation is frozen because the cumulative holds within one hour exceeded the threshold. Both limits are positive integers in micro-USD (micros), up to 10,000 USD, and the one-hour threshold cannot exceed the 24-hour limit. Limits are counted conservatively in five-minute windows, which may add up to about five minutes of extra restriction; refunds after failure or cancellation do not release safety allowance, to prevent probing by repeatedly creating tasks and getting refunds. The request that triggers the freeze creates no task and does not touch the wallet; if a contact email is configured and the email service is available, a notification is sent, but the email must not be treated as a precondition for the freeze taking effect. Review tasks and the ledger before lifting a freeze. Labels are 1–100 characters; the IP allowlist accepts single addresses or CIDRs, up to 32 entries. Do not put API Keys in URLs, browser local storage, or support ticket bodies. A Key's account scope can read other Keys' metadata and manage Webhooks, but cannot issue or modify Keys; it is recommended to grant task processes only tasks.

Prices, Tasks, and Usage

GET /v1/prices requires no login and returns an object keyed by type; each entry contains available, plus the global priceMicros,currency when enabled or reason when disabled, and may also include version,updatedAt. available means the type is enabled in the price configuration and does not guarantee real-time processing capacity.

To learn your actual unit price, call the authenticated endpoint GET /v1/me/prices: its structure is the same as GET /v1/prices, and enabled types additionally include listPriceMicros (the public list price) and negotiated. When negotiated:true, priceMicros is your negotiated price; if the operator raises the procurement cost so that the negotiated price no longer applies, it automatically falls back to the public list price with negotiated:false. Disabled or unconfigured types are not quoted, even if a negotiated price exists. Quoting and task creation use the same rules, but prices may still change between the two requests; the final hold amount is the priceMicros in the creation response. version is the public price list version; changes to negotiated prices do not change it. POST /v1/tasks requires the tasks scope and an Idempotency-Key of 8–128 characters. Request example:

POST /v1/tasks HTTP/1.1
Authorization: Bearer sh_EXAMPLE
Content-Type: application/json
Idempotency-Key: order-12345-turnstile

{"type":"turnstile","task":{"websiteURL":"https://example.com","websiteKey":"SITE_KEY"}}

On success, a 202 task object is returned, such as {"taskId":"uuid","type":"turnstile","status":"queued","priceMicros":200,"traceId":"uuid","createdAt":"2026-10-02T00:00:00Z"}. The task object may also include solution, errorCode, and finishedAt. On failure, errorCode is TASK_FAILED or TASK_TIMEOUT; when uncertain (pending verification), it is TASK_UNCERTAIN. Results contain only the fields the customer needs to complete their business; for diagnostic information, contact support with the taskId and X-Request-ID. Task statuses: queued (cancellable), dispatching, processing, uncertain, completed, failed, cancelled. uncertain is not a terminal state: the platform temporarily cannot confirm the task's processing result or cost, and the amount remains on hold; keep querying the original task and provide the taskId to support, and do not create a replacement task with a different idempotency key. On completion, the frozen sale price is charged; on an explicit failure/cancellation, the hold is refunded.

A failed task may also include failureReason: a sanitized, length-limited explanation of an explicit upstream failure, for example IP Blocked (fake page). If no description was supplied, a stable failure code may be used instead. Use errorCode and status for control flow; treat failureReason as diagnostic text rather than an enum.

When the same customer reuses the same key with an identical request body within the task idempotency record retention period, the original task is returned without placing another hold; the same key with a different request returns 409 IDEMPOTENCY_CONFLICT. On a client network timeout or 5xx, first retry with the same key, record the returned taskId, and keep querying. The server periodically purges task idempotency records older than about 25 hours, so clients should store taskId long-term and must not rely on old idempotency keys for deduplication after purging. The task task must not exceed 7 MiB.

Task Types and Parameters

The outer type is required; the inner task.type may be omitted, but if provided it must match the outer one. All types reject unlisted fields; clientKey or any external service key must not be passed. URLs in the table below must be complete HTTP(S) URLs; the proxy port is a string, and the proxy protocol can only be http.

websiteURL is limited to 2048 bytes; websiteKey 256, proxyAddress 256, proxyPort 5, and the proxy username/password 256 each. captchaUrl and WafScriptUrl are limited to 4096; server-side validation is authoritative for the lengths of specific optional fields. The complex structure of funcaptcha must be submitted according to that type's validation rules; avoid mixing in fields from other CAPTCHA types.

Allowed fields for funcaptcha.challengeInfo: publicKey,site,surl,apiUrl,capiMode,styleTheme,locationHref,documentReferrer,documentTitle,iframeUrl,ancestorOrigins,treeIndex,treeStructure,languageEnabled,jsfEnabled,appMode,uniqueFingerprint,oldFingerprint,overrideFingerprint,syntheticFingerprint,randomProtoChain,randomVideoExtended,staticSpeechData,customTimezoneOffset,historyLength,noIframe,lowBandwidthMode,storageAccess,solvePOW,cookieTimestamp,disableArid,disableAridCookie,disableCookies,disableCookiesAnalytics,disableGT2Cookies,disableNavigatorCookies,powPause,exploitMode,skipHighWaves,submitAnswerPause,extraData. Allowed fields for browserInfo: Accept-Language,Cache,Cookie,DNT,HTTP3,Linux,Mac,Mobile,Safari,Sec-Ch-Ua,Sec-Ch-Ua-Platform,User-Agent,dataBrands,languages,randomTLS,userbrowser. Unlisted fields are rejected.

Balance and Top-ups

Top-ups are supported only via manual crediting by an administrator or via recharge Keys issued by an administrator and redeemed by the customer. The customer POST /v1/topup-orders always returns 410 TOPUP_ORDERS_DISABLED, and GET /v1/topup-orders/instructions returns 410 PAYMENT_METHODS_DISABLED. The platform has no public bank card, Alipay, WeChat, USDT, PayPal, or automatic payment API. The ledger and GET /v1/balance are authoritative for the balance; it is never increased based on client-side payment prompts.

Support Tickets and Announcements

Ticket contains id,customerId,customerName,category,subject,status,priority,assignedTo,version,createdAt,updatedAt,lastMessageAt,closedAt,messageCount; TicketMessage contains id,ticketId,authorKind,authorRef,body,internal,createdAt. Support tickets have a limit on open tickets (20) and a rate limit (10 created within 24 hours).

Creating a support ticket and customer replies may carry an Idempotency-Key (8–128 visible ASCII characters, no spaces; an invalid format returns 400 INVALID_IDEMPOTENCY_KEY). Keys are isolated per customer and valid for 24 hours: retrying the same request with the same key (leading/trailing whitespace does not matter) returns the current state of the original support ticket without creating a duplicate or appending a message, even if the ticket has been closed or the rate limit has been reached; using the same key for different content, a different support ticket, or across creation and reply returns 409 IDEMPOTENCY_CONFLICT. On network errors or 5xx, retry unchanged with the same key; each new support ticket or reply must use a new key. Without this header, the original behavior is kept and every request is written. Announcement bodies are displayed as plain text; email announcements are sent asynchronously, and the website endpoint does not indicate that the email has been delivered.

Webhook

The multi-endpoint interface is recommended, with up to 10 endpoints; the address must be a publicly accessible HTTPS 443 URL, with no credentials, query string, or fragment. The signingSecret from creation and secret rotation is returned only once.

Subscribable events: task.completed, task.failed, task.cancelled, task.uncertain, api_key.expiring, api_key.expired, api_key.renewed, balance.low, topup_order.paid, topup_order.rejected, topup_order.expired. The manual test event is webhook.test and requires no subscription. Some historical order events apply only to existing orders.

balance.low is generated when the available balance drops from at least 5 USD to below 5 USD due to a task hold, Key renewal, manual deduction, or reversal; the held balance does not count toward the available balance. The event payload contains availableMicros and thresholdMicros. A verified notification email also receives an email; an unverified email does not. If the balance is later topped back up to at least 5 USD, a new alert is generated when it drops below again. Historical balances already below the threshold do not trigger a backfilled alert when this feature is deployed.

The platform POSTs JSON to the endpoint with the headers X-SolveHub-Event-ID (decimal event ID), X-SolveHub-Event-Type, X-SolveHub-Timestamp (Unix seconds), and X-SolveHub-Signature. Example task event body: {"event":"task.completed","occurredAt":"2026-10-02T00:00:00Z","taskId":"uuid","type":"turnstile","status":"completed","traceId":"uuid","priceMicros":200}; test events contain event,testId,endpointId,occurredAt. The signature is sha256= followed by the hexadecimal value of HMAC-SHA256(signingSecret, timestamp + "." + raw request body bytes); during a rotation grace period the signature header may contain two comma-separated sha256= values, and verifying either one is sufficient. After reading the raw bytes, the receiver should check the time window, compare signatures in constant time, deduplicate by event ID, and then return 2xx quickly; non-2xx responses are retried, and deliveries may be duplicated or arrive late. The event payload is not the final basis for settlement; after receiving a task event, query GET /v1/tasks/{id}.

Compatibility Endpoints

POST /createTask, POST /getTaskResult, and POST /getBalance accept a clientKey JSON field; both business success and failure may return HTTP 200, so you must check errorId (0 success, 1 failure) and errorCode. createTask supports native types and the aliases ImageToTextTask, TurnstileTask, TurnstileTaskProxyless, TurnstileTaskProxyLess, AntiTurnstileTaskProxyLess.

Compatibility errors may be ERROR_KEY_DOES_NOT_EXIST, ERROR_KEY_DENIED_ACCESS, ERROR_IP_NOT_ALLOWED, ERROR_ACCOUNT_SUSPENDED, ERROR_BAD_PARAMETERS, ERROR_TASK_NOT_SUPPORTED, ERROR_NO_SLOT_AVAILABLE, ERROR_ZERO_BALANCE, ERROR_NO_SUCH_CAPCHA_ID, or ERROR_SERVICE_UNAVAILABLE. The compatibility creation endpoint has no idempotency key, so blindly retrying after a timeout may create another task and place another hold on the balance; new integrations should use /v1/tasks.

Minimal Integration Example

export SOLVEHUB_URL='https://www.tiam.codes'
export SOLVEHUB_API_KEY='sh_REPLACE_ME'
curl -sS -H "Authorization: Bearer $SOLVEHUB_API_KEY" "$SOLVEHUB_URL/v1/balance"
curl -sS -X POST "$SOLVEHUB_URL/v1/tasks" \
  -H "Authorization: Bearer $SOLVEHUB_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: your-order-12345' \
  -d '{"type":"turnstile","task":{"websiteURL":"https://example.com","websiteKey":"SITE_KEY"}}'

When integrating, save the taskId, idempotency key, and X-Request-ID. Do not submit full API Keys, recharge Keys, passwords, TOTP secrets, or raw proxy credentials in logs, screenshots, or support tickets.

DataDome challenge URL helper

POST /v1/datadome/build-url requires a valid Key with tasks scope and an active account. It returns synchronously, is free and creates no solving task. Send websiteURL (up to 2048 bytes) and at least one of body, location, or captchaUrl. body is captured HTML/JSON (up to 1 MiB); each URL field accepts up to 4096 bytes. A supplied captchaUrl takes precedence. Never provide credentials for an internal service.

curl -sS -X POST 'https://www.tiam.codes/v1/datadome/build-url' \
  -H 'Authorization: Bearer sh_REPLACE_ME' \
  -H 'Content-Type: application/json' \
  --data '{"websiteURL":"https://example.com/login","body":"{\"url\":\"https://geo.captcha-delivery.com/captcha/?cid=EXAMPLE\"}"}'

{"captchaUrl":"https://geo.captcha-delivery.com/captcha/?cid=EXAMPLE","challengeType":"captcha"}

Success returns captchaUrl,challengeType; pass the URL unchanged to a DataDome solving task. Errors: 400 INVALID_DATADOME_PAYLOAD, 422 DATADOME_CHALLENGE_NOT_FOUND, 503 DATADOME_BUILDER_UNAVAILABLE (retry with backoff), or 502 DATADOME_BUILDER_FAILED. Compatibility POST /buildDataDomeUrl takes a SolveHub clientKey in JSON and uses HTTP 200 with errorId/errorCode/errorDescription. The helper needs no Idempotency-Key; solving tasks retain their existing idempotency and billing rules.

See Supported User Agents for browser coverage and copyable UA examples. Processing soft windows start after task creation is confirmed: 240 seconds for DataDome and 210 seconds for PerimeterX.

The optional keyId query parameter on GET /v1/tasks and GET /v1/usage filters tasks for that key within the authenticated customer. Omitting it preserves aggregate usage across all keys. A task response may include keyId, an identifier rather than the secret; older tasks may omit it. GET /v1/ledger supports kind (credit,reserve,capture,refund,fee,reversal,adjustment) across the full history; retain the same kind when paging.