# Urlbox API Reference > Technical reference for the Urlbox API Source: https://urlbox.com/docs/api Last updated: 2026-07-09 --- ## Introduction 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.com`. ```zsh 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. ```bash 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 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`](#create-a-render-synchronously)) | | `201` | Render created (when using [`/v1/render/async`](#create-a-render-asynchronously)) | | `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) | | `OptionNotAvailableOnPlan` | 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](https://urlbox.com/docs/options.md) 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](https://urlbox.com/docs/options.md). 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 | | `click_accept` | `boolean` | Whether to click the accept button on cookie banners | | `block_ads` | `boolean` | Whether to block ads | ```zsh POST /v1/render/sync ``` ```json { "url": "https://urlbox.com", "format": "png", "width": 1280, "height": 720 } ``` ```json { "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 } ``` ## 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](https://urlbox.com/docs/options.md) 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 `status` which will be 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 will also contain a `statusUrl` which allows you to [poll the current status of the render](#check-the-status-of-a-render). An alternative to polling is to [use webhooks](https://urlbox.com/docs/webhooks.md). ##### Error Response If the render request is rejected, the endpoint will respond with a `400 Bad Request` status code, with an error object in the response body for example: ```http 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 will count as two renders. #### Options To see a full list of options that can be supplied, see the [options reference](https://urlbox.com/docs/options.md). ```zsh POST /v1/render/async ``` POST /v1/render/async ```json { "url": "https://urlbox.com", "format": "png", "width": 1280, "height": 720 } ``` ```json { "status": "created", "renderId": "250ea007-552c-4555-ba2b-ef1c73e18be2", "statusUrl": "https://api.urlbox.com/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](#create-a-render-asynchronously). #### Response This endpoint responds immediately with HTTP status code `200 OK` if a render request has been successfully accepted, or if the render has already been generated. The response body will contain a `renderId` key which is the ID of the render, and a `statusUrl` key which allows you to poll the current status of the render. The response body will also contain a `status` key which will be one of the following values: - `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 In the case of a succeeded render, the response body will contain a `renderUrl` key which will contain the URL of the generated render, and a `size` key which will contain the size of the render in bytes. In the case of a failed render, the response body will contain a `reason` key which will contain a human readable message explaining why the render failed. If a renderId is not found, the endpoint will respond with a `404 Not Found` status code, and `status` set to `not-found`. ```zsh GET /v1/render/:renderId ``` GET /v1/render/250ea007-552c-4555-ba2b-ef1c73e18be2 ```json ``` ```http HTTP/1.1 200 OK Content-Type: application/json { "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 } ```