---
title: "Creates a share"
method: POST
path: "/shares"
tags: ["Shares"]
---

# Creates a share

`POST /shares`

Creates a new share object for the given path in your account. We support three types of shares:

  - A **shared folder** allows you to let outside parties access a folder in your account (including any files and nested subfolders) using just a link. Shared folders can be restricted; e.g. with an expiration date, password, download-only, etc. Shared folders are 'live'; if someone makes a change to a file in your shared folder, it will be immediately reflected in your account, and vice-versa.
  - A file **send** lets you send one or more files via an easy download link. File sends are different than shared folders because file sends are 'point in time' -- the recipient will get the files as you sent them. If you later make a change to the source file, it will not be updated for the recipient.
  - A **receive** folder lets you receive files into your account. You can either send users a link, or optionally [embed a customized form](/docs/account/05-file-sharing/05-upload-widget) on your website.
  
**How to send files from your computer using the API**:

In order to use the API to send files which are not already stored in your account, you'll need to follow a three-step process:

1. Use the [POST /shares](#operation/addShare) endpoint to set up your send, including password, recipients, expiration, etc. You must include **upload** among the permissions in the `accessMode` and set the `sendingLocalFiles` parameter to **true**. The response that is returned will include a "meta" attribute, which contains an **accessToken** attribute. This new access token is valid only for the send.
2. Use the [POST /resources/upload](#operation/uploadFile) endpoint to upload your files to the send you've created. The "/" path represents the root of the share, not your home directory. **You must send the access token that you received from the first step in the `ev-access-token` header**
3. Use the [POST /shares/complete-send/{id}](#operation/completeDirectSend) endpoint to indicate that you have finished uploading files to your send. This will trigger the system to remove the **upload** permission from the share and send any invitation emails you set up in the first step of the process. **You must send YOUR access token in the `ev-access-token` header, not the temporary access token**

**Setting the Share Permissions**

Only 5 different combinations of permissions are valid for the `accessMode` object:

- **Upload Only**: This allows share visitors to upload to a share but do nothing else to the contained files. To use this mode, set `upload` to **true** and all other permissions to **false**
- **Download Only**: This allows share visitors to download files from a share but do nothing else to the contained files. To use this mode, set `download` to **true** and all other permissions to **false**
- **Upload and Download**: This allows share visitors to upload new files to the share or download files within the share, but not make any other changes to the share contents. To use this mode, set `upload` and `download` to **true** and set both `modify` and `delete` to **false**
- **All but Delete**: This allows share visitors to make any changes to the contents of a share except deleting files. To use this mode, set `upload`, `download`, and `modify` to **true** and set `delete` to **false**
- **Full Access**: This allows share visitors to make any changes to the contents of a share. To use this mode, set all 4 permissions `upload`, `download`, `modify`, and `delete` to **true**

Any other combination of permissions provided as the `accessMode` will be rejected as a bad request.

**Notes:**

Authenticated user requires [share permission](/docs/account/04-users/00-introduction#managing-user-roles-and-permissions).

## Headers

- `ev-api-key` string, required
- `ev-access-token` string, required

## Request body

- object
  - `type` 'shared_folder' | 'receive' | 'send', required — The type of share to create. See above for a description of each.
  - `name` string, required — A name for the share. This will be visible on the page that recipients visit.
  - `resources` string[] — Array of resources for this share. See details on [how to specify resources](#section/Identifying-Resources) above. **shared_folder** and **receive** shares must have only one `resource`, which is a directory that does not have a current share attached. **send** shares may have multiple `resource` parameters. You can also leave this parameter null if you are planning to upload files to the send. If you are planning to upload files to the send that are not yet in your account, you will also need to call the [POST /shares/complete-send/{id}](#operation/completeDirectSend) endpoint to finish the send operation.
  - `accessMode` AccessMode — An object defining what a not-logged-in visitor can do with the share contents
    - `download` boolean — Whether share allows visitors to download
    - `upload` boolean — Whether share allows visitors to upload
    - `modify` boolean — Whether share allows visitors to rename or move contents.
    - `delete` boolean — Whether share allows visitors to delete contents
  - `embed` boolean — Whether this share can be embedded within a web page.
  - `recipients` object[] — People you want to invite to the share. **Note**: unless you also set the `messageSubject` and `messageBody` for the new share, invitation emails will not be sent to these recipients.
    - `type` string — What kind of email should be sent to this recipient. Valid choices are **direct** and **cc**
    - `email` string, email — Email address of person you are inviting to the share
  - `expiration` string, date-time — Expiration date for the share. If someone attempts to use the share after this date, they will receive an error that the share is not available.
  - `hasNotification` boolean — Whether delivery receipts should be sent.
  - `isPublic` boolean — Whether someone can visit the share without following a personalized recipient link.
  - `messageBody` string — The message to be included in email invitations for your recipients. Ignored if you have not also provided `recipients` and `messageSubject`
  - `notificationEmails` string[] — Emails that will receive delivery receipts for this share. `hasNotification` must be **true** for delivery receipts will be sent.
  - `password` string — Set a password for recipients to access the share. All recipients will use the same password.
  - `requireEmail` boolean — True if recipients must provide their email to view the share.
  - `messageSubject` string — Subject to use on emails inviting recipients to the share. Ignored if you have not also provided `recipients` and a `messageBody`
  - `fileDropCreateFolders` boolean — Only used for **receive** shares. If true, uploads will be automatically placed into sub-folders of the folder, named after the chosen field on your form.
  - `sendingLocalFiles` boolean — Use this only for **send** shares. Flag to indicate that you are going to upload additional files from your computer to the share. If this is **true**, you will also need to use the [POST /shares/complete-send/{id}](#operation/completeDirectSend) call to finish setting up your share after the files are uploaded.

## Response `201`

Successful operation

- ShareResponse — unresolved $ref

---

[API](https://skmtc.net/prismic/apis/exavault-api.md) · [All operations](https://skmtc.net/prismic/apis/exavault-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/prismic/exavault-api/revisions/a1bd874b5960/schema)