Urlbox API Reference

Urlbox is an API that generates high quality screenshots, PDFs, videos, metadata and HTML from website URLs and HTML.

Base URL

The base URL for all API requests is https://api.urlbox.com.

https://api.urlbox.com

Authentication

To authenticate an API request, provide a secret key for one of your projects in the Authorization header.

You can generate a secret key by creating a Project. When you first sign up, Urlbox automatically creates a default project for you.

Authorization: Bearer YOUR_URLBOX_SECRET

Errors

Errors are returned in JSON format, with a relevant status code and a human readable message. A code will also be returned in some cases. A requestId is also returned in the response, which can be used to help us debug any issues you may have.

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": {
    "message": "Please confirm your email to continue using the API",
    "code": "NotConfirmed"
  },
  "requestId": "fc147b37-83af-445d-a2c8-d003c13bcffd"
}

HTTP status codes

The table below lists the usual HTTP status codes that will be returned and what they represent in the context of the Urlbox API:

Error codes

The table below lists some of the most common error codes that may be returned in the code field of an error object:

Endpoints

A render is our generic term for anything that can be generated by the API — for example a screenshot is a render, a PDF is a render, so too is a video. You can create all kinds of render using the same endpoint, by specifying the options relevant to that render kind.

Create a render synchronously

Send a POST to /v1/render/sync and pass in the render options you want to use. The endpoint accepts either JSON or form-encoded data.

The only required option is either url or html. When using url, the URL must be publicly accessible.

This endpoint responds with 200 OK once the render has been generated. The response body contains a renderUrl key — a temporary URL pointing to the generated render, which expires after 30 days — and a size key with the size of the render in bytes.

POST /v1/render/sync

Example

{  "url": "https://urlbox.com",  "format": "png",  "width": 1280,  "height": 720}

{  "renderUrl": "https://renders.urlbox.com/urlbox1/renders/646625c282754962161b5cb3/2023/9/25/eee820e7-0d85-46af-94ff-1f6160664f3a.png",  "size": 310517,  "renderTime": 6609,  "queueTime": 127,  "bandwidth": 9429299}

Common options

To see the full list of options, see the options reference. Options can be supplied in camelCase or snake_case.

Long-running requests

After 95 seconds, if the render has not yet been generated, the API returns a 307 Temporary Redirect response with a Location header set to a temporary redirect URL. This prevents request timeouts from Cloudflare interrupting the request early.

When this URL is followed, the request continues to wait for the render to be returned. The response body will contain a redirectUrl key with the same temporary redirect URL. The redirect timeout can be configured using the redirect_after option.

Caching

Requests to this endpoint are not cached, and not de-duplicated. If you make the same request twice, that counts as two renders.

Create a render asynchronously

Send a POST to /v1/render/async and pass in the render options you want to use. The endpoint accepts either application/json or application/x-www-form-urlencoded payloads.

The only required option is either url or html. When using url, the URL must be publicly accessible.

This endpoint responds immediately with 201 Created once a render request has been successfully accepted. The response body contains a status set to created to show that the render request has been accepted and is being processed, and a renderId which is the ID of the render.

The response body also contains a statusUrl which lets you poll the current status of the render. An alternative to polling is to use webhooks.

POST /v1/render/async

Example

{  "url": "https://urlbox.com",  "format": "png",  "width": 1280,  "height": 720}

{  "status": "created",  "renderId": "250ea007-552c-4555-ba2b-ef1c73e18be2",  "statusUrl": "https://api.urlbox.com/v1/render/250ea007-552c-4555-ba2b-ef1c73e18be2"}

Error response

If the render request is rejected, the endpoint responds with a 400 Bad Request status code and an error object in the response body, for example:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": {
    "message": "Invalid URL",
    "code": "InvalidURLError"
  },
  "requestId": "0198613b-e03c-702c-892b-ef21eaaef4a7_pa"
}

Caching

Requests to this endpoint are not cached, and not de-duplicated. If you make the same request twice, that counts as two renders.

Check the status of a render

Send a GET request to /v1/render/:renderId and replace the path variable :renderId with the ID of the render you want to check. This is returned to you when you create a render asynchronously.

This endpoint responds immediately with 200 OK if a render request has been successfully accepted, or if the render has already been generated. The response body contains a renderId, a statusUrl for polling, and a status key which is one of:

• created — The render has been created and is being processed
• retrying — The render has stalled and is being retried
• succeeded — The render has been successfully generated
• failed — The render has failed to be generated
• not-found — The render was not found

For a succeeded render, the response body also contains a renderUrl with the URL of the generated render, and a size with the size of the render in bytes. For a failed render, the response body contains a reason with a human readable message explaining why the render failed. If a renderId is not found, the endpoint responds with 404 Not Found and status set to not-found.

GET /v1/render/:renderId

Example

{  "renderId": "250ea007-552c-4555-ba2b-ef1c73e18be2",  "status": "succeeded",  "renderUrl": "https://renders.urlbox.com/urlbox1/renders/571f54138cd8b877077d3788/2023/9/25/250ea007-552c-4555-ba2b-ef1c73e18be2.png",  "size": 781026,  "renderTime": 6609,  "queueTime": 127,  "bandwidth": 9429299}