WooScraper REST API

Programmatic access to the same surface the dashboard uses. Useful for agencies running batches, custom CRM integrations, or anything where the Chrome extension isn't a fit.

Authentication

Mint a key at /dashboard/api-keys — we show the secret once. Send it on every request:

curl https://wooscraper.com/api/v1/jobs \
  -H "Authorization: Bearer ws_live_…"

Rate limiting

120 requests/minute per key. Exceeding returns 429 with a retry-after header.

Endpoints

Machine-readable: /api/v1/docs (compact JSON) · /api/v1/openapi.json (OpenAPI 3.1 — drop into Postman, Insomnia, or any code-gen tool).

Create a job

curl -X POST https://wooscraper.com/api/v1/jobs \
  -H "Authorization: Bearer ws_live_…" \
  -H "content-type: application/json" \
  -d '{
    "sourceUrl": "https://www.allbirds.com",
    "sourcePlatform": "shopify",
    "mode": "fast"
  }'

Ship raw responses

Batches of up to 50 raw responses (HTML or JSON). Each item must include the original URL, content-type, status, and body. Use encoding: "base64" for binary payloads.

curl -X POST https://wooscraper.com/api/v1/jobs/$JOB/raw \
  -H "Authorization: Bearer ws_live_…" \
  -H "content-type: application/json" \
  -d '{
    "items": [{
      "url": "https://example.com/products.json?page=1",
      "contentType": "application/json",
      "status": 200,
      "body": "{\"products\":[...]}"
    }]
  }'

Mark complete, then export

curl -X POST https://wooscraper.com/api/v1/jobs/$JOB/complete \
  -H "Authorization: Bearer ws_live_…"

curl -X POST https://wooscraper.com/api/v1/jobs/$JOB/export \
  -H "Authorization: Bearer ws_live_…" \
  -H "content-type: application/json" \
  -d '{"kind":"woo-csv"}'

Poll for the export URL

curl https://wooscraper.com/api/v1/jobs/$JOB/exports \
  -H "Authorization: Bearer ws_live_…"

Scheduled re-scrapes

curl -X POST https://wooscraper.com/api/v1/watches \
  -H "Authorization: Bearer ws_live_…" \
  -H "content-type: application/json" \
  -d '{
    "sourceUrl": "https://competitor.com",
    "sourcePlatform": "shopify",
    "interval": "daily"
  }'

Typical agency flow

1. POST /jobs with the customer's source URL.
2. Have your scraper fetch source pages and POST batches to /jobs/:id/raw.
3. POST /jobs/:id/complete when discovery is done.
4. POST /jobs/:id/export for each format the customer needs.
5. Poll /jobs/:id/exports and download the Blob URLs.

Client snippets

Node.js

const KEY = process.env.WS_KEY;
const BASE = "https://wooscraper.com/api/v1";

async function ws(path, init = {}) {
  const res = await fetch(BASE + path, {
    ...init,
    headers: {
      authorization: `Bearer ${KEY}`,
      "content-type": "application/json",
      ...(init.headers ?? {}),
    },
  });
  if (!res.ok) throw new Error(`${path} → ${res.status}: ${await res.text()}`);
  return res.json();
}

const { job } = await ws("/jobs", {
  method: "POST",
  body: JSON.stringify({
    sourceUrl: "https://www.allbirds.com",
    sourcePlatform: "shopify",
  }),
});
console.log("job", job.id);

Python

import os, requests

KEY = os.environ["WS_KEY"]
BASE = "https://wooscraper.com/api/v1"

def ws(path, **kwargs):
    headers = {"authorization": f"Bearer {KEY}", **kwargs.pop("headers", {})}
    r = requests.request(kwargs.pop("method", "GET"), BASE + path,
                         headers=headers, **kwargs)
    r.raise_for_status()
    return r.json()

job = ws("/jobs", method="POST", json={
    "sourceUrl": "https://www.allbirds.com",
    "sourcePlatform": "shopify",
})["job"]
print("job", job["id"])

OpenAPI codegen

Generate a fully-typed client in any language with openapi-generator against /api/v1/openapi.json:

openapi-generator-cli generate \
  -i https://wooscraper.com/api/v1/openapi.json \
  -g typescript-fetch \
  -o ./wooscraper-client