API Documentation

Authentication

All API requests require an API key. Include your key as a query parameter:

?apiKey=ss_your_api_key_here

Get your API key from the dashboard after signing up.

Screenshot Endpoint

GET/api/screenshot

Parameters

Parameter	Type	Required	Description
`url`	string	Yes	The website URL to capture
`apiKey`	string	Yes	Your API key
`width`	number	No	Viewport width (default: 1280, max: 3840)
`height`	number	No	Viewport height (default: 800, max: 2160)
`fullPage`	boolean	No	Capture full scrollable page (default: false)
`delay`	number	No	Wait X ms before capture (max: 10000)
`format`	string	No	Output format: "png", "jpeg", or "pdf" (default: png)
`pageSize`	string	No	PDF page size: "a4", "letter", or "legal" (default: a4, PDF only)
`landscape`	boolean	No	PDF landscape orientation (default: false, PDF only)
`printBackground`	boolean	No	Include background colors/images in PDF (default: true, PDF only)

Response

On success, returns the screenshot as binary image data with appropriate Content-Type header.

Response headers include X-Usage-Count and X-Usage-Limit for tracking.

Code Examples

cURL

# Basic screenshot
curl "https://screenurl-staging.automata.army/api/screenshot?url=https://example.com&apiKey=YOUR_API_KEY" \
  --output screenshot.png

# Full page JPEG with custom size
curl "https://screenurl-staging.automata.army/api/screenshot?url=https://example.com&apiKey=YOUR_API_KEY&width=1920&height=1080&fullPage=true&format=jpeg" \
  --output screenshot.jpg

# PDF export (A4, portrait)
curl "https://screenurl-staging.automata.army/api/screenshot?url=https://example.com&apiKey=YOUR_API_KEY&format=pdf" \
  --output page.pdf

# PDF export (Letter, landscape, with background)
curl "https://screenurl-staging.automata.army/api/screenshot?url=https://example.com&apiKey=YOUR_API_KEY&format=pdf&pageSize=letter&landscape=true&printBackground=true" \
  --output page.pdf

JavaScript (Node.js)

const fs = require('fs');

async function captureScreenshot(url) {
  const apiKey = 'YOUR_API_KEY';
  const endpoint = `https://screenurl-staging.automata.army/api/screenshot?url=${encodeURIComponent(url)}&apiKey=${apiKey}`;
  
  const response = await fetch(endpoint);
  
  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.message);
  }
  
  const buffer = await response.arrayBuffer();
  fs.writeFileSync('screenshot.png', Buffer.from(buffer));
  
  console.log('Screenshot saved!');
  console.log('Usage:', response.headers.get('X-Usage-Count'), '/', response.headers.get('X-Usage-Limit'));
}

captureScreenshot('https://example.com');

Python

import requests

def capture_screenshot(url, api_key, filename='screenshot.png', format='png'):
    endpoint = 'https://screenurl-staging.automata.army/api/screenshot'
    
    params = {
        'url': url,
        'apiKey': api_key,
        'width': 1280,
        'height': 800,
        'format': format
    }
    
    response = requests.get(endpoint, params=params)
    
    if response.status_code == 200:
        with open(filename, 'wb') as f:
            f.write(response.content)
        print(f'Saved to {filename}')
        print(f'Usage: {response.headers.get("X-Usage-Count")}/{response.headers.get("X-Usage-Limit")}')
    else:
        print(f'Error: {response.json()}')

# Screenshot as PNG
capture_screenshot('https://example.com', 'YOUR_API_KEY')

# Export as PDF
capture_screenshot('https://example.com', 'YOUR_API_KEY', 'page.pdf', 'pdf')

Ruby

require 'net/http'
require 'uri'

def capture_screenshot(url, api_key)
  uri = URI("https://screenurl-staging.automata.army/api/screenshot")
  uri.query = URI.encode_www_form({
    url: url,
    apiKey: api_key
  })
  
  response = Net::HTTP.get_response(uri)
  
  if response.code == '200'
    File.binwrite('screenshot.png', response.body)
    puts "Screenshot saved!"
  else
    puts "Error: #{response.body}"
  end
end

capture_screenshot('https://example.com', 'YOUR_API_KEY')

Error Codes

Code	Description
`400`	Bad Request - Missing or invalid URL parameter
`401`	Unauthorized - Missing or invalid API key
`429`	Rate Limit Exceeded - Monthly quota reached
`500`	Server Error - Screenshot capture failed (timeout, invalid site, etc.)

Error Response Format

{
  "error": "Error type",
  "message": "Detailed error message"
}

Rate Limits

Plan	Screenshots/Month	Price
Free	100	$0
Starter	1,000	$9/mo
Pro	5,000	$29/mo
Enterprise	Custom	Contact us

Usage resets on the first of each month. Check your current usage in the dashboard. See pricing page for details.