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.

Response content types vary by endpoint and mode:

Scenario	Response Content-Type
Document generation (async — default)	application/json (job details)
Document generation (sync, async: false)	application/pdf, image/png, image/jpeg, or image/webp
Account, jobs, assets, storage	application/json

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": "job_abc123",
  "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 response body will be the raw generated file (PDF or image):

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}' \
  --output result.pdf

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

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.

{
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "The 'html' field is required and must be a base64-encoded string.",
    "details": {
      "field": "html",
      "reason": "missing"
    }
  }
}

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 receive the generated file directly in the response.
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.

List endpoints (GET /v1/jobs, GET /v1/assets) return paginated results. Use standard pagination query parameters:

List endpoints (GET /v2/jobs, GET /v2/assets) return paginated results. Use standard pagination query parameters: