# Files API

This group covers Drive files and folders, their versions and sharing, and shared drives. The group also carries the caller's alerts, Inbox items and notifications. Every call acts as a person: send a personal access token, or an OAuth access token from a person's sign-in (scope `Volobox`). An integration app's own client secret is refused with `403` (`Volobox:Integrations:MemberConnectionRequired`). Paths, tokens and conventions are in [API overview](/docs/api-overview).

## Alerts

| Method | Path | Operation | Summary |
| --- | --- | --- | --- |
| GET | `/api/v1/alerts` | `files.alerts.getList` | Lists the alerts the caller is a recipient of, filtered and paged. |
| GET | `/api/v1/alerts/{id}` | `files.alerts.get` | Gets an alert the caller is a recipient of. |
| POST | `/api/v1/alerts/{id}/acknowledge` | `files.alerts.acknowledge` | Acknowledges an active alert for everyone it reaches. |
| POST | `/api/v1/alerts/{id}/snooze` | `files.alerts.snooze` | Snoozes an alert for the caller until a given time. |
| POST | `/api/v1/alerts/{id}/unsnooze` | `files.alerts.unsnooze` | Ends the caller's snooze of an alert. |
| POST | `/api/v1/alerts/seen` | `files.alerts.markSeen` | Marks alerts as seen by the caller. |

## Files and folders

| Method | Path | Operation | Summary |
| --- | --- | --- | --- |
| GET | `/api/v1/file-entry` | `files.fileEntry.getList` | Lists files and folders in a Drive view (My Drive, a shared drive, shared with me, recent, starred or trash) or in one folder, paged. |
| GET | `/api/v1/file-entry/{id}` | `files.fileEntry.get` | Gets a file or folder the caller can open. |
| DELETE | `/api/v1/file-entry/{id}` | `files.fileEntry.deletePermanently` | Permanently deletes a file or folder that is in Trash. |
| GET | `/api/v1/file-entry/{id}/breadcrumb` | `files.fileEntry.getBreadcrumb` | Gets the path of folders from the drive root down to a file or folder. |
| POST | `/api/v1/file-entry/{id}/copy` | `files.fileEntry.copy` | Copies a file to another folder or drive. A folder cannot be copied: move it instead. |
| GET | `/api/v1/file-entry/{id}/download-url` | `files.fileEntry.getDownloadUrl` | Gets a short-lived URL that downloads a file, or one of its versions. |
| POST | `/api/v1/file-entry/{id}/duplicate` | `files.fileEntry.duplicate` | Makes a copy of a file beside it under a new name. A folder cannot be duplicated. |
| GET | `/api/v1/file-entry/{id}/location` | `files.fileEntry.getLocation` | Gets which drive and folder a file or folder is in. |
| PUT | `/api/v1/file-entry/{id}/move` | `files.fileEntry.move` | Moves a file or folder to another folder or drive. |
| GET | `/api/v1/file-entry/{id}/preview-url` | `files.fileEntry.getPreviewUrl` | Gets a short-lived URL that shows a file, or one of its versions, inline in a browser. |
| PUT | `/api/v1/file-entry/{id}/rename` | `files.fileEntry.rename` | Renames a file or folder. |
| POST | `/api/v1/file-entry/{id}/restore` | `files.fileEntry.restore` | Restores a file or folder from Trash. |
| PUT | `/api/v1/file-entry/{id}/star` | `files.fileEntry.star` | Stars or unstars a file or folder for the caller. |
| POST | `/api/v1/file-entry/{id}/trash` | `files.fileEntry.trash` | Moves a file or folder to Trash. |
| GET | `/api/v1/file-entry/{id}/versions` | `files.fileEntry.getVersions` | Lists the stored versions of a file, newest first. |
| POST | `/api/v1/file-entry/{id}/versions/restore` | `files.fileEntry.restoreVersion` | Makes an earlier version of a file its current version. |
| POST | `/api/v1/file-entry/folder` | `files.fileEntry.createFolder` | Creates a folder in My Drive or a shared drive, at the root or under a parent folder. |
| GET | `/api/v1/file-entry/folder-tree` | `files.fileEntry.getFolderTree` | Gets the folder tree of the caller's My Drive or of a shared drive. |

Request bodies:

- `CreateFolderDto` (`createFolder`): requires `name` (string).

## File sharing

| Method | Path | Operation | Summary |
| --- | --- | --- | --- |
| GET | `/api/v1/file-entry/{fileEntryId}/share/members` | `files.fileEntry.share.getMembers` | Lists the people, groups and agents a file or folder is shared with, and their roles. |
| POST | `/api/v1/file-entry/{fileEntryId}/share/members` | `files.fileEntry.share.addOrUpdateMember` | Shares a file or folder with a person, group or agent, or changes the role of one it is already shared with. |
| DELETE | `/api/v1/file-entry/{fileEntryId}/share/members/{memberId}` | `files.fileEntry.share.removeMember` | Stops sharing a file or folder with a person, group or agent. |

## Inbox

| Method | Path | Operation | Summary |
| --- | --- | --- | --- |
| GET | `/api/v1/inbox` | `files.inbox.getList` | Lists the items waiting in the caller's Inbox, such as approvals and questions, filtered and paged. |
| POST | `/api/v1/inbox/{id}/dismiss` | `files.inbox.dismiss` | Dismisses an item from the caller's Inbox. |

## Shared drives

| Method | Path | Operation | Summary |
| --- | --- | --- | --- |
| GET | `/api/v1/shared-drive` | `files.sharedDrive.getList` | Lists the shared drives the caller can open. |
| POST | `/api/v1/shared-drive` | `files.sharedDrive.create` | Creates a shared drive with the caller as its admin. |
| GET | `/api/v1/shared-drive/{id}` | `files.sharedDrive.get` | Gets a shared drive the caller can open. |
| PUT | `/api/v1/shared-drive/{id}` | `files.sharedDrive.update` | Updates a shared drive the caller administers. |
| DELETE | `/api/v1/shared-drive/{id}` | `files.sharedDrive.delete` | Deletes a shared drive the caller administers. |
| GET | `/api/v1/shared-drive/{id}/members` | `files.sharedDrive.getMembers` | Lists the people, groups and agents that are members of a shared drive, and their roles. |
| POST | `/api/v1/shared-drive/{id}/members` | `files.sharedDrive.addOrUpdateMember` | Adds a person, group or agent to a shared drive, or changes the role of an existing member. |
| DELETE | `/api/v1/shared-drive/{id}/members/{memberId}` | `files.sharedDrive.removeMember` | Removes a member from a shared drive. |
| PUT | `/api/v1/shared-drive/{id}/star` | `files.sharedDrive.star` | Stars or unstars a shared drive for the caller. |
| GET | `/api/v1/shared-drive/for-user/{userId}` | `files.sharedDrive.getForUser` | Lists the shared drives a workspace member belongs to that the caller can also open. |

Request bodies:

- `CreateSharedDriveDto` (`create`): requires `name` (string).
- `UpdateSharedDriveDto` (`update`): requires `name` (string).

## Notifications

| Method | Path | Operation | Summary |
| --- | --- | --- | --- |
| GET | `/api/v1/user-notification` | `files.userNotification.getList` | Lists the caller's notifications, newest first, filtered and paged. |
| POST | `/api/v1/user-notification/{id}/mark-read` | `files.userNotification.markRead` | Marks one of the caller's notifications as read. |
| POST | `/api/v1/user-notification/mark-all-read` | `files.userNotification.markAllRead` | Marks all of the caller's notifications as read. |

## Example

`files.fileEntry.getList`: lists files and folders in a Drive view (My Drive, a shared drive, shared with me, recent, starred or trash) or in one folder, paged.

```bash title="curl"
curl -s "https://volobox.example.com/api/v1/file-entry?SkipCount=0&MaxResultCount=20" \
  -H "Authorization: Bearer $VOLOBOX_TOKEN"
```

`SkipCount` is how many items to skip and `MaxResultCount` how many to return. The answer carries `totalCount` and the page of `items`.
