API Reference

gPdf API generates high-performance PDF/A documents from JSON requests.

---

📍 Endpoint

The only canonical route:

Endpoint	Authentication	Description
POST /api/v1/render	Authorization: Bearer <token>	The only public request entry point. prod/test are distinguished solely by environment and token.

---

📋 Core Documentation

Document	Description
API Console	Run requests and inspect PDF / JSON responses in the browser
📋 JSON Schema (Complete)	Full field reference
Schema Reference	Quick reference
PDF Profiles	Compliance level configuration
Metadata & Validation	Document properties and validation rules

---

🔧 Request Format

Headers

Content-Type: application/json
Authorization: Bearer <token>
X-Request-Id: <optional-client-request-id>

Body

A single DocumentRequest JSON object:

{
  "settings": {
    "defaults": {
      "text": { "font_family": "NotoSans-Regular", "font_size": 12 },
      "stroke": { "color": "#000000", "width": 0.4 },
      "shape": { "corner_radius": 0 }
    }
  },
  "pages": [
    {
      "size": "a4",
      "elements": [
        { "type": "text", "x": 10, "y": 20, "content": "Hello gPdf" }
      ]
    }
  ]
}

text accepts three public input forms:

• plain text shorthand: "content": "Hello gPdf"
• rich spans shorthand: "content": { "spans": [...] }
• block text: frame/defaults/content.blocks

All three forms are handled consistently during validation and rendering.
Block text is the most complete and recommended form for complex typography, variables, and pagination control.

For POST /api/v1/render, the currently guaranteed built-in variables are only:

• system.page
• system.total_pages

If you need business-data substitution, use POST /api/v1/template-render.
computed variables are not currently exposed as a public capability, and _if is not evaluated by the direct render route.

Operational response behavior:

• success responses return application/pdf
• error responses return application/json
• X-Request-Id is echoed in both success and error responses
• there is currently no public rate-limit response header contract
• there is currently no public idempotency-key contract
• settings.output.mode = "binary" | "file" does not change the payload format; both return PDF bytes and only differ in Content-Disposition

Error responses use the following JSON shape:

{
  "error": true,
  "code": "API-002",
  "message": "x must be >= 0",
  "req_id": "7f7d2f5a-4cb0-4c4e-b6ef-8f6d3e0b1fd8"
}

Typography note:

• font_family omitted or empty: automatic fallback mode
• font_family present and font_mode omitted: default strict
• font_mode currently supports strict and prefer

---

🚀 10-second start

Use this exact request first. It is the fastest way to verify:

• token works
• route works
• PDF bytes are returned correctly

curl -X POST "https://gpdf.example.com/api/v1/render" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "X-Request-Id: quickstart-001" \
  --data-binary '{
    "pages": [
      {
        "size": "label_100_150",
        "elements": [
          {
            "type": "text",
            "x": 10,
            "y": 18,
            "content": "Hello gPdf"
          }
        ]
      }
    ]
  }' \
  --output quickstart.pdf

If you need a better production starting point, use Quick Examples. If you want to run examples directly in the browser, open API Console.

---

✨ Core Capabilities

• General-purpose elements: text / barcode / line / rect / circle / ellipse / polygon / image / table / stack
• Horizontal anchor positioning: x_anchor for automatic element alignment
• Page size presets: a4 / a6 / letter / legal / label_100_100 / label_100_150 / label_4_6_in
• Image formats: jpg / jpeg / png / webp / svg

---

⚠️ Error Codes

Common public error codes:

Code	Trigger
API-001	Invalid JSON payload
API-002	Validation failure
API-101	Missing or malformed Authorization header
API-102	Authentication failed
API-103	Authentication failed (token blacklisted)
API-501	PDF rendering failure
API-502	PDF/A compliance check failed
API-900	Internal system error
API-999	Unknown internal error

Notes:

• API-102, API-103, and system errors (API-900 / API-901 / API-902 / API-999) use redacted public messages.
• Render errors (API-501 ~ API-507) preserve actionable details for client diagnosis.

Common ValidationError triggers:

• Invalid link (unsupported URL scheme, page index out of bounds, invalid padding/border)
• Invalid table (unknown column key, table.width cannot allocate positive width for undeclared columns, invalid span)
• Invalid profile
• font_mode used without a same-level font_family
• Explicit font in strict mode cannot cover the submitted text
• x and x_anchor provided simultaneously

Boundary notes:

• API-008 defaults to 16 MiB; different service deployments may configure a different limit
• API-004 is not a single hard-coded number in all environments: the effective limit is the smaller of the global max-pages setting and any token policy max_pages_per_request
• API-007 is policy-driven and applies only when the active render policy defines max_image_bytes