JSON API

JSON API

Introduction

phppptx Premium licenses include a JSON API that allows working with PPTX presentations from any language or platform capable of sending and receiving JSON data. This is not a remote or hosted service. Instead, it provides the classes and methods you need to build your own REST-ready architecture, API, or microservice using a JSON-based interface.

Among its many features, the following can be highlighted:

  • Add new contents (text, tables, images, lists, charts, medias...).
  • Create and apply new styles and customize existing ones.
  • Transform HTML into PPTX content.
  • Replace contents in templates.
  • Modify slide layout and settings.
  • Format conversion (HTML, PPTX to PDF...).
  • PptxPath queries to manipulate existing content.
  • Merge and watermark presentations.
  • Utilities for PPTX presentations.
  • Work with PptxFragments.
  • Performance features such as zip stream.
  • Files such as images can be added as local paths, Data URL (Uniform Resource Locator) with Base64-encoded string, or remote URLs.

All available actions and their JSON data parameters are documented in the JSON API reference.

Request structure

A JSON API request is a JSON object with the following top-level keys:

  • template (optional): The path to a PPTX template. Can be a local file path, a Base64-encoded string, or a remote URL.
  • settings (optional): Extra settings that apply to the entire request, such as streamMode.
  • pptxfragments (optional): An array of PptxFragments to be used in the request. Each PptxFragment has:
    • name: The name of the PptxFragment.
    • actions: The content of the PptxFragment.
  • actions: An array of actions to execute sequentially. Each action has:
    • action: The name of the phppptx action to call (e.g. addText, replaceVariableText).
    • data: The JSON object containing the action parameters.

Multiple actions can be chained in a single request. They are executed in the order they appear in the actions array.

New presentations

To create a new PPTX from scratch, omit the template key and add the content actions to run. For example, to add a slide, and text content:

Each action maps directly to a phppptx method. All available actions and their JSON data parameters are documented in the JSON API reference.

Template presentations

To work with an existing PPTX template, provide the template key. The template is loaded first, and then the actions are applied on top of it.

For example, to open a PPTX template and replace text variables:

A template can be provided as:

  • A local file path:
    "template": "path/to/template.pptx"
  • A Data URL (Uniform Resource Locator) with Base64-encoded string:
    "template": "data:application/vnd.openxmlformats-officedocument.presentationml.presentation;base64,..."
  • A remote URL:
    "template": "https://domain.com/template.pptx"

Template actions include replacing variables by text, image, HTML, PptxFragments...; getting template variable information; and many more. All available actions and their JSON data parameters are documented in the JSON API reference.

Settings

The optional settings key accepts global options that apply to the entire request.

Available settings:

  • streamMode: Generates a PPTX stream without saving the presentation to the file system. Set to true to enable.
  • responseType: Specifies the response type for the request. Possible values are "json" and "stream".
Response types

The responseType setting controls how the generated file is returned by the JSON API. If omitted, the default value is "json".

When responseType is "json" (default):

  • The API returns a JSON string.
  • On success, the response includes status: "success" and a data object with:
    • output: Base64-encoded generated file content.
    • mime: MIME type for the generated presentation.
  • Actions that return presentation information append their results to data. For example:
    • getPptxPathQueryInfo adds pptxPathQueryInfo.
    • getTemplateVariables adds templateVariables.
  • On error, the response includes status: "error" and a message with the error text.

Sample JSON response (success):

Sample JSON response (error):

When responseType is "stream":

  • The API returns the generated file content directly as a binary stream string.
  • No JSON wrapper is returned.
  • Error responses are not supported in stream mode; if an error occurs, an empty string is returned.
Available actions

The JSON API covers all major phppptx action groups:

  • PowerPoint contents.
  • Layouts.
  • Templates.
  • Format conversion.
  • PptxPath.
  • PptxUtilities.
  • PptxCustomizer.
  • Performance.

The full reference with all JSON data schemas and code samples is available in the JSON API documentation.

PptxFragments

PptxFragments let you define reusable content and inject them in actions to generate new presentations or replace variables in templates.

The following JSON sample illustrates how to define and use PptxFragments:

PptxFragments can include one or more actions.

More information

The JSON API documentation provides individual reference pages for every action, including the JSON data schema, parameter descriptions, and code samples.

In addition to this documentation, phppptx Premium packages include many ready-to-run samples illustrating how to use all JSON API actions.