> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hookpdf.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Render PDF Preview

Enqueue a preview render job. A preview PDF applies watermarks and has a short Time-To-Live (TTL). It does not count towards your monthly generation quota.

## Response Fields

<ResponseField name="job_id" type="string (uuid)">
  Unique identifier for the preview job. Use this to poll the job status via `GET /reports/{job_id}`.
</ResponseField>

<ResponseField name="status" type="string">
  Current status of the job. Will be `queued` immediately after creation.
</ResponseField>

<ResponseField name="is_preview" type="boolean">
  `true` for preview renders.
</ResponseField>

<ResponseField name="created_at" type="string (datetime)">
  Timestamp when the job was created.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.hookpdf.com/render/preview" \
    -H "Authorization: Bearer <YOUR_API_KEY>" \
    -H "Content-Type: application/json" \
    -d '{
      "template_id": "123e4567-e89b-12d3-a456-426614174000",
      "payload": {
        "name": "Jane Example",
        "date": "2024-05-10"
      },
      "options": {
        "page_size": "A4",
        "orientation": "portrait"
      }
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.hookpdf.com/render/preview', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer <YOUR_API_KEY>',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      template_id: "123e4567-e89b-12d3-a456-426614174000",
      payload: {
        name: "Jane Example",
        date: "2024-05-10"
      },
      options: {
        page_size: "A4",
        orientation: "portrait"
      }
    })
  });

  const result = await response.json();
  console.log("Preview Job ID:", result.job_id);
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.hookpdf.com/render/preview"
  headers = {
      "Authorization": "Bearer <YOUR_API_KEY>",
      "Content-Type": "application/json"
  }
  data = {
      "template_id": "123e4567-e89b-12d3-a456-426614174000",
      "payload": {
          "name": "Jane Example",
          "date": "2024-05-10"
      },
      "options": {
          "page_size": "A4",
          "orientation": "portrait"
      }
  }

  response = requests.post(url, headers=headers, json=data)
  print("Preview Job ID:", response.json().get("job_id"))
  ```

  ```php PHP theme={null}
  $url = "https://api.hookpdf.com/render/preview";
  $data = [
      "template_id" => "123e4567-e89b-12d3-a456-426614174000",
      "payload" => [
          "name" => "Jane Example",
          "date" => "2024-05-10"
      ],
      "options" => [
          "page_size" => "A4",
          "orientation" => "portrait"
      ]
  ];

  $ch = curl_init($url);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_POST, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
      "Authorization: Bearer <YOUR_API_KEY>",
      "Content-Type: application/json"
  ]);
  curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));

  $response = curl_exec($ch);
  curl_close($ch);

  $result = json_decode($response, true);
  echo "Preview Job ID: " . $result["job_id"];
  ```

  ```csharp C# theme={null}
  using var client = new HttpClient();
  client.DefaultRequestHeaders.Add("Authorization", "Bearer <YOUR_API_KEY>");

  var data = new
  {
      template_id = "123e4567-e89b-12d3-a456-426614174000",
      payload = new { name = "Jane Example", date = "2024-05-10" },
      options = new { page_size = "A4", orientation = "portrait" }
  };

  var json = System.Text.Json.JsonSerializer.Serialize(data);
  var content = new StringContent(json, System.Text.Encoding.UTF8, "application/json");

  var response = await client.PostAsync("https://api.hookpdf.com/render/preview", content);
  var result = await response.Content.ReadAsStringAsync();
  Console.WriteLine(result);
  ```

  ```powershell PowerShell theme={null}
  $headers = @{
      "Authorization" = "Bearer <YOUR_API_KEY>"
      "Content-Type"  = "application/json"
  }

  $body = @{
      template_id = "123e4567-e89b-12d3-a456-426614174000"
      payload = @{
          name = "Jane Example"
          date = "2024-05-10"
      }
      options = @{
          page_size = "A4"
          orientation = "portrait"
      }
  } | ConvertTo-Json -Depth 3

  $response = Invoke-RestMethod -Uri "https://api.hookpdf.com/render/preview" `
      -Method POST -Headers $headers -Body $body

  Write-Output "Preview Job ID: $($response.job_id)"
  ```
</RequestExample>

<ResponseExample>
  ```json 202 — Preview Job Queued theme={null}
  {
    "job_id": "a1b2c3d4-5678-9012-abcd-ef1234567890",
    "status": "queued",
    "is_preview": true,
    "created_at": "2026-02-28T15:09:17.006604+00:00"
  }
  ```
</ResponseExample>


## OpenAPI

````yaml POST /render/preview
openapi: 3.0.3
info:
  title: HOOKPDF API
  version: 1.0.0
  description: HOOKPDF render and control-plane API (MVP)
servers:
  - url: https://api.hookpdf.com
security: []
paths:
  /render/preview:
    post:
      tags:
        - render
      summary: Enqueue preview render job (watermarked, TTL)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RenderRequest'
      responses:
        '202':
          description: Preview job queued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobResponse'
              example:
                job_id: a1b2c3d4-5678-9012-abcd-ef1234567890
                status: queued
                is_preview: true
                created_at: '2026-02-28T15:09:17.006604+00:00'
        '429':
          description: Rate limit exceeded
      security:
        - apiKey: []
components:
  schemas:
    RenderRequest:
      type: object
      required:
        - template_id
        - payload
      properties:
        template_id:
          type: string
          format: uuid
          description: >-
            The unique ID of the template to render. You can find this in your
            Dashboard.
        payload:
          type: object
          description: The JSON data to inject into the template's Handlebars placeholders.
        options:
          type: object
          description: Optional rendering configuration.
          properties:
            page_size:
              type: string
              default: A4
              description: PDF page size (e.g. A4, Letter).
            orientation:
              type: string
              enum:
                - portrait
                - landscape
              default: portrait
              description: Page orientation.
            locale:
              type: string
              default: en-US
              description: Locale used for number and date formatting inside the template.
    JobResponse:
      type: object
      description: Returned when a render job is successfully queued.
      properties:
        job_id:
          type: string
          format: uuid
          description: >-
            Unique identifier for the render job. Use this to poll the job
            status via `/reports/{job_id}`.
        status:
          type: string
          enum:
            - queued
            - processing
            - completed
            - failed
          description: >-
            Current status of the job. Will be `queued` immediately after
            creation.
        is_preview:
          type: boolean
          description: >-
            `true` if this is a preview render (watermarked, short TTL), `false`
            for production.
        created_at:
          type: string
          format: date-time
          description: Timestamp when the job was created.
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: Enter your API key

````