The build lifecycle
A build is the durable working object that carries both the fill you are
composing and the resulting .pptx. It moves through a defined set of states
and is never silently deleted.
States
| State | What it means |
|---|---|
created | The fill is editable. The fill builder (or an API/MCP agent) can read and write the working fill. No credit has been spent. |
started | The build engine is running. One credit has been reserved. The fill is now read-only. |
built | The build succeeded. The .pptx is available for download. |
failed | The build engine returned an error. The credit was automatically refunded. The build can be reopened. |
archived | The build’s output file has been cleaned up; the fill is still kept. An archived build can be reopened or copied. |
Transitions
created ──start──► started ──success──► built ──archive──► archived
│ └──failure──► failed ──►──────►─┘
└── edit fill (PATCH /builds/{id}) — stays in created- Start: validates the fill, spends the credit, enqueues the job.
- Reopen: moves a
built,failed, orarchivedbuild back tocreatedwith its fill intact so you can edit and re-run it. - Copy: creates a new
createdbuild pre-seeded with the source build’s fill — useful for branching variations. - Archive: explicit archival any time from
builtorfailed; also triggered automatically by the scheduler after 7 days. The fill is always kept; only the output file is removed.
The /builds/{id} view
The build view at /builds/{id} switches its layout based on the current
state:
created— shows the fill builder (Assistant · Slides · Values tabs). This is where you compose the fill and, optionally, use the build assistant.- All other states — shows the build info panel: status, output link, slide reference images, and lifecycle actions (reopen, copy, archive).
Over the API and MCP
The full lifecycle is available programmatically:
| Action | API | MCP |
|---|---|---|
| Create a draft build | POST /api/v1/catalogs/{id}/builds | create_build |
| Edit the fill | PATCH /api/v1/builds/{id} | update_build |
| Start the build | POST /api/v1/builds/{id}/start | start_build |
| Poll status | GET /api/v1/builds/{id} | get_build_status |
| Download | GET /api/v1/builds/{id}/download | get_build_download_url |
| Copy | POST /api/v1/builds/{id}/copy | — |
| Reopen | POST /api/v1/builds/{id}/reopen | — |
| Archive | POST /api/v1/builds/{id}/archive | — |
See the JSON API reference and the MCP tool reference for full parameter details.