Sharing
- 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
Who a report is shared with. Share a report with a member of the organization to let them view or edit it; they get an email. Sharing again with another permission changes it. batchShareReports shares up to 50 reports with the same members in one call, and emails each member once, listing the reports newly shared with them.
The owner always has access. getReport lists everyone the report is shared with, and getReportViews who opened it and how far they read.
Get report views
GET https://api.rollstack.com/public/v1/reports/{id}/views
Who opened a report and how they read it, as its editors see under Views in the app: each person's visits, time spent and whether they opened it since its last successful run, who it is shared with but hasn't opened it since, and how far into it people read, slide by slide. Editors' own time editing doesn't count. Only its editors may.
Requires the slide_decks:read scope.
Operation ID: getReportViews.
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/.
Response 200
Success
application/json
visits(number, required): How many times people opened the report to read it, editors' own edits left out. Visits a few minutes apart count as one, and ones under 5 seconds don't count.medianVisitSeconds(number or null, required): How long a visit lasts, as the median in seconds.nullwith no visits.lastUpdatedAt(string (date-time) or null, required): When the report's last successful run ended, whichopenedSinceUpdatecompares to.nullif it never ran.people(array of object, required): Who opened the report, the most recent first.user(object, required)id(number, required): The member's user id, the same as theiridinlistMembers.name(string, required): The member's name, as shown in Rollstack.
visits(number, required): How many times they opened it.seconds(number, required): How long they spent on it in all, in seconds.lastViewedAt(string (date-time), required): When they last had it open.openedSinceUpdate(boolean, required): Whether they opened it since its last successful run, so saw its latest numbers.
notOpened(array of object, required): The members it is shared with who haven't opened it since its last successful run, you left out.id(number, required): The member's user id, the same as theiridinlistMembers.name(string, required): The member's name, as shown in Rollstack.
slides(array of object, required): How far into the report people read, slide by slide.slideId(string, required): The slide, asslideIdingetReportContent.reach(number, required): The share of visits that reached the slide, from 0 to 1.medianSeconds(number or null, required): How long a visit stays on the slide, as the median in seconds.
Share report
PUT https://api.rollstack.com/public/v1/reports/{id}/shares/{userId}
Shares a report of any type with a member of the organization to view or edit it, or changes their permission. They get an email. A report that updates a file, such as a Google Slides presentation, also shares the file with them, as the app does.
Requires the slide_decks:write scope.
Operation ID: shareReport.
Path parameters
id(string, required): The report to act on, of anytype, by itsidfromlistReportsorcreateReport. You can also copy it from the report's link in Rollstack (appUrl): it's the part right after/slides/or/destinations/.userId(integer, required): The member to share the report with, or to unshare it from. Use theiridfromlistMembers, which only owners and admins can call, or theiruserIdinsharedWithfromgetReportif the report is already shared with them. You can share a report only with active members of the organization, and not with yourself. Anyone the report is shared with can unshare it from themselves, even withviewpermission.
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
permission(string, required): What the member can do with the report.viewlets them open, export and duplicate it.commentalso lets them add, reply to and resolve comments on its slides.editalso 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. If the report is already shared with the member, this replaces their permission and they aren't notified again. On a report that updates a file in Google Drive or OneDrive, Rollstack also shares the file with them, as the app does. One ofview,comment,edit.
Response 200
Success
application/json
userId(number, required): The member the report is now shared with: theuserIdfrom the path.permission(string, required): What the member can now do with the report: thepermissionyou sent. One ofview,comment,edit.
Unshare report
DELETE https://api.rollstack.com/public/v1/reports/{id}/shares/{userId}
Removes a user's share of a report of any type, and their access to its file when it updates one, as the app does.
Requires the slide_decks:write scope.
Operation ID: unshareReport.
Path parameters
id(string, required): The report to act on, of anytype, by itsidfromlistReportsorcreateReport. You can also copy it from the report's link in Rollstack (appUrl): it's the part right after/slides/or/destinations/.userId(integer, required): The member to share the report with, or to unshare it from. Use theiridfromlistMembers, which only owners and admins can call, or theiruserIdinsharedWithfromgetReportif the report is already shared with them. You can share a report only with active members of the organization, and not with yourself. Anyone the report is shared with can unshare it from themselves, even withviewpermission.
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
Share reports in a batch
POST https://api.rollstack.com/public/v1/reports/batch-share
Shares up to 50 reports of any type with the same members, with the same permission, as shareReport does for one. Each member gets one email listing the reports newly shared with them. Answers one result per report, each naming its id: a report you may not share fails on its own and the others are still shared, but a member who is not in the organization, or yourself, fails the whole call with nothing shared.
Requires the slide_decks:write scope.
Operation ID: batchShareReports.
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
ids(array of string, required): The reports to act on, of anytype, by theiridfromlistReports. From 1 to 50 ids; an id listed twice is acted on once.userIds(array of integer, required): The members to share every report with, by their useridfromlistMembers. Each must be an active member of the organization other than you, or the whole call fails with nothing shared. From 1 to 50 ids.permission(string, required): What the member can do with the report.viewlets them open, export and duplicate it.commentalso lets them add, reply to and resolve comments on its slides.editalso 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. If the report is already shared with the member, this replaces their permission and they aren't notified again. On a report that updates a file in Google Drive or OneDrive, Rollstack also shares the file with them, as the app does. One ofview,comment,edit.
Response 200
Success
application/json
results(array of object, required): One result per report, each naming itsid.- When
statusisdoneid(string, required): The report, by itsidfromids.status(done, required): The call succeeded on this report.result(array of object, required): The members the report is now shared with, one for each ofuserIds.userId(number, required): The member the report is now shared with: theuserIdfrom the path.permission(string, required): What the member can now do with the report: thepermissionyou sent. One ofview,comment,edit.
- When
statusisfailedid(string, required): The report, by itsidfromids.status(failed, required): The call failed on this report and changed nothing on it. The other reports are unaffected.error(object, required): Why this report failed, as the endpoint for one report would answer. Retry only these reports.code(string, required): A stable, machine-readable code for the error, such asapi-key-missing-scopeordata-validation-error. Use it, rather thanmessage, to handle specific errors in your code.message(string, required): A human-readable explanation of what went wrong, to log or show to people. When the request's path parameters, query or body are invalid (data-validation-error), it lists each invalid field by its path, with the problem, such asbody.emails.0: Invalid email address.statusCode(number, required): The HTTP status the same call on this report alone would answer, such as404or403.
- When