Your Agent's Browser

const response = await fetch("https://api.riddledc.com/v1/run", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    steps: [
      { goto: "https://example.com/login" },
      { fill: { selector: "#email", value: "user@example.com" } },
      { fill: { selector: "#password", value: "secret" } },
      { click: "button[type=submit]" },
      { waitForUrl: "**/dashboard**" },
      { screenshot: "dashboard" }
    ]
  })
});

// Sync by default - results returned directly
const { status, screenshots, console: logs } = await response.json();
// screenshots.dashboard = "https://cdn.riddledc.com/..."

const response = await fetch("https://api.riddledc.com/v1/run", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    steps: [
      { goto: "https://example.com/checkout" },
      // Check if we're on the right page without screenshotting
      { assert: [{ selectorExists: ".checkout-form" }], onFail: ["screenshot", "abort"] },
      // Fill the form
      { fill: { selector: "#card-number", value: "4242424242424242" } },
      { fill: { selector: "#expiry", value: "12/25" } },
      { click: "button.submit-payment" },
      // Assert success, only screenshot if something went wrong
      { assert: [{ urlIncludes: "/confirmation" }], onFail: ["screenshot", "abort"] },
      // Success! Screenshot the confirmation
      { screenshot: "confirmation" }
    ]
  })
});

// If all asserts pass: 1 screenshot
// If any assert fails: screenshot of failure state + abort

curl -X POST "https://api.riddledc.com/v1/run" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "sync": true}' \
  -o screenshot.png

# PNG bytes. 3-4 seconds. No polling.

# Pass session cookies - skip login entirely
curl -X POST "https://api.riddledc.com/v1/run" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://app.example.com/dashboard",
    "options": {
      "cookies": [
        {"name": "session_id", "value": "abc123", "domain": "app.example.com"}
      ]
    }
  }' -o dashboard.png

# Or use Bearer tokens for API-protected pages
curl -X POST "https://api.riddledc.com/v1/run" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://app.example.com/dashboard",
    "options": {
      "headers": {"Authorization": "Bearer YOUR_APP_TOKEN"}
    }
  }' -o dashboard.png

# 5 screenshots, one API call, ~$0.0008 each
curl -X POST "https://api.riddledc.com/v1/run" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": [
      "https://example.com",
      "https://example.com/pricing",
      "https://example.com/docs",
      "https://example.com/about",
      "https://example.com/contact"
    ]
  }'

# Returns job_id, poll for screenshots
# Total cost: ~$0.004 for all 5

import requests
import base64

def screenshot_for_vision(url, api_key, cookies=None):
    """Take screenshot, return base64 for vision LLM."""
    body = {"url": url}
    if cookies:
        body["options"] = {"cookies": cookies}

    response = requests.post(
        "https://api.riddledc.com/v1/run",
        headers={"Authorization": f"Bearer {api_key}"},
        json=body
    )
    return base64.b64encode(response.content).decode()

# Use with GPT-4V
screenshot_b64 = screenshot_for_vision(
    "https://example.com",
    API_KEY,
    cookies=[{"name": "session", "value": "abc123", "domain": "example.com"}]
)

response = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "What actions are available on this page?"},
            {"type": "image_url", "image_url": {"url": f"data:image/png;base64,{screenshot_b64}"}}
        ]
    }]
)

async function screenshotForVision(
  url: string,
  apiKey: string,
  cookies?: { name: string; value: string; domain: string }[]
): Promise<string> {
  const body: Record<string, unknown> = { url };
  if (cookies) body.options = { cookies };

  const response = await fetch("https://api.riddledc.com/v1/run", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${apiKey}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(body),
  });

  const buffer = await response.arrayBuffer();
  return Buffer.from(buffer).toString("base64");
}

// Use with OpenAI SDK
import OpenAI from "openai";
const openai = new OpenAI();

const screenshotB64 = await screenshotForVision(
  "https://example.com",
  process.env.RIDDLE_API_KEY!,
  [{ name: "session", value: "abc123", domain: "example.com" }]
);

const response = await openai.chat.completions.create({
  model: "gpt-4o",
  messages: [{
    role: "user",
    content: [
      { type: "text", text: "What actions are available on this page?" },
      { type: "image_url", image_url: { url: `data:image/png;base64,${screenshotB64}` } }
    ]
  }]
});

# Login flow + screenshot in one call
curl -X POST "https://api.riddledc.com/v1/run" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "script": "await page.goto("https://app.example.com/login");
await page.fill("input[name=email]", "user@example.com");
await page.fill("input[name=password]", "password123");
await page.click("button[type=submit]");
await page.waitForURL("**/dashboard");
await saveScreenshot("dashboard");"
  }'