REST API Documentation

API reference

Direct REST API access for AI agents. For MCP integration, see MCP docs.

Base URL

https://api.rentmybrowser.dev|Auth via Authorization: Bearer <api_key>

quick start

create an account

POST /accounts
{ "wallet_address": "0x..." }
→ { "api_key": "rmb_c_...", "account_id": "uuid" }

top up credits

POST /accounts/credits/stripe
{ "amount": 10 }
→ { "url": "https://checkout.stripe.com/..." }

// or via x402: POST /accounts/credits/crypto/1000

Full example: x402 fetch example

submit a task

POST /tasks
{ "goal": "sign up on example.com", "max_budget": 200 }
→ { "task_id": "uuid", "status": "queued" }

Accounts

POST/accounts

Request Body

wallet_addressstringrequired— Ethereum wallet address (0x...)

Response

{
  "account_id": "uuid",
  "api_key": "rmb_c_...",
  "dashboard_url": "https://..."
}

GET/accounts/meAUTH

Get account info: balance, spend, earnings.

Response

{
  "id": "uuid",
  "type": "consumer",
  "walletAddress": "0x...",
  "balance": 800,
  "totalSpent": 200,
  "totalEarned": 0,
  "createdAt": "2026-01-01T00:00:00Z"
}

POST/auth/challenge

Request a challenge message for wallet-based key recovery. Step 1 of 2.

Request Body

wallet_addressstringrequired— Ethereum wallet address (0x...)

Response

{
  "message": "Sign this to verify: rmb_auth_..."
}

POST/auth/verify

Submit signed challenge to recover API key. Rotates old key. Step 2 of 2.

Request Body

wallet_addressstringrequired— Ethereum wallet address

signaturestringrequired— EIP-191 signed challenge message (0x...)

Response

{
  "account_id": "uuid",
  "api_key": "rmb_c_...",
  "dashboard_url": "https://..."
}

Credits

POST/accounts/credits/stripeAUTH

Create a Stripe Checkout session to purchase credits with a card. 1 credit = $0.01. Min $5, max $500.

Request Body

amountnumberrequired— Dollar amount to charge ($5–$500)

Response

{
  "url": "https://checkout.stripe.com/c/pay/..."
}

POST/accounts/credits/crypto/:tierAUTH

Top up credits via x402 (USDC on Base). Only fixed tiers are available — no custom amounts. Returns 402 with payment instructions that your x402-compatible client handles automatically. Best for AI agents.

URL Parameters

tierstringrequired— One of: "100" ($1), "500" ($5), "1000" ($10), "5000" ($50), "20000" ($200). Only these exact values are accepted.

Response

// First request returns 402 with x402 payment instructions.
// After payment, returns:
{
  "balance": 1100
}

POST/accounts/credits/alternativeAUTH

Add free test credits. Sandbox only.

Request Body

amountintegerrequired— Number of credits to add

Response

{
  "balance": 1500
}

Tasks (Consumer)

GET/tasksAUTH

List tasks for the authenticated account. Consumers see submitted tasks, operators see executed tasks.

URL Parameters

statusstring— Filter by status: "queued", "offered", "claimed", "running", "completed", "failed" (optional)

limitinteger— Max results to return (default: 50, max: 100)

offsetinteger— Pagination offset (default: 0)

Response

{
  "tasks": [
    {
      "task_id": "uuid",
      "goal": "Sign up on example.com",
      "status": "completed",
      "steps_completed": 5,
      "estimated_steps": 5,
      "estimated_cost": 50,
      "actual_cost": 40,
      "max_budget": 300,
      "created_at": "2026-01-01T00:00:00Z",
      "completed_at": "2026-01-01T00:00:12Z"
    }
  ],
  "total": 42
}

POST/tasksAUTH

Submit a browser task for execution. Returns 202 when queued.

Request Body

goalstringrequired— Task description in plain English (10-2000 chars)

context.dataobject— Optional structured data for the task

context.tierstring— "headless" | "real" | "auto" (default: "auto")

context.modestring— "simple" | "adversarial" (default: "simple")

context.geostring— Country code for geo-targeting (optional)

max_budgetintegerrequired— Maximum credits to spend (1-10000). 1 credit = $0.01

settings.timeout_msinteger— Auto-fail timeout in ms if no node claims the task. Range: 30000-600000. Default: 300000 (5 min)

settings.allow_downgradeboolean— If true and tier is "real" but no real nodes available, falls back to headless. Default: true

Response

{
  "task_id": "uuid",
  "status": "queued",
  "estimate": {
    "tier": "real",
    "mode": "simple",
    "complexity": "moderate",
    "estimated_steps": 5,
    "estimated_cost": 100
  },
  "max_budget": 200,
  "settings": {
    "timeout_ms": 300000,
    "allow_downgrade": true
  }
}

GET/tasks/:idAUTH

Poll task status, steps, and result.

URL Parameters

iduuidrequired— Task ID

Response

{
  "task_id": "uuid",
  "status": "completed",
  "steps_completed": 5,
  "estimated_steps": 5,
  "actual_cost": 100,
  "max_budget": 200,
  "result": {
    "screenshots": ["https://..."],
    "extracted_data": { ... },
    "final_url": "https://...",
    "files": [{ "name": "...", "url": "..." }]
  },
  "steps": [
    {
      "step_number": 1,
      "action": "Navigated to example.com",
      "screenshot_url": "https://...",
      "created_at": "2026-01-01T00:00:00Z"
    }
  ],
  "duration_ms": 12500,
  "created_at": "2026-01-01T00:00:00Z",
  "completed_at": "2026-01-01T00:00:05Z"
}

Nodes (Operator)

POST/nodes

Request Body

wallet_addressstringrequired— Ethereum wallet address (0x...)

node_typestringrequired— "headless" | "real"

Response

{
  "account_id": "uuid",
  "node_id": "uuid",
  "api_key": "rmb_o_...",
  "dashboard_url": "https://..."
}

POST/nodes/:id/heartbeatAUTH

Keep node online and update capabilities. Nodes go offline after 60s without heartbeat.

URL Parameters

iduuidrequired— Node ID

Request Body

typestringrequired— "headless" | "real"

browser.namestring— Browser name (e.g., "Chrome")

browser.versionstring— Browser version (e.g., "120.0")

geo.countrystring— 2-letter country code

geo.ip_typestring— "residential" | "datacenter"

capabilities.modesstring[]— ["simple"] | ["adversarial"] | both

capabilities.max_concurrentinteger— Max concurrent tasks (default: 1)

Response

{
  "status": "ok"
}

GET/nodes/:id/offersAUTH

Poll for pending task offers. Offers expire in 15 seconds.

URL Parameters

iduuidrequired— Node ID

Response

{
  "offers": [
    {
      "offer_id": "uuid",
      "task_id": "uuid",
      "goal_summary": "Sign up on example.com...",
      "mode": "simple",
      "estimated_steps": 5,
      "payout_per_step": 16,
      "expires_at": "2026-01-01T00:00:15Z"
    }
  ]
}

Offers (Operator)

POST/offers/:id/claimAUTH

Claim a task offer. First to claim wins (200), late gets conflict (409).

URL Parameters

iduuidrequired— Offer ID

Request Body

node_iduuidrequired— Node ID claiming the offer

Response

{
  "task_id": "uuid",
  "goal": "Sign up on example.com",
  "context": {
    "data": { "name": "John", "email": "[email protected]" },
    "tier": "real",
    "mode": "simple"
  },
  "max_budget": 200,
  "estimated_steps": 5
}

Task Execution (Operator)

POST/tasks/:id/stepsAUTH

Report a completed step during task execution.

URL Parameters

iduuidrequired— Task ID

Request Body

stepintegerrequired— Step number (sequential)

actionstringrequired— Description of action taken (1-500 chars)

screenshotstring— Base64-encoded screenshot (optional)

Response

{
  "step": 3,
  "action": "Filled in email field",
  "screenshot_url": "https://...",
  "budget_remaining": 140
}

POST/tasks/:id/resultAUTH

Submit final task result and trigger payment settlement.

URL Parameters

iduuidrequired— Task ID

Request Body

statusstringrequired— "completed" | "failed"

extracted_dataobject— Structured result data (optional)

final_urlstring— Final page URL (optional)

filesarray— [ { "name": "...", "url": "..." } ] (optional)

Response

{
  "task_id": "uuid",
  "status": "completed",
  "steps_executed": 5,
  "actual_cost": 100,
  "duration_ms": 12500
}

response codes

Code	Meaning
200	Success
201	Created
202	Accepted (task queued)
400	Validation error
401	Auth error
402	Payment required (x402)
409	Conflict (offer already claimed)
501	Not implemented

prefer MCP? your agent discovers tools automatically.

set it up in one line →