API Documentation

Everything you need to integrate Nightglass into your app.

Authentication

Nightglass supports two payment paths. Both hit the same screenshot engine.

Path A: API Key (Developers)

Authorization: Bearer ng_live_...

Path B: x402 (AI Agents)

No signup. No API key. Send a request — get a 402 with USDC payment details. Your x402 client pays automatically.

No auth header needed

Default behaviour: A request without an Authorization header returns HTTP 402 with x402 payment details. This is by design — AI agents discover the payment requirements and pay automatically.

Take a Screenshot

POST/api/v1/screenshot

Cost: $0.005 standard, $0.01 mockup

Parameter	Type	Required	Default	Description
url	string	Yes	—	URL to capture. Must include protocol.
format	string	No	'png'	'png', 'jpeg', or 'pdf'
width	integer	No	1280	Viewport width (320–3840)
height	integer	No	null	Viewport height. Null = natural height
fullPage	boolean	No	false	Capture entire scrollable page
darkMode	boolean	No	false	Force dark colour scheme
deviceScaleFactor	number	No	2	Device pixel ratio (1–3)
quality	integer	No	80	JPEG quality (1–100). Ignored for PNG/PDF
delay	integer	No	0	Wait ms after page load (0–10000)
style	string	No	—	Set to 'mockup' for beautified output
background	string	No	gradient	Mockup background: hex colour or 'gradient'
padding	integer	No	64	Mockup padding in pixels
borderRadius	integer	No	12	Mockup border radius in pixels
shadow	boolean	No	true	Mockup drop shadow
frame	string	No	'browser'	'browser', 'phone', or 'none'
blockCookieBanners	boolean	No	false	Dismiss cookie consent banners before capture
waitForSelector	string	No	—	CSS selector to wait for before capture
responseFormat	string	No	'binary'	'binary' or 'json' (base64 + metadata)

Examples

curl (API key)

curl -X POST https://nightglass.xyz/api/v1/screenshot \
  -H "Authorization: Bearer ng_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "format": "png", "style": "mockup"}' \
  --output screenshot.png

JavaScript (fetch)

const res = await fetch('https://nightglass.xyz/api/v1/screenshot', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ng_live_abc123...',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    url: 'https://example.com',
    format: 'png',
    fullPage: true,
    style: 'mockup',
    frame: 'browser',
  }),
});

const blob = await res.blob();

Python (requests)

import requests

response = requests.post(
    "https://nightglass.xyz/api/v1/screenshot",
    headers={"Authorization": "Bearer ng_live_abc123..."},
    json={
        "url": "https://example.com",
        "format": "png",
        "fullPage": True,
        "blockCookieBanners": True,
    },
)

with open("screenshot.png", "wb") as f:
    f.write(response.content)

HTML to Screenshot

POST/api/v1/html-to-screenshot

Cost: $0.005 — Send raw HTML instead of a URL. Max 500KB.

curl -X POST https://nightglass.xyz/api/v1/html-to-screenshot \
  -H "Authorization: Bearer ng_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "html": "<html><body><h1>Hello World</h1></body></html>",
    "width": 800,
    "format": "png"
  }' \
  --output rendered.png

Metadata Extraction

POST/api/v1/metadata

Cost: Free — Extract page metadata without taking a screenshot.

curl -X POST https://nightglass.xyz/api/v1/metadata \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

Response:

{
  "title": "Example Domain",
  "description": "This domain is for illustrative examples.",
  "ogImage": null,
  "ogTitle": null,
  "ogDescription": null,
  "favicon": "https://example.com/favicon.ico",
  "themeColor": null
}

Check Usage

GET/api/v1/usage

Returns balance and usage for the authenticated API key. API key auth only (not x402).

{
  "balance_cents": 245,
  "total_spent_cents": 5,
  "auto_topup_enabled": false,
  "recent_usage": [...]
}

Health Check

GET/api/v1/health

Public endpoint. No auth required.

Error Codes

All errors return JSON:

{ "error": { "code": "UNAUTHORIZED", "message": "..." } }

Code	HTTP Status	Description
UNAUTHORIZED	401	Invalid or missing API key
INSUFFICIENT_BALANCE	402	Balance too low — top up at /dashboard
RATE_LIMITED	429	Too many requests per second
INVALID_URL	422	URL not accessible or returned error
INVALID_PARAMS	400	Request body validation failed
RENDER_TIMEOUT	504	Page took > 30 seconds to load
RENDER_ERROR	500	Chromium crash or rendering failure

Pricing

Operation	Price
Standard screenshot	$0.005
Mockup mode	$0.01
HTML to screenshot	$0.005
Metadata extraction	Free

Signup bonus: 50 free screenshots ($2.50). Minimum top-up: $5. Credits never expire.