Endpoints
Presentations
Create a PPTX and SVG preview Workspace Files from a PresentationSpec.
Single endpoint POST /api/v1/presentations. Envelope: api-contracts.v1. See
Presentations for spec types, pagination, and file rollback.
Create
POST /api/v1/presentations — 201 { presentation }.
Requires header Idempotency-Key (validated before JSON parse). Idempotency lock: 30 minutes.
{
"name": "Q3 review",
"spec": {
"theme": "fluxus",
"slides": [{ "type": "title", "title": "Q3 review" }]
}
}
| Field | Notes |
|---|---|
name | Optional, trim, 1–255. Drives output file basename. |
spec | Required. Strict object; extra keys (including workspaceId) → 422. |
data.presentation (service payload, not a Workspace File row):
| Field | Notes |
|---|---|
id | Render UUID; used as Files resourceId for artifact references |
slideCount | Laid-out slide count |
presentation | Serialized ready PPTX Workspace File |
previews | Array of { slideIndex, ...serializedFile } SVG files |
Serialized files match the Files object (id, name, mimeType,
sizeBytes, sha256, status, createdAt, updatedAt).
Capability presentation.create uses the same service (name, spec) after Files write
readiness.
Error map
| HTTP | error.code | Typical cause |
|---|---|---|
| 400 | idempotency_key_invalid | Missing/invalid Idempotency-Key |
| 401 | authentication_required | Bearer |
| 403 | authorization_failed | Non-workspace key |
| 404 | resource_not_found | Image fileId not in this workspace (Presentation image file was not found.) |
| 409 | conflict | Input file not ready, or generated file failed scan |
| 422 | validation_failed | Spec/body invalid, unsupported image MIME/size |
| 500 | internal_error | Presentation creation failed. (not idempotency-cached) |