canonical: https://jentic.com/apis/cloudlayer.io/cloudlayer

# CloudLayer Document Generation API

Jentic publishes the only available OpenAPI specification for CloudLayer Document Generation API, keeping it validated and agent-ready. CloudLayer turns HTML, URLs, and templates into PDFs and images via a REST API. The v2 surface adds asynchronous job processing and asset storage, so callers can submit a render request, get back a job ID, and pick up the rendered file later - useful when generating long PDFs that exceed a single HTTP timeout. Authentication is an X-API-Key header.

## For AI agents

Render PDFs and images from HTML strings, public URLs, or stored templates on CloudLayer using an X-API-Key header.

## Scope

Does not OCR existing PDFs, edit existing PDFs, or convert non-HTML source formats - use for HTML-, URL-, and template-based PDF and image rendering only.

## Capabilities

- Render an HTML string to PDF via `/html/pdf`
- Render a public URL to PDF via `/url/pdf` with optional page selectors
- Generate a PDF from a stored template and JSON data via `/template/pdf`
- Render HTML, URL, or template to PNG or JPG image via the /image endpoints
- Manage asynchronous render jobs and retrieve completed assets
- Inspect account details and remaining usage at /account

## Use cases

### Invoice and Receipt PDF Generation

Generate transactional PDFs such as invoices, receipts, and order confirmations from server-rendered HTML. POST `/html/pdf` with the HTML string and any header/footer markup, and CloudLayer returns the rendered PDF either inline or as a job ID for async pickup. Avoids running headless Chromium in production.

Example prompt: POST `/html/pdf` with the rendered invoice HTML and pageMargin settings, then download the PDF or poll the job ID.

### Web Page Screenshots

Capture screenshots of public web pages for monitoring, social previews, or change-detection alerts. POST `/url/image` returns PNG or JPG, while POST `/url/pdf` returns the same page as a multi-page PDF. Useful when an app needs to embed a snapshot of an external page in a report.

Example prompt: POST `/url/image` with url=https://example.com/dashboard and format=png to capture a screenshot for the daily digest email.

### Template-Based Document Generation

Store reusable templates (contracts, certificates, statements) and render them with per-customer data. `/template/pdf` and `/template/image` accept a template ID and a JSON data block, applying the data via the template's placeholders. Keeps document layout under design control instead of inline HTML.

Example prompt: POST `/template/pdf` with templateId=cert-2026 and data={ name, course, date } to render the completion certificate.

### AI Agent Document Rendering

Let a Jentic-powered agent render documents on demand. The agent searches Jentic for 'render HTML to PDF', loads the CloudLayer createPdf operation, and executes it with the HTML and options. The X-API-Key stays in your Jentic One instance.

Example prompt: Search Jentic for 'render HTML to PDF', load the CloudLayer htmlToPdf operation, and execute with the agent-generated HTML.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/html/pdf` | Render HTML to PDF |
| POST | `/url/pdf` | Render a URL to PDF |
| POST | `/template/pdf` | Render a stored template to PDF |
| POST | `/html/image` | Render HTML to PNG or JPG |
| POST | `/url/image` | Render a URL to PNG or JPG |
| GET | `/jobs/{jobId}` | Get the status of a render job |
| GET | `/assets` | List stored render assets |
| GET | `/account` | Get account information and usage |

## Key resources

- **HTML Rendering** — HTML to PDF and HTML to image at `/html/pdf` and `/html/image.`
- **URL Rendering** — URL to PDF and URL to image at `/url/pdf` and `/url/image.`
- **Template Rendering** — Template-based PDF and image generation at `/template/pdf` and `/template/image.`
- **Jobs** — Async render job tracking at /jobs and `/jobs/{jobId}.`
- **Assets** — Stored render outputs at /assets.
- **Account** — Account information and credit usage at /account.

## Why Jentic

- **Setup:** Wiring the CloudLayer Document Generation API by hand means adding your X-API-Key header on every request and pointing the render calls at api.cloudlayer.io/v2 yourself. Through Jentic you install once, import the CloudLayer Document Generation API from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** CloudLayer names the render source in the request body rather than pinning one id in the URL path, so scope the agent by the operations it needs, such as rendering HTML to PDF or capturing a URL screenshot. You choose that set, so operations like reading account details or listing assets are only in reach if you include them.
- **Credential handling:** Your CloudLayer X-API-Key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'render HTML to PDF' or 'screenshot a URL', and Jentic returns the matching CloudLayer operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **PDFMonkey** — Template-first PDF generation with a built-in template editor.
- **Filestack** — File upload, transformation, and storage that pairs with rendered assets.
- **CloudConvert API** — Generic file format conversion that can also produce PDFs from many input formats.

## FAQ

### Why is there no official OpenAPI spec for CloudLayer Document Generation API?

CloudLayer does not publish a structured OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call CloudLayer Document Generation API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the CloudLayer Document Generation API use?

The API uses an X-API-Key header. Generate the key in the CloudLayer dashboard and pass it on every request. Through Jentic, the key is stored encrypted in the vault and never enters the agent's context.

### Can I render long PDFs without hitting an HTTP timeout?

Yes. v2 supports asynchronous processing - POST `/html/pdf` or `/url/pdf` returns a job ID, and GET `/jobs/{jobId}` reports the status. The rendered PDF is then available under /assets, which avoids long-lived synchronous connections for heavy documents.

### How do I capture a screenshot of a URL?

POST `/url/image` with the target URL and format (png or jpg). Optional fields include viewport width and height, full-page capture, and wait selectors so the screenshot fires after a specific element is rendered.

### How do I render an HTML invoice through Jentic?

Run jentic search 'render HTML to PDF', load the CloudLayer htmlToPdf operation, and execute with the HTML body and any margin, header, or footer options. Jentic handles the X-API-Key from the stored credential.

### Does CloudLayer support PDF templates?

Yes. Store templates in the CloudLayer dashboard, then call POST `/template/pdf` with the template ID and a JSON data object. The template's placeholders are filled in at render time, keeping layout decisions out of application code.

### Can I limit what my agent is allowed to do with the CloudLayer Document Generation API?

Yes. Because Jentic One is self-hosted, you decide which CloudLayer operations and credentials your agent can use. Since CloudLayer names the render source in the request body rather than in the URL path, you scope the agent by the operations it needs, such as rendering HTML to PDF at POST `/html/pdf` or capturing a URL screenshot at POST `/url/image.` Read-only operations like inspecting account usage at GET /account or listing stored assets at GET /assets are only in reach if you choose to include them.