Skip to main content

Sharing

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 its id from listReports or createReport. Only reports whose type is SlideDeck work here: another type, such as a Google Slides presentation, returns 400. 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. null with no visits.
  • lastUpdatedAt (string (date-time) or null, required): When the report's last successful run ended, which openedSinceUpdate compares to. null if 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 their id in listMembers.
      • 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 their id in listMembers.
    • 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, as slideId in getReportContent.
    • 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 any type, by its id from listReports or createReport. 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 their id from listMembers, which only owners and admins can call, or their userId in sharedWith from getReport if 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 with view permission.

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. view lets them open, export and duplicate it. comment also lets them add, reply to and resolve comments on its slides. edit also 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 of view, comment, edit.

Response 200

Success

application/json

  • userId (number, required): The member the report is now shared with: the userId from the path.
  • permission (string, required): What the member can now do with the report: the permission you sent. One of view, 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 any type, by its id from listReports or createReport. 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 their id from listMembers, which only owners and admins can call, or their userId in sharedWith from getReport if 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 with view permission.

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 any type, by their id from listReports. 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 user id from listMembers. 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. view lets them open, export and duplicate it. comment also lets them add, reply to and resolve comments on its slides. edit also 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 of view, comment, edit.

Response 200

Success

application/json

  • results (array of object, required): One result per report, each naming its id.
    • When status is done
      • id (string, required): The report, by its id from ids.
      • 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 of userIds.
        • userId (number, required): The member the report is now shared with: the userId from the path.
        • permission (string, required): What the member can now do with the report: the permission you sent. One of view, comment, edit.
    • When status is failed
      • id (string, required): The report, by its id from ids.
      • 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 as api-key-missing-scope or data-validation-error. Use it, rather than message, 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 as body.emails.0: Invalid email address.
        • statusCode (number, required): The HTTP status the same call on this report alone would answer, such as 404 or 403.