Drive & Office API
Bramble Drive: personal files and shared libraries, folders, uploads (small and resumable), sharing with people, groups and links, versions, the bin, search, the change feed Bramble Sync uses, public share links, and opening files in Bramble Office. Works with an API key.
- Address
https://<your-org>.brambleit.cloud/drive- Sign-in
- Signed-in session,
X-API-Key, or a Bramble app access token (Authorization: Bearer). - Address
https://<your-org>.brambleit.cloud/api- Sign-in
- Signed-in session,
X-API-Key, or a Bramble app access token (Authorization: Bearer). - Endpoints
- 80
- OpenAPI
- drive.json
- Guides
- How Drive & Office works
Where things are. Every file and folder is an item with a numeric id.
Endpoints that work in a folder take the folder as parent (or
parent_id) and the library as site (or site_id); leave both out for
the top of your personal files.
Roles. On a library or a shared item a person or group is a viewer,
editor or owner. Libraries that belong to a site in Bramble Sites are
managed by the site: change their members there.
Uploading. Files up to a few megabytes: POST /api/v2/upload with the
bytes as the body and the name in the query. Larger files: start a
resumable upload (POST /api/v2/uploads), send each part with
PUT /api/v2/uploads/:uid/parts/:n (any part can be retried), then
POST /api/v2/uploads/:uid/complete. When a name is taken, conflict
decides: rename (keep both) or replace (a new version).
Storage. Files count against the organisation's storage pool. When it's
full, uploads are refused with 507.
Resources
Browse & search
Folder listings, recent and starred files, what's shared with you and by you, search, your storage use, and finding people to share with.
| Method | Path | Summary |
|---|---|---|
| GET | /api/v2/me | Who you are and your Drive settings |
| GET | /api/v2/usage | Your storage use |
| GET | /api/v2/list | List a folder |
| GET | /api/v2/recent | Recent files |
| GET | /api/v2/starred | Starred items |
| GET | /api/v2/shared | Shared with you |
| GET | /api/v2/shared-by-me | Shared by you |
| GET | /api/v2/search | Search files and folders |
| GET | /api/v2/people | Find people and groups to share with |
Files & folders
One item: details, contents and thumbnails, rename, star, versions, activity, and sharing (people, groups and links). Plus creating folders, moving, copying and downloading several items as a zip.
| Method | Path | Summary |
|---|---|---|
| GET | /api/v2/items/:id | Get an item |
| GET | /api/v2/items/:id/content | Download a file |
| GET | /api/v2/items/:id/thumb | A file's thumbnail |
| PATCH | /api/v2/items/:id | Rename an item |
| POST | /api/v2/items/:id/star | Star or unstar an item |
| GET | /api/v2/items/:id/versions | A file's versions |
| POST | /api/v2/items/:id/versions/:vid/restore | Restore an older version |
| DELETE | /api/v2/items/:id/versions/:vid | Delete an older version |
| GET | /api/v2/items/:id/activity | An item's activity |
| GET | /api/v2/items/:id/sharing | Who an item is shared with |
| POST | /api/v2/items/:id/sharing/grants | Share an item with a person or group |
| PATCH | /api/v2/items/:id/sharing/grants/:gid | Change someone's access to an item |
| DELETE | /api/v2/items/:id/sharing/grants/:gid | Stop sharing an item with someone |
| POST | /api/v2/items/:id/sharing/links | Create a share link |
| DELETE | /api/v2/items/:id/sharing/links/:lid | Delete a share link |
| POST | /api/v2/items/:id/keep | Keep a file out of the bin's automatic clean-up |
| POST | /api/v2/folders | Create a folder |
| POST | /api/v2/folders/ensure | Make sure a folder path exists |
| POST | /api/v2/move | Move items |
| POST | /api/v2/copy | Copy items |
| GET | /api/v2/zip | Download items as a zip |
Uploading
Small uploads in one request, resumable uploads in parts, and checking which names already exist.
| Method | Path | Summary |
|---|---|---|
| POST | /api/v2/uploads/check | Which of these names already exist in a folder (so the client can ask "replace or keep both" before uploading) |
| POST | /api/v2/upload | Upload a small file |
| POST | /api/v2/uploads | Start a resumable upload |
| GET | /api/v2/uploads/:uid | Which parts of an upload have arrived |
| PUT | /api/v2/uploads/:uid/parts/:n | Send one part of an upload |
| POST | /api/v2/uploads/:uid/complete | Finish a resumable upload |
| DELETE | /api/v2/uploads/:uid | Abandon an upload |
Quick share
Upload files and get a share link in one step (they land in a "Quick share" folder).
| Method | Path | Summary |
|---|---|---|
| POST | /api/v2/quick-share | Quick share: start (where to upload), then finish (expiry + link) |
| POST | /api/v2/quick-share/:id | Change a quick share's link |
Bin
Deleted items stay in the bin for the organisation's retention period and can be restored.
| Method | Path | Summary |
|---|---|---|
| POST | /api/v2/trash | Move items to the bin |
| GET | /api/v2/trash | List the bin |
| POST | /api/v2/trash/:id/restore | Restore an item from the bin |
| DELETE | /api/v2/trash/:id | Delete an item for good |
| DELETE | /api/v2/trash | Empty the bin |
Libraries
Shared libraries and their members.
| Method | Path | Summary |
|---|---|---|
| GET | /api/v2/libraries | List libraries |
| POST | /api/v2/libraries | Create a library |
| GET | /api/v2/libraries/:id | Get a library |
| PATCH | /api/v2/libraries/:id | Update a library |
| DELETE | /api/v2/libraries/:id | Delete a library |
| GET | /api/v2/libraries/:id/members | A library's members |
| PUT | /api/v2/libraries/:id/members | Add or change a library member |
| DELETE | /api/v2/libraries/:id/members/:type/:mid | Remove a library member |
Sync change feed
What Bramble Sync and the mobile apps use to stay in step: the spaces you can sync (personal files and libraries) and a change feed per space. Keep the cursor from each answer and pass it next time; wait long-polls until something changes.
| Method | Path | Summary |
|---|---|---|
| GET | /api/v2/sync/spaces | Spaces you can sync |
| GET | /api/v2/sync/changes | Changes in a space since a cursor |
Office editing
Opening Word, Excel and PowerPoint files in Bramble Office (needs the Docs, Sheets or Slides licence), creating new blank ones, and the start pages' recent files. The /wopi/... endpoints are how the editor reads and saves the file, each call carrying an access token Drive issued for that file; they're refused through the gateway.
| Method | Path | Summary |
|---|---|---|
| GET | /wopi/files/:id | File details for the editor (WOPI CheckFileInfo) |
| GET | /wopi/files/:id/contents | File contents for the editor (WOPI GetFile) |
| POST | /wopi/files/:id/contents | Save from the editor (WOPI PutFile) |
| POST | /wopi/files/:id | Other editor requests (WOPI) |
| GET | /api/v2/office/config | Which Office apps you can use |
| GET | /api/v2/office/recent | The Docs / Sheets / Slides start pages: that kind's files the person can reach (their drive, their libraries, shared with them), newest first |
| POST | /api/v2/office/:id/session | Opens a file in the editor: the URL to post to and the token to post |
| POST | /api/v2/office/new | A new blank Word document, spreadsheet or presentation in a folder |
Public share links
What someone with a share link sees, without signing in: the item (or folder listing), unlocking a password-protected link, downloading, and thumbnails.
| Method | Path | Summary |
|---|---|---|
| GET | /api/public/:token | Open a share link |
| POST | /api/public/:token/unlock | Unlock a password-protected share link |
| GET | /api/public/:token/content | Download from a share link |
| GET | /api/public/:token/thumb | Thumbnail from a share link |
Legacy v1 (BRM-API)
The original Drive endpoints in BRM-API, kept for older clients. Use /drive/api/v2.
| Method | Path | Summary |
|---|---|---|
| GET | /v1/app/drive/items | List items in a folder |
| GET | /v1/app/drive/recent | List the caller's 20 most recently updated files |
| GET | /v1/app/drive/search | Search the caller's items by name |
| GET | /v1/app/drive/quota | Get the caller's personal storage quota and usage |
| GET | /v1/app/drive/item/:id/path | Get the breadcrumb path to an item |
| POST | /v1/app/drive/folder | Create a folder. If parent_id is given it must be an existing, non-deleted item belonging to the caller's tenant |
| PATCH | /v1/app/drive/item/:id | Rename an item. Only affects items owned (created_by) by the caller |
| POST | /v1/app/drive/item/:id/move | Move an item into a different folder |
| DELETE | /v1/app/drive/item/:id | Move an item to trash |
| GET | /v1/app/drive/trash | List the caller's trashed items |
| POST | /v1/app/drive/trash/restore/:id | Restore an item out of trash |
| POST | /v1/app/drive/item/:id/share | Create a public share link for a file |
| GET | /v1/app/drive/item/:id/shares | List active share links for an item |
| DELETE | /v1/app/drive/share/:token | Revoke a share link. Only affects shares on items owned by the caller |
Web pages
These return pages for the browser rather than data.
GET /GET /edit/:idGET /office/:appGET /s/:tokenGET /shared/:token