Urlbox API Reference

Urlbox API Reference

Technical reference for the Urlbox API

Intoduction

Urlbox is an API that generates high quality screenshots, PDF's, videos, metadata and HTML from website URL's and HTML.

Base URL

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

https://api.urlbox.io

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 

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:

CodeDescription
200OK (when using /v1/render/sync)
201Render created (when using /v1/render/async)
302Temporary redirect - for long-running renders
400Bad Request - request was invalid
401Unauthorized - API key is wrong
429Too many requests - Rate limit was reached
500Urlbox server error - Try again later
502Bad Gateway - Service temporary unavailable
503Service Unavailable - Temporarily offline for maintenance. Try again later

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:

CodeDescription
NoApiKeySuppliedNo API key was supplied in the request
UserNotFoundErrorA user for that API key could not be found
ApiKeyNotFoundThe API key was not found
ProjectNotFoundA project for the API key was not found
ProjectNotEnabledThe project is not enabled
NoPlanThe user currently has no plan
NotConfirmedThe user has not confirmed their email address
NotActiveThe user is not active (subscription has expired)
FeatureNotAvailableOnPlanThe feature is not available on the user's plan
InvalidOptionsThe options supplied were invalid
InvalidTtlThe TTL supplied was invalid
NoS3BucketConfiguredThe user has not configured an S3 bucket for their project
RateLimitExceededErrorThe user's rate limit has been exceeded
TrialUsageReachedThe user's trial usage has been reached
HTMLProcessErrorThe HTML could not be processed
InvalidQueryThe query string was invalid
NoUrlSuppliedNo URL was supplied in the request
UrlWasNotAStringErrorThe URL supplied was not a string
InvalidURLExtensionErrorThe URL extension was invalid
InvalidURLErrorThe URL was invalid
URLDoesNotResolveErrorThe URL does not resolve to a valid IP address
RenderTimeoutErrorThe render timed out before it could be completed
TokenlessRequestsNotEnabledThe user has not enabled tokenless (basic render link) requests
NoQuerySentNo query was sent in the request
TokenNotMatchedErrorThe token supplied did not match the token for the query string
EngineResponseNotOkErrorThe rendering engine was not able to generate the render
EngineAsyncResponseNotOkErrorThe rendering engine was not able to generate the render (async)
TimedOutErrorThe request timed out
NoRenderIdProvidedNo render ID was provided (when looking up a render)
ApiKeyWrongFormatThe API key was not sent in the correct format

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

Creating a render synchronously is achieved by calling this endpoint.

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 will contain a renderUrl key which is a temporary URL pointing to the generated render. This renderUrl will expire after 30 days. The size key contains the size of the render in bytes.

Long running requests

After 95 seconds, if the render has not yet been generated, the API will return a 307 Temporary Redirect response with a Location header set to a temporary redirect URL.

This is to prevent request timeouts from cloudflare interrupting the request early.

When this URL is followed the request will continue to wait for the render to be returned. The response body will contain a redirectUrl key also 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 will count as two renders.

Options

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

NameTypeDescription
urlstringThe URL to render
htmlstringThe HTML to render
formatstringThe output format of the render. One of png, jpg,webp, pdf, svg, mp4,webm,md
widthintegerThe width of the viewport in pixels
heightintegerThe height of the viewport in pixels
full_pagebooleanWhether to render the full page or just the viewport
selectorstringScreenshot just the element specified by the selector
hide_cookie_bannersbooleanWhether to hide cookie banners
block_adsbooleanWhether to block ads
POST /v1/render/sync

Request

curl -X POST \
	https://api.urlbox.io/v1/render/sync \
	-H 'Authorization: Bearer ' \
	-H 'Content-Type: application/json' \
	-d '
{
	"url": "https://urlbox.io",
	"format": "png",
	"width": 1280,
	"height": 720
}
'

Response

{
  "renderUrl":"https://renders.urlbox.io/urlbox1/renders/646625c282754962161b5cb3/2023/9/25/eee820e7-0d85-46af-94ff-1f6160664f3a.png",
  "size":310517
}

Create a render asynchronously

Creating a render asynchronously is achieved by calling this endpoint.

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-urlencoded payloads.

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

Response

This endpoint responds immediately with HTTP status code 201 Created once a render request has been successfully accepted. The response body will contain a statusUrl which allows you to poll the current status of the render.

Caching

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

Options

To see a full list of options that can be supplied, see the options reference.

POST /v1/render/async

Request

curl -X POST \
	https://api.urlbox.io/v1/render/async \
	-H 'Authorization: Bearer ' \
	-H 'Content-Type: application/json' \
	-d '
{
	"url": "https://urlbox.io",
	"format": "png",
	"width": 1280,
	"height": 720
}
'

Response

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

Check the status of a render

You can check the status of a render by calling this endpoint.

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.

Response

This endpoint responds immediately with HTTP status code 200 OK once a render request has been successfully accepted. The response body will contain a statusUrl key which allows you to poll the current status of the render.

GET /v1/render/:renderId

Request

curl https://api.urlbox.io/v1/render/250ea007-552c-4555-ba2b-ef1c73e18be2

Response

HTTP/1.1 200 OK
Content-Type: application/json
{
  "renderId": "250ea007-552c-4555-ba2b-ef1c73e18be2",
  "status": "succeeded",
  "renderUrl": "https://renders.urlbox.io/urlbox1/renders/571f54138cd8b877077d3788/2023/9/25/250ea007-552c-4555-ba2b-ef1c73e18be2.png",
  "size": 781026
}