Skip to main content

Uploaded files

Your own data, for the slides agent to build slides from: a CSV file sent as JSON, or an Excel workbook sent as a file, as with Upload files in the app. Uploaded files suit data that lives outside a connected BI tool or spreadsheet, such as an export from another system.

Upload a CSV file with createDataset, add it to a report with addReportDatasheets, then pass the datasheet id to the slides agent. Replace its content later and the reports built on it show the new data after their next run.

Upload a document, such as a brief or a report, with createDocument, then pass its id to the slides agent for it to read as context, as when you attach a document in the chat in the app.

Get an uploaded file

GET https://api.rollstack.com/public/v1/datasets/{id}

An uploaded CSV file or Excel workbook. A workbook comes with its sheets, the range each one uses and its named ranges: pass a sheet's id as sheetId to also read its cells as text, which shows where a table's header row is. Then add the sheet, or a range of it that starts at the header row, to a report with addReportDatasheets. Cells show what the workbook saved: nothing is recalculated.

Requires the slide_decks:read scope.

Operation ID: getDataset.

Path parameters

  • id (string, required): The uploaded file to read: the id returned by createDataset, or a datasheet's datasetId in listReportDatasheets. It can be any uploaded file of your organization, including one another member uploaded.

Query parameters

  • sheetId (string): A sheet of an uploaded workbook whose cells to read: one of the sheets[].id values of an earlier call. The answer's cells then holds them. Omit it to list the workbook's sheets only.
  • range (string): The cells to read from the sheet, in A1 notation without the sheet's name, such as A1:H40. Omit it to read from the start of the range the sheet uses. Only with sheetId. Example: A1:H40.

Response 200

Success

application/json

  • id (string, required): Unique identifier for the uploaded file. Pass it as id to replaceDataset and deleteDataset and, for a CSV file, as datasetId to addReportDatasheets to add it to a report.
  • name (string, required): The uploaded file's name: the name it was created with for a CSV file, or the workbook's file name for an Excel workbook, such as Q3 pipeline.xlsx. Replacing the file's content doesn't change it.
  • createdAt (string (date-time), required): When the file was uploaded. Replacing its content doesn't change it.
  • updatedAt (string (date-time), required): When the file's content was last replaced with replaceDataset, or when it was uploaded if it has never been replaced.
  • kind (string, required): What the uploaded file is. A csv file is added to a report whole. A workbook is added one sheet or range at a time. One of csv, workbook.
  • sheets (array of object or null, required): A workbook's sheets (tabs), in the order Excel shows them, hidden ones included. null for a CSV file.
    • id (string, required): Unique identifier for the sheet within the workbook. Pass it as sheetId to addReportDatasheets, with the file's id as datasetId.
    • title (string, required): The sheet's name, as shown on its tab in Excel.
    • hidden (boolean, required): Whether the sheet is hidden in Excel. A hidden sheet can still be read.
    • usedRange (string or null, required): The cells of the sheet that hold something, in A1 notation, such as A1:H40: what addReportDatasheets reads when you pass no range. It can start with title rows or hold several tables, so read its cells before adding it. null for an empty sheet.
  • namedRanges (array of object or null, required): A workbook's named ranges that lie on one of its sheets. null for a CSV file.
    • name (string, required): The named range's name in Excel.
    • sheetId (string, required): The sheet the named range is on: one of sheets[].id.
    • range (string, required): The cells the name stands for, in A1 notation. Pass it as range to addReportDatasheets.
  • cells (object or null, required): The cells of the sheet asked for with sheetId. null when no sheet was asked for.
    • sheetId (string, required): The sheet the cells were read from.
    • range (string, required): The cells asked for, in A1 notation.
    • rows (array of array of string, required): The cells as text, as Excel shows them, row by row from the top-left cell of range, with an empty string for an empty cell. At most 50 rows and 30 columns. Use them to find the row a table's header is on, then add the table with addReportDatasheets, starting its range at that row.
    • truncated (boolean, required): Whether range holds more rows or columns than rows shows. Read further with a range that starts lower.

Replace an uploaded file

PUT https://api.rollstack.com/public/v1/datasets/{id}

Replaces an uploaded CSV file's rows, or a workbook's content with a new .xlsx sent as multipart/form-data in the file field. It keeps its id, and a CSV is never replaced by a workbook or the other way round. Reports built on it show the new content after their next run or message to the slides agent. An invalid file leaves the current one in place, and a sheet or range the new workbook no longer has fails its datasheets' reads. Only the user who created it may. From an MCP client, send a workbook with createDatasetUpload and this file's id.

Requires the slide_decks:write scope.

Operation ID: replaceDataset.

Path parameters

  • id (string, required): The uploaded file to replace or delete: the id returned by createDataset. Only the user who uploaded the file can replace or delete it; for anyone else, the request fails with a 404, as if the file did not exist.

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

  • csv (string, required): The file's data, as CSV text: a header row naming the columns, then at least one row of data. With replaceDataset, it replaces the file's whole content, header included, and the uploaded file must be a CSV file. The header's names become the column names of the datasheets made from the file: a blank one becomes Column N, after the column's position, and a repeated one gets a _2, _3 suffix. Values can be separated by commas, semicolons or tabs, detected from the header row. At most 10 MB. Example: region,revenue EMEA,1200000 Americas,2400000.

multipart/form-data

  • file (string (binary), required): The Excel workbook to upload. With createDataset, it becomes a new uploaded file named after the file, such as Q3 pipeline.xlsx; with replaceDataset, it replaces the content of an uploaded workbook, which keeps its id and name. An uploaded workbook can't be added to a report with addReportDatasheets, which takes uploaded CSV files only. The file's name must end in .xlsx, and it can be at most 10 MB; legacy .xls, macro-enabled and password-protected workbooks are rejected.

Response 200

Success

application/json

  • id (string, required): Unique identifier for the uploaded file. Pass it as id to replaceDataset and deleteDataset and, for a CSV file, as datasetId to addReportDatasheets to add it to a report.
  • name (string, required): The uploaded file's name: the name it was created with for a CSV file, or the workbook's file name for an Excel workbook, such as Q3 pipeline.xlsx. Replacing the file's content doesn't change it.
  • createdAt (string (date-time), required): When the file was uploaded. Replacing its content doesn't change it.
  • updatedAt (string (date-time), required): When the file's content was last replaced with replaceDataset, or when it was uploaded if it has never been replaced.

Delete an uploaded file

DELETE https://api.rollstack.com/public/v1/datasets/{id}

Deletes an uploaded CSV file or workbook. Reports built on it keep what they last showed, and their datasheets fail on the next read. Only the user who created it may.

Requires the slide_decks:write scope.

Operation ID: deleteDataset.

Path parameters

  • id (string, required): The uploaded file to replace or delete: the id returned by createDataset. Only the user who uploaded the file can replace or delete it; for anyone else, the request fails with a 404, as if the file did not exist.

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.

Response 204

Success, no content

Get a link to upload a file

POST https://api.rollstack.com/public/v1/datasets/uploads

Answers a link to send a CSV file or an Excel workbook (.xlsx) to from a shell, as it is on disk, at most 10 MB: use it when the user gives you a file, in place of writing a CSV into createDataset, and for every workbook. Run the command it answers with the path of the file. The upload answers the uploaded file with its id, as createDataset does: add it to a report with addReportDatasheets, a workbook after reading its sheets with getDataset. With datasetId, the file replaces the content of that uploaded file. The link works for 10 minutes and for one file: a file that is refused uses it up, so ask for another. Without a shell, write the CSV into createDataset. At most 20 links a minute per user.

Requires the slide_decks:write scope.

Operation ID: createDatasetUpload.

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

  • datasetId (string): An uploaded file to replace the content of: its id from createDataset, or a datasheet's datasetId in listReportDatasheets. The file sent must be of its kind, a CSV for a CSV and a workbook for a workbook, and it keeps its id and name. Only the user who uploaded it may. Omit it to upload a new file.

Response 201

Success

application/json

  • uploadUrl (string, required): Where to send the file, as multipart/form-data in the file field, with no API key: the link is the permission, for one file. It answers the uploaded file as createDataset does, with its id.
  • command (string, required): A curl command that sends the file: replace PATH_TO_FILE with the file's path and run it in a shell. The file's name must end in .csv or .xlsx.
  • expiresAt (string (date-time), required): When the link stops working, 10 minutes after it was made.

Upload a document

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

Stores a document for the slides agent to read, such as a brief, a report or meeting notes, as when you attach one in the chat in the app: pass its id in documentIds on sendReportMessage. Over MCP, send the document's whole text as Markdown in text. Over REST, you can instead send the file as multipart/form-data in the file field: a .docx, .doc, .odt, .rtf, .pptx, .pdf, .txt or .md file of at most 100 MB and 100 pages, whose pages the agent can also look at. It joins your document library when you and your organization keep one.

Requires the slide_decks:write scope.

Operation ID: createDocument.

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 document's name, without an extension: it is stored as a Markdown file named after it. The slides agent and the app's chat show it. From 1 to 200 characters. Example: Q3 strategy brief.
  • text (string, required): The document's whole text, in Markdown: headings, lists and tables keep their structure for the agent. Send what the document says, not a summary of it. Example: `# Q3 strategy brief

    Revenue grew 12% in EMEA...`.

multipart/form-data

  • file (string (binary), required): The document to upload, stored under its file name. Its name must end in .docx, .doc, .odt, .rtf, .pptx, .pdf, .txt or .md, and it can be at most 100 MB and 100 pages.

Response 201

Success

application/json

  • id (string, required): Unique identifier for the document. Pass it in documentIds to sendReportMessage.
  • name (string, required): The document's file name, such as Q3 strategy brief.pdf.
  • pageCount (number or null, required): How many pages the document has, which the agent can look at. null for a text or Markdown file.

Upload a file

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

Stores a CSV for the slides agent to build slides from: a header row, then at least one data row, at most 10 MB. Add it to a report with addReportDatasheets. Over MCP the CSV is written into the tool call, so send large files to this REST endpoint instead. Or send an Excel workbook (.xlsx, at most 10 MB) as multipart/form-data in the file field: it is stored as it is, with all its sheets, formatting and charts, and the user picks its sheets and ranges for a report in the app's editor. Legacy .xls, macro-enabled and password-protected workbooks are rejected. A workbook is read as saved: formulas show their saved results, and nothing is recalculated. When you have the file and a shell, send the file itself with createDatasetUpload instead of writing it into the tool call. List the sheets of a workbook with getDataset, then add a sheet or a range of one to a report with addReportDatasheets.

Requires the slide_decks:write scope.

Operation ID: createDataset.

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): A name for the uploaded file, which its datasheet takes when you add the file to a report with addReportDatasheets. Leading and trailing spaces are removed, and a name containing a / keeps only its last part: exports/Q3 pipeline is stored as Q3 pipeline. From 1 to 255 characters. Example: Q3 pipeline.
  • csv (string, required): The file's data, as CSV text: a header row naming the columns, then at least one row of data. With replaceDataset, it replaces the file's whole content, header included, and the uploaded file must be a CSV file. The header's names become the column names of the datasheets made from the file: a blank one becomes Column N, after the column's position, and a repeated one gets a _2, _3 suffix. Values can be separated by commas, semicolons or tabs, detected from the header row. At most 10 MB. Example: region,revenue EMEA,1200000 Americas,2400000.

multipart/form-data

  • file (string (binary), required): The Excel workbook to upload. With createDataset, it becomes a new uploaded file named after the file, such as Q3 pipeline.xlsx; with replaceDataset, it replaces the content of an uploaded workbook, which keeps its id and name. An uploaded workbook can't be added to a report with addReportDatasheets, which takes uploaded CSV files only. The file's name must end in .xlsx, and it can be at most 10 MB; legacy .xls, macro-enabled and password-protected workbooks are rejected.

Response 201

Success

application/json

  • id (string, required): Unique identifier for the uploaded file. Pass it as id to replaceDataset and deleteDataset and, for a CSV file, as datasetId to addReportDatasheets to add it to a report.
  • name (string, required): The uploaded file's name: the name it was created with for a CSV file, or the workbook's file name for an Excel workbook, such as Q3 pipeline.xlsx. Replacing the file's content doesn't change it.
  • createdAt (string (date-time), required): When the file was uploaded. Replacing its content doesn't change it.
  • updatedAt (string (date-time), required): When the file's content was last replaced with replaceDataset, or when it was uploaded if it has never been replaced.