Convert to PDF

The file parameter allows you to select one local source file to upload to pdfRest's processing server for conversion. The submitted file becomes the primary input for the Convert to PDF request.

The following file formats are accepted:

• Office documents: .doc, .docx, .xls, .xlsx, .ppt, .pptx
• Image files: .jpg, .jpeg, .tif, .tiff, .bmp, .png
• Email: .eml
• Print formats: .ps, .eps
• Web content: .html
• Structured text: .md, .markdown, .txt, .json, .xml, .csv

Provide either file, id, or url as the primary source for a request. For Markdown conversion, you can also include supporting local image uploads through image_files.

The id parameter allows you to submit a resource ID for a file already stored on pdfRest's processing server instead of uploading that file again. Resource IDs are returned by the Upload Files API Tool and by other pdfRest API Tools when they create output files.

This allows applications to chain document-processing calls without downloading intermediate files. For example, you can upload a Markdown, JSON, XML, or CSV file, retain its resource ID, then submit that ID to Convert to PDF when the document is ready to process.

Provide either file, id, or url as the primary source for a request. For Markdown conversion, you can also provide existing image resource IDs through the separate image_ids parameter.

The url parameter allows you to submit the public URL of a web page for conversion to PDF. pdfRest retrieves the page and converts its HTML content without requiring you to upload a local file or first create a resource ID.

Use url for HTML web-page conversion only. Markdown, plain text, JSON, XML, CSV, Office documents, images, email, PostScript, and EPS files must be submitted through file or id.

Provide either file, id, or url as the primary source for a request.

The output parameter lets you set the filename of the resulting PDF without specifying a file extension. For example, setting output to quarterly-report produces an output file named quarterly-report.pdf.

Use this parameter when your workflow benefits from a predictable, meaningful output filename.

Compatible with PostScript, Microsoft Office, and HTML conversion.

The compression parameter controls image compression in the generated PDF. Choose one of the following values:

• lossy: Prioritizes a smaller PDF file size by allowing image-quality reduction. This is the default value.
• lossless: Preserves image quality without lossy compression, which can result in a larger PDF file.

This parameter does not apply to image-only, email, or structured-text conversion.

Compatible with PostScript, Microsoft Office, and HTML conversion.

The downsample parameter controls image resolution in the generated PDF. Choose 75, 150, 300, 600, or 1200 to downsample images to a target resolution in DPI, or choose off to preserve original image resolutions.

The default value is 300. Lower values can reduce file size for web delivery, while higher values are useful when image detail is more important.

This parameter does not apply to image-only, email, or structured-text conversion.

Compatible with Microsoft Office and structured-text conversion.

The tagged_pdf parameter controls whether supported input files produce tagged PDF output. Set the value to on to enable tagged output or off to disable it.

For Markdown, plain text, JSON, XML, and CSV input, tagged PDF output is enabled by default. Use structured_text_options.enable_tagging when you need to control tagging inside the structured-text configuration. When both parameters are supplied, structured_text_options.enable_tagging takes precedence.

Tagging adds logical document structure that can improve accessibility and downstream processing. Tagged output alone does not guarantee conformance with a specific accessibility standard.

Compatible with HTML and structured-text conversion.

The page_size parameter selects a standard paper size for the generated PDF. Choose one of the following values:

• letter
• legal
• ledger
• A3
• A4
• A5

The default value is letter.

For Markdown, plain text, JSON, XML, and CSV input, use structured_text_options.page_setup.size when page setup should be included in the structured-text configuration. The nested page_setup.size value takes precedence over page_size.

Compatible with HTML and structured-text conversion.

The page_margin parameter sets equal margins on all four sides of the generated PDF. Enter a number followed by in for inches or mm for millimeters.

Examples include:

• 1in
• 8mm
• 2.5in

The default value is 1in.

For Markdown, plain text, JSON, XML, and CSV input, use structured_text_options.page_setup.margin when you need separate top, right, bottom, and left margins. Nested margins use PDF points, where 72 PDF units equal 1 inch, and take precedence over page_margin.

Tip: Setting this to zero allows content to flow to the edges of the document, allowing a PDF to match the appearance of a website.

Compatible with HTML and structured-text conversion.

The page_orientation parameter sets the page orientation of the generated PDF. Choose one of the following values:

• portrait: The default value.
• landscape

For Markdown, plain text, JSON, XML, and CSV input, structured_text_options.page_setup.orientation takes precedence when supplied. The structured-text setting also supports auto, allowing the converter to select an orientation based on the configured page setup.

Compatible with HTML conversion.

The web_layout parameter selects the intended responsive layout when converting an HTML web page. Choose one of the following values:

• desktop: The default value.
• tablet
• mobile

Use this parameter when the source web page changes its layout according to the browser viewport. It helps produce a PDF that reflects the intended desktop, tablet, or mobile presentation.

Compatible with Microsoft Excel conversion.

The locale parameter controls regional number, currency, date, and time formatting when converting Excel files. Choose one of the following values:

• US: Uses the en_US locale. This is the default value.
• Germany: Uses the de_DE locale.

This parameter applies to Excel conversion only and does not affect other Office documents, HTML, images, email, PostScript, or structured-text input.

Compatible with Markdown, plain text, JSON, XML, and CSV conversion.

The structured_text_options parameter is a JSON object that configures PDF generation from structured-text input. The API determines the input format from the submitted file extension, so do not include an input_format property.

For multipart requests, provide this JSON object as the structured_text_options form field. For requests that use an existing source resource ID, provide it as a JSON object in the request body.

Shared options

• title: Optional PDF document title.
• language: Optional document language, typically a BCP 47 language tag such as en-US.
• enable_tagging: Optional Boolean that enables or disables tagged PDF output. When omitted, tagged_pdf applies if supplied; otherwise structured-text conversion uses its tagged-output default.
• page_setup: Optional page configuration. Values supplied here take precedence over page_size, page_margin, and page_orientation.
• style: Optional typography, color, and table-presentation configuration.

JSON and XML options

• data_presentation: Optional JSON or XML presentation mode.
  • source: Preserves source syntax and indentation. This is the default.
  • hierarchy: Renders the data as a readable hierarchy.

Markdown options

• include_unrendered_html: Optional Boolean. Set to true to preserve unsupported raw HTML as literal text; unsupported raw HTML is stripped by default.
• markdown.image_alt_text: Optional map of Markdown image targets to non-empty alternate-text strings.
• markdown.missing_image_alt_text: Optional policy for images without alternate text.
  • warn: Continue conversion. This is the default.
  • fail: Reject the conversion.
  • artifact: Mark the image as an artifact.
• markdown.image_sources: Optional map of each non-HTTPS Markdown image target to an uploaded image or an existing image resource ID. Inline images, reference-style images, and raw HTML <img> targets are supported.

Plain-text options

• plain_text.line_handling: Optional line-handling mode.
  • reflow: Reflows source lines into readable paragraphs. This is the default.
  • preserve: Preserves source line breaks and spacing.

CSV options

• csv.first_row_is_header: Optional Boolean that treats the first CSV row as table headers.
• csv.delimiter: Optional one-character field delimiter.
• csv.columns: Optional list of per-column overrides.
  • index: Required zero-based column index.
  • text_align: Optional left, center, or right alignment.
  • width_weight: Optional positive relative column-width weight.

Page setup options

• page_setup.size: Optional standard page-size name, such as Letter or A4.
• page_setup.width and page_setup.height: Optional custom page dimensions in PDF points. Supply both values together.
• page_setup.orientation: Optional auto, portrait, or landscape orientation.
• page_setup.margin: Optional per-side margins in PDF points.
  • top
  • right
  • bottom
  • left

Style options

• style.font: Optional body-text font family.
• style.heading_font: Optional heading font family.
• style.code_font: Optional font family for code and preformatted text.
• style.cjk_font: Optional font family for Chinese, Japanese, and Korean text.
• style.fallback_fonts: Optional ordered list of fallback font families used when a character is unavailable in the primary font.
• style.text_size: Optional body-text size from 6 to 72 PDF points.
• style.text_color_rgb: Optional body-text RGB color array, such as [34, 34, 34].
• style.heading_scale: Optional positive heading-size multiplier up to 4.
• style.table: Optional table styling for Markdown and CSV conversion.

Table style options

• column_width_weights: Optional list of positive relative column-width weights.
• keep_header_with_first_row: Optional Boolean that prevents a table header from being left alone at the bottom of a page.
• repeat_headers_on_overflow: Optional Boolean that repeats table headers on continuation pages.
• show_borders: Optional Boolean that shows or hides table borders.
• border_width: Optional border width from 0 to 12 PDF points.
• border_color_rgb: Optional RGB border color array.
• header_fill_color_rgb: Optional RGB header-row background color array.
• header_text_color_rgb: Optional RGB header-row text color array.
• row_fill_color_rgb: Optional RGB body-row background color array.
• alternate_row_fill_color_rgb: Optional RGB alternating body-row background color array.
• cell_padding: Optional per-side cell padding in PDF points, with top, right, bottom, and left values from 0 to 72.

Use supported font families from the pdfRest Font List.

Example: Styled CSV conversion

{
  "title": "Quarterly Service Summary",
  "language": "en-US",
  "enable_tagging": true,
  "page_setup": {
    "size": "Letter",
    "orientation": "landscape",
    "margin": {
      "top": 36,
      "right": 42,
      "bottom": 36,
      "left": 42
    }
  },
  "style": {
    "font": "Arial",
    "heading_font": "Arial",
    "text_size": 11,
    "text_color_rgb": [34, 34, 34],
    "table": {
      "column_width_weights": [2, 3, 1],
      "keep_header_with_first_row": true,
      "repeat_headers_on_overflow": true,
      "show_borders": true,
      "border_width": 0.75,
      "border_color_rgb": [180, 188, 200],
      "header_fill_color_rgb": [33, 64, 98],
      "header_text_color_rgb": [255, 255, 255],
      "row_fill_color_rgb": [250, 250, 252],
      "alternate_row_fill_color_rgb": [235, 240, 246],
      "cell_padding": {
        "top": 6,
        "right": 8,
        "bottom": 6,
        "left": 8
      }
    }
  },
  "csv": {
    "first_row_is_header": true,
    "delimiter": ",",
    "columns": [
      {
        "index": 0,
        "text_align": "left",
        "width_weight": 2
      },
      {
        "index": 1,
        "text_align": "left",
        "width_weight": 3
      },
      {
        "index": 2,
        "text_align": "right",
        "width_weight": 1
      }
    ]
  }
}

Example: Markdown conversion with uploaded and existing images

{
  "title": "Quarterly Operations Report",
  "language": "en-US",
  "enable_tagging": true,
  "page_setup": {
    "size": "Letter",
    "orientation": "portrait"
  },
  "markdown": {
    "image_alt_text": {
      "company-logo": "Company logo",
      "operations-chart": "Bar chart showing quarterly operations volume"
    },
    "missing_image_alt_text": "fail",
    "image_sources": {
      "company-logo": {
        "upload_index": 0
      },
      "operations-chart": {
        "image_id_index": 0
      }
    }
  }
}

Image Files

Compatible with multipart Markdown conversion through the /pdf endpoint.

The image_files parameter allows you to include one or more local images with a Markdown source file. Use this parameter when the Markdown source contains a non-HTTPS image target that should resolve to an image uploaded in the same request.

The following image formats are accepted:

• .gif
• .jpg / .jpeg
• .png
• .tif / .tiff

Repeat the image_files field once for each image. Upload order determines the zero-based upload_index values used in structured_text_options.markdown.image_sources.

For example, the first image upload uses "upload_index": 0, the second uses "upload_index": 1, and so on. Every uploaded image must be referenced by a Markdown image target.

Markdown images that use supported public HTTPS URLs are downloaded automatically and do not require image_files. pdfRest rejects URLs with credentials, non-HTTPS URLs, private or loopback network addresses, unsafe redirect targets, unsupported image types, and remote images larger than 20 MB.

Newly uploaded image resource IDs are returned in the inputId response array. For Markdown conversion, this array lists the source Markdown resource first, followed by newly uploaded image resources in upload order.

Image IDs

Compatible with Markdown conversion through the /pdf endpoint.

The image_ids parameter allows you to supply one or more existing pdfRest image resource IDs with a Markdown conversion request. Use this parameter when image assets were uploaded or generated in an earlier API call and remain available on the pdfRest processing server.

The following image formats are accepted:

• .gif
• .jpg / .jpeg
• .png
• .tif / .tiff

For multipart requests, repeat the image_ids field once for each resource ID. For JSON requests, provide image_ids as an ordered array. The order determines the zero-based image_id_index values used in structured_text_options.markdown.image_sources.

Every supplied image ID must be referenced by a Markdown image target.

Example: Markdown source resource with existing image resources

{
  "id": "your-markdown-resource-id",
  "image_ids": [
    "your-logo-resource-id",
    "your-chart-resource-id"
  ],
  "structured_text_options": {
    "markdown": {
      "image_sources": {
        "company-logo": {
          "image_id_index": 0
        },
        "operations-chart": {
          "image_id_index": 1
        }
      }
    }
  }
}

For Markdown conversion, the inputId response array lists the source Markdown resource first, followed by newly uploaded image resources and then existing image_ids in submission order.

Compatible with PostScript (.ps) and EPS (.eps) conversion.

The job_options parameter allows you to upload an optional .joboptions file with a PostScript or EPS source. A .joboptions file contains Adobe Distiller-compatible conversion settings. pdfRest applies a supplied profile with Datalogics PDF Converter SDK, maintained in partnership with Adobe using the same Adobe technology that powers Distiller.

Use this parameter when a workflow needs an established conversion profile for settings such as image handling, font embedding, color management, or output optimization. When job_options is omitted, Convert to PDF uses its standard PostScript and EPS conversion settings.

The uploaded profile must be readable, non-empty, no larger than 5 MB, and contain valid conversion settings. Do not send job_options together with job_options_id.

Newly uploaded .joboptions files receive resource IDs and follow the normal pdfRest resource-retention lifecycle. When a custom profile is used, the response inputId contains the source file ID followed by the .joboptions resource ID.

Compatible with PostScript (.ps) and EPS (.eps) conversion.

The job_options_id parameter lets you apply a previously uploaded .joboptions profile without uploading it again. Use it when an application stores an approved conversion profile as a pdfRest resource and wants to reuse that profile across PostScript or EPS conversion requests.

The referenced profile must be accessible, readable, non-empty, no larger than 5 MB, and contain valid conversion settings. Do not send job_options_id together with job_options.

When a custom profile is used, the response inputId contains the source file ID followed by the .joboptions resource ID.