Create report parameter
- 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/reports/{id}/parameters
Creates a parameter of a report, linked to the dashboard filters and datasheet columns given, as the app's report parameters editor does. With a value, writes it into those filters, and as a row filter into those columns, and reads their datasheets again. Answers the parameter. Only the report's editors may.
Requires the slide_decks:write scope.
Operation ID: createReportParameter.
Path parameters
id(string, required): The report to act on, by itsidfromlistReportsorcreateReport. Only reports whosetypeisSlideDeckwork here: another type, such as a Google Slides presentation, returns400. You can also copy it from the report's link in Rollstack: it's the part right after/slides/.
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, required): The parameter's name, as shown in Rollstack. It can't be the name of another parameter of the report. Example:Region.filterIds(array of string (uuid)): The filters the parameter links, by theiridinfiltersfromgetReportParameters: its value is written into each, in every datasheet that reads its dashboard. Each must have noparameterIdyet. A burst can vary by the parameter only if one of them has avalueType, or it links a column. Defaults to[].columns(array of object): The columns the parameter links, bydatasheetIdandcolumnascolumnsingetReportParameterslists them: its value is written into each as a row filter, in that datasheet only. Each must have noparameterIdyet. The value'stypefollows the first filter'svalueType, or the first column'skindwhen it links no filter that can be set. Defaults to[].datasheetId(string (uuid), required): The datasheet's id, asdatasheetIdincolumnsfromgetReportParameters.column(string, required): The column's name, ascolumnincolumnsfromgetReportParameters.
value(object or null): The parameter's value, of thevalueTypeof the filters it links. When set, it is written into those filters and their datasheets are read again with it, so the report's slides change. Ifnullor omitted, as for a parameter a burst's variants will set, the filters keep their own values. 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.
Defaults to
null.- 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:
Response 201
Success
application/json
id(string, required): The report parameter's id. Pass it inparameterIdstocreateBurstwhenburstableistrue.name(string, required): The report parameter's name, as shown in Rollstack.value(object or null, required): The parameter's value, which the report's datasheets read through the filters it links.nullwhen it has none, and those filters keep their own values. 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:
columns(array of object, required): The columns of datasheets the parameter links: its value is written into each as a row filter, in that datasheet only. Empty when it links none.datasheetId(string, required): The datasheet's id, as inlistReportDatasheets.datasheetName(string or null, required): The datasheet's name, ornullif it has none.column(string, required): The column's name in the datasheet's source.kind(string, required): The kind of value that filters the column, and so thetypeof a parameter value that reaches it:categoricaltakes a list,numbera number anddatea date. One ofcategorical,number,date.isLinked(boolean, required):falseonce the column was unlinked in Rollstack: the parameter no longer writes into it.
burstable(boolean, required): Whether a burst can vary by the parameter: it links at least one filter whosevalueTypeisn'tnull, or at least one column that is still linked. A parameter that links neither can't be.runId(string or null, required): The run that reads again the datasheets the value was written into, asrunIdingetReportRun. When a run of the report is already going, it reads them after that run.nullwhen no value was written, or when you can't run the report.