Presentations
Render a validated PresentationSpec to a PPTX and one SVG preview file per laid-out slide.
Presentations take a strict PresentationSpec, paginate dense slides, render a PowerPoint buffer
plus SVG previews, and persist each output as a ready Workspace File. Inputs that reference
workspace images must already be ready PNG, JPEG, or GIF files at most 10 MiB.
HTTP: POST /api/v1/presentations only. Agents use preview capability presentation.create
(confirmation and idempotency required). That executor also asserts Workspace Files write
readiness.
Spec
Theme is only fluxus (default). slides length 1–500. Slide types:
type | Required fields | Notes |
|---|---|---|
title | title | Optional subtitle |
section | title | Optional subtitle |
bullets | bullets (1–100 strings) | Optional title |
two-column | left / right columns with bullets | Optional headings |
table | columns (1–12), rows (1–500, width must match) | Cells: string (max 2000), number, bool, null |
chart | chartType bar | line | pie, categories, series | Pie requires exactly one series |
image | image.fileId + alt, or legacy image.data URI | See images below |
Optional spec fields: title, subject, author, company (bounded strings). Request body
name is optional (1–255 after trim) and becomes the PPTX basename.
Layout pagination (render, not spec max): bullets 7 per page, column bullets 6, table rows 8,
chart categories 10. slideCount in the response is the laid-out count (must equal preview
file count, ≥ 1).
Images
Primary: { fileId, alt } — file in the same workspace, status: ready, MIME
image/png | image/jpeg | image/gif, sizeBytes ≤ 10 MiB. Missing file: 404 without
revealing ownership. Not ready: 409. Bad MIME or size: 422. A 30 minute reference lease
(resourceType: "artifact") is taken before bytes are read.
Legacy dual-read: { data, alt } with a base64 data URI (png, jpeg, gif, or
svg+xml) decoding to at most 10 MiB. New Workspace File inputs reject SVG MIME types
(active content). Inline SVG remains only for already persisted specs.
Persistence and rollback
Outputs:
{basename}.pptx—application/vnd.openxmlformats-officedocument.presentationml.presentation{basename}-{preview.fileName}—image/svg+xmlper slide
Each output goes through Files create → put → complete → scan. If scan is not ready,
PresentationOutputNotReadyError (409). On any failure after files were created, the service
removes artifact references and requestDeletion on created outputs (and input leases).
Basename: NFKD, strip combining marks, drop .pptx/.svg, lowercase, non-alphanumeric → -,
max 120 characters, fallback presentation.
Authorization and idempotency
Workspace API key. 401 / 403 as other v1 routes. Body must not include workspaceId (strict
schema → 422).
Idempotency-Key is validated before parse. API lock duration 30 minutes. Replay of a
successful create returns 201 with Idempotency-Replayed: true and does not render again.
Transient 500 (Presentation creation failed.) is not cached; the same key can succeed on
retry (proven in API tests).