Folders
- 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
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 asfolderIdtolistReportsto list the reports in it, or tocreateReportorupdateReportto 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.nullfor 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.viewlets you open the reports in it,editalso lets you change them, andmanagealso 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 givesmanage.nullwhen 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 ofview,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 itsidfromlistFolders: one you own or havemanageon. Omit it or passnullto 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.nullfor a folder at the top level.permission(string or null, required): What you can do in the folder:view,editormanage, as inlistFolders.managewhen you own it.nullwhen you see it only because a report in it is shared with you. One ofview,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 theiridinlistMembers.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 hasmanage. One ofview,edit,manage.source(string, required):ownerfor the member who owns the folder,directwhen it is shared with them,folderwhen they reach it through a folder it is nested in, whichunshareFolderon this folder leaves as it is. One ofowner,direct,folder.folder(string): Withfolder: 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 itsidfromlistFoldersorcreateFolder.
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.nullfor a folder at the top level.permission(string or null, required): What you can do in the folder:view,editormanage, as inlistFolders.managewhen you own it.nullwhen you see it only because a report in it is shared with you. One ofview,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 theiridinlistMembers.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 hasmanage. One ofview,edit,manage.source(string, required):ownerfor the member who owns the folder,directwhen it is shared with them,folderwhen they reach it through a folder it is nested in, whichunshareFolderon this folder leaves as it is. One ofowner,direct,folder.folder(string): Withfolder: 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 itsidfromlistFoldersorcreateFolder.
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 itsidfromlistFolders, one you own or havemanageon, and not the folder itself or one nested in it. Passnullto 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.nullfor 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 itsidfromlistFoldersorcreateFolder.
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 itsidfromlistFoldersorcreateFolder.userId(integer, required): The member to share the folder with, or to unshare it from: theiridfromlistMembers, which only owners and admins can call, or theiruserIdinaccessfromgetFolder. 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.viewlets them open its reports,editalso lets them change them, andmanagealso 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 ofview,edit,manage.
Response 200
Success
application/json
userId(number, required): The member the folder is now shared with: theuserIdfrom the path.permission(string, required): What the member can now do with the folder: thepermissionyou sent. One ofview,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 itsidfromlistFoldersorcreateFolder.userId(integer, required): The member to share the folder with, or to unshare it from: theiridfromlistMembers, which only owners and admins can call, or theiruserIdinaccessfromgetFolder. 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