API Overview
rtrvr.ai exposes three HTTP endpoints for different automation needs: full agent runs, raw page scraping, and browser-as-API for your logged-in Chrome. All share the same authentication and credit system.
Authentication
All endpoints use the same API key. Pass it via the Authorization header:
Authorization: Bearer rtrvr_your_api_keyMCP OAuth Support
For /mcp, clients with OAuth can connect to mcp.rtrvr.ai directly for Google Sign-In authentication.
Security
Keep your key server-side. Never embed it in browser code or ship it to clients.
Unified Playground
API Playground
POST /agent
Get your API key from rtrvr.ai/cloud
URL to a CSV, JSON, or Excel file for row-by-row processing
Paste CSV/JSON data directly
Publicly accessible file URLs (PDF, CSV, text)
Publicly accessible image URLs (JPG, PNG)
Built-in tools: sheets_workflow, google_sheets_access, google_docs_access, google_slides_access, pdf_generator
Responses larger than this are snapshotted to storage
Stable ID for grouping phases. Omit to start new.
Use a recorded workflow as context
Get a live browser view URL in the response
Opt-in progress events (`options.ui.emitEvents=true`)
When to Use What
| 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`)
- • ≤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
New: File & Image Inputs
All agent and MCP credit tools now support file and image inputs via publicly fetchable URLs:
file_urlsCSV, PDF, text files to use as input data for workflows
image_urlsJPG, PNG images for visual context and recognition
recording_idUse a recorded workflow as context for replay
{
"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" }
}Webhooks
Both /agent and /scrape support webhook notifications. Get HTTP callbacks when executions complete, fail, or require 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.
// 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" }
}
]
}