{
  "openapi": "3.0.0",
  "info": {
    "title": "Zero Retention PDF API",
    "description": "A privacy-first HTML-to-PDF and screenshot rendering API for sensitive workflows. HTML payloads are rendered in-memory and returned directly to the client or an optional webhook.",
    "version": "1.0.0",
    "contact": {
      "name": "API Support",
      "email": "support@xeropdf.com",
      "url": "https://xeropdf.com"
    }
  },
  "servers": [
    {
      "url": "https://xeropdf.com",
      "description": "Production Server"
    }
  ],
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key",
        "description": "Your Zero Retention PDF API Key"
      }
    }
  },
  "paths": {
    "/v1/pdf": {
      "post": {
        "summary": "Convert HTML to PDF",
        "description": "Converts an HTML payload into a PDF document. Operates entirely in RAM for zero-retention compliance. Supports synchronous response or asynchronous delivery via webhooks.",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "html"
                ],
                "properties": {
                  "html": {
                    "type": "string",
                    "description": "The raw HTML string to convert into a PDF."
                  },
                  "format": {
                    "type": "string",
                    "description": "Optional page format such as A4, Letter, or Legal."
                  },
                  "width": {
                    "type": "string",
                    "description": "Optional custom page width, e.g. 8.27in or 1200px. Overrides format when set."
                  },
                  "height": {
                    "type": "string",
                    "description": "Optional custom page height, e.g. 11.69in or 1800px. Overrides format when set."
                  },
                  "landscape": {
                    "type": "boolean",
                    "description": "Render the PDF in landscape orientation."
                  },
                  "scale": {
                    "type": "number",
                    "description": "Scale factor between 0.1 and 2."
                  },
                  "pageRanges": {
                    "type": "string",
                    "description": "Optional page ranges, e.g. 1-3, 5, 8-10."
                  },
                  "printBackground": {
                    "type": "boolean",
                    "description": "Whether to include CSS backgrounds in the output."
                  },
                  "preferCSSPageSize": {
                    "type": "boolean",
                    "description": "Prefer @page CSS size rules over the format option."
                  },
                  "headerTemplate": {
                    "type": "string",
                    "description": "Optional HTML template for the PDF header. Must be valid HTML with inline CSS."
                  },
                  "footerTemplate": {
                    "type": "string",
                    "description": "Optional HTML template for the PDF footer. Must be valid HTML with inline CSS."
                  },
                  "margins": {
                    "type": "object",
                    "description": "Optional PDF margins.",
                    "properties": {
                      "top": { "type": "string" },
                      "right": { "type": "string" },
                      "bottom": { "type": "string" },
                      "left": { "type": "string" }
                    }
                  },
                  "password": {
                    "type": "string",
                    "description": "Optional password to encrypt the generated PDF (AES-256)."
                  },
                  "waitUntil": {
                    "type": "string",
                    "description": "Lifecycle event to wait for before rendering. Supported values: load, domcontentloaded, networkidle, commit."
                  },
                  "waitForSelector": {
                    "type": "string",
                    "description": "Optional CSS selector to wait for before rendering."
                  },
                  "delayMs": {
                    "type": "integer",
                    "description": "Optional extra render delay in milliseconds. Maximum 10000."
                  },
                  "viewport": {
                    "type": "object",
                    "description": "Optional browser viewport size.",
                    "properties": {
                      "width": { "type": "integer" },
                      "height": { "type": "integer" }
                    }
                  },
                  "webhookUrl": {
                    "type": "string",
                    "format": "uri",
                    "description": "Optional URL for asynchronous delivery. If provided, the API responds with 202 Accepted and POSTs the generated PDF to this URL."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful synchronous PDF generation.",
            "content": {
              "application/pdf": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "202": {
            "description": "Accepted for asynchronous processing via webhook.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string",
                      "example": "PDF generation queued successfully."
                    },
                    "status": {
                      "type": "string",
                      "example": "processing"
                    },
                    "webhookUrl": {
                      "type": "string",
                      "format": "uri"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad Request (e.g., missing HTML)."
          },
          "401": {
            "description": "Unauthorized (missing API key)."
          },
          "402": {
            "description": "Payment Required (zero credits remaining)."
          },
          "403": {
            "description": "Forbidden (invalid API key)."
          },
          "500": {
            "description": "Server error while generating the PDF."
          }
        }
      }
    },
    "/v1/screenshot": {
      "post": {
        "summary": "Render HTML to an image",
        "description": "Renders an HTML payload to a PNG, JPEG, or WebP screenshot.",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "html"
                ],
                "properties": {
                  "html": {
                    "type": "string",
                    "description": "The raw HTML string to render into an image."
                  },
                  "type": {
                    "type": "string",
                    "description": "Image type: png, jpeg, or webp."
                  },
                  "fullPage": {
                    "type": "boolean",
                    "description": "Capture the full scroll height of the page."
                  },
                  "quality": {
                    "type": "integer",
                    "description": "Image quality from 1 to 100 for JPEG and WebP."
                  },
                  "omitBackground": {
                    "type": "boolean",
                    "description": "Render with a transparent background for PNG output."
                  },
                  "waitUntil": {
                    "type": "string",
                    "description": "Lifecycle event to wait for before rendering. Supported values: load, domcontentloaded, networkidle, commit."
                  },
                  "waitForSelector": {
                    "type": "string",
                    "description": "Optional CSS selector to wait for before capturing."
                  },
                  "delayMs": {
                    "type": "integer",
                    "description": "Optional extra render delay in milliseconds. Maximum 10000."
                  },
                  "viewport": {
                    "type": "object",
                    "properties": {
                      "width": { "type": "integer" },
                      "height": { "type": "integer" }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful screenshot generation.",
            "content": {
              "image/png": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "image/jpeg": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "image/webp": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request (e.g., missing HTML)."
          },
          "401": {
            "description": "Unauthorized (missing API key)."
          },
          "402": {
            "description": "Payment Required (zero credits remaining)."
          },
          "403": {
            "description": "Forbidden (invalid API key)."
          },
          "500": {
            "description": "Server error while generating the screenshot."
          }
        }
      }
    }
  }
}