Skip to main content

Folders

The folders that organize reports, as nested in the app. Each folder answers the permission the user has on it: view, edit or manage. Sharing a folder gives access to everything in it, including the folders nested in it.

Pass a folder id as folderId to list the reports in it, or to create or move a report into it. To file reports, create a folder with createFolder, then move each report into it with updateReport. Rename or move a folder with updateFolder, See who it is shared with in getFolder, and change it with shareFolder and unshareFolder.

List folders

GET https://api.rollstack.com/public/v1/folders

The folders the user can see, each with its parent, null at the top level, and the user's permission on it: null, view, edit or manage. Pass a folder's id as folderId to listReports or createReport, or to getFolder to see who it's shared with.

Requires the slide_decks:read scope.

Operation ID: listFolders.

Response 200

Success

application/json: array of object

  • id (string, required): Unique identifier for the folder. Pass it as folderId to listReports to list the reports in it, or to createReport or updateReport to put a report in it.
  • name (string, required): The folder's name, as shown in Rollstack.
  • parentFolderId (string or null, required): The folder this one is nested in. null for a folder at the top level. The parent is missing from the list when you can see this folder but not its parent.
  • permission (string or null, required): What you can do in the folder. view lets you open the reports in it, edit also lets you change them, and manage also lets you share the folder and change who has access to it. It is the highest of what the folder is shared with you directly and what you get from the folders it is nested in, where owning one of those gives manage. null when you own the folder and get nothing from a parent folder, as with a top-level folder you created: as its owner, you can do everything in it. One of view, edit, manage.

Create folder

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

Creates a folder owned by the user: at the top level, which only owners and admins of the organization may, or inside a folder the user owns or has manage on. Then file reports in it with updateReport's folderId, or create them there with createReport. Each call creates another folder, even with the same name.

Requires the slide_decks:write scope.

Operation ID: createFolder.

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 folder's name, as members will see it in Rollstack. Leading and trailing spaces are removed, and it can't be blank. Example: Q3 business reviews.
  • parentFolderId (string or null): The folder to create it in, by its id from listFolders: one you own or have manage on. Omit it or pass null to create it at the top level, which only owners and admins of the organization may. Example: a3d5e7f9-1b2c-4d6e-8f0a-1b2c3d4e5f6a.

Response 201

Success

application/json

  • id (string, required): Unique identifier for the folder.
  • name (string, required): The folder's name, as shown in Rollstack.
  • parentFolderId (string or null, required): The folder this one is nested in. null for a folder at the top level.
  • permission (string or null, required): What you can do in the folder: view, edit or manage, as in listFolders. manage when you own it. null when you see it only because a report in it is shared with you. One of view, edit, manage.
  • access (array of object, required): Everyone with access to the folder, the owner first.
    • userId (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.
    • email (string, required): The member's email address.
    • permission (string, required): What they can do in the folder. The owner has manage. One of view, edit, manage.
    • source (string, required): owner for the member who owns the folder, direct when it is shared with them, folder when they reach it through a folder it is nested in, which unshareFolder on this folder leaves as it is. One of owner, direct, folder.
    • folder (string): With folder: the name of the parent folder they reach it through, when you can see that folder.

Get folder

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

A folder the user can see, with its parent and everyone who has access to it: its owner, the members it is shared with directly, and those who reach it through the folder it is nested in, each with their permission.

Requires the slide_decks:read scope.

Operation ID: getFolder.

Path parameters

  • id (string, required): The folder to act on, by its id from listFolders or createFolder.

Response 200

Success

application/json

  • id (string, required): Unique identifier for the folder.
  • name (string, required): The folder's name, as shown in Rollstack.
  • parentFolderId (string or null, required): The folder this one is nested in. null for a folder at the top level.
  • permission (string or null, required): What you can do in the folder: view, edit or manage, as in listFolders. manage when you own it. null when you see it only because a report in it is shared with you. One of view, edit, manage.
  • access (array of object, required): Everyone with access to the folder, the owner first.
    • userId (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.
    • email (string, required): The member's email address.
    • permission (string, required): What they can do in the folder. The owner has manage. One of view, edit, manage.
    • source (string, required): owner for the member who owns the folder, direct when it is shared with them, folder when they reach it through a folder it is nested in, which unshareFolder on this folder leaves as it is. One of owner, direct, folder.
    • folder (string): With folder: the name of the parent folder they reach it through, when you can see that folder.

Update folder

PATCH https://api.rollstack.com/public/v1/folders/{id}

Renames a folder, or moves it into another folder or to the top level, with everything in it. Members of the folder it moves into get access to its reports. Needs manage on the folder, or owning it, and the same on the one it moves into. Answers the name and parent of the folder: getFolder gives who has access.

Requires the slide_decks:write scope.

Operation ID: updateFolder.

Path parameters

  • id (string, required): The folder to act on, by its id from listFolders or createFolder.

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): The folder's name, as members will see it in Rollstack. Leading and trailing spaces are removed, and it can't be blank. Example: Q3 business reviews.
  • parentFolderId (string or null): The folder to move it into, by its id from listFolders, one you own or have manage on, and not the folder itself or one nested in it. Pass null to move it to the top level. Its reports, bursts and subfolders move with it. Example: a3d5e7f9-1b2c-4d6e-8f0a-1b2c3d4e5f6a.

Response 200

Success

application/json

  • id (string, required): Unique identifier for the folder.
  • name (string, required): The folder's name, as shown in Rollstack.
  • parentFolderId (string or null, required): The folder this one is nested in. null for a folder at the top level.

Delete folder

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

Deletes a folder, as Delete in the app does: its reports, bursts and subfolders stay and show at the top level. Only its owner may.

Requires the slide_decks:write scope.

Operation ID: deleteFolder.

Path parameters

  • id (string, required): The folder to act on, by its id from listFolders or createFolder.

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 folder

PUT https://api.rollstack.com/public/v1/folders/{id}/shares/{userId}

Shares a folder and everything in it with a member of the organization, or changes their permission, as Share in the app does. A member new to the folder gets an email. Needs manage on the folder, or owning it.

Requires the slide_decks:write scope.

Operation ID: shareFolder.

Path parameters

  • id (string, required): The folder to act on, by its id from listFolders or createFolder.
  • userId (integer, required): The member to share the folder with, or to unshare it from: their id from listMembers, which only owners and admins can call, or their userId in access from getFolder. Only active members of the organization. Anyone the folder is shared with can unshare it from themselves.

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 folder and everything in it. view lets them open its reports, edit also lets them change them, and manage also lets them rename, move and share the folder and add folders to it. If the folder is already shared with the member, this replaces their permission and they aren't notified again. Rollstack also shares the files of its reports that update a Google Drive or OneDrive file with them, as the app does. One of view, edit, manage.

Response 200

Success

application/json

  • userId (number, required): The member the folder is now shared with: the userId from the path.
  • permission (string, required): What the member can now do with the folder: the permission you sent. One of view, edit, manage.

Unshare folder

DELETE https://api.rollstack.com/public/v1/folders/{id}/shares/{userId}

Removes a member's direct share of a folder, and their access to its reports' files in Drive unless they still reach the folder through a parent folder, as the app does. Access through a parent folder stays: unshare that folder instead. Needs manage on the folder, or owning it, except to unshare it from yourself.

Requires the slide_decks:write scope.

Operation ID: unshareFolder.

Path parameters

  • id (string, required): The folder to act on, by its id from listFolders or createFolder.
  • userId (integer, required): The member to share the folder with, or to unshare it from: their id from listMembers, which only owners and admins can call, or their userId in access from getFolder. Only active members of the organization. Anyone the folder is shared with can unshare it from themselves.

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