cURL Screenshot API
Test and integrate the Screenshotly API from the command line with cURL. Quick access for scripting, CI/CD pipelines, shell automation, and manual testing. Includes one-liner examples for PNG capture, full-page PDF output, device mockups, and piping results to other tools.
Quick Start
Install dependencies
cURL comes pre-installed on macOS and most Linux distributions. On Windows, install via winget or chocolatey.
Get your API key
Sign up for Screenshotly and get your API key from the dashboard.
Copy the code example
Use our cURL code example as a starting point.
Customize and integrate
Modify the code to fit your specific use case and requirements.
Code Example
# cURL
curl -X POST "https://api.screenshotly.app/screenshot" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com",
"device": "desktop",
"format": "png"
}' \
--output screenshot.pngWhen to Use cURL with Screenshotly
Use the cURL integration for quick manual testing, shell scripts, CI/CD pipeline steps, and system administration tasks. cURL is the fastest way to test API parameters before writing code in another language, and it works in every Linux, macOS, and Windows (WSL) environment.
cURL Best Practices
Store your API key in an environment variable and reference it as $SCREENSHOTLY_API_KEY in all scripts to avoid accidental key leakage.
Use -w '\n%{http_code}' to append the HTTP status code to output — essential for scripting conditional logic.
For complex JSON payloads, store them in a file and use -d @payload.json instead of inline escaping.
Pipe output directly to other tools: curl ... | convert - -resize 50% thumbnail.png (ImageMagick) or curl ... | jq (JSON processing).
cURL: Production Notes
cURL is the right tool for quick validation, cron-driven batch captures, and CI/CD smoke tests. It is the wrong tool inside an application server — you lose structured error handling, proper retry semantics, and any ability to integrate with your app's logging.
In CI/CD, cURL is ideal for post-deploy smoke tests: capture the homepage after deploy, diff against a known-good baseline using ImageMagick's `compare`, fail the pipeline on significant pixel diff.
Error Handling Recipes
Concrete strategies for each failure mode. Do not silently swallow errors — surface them to your monitoring so the pipeline is observable.
HTTP 429
Use --retry combined with --retry-delay. cURL respects Retry-After headers automatically with --retry.
curl -X POST https://api.screenshotly.app/screenshot \
-H "Authorization: Bearer $API_KEY" \
--retry 3 --retry-delay 2 --retry-max-time 60 \
--fail --output screenshot.pngTimeout (exit code 28)
Combine --max-time 30 with --connect-timeout 5. In scripts, log and continue; let cron retry on the next run.
Production Hardening Checklist
The difference between dev code and prod code. Work through these before putting cURL captures on a critical path.
- Always pass --fail so non-2xx statuses exit non-zero.
- --retry 3 --retry-delay 2 --retry-max-time 60 provides resilience.
- --max-time 30 (or higher for PDF/full-page) bounds the total call.
- API key from env var ($API_KEY), never hardcoded.
- For batches, GNU Parallel or xargs -P caps concurrency.
Rate-Limit Strategy
Use GNU Parallel -j 4 or xargs -P 4 to cap concurrency at 4–5 parallel cURL invocations. For large batches, sleep 1 between iterations as a cheap throttle.
When cURL isn't the right fit
cURL works well for most capture workloads, but these patterns are legitimate reasons to pick a different stack:
- Your capture logic belongs inside an application server — use the native HTTP client for that language instead. cURL inside system() calls loses structured error handling and observability.
- Your batch exceeds ~100 URLs per run — bash loops become a maintenance burden that a real scripting language (Python, Node) handles more cleanly.
- You need retry logic more sophisticated than cURL's --retry flag — custom backoff with jitter, circuit breakers, observability integration — all belong in a real HTTP client.
API Reference
POST /api/screenshotBearer tokenapplication/jsonFrequently Asked Questions
How do I capture screenshots in batch using cURL?
Create a shell script that loops through a list of URLs. Use xargs for parallel processing: cat urls.txt | xargs -P 5 -I {} curl -X POST ... -d '{"url":"{}"}' --output {}.png. The -P flag controls concurrency.
How do I pass dynamic options with cURL?
Use shell variables: URL='https://example.com' && curl -X POST ... -d "{\"url\":\"$URL\",\"format\":\"png\"}" --output screenshot.png. For complex payloads, store JSON in a file and use -d @payload.json.
How do I check if a screenshot request succeeded?
Add -w '%{http_code}' to output the status code, or use -f to make cURL fail on HTTP errors. Check for 200 status on success. 401 means invalid API key, 429 means rate limited, 400 means invalid parameters.
Can I use cURL in CI/CD pipelines?
Yes. cURL is available in all major CI environments (GitHub Actions, GitLab CI, Jenkins). Store your API key as a CI secret and reference it as an environment variable in your pipeline script.
Start building with cURL
Get your API key and start capturing screenshots in minutes.
Other Languages
JavaScript
Capture website screenshots from the browser using client-side JavaScript. Call the Screenshotly API with the Fetch API from React, Vue, Angular, or vanilla JS — no server required for basic workflows. This guide covers browser JavaScript screenshot API usage, async/await patterns, error handling, blob URLs for display, and best practices for CORS and API key security when calling from the client.
Node.js
Server-side screenshot capture with Node.js — for backend services, Express/Fastify APIs, CLI tools, and automation scripts. This guide covers the Node.js screenshot API for server-side use only: streaming responses to disk or S3, Express screenshot middleware, cron jobs, and integrating with Bull/BullMQ for batch processing. Keep API keys on the server where they belong.
Python
Integrate screenshot capture into Python applications using the requests library or httpx. Ideal for data pipelines, Django/Flask web apps, automation scripts, and web scraping projects. Includes examples for synchronous and async requests, saving images to files, and handling rate limits with exponential backoff.
PHP
Add screenshot capabilities to PHP applications using cURL or Guzzle HTTP. Perfect for WordPress plugins, Laravel apps, and REST-based web services. Covers authentication, error handling, saving to local storage or S3, and integrating with Laravel queues for background processing.