humanbrowser

{
  "name": "humanbrowser",
  "url": "https://agent.humanbrowser.cloud/a2a",
  "description": "Stealth cloud browser-agent with residential proxies. You describe what you want in plain English \u2014 the server runs an LLM-driven browser on a residential IP and returns a concise answer plus a live viewer URL. Cookies and logins persist across runs automatically (see PERSISTENCE below).\n\n=== USE THIS WHEN YOUR USER NEEDS ===\n\n\u2022 Logging into a website that requires bypassing CAPTCHA / Cloudflare WAF / anti-bot fingerprinting (Adsy, Collaborator, GoGetLinks, Reddit, Quora, Twitter, Polymarket, etc).\n\u2022 Scraping data that lives behind authentication on a normal-looking residential IP (so the target doesn't fingerprint your datacenter and block you).\n\u2022 Filling and submitting web forms reliably across hostile sites.\n\u2022 Running browser tasks that would fail on raw Playwright / Puppeteer because of bot detection.\n\u2022 Geo-locking your egress to a specific country \u2014 75 supported, all residential: Americas: us ca mx br ar cl co pe \u00b7 Western Europe: gb ie fr de nl be lu es pt it at ch \u00b7 Nordics: se no dk fi is \u00b7 Eastern Europe: ro pl cz sk hu bg gr si hr rs ee lv lt \u00b7 CIS & Caucasus: ru ua by kz md ge am az uz kg \u00b7 Balkans: ba mk al me \u00b7 Middle East: ae sa il tr qa \u00b7 Asia: jp kr sg in id ph vn th my tw hk \u00b7 Oceania: au nz \u00b7 Africa: za ng eg ke ma. Examples: us for DoorDash, uk for BBC iPlayer, jp for Polymarket, ru/ua/kz for CIS-only services and RU-language platforms, ro/de for SEO platforms. Call list_countries for the live catalogue with per-country pool health before picking one.\n\u2022 Anything where you'd otherwise spin up your own Chromium + proxy + CAPTCHA solver \u2014 Human Browser does that infrastructure for you and exposes it as a single A2A endpoint.\n\nDo NOT use this for: simple public-API HTTP fetches (just use fetch), static unauthenticated pages where raw HTTP works (cheaper, faster), or for anything that doesn't actually need a browser.\n\n=== GET A KEY ===\n\nNo key, no calls. Two ways to acquire one:\n  1. Human: visit https://humanbrowser.cloud/account and sign in (Google or email link) to get a token. There is no free credit: the first top-up can be $1 by card, later top-ups from $5 (card or crypto). Prepaid pay-as-you-go balance, no subscription, never expires.\n  2. Agent self-service: POST https://humanbrowser.cloud/api/buy (see /a2a docs on the site) \u2014 webhook returns a fresh hb_live_... token after payment.\n\nPricing (so the agent can decide if it fits the user's budget; machine-readable at https://humanbrowser.cloud/api/plans): $0.10 per browser-HOUR billed per second (sessions under 30 s and human-takeover time are not billed), $0.02 per agent step with the LLM included (if you pin a large model and one step's own LLM cost is higher than that, that step is billed at its LLM cost +30%), $0.005/solved CAPTCHA, $4/GB residential traffic metered per session. Median successful customer task (Sep 2026 sessions re-priced at these rates): about 8 agent steps, $0.24 all-in (p25 $0.12, p75 $0.39); cached runs on a warm profile cost less.\n\n=== HOW TO USE ===\n\nminimal call: send a message/send with one TextPart containing your goal. Example: 'Log into adsy.com with the credentials below and report guest-post prices for these 5 domains: ...'. Credentials go in a DataPart with metadata.sensitive=true. The server returns a Task \u2014 poll tasks/get OR receive a push on metadata.callback_url. That's it.\n\n=== VERBATIM PAYLOADS \u2014 when the user gave you exact text to paste ===\n\nWHEN to use: any time your user supplied exact text that must land in a form character-for-character \u2014 pitch responses, application answers, comment text, code snippets, anything where paraphrasing would corrupt the intent. Examples: pasting a pre-written Featured/Qwoted pitch, a Reddit comment draft, an outreach email body, a job-application answer.\n\nHOW: wrap the text in <verbatim>\u2026</verbatim> markers inside your TextPart goal. Optionally name it: <verbatim name=\"my_pitch\">\u2026</verbatim> (useful when you have multiple drafts in one task). Example goal:\n\n  Log into featured.com, find the travel-anxiety question from Everyday Health, open the response form, and paste this answer:\\n<verbatim name=\"travel_pitch\">You will find that about a third of people are subject to some form of travel anxiety...</verbatim>\\nThen click Submit.\n\nWhat the server does on receipt: extracts each <verbatim>\u2026</verbatim> block, stashes the real text behind a placeholder (`<draft_1>`, `<draft_2>`, \u2026 or `<your_name>`), and replaces the marker in the goal with that placeholder. The LLM driving the browser sees ONLY the placeholder \u2014 it has zero visibility into the real content, so it cannot paraphrase, summarise, condense, expand, translate, or 'improve' it. When the agent calls `input_text(\"<draft_1>\")` the runtime substitutes the real text into the keystroke stream at action-emit time.\n\nWHY this matters: small/cheap LLMs (gpt-5.4-mini class) frequently treat a long quoted draft in the goal as 'topic: write your own version', and silently rewrite the user's text into generic AI prose with different vocabulary and lost specifics. This mechanism removes that failure mode entirely.\n\nIf you have many drafts to paste in one task, name them; multiple `<verbatim>` blocks in one goal each get their own placeholder. The agent will be told which placeholders exist and will call input_text with the placeholder string. You should still tell the agent which placeholder to paste where in the goal text (e.g. 'paste <draft_1> into the answer textarea').\n\n=== WHAT THE SERVER HANDLES FOR YOU (do NOT pass knobs for these) ===\n\n\u2022 CAPTCHA solving (recaptcha v2/v3, hCaptcha, Turnstile, Cloudflare WAF) \u2014 automatic via CapSolver + 2captcha race.\n\u2022 Cloudflare challenge bypass \u2014 automatic engine selection per site.\n\u2022 Anti-bot fingerprint \u2014 automatic stealth profile.\n\u2022 Residential proxy stickiness \u2014 automatic per-session sticky IP.\n\u2022 Engine choice (patchright/cloak), execution mode (fast/stealth), LLM model, warmup \u2014 automatic from goal + site-rules.\n\u2022 Profile / cookie persistence \u2014 automatic from goal domain (see below).\n\u2022 Files IN: attach an A2A FilePart (uri or base64 bytes; images, pdf, mp4, anything up to 8 MB) next to your TextPart and the agent can upload it into any file input; or name a public URL in the goal and the agent fetches it itself (fetch_file). Files OUT: anything the run downloads or saves comes back as kind:file parts on the final artifact with a URL behind the session key, and as metadata.outcome.produced_files.\n\u2022 Clicks that React ignores (Facebook / Meta Business Suite / Instagram div[role=button]): when a click changes nothing on the page, the runner automatically redoes it as a real OS-level mouse click at the element and tells the model whether the page moved. You do not need to ask for it. Drag gestures (sliders, cover-photo repositioning) are a real pointer drag too (drag_at_xy).\n\nYou will NOT find these in the message/send metadata schema. If you think you need them you are usually wrong \u2014 call without them first; the right setting is picked from your goal text. (For genuine power-user overrides, see ADVANCED at the bottom.)\n\n=== MULTIPLE TASKS ON ONE SESSION (queue) ===\n\nA session accepts more work while it is already busy. Send another task and it joins that\nsession's queue, then runs in the SAME browser the moment the current one finishes \u2014 still\nlogged in, cookies and all. Previously a second task was refused with 409 busy, so callers\nhad to start a fresh browser and log in again for every step of a multi-step job.\n\nUse it by addressing the live session (force_new:false to reuse rather than spawn). A queued\ntask answers 202 with {queued:true, task_id, position, queue_depth}; /status reports\nqueue_depth and the goals waiting. Up to 20 tasks may wait.\n\nIMPORTANT if you watch the WebSocket: the event stream belongs to the SESSION, not to your\ntask, so once a session holds more than one task you will see the other one's events too.\nEvery event carries task_id \u2014 match it against the task_id you were given and ignore the\nrest, or another task's `done` will look like your own answer. The task_id is issued when\nthe task is ACCEPTED and does not change when it later starts, so it is valid to filter on\nfrom the moment you receive it. Events with no task_id are session-level (meta,\nrouter_decision) and apply to everyone. While your task is still waiting it emits a\ntask_waiting heartbeat every 20s with its current position: that is how you tell queued\nfrom hung, and it keeps the connection from being reaped as idle.\n\npriority:\"high\" puts a task at the FRONT of the waiting queue. It does not interrupt the\nrunning task \u2014 stopping a browser mid-login loses the login, which is the failure this\nwhole mechanism exists to avoid. High priority means \"next\", not \"now\".\n\nSessions are REUSED by default: consecutive tasks on the same profile land in the same\nbrowser and inherit its logins, which is what you want for log in -> navigate -> extract.\nDifferent sites get different profiles and therefore still run in parallel; what serialises\nis several tasks on ONE identity, since a session runs its queue one at a time. Pass\nforce_new:true for a fresh isolated browser (a second identity on the same site, or work\nthat must not touch the saved profile).\n\n=== THE SITE MAY ALREADY HAVE A KNOWN API (ask before you click) ===\n\nWhile your sessions drive a site, the server records the internal API that site's own\ninterface calls. If you have worked on a site before, that surface may already be known \u2014 and\ncalling it is faster and far more reliable than clicking through a heavy admin UI, where a\nmis-aimed click can act on the wrong record.\n\nCall actions/list_learned_apis (optionally {\"domain\":\"example.com\"}) BEFORE planning a long\nsequence of clicks on a familiar site. You get each endpoint's method, path, whether it reads\nor mutates, how often it was seen, and the request/response shape needed to build a call.\n\nYou only ever receive what YOUR OWN sessions produced \u2014 the account is taken from your token,\nthere is no parameter to request another one, and nothing another customer's sessions learned\nis reachable. No credentials are returned and none are needed: you keep driving your own\nsession, which is already authenticated, so the call is made as you.\n\nTwo rules worth respecting. Recorded request bodies are not handed back, because they contain\nlive identifiers from earlier runs \u2014 build calls from the shapes instead. And for anything\nthat mutates, confirm the target by ID and show what you intend to send before sending it: an\nAPI write bypasses every confirmation the UI would have given you.\n\n=== PERSISTENCE (automatic) ===\n\nThe server canonicalises a profile from the first domain in your goal: 'collaborator.pro' \u2192 profile 'collaborator', 'cp.adsy.com' \u2192 'adsy', 'gogetlinks.net' \u2192 'gogetlinks'. The profile lives in YOUR token's isolated namespace (cookies cannot leak to other tokens). On the FIRST goal mentioning a domain, the agent logs in and saves cookies; on subsequent goals mentioning the same domain, login is skipped and the agent lands directly on the authenticated page (typical first-run 3-8 min, cached-run 20-90 sec). Response includes metadata.profile so you can see exactly which profile was chosen. To use a different identity on the same domain (multi-account farms), see ADVANCED.\n\nWHAT PERSISTS across tasks on the same profile: HTTP cookies (per-row merged into the profile's master Chromium UserDataDir on every successful task \u2014 concurrent logins for the same site coexist without one wiping the others), session cookies (captured from the live browser via storageState at the end of each task and re-injected on the next launch \u2014 these are held in memory and never written to disk by Chromium, so this is the only way logins like Yandex's Session_id survive at all), saved logins, history, and Preferences. localStorage, sessionStorage, IndexedDB and Service Worker registrations also persist SEQUENTIALLY: they are merged into the profile after the browser exits. WHAT DOES NOT PERSIST across PARALLEL tasks: localStorage, sessionStorage, IndexedDB and Service Worker registrations \u2014 these are Chromium LevelDB stores which OS-level forbid concurrent writers, so two tasks running at the same moment on one profile each get their own copy and only the last to finish is kept. Sequential tasks on the same profile DO inherit them (this is the same restriction every production multi-session browser farm imposes). For COOKIE-based auth (the vast majority of sites \u2014 Adsy, GoGetLinks, Collaborator, Reddit, Quora, Twitter, most SaaS dashboards) parallel tasks work seamlessly. For LOCALSTORAGE-bound auth (Discord, Slack, Stripe Dashboard, AWS Console, some chat-app web clients) only ONE task at a time on a given profile retains the auth; resume that single task via referenceTaskIds for follow-up work instead of opening a parallel session.\n\nPARALLELISM: send N tasks on the same profile and the server allocates N independent Chromium sessions, each cloned from the warm master profile. Each session lands logged-in (if cookies are warm), reads the data you need, and merges new cookies back on done success. Failed/canceled tasks do NOT pollute master cookies. Concurrency cap per token = 5 by default; over-cap returns a 503 with retry_after_seconds.\n\n=== VIEWER URL ===\n\nEvery response includes a live viewer URL of the form https://humanbrowser.cloud/a/s_<id>?k=<key>, returned as metadata.viewer_url and as the first artifact. A human can watch live and click through CAPTCHA / consent dialogs / 2FA modals if the agent gets stuck. Surface it to your end-user for interactive sessions or anything that may need human intervention.\n\n=== HUMAN-IN-THE-LOOP (input-required) ===\n\nWhen the agent needs something it can't derive autonomously (OTP code from an email inbox, magic-link URL, a credential you didn't pre-provide), it pauses with state=input-required and final=true. The SSE stream closes per A2A 1.0 spec; the task remains in the registry. Resume by sending a fresh message/send with message.referenceTaskIds=[taskId] and message.metadata.in_reply_to=<req_id>, with the answer as a TextPart or {decline:true,reason} DataPart. Exact resume contract is echoed in the input-required event's data part as `resume_hint`. While paused, a human operator can also answer directly from the viewer modal \u2014 first writer wins. Server-side timeout (default 300s, max 1800s) auto-declines. The agent asks ONCE and blocks; decline/timeout is terminal \u2014 no spam follow-ups.\n\n=== MOBILE UA ===\n\nFor mobile-only flows (Instagram webviews, TikTok login, mobile-specific layouts) pass metadata.mobile_ua=true on message/send. Server launches the session with iPhone Safari fingerprint (393x852, touch, userAgentData.mobile=true). Default is desktop Chrome. Fixed at spawn time.\n\n=== HOW TO RUN A TASK (the normal loop) ===\n\n1. POST /a2a message/send with your goal in plain language. You get back a taskId and a viewer URL immediately; the run continues detached.\n2. Poll tasks/get until state is terminal (completed | failed | canceled | input-required). While state=working the task IS running \u2014 do not narrate failure.\n3. On input-required, the agent is blocked on a human (2FA code, a decision). Answer via message/send with the same taskId.\n4. Read the result. On failed, read metadata.postmortem before deciding whether to retry.\n\nYou do NOT need to choose an engine, a model, a proxy country or a mode. The server routes from the goal and per-site rules. Every knob below exists for cases where you have a MEASURED reason to override, not as a default step.\n\n=== WHEN SOMETHING LOOKS BROKEN \u2014 DIAGNOSE, DO NOT GUESS ===\n\nIf a page looks empty, sits on a spinner, shows a loading state that never resolves, or a click appears to do nothing: call actions/get_page_diagnostics with your taskId BEFORE concluding anything and before retrying.\n\nIt answers what is actually wrong, as data rather than narrative:\n  verdict=ok               \u2014 the page rendered and requests are healthy. Whatever you are stuck on is NOT infrastructure; re-read the page.\n  verdict=degraded         \u2014 the page rendered but some assets failed. Usually a dead third-party script; proceed, the site is usable.\n  verdict=page_did_not_start \u2014 assets loaded but the app never rendered. Usually the SITE (its own JS or an API call). Waiting longer or reloading once is reasonable; a third attempt is not.\n  verdict=broken_by_us     \u2014 OUR browser or proxy is at fault. Retrying the same way will NOT help. Change something (proxy country via actions/switch_proxy_country, or report it) \u2014 do not burn steps repeating the action.\n\nIt also returns subresource counts by type and error code, and console errors, with URLs reduced to origin+path.\n\nDo NOT attribute a failure to bot protection, CAPTCHA or the site blocking you unless the diagnostics support it. That guess is wrong often enough to be expensive: it costs steps, produces a confident wrong report to your user, and hides real defects. \"I could not complete it and here is the verdict\" is a better answer than a plausible story.\n\n=== SEEING WHAT HAPPENED \u2014 SCREENSHOTS ===\n\nEvery session captures a frame per step and you can ask for them: actions/get_screenshots with your taskId. It returns LINKS, never image bytes \u2014 one URL per frame, plus the action and the page URL that produced it. Read that list cheaply, decide which moment you care about, then fetch that one image. Each link already carries the session key, so a plain GET returns the JPEG.\n\nHighlights are the default and are almost always what you want: the frames where something actually changed \u2014 first sight of the page, each navigation, form submits, anything that errored, and the final state. Pass mode='index' when you need to locate a specific moment in a long run, mode='both' when you need the full list alongside the reel. Do NOT pull every step. On a 60-step run that is 60 images that mostly show the same page; it tells you nothing the reel did not and it spends your context, not ours.\n\nThe reply also carries live_url \u2014 the page as it looks right now, useful while state=working \u2014 and video_url, an mp4 assembled on demand from the frames. The video is for handing a human a replay; do not feed it to a model.\n\nScreenshots pair with diagnostics rather than replacing them: get_page_diagnostics tells you WHY a page is broken, screenshots show you WHAT the agent was looking at when it went wrong. Reading frames is observation-only \u2014 it does not refresh session activity, so looking cannot keep an idle session alive or billing.\n\nOne caution: a frame shows whatever was on screen, including a typed password or a customer's personal data, and unlike text it cannot be scrubbed. Treat these links exactly like the viewer URL.\n\n=== CHOOSING (only with a reason) ===\n\nCountries \u2014 call actions/list_countries for the live catalogue (75 countries, all residential, incl. the full CIS and Caucasus). Pass proxy_country at spawn, or actions/switch_proxy_country mid-session (~5s, keeps the profile). Use when a site geo-blocks or an account is region-locked.\n\nModels \u2014 call actions/list_models. Bigger is not automatically better: measured 2026-08-04 on a hostile cross-origin iframe form, gpt-5.6-sol and the cheap default finished in the same number of steps. Pin one only when you have measured a difference on YOUR task.\n\nEngines \u2014 call actions/list_engines. Note that the remote-cdp engine enforces third-party robots.txt policy and will refuse some URLs (e.g. reddit.com/login) with a \"Requested URL is restricted\" error; that is the engine, not the site being down \u2014 retry with engine='patchright'.\n\n=== REPORTING CONTRACT \u2014 READ BEFORE RELAYING TO YOUR USER ===\n\nA task is one of: working | submitted | input-required | completed | failed | canceled. ONLY the last four are terminal. While state=working, the task IS still running \u2014 do NOT tell your user it failed, do NOT generate a 'probably stuck on CAPTCHA' narrative; poll tasks/get and wait for a terminal state, or use metadata.callback_url for push delivery. Expected wall-clock duration: first-run authenticated tasks on hostile sites (Cloudflare/recaptcha-gated) 3\u20138 minutes; cached subsequent runs 20\u201390 seconds.\n\nstatus.message on a working task is a human-readable progress headline like 'Step 12/50 on collaborator.pro \u2014 Submit the goodmenproject.com search'. Quote it verbatim to your user; do not paraphrase or interpret.\n\nOn terminal=failed, tasks/get attaches metadata.postmortem ({root_cause_category, observed_blockers, working_strategies, retry_recommendation}) within ~30 sec \u2014 quote those FACTS instead of inventing failure modes. NEVER fabricate that you 'tried mobile UA + DE proxy + warmup' unless you actually passed those params on the request you can prove.\n\n=== MCP REMOTE ENDPOINT (alternative transport for Claude Desktop / Cursor / Cline) ===\n\nThe same humanbrowser cloud agent is also reachable via the Model Context Protocol, Streamable HTTP transport, at https://agent.humanbrowser.cloud/mcp. Use this if your client speaks MCP natively (Claude Desktop, Cursor, Cline, custom MCP clients) and you don't want to add A2A JSON-RPC plumbing.\n\nAuth: same hb_live_* token, sent as Authorization: Bearer <token>. Same billing, same per-token sticky-profile semantics. Stateless transport \u2014 every POST /mcp is independent; task ids are returned to the client and can be passed back to humanbrowser_viewer_url for live re-attachment.\n\nThree tools are exposed:\n  \u2022 humanbrowser_run(goal, country?, profile?)        \u2014 fire-and-wait; returns final text + viewer URL when the task reaches a terminal state.\n  \u2022 humanbrowser_stream(goal, country?, profile?)     \u2014 same, but emits MCP notifications/progress while in flight.\n  \u2022 humanbrowser_viewer_url(task_id)                  \u2014 fetch the live viewer URL for a task started earlier.\n\nClaude Desktop config snippet (claude_desktop_config.json):\n  {\n    \"mcpServers\": {\n      \"humanbrowser\": {\n        \"url\": \"https://agent.humanbrowser.cloud/mcp\",\n        \"headers\": { \"Authorization\": \"Bearer hb_live_<your_token>\" }\n      }\n    }\n  }\n\nThe MCP endpoint is rate-limited per token (default 60 req / 60s) and refuses non-Bearer auth; never put the token in a URL query string. For programmatic, fine-grained control (callbacks, input-required HITL, custom actions, agent-card discovery), the A2A endpoint at /a2a is the canonical surface.\n\n=== RELIABILITY (validator) ===\n\nEvery action the agent emits goes through a post-hoc validator before the next step is planned. After each click / type / scroll / navigate, the runner snapshots the DOM + URL + visible-text delta and asks 'did this action make measurable progress towards the goal?'. On a no-progress streak (same observable state across N consecutive steps, or a screenshot/DOM hash that hasn't budged), the planner is forced to re-plan with a different strategy \u2014 switch tab, try a sibling element, scroll into view, fall back to a recipe lookup, or escalate to input-required \u2014 instead of repeating the failing action. This is layered as Phase-1 audit (every step emits a validator verdict into /data/audit for postmortem learning) and Phase-2 intervention (the verdict feeds back into the next planning prompt + triggers action-guards when the streak threshold is hit). Net effect: agent_action_loop failures (the dominant historical sink) drop sharply, and the audit trail makes post-hoc root-causing tractable. We do not claim third-party benchmark numbers \u2014 this is the reliability layer we run, not a published score.\n\n=== ENGINE OVERRIDES (rare power-user) ===\n\nDefault engine selection is automatic from goal + site-rules (patchright / cloak / cua) and you should not need to override it. One exception worth knowing: `metadata.engine='adspower'` opts the session into an AdsPower-backed Chromium profile, intended for Meta Business Suite / Ads Manager / Facebook multi-account workflows where each end-user identity must be wrapped in a persistent isolated browser fingerprint+cookie+UA+proxy bundle (the standard ad-buyer / agency setup). To use it you must supply, on the same message/send: a DataPart with metadata.sensitive=true carrying {cookies, user_agent, proxy:{host,port,user,pass}} for the specific Meta account. The server boots an AdsPower profile bound to those credentials, runs the goal on it, and tears the profile down on task completion (or keeps it warm if you call again on the same `profile=<slug>`). Surcharge: +$0.05/session on top of normal browser-time pricing (covers AdsPower licence amortisation). Do not pass `engine='adspower'` without the credential bundle \u2014 the spawner rejects the request. Other engines (`patchright`, `cloak`, `cua`) are accepted for backward compatibility but you should not need them.\n\n=== ADVANCED (rarely needed) ===\n\nPower-user overrides on message/send.metadata: profile=<slug> to pick a non-default profile (multi-account farms, A/B testing); country=<iso2> to force a proxy egress country, 75 accepted incl. the full CIS (ru ua by kz md ge am az uz kg) \u2014 geo-blocked sites like BBC iPlayer\u2192uk, Polymarket\u2192jp, RU-only services\u2192ru; callback_url=<https://...> for push delivery of the terminal task envelope instead of polling. Other knobs (mode/engine/model/warmup/proxy) are accepted for backward compatibility but you should not need them \u2014 let the server choose.\n\nHOW TO CALL THESE: the JSON-RPC method is \"actions/<name>\", NOT the bare name. e.g. {\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"actions/list_countries\",\"params\":{}} \u2014 calling \"list_countries\" without the actions/ prefix returns -32601 Method not found. Same POST /a2a endpoint and Bearer token as message/send.\n",
  "version": "5.1.0",
  "documentationUrl": "https://humanbrowser.cloud/a2a",
  "iconUrl": "https://humanbrowser.cloud/favicon.ico",
  "defaultInputModes": [
    "text/plain",
    "application/json",
    "image/png",
    "image/jpeg",
    "image/webp",
    "image/gif",
    "application/pdf",
    "video/mp4",
    "application/octet-stream"
  ],
  "defaultOutputModes": [
    "text/plain",
    "application/json"
  ],
  "skills": [
    {
      "id": "browser_task",
      "name": "Browser Task",
      "description": "Execute a free-form natural-language web automation task. The agent navigates, clicks, fills forms, scrolls and reads pages on a stealth browser with a residential IP. Returns natural-language answer + structured findings. The response includes a live viewer URL (viewer_url metadata + first artifact) at https://humanbrowser.cloud/a/s_<id>?k=...; surface it to the end user when human intervention may be useful.",
      "tags": [
        "browser",
        "automation",
        "scraping",
        "navigation",
        "stealth"
      ],
      "examples": [
        "Find the cheapest flight from Bangkok to Tokyo next weekend on skyscanner.com",
        "Open polymarket.com and report current odds on the top US politics market",
        "Visit reddit.com/r/programming and list the top 5 post titles"
      ],
      "inputModes": [
        "text/plain",
        "application/json"
      ],
      "outputModes": [
        "text/plain",
        "application/json"
      ]
    },
    {
      "id": "login_and_scrape",
      "name": "Login and Scrape",
      "description": "Login to a website using provided credentials (TextPart + DataPart sensitive=true with {login,password,totp?}), then perform a scraping/data-extraction task on the authenticated session. Credentials are injected at execution time and never echoed in artifacts or logs. Login flows often need human intervention (CAPTCHA, 2FA, device-trust prompts), so relaying the response's viewer URL to the end user is typically helpful for this skill.",
      "tags": [
        "browser",
        "login",
        "scraping",
        "authenticated"
      ],
      "examples": [
        "Login to quora.com with the provided credentials and list questions in my feed",
        "Login to reddit.com and read my notifications inbox"
      ],
      "inputModes": [
        "text/plain",
        "application/json"
      ],
      "outputModes": [
        "text/plain",
        "application/json"
      ]
    },
    {
      "id": "meta_business_workflow",
      "name": "Meta Business Workflow",
      "description": "Drive Meta Business Suite / Facebook Ads Manager / Meta-owned web properties on behalf of a specific Meta account, using customer-supplied cookies+proxy+UA bundled into a persistent AdsPower-backed Chromium profile. Use this when the goal requires touching an authenticated Meta surface (pulling campaign performance, dispatching ad creation, reading Page inbox, exporting audience reports) and the end-user has a Meta account they already operate manually. Credentials go in a DataPart with metadata.sensitive=true carrying {cookies, user_agent, proxy:{host,port,user,pass}}; on message/send pass metadata.engine='adspower' and metadata.profile=<account_slug> so the same fingerprint is reused across follow-up tasks. Surcharge: +$0.05/session. Login flows on Meta routinely trip 2FA / checkpoint / device-trust prompts, so relaying the response viewer URL to the end user is typically helpful. Since 2026-09-07: Meta's div[role=button] controls that ignored synthetic clicks (Create a business portfolio, Save changes, Post, I accept) are clicked with a real OS mouse automatically when the first click changes nothing; avatar/cover uploads take an attached FilePart or a public URL; cover repositioning uses a real drag. A named profile (metadata.profile) keeps the Facebook login between tasks \u2014 do not pass force_new for follow-up work on the same account.",
      "tags": [
        "browser",
        "meta",
        "facebook",
        "ads-manager",
        "business-suite",
        "multi-account",
        "adspower"
      ],
      "examples": [
        "Open Meta Ads Manager for the supplied account and report last-7-day spend + CPM per active campaign",
        "In Meta Business Suite, read unread Page inbox messages for the supplied account and summarise them",
        "Duplicate the top-performing ad set in campaign <id> with budget +20%, paused"
      ],
      "inputModes": [
        "text/plain",
        "application/json"
      ],
      "outputModes": [
        "text/plain",
        "application/json"
      ]
    },
    {
      "id": "fill_form",
      "name": "Fill Form",
      "description": "Open a URL and fill the form with the provided structured data (DataPart with field map). Submit and report the resulting URL/message. The response includes a viewer URL \u2014 useful to relay if a field may need human input (CAPTCHA, validation popups).",
      "tags": [
        "browser",
        "form",
        "submit"
      ],
      "examples": [
        "Open https://example.com/contact and submit { name, email, message }"
      ],
      "inputModes": [
        "text/plain",
        "application/json"
      ],
      "outputModes": [
        "text/plain",
        "application/json"
      ]
    },
    {
      "id": "scrape_url",
      "name": "Scrape URL",
      "description": "URL in, structured data + clean text out. Send a TextPart of the form 'Scrape <url> and return {fields...}' or 'Extract product name, price and availability from <url>'. The agent renders the page in real Chromium (JS-executed, cookies live, residential IP), extracts the requested fields, and returns them as JSON in artifacts[0].data. Use for pages that a plain HTTP fetch cannot render (SPAs, JS-heavy dashboards, login-walled content, geo-restricted views). For bulk static-content ingest at 100k+ pages/month a dedicated scraping API (Firecrawl-class) is typically cheaper per page \u2014 HB is the right fit when the URL sits behind auth, geo-block, or an anti-bot wall (Cloudflare Managed Challenge / PerimeterX / DataDome / Turnstile).",
      "tags": [
        "browser",
        "scraping",
        "url-to-json",
        "structured-extraction"
      ],
      "examples": [
        "Scrape https://example.com/product/123 and return {name, price, in_stock, rating}",
        "Extract the article title, author, date, and body text from https://blog.example.com/post-slug",
        "Return the top-10 job listings visible on https://careers.example.com/search?q=engineer as a JSON array"
      ],
      "inputModes": [
        "text/plain",
        "application/json"
      ],
      "outputModes": [
        "text/plain",
        "application/json"
      ]
    },
    {
      "id": "relay_reverse_api",
      "name": "Relay (reverse-API)",
      "description": "Route the task through a pre-mapped reverse-API recipe instead of driving a browser. When the target domain is in our recipe catalog (property portals \u2014 dotproperty, renthub, fazwaz, hipflat; hotel aggregators \u2014 agoda, booking, airbnb; marketplaces \u2014 kaidee; plus authenticated dashboards we've mapped), we call the site's own JSON/GraphQL endpoints directly with cookies from the profile pool. ~$0.0001 per call vs $0.005-0.02 per browser task, 10x-30x faster, zero captcha exposure. Pass metadata.engine='relay' on message/send. If the domain has no recipe, server returns a 404 with hint {engine:'browser'} \u2014 retry without the engine override. Discover mapped domains via GET /relay/recipes.",
      "tags": [
        "reverse-api",
        "relay",
        "fast-path",
        "no-browser",
        "cost-optimized"
      ],
      "examples": [
        "engine=relay: List 20 rentals on Renthub for Sukhumvit district under 30000 THB/month",
        "engine=relay: Fetch DotProperty listing details for URL https://dotproperty.co.th/en/property/123456",
        "engine=relay: Return current price for Agoda cityId 15843 checkin 2026-08-01 checkout 2026-08-03 room=1 pax=2"
      ],
      "inputModes": [
        "text/plain",
        "application/json"
      ],
      "outputModes": [
        "application/json"
      ]
    },
    {
      "id": "hostile_site_solver",
      "name": "Hostile Site Solver",
      "description": "The task explicitly targets a site protected by an interactive anti-bot wall \u2014 Cloudflare Managed Challenge, PerimeterX press-and-hold, DataDome, Cloudflare Turnstile, Akamai Bot Manager, or Kasada. Pass metadata.engine='cua' (or leave unset for auto-router). The server picks the execution path that historically defeats that vendor: CDP-Patches + human-motion CDP input (patchright fingerprints leak too many CDP signals for these targets), plus a Computer-Use-Agent path (xdotool + scrot on Xvfb driving real Chromium) for canvas-heavy challenges. Interactive challenge solving billed at $0.005/solve on success only \u2014 no charge if the site accepts the pattern without a challenge. Typical cost $0.13-$0.30 per successful task on hostile sites vs the $0.05 baseline. Use this skill when you know the target site is hostile (extraction APIs like Firecrawl's Stealth Mode $0.05/page often fail on these).",
      "tags": [
        "anti-bot",
        "cloudflare",
        "turnstile",
        "perimeterx",
        "datadome",
        "cua",
        "hard-target"
      ],
      "examples": [
        "Search for 'senior software engineer' on linkedin.com/jobs (US) and return top 10 results (hostile: LinkedIn bot detection)",
        "Fetch product listing from etsy.com/shop/StoreName sorted by newest \u2014 full titles, prices, thumbnails (hostile: PerimeterX press-and-hold)",
        "Open realtor.com and return top-20 listings for zip 90210 sorted by price (hostile: DataDome managed challenge)"
      ],
      "inputModes": [
        "text/plain",
        "application/json"
      ],
      "outputModes": [
        "text/plain",
        "application/json"
      ]
    },
    {
      "id": "email_verified_signup",
      "name": "Email-Verified Signup",
      "description": "Fully-autonomous signup on sites that require Cloudflare Turnstile + email OTP verification (Hunter.io, Apollo.io, ZeroBounce, Findymail, Snov, most modern SaaS with double opt-in). Requires a DataPart with metadata.sensitive=true carrying {email, password, imap:{host,port,user,pass}} \u2014 the agent registers, solves Turnstile via CapSolver/2captcha race, polls the mailbox via IMAP for the verification email, extracts the OTP or magic link (context-aware \u2014 avoids grabbing CSS hex codes or unrelated 6-digit strings), completes verification, and returns the resulting API key / dashboard URL / account_id as an artifact. ~5 minutes end-to-end, ~$0.16 per successful signup ($0.06 solver + $0.10 LLM). See humanbrowser.cloud/blog/turnstile-otp-fully-unattended for the technical walkthrough.",
      "tags": [
        "signup",
        "onboarding",
        "email-otp",
        "turnstile",
        "hunter",
        "apollo",
        "zerobounce"
      ],
      "examples": [
        "Sign up to hunter.io with the provided email/password and return the API key from the dashboard",
        "Register on apollo.io with the provided credentials, verify the OTP from the inbox, and return the workspace ID",
        "Create an account on snov.io using the credentials + IMAP details supplied and return the free-tier API token"
      ],
      "inputModes": [
        "text/plain",
        "application/json"
      ],
      "outputModes": [
        "text/plain",
        "application/json"
      ]
    },
    {
      "id": "network_discovery",
      "name": "Network endpoint discovery",
      "description": "Open ANY URL through a residential browser and deterministically capture its browser network traffic (XHR/fetch), then return a de-duplicated list of the site's API endpoints with freshness signals (ids/timestamps like id/created_at/list_time). No LLM, no per-step billing; credential headers (cookie/authorization) are stripped. Use to reverse-engineer a site's private/data APIs \u2014 often fresher and richer than its public search \u2014 for any dynamic site (marketplaces, classifieds, SPAs). Params: url (required), country, duration_ms (<=90000, default 45000), scroll, reload, match_url (host/substring filter; omit to capture cross-host APIs), freshness_fields[].",
      "tags": [
        "browser",
        "network",
        "reverse-api",
        "discovery",
        "api-scout"
      ],
      "examples": [],
      "inputModes": [
        "text/plain",
        "application/json"
      ],
      "outputModes": [
        "application/json",
        "text/plain"
      ]
    }
  ],
  "capabilities": {
    "streaming": true,
    "pushNotifications": true,
    "stateTransitionHistory": true,
    "extensions": null
  },
  "protocolVersion": "1.0.0",
  "provider": {
    "organization": "Virix Labs",
    "url": "https://humanbrowser.cloud/"
  }
}