# Screenshotty - Full Documentation

> A powerful screenshot API that captures high-quality screenshots of websites or raw HTML content.

Screenshotty is a website screenshot API available on RapidAPI. It enables developers to programmatically capture screenshots of any webpage with extensive customization options including custom viewports, JavaScript/CSS injection, element selection, geo-targeting, and more.

## API Information

- **Base URL**: https://screenshotty1.p.rapidapi.com
- **Version**: 1.1.0
- **Category**: Tools
- **Tags**: screenshot, web capture, pdf, website, image, render, browser

## Authentication

All requests require RapidAPI authentication headers:

```
X-RapidAPI-Key: YOUR_RAPIDAPI_KEY
X-RapidAPI-Host: screenshotty1.p.rapidapi.com
```

Subscribe at: https://rapidapi.com/nexus-apis-nexus-apis-default/api/screenshotty1

---

## Endpoints

### POST /v1/screenshot

Capture a screenshot of a URL or HTML content. Recommended for complex requests with cookies, headers, or code injection.

**Request Body** (application/json):

```json
{
  "url": "https://example.com",
  "format": "image/png",
  "viewport_width": 1920,
  "viewport_height": 1080,
  "full_page": true
}
```

### GET /v1/screenshot

Same functionality using query parameters. Useful for embedding URLs directly in HTML `<img>` tags.

**Example**: `/v1/screenshot?url=https://example.com&format=image/png`

### GET /v1/screenshot/countries

Returns list of available country codes for geo-targeting.

**Response**:
```json
{
  "countries": ["US", "UK", "DE", "FR", "JP", "BR"]
}
```

---

## Parameters Reference

### Required (one of)

| Parameter | Type | Description |
|-----------|------|-------------|
| url | string (uri) | URL of the webpage to capture |
| html | string | Raw HTML content to render and capture |

### Output Options

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| format | string | image/png | Output format. Options: image/png, image/jpg, image/jpeg, image/gif, image/webp, image/jp2, image/tiff, application/pdf |
| response_type | string | image | Response format. Options: image (binary), json/url (JSON with URL), redirect (302 redirect), file (binary) |

### Viewport Options

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| viewport_width | integer | 1920 | Browser viewport width (1-3840 pixels) |
| viewport_height | integer | 1080 | Browser viewport height (1-3840 pixels) |
| viewport_preset | string | - | Device preset: desktop, desktop_hd, desktop_4k, tablet, tablet_landscape, mobile, mobile_landscape, mobile_android, mobile_android_landscape, iphone_se, iphone_14, iphone_14_pro, iphone_14_pro_max, iphone_15, iphone_15_pro_max |
| device_scale_factor | integer | 1 | Pixel density (1-3). Use 2 for Retina displays |

### Capture Options

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| full_page | boolean | true | Capture entire scrollable page content |
| selector | string | - | CSS selector to capture specific element only |
| crop_x | integer | - | X coordinate of crop region top-left corner |
| crop_y | integer | - | Y coordinate of crop region top-left corner |
| crop_width | integer | - | Width of crop region |
| crop_height | integer | - | Height of crop region |
| transparent_background | boolean | false | Make background transparent (PNG only) |

### Timing Options

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| ready_event | string | domcontentloaded | When page is ready: load, domcontentloaded, networkidle, networkidle2, networkidle0 |
| wait_ms | integer | - | Additional wait time after ready_event (milliseconds) |
| scroll_to_bottom | boolean | false | Scroll page to bottom before capture (triggers lazy loading) |

### Code Injection

| Parameter | Type | Description |
|-----------|------|-------------|
| javascript_code | string | JavaScript code to execute before capture |
| css_code | string | CSS code to inject before capture |

**JavaScript Examples**:
```javascript
// Remove elements
document.querySelector('.cookie-banner')?.remove();

// Click buttons
document.querySelectorAll('.accordion-toggle').forEach(btn => btn.click());

// Modify content
document.querySelector('h1').textContent = 'Custom Title';
```

**CSS Examples**:
```css
/* Hide elements */
.advertisement { display: none !important; }

/* Change styles */
body { font-family: 'Inter', sans-serif !important; }
```

### Page Appearance

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| light_mode | string | default | Color scheme: default, light, dark |
| adblock | boolean | false | Block ads and trackers |
| block_cookie_banner | boolean | false | Remove cookie consent banners and GDPR popups |

### Request Customization

| Parameter | Type | Description |
|-----------|------|-------------|
| user_agent | string | Custom User-Agent string |
| language | string | Browser language code (e.g., en-US, fr-FR) |
| country | string | ISO 3166-1 alpha-2 country code for geo-targeting |
| http_headers | object | Custom HTTP headers (JSON object) |
| cookies | array | Array of cookie objects for authenticated pages |

**Cookie Object Structure**:
```json
{
  "name": "session_id",
  "value": "abc123",
  "domain": "example.com",
  "path": "/",
  "expires": 1735689600,
  "httpOnly": false,
  "secure": false,
  "sameSite": "Lax"
}
```

---

## Code Examples

### cURL

```bash
curl -X POST "https://screenshotty1.p.rapidapi.com/v1/screenshot" \
  -H "Content-Type: application/json" \
  -H "X-RapidAPI-Key: YOUR_API_KEY" \
  -H "X-RapidAPI-Host: screenshotty1.p.rapidapi.com" \
  -d '{
    "url": "https://example.com",
    "format": "image/png",
    "viewport_width": 1920,
    "viewport_height": 1080,
    "full_page": true
  }' \
  --output screenshot.png
```

### Node.js (Fetch)

```javascript
const fs = require('fs');

const response = await fetch(
  "https://screenshotty1.p.rapidapi.com/v1/screenshot",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-RapidAPI-Key": "YOUR_API_KEY",
      "X-RapidAPI-Host": "screenshotty1.p.rapidapi.com"
    },
    body: JSON.stringify({
      url: "https://example.com",
      format: "image/png",
      viewport_width: 1920,
      viewport_height: 1080,
      full_page: true
    })
  }
);

const buffer = await response.arrayBuffer();
fs.writeFileSync("screenshot.png", Buffer.from(buffer));
```

### Node.js (Axios)

```javascript
const axios = require('axios');
const fs = require('fs');

const response = await axios.post(
  "https://screenshotty1.p.rapidapi.com/v1/screenshot",
  {
    url: "https://example.com",
    format: "image/png",
    viewport_width: 1920,
    viewport_height: 1080,
    full_page: true
  },
  {
    headers: {
      "X-RapidAPI-Key": "YOUR_API_KEY",
      "X-RapidAPI-Host": "screenshotty1.p.rapidapi.com"
    },
    responseType: "arraybuffer"
  }
);

fs.writeFileSync("screenshot.png", response.data);
```

### Python

```python
import requests

url = "https://screenshotty1.p.rapidapi.com/v1/screenshot"

payload = {
    "url": "https://example.com",
    "format": "image/png",
    "viewport_width": 1920,
    "viewport_height": 1080,
    "full_page": True
}

headers = {
    "Content-Type": "application/json",
    "X-RapidAPI-Key": "YOUR_API_KEY",
    "X-RapidAPI-Host": "screenshotty1.p.rapidapi.com"
}

response = requests.post(url, json=payload, headers=headers)

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

### Java

```java
import java.net.http.*;
import java.net.URI;
import java.nio.file.*;

HttpClient client = HttpClient.newHttpClient();

String jsonBody = """
    {
      "url": "https://example.com",
      "format": "image/png",
      "viewport_width": 1920,
      "viewport_height": 1080,
      "full_page": true
    }
    """;

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://screenshotty1.p.rapidapi.com/v1/screenshot"))
    .header("Content-Type", "application/json")
    .header("X-RapidAPI-Key", "YOUR_API_KEY")
    .header("X-RapidAPI-Host", "screenshotty1.p.rapidapi.com")
    .POST(HttpRequest.BodyPublishers.ofString(jsonBody))
    .build();

HttpResponse<byte[]> response = client.send(
    request, HttpResponse.BodyHandlers.ofByteArray()
);

Files.write(Path.of("screenshot.png"), response.body());
```

### PHP

```php
<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => "https://screenshotty1.p.rapidapi.com/v1/screenshot",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode([
        "url" => "https://example.com",
        "format" => "image/png",
        "viewport_width" => 1920,
        "viewport_height" => 1080,
        "full_page" => true
    ]),
    CURLOPT_HTTPHEADER => [
        "Content-Type: application/json",
        "X-RapidAPI-Key: YOUR_API_KEY",
        "X-RapidAPI-Host: screenshotty1.p.rapidapi.com"
    ],
]);

$response = curl_exec($curl);
curl_close($curl);

file_put_contents("screenshot.png", $response);
```

---

## Use Case Examples

### Mobile Device Screenshot

```json
{
  "url": "https://example.com",
  "viewport_preset": "iphone_14",
  "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 16_0 like Mac OS X) AppleWebKit/605.1.15"
}
```

### Social Media Card (Open Graph)

```json
{
  "url": "https://example.com",
  "viewport_width": 1200,
  "viewport_height": 630,
  "full_page": false,
  "format": "image/png"
}
```

### Authenticated Page with Cookies

```json
{
  "url": "https://example.com/dashboard",
  "cookies": [
    {
      "name": "session_id",
      "value": "abc123",
      "domain": "example.com"
    }
  ],
  "http_headers": {
    "Authorization": "Bearer token123"
  }
}
```

### Clean Screenshot (No Ads/Banners)

```json
{
  "url": "https://example.com",
  "adblock": true,
  "block_cookie_banner": true
}
```

### PDF Export

```json
{
  "url": "https://example.com/report",
  "format": "application/pdf",
  "full_page": true
}
```

### Geo-Targeted Screenshot

```json
{
  "url": "https://example.com",
  "country": "JP"
}
```

### Element Screenshot with Transparency

```json
{
  "url": "https://example.com",
  "selector": "#main-content",
  "transparent_background": true,
  "format": "image/png"
}
```

---

## Error Responses

| Status | Description |
|--------|-------------|
| 400 | Bad Request - Invalid parameters or processing failed |
| 401 | Unauthorized - Missing or invalid API key |
| 403 | Forbidden - Subscription inactive or quota exceeded |
| 429 | Too Many Requests - Rate limit exceeded |
| 500 | Internal Server Error - Processing failed |

**Error Response Format**:
```json
{
  "error": "Error message description"
}
```

---

## Links

- **RapidAPI Marketplace**: https://rapidapi.com/nexus-apis-nexus-apis-default/api/screenshotty1
- **OpenAPI Specification**: /openapi.json
- **Summary Documentation**: /llms.txt