API Documentation

# Create an API key
curl -X POST "https://api.riddledc.com/billing/api-keys" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Production Key"}'

# Response
{
  "apiKey": "rdc_live_abc123********************xyz789",
  "keyId": "key_0844fb72799dd7b3",
  "warning": "Save this key now - you will not be able to see it again!"
}

Authorization: Bearer rdc_live_abc123********************xyz789

curl -X POST "https://cognito-idp.us-east-1.amazonaws.com/" \
  -H "Content-Type: application/x-amz-json-1.1" \
  -H "X-Amz-Target: AWSCognitoIdentityProviderService.InitiateAuth" \
  -d '{
    "AuthFlow": "USER_PASSWORD_AUTH",
    "ClientId": "7u1bt3r20v613j7eaki9dkbhve",
    "AuthParameters": {
      "USERNAME": "your-email@example.com",
      "PASSWORD": "your-password"
    }
  }'

# Use the IdToken from the response

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"}' -o screenshot.png

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"
    ]
  }'

curl -X POST "https://api.riddledc.com/v1/run" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "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" }
    ]
  }'

curl -X POST "https://api.riddledc.com/v1/run" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "script": "await page.goto('\''https://example.com'\''); const title = await page.title(); console.log('\''Title:'\''', title); await saveScreenshot('\''homepage'\''');"
  }'

await waitForWindow("appReady", 30000);
const data = await page.evaluate(() => window.appState);
await saveJson("state", data);

{
  "url": "https://example.com",
  "timeout_sec": 60,
  "options": {
    "viewport": { "width": 1920, "height": 1080 },
    "fullPage": true,
    "cookies": [{ "name": "session", "value": "abc", "domain": "example.com" }],
    "headers": { "Authorization": "Bearer APP_TOKEN" },
    "localStorage": { "token": "xyz" }
  }
}

{
  "steps": [
    { "goto": "https://example.com/checkout" },
    { "assert": [{ "selectorExists": ".checkout-form" }], "onFail": ["screenshot", "abort"] },
    { "fill": { "selector": "#card", "value": "4242424242424242" } },
    { "click": "button.pay" },
    { "assert": [{ "urlIncludes": "/confirmation" }], "onFail": ["screenshot", "abort"] },
    { "screenshot": "confirmation" }
  ]
}

// Assertion types: selectorExists, selectorMissing, urlIncludes, urlExcludes, textContains

// Both work - browser code auto-wrapped:
{ "eval": "document.title" }
{ "eval": "await page.evaluate(() => document.title)" }

// Playwright APIs work directly:
{ "eval": "await page.click('.submit')" }

{ "screenshot": "homepage" }

{ "screenshot": { "label": "navbar", "selector": "nav.main-nav" } }

{ "screenshot": { "label": "hero", "clip": { "x": 0, "y": 0, "width": 1200, "height": 600 } } }

{ "screenshot": { "label": "above-fold", "fullPage": false } }

// JPEG with quality
{ "screenshot": { "label": "compressed", "type": "jpeg", "quality": 75 } }

// Retina scale
{ "screenshot": { "label": "retina", "scale": "device" } }

// Transparent background
{ "screenshot": { "label": "transparent", "omitBackground": true } }

HTTP/1.1 200 OK
Content-Type: image/png
X-Job-Id: job_abc123
X-Duration-Ms: 4200

[PNG bytes]

curl -X POST "https://api.riddledc.com/v1/run" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "url": "https://example.com",
    "include": ["console", "har", "result"]
  }'

{
  "status": "completed",
  "job_id": "job_abc123",
  "duration_ms": 4200,
  "screenshot": {
    "name": "result.png",
    "data": "data:image/png;base64,iVBORw0K...",
    "size": 45678
  },
  "console": {
    "summary": { "total_entries": 3, "error_count": 1 },
    "entries": { "log": [...], "error": [...] }
  },
  "result": { "score": 42 },
  "har": {
    "log": { "entries": [...] }
  }
}

// 1. Submit
const { job_id } = await fetch("https://api.riddledc.com/v1/run", {
  method: "POST",
  headers: { "Authorization": "Bearer KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ url: "https://example.com", sync: false })
}).then(r => r.json());

// 2. Poll until status is "completed"
const status = await fetch(`https://api.riddledc.com/v1/jobs/${job_id}`, {
  headers: { "Authorization": "Bearer KEY" }
}).then(r => r.json());

// 3. Get artifacts
const artifacts = await fetch(`https://api.riddledc.com/v1/jobs/${job_id}/artifacts`, {
  headers: { "Authorization": "Bearer KEY" }
}).then(r => r.json());

{
  "url": "https://example.com",
  "webhook_url": "https://your-server.com/riddle-webhook"
}

{
  "event": "job.completed",
  "job_id": "job_abc123",
  "status": "completed",
  "duration_ms": 5693,
  "artifacts": [
    { "name": "screenshot.png", "url": "https://cdn.riddledc.com/..." }
  ],
  "billing": { "actual_seconds": 30, "actual_cost_dollars": 0.004167 }
}