How to Add Custom Headers and Cookies to APITemplate.io Screenshot Requests

Short answer: APITemplate.io documents headers that authenticate your request to its API, but the official documentation examined for this guide does not show a documented option for forwarding arbitrary headers or cookies to the page its renderer visits. Do not assume that X-API-KEY logs the renderer into the target website, and do not invent a JSON property or query parameter for page cookies.

The documented v2 URL-based PDF endpoint is POST /create-pdf-from-url, with the target URL in a JSON body. APITemplate.io also documents a template-based create-image endpoint. Those endpoint examples establish their documented purposes and API authentication pattern; they do not establish a screenshot endpoint or target-page header and cookie support. Check APITemplate.io’s current [REST API reference](https://apitemplate.io/apitemplate-api/) and [getting started guide](https://apitemplate.io/docs/getting-started/) for the endpoint and fields available to your account.

1. Separate API authentication from target-page authentication

There are two different HTTP requests in this workflow:

1. Your application sends a request to APITemplate.io. The documented v2 examples authenticate this request with X-API-KEY: YOUR_API_KEY.
2. The rendering service visits the target URL to generate output. A header or cookie on your first request does not automatically become a header or cookie on this later page request.

The cited APITemplate.io examples document the first request. The material examined for this guide does not specify how to configure headers or cookies on the renderer’s request to the target page. That is an unresolved documentation question, not proof that no endpoint or support path exists. For an authenticated or header-protected page, ask APITemplate.io to confirm the precise endpoint and accepted fields before relying on a request format.

2. Documented v2 URL-to-PDF request

This cURL example follows the documented v2 URL-based PDF pattern. It sends the API key to APITemplate.io and the target URL in the JSON body. It does not demonstrate passing target-page headers or cookies, and it should not be treated as a verified screenshot endpoint.

curl -X POST "https://rest.apitemplate.io/v2/create-pdf-from-url" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/page"}'

Replace YOUR_API_KEY and the URL with your own values. Use the output behavior and response handling documented for your account and endpoint; this minimal example is intended to show request authentication and the documented URL field, not to promise a particular response format or file-saving behavior.

3. What about v1 authentication?

The older v1 reference documents Authorization: Token [API_KEY] as an authentication option for that API generation. Do not silently apply this legacy syntax to v2. For a v2 request, use the current v2 reference’s documented X-API-KEY header unless APITemplate.io’s current instructions for your endpoint say otherwise.

4. How to verify target headers and cookies safely

1. Identify the exact APITemplate.io endpoint and API version you intend to use. The documented v2 reference distinguishes template-based image generation from URL-based PDF generation.
2. Look for explicit schema fields for target-page request headers and cookies. An API authentication header alone is not such a field.
3. If the schema or examples do not show those fields, ask APITemplate.io support to confirm the endpoint, field names, cookie format, and whether the values are applied to the browser’s request to the target URL.
4. Test with a page and credentials you control. Confirm that the rendered output reflects the authenticated state; a successful API response only proves what the endpoint response says, not that the target page received the intended session.
5. Keep API keys and session cookies out of source control, public URLs, logs, and shared screenshots. Use the provider’s documented secret-handling method for your deployment.

Do not send guessed fields such as headers or cookies and interpret an accepted API request as proof they reached the target site. Without explicit endpoint documentation or provider confirmation, their semantics are unknown.

5. Endpoint, region, and capacity considerations

APITemplate.io’s v2 REST reference lists https://rest.apitemplate.io/v2/ as a base URL and names Singapore as the default region, along with Frankfurt, US East (N. Virginia), and Australia. The getting-started guide lists US/default, EU, Australia, and Singapore hostnames. Because those descriptions differ, verify the current endpoint applicable to your account and data-residency requirements instead of inferring a hostname from a region label.

The v2 reference states a limit of 100 requests per 10 seconds per IP and 100 concurrent synchronous PDF-generation requests per user account. Requests beyond limits receive HTTP 429; the reference suggests asynchronous generation for high-volume workloads. It also describes regional processing and storage for generated files and lists outbound IP addresses to whitelist when the service needs to retrieve geo-restricted assets. These are operational details; they do not confirm that target-page headers or cookies can be set.

6. Common errors and troubleshooting

Symptom	Likely cause	What to do
Authentication failure	The API key is missing, invalid, or sent using a header format that does not match the endpoint’s API version.	For documented v2 requests, send X-API-KEY. Use the legacy Authorization: Token ... syntax only when working with a v1 endpoint whose documentation calls for it.
The API accepts the request, but the output shows a login page	The API key authenticated your caller to APITemplate.io; it may not have authenticated the renderer to the target site.	Confirm whether the selected endpoint supports target-page cookies or headers, and how to provide them. The examined documentation does not establish those options.
A guessed JSON field has no effect or is rejected	The field name or behavior is undocumented for the endpoint you are using.	Remove assumptions and check the endpoint schema or ask APITemplate.io for the supported request format.
HTTP 429	The request exceeds a documented rate or concurrency limit.	Reduce request rate or synchronous concurrency. For higher-volume work, review the documented asynchronous generation option and current account guidance.
Region or asset access problem	The chosen regional endpoint may not match account requirements, or the renderer may be unable to retrieve a geo-restricted asset.	Confirm the endpoint with the current regional table. If required, use the documented outbound IP information for asset allowlisting.
Output is an image when you expected a URL capture, or vice versa	The template-based image endpoint and URL-based PDF endpoint have different documented purposes.	Choose the endpoint that matches the task. Do not infer URL screenshot behavior from a template-based image example.

7. Performance, reliability, and cost planning

For throughput, account for the documented per-IP request limit and per-account synchronous PDF concurrency limit. If a workload approaches those limits, batch work responsibly and review asynchronous generation support in the current API documentation. Do not treat the rate and concurrency figures as a performance benchmark or as a guarantee that a particular job will finish within a given time.

For reliability, distinguish API-level success from successful target-page authentication and rendering. Check the generated result itself, especially when the target depends on a session, region, or protected assets. The examined sources do not establish the behavior, availability, or cost of target-page header and cookie options, so confirm those details with APITemplate.io before building a workflow around them.

For regional processing and asset access, select an endpoint based on the current account documentation and confirm any allowlisting requirements for geo-restricted resources. The cited material provides operational limits and endpoint details, but no relevant pricing figures for this specific workflow; consult current APITemplate.io account and pricing information for costs.

8. Or skip the browser setup

If the job is to capture a page with custom headers or cookies, ScreenshotNeo is a website screenshot API with documented options for custom headers, cookies, and Authorization. It returns a screenshot or PDF from one GET request. See the ScreenshotNeo API documentation for request parameters and response details.

curl -G "https://api.screenshotneo.com/v1/shot" \
  -d access_key=YOUR_API_KEY \
  --data-urlencode url=https://example.com/page

Add the documented header and cookie parameters for your use case as described in the API docs. This basic call shows the endpoint and URL pattern; it does not include credentials for the target page.

ScreenshotNeo accepts cookie and consent banners like a visitor and removes 60+ known consent platforms, newsletter popups, and chat widgets before capture; each step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing, and response headers report the page verdict and billing status. An MCP server provides take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 shots. Every feature is on every plan.

Sign up free for 1,000 screenshots a month, with no card required.

9. FAQ

Does X-API-KEY authenticate me to the target website?

It is documented as APITemplate.io API authentication for v2. The examined docs do not say that it is forwarded to the target page.

Can I pass a session cookie to the page APITemplate.io renders?

The sources examined do not establish a supported target-page cookie field. Confirm the precise endpoint and accepted schema with APITemplate.io.

Is create-image the documented URL screenshot endpoint?

The v2 reference describes it as template-based image generation. The URL-based endpoint cited here is create-pdf-from-url; do not infer undocumented screenshot behavior from either example.

Which regions can I use?

The detailed REST reference and getting-started guide describe regional endpoints differently. Check the current endpoint table and account requirements before choosing one.

Sources

• APITemplate.io v2 REST API reference
• APITemplate.io getting started guide