API Overview

All API requests are made to:

https://api.cloudlayer.io/v1

Every endpoint path in this documentation is relative to this base URL. For example, POST /v1/html/pdf means you send your request to https://api.cloudlayer.io/v1/html/pdf.

All API requests are made to:

https://api.cloudlayer.io/v2

Every endpoint path in this documentation is relative to this base URL. For example, POST /v2/html/pdf means you send your request to https://api.cloudlayer.io/v2/html/pdf.

X-API-Key: your-api-key-here

cURL

curl -X GET "https://api.cloudlayer.io/v1/account" \
  -H "X-API-Key: your-api-key-here"

JavaScript (fetch)

const response = await fetch("https://api.cloudlayer.io/v1/account", {
  method: "GET",
  headers: {
    "X-API-Key": "your-api-key-here",
  },
});

const data = await response.json();

Python (requests)

import requests

response = requests.get(
    "https://api.cloudlayer.io/v1/account",
    headers={"X-API-Key": "your-api-key-here"},
)

data = response.json()

cURL

curl -X GET "https://api.cloudlayer.io/v2/account" \
  -H "X-API-Key: your-api-key-here"

JavaScript (fetch)

const response = await fetch("https://api.cloudlayer.io/v2/account", {
  method: "GET",
  headers: {
    "X-API-Key": "your-api-key-here",
  },
});

const data = await response.json();

Python (requests)

import requests

response = requests.get(
    "https://api.cloudlayer.io/v2/account",
    headers={"X-API-Key": "your-api-key-here"},
)

data = response.json()

Response content types depend on the endpoint:

Scenario	Response Content-Type
Document generation	application/pdf, image/png, image/jpeg, or image/webp
Account, jobs, assets, storage	application/json

All document generation responses return the raw file binary directly.

All v2 responses return JSON:

Scenario	Response Content-Type
Document generation (async — default)	application/json (job metadata)
Document generation (sync, async: false)	application/json (completed job with asset URL)
Account, jobs, assets, storage	application/json

v2 always returns JSON with job metadata. Only v1 returns raw binary file content directly.

All document generation requests in v1 are processed synchronously. The API waits for the document to be generated and returns the raw file binary (PDF or image) directly in the response body.

curl -X POST "https://api.cloudlayer.io/v1/html/pdf" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{"html": "PGgxPkhlbGxvIFdvcmxkPC9oMT4="}' \
  --output result.pdf

The response is the raw PDF binary. Use --output (cURL) or handle the response as a binary stream.

Tip: For large or complex documents that take a long time to render, consider switching to the v2 API which supports asynchronous processing.

By default, document generation endpoints in v2 process your request asynchronously. The API returns a JSON response immediately with the job ID, and the generated file is stored and accessible via the Assets endpoint once processing completes.

Asynchronous (default)

curl -X POST "https://api.cloudlayer.io/v2/html/pdf" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{"html": "PGgxPkhlbGxvIFdvcmxkPC9oMT4="}'

Returns a JSON response immediately:

{
  "id": "1705312200000",
  "status": "pending"
}

Poll the Jobs endpoint or use Webhooks to be notified when the job completes. Once complete, retrieve the result from the Assets endpoint.

Synchronous

To process a request synchronously, include "async": false in your request body. The API still returns JSON, but waits for processing to complete before responding:

curl -X POST "https://api.cloudlayer.io/v2/html/pdf" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{"html": "PGgxPkhlbGxvIFdvcmxkPC9oMT4=", "async": false}'

The response is JSON with the completed job details, including the asset URL for downloading the generated file.

Note: In v2, storage also defaults to true. When async is true (the default), the generated file is automatically stored and accessible via the Assets endpoint. You can set "storage": false to disable storage, but this requires "async": false as well.

{
  "statusCode": 400,
  "message": "The 'html' field is required and must be a base64-encoded string."
}

{
  "status": "error",
  "message": "Generation failed: page timeout exceeded."
}

Async & Storage Parameters (v2 only)

Parameter	Type	Default	Description
async	boolean	true	Process the request asynchronously. When true, the API returns immediately with a job ID. Set to false to wait for processing to complete before the API responds (response is still JSON).
storage	boolean	true	Store the generated file in cloudlayer.io storage. When true, the file is accessible via the Assets endpoint. Requires a plan that supports storage.