AI Agent & Developer Prompt

Status: Public Documentation & System Prompt. Last updated: 2026-05-29

This document serves a dual purpose: it is an elegant reference for human developers and a highly optimized system prompt for AI coding assistants (like Cursor, GitHub Copilot, and custom GPTs). Import this document to guide your AI in writing 100% valid gPdf JSON payloads.

1. System Context for AI Agents

When acting as an AI coding assistant tasked with generating a PDF layout for gPdf, you must strictly adhere to the layout rules defined below. The gPdf rendering engine does not parse HTML or CSS; instead, it uses a lightweight, high-performance AST (Abstract Syntax Tree) defined by absolute coordinates in millimeters.

2. Core Layout Engine Rules

2.1 Coordinate Space

Units: Coordinates and lengths (x, y, width, height) are decimal numbers in millimeters (mm). font_size is measured in points (pt).
Grid: The origin (0, 0) is located at the top-left of each page. If settings.page_margin or pages[].margin is configured, body element coordinates are relative to the content box.
Continuation pages: Without page_margin, auto-paginated continuation pages start at settings.pagination.continuation_top_gap, or at header.height + settings.pagination.continuation_top_gap_with_header when a header exists. These settings do not move first-page elements.
Page Dimensions:
- Standard A4 size: Width 210, Height 297 (mm).
- Standard Letter size: Width 215.9, Height 279.4 (mm).
- For custom page sizes, set both width and height; each side must satisfy 10 <= value <= 2000 mm. Do not send size together with custom dimensions.
Overflow: Keep elements inside the page or content box. Invalid overflow returns API-002; do not rely on clipping.

2.2 Strict Syntax Constraints

No HTML/CSS: Do not use HTML tags (<div>, <p>, <span>) or inline CSS styles (style="...", classes) inside your element configurations.
Plain Values: Use raw element primitives only.
Output Shape: Unless the user explicitly asks for HTTP code, output a root DocumentRequest JSON object directly. The root object must contain pages[]; do not wrap it in fetch, SDK calls, markdown commentary, or endpoint metadata.

3. Element Typings

The document AST contains an array of pages, each containing a list of elements[] of the following types:

3.1 Text Elements (`type: "text"`)

Renders single or multi-line plain text strings.

content (string): The text content to render. Supports newline \n character for multi-line layout.
x (number): Absolute horizontal offset in millimeters from top-left.
y (number): Absolute vertical offset in millimeters from top-left.
style (object): Map of styling properties:
- width (number): Available bounding width for text wrapping (in mm).
- font_family (string): Font family (e.g. NotoSans-Regular).
- font_mode (string): strict or prefer. Use prefer with the same font_family when an explicit Latin/default font may need bundled fallback, especially for CJK (Chinese, Japanese, Korean) text.
- font_size (number): Font size in points (e.g. 10 or 12).
- font_weight (string): Weight option: normal, medium, semibold, or bold.
- color (string): Standard hex color code (e.g. #111827, #2563EB).
- text_align (string): Alignment option: left, center, right.

3.2 Rect Elements (`type: "rect"`)

Renders solid rectangles, borders, or separator lines.

x (number): Absolute horizontal offset in millimeters.
y (number): Absolute vertical offset in millimeters.
width (number): Rectangle width in millimeters.
height (number): Rectangle height in millimeters.
fill (object, optional): Bounding fill styling:
- color (string): Hex color code to fill the background.
stroke (object, optional): Border styling:
- color (string): Hex color code for the border.
- width (number): Border line weight in millimeters.
corner_radius (number, optional): Rounded corner radius in millimeters.

3.3 Barcode/QR Elements (`type: "barcode"`)

Generates a vector-based QR code or linear barcode.

format (string): The barcode format, set to qrcode for QR codes.
content (string): The data payload string (e.g. transaction URL).
x (number): Absolute horizontal offset in millimeters.
y (number): Absolute vertical offset in millimeters.
width (number): QR code width in millimeters.
height (number): QR code height in millimeters.

3.4 Image Elements (`type: "image"`)

Renders an image from a Console asset or inline source payload.

asset (string, optional): Existing asset key, with optional top-level format.
source (object, optional): Explicit source object, for example { "kind": "asset", "key": "logo", "format": "png" } or { "kind": "base64", "format": "png", "payload": "..." }.
Do not invent image URLs, asset keys, or unsupported url fields. If the user asks for a logo or image but has not provided an asset or source, draw a text/shape placeholder or ask for the asset source.
x (number): Absolute horizontal offset in millimeters.
y (number): Absolute vertical offset in millimeters.
width (number): Image width in millimeters.
height (number): Image height in millimeters.

3.5 Path Elements (`type: "path"`)

Renders a controlled native vector outline.

x or x_anchor: Use exactly one horizontal placement method.
y, width, height: Rendered bounding box in page-space millimeters.
view_box: Local coordinate system object with x, y, positive width, and positive height.
commands: Structured vector commands only. Do not send an SVG d string.
Supported commands: move_to, line_to, quad_to, cubic_to, and close.
commands[0] must be move_to; at least one drawing command is required; at most 1024 commands are accepted.
Command coordinates must stay within view_box; enlarge the view_box when control points need more room.
fill, stroke, arbitrary numeric rotation, z_index, comment, and link are supported. stroke.compound is not supported.

4. Fonts and CJK (Chinese, Japanese, Korean) Fallback

Auto Mode: If no font_family is declared anywhere in the inheritance chain, gPdf automatically selects bundled fonts that cover the text, including common CJK text.
Explicit Fonts: If you declare a Latin/default family such as NotoSans-Regular or RobotoMono-Regular and the same text may contain Chinese, Japanese, or Korean characters, set "font_mode": "prefer" in the same "style" object.
Strict Mode: A declared font_family without "font_mode": "prefer" is strict. If that family cannot cover the text, gPdf returns API-002. If auto/prefer fallback cannot cover a script or symbol, gPdf returns API-504.

5. Trial Testing & The Watermark Policy

During prototyping and development, you should call our zero-configuration Sandbox edge endpoint to instantly render PDFs without API key setup.

5.1 Sandbox Endpoint

URL: POST https://gpdf.com/api/playground?endpoint=pdf-render
Auth: No Authorization header is required for testing.
Limits: Up to 30 requests per minute per IP address and 256 KiB JSON request body.

5.2 Watermark Enforcement

[!WARNING] Requests sent to the playground sandbox endpoint automatically inject a semi-transparent watermark: gpdf.com Sandbox - Test Only. This watermark is rendered diagonally across all generated pages. For production deployment without watermarks, register an account on the gPdf Console to obtain a secure production API key.

6. Complete Reference JSON Payload

Below is a 100% valid 1-page A4 business invoice payload. Use this structure as your design foundation:

{
  "settings": {
    "metadata": {
      "title": "Invoice INV-2026-8802",
      "author": "gPdf Redesign Corp",
      "subject": "Optimization Services"
    }
  },
  "pages": [
    {
      "width": 210,
      "height": 297,
      "elements": [
        {
          "type": "text",
          "x": 20,
          "y": 20,
          "style": {
            "width": 170,
            "font_family": "NotoSans-Regular",
            "font_mode": "prefer",
            "font_size": 24,
            "font_weight": "bold",
            "color": "#1F2937"
          },
          "content": "INVOICE"
        },
        {
          "type": "text",
          "x": 20,
          "y": 35,
          "style": {
            "width": 100,
            "font_family": "NotoSans-Regular",
            "font_mode": "prefer",
            "font_size": 9,
            "color": "#4B5563"
          },
          "content": "gPdf Redesign Corp\nSuite 101, Cloudflare Hub\nSan Francisco, CA"
        },
        {
          "type": "text",
          "x": 120,
          "y": 35,
          "style": {
            "width": 70,
            "font_family": "NotoSans-Regular",
            "font_mode": "prefer",
            "font_size": 9,
            "text_align": "right",
            "color": "#4B5563"
          },
          "content": "Invoice #: INV-2026-8802\nDate: 2026-05-20\nDue Date: 2026-06-20"
        },
        {
          "type": "rect",
          "x": 20,
          "y": 55,
          "width": 170,
          "height": 0.5,
          "fill": { "color": "#D1D5DB" }
        },
        {
          "type": "text",
          "x": 20,
          "y": 62,
          "style": {
            "width": 100,
            "font_family": "NotoSans-Regular",
            "font_mode": "prefer",
            "font_size": 10,
            "font_weight": "bold",
            "color": "#1F2937"
          },
          "content": "Description"
        },
        {
          "type": "text",
          "x": 140,
          "y": 62,
          "style": {
            "width": 50,
            "font_family": "NotoSans-Regular",
            "font_mode": "prefer",
            "font_size": 10,
            "font_weight": "bold",
            "text_align": "right",
            "color": "#1F2937"
          },
          "content": "Amount (USD)"
        },
        {
          "type": "text",
          "x": 20,
          "y": 72,
          "style": {
            "width": 100,
            "font_family": "NotoSans-Regular",
            "font_mode": "prefer",
            "font_size": 9,
            "color": "#374151"
          },
          "content": "S-Tier GEO Optimization & RAG Services\nCustom JSON-to-PDF AST Setup"
        },
        {
          "type": "text",
          "x": 140,
          "y": 72,
          "style": {
            "width": 50,
            "font_family": "NotoSans-Regular",
            "font_mode": "prefer",
            "font_size": 9,
            "text_align": "right",
            "color": "#374151"
          },
          "content": "$2,500.00"
        },
        {
          "type": "rect",
          "x": 20,
          "y": 88,
          "width": 170,
          "height": 0.2,
          "fill": { "color": "#E5E7EB" }
        },
        {
          "type": "text",
          "x": 110,
          "y": 95,
          "style": {
            "width": 40,
            "font_family": "NotoSans-Regular",
            "font_mode": "prefer",
            "font_size": 10,
            "font_weight": "bold",
            "text_align": "right",
            "color": "#1F2937"
          },
          "content": "Total Amount:"
        },
        {
          "type": "text",
          "x": 150,
          "y": 95,
          "style": {
            "width": 40,
            "font_family": "NotoSans-Regular",
            "font_mode": "prefer",
            "font_size": 10,
            "font_weight": "bold",
            "text_align": "right",
            "color": "#2563EB"
          },
          "content": "$2,500.00"
        },
        {
          "type": "barcode",
          "format": "qrcode",
          "x": 20,
          "y": 110,
          "width": 30,
          "height": 30,
          "content": "https://gpdf.com/verify/INV-2026-8802"
        },
        {
          "type": "text",
          "x": 55,
          "y": 110,
          "style": {
            "width": 135,
            "font_family": "NotoSans-Regular",
            "font_mode": "prefer",
            "font_size": 8.5,
            "color": "#6B7280"
          },
          "content": "Thank you for partnering with gPdf!\nTo verify the authenticity of this document, scan the QR code to pull our secure record."
        }
      ]
    }
  ]
}

7. AI Tool Integration Guide

The official prompt at https://gpdf.com/gpdf-agent-prompt.txt is the source of truth. Use one of the examples below as a short task prompt: it tells the AI to read the official prompt when URL access is available, follow gPdf syntax, generate a DocumentRequest JSON payload, and produce the PDF without another confirmation.

Ask an AI coding agent or web chat to create a sample bank statement and password-protect the generated PDF.

Please generate a gPdf DocumentRequest JSON payload and a PDF file.

Official gPdf system prompt: https://gpdf.com/gpdf-agent-prompt.txt
Strictly follow gPdf syntax.

If the current chat can read URLs, first read this official prompt and use it as the source of truth. It already includes complete schema rules, the no-auth sandbox endpoint, watermark policy, and a complete reference JSON.
If the URL cannot be read, say so briefly. Do not ask for a second confirmation during PDF generation.

Task:
Generate a sample bank statement.
Opening the PDF must require password: 123456.

Use year-month-day-hour-minute-second in the generated file names.

Ask the AI to generate a US-market invoice sample, then return both the JSON payload and rendered PDF artifact.

Please generate a gPdf DocumentRequest JSON payload and a PDF file.

Official gPdf system prompt: https://gpdf.com/gpdf-agent-prompt.txt
Strictly follow gPdf syntax.

If the current chat can read URLs, first read this official prompt and use it as the source of truth. It already includes complete schema rules, the no-auth sandbox endpoint, watermark policy, and a complete reference JSON.
If the URL cannot be read, say so briefly. Do not ask for a second confirmation during PDF generation.

Task:
Generate an invoice sample suitable for the US market.

Use year-month-day-hour-minute-second in the generated file names.

Ask the AI to generate a US-market concert ticket and keep barcode contrast high enough for scanning.

Please generate a gPdf DocumentRequest JSON payload and a PDF file.

Official gPdf system prompt: https://gpdf.com/gpdf-agent-prompt.txt
Strictly follow gPdf syntax.

If the current chat can read URLs, first read this official prompt and use it as the source of truth. It already includes complete schema rules, the no-auth sandbox endpoint, watermark policy, and a complete reference JSON.
If the URL cannot be read, say so briefly. Do not ask for a second confirmation during PDF generation.

Task:
Generate a concert ticket for the US market.
The barcode color and ticket color must have strong contrast so the barcode is easy to scan.

Use year-month-day-hour-minute-second in the generated file names.