REST quickstart

Five minutes to your first scraped row. We’ll use the preview-from-url endpoint — the fastest way to get data out of Scrapewise without setting up a scraper, schema, or schedule.

Prerequisites

A Scrapewise account (sign up takes 2 minutes)
An API key with scope USER (default) or higher

Set the key as an env var so you don’t paste it into every command:


export SCRAPEWISE_KEY="sw_live_abc1234.your-secret-here"

One-shot scrape with curl

POST /api/scraper-simple/preview-from-url takes a URL and returns a preview of what Scrapewise can extract from it. No scraper saved, no job state, no schema definition — just the data.


curl -X POST \
  -H "Authorization: Bearer $SCRAPEWISE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/products/some-page",
    "fields": ["title", "price", "description"]
  }' \
  "https://portal.scrapewise.ai/api/scraper-api/api/scraper-simple/preview-from-url"

The response:


{
  "url": "https://example.com/products/some-page",
  "fields": {
    "title": "Some Product Name",
    "price": "29.99",
    "description": "A long description of the product..."
  },
  "elapsedMs": 1247
}

That’s it. You scraped a page.

What just happened

Scrapewise loaded the URL (using a real browser, so JavaScript-rendered content works).
It used the fields list as hints for what to look for. The fields can be:
- Common product/article terms (title, price, description, image, author, date)
- Custom hints — try ["main heading", "primary call-to-action button text"]
The extracted values come back as a flat JSON object.

Going further — save it as a real scraper

preview-from-url is for exploration. When you want to scrape many similar pages on a schedule, create a real scraper:


curl -X POST \
  -H "Authorization: Bearer $SCRAPEWISE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-first-scraper",
    "startUrls": ["https://example.com/products"],
    "schema": {
      "title": "string",
      "price": "number",
      "in_stock": "boolean"
    }
  }' \
  "https://portal.scrapewise.ai/api/scraper-api/api/scraper"

Then trigger a run + read the results:


# Get the scraper ID from the create-response above, then:
SCRAPER_ID="..."
 
# Trigger a run
curl -H "Authorization: Bearer $SCRAPEWISE_KEY" \
  "https://portal.scrapewise.ai/api/scraper-api/api/scraper/${SCRAPER_ID}/run"
 
# Watch progress (SSE stream)
curl -N -H "Authorization: Bearer $SCRAPEWISE_KEY" \
  "https://portal.scrapewise.ai/api/scraper-api/api/scraper/${SCRAPER_ID}/stream-job-status"
 
# Read scraped rows
curl -H "Authorization: Bearer $SCRAPEWISE_KEY" \
  "https://portal.scrapewise.ai/api/scraper-api/api/scraper/data?scraperId=${SCRAPER_ID}"

Node.js example

Same flow in TypeScript:


const SCRAPEWISE_KEY = process.env.SCRAPEWISE_KEY!;
const BASE = "https://portal.scrapewise.ai/api/scraper-api";
 
const res = await fetch(`${BASE}/api/scraper-simple/preview-from-url`, {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${SCRAPEWISE_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://example.com/products/some-page",
    fields: ["title", "price", "description"],
  }),
});
 
if (!res.ok) {
  throw new Error(`Scrapewise: ${res.status} ${await res.text()}`);
}
 
const data = await res.json();
console.log(data.fields);

Python example


import os, requests
 
SCRAPEWISE_KEY = os.environ["SCRAPEWISE_KEY"]
BASE = "https://portal.scrapewise.ai/api/scraper-api"
 
r = requests.post(
    f"{BASE}/api/scraper-simple/preview-from-url",
    headers={"Authorization": f"Bearer {SCRAPEWISE_KEY}"},
    json={
        "url": "https://example.com/products/some-page",
        "fields": ["title", "price", "description"],
    },
)
r.raise_for_status()
print(r.json()["fields"])

Common errors

Status	Meaning	Fix
`401 Unauthorized`	Missing / invalid `Authorization: Bearer …` header	Check the `Bearer` prefix (with space). Re-mint key if revoked.
`403 Forbidden` (with `scope_rejected`)	Your key’s scope can’t call this endpoint	Mint a higher-scope key — see Scopes
`429 Too Many Requests`	Rate-limited	Wait the `Retry-After` seconds in the response header
`503 Service Unavailable`	Scrapewise overloaded or briefly down	Retry with exponential backoff

For the full error format, see Errors.

What’s next

Connect Claude to do this via natural language → MCP quickstart
Full REST reference → REST API overview
Understand the data model → Concepts