JSON Renderer

Generate documents from JSON definitions with full control over layout and content.

Endpoint

POST /api/v1/renderer/json

Description

The JSON Renderer allows you to define documents programmatically using a JSON schema. This gives you complete control over the document structure, styling, and content without needing to use the visual editor.

Request Body

{
  "document": {
    "pages": [
      {
        "width": 595,
        "height": 842,
        "elements": [
          {
            "type": "text",
            "content": "Hello World",
            "x": 50,
            "y": 50,
            "fontSize": 24
          }
        ]
      }
    ]
  },
  "options": {
    "format": "pdf",
    "response": "binary"
  }
}

Query Parameters

POST /api/v1/renderer/json?format=pdf&response=binary&validate=true

Parameter	Type	Default	Description
format	string	pdf	Output format: pdf, png, jpg, html
response	string	binary	Response type: binary, base64, preview
validate	boolean	false	Validate only without rendering
scale	number	1	Scale factor (0.1-2)
quality	number	90	Image quality for JPEG (1-100)
printBackground	boolean	true	Include background in output
displayHeaderFooter	boolean	false	Show header/footer
headerTemplate	string	-	Custom header HTML
footerTemplate	string	-	Custom footer HTML
timeout	number	30000	Render timeout in ms (1000-120000)
fullPage	boolean	false	Capture full page height
omitBackground	boolean	false	Transparent background
raw	boolean	false	Return raw HTML instead of rendered output

Options Object

{
  "document": { ... },
  "options": {
    "format": "pdf",
    "scale": 1,
    "quality": 90,
    "printBackground": true,
    "displayHeaderFooter": false,
    "headerTemplate": "<div style='font-size:10px'>Header</div>",
    "footerTemplate": "<div style='font-size:10px'>Page <span class='pageNumber'></span></div>",
    "timeout": 30000,
    "fullPage": false,
    "omitBackground": false,
    "raw": false
  }
}

Query Parameters Take Precedence

When the same option is specified in both query params and body options, the query parameter value is used.

Options Reference

format

Output format for the rendered document.

Value	Description
pdf	PDF document (default)
png	PNG image
jpg	JPEG image
html	HTML output

response

Response encoding type.

Value	Description
binary	Raw binary data (default)
base64	Base64 encoded string
preview	Preview mode for testing

validate

When true, validates the JSON document structure without rendering. Useful for testing document definitions.

scale

Scale factor for the output.

• Range: 0.1 to 2
• Default: 1

quality

JPEG compression quality. Only applies when format is jpg.

• Range: 1 to 100
• Default: 90

printBackground

When true, includes background colors and images in the output.

displayHeaderFooter

When true, displays custom header and footer templates.

headerTemplate / footerTemplate

Custom HTML templates for headers and footers. Available classes:

• .date - Current date
• .title - Document title
• .url - Document URL
• .pageNumber - Current page number
• .totalPages - Total page count

timeout

Maximum time to wait for rendering in milliseconds.

• Range: 1000 to 120000
• Default: 30000

fullPage

When true, captures the full scrollable page height (useful for long documents).

omitBackground

When true, renders with a transparent background (PNG only).

raw

When true, returns the generated HTML instead of the rendered PDF/image.

Document Schema

Page Object

{
  "width": 595,
  "height": 842,
  "background": "#ffffff",
  "elements": []
}

Element Types

Text Element

{
  "type": "text",
  "content": "Hello World",
  "x": 50,
  "y": 50,
  "width": 200,
  "height": 50,
  "fontSize": 16,
  "fontFamily": "Arial",
  "fontWeight": "bold",
  "color": "#000000",
  "align": "left"
}

Image Element

{
  "type": "image",
  "src": "https://example.com/image.png",
  "x": 50,
  "y": 100,
  "width": 200,
  "height": 150
}

Rectangle Element

{
  "type": "rect",
  "x": 50,
  "y": 50,
  "width": 100,
  "height": 100,
  "fill": "#ea997e",
  "stroke": "#000000",
  "strokeWidth": 2,
  "cornerRadius": 10
}

Examples

Basic Document

curl -X POST "https://api.pdfgenstudio.com/api/v1/renderer/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "document": {
      "pages": [{
        "width": 595,
        "height": 842,
        "elements": [
          {
            "type": "text",
            "content": "Invoice #12345",
            "x": 50,
            "y": 50,
            "fontSize": 28,
            "fontWeight": "bold"
          },
          {
            "type": "text",
            "content": "Date: January 4, 2026",
            "x": 50,
            "y": 90,
            "fontSize": 14
          }
        ]
      }]
    }
  }' \
  --output document.pdf

Validate Only

curl -X POST "https://api.pdfgenstudio.com/api/v1/renderer/json?validate=true" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"document": {"pages": []}}'

Response:

{
  "valid": true,
  "message": "Document structure is valid"
}

PNG with Custom Options

curl -X POST "https://api.pdfgenstudio.com/api/v1/renderer/json?format=png&scale=1.5&printBackground=true" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"document": {...}}' \
  --output document.png

Response

Success (Binary)

• Status: 200 OK
• Content-Type: application/pdf, image/png, image/jpeg, or text/html
• Body: Raw binary data

Success (Base64)

{
  "data": "<base64-encoded-content>",
  "contentType": "application/pdf"
}

Validation Success

{
  "valid": true,
  "message": "Document structure is valid"
}

Error Response

{
  "error": "Validation Error",
  "message": "Invalid document structure",
  "details": ["pages array is required"],
  "statusCode": 422
}