REST API overview

The REST surface that everything else (portal, MCP gateway, SDKs) is built on. Standard JSON over HTTPS.

Base URL


https://portal.scrapewise.ai/api/scraper-api

All endpoints below use this prefix. Throughout the docs, paths like /api/key/whoami mean https://portal.scrapewise.ai/api/scraper-api/api/key/whoami.

Headers

Every request:

Header	Required	Value
`Authorization`	yes	`Bearer <token>` — see Authentication
`Content-Type`	for POST / PUT / PATCH	`application/json`
`Accept`	recommended	`application/json` (default response type)

Optional but useful:

Header	Purpose
`Idempotency-Key`	Provide a UUID. If a network blip causes you to retry, the same idempotency key won’t double-execute the side effect. Supported on `POST /api/scraper` (create) and `POST /api/scraper/{id}/run` (trigger).
`X-Request-Id`	Your trace ID. Echoed in response + logged server-side. Useful for cross-system correlation.

Pagination

Read endpoints that can return many rows (/api/scraper/data, /api/scraper/list, etc.) use cursor-based pagination.

Request:


GET /api/scraper/data?scraperId=...&limit=100&cursor=eyJsYXN0SWQi...

Response:


{
  "items": [ /* up to limit rows */ ],
  "nextCursor": "eyJsYXN0SWQi...",
  "hasMore": true
}

To paginate:

First call: omit cursor, set limit (default 100, max 1000)
Use nextCursor from the response as cursor on the next call
Stop when hasMore: false (and nextCursor is null)

Cursors are opaque base64. Don’t try to parse them — they may include sort-state, snapshot IDs, etc.

Filtering + sorting

Most list endpoints accept query params:

Param	Example	Effect
`q`	`q=widget`	Free-text search on relevant fields
`sort`	`sort=createdAt:desc`	Sort by field + direction
`from`	`from=2026-05-01T00:00:00Z`	Only items at or after this timestamp
`to`	`to=2026-05-19T23:59:59Z`	Only items at or before

For full filter syntax on a specific endpoint, see that endpoint’s page in the sidebar.

Errors

All errors return JSON in the problem-details envelope:


{
  "status": 422,
  "code": "validation_failed",
  "title": "Validation failed",
  "detail": "Field 'startUrls' must be a non-empty array.",
  "correlationId": "req_..."
}

Switch on code (machine-readable, stable). Include correlationId in support tickets.

Rate limits

Per-key default: ~60 requests/minute for most endpoints, ~600 requests/hour for read endpoints. Trigger endpoints (run a scraper) have lower limits.

When limited, 429 Too Many Requests with Retry-After: <seconds> header. Back off and retry.

OpenAPI spec

Live spec served at:


https://portal.scrapewise.ai/api/scraper-api/v3/api-docs

Plus a Redoc-rendered browser view (when shipped — pending PR-Docs3). The spec is the source of truth — if this doc and the spec disagree, the spec wins.

For MCP-tag-only filter (the subset exposed to MCP agents):


https://portal.scrapewise.ai/api/scraper-api/v3/api-docs/mcp

Top-5 endpoints

The fastest path to “useful” — covered in detail below:

Endpoint	Page
`POST /api/scraper-simple/preview-from-url`	Preview
`POST /api/scraper` + `GET /api/scraper/{id}/run`	Scrapers
`GET /api/scraper/data`	Data
`PUT /api/key/generate` + `/api/key/list` + `/api/key/{id}` (DELETE)	API keys
Full surface (every endpoint)	Reference

What’s next

Fastest “hello world” → Preview
Create + run a real scraper → Scrapers
Read scraped data → Data