API Screenshot v1

Paramètres, contraintes et exemples pour POST /api/v1/screenshots.

Authentification

Envoyez votre clé API dans l’en-tête Authorization :

Authorization: Bearer <api_key>

Créer une capture

Point de terminaison: POST /api/v1/screenshots

Corps: JSON

Requête minimale

curl -X POST "https://api.page-ops.com/api/v1/screenshots" \
  -H "Authorization: Bearer $SCREENSHOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com"}'

Requête sync (si autorisée)

curl -X POST "https://api.page-ops.com/api/v1/screenshots" \
  -H "Authorization: Bearer $SCREENSHOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "mode": "sync",
    "timeoutMs": 8000,
    "fullPage": false
  }'

Si la fenêtre sync expire avant la fin, l’API renvoie status=processing. Continuez à interroger avec GET /api/v1/screenshots/{jobId}.

Paramètres clés

url

Obligatoire. URL cible à capturer.

mode

Optionnel. async (par défaut) ou sync.

timeoutMs

Requis pour sync. Doit être > 0 et < 10000.

fullPage

Optionnel. Pour le mode sync , la valeur doit être false.

Contraintes du mode synchrone

Même si vous demandez mode=sync, , le serveur basculera en async sauf si :

mode == "sync"

timeoutMs != null

0 < timeoutMs < 10000

fullPage == false

Référence des paramètres (complète)

Champ	Type	Obligatoire	Valeur par défaut	Notes
url	string	Oui	-	URL cible.
mode	string	Non	async	Accepte async ou sync (insensible à la casse).;
timeoutMs	int?	Non	-	Utilisé uniquement en sync. Doit être 0 < timeoutMs < 10000.
fullPage	bool	Non	false	Le mode sync exige false.
viewport	object?	Non	-	Remplacement du viewport.
format	string?	Non	-	Actuellement, seul png est pris en charge. Les autres formats sont réservés aux versions futures.
quality	int?	Non	-	Actuellement ignoré (utilisé seulement pour jpeg/webp à l’avenir).
waitUntil	string?	Non	-	Valeurs suggérées : load, domcontentloaded, networkidle.
delayMs	int?	Non	-	Délai supplémentaire après waitUntil.
selector	string?	Non	-	Capture uniquement un élément spécifique.
headers	object?	Non	-	Dictionnaire d’en-têtes de requête supplémentaires.
cookies	array?	Non	-	Liste de cookies à injecter.
javascript	string?	Non	-	JS personnalisé à injecter (selon l’implémentation).;
css	string?	Non	-	CSS personnalisé à injecter (selon l’implémentation).;
device	string?	Non	-	Valeurs suggérées : desktop/iphone/ipad/pixel.
strictDevice	bool?	Non	-	Si true, un appareil non pris en charge doit échouer (selon l’implémentation).;
colorScheme	string?	Non	-	Valeurs suggérées : light/dark/no-preference.
proxy	string?	Non	-	Réservé aux versions futures. Actuellement ignoré.
trace	bool?	Non	-	Réservé aux versions futures. Actuellement ignoré.
har	bool?	Non	-	Réservé aux versions futures. Actuellement ignoré.
returnDom	bool?	Non	-	Réservé aux versions futures. Actuellement ignoré.
returnNetwork	bool?	Non	-	Réservé aux versions futures. Actuellement ignoré.
priority	int?	Non	-	Réservé aux versions futures. Actuellement ignoré.

viewport

Champ	Type	Obligatoire	Notes
viewport.width	int	Non	Largeur du viewport.
viewport.height	int	Non	Hauteur du viewport.

cookies[]

Champ	Type	Obligatoire	Notes
cookies[].name	string	Oui	Nom du cookie.
cookies[].value	string	Oui	Valeur du cookie.
cookies[].domain	string?	Non	Domaine du cookie.
cookies[].path	string?	Non	Chemin du cookie.

Réponses

Async (par défaut)

{ "jobId": "<guid>", "status": "pending" }

Sync (terminée)

{ "jobId": "<guid>", "status": "completed", "result": { "url": "https://..." } }

Sync (échouée)

{ "jobId": "<guid>", "status": "failed", "errorMessage": "..." }

Sync (timeout)

{ "jobId": "<guid>", "status": "processing" }

Pour les appels async (ou les timeouts sync), utilisez GET /api/v1/screenshots/{jobId} pour vérifier l’état. Valeurs possibles : pending, processing, completed, failed, expired.

Erreurs

HTTP	Quand	Corps
400	Body manquant ou url manquante/vide	BadRequest
401	Clé API invalide/manquante	Réponse du middleware
402	Quota dépassé	{ "error": "quota_exceeded", "operationKey": "screenshot.capture", ... }
429	Limite de débit atteinte	{ "error": "rate_limited", "operationKey": "screenshot.capture", ... }
404	Job introuvable	NotFound

Exemples pratiques

Exemples pratiques pour les besoins d’intégration courants.

Transmettre le jeton d’auth du site cible (via headers)

Si la page à capturer est protégée (Bearer/JWT/session token), transmettez-le via headers:

{
  "url": "https://example.com/dashboard",
  "headers": {
    "Authorization": "Bearer <target_site_token>"
  }
}

Définir des cookies (connexion basée sur une session)

Si le site utilise des cookies pour l’authentification, transmettez-les via cookies:

{
  "url": "https://example.com/account",
  "cookies": [
    { "name": "session", "value": "<cookie_value>", "domain": "example.com", "path": "/" }
  ]
}

En-têtes personnalisés (User-Agent / locale)

{
  "url": "https://example.com",
  "headers": {
    "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)",
    "Accept-Language": "en-US,en;q=0.9"
  }
}

Viewport + format + qualité

{
  "url": "https://example.com",
  "viewport": { "width": 1280, "height": 720 },
  "format": "jpeg",
  "quality": 85
}

Attendre le chargement de la page + ajouter un délai

{
  "url": "https://example.com",
  "waitUntil": "networkidle",
  "delayMs": 500
}

Capturer un élément précis (selector)

{
  "url": "https://example.com/pricing",
  "selector": "#pricing"
}

Obtenir le statut

Interroger le job :

GET /api/v1/screenshots/{jobId}