Quickstart

This guide will get you all set up and ready to use the Screenshot API. We'll cover how to get started with API authentication and how to capture your first screenshot. We'll also look at the complete workflow from job creation to result retrieval.

Before you can make requests to the Screenshot API, you will need an API key. Contact your administrator to obtain your API key.

Making your first screenshot request

The Screenshot API follows an asynchronous workflow. You submit a screenshot job, receive a job ID, then poll for the result. Here's how to capture your first screenshot:

Step 1: Create a screenshot job

Submit a POST request to create a new screenshot job:

curl -X POST https://api.webcapture.ai/screenshot \
  -H "x-api-key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "viewport": {
      "width": 1200,
      "height": 800
    },
    "format": "png",
    "fullPage": false
  }'

This will return a response like:

{
  "message": "Screenshot job created",
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "statusUrl": "/screenshot/status/550e8400-e29b-41d4-a716-446655440000"
}

Step 2: Check job status

Use the job ID to check the status and retrieve the result when completed:

curl https://api.webcapture.ai/screenshot/status/550e8400-e29b-41d4-a716-446655440000 \
  -H "x-api-key: your_api_key_here"

When completed, you'll receive a response with the screenshot URL:

{
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "createdAt": "2023-12-07T10:30:00Z",
  "completedAt": "2023-12-07T10:30:15Z",
  "result": {
    "url": "https://example.com",
    "format": "png",
    "resultUrl": "/screenshot/files/550e8400-e29b-41d4-a716-446655440000.png",
    "fileSize": 245760,
    "dimensions": {
      "width": 1200,
      "height": 800
    }
  },
  "directUrl": "https://api.webcapture.ai/screenshot/files/550e8400-e29b-41d4-a716-446655440000.png"
}

Advanced examples

Mobile screenshot with device emulation

curl -X POST https://api.webcapture.ai/screenshot \
  -H "x-api-key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "viewport": {
      "width": 375,
      "height": 812
    },
    "deviceEmulation": "iPhone X",
    "deviceOrientation": "portrait",
    "format": "jpeg",
    "quality": 90
  }'

Full page PDF generation

curl -X POST https://api.webcapture.ai/screenshot \
  -H "x-api-key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "viewport": {
      "width": 1200,
      "height": 800
    },
    "outputType": "pdf",
    "fullPage": true,
    "pdfOptions": {
      "format": "A4",
      "landscape": false,
      "printBackground": true,
      "margin": {
        "top": "0.5in",
        "bottom": "0.5in",
        "left": "0.5in",
        "right": "0.5in"
      }
    }
  }'

Screenshot with custom headers and cookies

curl -X POST https://api.webcapture.ai/screenshot \
  -H "x-api-key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "viewport": {
      "width": 1200,
      "height": 800
    },
    "headers": {
      "User-Agent": "MyBot/1.0",
      "Accept-Language": "en-US,en;q=0.9"
    },
    "cookies": [
      {
        "name": "session_id",
        "value": "abc123",
        "domain": "example.com"
      }
    ]
  }'

What's next?

Great, you've captured your first screenshot! Here are some helpful resources as you explore more of the Screenshot API:

Complete API reference - All endpoints and parameters
Authentication guide - API key setup and security
Error handling guide - Understanding error responses

Explore the full Screenshot API