Skip to main content

Create burst

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

Makes a report the template of a new burst, and answers the burst, named after the report and with no variants yet. Add them with addBurstVariants. A Rollstack report's variants differ by the report parameters in parameterIds, found with getReportParameters. An older report's variants differ by the filters in filters, found with listReportSyncFilters: a folder is made for the burst in Google Drive or OneDrive and the report's file is copied into it as the template, which can take a minute. Only the report's editors may.

Requires the slide_decks:write scope.

Operation ID: createBurst.

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

  • templateReportId (string, required): The report to make the template of the burst, by its id from listReports. You must be able to edit it, and it can't already be part of a burst. A Rollstack report must have datasheets, and becomes the template as it is. An older report must have syncs: its file is copied into a new folder for the burst, and the copy becomes the template. Example: 6c1f9a2e-3b4d-4e8f-9a1b-2c3d4e5f6a7b.
  • parameterIds (array of string (uuid)): For a Rollstack report: the template report's parameters the variants differ by, by their id from getReportParameters, in the order their values name a variant. Each must be burstable there. At least one.
  • filters (object): For an older report, such as a Google Slides or PowerPoint file: the filters of its syncs the variants differ by.
    • primaryIds (array of string, required): The filters that name the variants, by their id from listReportSyncFilters, in the order their values name a variant. 1 to 3. With more than one, each variant's file goes in a folder per value, one level per filter.
    • secondaryIds (array of string): Filters a variant can also set, which don't name it, by their id from listReportSyncFilters. Defaults to [].
  • parentFolderId (string): For an older report: the Google Drive or OneDrive folder to create the burst's folder in, by its id in that drive. The template and the variants' files go in the burst's folder. Defaults to the top of your drive.
  • driveId (string): For an older report: the shared drive parentFolderId is in. Leave it out for a folder in your own drive.
  • variantNaming (string): How each variant's report is named from the burst's name and the name the variant is added with, EMEA in a burst named Regional Review: suffix gives Regional Review - EMEA, prefix gives EMEA - Regional Review, and sameName gives EMEA. It applies to variants added from then on. Defaults to suffix. One of sameName, prefix, suffix.

Response 201

Success

application/json

  • id (string, required): Unique identifier for the burst. Pass it as id to the other /bursts/{id} endpoints.
  • name (string, required): Name of the burst, as members see it in Rollstack. It is the template report's name when the burst is created, and is part of each variant report's name unless variantNaming is sameName.
  • folderId (string or null, required): The folder the burst is in, by its id in listFolders. null when the burst is at the top level.
  • owner (object, required): The member who owns the burst: whoever created it, unless ownership has since been transferred in the app.
    • 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.
  • templateReportId (string or null, required): The template report, which every variant was copied from when it was added, by its id for getReport and the other /reports/{id} endpoints. Changes to the template reach existing variants only when pushed from the app; variants added later copy it as it is then. null if the template was deleted.
  • variantNaming (string, required): How each variant's report is named from the burst's name and the name the variant is added with, EMEA in a burst named Regional Review: suffix gives Regional Review - EMEA, prefix gives EMEA - Regional Review, and sameName gives EMEA. It applies to variants added from then on. One of sameName, prefix, suffix.
  • kind (string, required): What the variants differ by. parameters: report parameters of a Rollstack report, listed in parameters and set with parameters in addBurstVariants. filters: filters of an older report's syncs, such as a Google Slides or PowerPoint file, listed in filters and set with filters in addBurstVariants. One of parameters, filters.
  • reportType (string, required): The type of report the burst copies, as type in listReports: SlideDeck for a Rollstack report, which bursts by parameters, any other type for an older report, which bursts by filters. One of GoogleDocs, GoogleSlides, MicrosoftPowerPoint, MicrosoftWord, Email, UploadedPPTXFile, SlideDeck.
  • parameters (array of object, required): The template report's parameters the variants differ by, in the order their values name a variant. Each variant holds its own value of each, which its datasheets' filters read. Empty for a burst by filters.

    • id (string, required): The report parameter's id on the template report. Use it as a key of parameters in addBurstVariants.
    • name (string, required): The report parameter's name, as shown in Rollstack.
    • value (object or null, required): The template's value of the parameter, which a variant keeps when it doesn't set one. null when the template has none. A value of a report parameter, in the shape of its type. Copy the shape of the parameter's value in listBursts, or of a variant's in listBurstVariants:

      • A list of values: { "type": "categorical", "values": ["EMEA"] }, with at least one value. operator can also be is_not, contains or doesnt_contain; it is is when left out.
      • A number: { "type": "number", "value": 10 }. Text: { "type": "text", "value": "EMEA" }.
      • A date range: { "type": "date", "subtype": "date_range", "startDate": "2026-01-01", "endDate": "2026-03-31" }. One date: { "type": "date", "subtype": "date_single", "date": "2026-03-31" }.
      • A month or a quarter: { "type": "date", "subtype": "date_month_year", "month": 3, "year": 2026 } (months 1 to 12), { "type": "date", "subtype": "date_quarter_year", "quarter": 1, "year": 2026 }.
      • A relative period: { "type": "date", "subtype": "date_relative", "rangeType": "lastN", "rangeN": 3, "periodType": "months" }. rangeType is current, lastN or nextN; periodType is days, weeks, months, quarters or years, or completeDays through completeYears for whole periods only.
      • When type is categorical
        • type (categorical, required)
        • values (array of string or number, required)
        • operator (string): One of is, is_not, contains, doesnt_contain.
      • When type is date and subtype is date_range
        • type (date, required)
        • subtype (date_range, required)
        • startDate (string, required)
        • endDate (string, required)
      • When type is date and subtype is date_relative
        • type (date, required)
        • subtype (date_relative, required)
        • rangeType (string, required): One of current, lastN, nextN.
        • rangeN (number, required)
        • periodType (string, required): One of days, weeks, months, quarters, years, completeDays, completeWeeks, completeMonths, completeQuarters, completeYears.
      • When type is date and subtype is date_month_year
        • type (date, required)
        • subtype (date_month_year, required)
        • month (number, required)
        • year (number, required)
      • When type is date and subtype is date_quarter_year
        • type (date, required)
        • subtype (date_quarter_year, required)
        • quarter (number, required)
        • year (number, required)
      • When type is date and subtype is date_single
        • type (date, required)
        • subtype (date_single, required)
        • date (string, required)
      • When type is date and subtype is date_null
        • type (date, required)
        • subtype (date_null, required)
      • When type is number
        • type (number, required)
        • value (number, required)
      • When type is text
        • type (text, required)
        • value (string, required)
  • filters (array of object, required): The filters of the template report's syncs that the variants differ by, primary ones first in the order their values name a variant. Each variant holds its own value of each, applied to the syncs that read the filter's dashboard. Empty for a burst by parameters.
    • id (string, required): The filter's id. Use it as a key of filters in addBurstVariants.
    • name (string, required): The filter's name on its dashboard, as shown in Rollstack.
    • primary (boolean, required): Whether the filter names the variants: a variant added without a name is named after its primary filters' values, in order. A secondary filter only narrows what each variant shows.
    • valueType (string or null, required): The kind of value the filter takes, and so the type of a variant's value of it. null when Rollstack doesn't know the filter's editor: copy the shape of a variant's value instead. One of categorical, date, number, text.
  • variantCount (number, required): How many variants the burst has, including any you can't open.
  • appUrl (string (uri), required): Link that opens the burst in Rollstack.
  • createdAt (string (date-time), required): When the burst was created. listBursts returns the newest first.
  • updatedAt (string (date-time), required): When the burst's details last changed.