API Reference

Screenshot Capture

Capture full-page or viewport screenshots of any URL

Capture pixel-perfect screenshots of any web page programmatically. The Screenshot API renders pages in a headless browser with configurable viewport size, full-page capture, and multiple output formats. Use it for visual regression testing, thumbnail generation, PDF reports, and content monitoring at scale.

full-page captureviewport sizingPNG/JPEG outputheadless Chrome

Endpoint

POST /v1/screenshot/capture
Authentication: Include your API key in the X-API-Key header with every request. All requests go through the API gateway which handles authentication, rate limiting, and usage tracking.
Open Swagger UI (interactive docs)

Request

{
  "url": "https://example.com",
  "viewport": {
    "width": 1280,
    "height": 720
  },
  "fullPage": false,
  "format": "png"
}

Request Fields

FieldTypeDescription
url string Target URL
viewport object Nested object with properties
fullPage boolean Field value
format string Field value

Response

{
  "id": "cap_abc123",
  "url": "https://example.com",
  "format": "png",
  "width": 1280,
  "height": 720,
  "fileSize": 245760,
  "downloadUrl": "/api/v1/captures/cap_abc123/download"
}

Response Fields

FieldTypeDescription
id string Unique identifier
url string Target URL
format string Field value
width integer Field value
height integer Field value
fileSize integer Field value
downloadUrl string Field value

Error Codes

StatusMeaning
200Request completed successfully
400Bad request — invalid or missing parameters
401Missing or invalid X-API-Key header
429Rate limit exceeded — check Retry-After header
500Internal server error

Common Error Scenarios

400 Invalid URL

Request that triggers this:

{"url": "invalid url"}

Error response:

{"type": "/problems/validation-error", "title": "Invalid URL", "status": 400, "detail": "'invalid url' is not a valid URL"}

How to fix: Use a valid HTTP or HTTPS URL with proper formatting (e.g., https://example.com).

504 Page load timeout

Request that triggers this:

{"url": "https://very-slow-site.example.com"}

Error response:

{"type": "/problems/gateway-timeout", "title": "Page Load Timeout", "status": 504, "detail": "Page did not load within 30 seconds"}

How to fix: The page loads too slowly. Optimize page performance or increase timeout if available. Try again later.

Code Examples

curl -X POST /v1/screenshot/capture \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
  "url": "https://example.com",
  "viewport": {
    "width": 1280,
    "height": 720
  },
  "fullPage": false,
  "format": "png"
}' 
// Node.js (18+) or modern browser
const response = await fetch("/v1/screenshot/capture", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "url": "https://example.com",
    "viewport": {
        "width": 1280,
        "height": 720
    },
    "fullPage": false,
    "format": "png"
}),
});

const data = await response.json();
console.log(response.status, data);
import requests

response = requests.post(
    "/v1/screenshot/capture",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
    "url": "https://example.com",
    "viewport": {
        "width": 1280,
        "height": 720
    },
    "fullPage": false,
    "format": "png"
},
)

print(response.status_code)
print(response.json())
package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	body := strings.NewReader(`{
  "url": "https://example.com",
  "viewport": {
    "width": 1280,
    "height": 720
  },
  "fullPage": false,
  "format": "png"
}`)
	req, _ := http.NewRequest("POST", "/v1/screenshot/capture", body)
	req.Header.Set("X-API-Key", "YOUR_API_KEY")
	req.Header.Set("Content-Type", "application/json")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	data, _ := io.ReadAll(resp.Body)
	fmt.Println(resp.StatusCode)
	fmt.Println(string(data))
}
{
  "name": "screenshot",
  "description": "Capture full-page or viewport screenshots of any URL",
  "inputSchema": {
    "type": "object",
    "properties": {
      "api_key": {"type": "string", "description": "Your Orovai API key"},
      "request": {"type": "object", "description": "Request body"}
    },
    "required": ["api_key", "request"]
  },
  "endpoint": "/v1/screenshot/capture",
  "method": "POST",
  "headers": {
    "X-API-Key": "{{api_key}}",
    "Content-Type": "application/json"
  }
}

API Reference