API Reference

Complete reference for the Scraper REST API. All endpoints require authentication via API key.

Authentication

Include your API key in the X-API-Key header with every request. Generate keys from the dashboard under Settings > API Keys.

Header

X-API-Key: scr_live_your_key_here

Base URL

https://scraper.bot/api

GET/flows

List all flows. Supports filtering by status and mode.

Query Parameters

Name	Type	Description
`status`	string	Filter by flow status: active, paused, draft, error
`mode`	string	Filter by flow mode: extract, interact, monitor

Response

JSON

{
  "data": [
    {
      "id": "flow-1",
      "name": "Product Price Monitor",
      "status": "active",
      "mode": "monitor",
      "url": "https://example-store.com/products",
      "successRate": 98.5,
      "totalRuns": 248,
      "createdAt": "2026-02-15T10:00:00Z"
    }
  ],
  "total": 6
}

Examples

curl

curl https://scraper.bot/api/flows?status=active \
  -H "X-API-Key: scr_live_your_key_here"

JavaScript

const res = await fetch("/api/flows?status=active", {
  headers: { "X-API-Key": "scr_live_your_key_here" },
});
const { data } = await res.json();

POST/flows

Create a new flow.

Request Body

JSON

{
  "name": "My New Flow",
  "description": "Scrape product listings",
  "url": "https://example.com/products",
  "mode": "extract",
  "steps": [
    { "type": "navigate", "label": "Go to page" },
    { "type": "extract", "label": "Extract data" }
  ],
  "outputSchema": { "title": "string", "price": "number" }
}

Response

JSON

{
  "data": {
    "id": "flow-1710000000000",
    "name": "My New Flow",
    "status": "draft",
    "createdAt": "2026-03-18T12:00:00Z"
  }
}

Examples

curl

curl -X POST https://scraper.bot/api/flows \
  -H "X-API-Key: scr_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"name":"My New Flow","url":"https://example.com","mode":"extract"}'

JavaScript

const res = await fetch("/api/flows", {
  method: "POST",
  headers: {
    "X-API-Key": "scr_live_your_key_here",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "My New Flow",
    url: "https://example.com",
    mode: "extract",
  }),
});
const { data } = await res.json();

GET/flows/:id

Get a single flow by ID.

Response

JSON

{
  "data": {
    "id": "flow-1",
    "name": "Product Price Monitor",
    "description": "Track prices across e-commerce sites",
    "url": "https://example-store.com/products",
    "mode": "monitor",
    "status": "active",
    "steps": [...],
    "outputSchema": { "name": "string", "price": "number" },
    "successRate": 98.5,
    "totalRuns": 248
  }
}

Examples

curl

curl https://scraper.bot/api/flows/flow-1 \
  -H "X-API-Key: scr_live_your_key_here"

JavaScript

const res = await fetch("/api/flows/flow-1", {
  headers: { "X-API-Key": "scr_live_your_key_here" },
});
const { data } = await res.json();

PUT/flows/:id

Update an existing flow. Merge-patches the provided fields.

Request Body

JSON

{
  "name": "Updated Flow Name",
  "status": "active"
}

Response

JSON

{
  "data": {
    "id": "flow-1",
    "name": "Updated Flow Name",
    "status": "active",
    "updatedAt": "2026-03-18T12:00:00Z"
  }
}

Examples

curl

curl -X PUT https://scraper.bot/api/flows/flow-1 \
  -H "X-API-Key: scr_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"name":"Updated Flow Name","status":"active"}'

JavaScript

const res = await fetch("/api/flows/flow-1", {
  method: "PUT",
  headers: {
    "X-API-Key": "scr_live_your_key_here",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ name: "Updated Flow Name" }),
});

DELETE/flows/:id

Delete a flow by ID.

Response

JSON

{
  "message": "Flow flow-1 deleted successfully"
}

Examples

curl

curl -X DELETE https://scraper.bot/api/flows/flow-1 \
  -H "X-API-Key: scr_live_your_key_here"

JavaScript

await fetch("/api/flows/flow-1", {
  method: "DELETE",
  headers: { "X-API-Key": "scr_live_your_key_here" },
});

GET/runs

List all runs. Supports filtering by flow ID and status.

Query Parameters

Name	Type	Description
`flowId`	string	Filter runs by flow ID
`status`	string	Filter by run status: queued, running, completed, failed, cancelled

Response

JSON

{
  "data": [
    {
      "id": "run-1",
      "flowId": "flow-1",
      "flowName": "Product Price Monitor",
      "status": "completed",
      "startedAt": "2026-03-18T12:00:00Z",
      "duration": 12400,
      "itemsExtracted": 147,
      "cost": 0.003
    }
  ],
  "total": 5
}

Examples

curl

curl https://scraper.bot/api/runs?flowId=flow-1&status=completed \
  -H "X-API-Key: scr_live_your_key_here"

JavaScript

const res = await fetch("/api/runs?flowId=flow-1", {
  headers: { "X-API-Key": "scr_live_your_key_here" },
});
const { data } = await res.json();

POST/runs

Trigger a new run for a flow. The run starts in queued status.

Request Body

JSON

{
  "flowId": "flow-1"
}

Response

JSON

{
  "data": {
    "id": "run-1710000000000",
    "flowId": "flow-1",
    "flowName": "Product Price Monitor",
    "status": "queued",
    "startedAt": "2026-03-18T12:00:00Z",
    "cost": 0
  }
}

Examples

curl

curl -X POST https://scraper.bot/api/runs \
  -H "X-API-Key: scr_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"flowId":"flow-1"}'

JavaScript

const res = await fetch("/api/runs", {
  method: "POST",
  headers: {
    "X-API-Key": "scr_live_your_key_here",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ flowId: "flow-1" }),
});

GET/runs/:id

Get a single run by ID, including full logs.

Response

JSON

{
  "data": {
    "id": "run-1",
    "flowId": "flow-1",
    "status": "completed",
    "duration": 12400,
    "itemsExtracted": 147,
    "logs": [
      { "timestamp": "...", "level": "info", "message": "Run started" },
      { "timestamp": "...", "level": "info", "message": "Extracted 147 items" }
    ],
    "outputPreview": [...]
  }
}

Examples

curl

curl https://scraper.bot/api/runs/run-1 \
  -H "X-API-Key: scr_live_your_key_here"

JavaScript

const res = await fetch("/api/runs/run-1", {
  headers: { "X-API-Key": "scr_live_your_key_here" },
});
const { data } = await res.json();
console.log(data.logs);

POST/extract

One-shot extraction. Send a URL and optional instructions to get structured data back instantly without creating a flow.

Request Body

JSON

{
  "url": "https://example-store.com/products",
  "instructions": "Extract all product names and prices",
  "schema": {
    "name": "string",
    "price": "number"
  }
}

Response

JSON

{
  "data": {
    "url": "https://example-store.com/products",
    "extractedAt": "2026-03-18T12:00:00Z",
    "itemCount": 3,
    "items": [
      { "name": "Wireless Headphones Pro", "price": 79.99 },
      { "name": "USB-C Hub 7-in-1", "price": 34.99 },
      { "name": "Mechanical Keyboard", "price": 129.99 }
    ]
  }
}

Examples

curl

curl -X POST https://scraper.bot/api/extract \
  -H "X-API-Key: scr_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example-store.com/products","instructions":"Extract all product names and prices"}'

JavaScript

const res = await fetch("/api/extract", {
  method: "POST",
  headers: {
    "X-API-Key": "scr_live_your_key_here",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://example-store.com/products",
    instructions: "Extract all product names and prices",
    schema: { name: "string", price: "number" },
  }),
});
const { data } = await res.json();
console.log(data.items);

GET/keys

List all API keys. Keys are returned masked for security.

Response

JSON

{
  "data": [
    {
      "id": "key-1",
      "name": "Production API Key",
      "key": "scr_live_****xxxx",
      "createdAt": "2026-01-15T10:00:00Z",
      "scopes": ["flows:read", "flows:write", "runs:read", "runs:write"]
    }
  ],
  "total": 3
}

Examples

curl

curl https://scraper.bot/api/keys \
  -H "X-API-Key: scr_live_your_key_here"

JavaScript

const res = await fetch("/api/keys", {
  headers: { "X-API-Key": "scr_live_your_key_here" },
});
const { data } = await res.json();

POST/keys

Create a new API key. The full key is only returned once on creation.

Request Body

JSON

{
  "name": "My New Key",
  "scopes": ["flows:read", "runs:read", "runs:write"]
}

Response

JSON

{
  "data": {
    "id": "key-1710000000000",
    "name": "My New Key",
    "key": "scr_live_abc123def456...",
    "createdAt": "2026-03-18T12:00:00Z",
    "scopes": ["flows:read", "runs:read", "runs:write"]
  }
}

Examples

curl

curl -X POST https://scraper.bot/api/keys \
  -H "X-API-Key: scr_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"name":"My New Key","scopes":["flows:read","runs:read"]}'

JavaScript

const res = await fetch("/api/keys", {
  method: "POST",
  headers: {
    "X-API-Key": "scr_live_your_key_here",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "My New Key",
    scopes: ["flows:read", "runs:read"],
  }),
});
const { data } = await res.json();
// Save data.key - it won't be shown again

POST/runs/trigger

Trigger a run for a flow by flow ID. Alias for POST /runs with additional trigger metadata.

Request Body

JSON

{
  "flowId": "flow-1",
  "trigger": "api"
}

Response

JSON

{
  "data": {
    "id": "run-1710000000000",
    "flowId": "flow-1",
    "status": "queued",
    "trigger": "api",
    "startedAt": "2026-03-19T12:00:00Z"
  }
}

Examples

curl

curl -X POST https://scraper.bot/api/runs/trigger \
  -H "X-API-Key: scr_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"flowId":"flow-1","trigger":"api"}'

JavaScript

const res = await fetch("/api/runs/trigger", {
  method: "POST",
  headers: {
    "X-API-Key": "scr_live_your_key_here",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ flowId: "flow-1", trigger: "api" }),
});

POST/generate

Generate a complete scraping flow from a natural language description using Claude AI.

Request Body

JSON

{
  "prompt": "Scrape all product names and prices from this e-commerce page",
  "url": "https://example-store.com/products"
}

Response

JSON

{
  "data": {
    "name": "Product Price Scraper",
    "description": "Extract product names and prices",
    "url": "https://example-store.com/products",
    "mode": "extract",
    "steps": [
      { "type": "navigate", "url": "https://example-store.com/products" },
      { "type": "extract", "selector": ".product-card", "fields": ["name", "price"] }
    ],
    "outputSchema": { "name": "string", "price": "number" }
  }
}

Examples

curl

curl -X POST https://scraper.bot/api/generate \
  -H "X-API-Key: scr_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Scrape all product names and prices","url":"https://example-store.com/products"}'

JavaScript

const res = await fetch("/api/generate", {
  method: "POST",
  headers: {
    "X-API-Key": "scr_live_your_key_here",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    prompt: "Scrape all product names and prices",
    url: "https://example-store.com/products",
  }),
});
const { data } = await res.json();

GET/alerts

List all alerts. Supports filtering by severity and read status.

Query Parameters

Name	Type	Description
`severity`	string	Filter by severity: info, warning, critical
`read`	boolean	Filter by read status

Response

JSON

{
  "data": [
    {
      "id": "alert-1",
      "type": "change_detected",
      "severity": "warning",
      "flowId": "flow-1",
      "message": "Price changed from $29.99 to $24.99",
      "read": false,
      "createdAt": "2026-03-19T08:00:00Z"
    }
  ],
  "total": 3
}

Examples

curl

curl https://scraper.bot/api/alerts?severity=warning \
  -H "X-API-Key: scr_live_your_key_here"

JavaScript

const res = await fetch("/api/alerts?severity=warning", {
  headers: { "X-API-Key": "scr_live_your_key_here" },
});
const { data } = await res.json();

GET/analytics

Retrieve usage analytics including run counts, success rates, and cost breakdown over a time range.

Query Parameters

Name	Type	Description
`period`	string	Time period: 7d, 30d, 90d

Response

JSON

{
  "data": {
    "totalRuns": 1247,
    "successRate": 96.8,
    "totalCost": 12.47,
    "dataPointsExtracted": 48230,
    "dailyBreakdown": [
      { "date": "2026-03-19", "runs": 42, "success": 41, "cost": 0.42 }
    ]
  }
}

Examples

curl

curl https://scraper.bot/api/analytics?period=30d \
  -H "X-API-Key: scr_live_your_key_here"

JavaScript

const res = await fetch("/api/analytics?period=30d", {
  headers: { "X-API-Key": "scr_live_your_key_here" },
});
const { data } = await res.json();

GET/audit

Retrieve the audit log of all actions performed on the account.

Query Parameters

Name	Type	Description
`limit`	number	Number of entries to return (default 50)

Response

JSON

{
  "data": [
    {
      "id": "audit-1",
      "action": "flow.created",
      "userId": "user-1",
      "resource": "flow-1",
      "timestamp": "2026-03-19T10:00:00Z",
      "metadata": { "name": "Product Scraper" }
    }
  ],
  "total": 128
}

Examples

curl

curl https://scraper.bot/api/audit?limit=20 \
  -H "X-API-Key: scr_live_your_key_here"

JavaScript

const res = await fetch("/api/audit?limit=20", {
  headers: { "X-API-Key": "scr_live_your_key_here" },
});
const { data } = await res.json();

POST/checkout

Create a Stripe checkout session for plan upgrades. Redirects the user to Stripe for payment.

Request Body

JSON

{
  "plan": "pro",
  "interval": "monthly"
}

Response

JSON

{
  "url": "https://checkout.stripe.com/c/pay/cs_live_...",
  "sessionId": "cs_live_..."
}

Examples

curl

curl -X POST https://scraper.bot/api/checkout \
  -H "X-API-Key: scr_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"plan":"pro","interval":"monthly"}'

JavaScript

const res = await fetch("/api/checkout", {
  method: "POST",
  headers: {
    "X-API-Key": "scr_live_your_key_here",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ plan: "pro", interval: "monthly" }),
});
const { url } = await res.json();
window.location.href = url;

POST/email

Send a transactional email via Resend. Used internally for alerts, reports, and welcome emails.

Request Body

JSON

{
  "to": "user@example.com",
  "subject": "Your scraping report is ready",
  "template": "report_ready",
  "data": { "flowName": "Product Monitor", "itemCount": 147 }
}

Response

JSON

{
  "id": "msg_1710000000000",
  "status": "sent"
}

Examples

curl

curl -X POST https://scraper.bot/api/email \
  -H "X-API-Key: scr_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"to":"user@example.com","subject":"Report ready","template":"report_ready"}'

JavaScript

const res = await fetch("/api/email", {
  method: "POST",
  headers: {
    "X-API-Key": "scr_live_your_key_here",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    to: "user@example.com",
    subject: "Report ready",
    template: "report_ready",
  }),
});

GET/health

Health check endpoint. Returns the current status of all platform services.

Response

JSON

{
  "status": "healthy",
  "services": {
    "api": "up",
    "database": "up",
    "scraping_engine": "up",
    "ai": "up"
  },
  "version": "0.6.0",
  "uptime": 864000
}

Examples

curl

curl https://scraper.bot/api/health

JavaScript

const res = await fetch("/api/health");
const { status, services } = await res.json();

POST/screenshot

Capture a screenshot of any URL using the Browserless Chrome engine.

Request Body

JSON

{
  "url": "https://example.com",
  "fullPage": true,
  "width": 1280
}

Response

JSON

{
  "data": {
    "url": "https://example.com",
    "screenshotUrl": "https://storage.scraper.bot/screenshots/scr_1710000000.png",
    "width": 1280,
    "height": 2400,
    "capturedAt": "2026-03-19T12:00:00Z"
  }
}

Examples

curl

curl -X POST https://scraper.bot/api/screenshot \
  -H "X-API-Key: scr_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","fullPage":true}'

JavaScript

const res = await fetch("/api/screenshot", {
  method: "POST",
  headers: {
    "X-API-Key": "scr_live_your_key_here",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ url: "https://example.com", fullPage: true }),
});
const { data } = await res.json();

POST/tickets

Submit a trouble ticket or bug report. Supports visual bug reports with element selectors.

Request Body

JSON

{
  "subject": "Flow fails on login page",
  "description": "The flow times out when trying to click the login button",
  "type": "bug",
  "priority": "high",
  "flowId": "flow-1",
  "screenshot": "data:image/png;base64,..."
}

Response

JSON

{
  "data": {
    "id": "ticket-1710000000000",
    "subject": "Flow fails on login page",
    "status": "open",
    "priority": "high",
    "createdAt": "2026-03-19T12:00:00Z"
  }
}

Examples

curl

curl -X POST https://scraper.bot/api/tickets \
  -H "X-API-Key: scr_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"subject":"Flow fails on login page","type":"bug","priority":"high"}'

JavaScript

const res = await fetch("/api/tickets", {
  method: "POST",
  headers: {
    "X-API-Key": "scr_live_your_key_here",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    subject: "Flow fails on login page",
    type: "bug",
    priority: "high",
  }),
});
const { data } = await res.json();

GET/activity

Retrieve the recent activity feed for the authenticated user.

Query Parameters

Name	Type	Description
`limit`	number	Number of entries (default 20)

Response

JSON

{
  "data": [
    {
      "id": "act-1",
      "type": "run.completed",
      "message": "Product Monitor completed successfully",
      "flowId": "flow-1",
      "timestamp": "2026-03-19T11:30:00Z"
    }
  ],
  "total": 45
}

Examples

curl

curl https://scraper.bot/api/activity?limit=10 \
  -H "X-API-Key: scr_live_your_key_here"

JavaScript

const res = await fetch("/api/activity?limit=10", {
  headers: { "X-API-Key": "scr_live_your_key_here" },
});
const { data } = await res.json();

GET/webhooks

List all configured webhooks for the authenticated user.

Response

JSON

{
  "data": [
    {
      "id": "wh-1",
      "url": "https://example.com/webhook",
      "events": ["run.completed", "alert.created"],
      "active": true,
      "createdAt": "2026-03-10T10:00:00Z"
    }
  ],
  "total": 2
}

Examples

curl

curl https://scraper.bot/api/webhooks \
  -H "X-API-Key: scr_live_your_key_here"

JavaScript

const res = await fetch("/api/webhooks", {
  headers: { "X-API-Key": "scr_live_your_key_here" },
});
const { data } = await res.json();

POST/webhooks

Create a new webhook endpoint to receive event notifications.

Request Body

JSON

{
  "url": "https://example.com/webhook",
  "events": ["run.completed", "run.failed", "alert.created"],
  "secret": "whsec_your_signing_secret"
}

Response

JSON

{
  "data": {
    "id": "wh-1710000000000",
    "url": "https://example.com/webhook",
    "events": ["run.completed", "run.failed", "alert.created"],
    "active": true,
    "createdAt": "2026-03-19T12:00:00Z"
  }
}

Examples

curl

curl -X POST https://scraper.bot/api/webhooks \
  -H "X-API-Key: scr_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/webhook","events":["run.completed"]}'

JavaScript

const res = await fetch("/api/webhooks", {
  method: "POST",
  headers: {
    "X-API-Key": "scr_live_your_key_here",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://example.com/webhook",
    events: ["run.completed", "run.failed"],
  }),
});
const { data } = await res.json();

Ready to integrate?

Create your first flow in minutes. No credit card required.

Get Your API Key