REST API

Use the REST API when the JavaScript SDK does not fit your stack. It is one endpoint with one JSON body, and every answer has the same shape.

EndpointLink to this section

Send a POST request with a JSON body and the Content-Type: application/json header.

Request bodyLink to this section

• urlstringRequired

  The page to capture, such as example.com/pricing. The protocol is optional, pages are always loaded over https.

• tokenstringRequired

  Your API token from the Account page. It identifies the account the credits are taken from.

• optionsobjectdefault {}

  Capture settings. Every one of them is optional, see the options reference.

Fields the API does not know are ignored, and an option with a value it cannot use falls back to its default instead of failing the request. See the options reference for every setting.

ExamplesLink to this section

The same capture in five languages: a 1440 by 900 window, captured as a full page.

curl -X POST https://url2image.modulify.website/api/screenshots/create \
  -H "Content-Type: application/json" \
  -d '{
    "url": "example.com",
    "token": "YOUR_API_TOKEN",
    "options": { "width": 1440, "height": 900, "fullPage": true }
  }'

ResponseLink to this section

Every answer, success or error, is a JSON object with the same fields:

• successbooleanAlways

  true when the screenshot was created, false for every error.

• codenumberAlways

  The HTTP status of the answer, repeated in the body.

• messagestringAlways

  What happened, in plain words. Safe to show to your own users.

• dataobject | nullAlways

  The result on success. null on most errors, or the list of what is wrong when fields are missing.

• data.scrUrlstring | nullOn success

  The permanent link to the hosted PNG. It never expires. null when storage is false.

• data.scrBase64stringOn success

  The same PNG encoded as base64, without a data: prefix.

{
  "success": true,
  "code": 200,
  "message": "Screenshot was generated.",
  "data": {
    "scrUrl": "https://.../screenshots/.../8f3c2a91d4e5b6c7.png",
    "scrBase64": "iVBORw0KGgoAAAANSUhEUgAA..."
  }
}

To keep the image yourself, decode scrBase64. In Node.js:

import { writeFile } from "node:fs/promises"

await writeFile("screenshot.png", Buffer.from(data.scrBase64, "base64"))

The errors and what each one means are on the responses and errors page.

TimeoutsLink to this section

The request stays open until the capture is finished. That is usually a few seconds, and never more than two minutes.

• Set your HTTP client timeout to at least 150 seconds, so it does not give up before the API answers.
• A capture that runs out of time fails with an error, and its credits are returned.
• Several captures can run at the same time, up to the limit of your account.

Calling from a browserLink to this section

The endpoint accepts requests from any origin, so it works from a browser too. Your token would be visible to everyone who opens the page, though, and anyone who has it can spend your credits.