RUN

Choose the right endpoint.

Let rtrvr plan and act, return page data for your own pipeline, or give an MCP client access to a signed-in browser.

Try a request Create API key Add to Chrome

Agent API

Plan and complete a browser job, then return the finished result.

Scrape API

Return page text and structure for your own models and pipelines.

Browser API and MCP

Use the browser already signed in on your device.

CLI

Call every endpoint from your terminal with rtrvr CLI.

npm install -g @rtrvr-ai/cli

Pick the right depth

Three endpoints. One browser layer.

Choose how much rtrvr should decide: complete the job, return the page, or expose your signed-in browser.

01POST /agent

Agent API

Describe the outcome. rtrvr plans the route, works across pages, and returns the finished result.

02POST /scrape

Scrape API

Return clean page text, structure, and links for your own search, RAG, or enrichment pipeline.

03POST /mcp

Browser as API/MCP

Let a backend or MCP client use the Chrome browser already signed in on your device.

One key

Authentication

All endpoints accept the same API key in the Authorization header.

Header

Authorization: Bearer rtrvr_your_api_key

Try the contract

One playground. Every parameter.

Switch endpoints without losing the request shape. The full form stays available; secondary options scroll inside the frame.

API Playground

POST/agent

Shape a real request, inspect the contract, then send it when you are ready.

Describe the outcome. rtrvr plans the route, works across pages, and returns the finished result.Read Agent API

API Key

Get your API key from rtrvr.ai/cloud

Task Description*

Starting URLs

Output Schema (JSON)

Data Input URL

URL to a CSV, JSON, or Excel file for row-by-row processing

Inline Data

Paste CSV/JSON data directly

Data Format

File URLs

Publicly accessible file URLs (PDF, CSV, text)

Image URLs

Publicly accessible image URLs (JPG, PNG)

Enable Tools

Built-in tools: sheets_workflow, google_sheets_access, google_docs_access, google_slides_access, pdf_generator

Response Verbosity

Max Steps

Max Inline Output Bytes

Responses larger than this are snapshotted to storage

Trajectory ID

Stable ID for grouping phases. Omit to start new.

Recording ID

Use a recorded workflow as context

Enable VNC Live ViewEnabled

Get a live browser view URL in the response

Emit EventsEnabled

Opt-in progress events (`options.ui.emitEvents=true`)

WebhooksManage in Cloud

curl -X POST "https://api.rtrvr.ai/agent" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "input": "",
  "urls": [
    "https://news.ycombinator.com/"
  ],
  "response": {
    "verbosity": "final"
  }
}'

Decision guide

Choose by the result you need.

Start with the smallest endpoint that can finish the job. Move up to the planner when the route itself needs judgment.

Use Case	Endpoint	Why
End-to-end web automation	`/agent`	Full planner + tools, can write to Sheets/Docs
Feed your own LLM/RAG pipeline	`/scrape`	Infra-only credits, returns raw text + tree
Use logged-in sessions (Gmail, Salesforce)	`/mcp`	Runs in your Chrome via extension
Bulk data extraction	`/agent`	Use dataInputs + sheets_workflow
Quick page content check	`/scrape`	Cheapest option, predictable schema
MCP client integration (Claude, etc.)	`/mcp`	Direct MCP protocol support

/agent

• Model + infra credits
• Higher latency (LLM calls)
• Full automation capability
• Progress events are opt-in (`options.ui.emitEvents=true`)
• Responses include protocol.name="rtrvr.agent", run, inputRequest, and history for A2W/A2A-style continuation
• ≤1MB inline preview; larger payloads include refs (outputRef / resultRef / responseRef)

/scrape

• Infra-only credits
• Lower latency
• Raw data for your models
• Progress events are opt-in (`options.ui.emitEvents=true`)
• ≤1MB tab payload inline; oversized responses include metadata.responseRef

/mcp

• Your logged-in browser
• MCP + HTTP + OAuth
• Access authenticated sites
• `emitEvents` opt-in; large outputs follow same preview+ref contract

More context

Files, images, and recordings

Agent and MCP tools can take publicly fetchable assets alongside the starting page. For local files, upload them first with the upload_file MCP tool (base64, URL import, or signed upload URL) and pass the returned storage URL

file_urls

CSV, PDF, text files to use as input data for workflows

image_urls

JPG, PNG images for visual context and recognition

recording_id

Use a recorded workflow as context for replay

Example: Agent API with file inputs

{
  "input": "Upload this CSV and submit the form",
  "urls": ["https://example.com/upload"],
  "file_urls": ["https://example.com/data.csv"],
  "image_urls": ["https://example.com/screenshot.png"],
  "recording_id": "rec_abc123",
  "response": { "verbosity": "final" }
}

Hand off the result

Webhooks

Have /agent or /scrape call your system when a run completes, fails, or needs input.

Real-time delivery

Webhooks fire asynchronously via Cloud Tasks with best-effort delivery and automatic retries.

HMAC signing

Provide a secret to receive X-Rtrvr-Signature headers for secure payload verification.

Auth support

Configure Bearer token or Basic auth for your webhook endpoints.

Webhook configuration example

// Add webhooks to any /agent or /scrape request
{
  "input": "Extract product data from the page",
  "urls": ["https://example.com/products"],
  "webhooks": [
    {
      "url": "https://your-server.com/webhook",
      "events": ["rtrvr.execution.succeeded", "rtrvr.execution.failed"],
      "secret": "whsec_your_signing_secret",
      "auth": { "type": "bearer", "token": "your-token" },
      "headers": { "X-Custom-Header": "my-value" }
    }
  ]
}

YOUR NEXT RUN

Run the example on a real site.

Use Chrome for the page in front of you. Use Cloud when the run should continue on a schedule or across many pages.

RUN

Choose the right endpoint.

Let rtrvr plan and act, return page data for your own pipeline, or give an MCP client access to a signed-in browser.

Try a request Create API key Add to Chrome

Agent API

Plan and complete a browser job, then return the finished result.

Scrape API

Return page text and structure for your own models and pipelines.

Browser API and MCP

Use the browser already signed in on your device.

CLI

Call every endpoint from your terminal with rtrvr CLI.

npm install -g @rtrvr-ai/cli

Pick the right depth

Three endpoints. One browser layer.

Choose how much rtrvr should decide: complete the job, return the page, or expose your signed-in browser.

01POST /agent

Agent API

Describe the outcome. rtrvr plans the route, works across pages, and returns the finished result.

02POST /scrape

Scrape API

Return clean page text, structure, and links for your own search, RAG, or enrichment pipeline.

03POST /mcp

Browser as API/MCP

Let a backend or MCP client use the Chrome browser already signed in on your device.

One key

Authentication

All endpoints accept the same API key in the Authorization header.

Header

Authorization: Bearer rtrvr_your_api_key

Try the contract

One playground. Every parameter.

Switch endpoints without losing the request shape. The full form stays available; secondary options scroll inside the frame.

API Playground

POST/agent

Shape a real request, inspect the contract, then send it when you are ready.

Describe the outcome. rtrvr plans the route, works across pages, and returns the finished result.Read Agent API

API Key

Get your API key from rtrvr.ai/cloud

Task Description*

Starting URLs

Output Schema (JSON)

Data Input URL

URL to a CSV, JSON, or Excel file for row-by-row processing

Inline Data

Paste CSV/JSON data directly

Data Format

File URLs

Publicly accessible file URLs (PDF, CSV, text)

Image URLs

Publicly accessible image URLs (JPG, PNG)

Enable Tools

Built-in tools: sheets_workflow, google_sheets_access, google_docs_access, google_slides_access, pdf_generator

Response Verbosity

Max Steps

Max Inline Output Bytes

Responses larger than this are snapshotted to storage

Trajectory ID

Stable ID for grouping phases. Omit to start new.

Recording ID

Use a recorded workflow as context

Enable VNC Live ViewEnabled

Get a live browser view URL in the response

Emit EventsEnabled

Opt-in progress events (`options.ui.emitEvents=true`)

WebhooksManage in Cloud

curl -X POST "https://api.rtrvr.ai/agent" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "input": "",
  "urls": [
    "https://news.ycombinator.com/"
  ],
  "response": {
    "verbosity": "final"
  }
}'

Decision guide

Choose by the result you need.

Start with the smallest endpoint that can finish the job. Move up to the planner when the route itself needs judgment.

Use Case	Endpoint	Why
End-to-end web automation	`/agent`	Full planner + tools, can write to Sheets/Docs
Feed your own LLM/RAG pipeline	`/scrape`	Infra-only credits, returns raw text + tree
Use logged-in sessions (Gmail, Salesforce)	`/mcp`	Runs in your Chrome via extension
Bulk data extraction	`/agent`	Use dataInputs + sheets_workflow
Quick page content check	`/scrape`	Cheapest option, predictable schema
MCP client integration (Claude, etc.)	`/mcp`	Direct MCP protocol support

/agent

• Model + infra credits
• Higher latency (LLM calls)
• Full automation capability
• Progress events are opt-in (`options.ui.emitEvents=true`)
• Responses include protocol.name="rtrvr.agent", run, inputRequest, and history for A2W/A2A-style continuation
• ≤1MB inline preview; larger payloads include refs (outputRef / resultRef / responseRef)

/scrape

• Infra-only credits
• Lower latency
• Raw data for your models
• Progress events are opt-in (`options.ui.emitEvents=true`)
• ≤1MB tab payload inline; oversized responses include metadata.responseRef

/mcp

• Your logged-in browser
• MCP + HTTP + OAuth
• Access authenticated sites
• `emitEvents` opt-in; large outputs follow same preview+ref contract

More context

Files, images, and recordings

file_urls

CSV, PDF, text files to use as input data for workflows

image_urls

JPG, PNG images for visual context and recognition

recording_id

Use a recorded workflow as context for replay

Example: Agent API with file inputs

{
  "input": "Upload this CSV and submit the form",
  "urls": ["https://example.com/upload"],
  "file_urls": ["https://example.com/data.csv"],
  "image_urls": ["https://example.com/screenshot.png"],
  "recording_id": "rec_abc123",
  "response": { "verbosity": "final" }
}

Hand off the result

Webhooks

Have /agent or /scrape call your system when a run completes, fails, or needs input.

Real-time delivery

Webhooks fire asynchronously via Cloud Tasks with best-effort delivery and automatic retries.

HMAC signing

Provide a secret to receive X-Rtrvr-Signature headers for secure payload verification.

Auth support

Configure Bearer token or Basic auth for your webhook endpoints.

Webhook configuration example

// Add webhooks to any /agent or /scrape request
{
  "input": "Extract product data from the page",
  "urls": ["https://example.com/products"],
  "webhooks": [
    {
      "url": "https://your-server.com/webhook",
      "events": ["rtrvr.execution.succeeded", "rtrvr.execution.failed"],
      "secret": "whsec_your_signing_secret",
      "auth": { "type": "bearer", "token": "your-token" },
      "headers": { "X-Custom-Header": "my-value" }
    }
  ]
}

YOUR NEXT RUN

Run the example on a real site.

Use Chrome for the page in front of you. Use Cloud when the run should continue on a schedule or across many pages.