PixelPull API

Scan pages and download images from your own scripts. Generate a key under Dashboard → API key and send it as a bearer token. API downloads share your account quota and appear in your history.

Authentication

Authorization: Bearer pp_live_xxxxxxxxxxxxxxxxxxxxxxxx

POST /api/v1/scan

Find every image on one or more pages. Returns JSON.

curl -X POST https://YOUR-DOMAIN/api/v1/scan \
  -H "Authorization: Bearer $PIXELPULL_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": ["https://example.com/gallery"],
    "options": {
      "renderJs": true,          // headless browser
      "autoScroll": true,        // trigger lazy loading
      "waitMs": 1500,            // extra wait after load
      "crawlPages": 5,           // follow same-site links
      "ua": "desktop",           // desktop | mobile | bot
      "probe": true,             // measure width/height/bytes
      "sources": ["img","srcset","lazy","picture","css","meta","jsonld","icon","svg","link","video","data","network"]
    }
  }'

{
  "pages": ["https://example.com/gallery"],
  "images": [
    { "id": "3f1c…", "url": "https://example.com/a.jpg", "kind": "img", "alt": "Sunset",
      "page": "https://example.com/gallery", "type": "jpg", "width": 1920, "height": 1080,
      "bytes": 412331, "filename": "a.jpg" }
  ],
  "warnings": [],
  "rendered": true,
  "tookMs": 5321
}

POST /api/v1/download

Download images as a ZIP (or a single file with "zip": false). Pass image objects from a scan, or just { "url": "…" }.

curl -X POST https://YOUR-DOMAIN/api/v1/download \
  -H "Authorization: Bearer $PIXELPULL_KEY" \
  -H "Content-Type: application/json" \
  -o images.zip \
  -d '{
    "images": [{ "url": "https://example.com/a.jpg", "page": "https://example.com/gallery" }],
    "zip": true,
    "consent": true,             // required: you accept sole responsibility (see /terms#responsibility)
    "options": {
      "format": "webp",            // original | jpg | png | webp | avif
      "quality": 85,
      "maxWidth": 1920, "maxHeight": null,
      "stripMetadata": true,
      "background": "#ffffff",     // for transparent → jpg
      "namePattern": "{domain}-{n}-{w}x{h}",
      "folders": "type",           // flat | type | page | kind
      "manifest": "csv",           // none | csv | json
      "zipName": "my-images"
    }
  }'

Naming tokens

GET /api/v1/quota

curl https://YOUR-DOMAIN/api/v1/quota -H "Authorization: Bearer $PIXELPULL_KEY"

Errors

Error bodies look like { "error": "message", "code": "PRO_REQUIRED" }.