JSON API — /api/v1
Slidura’s HTTP+JSON interface. Authenticate with a Bearer API key on every request; scopes on the key control what each call is allowed to do.
Base URL
https://app.slidura.com/api/v1Authentication
Authorization: Bearer slidura_live_...Mint a key at app.slidura.com/settings/api-keys.
Scopes
Keys carry coarse per-route scopes. The required scope is inferred from the HTTP method unless a route overrides it explicitly.
| Scope | Default HTTP methods | Used by |
|---|---|---|
read | GET, HEAD | Listing templates, fetching catalogs, polling build status |
write | POST, PUT, PATCH | Editing annotations, updating a build’s working fill |
delete | DELETE | Removing templates or builds |
build | — (explicit override) | Creating a draft build, starting a build, copying/archiving |
A key missing the required scope receives 403 Forbidden.
Resources
Account
| Method | Path | Description |
|---|---|---|
| GET | /me | Caller’s account and current credit balance |
Templates
| Method | Path | Description |
|---|---|---|
| GET | /templates | Own + non-hidden provider templates, starred first |
| POST | /templates | Upload a new .pptx template (multipart; optional slides_pdf) |
| GET | /templates/{id} | Template detail with versions and catalog summary |
| DELETE | /templates/{id} | Delete a template and all its catalogs/builds (cascades) |
| GET | /templates/{id}/theme | Active theme and derived palette |
| PUT | /templates/{id}/theme | Set the theme (base, look, font, background, variables) |
| POST | /templates/{id}/star | Star or un-star a template |
| POST | /templates/{id}/hide | Hide a starter template from listings (hide-not-delete) |
Catalogs and annotations
| Method | Path | Description |
|---|---|---|
| GET | /catalogs/{id} | Catalog status and metadata |
| GET | /catalogs/{id}/compact | Annotated compact catalog — the agent brief |
| GET | /catalogs/{id}/full | Raw full catalog JSON (available once the scan job completes) |
| GET | /catalogs/{id}/annotations | List all field annotations |
| PATCH | /catalogs/{id}/annotations/{aid} | Update a field annotation (label, description, choices, types…) |
| GET | /catalogs/{id}/variables | Head variables for template-product interpolation |
| PUT | /catalogs/{id}/variables | Replace head variables |
| GET | /catalogs/{id}/fill-draft | Staged draft fill (legacy catalog-scoped draft) |
| PUT | /catalogs/{id}/fill-draft | Write a staged draft a human can review in the fill builder |
| GET | /catalogs/{id}/default-fill | Owner-editable default every new build starts from |
| PUT | /catalogs/{id}/default-fill | Replace the default fill |
Builds — full lifecycle
| Method | Path | Scope | Description |
|---|---|---|---|
| POST | /catalogs/{id}/builds | build | Create a created build (the agent-editing entry point) |
| GET | /builds | read | List the caller’s builds; optional lifecycle filter |
| GET | /builds/{id} | read | Build status and metadata |
| PATCH | /builds/{id} | write | Edit the working fill and/or title of a created build |
| POST | /builds/{id}/start | build | Validate, spend credit, enqueue the build job |
| POST | /builds/{id}/copy | build | Copy a build into a new created build |
| POST | /builds/{id}/reopen | build | Reopen an archived build back to created |
| POST | /builds/{id}/archive | build | Archive a build |
| DELETE | /builds/{id} | delete | Permanently delete a build |
| GET | /builds/{id}/download | read | Download the .pptx output (also accepts a signed URL) |
See the build lifecycle for state
transitions and the lifecycle field values.
Refs
| Method | Path | Description |
|---|---|---|
| GET | /refs | Search fillable assets for paste-ready @ref strings; context ranks scoped items first |
Media — charts, tables, images, icons, diagrams, code, arts
All media resources follow the same pattern: list, create, get, update, delete. Arts additionally expose layout manifests, SVG rendering, and a geometry solve endpoint.
| Resource | Base path |
|---|---|
| Charts | /charts |
| Tables | /tables |
| Images | /images (presign + confirm upload flow) |
| Icon packs / glyphs | /icon-packs, /icon-glyphs |
| Diagrams | /diagrams |
| Code blocks | /code-blocks |
| Procedural arts | /arts |
Jobs
| Method | Path | Description |
|---|---|---|
| GET | /jobs/{id} | Poll a background job by id (catalog scan, build, enrichment) |
Published-fill hooks
These endpoints sit outside /api/v1 and use no API key — the capability
token embedded in the URL is the only credential.
| Method | Path | Description |
|---|---|---|
| POST | /hooks/fills/{token} | Trigger a build from a flat {variables, fields} payload merged onto the endpoint’s published default fill; returns build_id + status_url |
| GET | /hooks/fills/{token}/builds/{build_id} | Poll the build; returns status, download_url (time-limited signed URL), and expires_at |
Manage published-fill endpoints from the template workspace (Designs view) or the web UI.
Per-resource request/response shapes and generated OpenAPI docs are TODO.