PageShot API
Free Screenshot & Webpage Capture API for developers. Capture any public URL as a PNG/JPEG/WebP image via a simple REST API.
Features
- URL → Image —
GETorPOSTto capture any public webpage - Full-page capture — render the entire scrollable page
- Device emulation — custom viewport, scale factor, user-agent
- Element selector — capture a specific CSS selector on the page
- Dark mode — force
prefers-color-scheme: dark - Ad blocking — block common ad/tracker domains
- CSS injection — apply custom styles before capture
- Multiple formats — PNG, JPEG, WebP with quality control
- SSRF protection — private/internal IPs are blocked
- Rate limiting — 30 req/min per API key
- Free tier — 100 screenshots/month, no credit card required
Tech Stack
| Layer | Technology |
|---|---|
| Runtime | Node.js 20+ |
| Framework | Express 4 |
| Browser | Playwright (Chromium, headless) |
| Image processing | Sharp |
| Security | Helmet, CORS, rate limiting |
| Deployment | Docker → Azure Web App |
Quick Start
Prerequisites
- Node.js 20 or later
- npm (comes with Node.js)
Install & Run
# Clone the repo
git clone https://github.com/your-org/pageshot-api.git
cd pageshot-api
# Install dependencies
npm install
# Install Playwright's Chromium browser
npx playwright install chromium
# Start the development server (auto-reload on changes)
npm run dev
The server starts at http://localhost:3000.
| URL | Description |
|---|---|
| http://localhost:3000 | Landing page |
| http://localhost:3000/docs | API documentation |
| http://localhost:3000/v1 | API info endpoint |
| http://localhost:3000/health | Health check |
Take a Screenshot
curl "http://localhost:3000/v1/screenshot?url=https://example.com" \
-H "Authorization: Bearer ps_live_demo" \
-o screenshot.png
Running with Docker
# Build and start
docker-compose up --build
# The API is available at http://localhost:3000
Or build the image manually:
docker build -t pageshot-api .
docker run -p 3000:8080 pageshot-api
API Endpoints
| Method | Path | Auth | Description |
|---|---|---|---|
GET |
/v1/screenshot |
Yes | Capture a URL, return the image directly |
POST |
/v1/screenshot |
Yes | Capture with JSON body, optional JSON response |
GET |
/v1/status |
No | Service health check |
GET |
/health |
No | Docker/container health check |
GET |
/docs |
No | Interactive API documentation |
GET |
/ |
No | Landing page |
Authentication
Pass your API key using any of these methods:
Authorization: Bearer ps_live_xxxxx
X-API-Key: ps_live_xxxxx
?api_key=ps_live_xxxxx
Keys are auto-registered on first use (demo mode).
Screenshot Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
url |
string | required | URL to capture |
width |
int | 1280 | Viewport width (320–3840) |
height |
int | 720 | Viewport height (200–2160) |
full_page |
bool | false | Capture the full scrollable page |
format |
string | png | Output format: png, jpeg, webp |
quality |
int | 80 | JPEG/WebP quality (1–100) |
dark_mode |
bool | false | Force dark color scheme |
block_ads |
bool | false | Block common ad/tracker domains |
selector |
string | — | CSS selector to capture |
delay |
int | 0 | Wait ms after page load before capture |
scale |
float | 1 | Device scale factor (1–3) |
user_agent |
string | — | Custom User-Agent string |
css |
string | — | CSS to inject before capture |
Environment Variables
| Variable | Default | Description |
|---|---|---|
PORT |
3000 (dev) / 8080 (prod) |
Server listen port |
NODE_ENV |
development |
development or production |
Project Structure
pageshot-api/
├── src/
│ ├── server.js # Express app & route wiring
│ ├── routes/
│ │ ├── screenshot.js # GET & POST /v1/screenshot
│ │ └── docs.js # /docs route
│ ├── middleware/
│ │ ├── apiKey.js # API key auth + usage tracking
│ │ └── rateLimit.js # Rate limiting
│ ├── services/
│ │ └── browser.js # Playwright browser management
│ └── public/ # Landing page & docs assets
├── Dockerfile # Production container image
├── docker-compose.yml # Local Docker development
└── package.json
Scripts
| Command | Description |
|---|---|
npm start |
Start the production server |
npm run dev |
Start with --watch (auto-reload on file changes) |
License
MIT
