Create burst
- OpenAPI 3.1.0 document: https://api.rollstack.com/public/v1/openapi.json
- The whole reference in Markdown: https://docs.rollstack.com/llms-full.txt
- An index of the reference: https://docs.rollstack.com/llms.txt
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 itsidfromlistReports. 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 theiridfromgetReportParameters, in the order their values name a variant. Each must beburstablethere. 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 theiridfromlistReportSyncFilters, 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 theiridfromlistReportSyncFilters. 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 driveparentFolderIdis 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,EMEAin a burst namedRegional Review:suffixgivesRegional Review - EMEA,prefixgivesEMEA - Regional Review, andsameNamegivesEMEA. It applies to variants added from then on. Defaults tosuffix. One ofsameName,prefix,suffix.
Response 201
Success
application/json
id(string, required): Unique identifier for the burst. Pass it asidto 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 unlessvariantNamingissameName.folderId(string or null, required): The folder the burst is in, by itsidinlistFolders.nullwhen 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 theiridinlistMembers.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 itsidforgetReportand 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.nullif 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,EMEAin a burst namedRegional Review:suffixgivesRegional Review - EMEA,prefixgivesEMEA - Regional Review, andsameNamegivesEMEA. It applies to variants added from then on. One ofsameName,prefix,suffix.kind(string, required): What the variants differ by.parameters: report parameters of a Rollstack report, listed inparametersand set withparametersinaddBurstVariants.filters: filters of an older report's syncs, such as a Google Slides or PowerPoint file, listed infiltersand set withfiltersinaddBurstVariants. One ofparameters,filters.reportType(string, required): The type of report the burst copies, astypeinlistReports:SlideDeckfor a Rollstack report, which bursts byparameters, any other type for an older report, which bursts byfilters. One ofGoogleDocs,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 byfilters.id(string, required): The report parameter's id on the template report. Use it as a key ofparametersinaddBurstVariants.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.nullwhen the template has none. A value of a report parameter, in the shape of its type. Copy the shape of the parameter'svalueinlistBursts, or of a variant's inlistBurstVariants:- A list of values:
{ "type": "categorical", "values": ["EMEA"] }, with at least one value.operatorcan also beis_not,containsordoesnt_contain; it isiswhen 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" }.rangeTypeiscurrent,lastNornextN;periodTypeisdays,weeks,months,quartersoryears, orcompleteDaysthroughcompleteYearsfor whole periods only. - When
typeiscategoricaltype(categorical, required)values(array of string or number, required)operator(string): One ofis,is_not,contains,doesnt_contain.
- When
typeisdateandsubtypeisdate_rangetype(date, required)subtype(date_range, required)startDate(string, required)endDate(string, required)
- When
typeisdateandsubtypeisdate_relativetype(date, required)subtype(date_relative, required)rangeType(string, required): One ofcurrent,lastN,nextN.rangeN(number, required)periodType(string, required): One ofdays,weeks,months,quarters,years,completeDays,completeWeeks,completeMonths,completeQuarters,completeYears.
- When
typeisdateandsubtypeisdate_month_yeartype(date, required)subtype(date_month_year, required)month(number, required)year(number, required)
- When
typeisdateandsubtypeisdate_quarter_yeartype(date, required)subtype(date_quarter_year, required)quarter(number, required)year(number, required)
- When
typeisdateandsubtypeisdate_singletype(date, required)subtype(date_single, required)date(string, required)
- When
typeisdateandsubtypeisdate_nulltype(date, required)subtype(date_null, required)
- When
typeisnumbertype(number, required)value(number, required)
- When
typeistexttype(text, required)value(string, required)
- A list of values:
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 byparameters.id(string, required): The filter's id. Use it as a key offiltersinaddBurstVariants.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 anameis 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 thetypeof a variant's value of it.nullwhen Rollstack doesn't know the filter's editor: copy the shape of a variant's value instead. One ofcategorical,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.listBurstsreturns the newest first.updatedAt(string (date-time), required): When the burst's details last changed.