action exavault_add_share { label: "Creates a share" description: "Creates a new share object for the given path in your account. We support three types of shares:\n\n - 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.\n - 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.\n - 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.\n \n**How to send files from your computer using the API**:\n\nIn 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:\n\n1. 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.\n2. 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**\n3. 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**\n\n**Setting the Share Permissions**\n\nOnly 5 different combinations of permissions are valid for the `accessMode` object:\n\n- **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**\n- **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**\n- **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**\n- **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**\n- **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**\n\nAny other combination of permissions provided as the `accessMode` will be rejected as a bad request.\n\n**Notes:**\n\nAuthenticated user requires [share permission](/docs/account/04-users/00-introduction#managing-user-roles-and-permissions)." provider: exavault method: POST path: "/shares" encoding: json input: { type: "object" properties: { accessMode: { type: "object" description: "An object defining what a not-logged-in visitor can do with the share contents" properties: { delete: { type: "boolean" description: "Whether share allows visitors to delete contents" } download: { type: "boolean" description: "Whether share allows visitors to download" } modify: { type: "boolean" description: "Whether share allows visitors to rename or move contents." } upload: { type: "boolean" description: "Whether share allows visitors to upload" } } } embed: { type: "boolean" description: "Whether this share can be embedded within a web page." } "ev-access-token": { type: "string" } "ev-api-key": { type: "string" } expiration: { type: "string" format: "date-time" description: "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." } fileDropCreateFolders: { type: "boolean" description: "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. " } hasNotification: { type: "boolean" description: "Whether delivery receipts should be sent." } isPublic: { type: "boolean" description: "Whether someone can visit the share without following a personalized recipient link." } messageBody: { type: "string" description: "The message to be included in email invitations for your recipients. Ignored if you have not also provided `recipients` and `messageSubject`" } messageSubject: { type: "string" description: "Subject to use on emails inviting recipients to the share. Ignored if you have not also provided `recipients` and a `messageBody`" } name: { type: "string" description: "A name for the share. This will be visible on the page that recipients visit. " } notificationEmails: { type: "array" description: "Emails that will receive delivery receipts for this share. `hasNotification` must be **true** for delivery receipts will be sent." items: { type: "string" format: "email" } } password: { type: "string" description: "Set a password for recipients to access the share. All recipients will use the same password." } recipients: { type: "array" description: "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." items: { type: "object" properties: { email: { type: "string" format: "email" description: "Email address of person you are inviting to the share" } type: { type: "string" description: "What kind of email should be sent to this recipient. Valid choices are **direct** and **cc**" } } } } requireEmail: { type: "boolean" description: "True if recipients must provide their email to view the share." } resources: { type: "array" description: "Array of resources for this share. See details on [how to specify resources](#section/Identifying-Resources) above.\n\n**shared_folder** and **receive** shares must have only one `resource`, which is a directory that does not have a current share attached.\n\n**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.\n" items: { type: "string" } } sendingLocalFiles: { type: "boolean" description: "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." } type: { type: "string" description: "The type of share to create. See above for a description of each." enum: ["shared_folder", "receive", "send"] } } required: ["ev-access-token", "ev-api-key", "name", "type"] additionalProperties: false } output: { type: "object" description: "Response object for shares." properties: { data: { type: "object" description: "Object contains share properties." properties: { attributes: { type: "object" description: "Attributes of the share including the name, path and share recipients. " properties: { accessDescription: { type: "string" description: "Description of the share access rights." } accessMode: { type: "object" description: "An object defining what a not-logged-in visitor can do with the share contents" properties: { delete: { type: "boolean" description: "Whether share allows visitors to delete contents" } download: { type: "boolean" description: "Whether share allows visitors to download" } modify: { type: "boolean" description: "Whether share allows visitors to rename or move contents." } upload: { type: "boolean" description: "Whether share allows visitors to upload" } } } created: { type: "string" format: "date-time" description: "Timestamp of share creation." } embed: { type: "boolean" description: "True if share can be embedded." } expiration: { type: "string" description: "Expiration date of the share." } expired: { type: "boolean" description: "True if the share has expired." enum: [true, false] } fileDropCreateFolders: { type: "boolean" description: "Flag to show if separate folders should be created for each file upload to receive folder." enum: [true, false] } formId: { type: "integer" description: "ID of the form." } hasNotification: { type: "boolean" description: "True if share has notification." enum: [true, false] } hasPassword: { type: "boolean" description: "True if the share has password." enum: [true, false] } hash: { type: "string" description: "Share hash." } inherited: { type: "boolean" description: "True if share inherited from parent folder." enum: [true, false] } messages: { type: "array" description: "Array of invitation messages." items: { type: "object" properties: { body: { type: "string" description: "Share invitation message text." } created: { type: "string" format: "date-time" description: "Timestamp of message creation." } id: { type: "integer" format: "int32" description: "Message id." } modified: { type: "string" format: "date-time" description: "Timestamp of message modification." } shareId: { type: "integer" format: "int32" description: "ID of associated share" } subject: { type: "string" description: "Share invitation message subject." } userId: { type: "integer" format: "int32" description: "User ID who generated share invite" } } } } modified: { type: "string" format: "date-time" description: "Timestamp of share modification. Can be `null` if it wasn't modified." } name: { type: "string" description: "Share name." } ownerHash: { type: "string" description: "Share owner's hash." } paths: { type: "array" description: "Path to the shared resource in your account." items: { type: "string" } } public: { type: "boolean" description: "True if the share has a public url." enum: [true, false] } recipients: { type: "array" description: "Array of recipients." items: { type: "object" properties: { created: { type: "string" format: "date-time" description: "Timestamp of adding recipient to the share." } email: { type: "string" description: "Recipient email address." } hash: { type: "string" description: "Share hash." } id: { type: "integer" format: "int32" description: "ID of the recipient." } received: { type: "boolean" description: "Set to true if recipient has accessed the share. Note this is set to true when the recipient clicks the link to access the share; not when they download a file." enum: [true, false] } sent: { type: "boolean" description: "Set to true if invite email was sent; false otherwise." enum: [true, false] } shareId: { type: "string" description: "ID of the share that the recipoient belongs to." } type: { type: "string" description: "Type of the recipient." enum: ["owner", "direct"] } } } } requireEmail: { type: "boolean" description: "True if share requires email to access." } resent: { type: "string" format: "date-time" description: "Invitations resent date. Can be `null` if resent never happened." } status: { type: "integer" format: "int32" description: "Share activity status. Can be active (1) or deactivated (0)." enum: [0, 1] } trackingStatus: { type: "string" description: "Checks recipient received status and returns whether it's been received (`complete`,) partial received (`incomplete`,) or not received yet (`pending`.)" enum: ["complete", "incomplete", "pending"] } type: { type: "string" description: "Type of share." enum: ["shared_folder", "send", "receive"] } } } id: { type: "integer" format: "int32" description: "ID of the share." } relationships: { type: "object" description: "Message, owner, resource, and notification relationships of the share. " properties: { messages: { type: "array" items: { type: "object" properties: { data: { type: "object" properties: { id: { type: "integer" description: "ID of the message." } type: { type: "string" description: "Type is message. " enum: ["message"] } } } } } } notifications: { type: "array" items: { type: "object" properties: { data: { type: "object" properties: { id: { type: "integer" description: "ID of the notification. " } type: { type: "string" description: "Type is notification. " enum: ["notification"] } } } } } } owner: { type: "object" properties: { data: { type: "object" properties: { id: { type: "integer" description: "ID of the owner." } type: { type: "string" description: "Type is user." } } } } } resources: { type: "array" items: { type: "object" properties: { data: { type: "object" properties: { id: { type: "integer" format: "int64" description: "ID of the shared resource." } type: { type: "string" description: "Type is resource. " enum: ["resource"] } } } } } } } } type: { type: "string" description: "Type of the share. " enum: ["share"] } } } included: { type: "array" items: { type: "object" } } responseStatus: { type: "integer" description: "Http status code of the response." } } } }