# Migrate a screenshot workflow to Latchshot

Latchshot uses one Bearer-authenticated endpoint for screenshots and PDFs. Most integrations can migrate by replacing the request URL, moving the credential into the `Authorization` header, and renaming a few options.

## Common option map

| Existing concept or common name | Latchshot |
| --- | --- |
| API key in `access_key`, `key`, or `token` | `Authorization: Bearer ls_...` header |
| Target page | JSON `url` |
| `viewport_width`, `viewport.width` | `width` |
| `viewport_height`, `viewport.height` | `height` |
| `full_page` | `fullPage` |
| `dark_mode` | `darkMode` |
| Screenshot type | `kind: "screenshot"` plus `format: "png"` or `"jpeg"` |
| JPEG quality | `quality`, integer 1–100; JPEG only, default 85 |
| PDF type | `kind: "pdf"` plus `paper` and `landscape` |
| Wait time after navigation | `delay`, bounded to 0–3000 ms |
| Navigation timeout | `timeout`, bounded to 3000–30000 ms |

Latchshot intentionally does not accept arbitrary page scripts, proxy credentials, CAPTCHA options, private-network destinations, or anti-bot bypass settings. Confirm that a workflow does not depend on those features before migrating it.

Using ApiFlash today? The [ApiFlash-to-Latchshot migration guide](https://latchshot.fly.dev/guides/migrate-from-apiflash.html) moves the query or form credential into a Bearer header, converts seconds to milliseconds, and separates compatible binary PNG/JPEG captures from provider caching, hosted JSON URLs, WebP, selectors, page modification, extraction, proxies, and storage.

Using ScreenshotMachine today? The [ScreenshotMachine-to-Latchshot migration guide](https://latchshot.fly.dev/guides/migrate-from-screenshotmachine.html) moves the API key out of the image URL, splits dimensions into explicit viewport controls, preserves millisecond delays, and separates compatible binary PNG/JPEG captures from signed embedding, caching, GIF, device presets, page changes, cookies, custom headers, element capture, and cropping.

Using ScreenshotOne today? The [ScreenshotOne-to-Latchshot migration guide](https://latchshot.fly.dev/guides/migrate-from-screenshotone.html) adds an exact before-and-after request, seconds-to-milliseconds conversion, a provider-specific option map, five bounded cleanup controls, and a stop list for custom/exhaustive blockers, selectors, async delivery, storage, proxies, and page modification.

Using Browserless today? The [Browserless-to-Latchshot migration guide](https://latchshot.fly.dev/guides/migrate-from-browserless.html) maps the narrow public-URL screenshot intersection: Bearer authentication, direct image bytes, viewport, output, full-page, wait, timeout, and delay controls. Keep Browserless for inline HTML, CDP or browser-library sessions, scripts and page actions, authenticated state, element or clip capture, scrolling, private targets, and proxy or region placement.

Using Urlbox today? The [Urlbox-to-Latchshot migration guide](https://latchshot.fly.dev/guides/migrate-from-urlbox.html) separates compatible server-side binary captures from render links, temporary hosted URLs, provider caching, async delivery, page modification, storage, and other Urlbox-only workflow features.

## Check a specific migration

Not sure whether one production job falls inside the compatible slice? Open a [public migration-fit question on GitHub](https://github.com/BaiqingL/latchshot/issues/new?template=migration-fit.yml) with the request contract, required provider behavior, and expected volume. Describe the contract rather than the customer or target. Never include an API key, authorization header, private or signed URL, customer data, or sensitive artifact.

## Optional $99 implementation pilot

Read the [exact implementation-pilot scope, deliverables, sequence, and acceptance boundary](https://latchshot.fly.dev/implementation-pilot.html). If the fit check confirms that the job uses Latchshot's supported contract, the $99 one-time pilot can move one existing JavaScript/TypeScript or Python backend call site in a public GitHub repository you control. API usage is separate; use the Free plan for acceptance testing, then choose a monthly plan only if the production volume needs it.

The pilot includes:

- one provider-call replacement that returns synchronous PNG, JPEG, or PDF bytes;
- focused tests using the repository's existing test conventions;
- one maintainer-approved public sample capture plus a cutover and rollback note; and
- one review revision that stays inside the agreed request contract.

The pilot is complete when the focused tests pass and the agreed public sample returns the required artifact shape. You review, merge, deploy, and retain control of the repository.

The pilot does not add login state, cookies, private-network access, arbitrary scripts or actions, selectors, proxies, CAPTCHA bypass, hosted artifact URLs, provider storage, async delivery, a new queue, or an SLA. Additional repositories, call sites, languages, and application redesign are separate work. Never send production credentials or private customer data for the pilot.

To request it:

1. Use the [no-account implementation-pilot request](https://latchshot.fly.dev/implementation-pilot.html#request-pilot) with the public repository, one call-site path, non-secret request contract, required behavior, expected volume, and public acceptance sample. If you prefer a public review thread, use the [GitHub pilot form](https://github.com/BaiqingL/latchshot/issues/new?template=implementation-pilot.yml). No work or payment starts before the fit and scope are confirmed.
2. After the fit is confirmed, reuse your existing Latchshot key. If you do not have one, [create a Free-plan key through the migration-pilot path](https://latchshot.fly.dev/?intent=migrationpilot#trial). In the optional workflow context, paste the public issue URL and opt into product-fit guidance so the owner may reply privately.
3. The owner confirms the exact call site, acceptance sample, payment, and start before any customer-repository change. Do not put payment details, credentials, private URLs, or customer data in the issue or form.

## Minimal replacement

```sh
curl --fail-with-body https://latchshot.fly.dev/v1/render \
  -H "Authorization: Bearer $LATCHSHOT_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
    "url": "https://example.com",
    "kind": "screenshot",
    "format": "png",
    "width": 1440,
    "height": 900,
    "fullPage": false
  }' \
  --output capture.png
```

For an existing query-string integration, `GET /v1/screenshot` accepts `url`, `width`, `height`, `format`, JPEG-only `quality`, `fullPage`, and `darkMode`. Use `POST /v1/render` for the full option set and for PDFs.

## Dependency-free adapters

- [Node.js adapter](https://latchshot.fly.dev/examples/node.mjs) — native `fetch`, bounded retries, response diagnostics, and file output.
- [Python adapter](https://latchshot.fly.dev/examples/python.py) — standard library only, bounded retries, response diagnostics, and file output.

Run either adapter after setting the API key:

```sh
export LATCHSHOT_API_KEY='ls_live_replace_me'

node node.mjs 'https://example.com' example.png
python3 python.py 'https://example.com' example.png
```

Both adapters retry `429`, `502`, `503`, and `504` at most twice. Direct Latchshot plans count only successful renders, but retry loops should still remain bounded.

## Production cutover checklist

1. Render a representative sample of public pages with the same dimensions and format as the current provider.
2. Compare output visually, including fonts, consent banners, lazy-loaded content, and authenticated-page assumptions.
3. Record `X-Latchshot-Render-Ms`, `X-Latchshot-Navigation`, `X-Latchshot-Fonts`, and `X-Latchshot-Scripts` during the test.
4. Treat `400` and `401` as permanent errors. Retry only `429`, `502`, `503`, and `504`, with a strict attempt limit.
5. Check `GET /v1/usage` before cutover and alert on `X-Quota-Remaining` rather than enabling automatic overages.
6. Route a small percentage of production captures first; keep the former provider available until the target sample is stable.

Get a Free-plan key with 100 successful renders each UTC calendar month through [the developer documentation](https://latchshot.fly.dev/docs.md#get-100-free-renders-each-month).

For a job-specific walkthrough, use the [URL-to-screenshot guide](https://latchshot.fly.dev/guides/url-to-screenshot-api.html) or [URL-to-PDF guide](https://latchshot.fly.dev/guides/url-to-pdf-api.html).