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:

Code	Description
`200`	OK (when using `/v1/render/sync`)
`201`	Render created (when using `/v1/render/async`)
`302`	Temporary redirect - for long-running renders
`400`	Bad Request - request was invalid
`401`	Unauthorized - API key is wrong
`429`	Too many requests - Rate limit was reached
`500`	Urlbox server error - Try again later
`502`	Bad Gateway - Service temporary unavailable
`503`	Service 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:

Code	Description
`NoApiKeySupplied`	No API key was supplied in the request
`UserNotFoundError`	A user for that API key could not be found
`ApiKeyNotFound`	The API key was not found
`ProjectNotFound`	A project for the API key was not found
`ProjectNotEnabled`	The project is not enabled
`NoPlan`	The user currently has no plan
`NotConfirmed`	The user has not confirmed their email address
`NotActive`	The user is not active (subscription has expired)
`FeatureNotAvailableOnPlan`	The feature is not available on the user's plan
`InvalidOptions`	The options supplied were invalid
`InvalidTtl`	The TTL supplied was invalid
`NoS3BucketConfigured`	The user has not configured an S3 bucket for their project
`RateLimitExceededError`	The user's rate limit has been exceeded
`TrialUsageReached`	The user's trial usage has been reached
`HTMLProcessError`	The HTML could not be processed
`InvalidQuery`	The query string was invalid
`NoUrlSupplied`	No URL was supplied in the request
`UrlWasNotAStringError`	The URL supplied was not a string
`InvalidURLExtensionError`	The URL extension was invalid
`InvalidURLError`	The URL was invalid
`URLDoesNotResolveError`	The URL does not resolve to a valid IP address
`RenderTimeoutError`	The render timed out before it could be completed
`TokenlessRequestsNotEnabled`	The user has not enabled tokenless (basic render link) requests
`NoQuerySent`	No query was sent in the request
`TokenNotMatchedError`	The token supplied did not match the token for the query string
`EngineResponseNotOkError`	The rendering engine was not able to generate the render
`EngineAsyncResponseNotOkError`	The rendering engine was not able to generate the render (async)
`TimedOutError`	The request timed out
`NoRenderIdProvided`	No render ID was provided (when looking up a render)
`ApiKeyWrongFormat`	The 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.

Name	Type	Description
`url`	`string`	The URL to render
`html`	`string`	The HTML to render
`format`	`string`	The output format of the render. One of `png`, `jpg`,`webp`, `pdf`, `svg`, `mp4`,`webm`,`md`
`width`	`integer`	The width of the viewport in pixels
`height`	`integer`	The height of the viewport in pixels
`full_page`	`boolean`	Whether to render the full page or just the viewport
`selector`	`string`	Screenshot just the element specified by the selector
`hide_cookie_banners`	`boolean`	Whether to hide cookie banners
`block_ads`	`boolean`	Whether 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
}

Storage Options

Render Link