v1.5.6 — Screenshot API

The All-Seeing Screenshot API

From Bifröst to your browser — crisp, reliable captures across all nine realms.

https://heimdall.page/capture
Request 
curl -X POST https://heimdall.page/capture \
  -H "Content-Type: application/json" \
  -d '{"url": "https://github.com"}'
Response 
{
  "success": true,
  "job_id": "a1b2c3_1703700000",
  "screenshot_id": "scr_7x8k2m9p4q",
  "status": "queued"
}

7-Day Screenshot Retention

Screenshots are stored for 7 days or until manually deleted using your screenshot_id. We recommend downloading and saving screenshots locally for long-term storage.

Features

Built for Developers

Everything you need to capture website screenshots at scale.

Async Processing

Queue screenshots and check status. No blocking requests.

Smart Caching

7-day cache with force refresh option. Fast repeat requests.

SSL Bypass

Handles certificate errors gracefully. Capture any site.

Retry Strategies

Multiple loading strategies for reliable captures.

Custom Viewport

Set width, height, and timeout per request.

Debug Endpoint

DNS, HTTP status, and detailed error tracking.

API Reference

Documentation

Complete endpoint reference with examples.

Capture Screenshots

POST /capture Request screenshot (async)

Parameters

NameTypeDefaultDescription
urlrequired string — URL to capture
widthoptional integer 1280 Viewport width
heightoptional integer 800 Viewport height
forceoptional boolean false Bypass cache

Example

cURL 
curl -X POST https://heimdall.page/capture \
  -H "Content-Type: application/json" \
  -d '{"url": "https://github.com", "width": 1920}'
POST /capture/sync Request screenshot (sync)

Same parameters as /capture. Waits for completion before returning.

Retrieve Screenshots

GET /screenshot/{url_hash} Get screenshot image

Example

cURL 
curl https://heimdall.page/screenshot/a0714cb80b6e5b4eeb72c2e1c620d35d \
  -o screenshot.png
GET /status/{job_id} Check job status

Response

JSON 
{
  "job_id": "a1b2c3_1703700000",
  "screenshot_id": "scr_7x8k2m9p4q",
  "status": "completed",
  "screenshot_path": "/screenshot/d41d8cd9...",
  "expires_at": "2025-01-04T10:30:00Z"
}

Delete Screenshots

DELETE /screenshot/{screenshot_id} Delete by screenshot_id

Example

cURL 
curl -X DELETE https://heimdall.page/screenshot/scr_7x8k2m9p4q

System

GET /health Health check
GET /stats Service statistics
GET /debug/{url} Debug capture attempt
Reference

Integration Examples

Quick start snippets for popular languages.

Python 
import requests

response = requests.post(
    "https://heimdall.page/capture/sync",
    json={"url": "https://github.com"}
)
data = response.json()

if data["success"]:
    # Save screenshot_id for later deletion
    screenshot_id = data["screenshot_id"]
    image_url = f"https://heimdall.page{data['path']}"
JavaScript 
const response = await fetch(
  "https://heimdall.page/capture/sync",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ url: "https://github.com" })
  }
);
const data = await response.json();
const imageUrl = `https://heimdall.page${data.path}`;

Error Codes

Status Error Description
400 Invalid URL The provided URL is malformed or missing
404 Not Found Screenshot or job not found
408 Timeout Page load exceeded timeout limit
429 Rate Limited Too many requests, please slow down
500 Capture Failed Screenshot capture failed (check /debug endpoint)

Configuration

Environment Variable Default Description
SCREENSHOT_DIR /data/screenshots Storage directory for screenshots
DEFAULT_TIMEOUT 45000 Page load timeout (ms)
DEFAULT_WIDTH 1280 Default viewport width
DEFAULT_HEIGHT 800 Default viewport height
MAX_CONCURRENT_JOBS 3 Maximum parallel captures
CACHE_DAYS 7 Cache duration in days