API Documentation

The rtrvr.ai API provides programmatic access to all platform capabilities, allowing you to integrate web automation directly into your applications and workflows.

Authentication

All API requests require authentication using your API key. Include it in the Authorization header:

bash

curl -H "Authorization: Bearer YOUR_API_KEY" \
    https://api.rtrvr.ai/v1/tasks

Keep your API key secure and never expose it in client-side code.

Base URL

text

https://api.rtrvr.ai/v1

Create Task

Create a new web automation task:

bash

POST /tasks
  
  {
    "prompt": "Go to example.com and extract the main heading",
    "type": "single",
    "options": {
      "timeout": 30000,
      "screenshot": true
    }
  }

Sheets Workflow

Process a spreadsheet with web agent tasks:

bash

POST /workflows/sheets
  
  {
    "prompt": "Visit the website column and extract contact email",
    "data": [
      {"company": "Acme Corp", "website": "acme.com"},
      {"company": "Beta Inc", "website": "beta.io"}
    ],
    "context_columns": ["company", "website"],
    "output_columns": ["contact_email"]
  }

Get Task Status

bash

GET /tasks/{task_id}
  
  Response:
  {
    "id": "task_123",
    "status": "completed",
    "result": {
      "data": "Extracted content here",
      "screenshot": "base64_image_data"
    },
    "created_at": "2025-01-01T00:00:00Z",
    "completed_at": "2025-01-01T00:01:30Z"
  }

Webhooks Integration

Receive real-time notifications when tasks complete:

bash

POST /tasks
  
  {
    "prompt": "Monitor this page for changes",
    "webhook_url": "https://your-app.com/webhook",
    "webhook_events": ["completed", "failed"]
  }

Rate Limits

Basic: 100 requests per hour
Pro: 1,000 requests per hour
Enterprise: 10,000 requests per hour
Scale: Custom limits available

Error Handling

The API uses standard HTTP status codes and returns detailed error messages:

json

{
    "error": {
      "code": "INVALID_PROMPT",
      "message": "The provided prompt is too vague. Please be more specific.",
      "details": {
        "suggestion": "Try: 'Extract the price from the product page'"
      }
    }
  }