Skip to main content

Create report

POST https://api.rollstack.com/public/v1/reports

Creates a report of type SlideDeck, in a folder the user can see when folderId is set. It starts empty, in the look of a saved template from listTemplates when templateId is set, or of another report when templateDeckId is set: its theme, masters and layouts, without its slides. Ask the user which template to use when the organization has company templates. With link, it imports an existing deck instead, with its slides: a PowerPoint file in OneDrive or SharePoint, or a Google Slides presentation, read with the user's own Microsoft or Google account. Rollstack can open only the Google Slides presentations the user picked in Rollstack before, so a link to one they never did answers 422. Over REST, it also imports a PowerPoint (.pptx) file sent as multipart/form-data in the file field, with name and folderId as fields beside it; a report imported from a file is named after it unless name is set. An import answers once the deck is in, which can take a minute for a large one: send an Idempotency-Key (MCP: idempotencyKey) so a retry doesn't import it twice. At most 10 imports a minute per user.

Requires the slide_decks:write scope.

Operation ID: createReport.

Headers

  • Idempotency-Key (string): A unique value, such as a UUID, that makes retrying this call safe. A retry with the same key within 24 hours answers the first call's result instead of running it again. Use a new key for each new call. From 1 to 255 printable ASCII characters.

Request body, required

application/json

  • name (string): Name for the report, as members will see it in Rollstack. Leading and trailing spaces are removed, and it can't be blank. If omitted, a report imported with link takes its file's name, and an empty report is named Untitled report until the slides agent names it as it builds the deck, as in the app. Example: Q3 business review.
  • folderId (string): The folder to create the report in, by its id from listFolders; it must be one you can see. Members with access to the folder can then open the report too, with the access the folder gives them. If omitted, the report is created at the top level, outside any folder. Example: a3d5e7f9-1b2c-4d6e-8f0a-1b2c3d4e5f6a.
  • templateDeckId (string): An existing report whose design the new report starts with, by its id from listReports: its theme, slide masters, layouts and slide size, but none of its slides or data. Its type must be SlideDeck, and you need at least view access to it. If neither this, templateId nor link is set, the report starts with no slides and Rollstack's default theme and layouts. Example: 6c1f9a2e-3b4d-4e8f-9a1b-2c3d4e5f6a7b.
  • templateId (string): A saved template the new report starts with, by its id from listTemplates: a company template or Rollstack's own. The report gets its theme, slide masters, layouts and slide size, with no slides. Leave out templateDeckId when you set it. Example: rollstack-signature.
  • link (string): A link to an existing deck to import, as its Share or Copy link button gives it: a PowerPoint (.pptx) file in OneDrive or SharePoint, or a Google Slides presentation. The report starts with its slides and look: a PowerPoint file's charts come in as charts with their data, and a Google Slides presentation's as pictures. The file stays as it is. It is read with the user's own Microsoft or Google account, connected in the app, so they must be able to open it, and Rollstack can open only the Google Slides presentations the user picked in Rollstack before. The report keeps the deck's look, so leave out templateId and templateDeckId. Example: https://contoso.sharepoint.com/:p:/s/Finance/EbXqT9kLmNpQrStUvWxYz.

multipart/form-data

  • file (string (binary), required): The PowerPoint file, a .pptx of at most 100 MB. The endpoint says what it takes from the file and how it names what it makes.
  • name (string): Name for the report, as members will see it in Rollstack. If omitted, it takes the file's name without .pptx. Example: Q3 business review.
  • folderId (string): The folder to create the report in, by its id from listFolders; it must be one you can see. Members with access to the folder can then open the report too, with the access the folder gives them. If omitted, the report is created at the top level, outside any folder. Example: a3d5e7f9-1b2c-4d6e-8f0a-1b2c3d4e5f6a.

Response 201

Success

application/json

  • id (string, required): Unique identifier for the report. Pass it as id to the other /reports/{id} endpoints.
  • type (string, required): The kind of report, which decides the endpoints that work on it.

    • SlideDeck: a slide deck built in Rollstack. Every /reports/{id} endpoint works on it, except listReportSyncs and convertReport.
    • GoogleSlides, GoogleDocs, MicrosoftPowerPoint, MicrosoftWord: a file in Google Drive or OneDrive that Rollstack updates with its visualizations.
    • UploadedPPTXFile: a PowerPoint file uploaded to Rollstack, which it updates the same way.
    • Email: an email report, whose visualizations Rollstack sends in an email.

    On a report that isn't a SlideDeck, only getReport, updateReport, deleteReport, shareReport, unshareReport, getReportSchedules, updateReportSchedules, startReportRun, listReportRuns, getReportRun, cancelReportRun, listReportSyncs and the email endpoints (getReportEmailConfig, updateReportEmailConfig, listReportEmails, sendReportEmail, sendReportTestEmail) work, and convertReport on a GoogleSlides or MicrosoftPowerPoint report. The other /reports/{id} endpoints take SlideDeck reports only, as their id says, and return 400.

    One of GoogleDocs, GoogleSlides, MicrosoftPowerPoint, MicrosoftWord, Email, UploadedPPTXFile, SlideDeck.

  • name (string, required): Name of the report, as members see it in Rollstack. Change it with updateReport.
  • folderId (string or null, required): The folder the report is in, by its id in listFolders. null when the report is at the top level, outside any folder.
  • owner (object, required): The member who owns the report: whoever created it, unless ownership has since been transferred, in the app or with transferReportOwnership. Only the owner can delete the report.
    • id (number, required): The owner's user id, the same as their id in listMembers.
    • name (string, required): The owner's name, as shown in Rollstack.
    • email (string, required): The owner's email address. Rollstack emails this address when a scheduled run of the report fails, while notifyOnFailure is true.
  • permission (string or null, required): Your access to the report, as the user the API key belongs to. view lets you open and export it, and see its datasheets, runs, schedules and email setup. comment also lets you add, reply to and resolve comments on its slides. edit also lets you change it: rename or move it, chat with the slides agent about it, add datasheets and read their data, start runs, set its schedules and email, send its email, and share it. It's never null here, since the API only returns reports you can at least view. One of view, comment, edit.
  • timezone (string or null, required): The report's timezone, such as America/New_York. The slides agent uses it to tell today's date, and the report's emails show the time of its last successful update ({{last_updated_at}}) in it. On a report that updates a file, such as a Google Slides presentation, it's also the timezone of the file's date variables, unless the organization's timezone replaces it. Schedules don't use it: each has its own timezone. null when the report has none, in which case the slides agent uses UTC. Reports created with createReport start with the organization's timezone from getOrganization, if it has one.
  • notifyOnFailure (boolean, required): Whether Rollstack emails the report's owner when a scheduled run fails or some of its datasheets, or a file's visualizations, fail to refresh, copying everyone in notificationMailingList. Runs started in the app or with startReportRun never send this email. New reports start with true.
  • lastSyncedAt (string (date-time) or null, required): When the report's latest run ended, whatever its outcome. null if the report has never run.
  • lastSuccessfulUpdateAt (string (date-time) or null, required): When the report's latest fully successful run ended: one that refreshed every datasheet it ran on, or every visualization on a report that updates a file, with none failing. Runs with nothing to refresh don't count. The report's emails show this time as {{last_updated_at}}. null until the report has had such a run.
  • lastRunStatus (string or null, required): How the report's latest run ended. completed: it finished, even if some datasheets or visualizations failed to refresh or it had none to refresh; on a SlideDeck report, listReportDatasheets shows each datasheet's error. failed: it stopped on an error, or none of its datasheets or visualizations could be refreshed. cancelled: it was stopped before it finished, for example with cancelReportRun. null if the report has never run. running and timed_out never appear here: check running to see whether a run is in progress. One of running, completed, failed, cancelled, timed_out.
  • running (boolean, required): Whether a run of the report is in progress, whoever started it, such as you with startReportRun, a member in the app, or one of its schedules. While it's true, startReportRun returns that run instead of starting another.
  • appUrl (string (uri), required): Link that opens the report in Rollstack.
  • fileUrl (string or null, required): Link that opens the Google Slides, Google Docs, PowerPoint or Word file the report updates. null for a slide deck, an email report or an uploaded PowerPoint file, which have no file to open, and for a Microsoft file whose link Rollstack has not read yet.
  • createdAt (string (date-time), required): When the report was created. listReports returns the newest first.
  • updatedAt (string (date-time), required): When the report's details last changed, such as its name, folder or owner, or the outcome of its latest run.
  • notificationMailingList (array of string, required): Email addresses Rollstack copies when it emails the owner about a failed scheduled run, while notifyOnFailure is true. Change the list with updateReport.
  • schedules (array of object, required): The report's schedules: when Rollstack runs the report on its own to update it with fresh data. Empty if it has none, in which case the report only runs when someone starts a run. Replace them with updateReportSchedules.
    • id (string, required): Unique identifier for the schedule. updateReportSchedules replaces every schedule, so the ids change each time you call it.
    • frequency (string, required): How often the schedule runs. hourly runs every day at each time in selectedTimes. daily, weekly, monthly and quarterly run whenever cronExpression fires; those made in the app run every day, on chosen weekdays, on chosen days of the month, or every three months, respectively. yearly can't be set through the API or the app, and also runs on cronExpression. One of daily, weekly, monthly, quarterly, hourly, yearly.
    • cronExpression (string, required): When the schedule runs, as a five-field cron expression (minute, hour, day of month, month, day of week) in the schedule's timezone. For an hourly schedule, Rollstack generates it from selectedTimes and runs the report at those times instead. Monthly schedules made in the app can use L and #, such as 0 9 L * * (last day of the month) or 0 9 ? * 1#1 (first Monday).
    • selectedTimes (array of string, required): The times of day an hourly schedule runs, every day, as 24-hour HH:mm in the schedule's timezone. Other frequencies don't use it; it's empty on those set through the API.
    • startDate (string (date-time), required): When the schedule starts: it never runs the report before this date and time. This is a local date and time in the schedule's timezone, written as if it were UTC: 2026-11-02T09:00:00Z means 9:00 on November 2, 2026 in that timezone, not 9:00 UTC.
    • endDate (string (date-time) or null, required): When the schedule ends: it never runs the report after this date and time. null if the schedule never ends. Like startDate, this is a local date and time in the schedule's timezone, written as if it were UTC.
    • timezone (string, required): The timezone the schedule runs in. Its run times (cronExpression or selectedTimes), startDate and endDate are all local times in this timezone, so a schedule set for 9:00 keeps running at 9:00 local time when daylight saving time starts or ends. Given as an IANA timezone name, such as America/New_York.
    • syncIds (array of string or null, required): The syncs, from listReportSyncs, that the schedule updates on a report other than a SlideDeck. null when it updates the whole report, which a slide deck always does.
    • nextRunAt (string (date-time) or null, required): When the schedule will next run the report. null if it has no runs left before its endDate. Unlike startDate and endDate, this is an actual UTC time.
  • sharedWith (array of object, required): Members the report is shared with directly, with their access. Members who can open it through its folder aren't listed. Change this list with shareReport and unshareReport.
    • userId (number, required): The member's user id. Pass it as userId to shareReport to change their access, or to unshareReport to remove it.
    • email (string, required): The member's email address, as shown in Rollstack.
    • name (string, required): The member's name, as shown in Rollstack.
    • permission (string, required): What the member can do with the report. view lets them open, export and duplicate it. comment also lets them add, reply to and resolve comments on its slides. edit also lets them change its slides, data, schedules, email and other settings, run it, send its email, chat with the slides agent about it, and manage who it's shared with. Neither lets them delete the report or transfer its ownership. One of view, comment, edit.