Assets

Assets are the files generated by cloudlayer.io API calls — PDFs, PNGs, JPGs, and WebP images. Every document generation request produces an asset that you can retrieve later by its ID.

Assets are particularly useful when using async mode, where the generation response returns a job ID instead of the file directly. Once the job completes, the asset is available for download.

Endpoints

GET /v1/assets/:id
GET /v1/assets

GET /v2/assets/:id
GET /v2/assets

Get a Single Asset

Retrieve a specific asset by its ID.

GET /v1/assets/:id

GET /v2/assets/:id

Path Parameters

Examples

cURL

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

JavaScript (fetch)

const assetId = "ast_abc123def456";

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

const asset = await response.json();
console.log(asset);

Python (requests)

import requests

asset_id = "ast_abc123def456"

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

asset = response.json()
print(asset)

Response

{
  "id": "ast_abc123def456",
  "jobId": "job_xyz789",
  "ext": "pdf",
  "type": "application/pdf",
  "size": 245760,
  "url": "https://storage.cloudlayer.io/assets/ast_abc123def456.pdf",
  "timestamp": "2024-01-15T10:30:00.000Z"
}

List Assets

Retrieve a paginated list of all your assets, ordered by creation date (newest first).

GET /v1/assets

GET /v2/assets

Query Parameters

Examples

cURL

# Get the 25 most recent assets
curl -X GET "https://api.cloudlayer.io/v2/assets" \
  -H "X-API-Key: your-api-key-here"

# Paginate: get assets 26-50
curl -X GET "https://api.cloudlayer.io/v2/assets?limit=25&offset=25" \
  -H "X-API-Key: your-api-key-here"

JavaScript (fetch)

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

const assets = await response.json();
console.log(assets);

Python (requests)

import requests

response = requests.get(
    "https://api.cloudlayer.io/v2/assets",
    params={"limit": 10, "offset": 0},
    headers={"X-API-Key": "your-api-key-here"},
)

assets = response.json()
for asset in assets:
    print(f"{asset['id']} - {asset['ext']} - {asset['size']} bytes")

Response

[
  {
    "id": "ast_abc123def456",
    "jobId": "job_xyz789",
    "ext": "pdf",
    "type": "application/pdf",
    "size": 245760,
    "url": "https://storage.cloudlayer.io/assets/ast_abc123def456.pdf",
    "timestamp": "2024-01-15T10:30:00.000Z"
  },
  {
    "id": "ast_ghi789jkl012",
    "jobId": "job_mno345",
    "ext": "png",
    "type": "image/png",
    "size": 102400,
    "url": "https://storage.cloudlayer.io/assets/ast_ghi789jkl012.png",
    "timestamp": "2024-01-15T10:25:00.000Z"
  }
]

Response Fields

Download an Asset

The url field in the asset response is a direct download link. You can use it to download the file without additional authentication:

cURL

# First, get the asset metadata
ASSET_URL=$(curl -s "https://api.cloudlayer.io/v2/assets/ast_abc123def456" \
  -H "X-API-Key: your-api-key-here" | jq -r '.url')

# Then download the file
curl -o downloaded-file.pdf "$ASSET_URL"

JavaScript (fetch)

// Get asset metadata
const metaResponse = await fetch(
  "https://api.cloudlayer.io/v2/assets/ast_abc123def456",
  {
    headers: { "X-API-Key": "your-api-key-here" },
  }
);
const asset = await metaResponse.json();

// Download the file using the pre-authenticated URL
const fileResponse = await fetch(asset.url);
const fileBuffer = await fileResponse.arrayBuffer();

Python (requests)

import requests

# Get asset metadata
meta_response = requests.get(
    "https://api.cloudlayer.io/v2/assets/ast_abc123def456",
    headers={"X-API-Key": "your-api-key-here"},
)
asset = meta_response.json()

# Download the file
file_response = requests.get(asset["url"])
with open(f"downloaded.{asset['ext']}", "wb") as f:
    f.write(file_response.content)

Async Workflow

When using async mode for document generation, use the Assets endpoint to retrieve the result:

// 1. Start an async generation job
const jobResponse = await fetch("https://api.cloudlayer.io/v2/html/pdf", {
  method: "POST",
  headers: {
    "X-API-Key": "your-api-key-here",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    html: btoa("<h1>Hello World</h1>"),
    async: true,
  }),
});

const job = await jobResponse.json();
console.log(`Job started: ${job.id}`);

// 2. Poll the job until it completes
let jobStatus;
do {
  await new Promise((resolve) => setTimeout(resolve, 1000)); // Wait 1 second
  const statusResponse = await fetch(
    `https://api.cloudlayer.io/v2/jobs/${job.id}`,
    { headers: { "X-API-Key": "your-api-key-here" } }
  );
  jobStatus = await statusResponse.json();
} while (jobStatus.status === "pending" || jobStatus.status === "processing");

// 3. Retrieve the generated asset
if (jobStatus.status === "completed") {
  const assetsResponse = await fetch(
    "https://api.cloudlayer.io/v2/assets?limit=1",
    { headers: { "X-API-Key": "your-api-key-here" } }
  );
  const assets = await assetsResponse.json();
  console.log(`Download URL: ${assets[0].url}`);
}

Tips

• Asset retention: Assets are retained based on your subscription plan. Check your plan details for the retention period. Download and store important assets in your own storage if long-term retention is required.
• Storage usage: Use the Account endpoint to monitor your total storage usage (bytesUsed).
• User storage: Configure your own S3-compatible storage to have assets delivered directly to your bucket. See the Storage endpoint for configuration.
• Pagination: When listing assets, use limit and offset to paginate through results. The maximum limit is 100 per request.