API Reference

pptx.dev API Documentation

Generate .pptx files from OpenPresentation JSON, validate OPF documents, parse existing decks, and run best-effort PPTX-to-OPF conversion. Authenticated /v1 endpoints use Bearer token authentication.

OpenAPI (Swagger UI) →OPF Format Reference →OPF Toolkit npm proof →Registry Guide →TypeScript SDK (pre-release) →Python SDK (pre-release) →Go SDK (pre-release) →MCP Server (hosted beta) →CLI (pre-release) →Browse Gallery

Authentication

Authenticated API endpoints require a Clerk API key sent as a Bearer token. Local Author and Inspector editing, preview, and PowerPoint export need no account or API key. Get your API key from the API Keys page in your account settings.

Authorization: Bearer ak_your_clerk_api_key

Both user-level and organization-level Clerk API keys are supported. Signed-in browser sessions are used for account pages and optional hosted operations such as Decoder conversion and saved Author threads.

Base URL

https://api.pptx.dev

Endpoints

POST/v1/validatelive

Validate OPF

Validate an OPF JSON document or an external OPF registry URL. Returns errors and warnings without generating any files.

InputJSON body (OPF document or { registryUrl })

Output{ valid, errors[], warnings[], items[]? }

POST/v1/previewlive

Preview OPF (anonymous)

Validate OPF (max 256 KB) for Inspector. No API key; 30 req/min and 500/hour per IP. Query ?format=web|svg|png (default svg) and ?slides=1,3 for subsets.

InputJSON body (OPF document)

Output{ status, format, dimensions, slides[], warnings[] } (svg/png return slide metadata with svg: null and an export notice, not an image)

POST/v1/parselive

Parse PPTX

Upload a .pptx file and extract structured data: slides, text, metadata, speaker notes.

InputFormData with "file" (.pptx)

Output{ parseId, slideCount, width, height }

POST/v1/convertlive

PPTX to OPF

Convert an existing .pptx file into a best-effort OPF JSON document for Decoder, inspection, editing, and regeneration. This is the canonical OPF-out API; there is no separate /v1/decode alias.

InputFormData with "file" (.pptx)

OutputOPF JSON document

POST/v1/generatelive

Generate PPTX

Turn a valid OPF JSON document into a production .pptx file. Only format=pptx is implemented. format=pdf|png|svg are reserved values and return 501 not_implemented.

InputJSON body (OPF document)

Output.pptx binary for format=pptx; 501 not_implemented for pdf, png and svg

POST/v1/authorbeta

Author OPF draft

Create or refine a beta OPF draft from prompts, uploads, raw text, or OPF source. Author is the developer workbench/API layer, distinct from DeckChat's chat-first business surface.

InputJSON body or multipart source payload

OutputOPF draft, validation, and run metadata

POST/v1/author/threadsbeta

Create Author thread

Create a persistent Author conversation with OPF versions, run history, tool-call traces, and reviewable ghost edits.

InputJSON body with message, title?, client?

OutputThread snapshot and Author result envelope

POST/v1/renderbeta

Render slides

Convert a .pptx file to web-viewable slide data. Only format=web is implemented. format=svg|png return 501 not_implemented.

InputFormData with "file" (.pptx)

OutputSlide data for web rendering; 501 not_implemented for SVG/PNG

GET/v1/parse/[parseId]/metadatalive

Get metadata

Retrieve metadata (title, creator, dates, custom properties) from a previously parsed PPTX.

InputparseId path param

OutputMetadataResult JSON

GET/v1/parse/[parseId]/slides/[index]live

Get slide

Retrieve a single slide's text runs, dimensions, and speaker notes by index.

InputparseId + slide index

OutputSlideData JSON

GET/v1/parse/[parseId]/textlive

Get all text

Retrieve all text content from all slides of a parsed PPTX.

InputparseId path param

OutputArray of slide text data

POST/v1/data/importbeta

Data to table or chart

Turn CSV, TSV, JSON or .xlsx data into OPF table or chart content with the same rules as opf ingest. Returns a one-slide OPF document, or adds a slide (or a table/chart at a JSON Pointer path) to a document you send, with a validation report. Up to 5 MiB of text or a 10 MiB workbook, 5,000 rows and 100 columns; .xlsx reads one sheet, uses the values Excel saved for formulas, and turns date-formatted cells into ISO dates.

InputJSON { data, as, chartType?, category?, series?, columns?, header?, delimiter?, title?, document?, path? } or FormData with "file" and "options"

Output{ content, document, target, source, validation }

POST/v1/diffbeta

Diff two decks

Structural diff of two OPF decks (inline, or stored decks by id): slides and blocks match by id, then identical content, then similarity. Returns categorized changes, a slide summary, a text report and an RFC 6902 patch from a to b.

InputJSON { a, b, threshold?, report? }

Output{ equal, summary, slides, changes, patch, report }

POST/v1/patchbeta

Apply a patch

Apply RFC 6902 operations to an OPF deck atomically, with the inverse patch for undo. The result is validated by default (422 when invalid); with a stored deck, save: true stores it as a new version.

InputJSON { document, patch, validate?, strict?, save? }

Output{ document, inverse, patch, validation?, saved? }

POST/v1/lintbeta

Lint and audit

Format and reference checks (schema checks and catalog reference checks against the records the deck embeds and the default catalog pptx.dev registers, with suggestions), design and accessibility audit (contrast, overflow, type size, alt text, reading order, charts and more) and a font report, as findings in core's Finding format. Send source (JSON text) to get line and column for each finding.

InputJSON { document | source, audit?, fonts?, auditOptions? }

Output{ valid, lint, audit?, fonts? }

POST/v1/fonts/checkbeta

Check fonts

Every family an OPF deck, a .pptx or a list names, with OPF's font policy: license class, where viewers get the font, the open replacement previews draw with, and viewer diagnostics.

InputJSON { document | families } or FormData with "file" (.pptx or OPF JSON)

Output{ source, families[], diagnostics[], summary }

POST/v1/decksbeta

Store a deck

Store a .pptx file or an OPF JSON file as a new deck owned by your user or organization. Files up to 50 MiB; 1 GiB and 1,000 decks per owner. OPF files are stored even when they do not validate, and the response reports the validation result. Supports Idempotency-Key.

InputFormData with "file" (.pptx, .json or .opf) and optional "name"

Output{ deck, version, validation? }

GET/v1/decksbeta

List decks

Your stored decks, most recently updated first, with storage usage and limits. Page with ?limit= and ?cursor=.

InputOptional limit (1-100) and cursor

Output{ decks[], nextCursor, usage, limits }

GET/v1/decks/[deckId]beta

Get a deck

A stored deck's metadata and its versions, newest first. DELETE on the same path deletes the deck, every version and every share link.

InputdeckId path param

Output{ deck, versions[] }

POST/v1/decks/[deckId]/versionsbeta

Store a new version

Add a version in the deck's format (up to 100 per deck). GET on the same path lists the versions.

InputFormData with "file"

Output{ deck, version, validation? }

GET/v1/decks/[deckId]/contentbeta

Download a deck

Download the latest version, or ?version=N, as an attachment. The ETag is the file's SHA-256.

InputdeckId path param, optional version

Output.pptx or OPF JSON bytes

POST/v1/decks/[deckId]/sharesbeta

Create a share link

Create an expiring link (1 minute to 30 days, default 7 days) that downloads the deck without an account, pinned to a version or following the latest. The URL is shown once. GET lists links; DELETE /v1/decks/[deckId]/shares/[shareId] revokes one.

InputJSON { expiresInSeconds?, version? }

Output{ share, url, token }

GET/v1/shares/[token]beta

Download a shared deck

Public download through a share link; no API key. Unknown, expired and revoked links return 404.

Inputtoken path param

Output.pptx or OPF JSON bytes

Quick Start

Create a minimal OPF document and validate it:

cURL

curl -X POST https://api.pptx.dev/v1/validate \
  -H "Authorization: Bearer ak_your_clerk_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "$schema": "https://openpresentation.org/schema/opf/v1",
    "name": "My Presentation",
    "slides": [{ "title": "Hello, World" }]
  }'

Conversion Pipeline

The full input/output matrix supported by the API:

From	To	Endpoint	Status
Natural language	OPF JSON	/author + /v1/author/*	Beta
.pptx file	OPF JSON	/v1/convert	Live
OPF JSON	.pptx file	/v1/generate	Live
OPF JSON	PDF	/v1/generate?format=pdf	Not available (501)
.pptx file	Web slides	/v1/render?format=web	Beta
.pptx file	SVG / PNG	/v1/render?format=svg	Not available (501)

Error Codes

Code	Meaning
400	Bad request — invalid input, missing fields, or wrong content type
401	Unauthorized — missing or invalid API key
403	Forbidden — API key lacks required scopes, or a storage quota would be exceeded (`quota_exceeded`)
422	Unprocessable — OPF document failed schema validation
413	Payload too large — the upload is over the size limit
429	Rate limited — too many requests for the current key or IP
500	Internal error — please report if persistent
501	Not implemented — the requested format (PDF, PNG or SVG output) is not available yet. The body is `{ error: { code: "not_implemented", message, details } }`; nothing is processed or billed.
503	Service unavailable — a backing service such as deck storage is not configured on this host (`service_unavailable`)