API Documentation - GoScreenAPI
GoScreenAPI Screenshot API
Get started
REST API · v1

API Reference

Everything you need to integrate GoScreenAPI into your application. One endpoint, powerful options.

Authentication

Pass your API key via the Authorization header on every request.

HTTP Header 
Authorization: Bearer {{ $displayKey }}_here

Generate API keys from your dashboard. Each key can be revoked independently.

Endpoints

POST
https://goscreenapi.com/api/v1/screenshot

Create a screenshot request

GET
https://goscreenapi.com/api/v1/screenshot/{id}

Poll request status (async mode)

GET
https://goscreenapi.com/api/v1/screenshots

List your screenshot history (paginated)

GET
https://goscreenapi.com/api/v1/me

Get account info and quota status

Parameters

Send as JSON body with Content-Type: application/json.

Parameter Type Required Description
url string required* The URL to screenshot. Must be http/https. Required if html is not set.
html string optional Raw HTML string to render instead of a URL. Required if url is not set.
async boolean optional false = sync (wait for result, returns image_url directly). true = async (returns poll_url). Default: true.
device string optional desktop (default), mobile (390×844), or tablet (768×1024).
width integer optional Viewport width in px. Min: 100, Max: 4000.
height integer optional Viewport height in px. Min: 100, Max: 4000.
format string optional png (default), jpg, jpeg, webp, pdf.
quality integer optional JPEG/WebP quality 1-100. Default: 80.
full_page boolean optional Capture full scrollable page. Default: false.
block_ads boolean optional Block ad networks and trackers. Default: false.
block_cookies boolean optional Dismiss cookie consent banners. Default: false.
stealth boolean optional Enable stealth mode to bypass bot detection. Default: false.
delay integer optional Wait N milliseconds after page load before capture. Max: 10000.
timeout integer optional Page load timeout in ms. Min: 1000, Max: 60000. Default: 30000.
scroll_to integer optional Scroll to Y position (px) before capture.
proxy_country string optional ISO 3166-1 alpha-2 country code for IP routing (e.g. US, DE, TR).
js_scenario string optional JavaScript code to execute on the page before capture. Max 4096 chars.
selector string optional CSS selector — capture only the matching element (e.g. #hero, .card).
wait_for string optional CSS selector or ms to wait before capture (e.g. .loaded or 2000).
css string optional Custom CSS to inject into the page before capture. Max 65535 chars.
theme string optional light (default) or dark — sets prefers-color-scheme media query.
headers string optional JSON object of custom HTTP headers sent with the page request. Max 10 keys.
cache_ttl integer optional Cache result for N seconds (60–2592000). Same URL+params returns cached result.
webhook_url string optional URL to POST result to when screenshot completes (async mode).
webhook_secret string optional Secret for HMAC-SHA256 webhook signature verification.
signed_link boolean optional Generate a signed time-limited public link for the result.
signed_link_expires_in integer optional Signed link TTL in seconds. Min: 60, Max: 604800. Default: 3600.

* Either url or html is required.

Code Examples

cURL
curl -X POST 'https://goscreenapi.com/api/v1/screenshot' \
  -H 'Authorization: Bearer {{ $displayKey }}' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com",
    "format": "png",
    "full_page": true,
    "block_ads": true,
    "async": false
  }'
JavaScript
const response = await fetch('https://goscreenapi.com/api/v1/screenshot', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer {{ $displayKey }}',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    url: 'https://example.com',
    format: 'png',
    full_page: true,
    block_ads: true,
    async: false,
  }),
});

const data = await response.json();
console.log(data.image_url); // https://goscreenapi.com/storage/screenshots/uuid.png
PHP
$response = Http::withToken('{{ $displayKey }}')
    ->post('https://goscreenapi.com/api/v1/screenshot', [
        'url'       => 'https://example.com',
        'format'    => 'png',
        'full_page' => true,
        'block_ads' => true,
        'async'     => false,
    ]);

$data = $response->json();
echo $data['image_url'];
Python
import requests

response = requests.post(
    'https://goscreenapi.com/api/v1/screenshot',
    headers={'Authorization': 'Bearer {{ $displayKey }}'},
    json={
        'url': 'https://example.com',
        'format': 'png',
        'full_page': True,
        'block_ads': True,
        'async': False,
    }
)

data = response.json()
print(data['image_url'])

Response (sync mode — async: false)

JSON · 200 OK
{
  "status": "completed",
  "request_id": "018e1234-abcd-7000-8000-000000000001",
  "image_url": "https://goscreenapi.com/storage/screenshots/018e1234-abcd-7000-8000-000000000001.png",
  "duration_ms": 2984,
  "async": false,
  "quota": {
    "monthly_quota": 250,
    "monthly_used": 5,
    "monthly_remaining": 245,
    "overage_active": false
  }
}

Async Mode

Default mode. Request returns immediately with a poll_url. Poll until status is completed.

JSON · 202 Accepted
{
  "status": "queued",
  "request_id": "018e1234-abcd-7000-8000-000000000001",
  "poll_url": "https://goscreenapi.com/api/v1/screenshot/018e1234-abcd-7000-8000-000000000001",
  "async": true,
  "quota": { "monthly_quota": 250, "monthly_used": 4, "monthly_remaining": 246 }
}

Polling the result

cURL — Poll
curl 'https://goscreenapi.com/api/v1/screenshot/{request_id}' \
  -H 'Authorization: Bearer {{ $displayKey }}'

# Response when completed:
{
  "status": "success",
  "request": {
    "id": "018e1234-...",
    "status": "completed",
    "image_url": "https://goscreenapi.com/storage/screenshots/018e1234.png",
    "duration_ms": 3120,
    "requested_at": "2026-03-19T10:00:00Z",
    "completed_at": "2026-03-19T10:00:03Z"
  }
}

Advanced Example

Element screenshot with dark mode, custom CSS injection, and a custom auth header.

cURL — Advanced
curl -X POST 'https://goscreenapi.com/api/v1/screenshot' \
  -H 'Authorization: Bearer {{ $displayKey }}' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com",
    "selector": "#pricing-table",
    "theme": "dark",
    "wait_for": ".pricing-loaded",
    "css": ".cookie-banner { display: none; }",
    "headers": "{\"Authorization\": \"Bearer my_token\"}",
    "format": "png",
    "async": false
  }'
JavaScript — Advanced
const response = await fetch('https://goscreenapi.com/api/v1/screenshot', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer {{ $displayKey }}',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    url: 'https://example.com',
    selector: '#pricing-table',
    theme: 'dark',
    wait_for: '.pricing-loaded',
    css: '.cookie-banner { display: none; }',
    headers: JSON.stringify({ Authorization: 'Bearer my_token' }),
    format: 'png',
    async: false,
  }),
});
const data = await response.json();
console.log(data.image_url);
PHP — Advanced
$response = Http::withToken('{{ $displayKey }}')
    ->post('https://goscreenapi.com/api/v1/screenshot', [
        'url'      => 'https://example.com',
        'selector' => '#pricing-table',
        'theme'    => 'dark',
        'wait_for' => '.pricing-loaded',
        'css'      => '.cookie-banner { display: none; }',
        'headers'  => json_encode(['Authorization' => 'Bearer my_token']),
        'format'   => 'png',
        'async'    => false,
    ]);

echo $response->json('image_url');
Python — Advanced
import requests, json

response = requests.post(
    'https://goscreenapi.com/api/v1/screenshot',
    headers={'Authorization': 'Bearer {{ $displayKey }}'},
    json={
        'url': 'https://example.com',
        'selector': '#pricing-table',
        'theme': 'dark',
        'wait_for': '.pricing-loaded',
        'css': '.cookie-banner { display: none; }',
        'headers': json.dumps({'Authorization': 'Bearer my_token'}),
        'format': 'png',
        'async': False,
    }
)
print(response.json()['image_url'])

Account & Quota

GET /api/v1/me — Check your plan, quota usage, and wallet balance programmatically.

cURL
curl 'https://goscreenapi.com/api/v1/me' \
  -H 'Authorization: Bearer {{ $displayKey }}'
JSON · 200 OK
{
  "status": "success",
  "user": {
    "email": "[email]",
    "plan": "Pro",
    "overage_enabled": true,
    "wallet_balance": 12.50
  },
  "quota": {
    "monthly_quota": 5000,
    "monthly_used": 312,
    "monthly_remaining": 4688,
    "reset_at": "2026-04-01T00:00:00Z",
    "overage_active": false
  }
}

Screenshot History

GET /api/v1/screenshots — List your past requests. Supports ?status=completed and ?per_page=50 (max 100).

cURL
curl 'https://goscreenapi.com/api/v1/screenshots?per_page=10&status=completed' \
  -H 'Authorization: Bearer {{ $displayKey }}'
JSON · 200 OK
{
  "status": "success",
  "data": [
    {
      "id": "018e1234-...",
      "url": "https://example.com",
      "status": "completed",
      "format": "png",
      "device": "desktop",
      "image_url": "https://goscreenapi.com/storage/screenshots/018e1234.png",
      "duration_ms": 2984,
      "cache_hit": false,
      "requested_at": "2026-03-19T10:00:00Z",
      "completed_at": "2026-03-19T10:00:03Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 10,
    "total": 312,
    "last_page": 32
  }
}

Webhooks

Set webhook_url in your request. When the screenshot completes, we POST the result to your endpoint.

Signature verification: Each webhook includes an X-GSS-Signature header — HMAC-SHA256 of the raw body using your webhook_secret.
Webhook payload
{
  "request_id": "018e1234-...",
  "status": "completed",
  "image_url": "https://goscreenapi.com/storage/screenshots/018e1234.png",
  "duration_ms": 2984,
  "requested_at": "2026-03-19T10:00:00Z",
  "completed_at": "2026-03-19T10:00:03Z"
}

Error Codes

HTTP Meaning
401 Invalid or missing API key
403 Account suspended or inactive
422 Validation error — check errors field in response
429 Quota exceeded or too many pending requests
500 Internal server error
503 Worker temporarily unavailable

Rate Limits

Each user can have at most 10 pending requests at a time. Monthly quota depends on your plan.

Need higher limits? Upgrade your plan or contact us for enterprise.