Guides / URL safety

URL safety and validation

Screenshot APIs are attractive SSRF vectors if they can reach internal services. ScreenNabster validates every URL before the worker navigates, rejecting schemes and hosts that commonly indicate loopback, private networks, or cloud metadata endpoints.

Overview

Validation happens in the API gateway using deterministic rules on the URL string you submit. Stronger deployments also re-check resolved IPs inside the worker to mitigate DNS rebinding; treat any internal resource as out of scope—use staging hosts on the public internet or ship HTML directly with the html field.

What is allowed

Schemes: http: and https: only.
Hosts that are not localhost, not obvious private IPv4 ranges, and not well-known metadata hostnames.
Either url or html must be present; you cannot omit both.

What is typically blocked

Examples include localhost, 127.0.0.0/8, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, link-local addresses, and cloud metadata hosts. These checks mirror the implementation in capture-schema.ts—refer to source if you need the exhaustive list for security reviews.

HTML alternative

When your content only exists on a VPN, render it server-side and POST the markup:

body.json

{
  "html": "<!DOCTYPE html><html>…</html>",
  "output": "png",
  "screen_width": 1200,
  "screen_height": 800
}

This path never performs outbound fetches to arbitrary internal URLs—only your supplied string is rendered—so it is the right pattern for air-gapped content pipelines.

Errors you will see

Blocked hosts and malformed URLs surface as 400 with VALIDATION_ERROR from Zod refiners. Example message fragment: “URL must be a publicly reachable HTTP/HTTPS address.”

curl

# This should fail validation before any worker cost:
curl -X POST "https://screennabster.com/api/v1/capture" \
  -H "X-API-Key: pk_live_…" \
  -H "Content-Type: application/json" \
  -d "{\"url\":\"http://127.0.0.1:8080/admin\"}"

Need help interpreting a specific failure? Cross-check the error catalog and your response body.