Quickstart

Render your first PDF with gpdf-api in three minutes — sign up, copy a key, send a request.

Quickstart

You'll have a real PDF on disk in three minutes. The only prerequisite is curl, Node, Go, or Python — pick one.

1. Sign up and get a key

  1. Visit app.gpdf.dev/signup. Sign up with email + 6-digit code, or with Continue with Google.

  2. Right after signup, the dashboard shows your default API key once. Copy it now into a password manager or a .env file:

    export GPDF_API_KEY=gpdf_a1b2c3d4e5f6g7h8...
  3. Need another key later? Open /app/keys and click Create key. Free has up to 3 keys; Pro has up to 20.

💡 Tip — Lost your key?

We don't store the raw key anywhere — only an SHA-256 hash. There's no "show key" button. If you lose it, revoke the old one and create a new one. That's by design.

2. Render your first PDF

Pick whichever client you like. Each example renders the same single-page A4 PDF that says "Hello, PDF!".

::code-group

curl https://api.gpdf.dev/v1/pdf \
  -H "Authorization: Bearer $GPDF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template": {
      "page": { "size": "A4" },
      "body": [
        { "text": "Hello, PDF!" }
      ]
    }
  }' \
  --output hello.pdf
import fs from 'node:fs'

const res = await fetch('https://api.gpdf.dev/v1/pdf', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.GPDF_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    template: {
      page: { size: 'A4' },
      body: [{ text: 'Hello, PDF!' }]
    }
  })
})

if (!res.ok) {
  throw new Error(`${res.status} ${res.statusText}: ${await res.text()}`)
}
fs.writeFileSync('hello.pdf', Buffer.from(await res.arrayBuffer()))
package main

import (
    "io"
    "net/http"
    "os"
    "strings"
)

func main() {
    body := strings.NewReader(`{
        "template": {
            "page": {"size": "A4"},
            "body": [{"text": "Hello, PDF!"}]
        }
    }`)
    req, _ := http.NewRequest("POST", "https://api.gpdf.dev/v1/pdf", body)
    req.Header.Set("Authorization", "Bearer "+os.Getenv("GPDF_API_KEY"))
    req.Header.Set("Content-Type", "application/json")

    resp, err := http.DefaultClient.Do(req)
    if err != nil { panic(err) }
    defer resp.Body.Close()

    out, _ := os.Create("hello.pdf")
    defer out.Close()
    io.Copy(out, resp.Body)
}
import os
import requests

res = requests.post(
    "https://api.gpdf.dev/v1/pdf",
    headers={"Authorization": f"Bearer {os.environ['GPDF_API_KEY']}"},
    json={
        "template": {
            "page": {"size": "A4"},
            "body": [{"text": "Hello, PDF!"}],
        }
    },
)
res.raise_for_status()
open("hello.pdf", "wb").write(res.content)
require 'net/http'
require 'json'
require 'uri'

uri = URI('https://api.gpdf.dev/v1/pdf')
req = Net::HTTP::Post.new(uri)
req['Authorization'] = "Bearer #{ENV['GPDF_API_KEY']}"
req['Content-Type'] = 'application/json'
req.body = {
  template: {
    page: { size: 'A4' },
    body: [{ text: 'Hello, PDF!' }]
  }
}.to_json

res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
raise "#{res.code} #{res.message}: #{res.body}" unless res.is_a?(Net::HTTPSuccess)
File.binwrite('hello.pdf', res.body)
<?php
$payload = json_encode([
    'template' => [
        'page' => ['size' => 'A4'],
        'body' => [['text' => 'Hello, PDF!']],
    ],
]);

$ch = curl_init('https://api.gpdf.dev/v1/pdf');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => $payload,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . getenv('GPDF_API_KEY'),
        'Content-Type: application/json',
    ],
]);

$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($status !== 200) {
    throw new RuntimeException("HTTP $status: $body");
}
file_put_contents('hello.pdf', $body);
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.file.Path;

public class Quickstart {
    public static void main(String[] args) throws Exception {
        String body = """
            {
              "template": {
                "page": {"size": "A4"},
                "body": [{"text": "Hello, PDF!"}]
              }
            }
            """;

        HttpRequest req = HttpRequest.newBuilder()
            .uri(URI.create("https://api.gpdf.dev/v1/pdf"))
            .header("Authorization", "Bearer " + System.getenv("GPDF_API_KEY"))
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(body))
            .build();

        HttpResponse<Path> res = HttpClient.newHttpClient()
            .send(req, HttpResponse.BodyHandlers.ofFile(Path.of("hello.pdf")));

        if (res.statusCode() != 200) {
            throw new RuntimeException("HTTP " + res.statusCode());
        }
    }
}
using System;
using System.IO;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;

class Quickstart {
    static async Task Main() {
        var apiKey = Environment.GetEnvironmentVariable("GPDF_API_KEY");
        var payload = """
            {
              "template": {
                "page": {"size": "A4"},
                "body": [{"text": "Hello, PDF!"}]
              }
            }
            """;

        using var http = new HttpClient();
        http.DefaultRequestHeaders.Authorization =
            new AuthenticationHeaderValue("Bearer", apiKey);

        using var content = new StringContent(payload, Encoding.UTF8, "application/json");
        using var res = await http.PostAsync("https://api.gpdf.dev/v1/pdf", content);
        res.EnsureSuccessStatusCode();

        await using var fs = File.Create("hello.pdf");
        await res.Content.CopyToAsync(fs);
    }
}

::

Open hello.pdf in any viewer — that's a real PDF/A-compatible document.

3. Read the response headers

Every successful response includes a few metadata headers worth keeping an eye on:

Header Example What it means
Content-Type application/pdf Always application/pdf on success.
Content-Disposition attachment; filename="hello.pdf" Reflects the options.filename you sent (or the slug, if any).
X-GPDF-Pages 1 Number of pages in the rendered PDF.
X-GPDF-Latency-Us 13872 Render time on the server, in microseconds.
X-GPDF-Quota-Remaining 499 Successful renders left in this billing period.
X-GPDF-RateLimit-Remaining 9 Tokens left in your per-key bucket.
X-Request-Id req_01HZ… Trace ID — quote this when filing a support ticket.

The full list is in Response headers →.

4. Pass real data into a template

Hard-coding strings is fine for a demo, but in production you usually want one fixed template + per-request data. gpdf-api accepts a Go-template data block alongside the template:

curl https://api.gpdf.dev/v1/pdf \
  -H "Authorization: Bearer $GPDF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "invoice_q1",
    "template": {
      "page": { "size": "A4", "margin": "20mm" },
      "body": [
        { "text": "Invoice #{{.id}}", "style": { "fontSize": 18, "weight": "bold" } },
        { "spacer": "8mm" },
        { "text": "Billed to: {{.customer.name}}" },
        { "text": "Total: {{.total | printf \"%.2f\"}} USD" }
      ]
    },
    "data": {
      "id": "INV-001",
      "customer": { "name": "Acme, Inc." },
      "total": 2720.00
    }
  }' \
  --output invoice.pdf

The same template can be cached on your side and only data (and slug) needs to change.

The slug field is optional but useful — it shows up in the dashboard logs so you can answer "which template was that?" at a glance.

5. Handle errors

Anything other than 200 returns a JSON body shaped like this:

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests for this key. Retry after 1.0s.",
    "request_id": "req_01HZTV...",
    "doc_url": "https://docs.gpdf.dev/errors#rate_limited"
  }
}

The most common ones to handle:

HTTP Code Fix
401 unauthorized Check the Authorization header — typo or revoked key.
402 quota_exceeded Buy an addon pack or upgrade.
413 payload_too_large Trim the input or upgrade for the larger ceiling.
429 rate_limited Honour the Retry-After response header.
503 service_unavailable Retry with exponential backoff (1, 2, 4, 8 s).

Full catalogue and recommended retry behaviour: Errors →.

6. Check your usage

The dashboard at /app/usage shows your current period as a chart, with daily / hourly breakdowns and remaining quota.

What's next

You now have the basics. The longer reads worth the time:

Something unclear or missing on this page?