> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spoolpdf.nandra.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Trial render (IP rate-limited)
> Same body as `POST /v1/render`, without an API key. Does not increment
usage. IP rate-limited. Not for production volume.
## OpenAPI
````yaml /openapi.yaml post /v1/trial/render
openapi: 3.1.0
info:
title: spoolpdf API
version: 0.1.0
description: |
HTML/URL to PDF render API.
Error codes returned in `ErrorEnvelope.error.code`:
`unauthorized`, `validation_error`, `ssrf_blocked`, `rate_limited`,
`concurrency_limit`, `payload_too_large`, `render_failed`,
`subscription_inactive`.
`concurrency_limit` means your plan's parallel render allowance is full
(Free 1, Starter 2, Growth 4, Scale 8). Retry after the interval in
`Retry-After`; the allowance is echoed in `X-Concurrency-Limit`.
servers:
- url: https://spoolpdf-api.nandra.dev
description: Production
- url: http://localhost:8080
description: Local Compose
security: []
tags:
- name: Render
description: Authenticated HTML or URL to PDF.
- name: Trial
description: >-
Unauthenticated smoke-test render. IP rate-limited. Does not increment
usage.
- name: Health
description: Liveness and readiness probes.
paths:
/v1/trial/render:
post:
tags:
- Trial
summary: Trial render (IP rate-limited)
description: |
Same body as `POST /v1/render`, without an API key. Does not increment
usage. IP rate-limited. Not for production volume.
operationId: postTrialRender
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RenderRequest'
example:
html: Trial
responses:
'200':
description: PDF bytes
headers:
X-Request-Id:
schema:
type: string
format: uuid
content:
application/pdf:
schema:
type: string
format: binary
'400':
$ref: '#/components/responses/Error'
'422':
$ref: '#/components/responses/Error'
'429':
$ref: '#/components/responses/Error'
'502':
$ref: '#/components/responses/Error'
x-codeSamples:
- lang: bash
label: curl
source: |
curl -sS -o trial.pdf \
-X POST https://spoolpdf-api.nandra.dev/v1/trial/render \
-H "Content-Type: application/json" \
-d '{"html":"Trial
"}'
components:
schemas:
RenderRequest:
type: object
description: |
Exactly one of `html` or `url` must be provided.
properties:
html:
type: string
description: HTML document to render
url:
type: string
format: uri
description: Public URL to render
format:
type: string
description: |
Paper format. Named sizes: A0–A6, Letter, Legal, Tabloid, Ledger
(default A4). Or `{width}x{height}` with optional units, e.g.
`210mmx297mm` or `11x17` (inches when omitted). Height `auto`
(`1024xauto`, `210mmxauto`) renders a single scrolling page;
unitless width is pixels (÷96 → inches).
default: A4
paper_width:
type: string
description: >-
Overrides format width (Gotenberg units, e.g. `8.5in`). Must be
paired with paper_height.
paper_height:
type: string
description: Overrides format height. Must be paired with paper_width.
landscape:
type: boolean
print_background:
type: boolean
scale:
type: number
description: Render scale (default 1)
default: 1
zoom:
type: number
description: Alias for scale when scale is unset
margin:
$ref: '#/components/schemas/Margin'
header:
$ref: '#/components/schemas/HeaderFooter'
footer:
$ref: '#/components/schemas/HeaderFooter'
wait_delay:
type: string
description: Pause before print (Go duration, e.g. `2s` or `500ms`). Max 30s.
wait_for_selector:
type: string
description: CSS selector; Chromium waits until a matching element exists.
wait_for_expression:
type: string
description: JavaScript expression; Chromium waits until it is truthy.
wait_for_network_idle:
type: boolean
description: When true, wait for Chromium network idle (0 connections for 500ms).
extra_http_headers:
type: object
additionalProperties:
type: string
description: |
Headers Chromium sends while loading the page (URL assets included).
Cookie and hop-by-hop names are rejected; use `cookies` for Cookie.
cookies:
type: array
items:
$ref: '#/components/schemas/Cookie'
sandbox:
type: boolean
description: |
Watermarked PDF; does not increment usage. Response includes
`X-Sandbox: true` and omits `X-Usage-Count`. Still uses a
concurrency slot.
pages:
type: string
description: >-
Page ranges to keep, e.g. `1-3,6`. Cannot combine with single_page
or auto height.
single_page:
type: boolean
description: One continuous page (also implied by `{width}xauto` format).
emulate_media:
type: string
enum:
- print
- screen
description: Chromium media type. Default is print.
css:
type: string
description: Inline CSS or a public http(s) stylesheet URL (SSRF-checked).
javascript:
type: string
description: Inline JS or a public http(s) script URL (SSRF-checked).
raise_for_status:
type: boolean
description: |
`true` fails on 3xx/4xx/5xx of the main URL. `false` allows error
pages. Omit to keep Gotenberg default (fail on 4xx/5xx).
auth:
$ref: '#/components/schemas/BasicAuth'
lazy_load_images:
type: boolean
description: Scroll the page so lazy-loaded images fetch before print.
metadata:
$ref: '#/components/schemas/PdfMetadata'
Margin:
type: object
properties:
top:
type: string
right:
type: string
bottom:
type: string
left:
type: string
HeaderFooter:
type: object
properties:
html:
type: string
height:
type: string
Cookie:
type: object
required:
- name
- value
- domain
properties:
name:
type: string
value:
type: string
domain:
type: string
path:
type: string
secure:
type: boolean
http_only:
type: boolean
same_site:
type: string
enum:
- Strict
- Lax
- None
BasicAuth:
type: object
required:
- username
- password
properties:
username:
type: string
password:
type: string
description: >-
HTTP Basic auth for the page URL. Conflicts with extra_http_headers
Authorization.
PdfMetadata:
type: object
properties:
title:
type: string
author:
type: string
subject:
type: string
keywords:
type: string
ErrorEnvelope:
type: object
required:
- error
properties:
error:
type: object
required:
- code
- message
- request_id
properties:
code:
type: string
message:
type: string
request_id:
type: string
format: uuid
responses:
Error:
description: Error envelope
headers:
X-Request-Id:
schema:
type: string
format: uuid
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
````