Signed URLs

Signed URLs let you share a screenshot with anyone — without giving them your API key. The URL is cryptographically signed so only valid links work, and you control how long they last.

This is useful when you need to:

Embed screenshots in emails or reports
Share a screenshot link with a client or teammate
Display screenshots on public web pages using <img> tags
Give temporary access to an image without building a proxy endpoint

How It Works

You create a screenshot using the Screenshots API.
Once the screenshot is completed, you call the signed URL endpoint with the screenshot ID.
The API returns a special URL that includes a cryptographic signature and an expiration timestamp.
Anyone with that URL can download the image — no API key needed. Once it expires, the URL returns 403 Forbidden.

Generate a Signed URL

POST /v1/screenshots/{id}/signed-url

Creates a time-limited signed URL for a completed screenshot. The screenshot must have completed status.

Parameters

Parameter	Type	Default	Description
`expires_in`	integer	60	How long the URL stays valid, in minutes. Range: 1–43,200 (30 days). Pass `0` for a permanent URL.

Example: URL that expires in 24 hours

curl -X POST https://api.screenshotrun.com/v1/screenshots/550e8400-.../signed-url \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"expires_in": 1440}'

Response

{
  "data": {
    "url": "https://api.screenshotrun.com/v1/screenshots/550e8400-.../signed-image?expires=1741520400&signature=abc123...",
    "expires_at": "2026-03-10T10:30:00+00:00"
  }
}

Example: Permanent signed URL

curl -X POST https://api.screenshotrun.com/v1/screenshots/550e8400-.../signed-url \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"expires_in": 0}'

Warning

Permanent URLs stay valid as long as the screenshot image exists. Keep in mind that images are deleted after the retention period ends.

Using Signed URLs

The signed URL works like any regular image URL. No authentication needed.

In HTML

<img src="https://api.screenshotrun.com/v1/screenshots/550e8400-.../signed-image?expires=1741520400&signature=abc123..." alt="Website screenshot">

Download with cURL

# No Authorization header needed
curl "https://api.screenshotrun.com/v1/screenshots/550e8400-.../signed-image?expires=1741520400&signature=abc123..." \
  -o screenshot.png

Error Responses

Status	When
`403 Forbidden`	The signed URL has expired or the signature is invalid.
`404 Not Found`	The screenshot does not exist or is not `completed`.
`410 Gone`	The screenshot image has been deleted after the retention period.

Security Notes

Signed URLs use HMAC signatures — they cannot be forged or modified.
Each signed URL is tied to one specific screenshot. You cannot change the screenshot ID in the URL.
Use short expiration times when sharing sensitive content. For public screenshots, permanent URLs are fine.
If a signed URL is leaked, it cannot be revoked individually. The image becomes inaccessible once the retention period ends.