{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/superdocs-app/json-schema/superdocs-app-export-request-schema.json",
  "title": "ExportRequest",
  "description": "Unified request body for POST /v1/documents/export.\n\nBackward-compat notes:\n- Top-level ``filename`` is retained for legacy clients that sent only\n  ``{ html }`` and relied on the filename being auto-extracted from the\n  first <h1>. New clients should use ``options.filename`` —\n  options.filename wins when both are set.\n- ``format`` defaults to \"docx\". Legacy callers passing format=\"doc\"\n  explicitly keep working during a short back-compat window.",
  "x-generated": "2026-10-31",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/superdocs-app-openapi.json#/components/schemas/ExportRequest",
  "properties": {
    "session_id": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 256
        },
        {
          "type": "null"
        }
      ],
      "title": "Session Id",
      "description": "Session ID to export from (the document is taken from the session). Required if html is omitted."
    },
    "html": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 200000000
        },
        {
          "type": "null"
        }
      ],
      "title": "Html",
      "description": "HTML content to export inline. Used instead of the session document if provided."
    },
    "format": {
      "type": "string",
      "enum": [
        "docx",
        "pdf",
        "html",
        "markdown",
        "txt",
        "doc"
      ],
      "title": "Format",
      "description": "Export format. One of docx (default), pdf, html, markdown, txt.",
      "default": "docx"
    },
    "options": {
      "$ref": "#/$defs/ExportOptions",
      "description": "Customization (paper, margins, filename, watermark, etc.)."
    },
    "filename": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 255
        },
        {
          "type": "null"
        }
      ],
      "title": "Filename",
      "description": "DEPRECATED. Use options.filename. Top-level kept for legacy callers."
    },
    "source_filename": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 255
        },
        {
          "type": "null"
        }
      ],
      "title": "Source Filename",
      "description": "The document's original/source filename (e.g. the name it was uploaded under). Used as the default export filename when no explicit options.filename is set, taking precedence over the first heading."
    },
    "upload_id": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 64
        },
        {
          "type": "null"
        }
      ],
      "title": "Upload Id",
      "description": "ID returned by /v1/uploads (large-document upload flow, for payloads above ~25 MB). When set, the route fetches the HTML body from the uploaded payload instead of using the html field."
    }
  },
  "type": "object",
  "$defs": {
    "ExportOptions": {
      "properties": {
        "paper_size": {
          "type": "string",
          "enum": [
            "A4",
            "Letter",
            "A3",
            "Legal"
          ],
          "title": "Paper Size",
          "description": "Page size for DOCX/PDF/legacy .doc. HTML/MD/TXT exports ignore.",
          "default": "Letter"
        },
        "orientation": {
          "type": "string",
          "enum": [
            "portrait",
            "landscape"
          ],
          "title": "Orientation",
          "description": "Page orientation for DOCX/PDF/legacy .doc.",
          "default": "portrait"
        },
        "margins": {
          "type": "string",
          "enum": [
            "narrow",
            "normal",
            "wide",
            "custom"
          ],
          "title": "Margins",
          "description": "Page margins preset. 'narrow' = 0.5in, 'normal' = 1.0in, 'wide' = 1.5in. 'custom' uses custom_margins_inches.",
          "default": "normal"
        },
        "custom_margins_inches": {
          "anyOf": [
            {
              "additionalProperties": {
                "type": "number"
              },
              "propertyNames": {
                "enum": [
                  "top",
                  "right",
                  "bottom",
                  "left"
                ]
              },
              "type": "object"
            },
            {
              "type": "null"
            }
          ],
          "title": "Custom Margins Inches",
          "description": "Required when margins='custom'. Each value 0.25-3.0 inches."
        },
        "filename": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 255
            },
            {
              "type": "null"
            }
          ],
          "title": "Filename",
          "description": "Custom filename (no extension). Auto-detected from first <h1> if unset."
        },
        "embed_images": {
          "type": "boolean",
          "title": "Embed Images",
          "description": "HTML export only. When True, images are base64-embedded for offline portability (raises size cap to 150 MB). When False, images are referenced by URL (smaller file, online-only).",
          "default": false
        },
        "watermark_text": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 64
            },
            {
              "type": "null"
            }
          ],
          "title": "Watermark Text",
          "description": "PDF only. Optional text watermark overlaid on every page."
        },
        "watermark_opacity": {
          "type": "number",
          "maximum": 1.0,
          "minimum": 0.05,
          "title": "Watermark Opacity",
          "description": "PDF watermark opacity, 0.05-1.0.",
          "default": 0.3
        },
        "fidelity": {
          "anyOf": [
            {
              "type": "string",
              "enum": [
                "strict",
                "compat"
              ]
            },
            {
              "type": "null"
            }
          ],
          "title": "Fidelity",
          "description": "Export fidelity. 'strict' (server default) renders only the formatting the document carries — no imposed table widths/borders (except visual defaults on fully unstyled tables), overflow-only clamping, highlight colors honored. 'compat' reproduces the legacy normalized output."
        }
      },
      "type": "object",
      "title": "ExportOptions",
      "description": "User-facing export customisation (page size, orientation, margins,\nfilename, watermark). Sent on every export request."
    }
  }
}