logoKeepMot API
DocsAPI ReferenceRender API

PDF · JSON Render

Render API

Turn a complete JSON document definition into PDF with direct control over pages, coordinates, text, shapes, images, tables, and pagination.

Use JSON Render when the caller owns the layout or when a document does not match a saved template. Page dimensions and element positions are expressed in millimetres.

The request is validated and rendered in one server-side flow. A successful response contains the generated PDF bytes directly.

Endpoint

POST/pdf/render

Content-Type

application/json

Success

200 · application/pdf

Cache

no-store

Request body

JSON
pages
Page[]required

One or more page definitions. Pages are emitted in array order.

pages[].width
numberrequired

Physical page width in millimetres, for example 210 for A4.

pages[].height
numberrequired

Physical page height in millimetres, for example 297 for A4.

pages[].elements
Element[]required

Text, images, barcodes, tables, shapes, stacks, and other supported document elements.

Element reference

pages[].elements

Each entry is selected by its type. Coordinates and dimensions are expressed in millimetres unless a field says otherwise.

Table

type: "table"

Renders structured rows and columns. Rows may be supplied inline or bound with an expression such as {{#each items}}; cell-level values may be scalars or rich content objects with spans and styles.

x / y
numberrequired

Top-left position on the page.

width
number

Overall table width. Fixed column widths should normally add up to this value.

columns
TableColumn[]required

Column definitions. Each column has a key, optional header, width ({ mode: fixed | percent | auto, value? }), role, cell, and header_cell.

rows
string | TableRow[]required

A binding expression or inline row array. Object keys match columns[].key.

cell
TableCellStyle

Default cell style: fill, text, padding, borders, and content offsets.

header
object

Header controls: show, repeat_on_page_break, default cell style, and optional multi-row header definitions.

body
object

Body cell defaults and alternate_fill for zebra striping.

grid
object

Outer and internal border strokes: top, right, bottom, left, horizontal, and vertical.

pagination
object

Page-break behavior: keep_spans_together, row_min_height, and header_min_height.

preview_rows
TableRow[]

Studio preview data. For dynamic production data, use rows binding and replace it through the Template API.

JSON example
{
  "type": "table",
  "x": 20,
  "y": 40,
  "width": 170,
  "columns": [
    { "key": "name", "header": "Name", "width": { "mode": "fixed", "value": 100 } },
    { "key": "amount", "header": "Amount", "width": { "mode": "fixed", "value": 70 } }
  ],
  "rows": [
    { "name": "Design", "amount": "$120.00" },
    { "name": "Hosting", "amount": "$25.00" }
  ],
  "header": { "show": true, "repeat_on_page_break": true },
  "cell": { "padding": { "x": 2, "y": 2 }, "text": { "font_size": 9 } },
  "grid": {
    "horizontal": { "color": "#d1d5db", "width": 0.2 },
    "vertical": { "color": "#d1d5db", "width": 0.2 }
  }
}

Text

type: "text"

Renders block-based rich text. Content contains paragraphs, lists, or page breaks; inline runs carry the actual text and optional run styling.

x / y
numberrequired

Element position. x may be replaced by x_anchor for reference-based horizontal alignment.

content.blocks
TextBlock[]required

Paragraph, list, or page_break blocks. Paragraph blocks contain an inlines array.

content.blocks[].inlines
Inline[]

Text and other supported inline runs. A text run uses { type: "text", text, style? }.

defaults.run
object

Default run style, including font_family, font_size, font_weight, font_style, color, decoration, and letter_spacing.

defaults.paragraph
object

Default paragraph alignment, line height, spacing, indentation, and related paragraph formatting.

frame
object

Text frame sizing and overflow behavior, including width, height, padding, vertical_align, shrink_to_fit, and min_font_size.

rotation / z_index
number

Optional rotation in degrees and paint order.

link
object

Optional clickable link specification.

JSON example
{
  "type": "text",
  "x": 20,
  "y": 20,
  "frame": { "width": 120, "height": 24, "vertical_align": "middle" },
  "defaults": {
    "run": { "font_family": "Helvetica", "font_size": 16, "color": "#111827" },
    "paragraph": { "align": "left" }
  },
  "content": {
    "blocks": [{
      "type": "paragraph",
      "inlines": [
        { "type": "text", "text": "Invoice ", "style": { "font_weight": "bold" } },
        { "type": "text", "text": "#1048" }
      ]
    }]
  }
}

Image

type: "image"

Places an image asset or an embedded base64 source inside a rectangular frame.

x / y
numberrequired

Top-left position. x_anchor may be used instead of x.

width / height
numberrequired

Rendered image frame dimensions.

asset
string

Asset identifier or supported asset value. Use this or source.

source
object

Embedded image source, for example { kind: "base64", payload, format }.

format
string

Image format hint such as png, jpeg, webp, or svg.

fit
string

How the image fills its frame: fill, contain, cover, or none.

opacity
number

Opacity from 0 (transparent) to 1 (opaque).

rotation / z_index
number

Optional rotation and paint order.

JSON example
{
  "type": "image",
  "x": 150,
  "y": 15,
  "width": 40,
  "height": 24,
  "fit": "contain",
  "opacity": 1,
  "source": {
    "kind": "base64",
    "format": "png",
    "payload": "iVBORw0KGgoAAA..."
  }
}

Barcode

type: "barcode"

Renders a one-dimensional or matrix barcode. Use a non-QR format such as code128 for conventional barcodes.

x / y
numberrequired

Top-left position.

width / height
numberrequired

Barcode bounding box.

format
stringrequired

Barcode symbology, for example code128, ean13, code39, or datamatrix.

content
stringrequired

Value encoded into the barcode.

style
object

Foreground/fill, background, quiet-zone, and other visual settings supported by the renderer.

options
object

Format-specific controls such as error correction, module shape, GS1, bearer bars, or Data Matrix shape.

barcode_text
object

Human-readable label settings: enabled, content, position, offset, and text style.

rotation / z_index
number

Optional rotation and paint order.

JSON example
{
  "type": "barcode",
  "x": 20,
  "y": 250,
  "width": 70,
  "height": 18,
  "format": "code128",
  "content": "INV-2026-0018",
  "barcode_text": {
    "enabled": true,
    "position": "bottom",
    "style": { "font_size": 8 }
  }
}

QR Code

type: "barcode"

QR Code uses the barcode element contract with format set to qrcode. Keep width and height equal to avoid distortion.

x / y
numberrequired

Top-left position.

width / height
numberrequired

Square QR Code dimensions.

format
"qrcode"required

Selects QR Code encoding while the element type remains barcode.

content
stringrequired

URL, text, or other value encoded in the QR Code.

options
object

Quiet zone, module shape, and other supported barcode options.

style
object

Module color and background presentation. Use color, background_color, or fill.

rotation / z_index
number

Optional rotation and paint order.

JSON example
{
  "type": "barcode",
  "x": 160,
  "y": 250,
  "width": 28,
  "height": 28,
  "format": "qrcode",
  "content": "https://gpdf.keepmot.com",
  "options": { "quiet_zone": 2, "module_shape": "square" },
  "style": { "color": "#111827", "background_color": "#ffffff" }
}

Total

type: "total"

Creates a vertical flow container for tables and blocks. Children are laid out in order, making it useful for invoice bodies followed by totals or notes.

children
(Table | Block)[]required

Ordered flow children. A table is embedded directly; a block contains its own elements array.

gap
number

Vertical spacing between children.

z_index
number

Paint order for the container.

comment
string

Optional authoring annotation ignored by layout.

children[].type
"table" | "block"required

Selects a flow child. Block children can contain text, image, barcode, line, path, and shape elements.

JSON example
{
  "type": "total",
  "gap": 4,
  "children": [
    {
      "type": "table",
      "x": 20,
      "y": 40,
      "columns": [{ "key": "item", "width": { "mode": "fixed", "value": 170 } }],
      "rows": [{ "item": "Service total: $145.00" }]
    },
    {
      "type": "block",
      "elements": [{
        "type": "text",
        "y": 0,
        "content": { "blocks": [{ "type": "paragraph", "inlines": [{ "type": "text", "text": "Thank you" }] }] }
      }]
    }
  ]
}

Line

type: "line"

Draws a straight line segment between two points.

x1 / y1
numberrequired

Start point.

x2 / y2
numberrequired

End point.

stroke
object

Line color, width, dash pattern, opacity, line cap, and related stroke settings.

marker
object

Optional start/end marker configuration for arrows or other endpoint markers.

z_index
number

Paint order.

link
object

Optional clickable link specification.

JSON example
{
  "type": "line",
  "x1": 20,
  "y1": 235,
  "x2": 190,
  "y2": 235,
  "stroke": { "color": "#9ca3af", "width": 0.3 }
}

Path

type: "path"

Draws a scalable vector path using SVG path data, mapped from view_box coordinates into the requested frame.

x / y
numberrequired

Top-left position of the output frame.

width / height
numberrequired

Rendered frame dimensions.

d
stringrequired

SVG path data, for example M, L, C, Q, and Z commands.

view_box
object

Source coordinate system: x, y, width, and height.

fill
object

Interior fill color and opacity.

stroke
object

Outline color, width, dash pattern, and related stroke settings.

z_index
number

Paint order.

link
object

Optional clickable link specification.

JSON example
{
  "type": "path",
  "x": 20,
  "y": 245,
  "width": 24,
  "height": 24,
  "view_box": { "x": 0, "y": 0, "width": 24, "height": 24 },
  "d": "M12 2 L22 22 L2 22 Z",
  "fill": { "color": "#6366f1" },
  "stroke": { "color": "#4338ca", "width": 0.4 }
}

Request example

Send the JSON body below with a POST request. A successful response contains the generated PDF bytes.

JSON example
{
  "pages": [
    {
      "width": 210,
      "height": 297,
      "elements": [
        {
          "type": "text",
          "x": 20,
          "y": 20,
          "z_index": 1,
          "content": {
            "blocks": [
              {
                "type": "paragraph",
                "inlines": [
                  {
                    "type": "text",
                    "text": "Hello gpdf"
                  }
                ]
              }
            ]
          }
        }
      ]
    }
  ]
}

Coordinate system

Body element positions use millimetres from the page origin. Elements may define x/y directly and can carry their own dimensions and z-index.

Rich documents

Add block text, tables, headers, footers, layers, images, barcodes, and pagination only when the document needs them.

Responses

StatusMessageDescription
200PDF generatedThe response body contains application/pdf bytes.
400Invalid request bodyThe body is empty or is not valid JSON.
401Authorization requiredThe Bearer API key is missing, invalid, expired, disabled, or its user is inactive.
402Insufficient Token balanceThe authenticated account does not have enough Tokens for the generated PDF pages.
404Not foundThe requested PDF Worker route does not exist.
415Unsupported mediaThe request Content-Type is not application/json.
422PDF render failedThe renderer rejected the supplied PDF document.
500PDF Worker errorAn unexpected Worker or WASM runtime error occurred.