Hosted API Reference

The hosted runtime accepts a documented semantic protocol and issues durable render jobs.

Boundary:

• Public contract: sourceSchema: "protocol_v2" plus document.version: "2.0" and document.layoutFamily
• Free local package: @paperjsx/json-to-pptx
• Paid PPTX package: @paperjsx/json-to-pptx-pro
• Hosted production usage: Pro / Pro (All Formats) / Enterprise

Protocol Contract

Treat PresentationSpec as a wire contract and validate in your own code against the shape below. The workspace @paperjsx/protocol package is internal.

PresentationSpecSchema

import { z } from "zod";

const PresentationSpecSchema = z.object({
  version: z.literal("2.0"),
  title: z.string(),
  layoutFamily: z.enum(["editorial", "board", "product", "immersive"]),
  accentColor: z.string().optional(),
  slides: z.array(z.unknown()),
});

PresentationSpec

interface PresentationSpec {
  version: "2.0";
  title: string;
  layoutFamily: "editorial" | "board" | "product" | "immersive";
  accentColor?: string;
  brand?: {
    brandPackId?: string;
    brandPackVersionId?: string;
  };
  slides: SlideSpec[];
}

SlideSpec

Stable V2 slide types:

• title-body
• kpi-grid
• comparison-table
• market-map
• timeline
• org-chart
• waterfall
• tombstone-grid

Example:

const document: PresentationSpec = {
  version: "2.0",
  title: "Board Update",
  layoutFamily: "board",
  accentColor: "#2563EB",
  slides: [
    {
      slideType: "title-body",
      title: "Executive Summary",
      body: [
        "Revenue accelerated in Q2.",
        "The operating model is ready for rollout."
      ]
    },
    {
      slideType: "kpi-grid",
      title: "Core KPIs",
      items: [
        { label: "ARR", value: "$12.4M", trend: "up" },
        { label: "NRR", value: "118%", trend: "up" }
      ]
    }
  ]
};

Runtime Endpoints

The canonical flow is preflight → render → poll → compare/approve.

POST /api/v2/preflight

{
  sourceSchema: "protocol_v2",
  brandPackId?: string,
  brandPackVersionId?: string,
  preflightPolicy?: { autoFix?: "off" | "suggest_only" },
  document: PresentationSpec
}

Returns data.job_id, data.job_url, data.quality_report, data.brand_compliance, data.policyResult, data.validationSummary, and data.requested_validation_mode.

policyResult is the canonical guardrail decision and includes allowedToRender, blocking, blockingCodes, blockingFindingCount, unsupportedModes, reasons, and nextActions.

If the requested validation mode is unsupported, preflight returns a durable blocked decision on the same route — with the job URL plus policyResult — instead of pretending the mode ran.

validationSummary records what ran vs. what was deferred: requestedMode, preflightExecutedModes, renderExecutedModes, executedModes, deferredModes, unsupportedModes, reason.

POST /api/v2/render

{
  sourceSchema: "protocol_v2",
  mode?: "sync" | "async",
  approvalRequired?: boolean,
  brandPackId?: string,
  brandPackVersionId?: string,
  baselineJobId?: string,
  preflightPolicy?: {
    preflightOnly?: boolean,
    renderIfScoreAbove?: number,
    autoFix?: "off" | "suggest_only"
  },
  document: PresentationSpec
}

Returns:

• Sync: artifact URLs, quality_report, policyResult, validationSummary.
• Async: job_id and job_url.

For desktop_blocking, validationSummary makes the phase split explicit. A successful render can report executedModes: ["structural", "desktop_blocking"] with a reason noting that desktop validation was deferred until render-backed execution.

GET /api/v2/jobs/:id

Durable job record with artifact and preview URLs, latest approval plus history, diff summary, brand-pack metadata, and preflight report summary.

GET /api/v2/jobs/:id/diff

Deck-level diff summary, per-slide slides[], currentPreviewUrl, baselinePreviewUrl, diffPreviewUrl, approval payload, and package diff.

The V2 runtime is protocol-only. Legacy V1 AgentDocument payloads are not part of the supported contract.