API Documentation

Authentication

API keys use the snap_ prefix and are passed as Bearer tokens. Generate keys from your dashboard.

Authorization: Bearer snap_your_api_key_here

Three authentication methods are supported:

1. API key (recommended for scripts and integrations) - Pass via the Authorization header as shown above. Keys are available on all tiers.
2. Session cookie (browser usage) - Automatically set when logged in via the web interface.
3. Anonymous - No auth required for basic captures. Free tier rate limits apply.

API keys are hashed with SHA-256 before storage. The raw key is shown only once at creation time and cannot be retrieved again.

POST/api/capture

Capture a webpage using server-side rendering. Snapoena visits the URL with a headless browser, takes a full-page screenshot, embeds a metadata bar (URL, timestamp), computes a SHA-256 hash, and requests an RFC 3161 trusted timestamp.

Request body

Response (200)

{
  "id": "abc123xyz",
  "url": "https://example.com",
  "timestamp": "2026-03-26T14:30:00.000Z",
  "sha256": "a3f2b8c1d4e5f6...",
  "imageUrl": "https://pub-xxx.r2.dev/captures/abc123xyz.png",
  "htmlUrl": "https://pub-xxx.r2.dev/captures/abc123xyz.html",
  "pageTitle": "Example Domain",
  "truncated": false,
  "durationMs": 3200,
  "viewport": "desktop",
  "tsrVerified": true,
  "whoisAvailable": true,
  "dnsAvailable": true,
  "harAvailable": true,
  "mhtmlAvailable": true,
  "tlsAvailable": true,
  "serverIp": "203.0.113.1",
  "serverLocation": "US"
}

POST/api/capture/extension

Submit a capture from the browser extension. Unlike the server-side capture endpoint, the extension captures the visible tab locally and sends the data here for processing. This works for authenticated or logged-in pages that the server cannot access.

API key authentication is required. Anonymous extension captures are not supported.

Request body

Response (200)

{
  "id": "ext_abc123",
  "url": "https://app.example.com/dashboard",
  "timestamp": "2026-03-26T14:30:00.000Z",
  "sha256": "b4c3d2e1f0...",
  "imageUrl": "https://pub-xxx.r2.dev/captures/ext_abc123.png",
  "htmlUrl": "https://pub-xxx.r2.dev/captures/ext_abc123.html",
  "pageTitle": "Dashboard",
  "durationMs": 1200,
  "captureMethod": "extension",
  "tsrVerified": true
}

Maximum payload size: 50 MB. Request timeout: 60 seconds.

POST/api/bulk

Capture multiple URLs in a single request. URLs are processed sequentially, and each counts against your monthly capture quota. Requires authentication (API key or session).

Request body

Response (200)

{
  "results": [
    {
      "url": "https://example.com",
      "id": "abc123",
      "status": "success"
    },
    {
      "url": "https://invalid.test",
      "status": "error",
      "error": "Could not resolve domain: invalid.test"
    }
  ],
  "summary": {
    "total": 2,
    "succeeded": 1,
    "failed": 1
  }
}

Individual URL failures do not fail the entire batch. Each result includes its own status.

POST/api/capture/[id]/extend

Extend the retention period of a capture. Only available to Pro and Enterprise users. You must own the capture. Authentication is via session cookie (not API key).

Request

No request body is needed. The capture ID is in the URL path.

Response (200)

{
  "success": true,
  "expiresAt": "2027-03-26T14:30:00.000Z",
  "retentionDays": 365
}

Error responses

• 401 - UNAUTHORIZED - Login required or session expired
• 403 - UPGRADE_REQUIRED - Free tier cannot extend retention
• 403 - FORBIDDEN - You do not own this capture
• 404 - NOT_FOUND - Capture not found or expired

Download endpoints

After a capture completes, use these endpoints to download individual artifacts. All are GET requests with the capture ID in the path.

Search and export

All search endpoints require authentication.

• GET /api/captures/search?q= - Search captures by URL
• GET /api/captures/text-search?q= - Search captures by page content
• GET /api/captures/export - Export captures as CSV

Monitors

Monitors automatically capture a URL on a schedule. Available on Pro (10 monitors) and Enterprise (unlimited) tiers.

• GET /api/monitors - List your monitors (authenticated)
• POST /api/monitors - Create a monitor (Pro/Enterprise)

Actions

• POST /api/capture/{id}/send - Send evidence via email (authenticated)

Rate limits

Every API response includes rate limit headers:

X-RateLimit-Limit: 20
X-RateLimit-Remaining: 17
X-RateLimit-Reset: 1711500000

When the limit is exceeded, the response also includes a Retry-After header with the number of seconds until the limit resets. The HTTP status will be 429 Too Many Requests.

Tier limits

See pricing for full plan details.

Error codes

All errors return a consistent JSON structure:

{
  "error": {
    "code": "INVALID_URL",
    "message": "Only http and https URLs are allowed."
  }
}

Code examples

Capture a URL with curl

curl -X POST https://snapoena.com/api/capture \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer snap_your_api_key" \
  -d '{"url": "https://example.com"}'

Capture with options

curl -X POST https://snapoena.com/api/capture \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer snap_your_api_key" \
  -d '{
    "url": "https://example.com",
    "viewport": "mobile",
    "watermark": false,
    "note": "Evidence for Case #12345"
  }'

JavaScript (fetch)

const response = await fetch("https://snapoena.com/api/capture", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer snap_your_api_key",
  },
  body: JSON.stringify({
    url: "https://example.com",
    viewport: "desktop",
  }),
});

const data = await response.json();

if (!response.ok) {
  console.error("Capture failed:", data.error.code, data.error.message);
} else {
  console.log("Capture ID:", data.id);
  console.log("Screenshot:", data.imageUrl);
  console.log("SHA-256:", data.sha256);
  console.log("Timestamp verified:", data.tsrVerified);
}

Bulk capture with curl

curl -X POST https://snapoena.com/api/bulk \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer snap_your_api_key" \
  -d '{
    "urls": [
      "https://example.com",
      "https://example.org",
      "https://example.net"
    ]
  }'

Download the evidence bundle

# After capturing, download the full evidence ZIP
curl -O https://snapoena.com/api/capture/abc123xyz/bundle

Handle rate limits

const response = await fetch("https://snapoena.com/api/capture", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer snap_your_api_key",
  },
  body: JSON.stringify({ url: "https://example.com" }),
});

// Check rate limit headers
const remaining = response.headers.get("X-RateLimit-Remaining");
const limit = response.headers.get("X-RateLimit-Limit");
console.log(`Captures remaining: ${remaining}/${limit}`);

if (response.status === 429) {
  const retryAfter = response.headers.get("Retry-After");
  console.log(`Rate limited. Retry after ${retryAfter} seconds.`);
}

Notes

• All responses are JSON unless otherwise noted (e.g. download endpoints return binary data).
• Server-side capture (/api/capture) cannot access authenticated or login-gated pages. Use the extension endpoint for those.
• Free tier captures are stored for 7 days. Pro captures are kept for 1 year. Enterprise retention is unlimited.
• SSRF protection: private IPs and internal networks are blocked.
• RFC 3161 timestamps are provided by FreeTSA (freetsa.org).
• WHOIS lookups are available for .com and .net domains only.
• DNS, TLS, and WHOIS evidence supplements are added automatically for paid tier extension captures.