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

# Generate a PDF

> Render HTML as a binary PDF or a Base64 JSON response through your configured AvraAPI PDF Generator.

Render a small HTML document as a PDF. The default response is binary `application/pdf`; use `response_type: "base64"` only when your application needs the PDF inside a JSON envelope.

The Playground is deliberately limited to `response_type: "base64"` and returns the JSON envelope only. For a raw `application/pdf` response, use Postman or your backend integration.

<Info>
  **Live Testing Guide:** Before using **Try it**, create a Development project, then enter its **Client ID** and **Client Secret**. Configure the relevant provider for that project before sending the request.
</Info>

<Warning>
  HTML can contain invoice details, customer data, and other sensitive business information. Send `X-Privacy-Mode: 1` when that privacy guarantee is appropriate for the request. Never place Project Client Secrets in frontend code.
</Warning>

## API endpoint

```text title="POST" theme={null}
https://avraapi.com/api/v1/utilities/pdf/generate
```

## Request fields

| Field | Required | Rules |
| - | - | - |
| `html` | Yes | HTML source; 1–524,288 bytes after decoding when `is_base64` is `true`. |
| `is_base64` | No | Boolean. When `true`, send Base64-encoded HTML in `html`; AvraAPI decodes it before validation and rendering. Default `false`. |
| `page_size` | No | `A4` (default), `Letter`, or `Legal`. |
| `orientation` | No | `portrait` (default) or `landscape`. |
| `margins.top` | No | Top margin in millimetres, from 0 to 100; default `15`. |
| `margins.right` | No | Right margin in millimetres, from 0 to 100; default `15`. |
| `margins.bottom` | No | Bottom margin in millimetres, from 0 to 100; default `15`. |
| `margins.left` | No | Left margin in millimetres, from 0 to 100; default `15`. |
| `response_type` | No | `binary` (default) for `application/pdf`, or `base64` for a JSON response. |
| `privacy_mode` | No | Boolean request-level privacy setting. `X-Privacy-Mode: 1` is the shared universal override. |

AvraAPI sanitizes the HTML before rendering. Treat the result as a document generated from your own content: keep complex document storage, delivery, and authorization in your backend.

## Request example

This request receives a real PDF stream. The `--output` option saves that binary response as a file.

```bash curl theme={null} theme={null}
curl --request POST "https://avraapi.com/api/v1/utilities/pdf/generate" \
  --header "X-API-KEY: YOUR_PROJECT_CLIENT_ID" \
  --header "X-API-SECRET: YOUR_PROJECT_CLIENT_SECRET" \
  --header "X-ENV: development" \
  --header "X-Privacy-Mode: 1" \
  --header "Accept: application/pdf" \
  --header "Content-Type: application/json" \
  --data '{
    "html": "<html><body><h1>Order receipt</h1><p>ORDER-2026-001</p></body></html>",
    "page_size": "A4",
    "orientation": "portrait",
    "margins": {"top": 15, "right": 15, "bottom": 15, "left": 15},
    "response_type": "binary"
  }' \
  --output receipt.pdf
```

## Binary PDF response

`response_type: "binary"` is the default. A successful request returns the PDF bytes with `Content-Type: application/pdf`, `Content-Length`, `Cache-Control: no-store`, `Content-Disposition: inline; filename="apix-document.pdf"`, and `X-APIX-Request-ID` headers.

The PDF is the response body, not a JSON object. Use this mode from your backend, Postman, or another HTTP client that can handle binary media.

## Base64 JSON response

Set `response_type` to `base64` when a JSON response is required. `data.data` contains Base64 PDF bytes; it is not a temporary download link and AvraAPI does not store an artifact for later retrieval through this API.

```bash curl theme={null} theme={null}
curl --request POST "https://avraapi.com/api/v1/utilities/pdf/generate" \
  --header "X-API-KEY: YOUR_PROJECT_CLIENT_ID" \
  --header "X-API-SECRET: YOUR_PROJECT_CLIENT_SECRET" \
  --header "X-ENV: development" \
  --header "X-Privacy-Mode: 1" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data '{
    "html": "<html><body><h1>Order receipt</h1><p>ORDER-2026-001</p></body></html>",
    "response_type": "base64"
  }'
```

```json theme={null}
{
  "success": true,
  "request_id": "abd340d9-2491-4403-b076-51f395048c8d",
  "data": {
    "format": "base64",
    "media_type": "application/pdf",
    "data": "JVBERi0xLjcKMSAwIG9iago8PCAvVHlwZSAvQ2F0YWxvZw..."
  }
}
```

<Note>
  The value above is intentionally truncated. A successful response carries the complete Base64 document. Decode it only in a protected backend or trusted application context; do not place PDF content containing sensitive data into browser logs, analytics, or public client state.
</Note>

## Error codes

| HTTP | `error.code` | When it happens | What to do |
| - | - | - | - |
| `400` | <span style={{ whiteSpace: 'nowrap' }}><code>http\_error</code></span> | PDF rendering could not process the supplied HTML or a permitted external image. | Correct the document content and retry with a small controlled example first. |
| `401` | <span style={{ whiteSpace: 'nowrap' }}><code>unauthorized</code></span> | Credentials are missing, invalid, inactive, or do not match `X-ENV`. | Check your backend credential configuration. |
| `402` | <span style={{ whiteSpace: 'nowrap' }}><code>insufficient\_funds</code></span> | The selected PDF Generator integration requires credits that are unavailable. | Check the project balance and service configuration. |
| `422` | <span style={{ whiteSpace: 'nowrap' }}><code>validation\_failed</code></span> | `html` is missing, malformed Base64 was used with `is_base64`, or a field is outside its documented range or enum. | Correct the request using the field details in the response. |
| `422` | <span style={{ whiteSpace: 'nowrap' }}><code>provider\_selection\_failed</code></span> | No active HTML to PDF integration can be selected for the project environment. | Enable or configure the HTML to PDF Converter integration. |
| `429` | <span style={{ whiteSpace: 'nowrap' }}><code>rate\_limit\_exceeded</code></span> | The configured request limit was reached. | Respect `Retry-After` when present. |
| `500` | <span style={{ whiteSpace: 'nowrap' }}><code>internal\_error</code></span> | The renderer could not complete unexpectedly. | Retain the request ID and retry only when your workflow permits it. |
| `503` | <span style={{ whiteSpace: 'nowrap' }}><code>project\_paused</code></span> | The project is paused. | Reactivate the project before retrying. |

See the [REST API guide](/api-reference/rest-api) for shared credentials, privacy, and response-handling rules.

## Playground resources

The generated reference below lists this endpoint's API standard details: request fields, authorizations, and response schema. The complete integration guide, request and response examples, and endpoint-specific error handling are above.


## OpenAPI

````yaml api-reference/provider-api.openapi.yaml POST /utilities/pdf/generate
openapi: 3.0.3
info:
  title: AvraAPI Provider API
  version: 1.0.0
  description: >-
    The reviewed public contract for AvraAPI provider services. Operations are
    added to this document only after their route, validation, response,
    privacy, usage, and public-safety contracts have been verified.
servers:
  - url: https://avraapi.com/api/v1
    description: AvraAPI REST API v1
security:
  - ApiKeyHeader: []
    ApiSecretHeader: []
tags:
  - name: Currency
    description: Currency codes, exchange rates, and conversion.
  - name: SMS
    description: Messaging operations through configured AvraAPI providers.
  - name: Security
    description: IP and email security checks.
  - name: Location
    description: IP geolocation and intelligence.
  - name: Utilities
    description: QR code, barcode, and PDF generation.
paths:
  /utilities/pdf/generate:
    post:
      tags:
        - Utilities
      summary: Generate a PDF from HTML
      description: >-
        Renders sanitized HTML to a PDF. The normal API supports a binary
        application/pdf response, but this Documentation Playground operation is
        fixed to a Base64 JSON envelope. This live operation may process
        sensitive document content and may consume credits.
      operationId: generatePdf
      parameters:
        - $ref: '#/components/parameters/XEnvironmentHeader'
        - $ref: '#/components/parameters/AcceptJsonHeader'
        - $ref: '#/components/parameters/XPrivacyModeHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PdfPlaygroundRequest'
            examples:
              base64:
                summary: Browser-safe Base64 JSON response
                value:
                  html: >-
                    <html><body><h1>Order
                    receipt</h1><p>ORDER-2026-001</p></body></html>
                  response_type: base64
                  privacy_mode: true
      responses:
        '200':
          description: Base64 PDF JSON envelope for the Documentation Playground.
          headers:
            X-APIX-Request-ID:
              $ref: '#/components/headers/RequestIdHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PdfBase64Response'
              examples:
                base64:
                  summary: Base64 PDF response
                  value:
                    success: true
                    request_id: abd340d9-2491-4403-b076-51f395048c8d
                    data:
                      format: base64
                      media_type: application/pdf
                      data: JVBERi0xLjcKMSAwIG9iago8PCAvVHlwZSAvQ2F0YWxvZw...
        '400':
          $ref: '#/components/responses/UtilitiesBadRequest'
        '401':
          $ref: '#/components/responses/UtilitiesUnauthorized'
        '402':
          $ref: '#/components/responses/UtilitiesInsufficientFunds'
        '422':
          $ref: '#/components/responses/UtilitiesUnprocessable'
        '429':
          $ref: '#/components/responses/UtilitiesRateLimited'
        '500':
          $ref: '#/components/responses/UtilitiesInternalError'
        '503':
          $ref: '#/components/responses/UtilitiesUnavailable'
components:
  parameters:
    XEnvironmentHeader:
      name: X-ENV
      in: header
      required: false
      description: >-
        Selects the Development credential environment. The Documentation
        Playground exposes Development values only; normal backend integrations
        may use their documented Production credentials outside this tool.
      schema:
        type: string
        enum:
          - dev
          - development
        default: development
    AcceptJsonHeader:
      name: Accept
      in: header
      required: false
      description: Requests a JSON response where the selected operation supports JSON.
      schema:
        type: string
        example: application/json
    XPrivacyModeHeader:
      name: X-Privacy-Mode
      in: header
      required: false
      description: >-
        Optional privacy override. Turn this on to request that AvraAPI suppress
        request-payload storage in observability logs for this request.
      schema:
        type: boolean
        default: false
        example: true
  schemas:
    PdfPlaygroundRequest:
      description: >-
        Documentation Playground request projection. The released API also
        supports a binary PDF response for backend and Postman integrations.
      type: object
      required:
        - html
        - response_type
        - privacy_mode
      properties:
        html:
          type: string
          minLength: 1
          maxLength: 524288
          description: >-
            HTML source, limited to 512 KB after Base64 decoding when is_base64
            is true.
          x-default: >-
            <html><body><h1>Order
            receipt</h1><p>ORDER-2026-001</p></body></html>
        is_base64:
          type: boolean
          default: false
          x-default: false
          description: >-
            When true, html is Base64-encoded HTML and is decoded before
            validation and rendering.
        page_size:
          type: string
          enum:
            - A4
            - Letter
            - Legal
          default: A4
          x-default: A4
        orientation:
          type: string
          enum:
            - portrait
            - landscape
          default: portrait
          x-default: portrait
        margins:
          $ref: '#/components/schemas/PdfMargins'
        response_type:
          type: string
          enum:
            - base64
          default: base64
          x-default: base64
          description: Fixed to Base64 JSON for the Documentation Playground.
        privacy_mode:
          type: boolean
          enum:
            - true
          default: true
          x-default: true
          description: Fixed on for the Documentation Playground request body.
    PdfBase64Response:
      allOf:
        - $ref: '#/components/schemas/ApiSuccessEnvelope'
        - type: object
          properties:
            data:
              $ref: '#/components/schemas/PdfBase64Data'
    PdfMargins:
      type: object
      properties:
        top:
          type: number
          minimum: 0
          maximum: 100
          default: 15
        right:
          type: number
          minimum: 0
          maximum: 100
          default: 15
        bottom:
          type: number
          minimum: 0
          maximum: 100
          default: 15
        left:
          type: number
          minimum: 0
          maximum: 100
          default: 15
      description: Page margins in millimetres.
    ApiSuccessEnvelope:
      type: object
      required:
        - success
        - request_id
        - data
      properties:
        success:
          type: boolean
          enum:
            - true
        request_id:
          type: string
          format: uuid
          description: Include this value when contacting AvraAPI support.
        data:
          description: Operation-specific result data.
          nullable: true
    PdfBase64Data:
      type: object
      required:
        - format
        - media_type
        - data
      properties:
        format:
          type: string
          enum:
            - base64
        media_type:
          type: string
          enum:
            - application/pdf
        data:
          type: string
          format: byte
          description: Base64-encoded PDF bytes.
    ApiErrorEnvelope:
      type: object
      required:
        - success
        - request_id
        - error
      properties:
        success:
          type: boolean
          enum:
            - false
        request_id:
          type: string
          format: uuid
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              description: Stable machine-readable error code.
            message:
              type: string
              description: Human-readable error summary.
            details:
              type: object
              additionalProperties:
                type: array
                items:
                  type: string
              description: Field-level validation messages when available.
        meta:
          type: object
          description: Some infrastructure errors include additional diagnostic metadata.
          additionalProperties: true
  headers:
    RequestIdHeader:
      description: AvraAPI request identifier for support and troubleshooting.
      schema:
        type: string
        format: uuid
    RetryAfterHeader:
      description: Seconds to wait before retrying a rate-limited request.
      schema:
        type: integer
        minimum: 0
  responses:
    UtilitiesBadRequest:
      description: >-
        The generator could not process an otherwise valid request, such as an
        unsupported barcode payload or an unreachable QR logo URL.
      headers:
        X-APIX-Request-ID:
          $ref: '#/components/headers/RequestIdHeader'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorEnvelope'
          examples:
            http_error:
              value:
                success: false
                request_id: 01f00000-0000-4000-8000-000000000025
                error:
                  code: http_error
                  message: The generator could not process the supplied input.
                meta: {}
    UtilitiesUnauthorized:
      description: >-
        Missing, invalid, inactive, or environment-mismatched project
        credentials.
      headers:
        X-APIX-Request-ID:
          $ref: '#/components/headers/RequestIdHeader'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorEnvelope'
          examples:
            unauthorized:
              value:
                success: false
                request_id: 01f00000-0000-4000-8000-000000000026
                error:
                  code: unauthorized
                  message: Project credentials were not accepted.
                meta: {}
    UtilitiesInsufficientFunds:
      description: >-
        The selected Utility integration requires credits that are not
        available.
      headers:
        X-APIX-Request-ID:
          $ref: '#/components/headers/RequestIdHeader'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorEnvelope'
          examples:
            insufficient_funds:
              value:
                success: false
                request_id: 01f00000-0000-4000-8000-000000000027
                error:
                  code: insufficient_funds
                  message: The selected Utility integration has insufficient credits.
                meta: {}
    UtilitiesUnprocessable:
      description: >-
        The request body is invalid, or the matching Utility integration cannot
        be resolved for the project environment.
      headers:
        X-APIX-Request-ID:
          $ref: '#/components/headers/RequestIdHeader'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorEnvelope'
          examples:
            validation_failed:
              summary: Request validation error
              value:
                success: false
                request_id: 01f00000-0000-4000-8000-000000000022
                error:
                  code: validation_failed
                  message: Validation failed.
                  details:
                    data:
                      - The data field is required.
            unavailable_provider:
              summary: Utility provider is not available
              value:
                success: false
                request_id: 01f00000-0000-4000-8000-000000000023
                error:
                  code: provider_selection_failed
                  message: >-
                    No active generator integration is available for this
                    project environment.
    UtilitiesRateLimited:
      description: The configured request limit has been reached.
      headers:
        X-APIX-Request-ID:
          $ref: '#/components/headers/RequestIdHeader'
        Retry-After:
          $ref: '#/components/headers/RetryAfterHeader'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorEnvelope'
          examples:
            rate_limit_exceeded:
              value:
                success: false
                request_id: 01f00000-0000-4000-8000-000000000029
                error:
                  code: rate_limit_exceeded
                  message: The request limit has been reached.
                meta: {}
    UtilitiesInternalError:
      description: The Utility operation could not complete unexpectedly.
      headers:
        X-APIX-Request-ID:
          $ref: '#/components/headers/RequestIdHeader'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorEnvelope'
          examples:
            internal_error:
              value:
                success: false
                request_id: 01f00000-0000-4000-8000-000000000028
                error:
                  code: internal_error
                  message: The Utility operation could not complete.
                meta: {}
    UtilitiesUnavailable:
      description: The project is paused.
      headers:
        X-APIX-Request-ID:
          $ref: '#/components/headers/RequestIdHeader'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorEnvelope'
          examples:
            project_paused:
              value:
                success: false
                request_id: 01f00000-0000-4000-8000-000000000024
                error:
                  code: project_paused
                  message: This project is currently paused.
  securitySchemes:
    ApiKeyHeader:
      type: apiKey
      in: header
      name: X-API-KEY
      description: >-
        Your Development project's Client ID. Enter your own value in the
        Documentation Playground.
    ApiSecretHeader:
      type: apiKey
      in: header
      name: X-API-SECRET
      description: >-
        Your Development project's Client Secret. Mintlify does not proxy these
        requests; the browser sends them directly to AvraAPI. Never enter a
        Production secret in the Documentation Playground.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.