API reference

POST https://api.shotbot.net/capture/callback
Content-Type: application/json

{
  "key":             "your_api_key",
  "url":             "https://test.shotbot.net",
  "callback_url":    "https://your-site.com/shotbot-callback.php",
  "callback_secret": "a-random-secret",
  "format":          "webp",
  "viewport_width":  1280,
  "ratio":           "16:9"
}

{ "token": "a3f1c9…", "status": "queued", "eta_seconds": 20 }

$_POST["token"]          → 32-char alphanumeric token (unique capture identifier)
$_POST["url"]             → original captured URL
$_POST["status"]          → "OK" | "ERR"
$_POST["format"]          → image format (jpg, webp, etc.)
$_POST["callback_secret"] → secret echoed back as-is (only if provided on creation)
$_FILES["file"]           → binary image (requested size and format)

// No preview in callback mode | one image in the requested format only.

<?php
// submit-capture.php, client side
$ch = curl_init("https://api.shotbot.net/capture/callback");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => ["Content-Type: application/json"],
    CURLOPT_POSTFIELDS     => json_encode([
        "key"             => "YOUR_API_KEY",
        "url"             => "https://test.shotbot.net",
        "callback_url"    => "https://your-site.com/shotbot-callback.php",
        "callback_secret" => "a-random-secret",
        "format"          => "webp",
        "viewport_width"  => 1280,
        "ratio"           => "16:9",
    ]),
]);
$res = json_decode(curl_exec($ch), true);
curl_close($ch);
echo "Capture: " . $res["token"];

<?php
// shotbot-callback.php | receives the capture from Shotbot
$EXPECTED_SECRET = "a-random-secret"; // same as callback_secret sent

if (!hash_equals($EXPECTED_SECRET, $_POST["callback_secret"] ?? "")) {
    http_response_code(403);
    exit;
}

if (($_POST["status"] ?? "") !== "OK") {
    http_response_code(200);
    exit;
}

$token = preg_replace("/[^A-Za-z0-9]/", "", $_POST["token"] ?? "");
$format = in_array($_POST["format"] ?? "", ["jpg","png","webp","avif"])
        ? $_POST["format"] : "jpg";

if (!$token || !isset($_FILES["file"])) {
    http_response_code(400);
    exit;
}

$dest = __DIR__ . "/shots/" . $token . "." . $format;
move_uploaded_file($_FILES["file"]["tmp_name"], $dest);

http_response_code(200);
echo "OK";

POST https://api.shotbot.net/capture/batch
Content-Type: application/json

{
  "key":  "your_api_key",

  "jobs": [
    { "url": "https://test.shotbot.net" },
    { "url": "https://other.com", "format": "png", "viewport_width": 390 }
  ],

  // Global options, applied to all captures, overridable per job
  "format":         "webp",
  "viewport_width": 1280,
  "ratio":          "16:9"
}

{
  "submitted":    2,
  "waitlisted":   0,
  "deduplicated": 0,
  "errors":       0,
  "jobs": [
    { "index": 0, "url": "https://test.shotbot.net", "token": "a3f1c9…", "status": "queued" },
    { "index": 1, "url": "https://other.com",   "token": "b7e2d4…", "status": "queued" }
  ]
}

<?php
$api_key = "YOUR_API_KEY";

$urls = [
    "https://test.shotbot.net",
    "https://github.com",
    "https://wikipedia.org",
    // ... up to 500
];

// Submit the batch
$ch = curl_init("https://api.shotbot.net/capture/batch");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => ["Content-Type: application/json"],
    CURLOPT_POSTFIELDS     => json_encode([
        "key"            => $api_key,
        "format"         => "webp",
        "viewport_width" => 1280,
        "ratio"          => "16:9",
        "jobs"           => array_map(fn($u) => ["url" => $u], $urls),
    ]),
]);
$res = json_decode(curl_exec($ch), true);
curl_close($ch);

echo "Submitted: {$res['submitted']} · Waitlisted: {$res['waitlisted']}\n";

// Collect tokens for created captures
$tokens = [];
foreach ($res["jobs"] as $capture) {
    if (isset($capture["token"])) {
        $tokens[$capture["url"]] = $capture["token"];
    }
}

// Wait and display results
foreach ($tokens as $url => $token) {
    do {
        sleep(3);
        $status = json_decode(file_get_contents(
            "https://api.shotbot.net/capture/" . $token
        ), true);
    } while (($status["status"] ?? "") !== "done");

    echo $url . " → " . $status["image"] . "\n";
}

https://update.shotbot.net/k={KEY}/[options/]{URL}
// Same parameters as add | re-captures without deduplication

https://status.shotbot.net/k={KEY}
// → "OK 500:327:5000"  (quota:used:reserve)