Uploads
MASV has two types of uploads (or packages sent):
- Team uploads: Packages sent to email recipients or that can be shared via a link.
- Portal uploads: Packages sent to a specific MASV Portal, not necessarily owned by the logged-in user.
Regardless of the type of upload, all uploads are managed in the same way -- the only difference is the way they're created. Each upload can be in one of the following states:
transferring: the upload is currently transferring (uploading) data.pausedthe upload is paused by the user.idle: the upload has finished uploading data, and can accept additional files or be finalized.complete: the upload has been finalized and the package has been sent to the desired destination, and the intended recipient(s) are notified.error: a fatal error was encountered and the upload had to stop. This might or might not be recoverable, depending on the type of error.
Attention
Please note that the uploader ignores the following files/directories because they tend to change during the upload process, which causes the upload to fail:
desktop.ini.DS_Store.fcpcache
Parameters
Common parameters
These parameters are supported by all uploads, regardless of type.
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
chunk-size |
Integer | No | 104857600 | Target chunk size for the upload. If set, it overrides the chunk-size flag from the server |
description |
String | No | "" |
Package description |
name |
String | No | N/A | Package name |
priority |
Integer | No | 0 | Upload priority. Higher values mean higher priority |
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
chunk_size |
Integer | No | 104857600 | Target chunk size for the upload. If set, it overrides the chunk-size flag from the server |
package_description |
String | No | "" |
Package description |
package_name |
String | No | N/A | Package name |
paths |
Array | Yes | N/A | Array of file/directory paths to include in the upload |
priority |
Integer | No | 0 | Upload priority. Higher values mean higher priority |
Parameters: Send as a shareable link
Includes all Common parameters.
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
delete-after |
Integer | No | N/A | Number of days to keep the package in MASV storage |
download-limit |
Integer | No | N/A | Default access limit for download links created for this package |
password |
String | No | N/A | Default password for download links created for this package |
tag-name |
String | No | N/A | Name of the package's tag. Will be created if it doesn't already exist. |
tag-id |
String | No | N/A | ID of an existing Package Tag |
team-id |
String | Yes | N/A | Team ID to associate with this upload |
teamspace-id |
String | No | N/A | Teamspace ID to associate with this upload. If not specified, the upload is associated with the entire Team. |
unlimited-storage |
Boolean | No | false | Enables unlimited storage for the package |
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
delete_after |
Integer | No | N/A | Number of days to keep the package in storage |
download_limit |
Integer | No | N/A | Default access limit for download links created for this package |
password |
String | No | N/A | Default password for download links created for this package |
tag |
Object | No | N/A | Tag object |
team_id |
String | Yes | N/A | Team ID to associate with this upload |
teamspace_id |
String | No | N/A | Teamspace ID to associate with this upload. If not specified, the upload is associated with the entire Team. |
unlimited_storage |
Boolean | No | false | Enables unlimited storage for the package |
Parameters: Send to email recipients
Includes all parameters supported by Send as a shareable link.
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
emails |
String | Yes | N/A | Comma separated list of email recipients of the package. e.g: '[email protected],[email protected]' |
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
recipients |
Array | Yes | N/A | Array of email recipients of the package |
Parameters: Send to Portal
Includes all Common parameters.
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
metadata |
String | No | N/A | Key-value pairs to submit as portal metadata following the format: key1=value1,key2=value2 |
password |
String | No | N/A | Portal access code; required for password-protected portals |
sender |
String | Yes | N/A | The sender's email address |
subdomain |
String | Yes | N/A | Target portal subdomain. For example, if the desired portal URL is https://acme.portal.massive.app, then the subdomain is acme |
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
access_code |
String | No | N/A | Portal access code; required for password-protected portals |
metadata |
Object | No | N/A | JSON key-value pairs to submit as portal metadata. e.g: { "key1": "value1", "key2": "value2" } |
sender_email |
String | Yes | N/A | The sender's email address |
subdomain |
String | Yes | N/A | Target portal subdomain. For example, if the desired portal URL is https://acme.portal.massive.app, then the subdomain is acme |
Send to email recipients
Team packages are meant to be sent to email recipients or shared as a download link. A valid user session is required to send a Team package.
Note
When an upload is initiated, MASV Agent will start uploading files immediately. After all files are completely uploaded, the upload will transition to idle state. In this state, the upload is not considered complete and the intended recipient(s) will not be notified. To finalize the upload and transition it to the complete state, see Finalize an upload.
The following command will create a Team upload and send it to two email recipients:
masv upload start email \
--emails='[email protected],[email protected]' \
--team-id=TEAM_ID \
--name="Optional package name" \
--description="Optional package description" \
--password="optional_download_password" \
/path/to/file/or/folder \
/path/to/another/file/or/folder
curl -X POST -H "Content-Type: application/json" http://localhost:8080/api/v1/uploads -d '{
"team_id":"TEAM_ID",
"paths":["/path/to/file/or/folder", "/path/to/another/file/or/folder"],
"package_name": "Optional package name",
"package_description": "Optional package description",
"recipients": ["[email protected]", "[email protected]"],
"password": "optional_download_password"
}'
See all supported parameters.
Generate a shareable link with the CLI
You can generate a shareable download link for Team uploads that can be shared with any desired recipient.
The following command will create a Team upload and immediately generate a shareable link for it:
masv upload start link \
--team-id=TEAM_ID \
--name="Optional package name" \
--description="Optional package description" \
--password="optional_download_password" \
/path/to/file/or/folder \
/path/to/another/file/or/folder
See all supported parameters.
If successful, MASV Agent will start an upload and output a shareable link to standard output. You can send this link to your recipients right away:
Upload 5c8b2cd9-55fc-4462-9c01-87f4df03814a started. Shareable link: https://get.massive.io/{LINK_ID}?secret={SECRET}
The link will become active as soon as the upload finalizes.
Generate a shareable link with the REST API
You can generate a shareable download link for Team uploads that can be shared with any desired recipient.
To create a link, the upload has to be in the complete state and the upload type should be team. Simply call:
curl -X POST -H "Content-Type: application/json" http://localhost:8080/api/v1/uploads/{UPLOAD_ID}/link
Optional fields can also be specified in the POST data while creating a link:
curl -X POST -H "Content-Type: application/json" http://localhost:8080/api/v1/uploads/{UPLOAD_ID}/link -d '{
"active": "true",
"access_limit": 10,
"email": "[email protected]",
"expiry": "2021-06-18T10:00:00Z",
"password": "PASSWORD",
}'
See all supported parameters.
MASV Agent will return a JSON object similar to the following:
{
"email": "[email protected]",
"expiry": "2020-12-31T23:59:59.999",
"locked": false,
"id": "01ECSWWC8R6J1N8Y46S094CRGT",
"secret": "dDaNpsSTqlRDnTBe"
}
To construct a download link from the information above, simply plug in the id and secret values from the response to the following URL: https://get.massive.app/{id}?secret={secret}
Initiate a Portal upload
MASV Agent can also upload packages to any MASV Portal. This functionality does not require a user session. Portal uploads can be done without first logging in.
Note
When an upload is initiated, MASV Agent will start uploading files immediately. After all files are completely uploaded, the upload will transition to idle state. In this state, the upload is not considered complete and the intended recipient(s) will not be notified. To finalize the upload and transition it to the complete state, see the "Finalize an upload" section below.
To create a portal upload:
masv upload start portal \
--subdomain=PORTAL_SUBDOMAIN \
--sender='[email protected]' \
--password="access code for the portal" \
--name="Optional package name" \
--description="Optional package description" \
/path/to/file/or/folder \
/path/to/another/file/or/folder
curl -X POST -H "Content-Type: application/json" http://localhost:8080/api/v1/portals/uploads -d '{
"subdomain":"PORTAL_SUBDOMAIN",
"sender_email":"[email protected]",
"paths":["/path/to/file/or/folder", "/path/to/another/file/or/folder"],
"access_code": "optional_access_code",
"package_name": "Optional package name",
"package_description": "Optionali package description"
}'
See all supported parameters.
Finalize an upload
When an upload has finished transferring all files (transitioned to the idle state), it can be finalized. After it is finalized, no more files can be added to the upload, and the upload is transitioned to the complete state. When an upload is complete, the intended package recipient(s) will be notified about the upload.
To finalize an upload:
masv upload finalize UPLOAD_ID
curl -X POST http://localhost:8080/api/v1/uploads/{UPLOAD_ID}/finalize
View upload status
As mentioned earlier, all uploads, regardless of their type, can be managed in the same way after they're created.
To list all uploads managed by masv-agent, use:
masv upload ls
curl -X GET http://localhost:8080/api/v1/uploads
In order to view the full details for a specific upload (including individual file states), use the following command:
masv upload status UPLOAD_ID
curl -X GET http://localhost:8080/api/v1/uploads/{UPLOAD_ID}
Manage uploads
MASV Agent will start uploading file data at the time of upload creation. Uploads can be paused and resumed, as well as deleted. After all files are transferred for a given upload, it will transition to the idle state.
To pause an upload:
masv upload pause UPLOAD_ID
curl -X POST http://localhost:8080/api/v1/uploads/{UPLOAD_ID}/pause
To pause all in-progress uploads:
masv upload pause all
curl -X POST http://localhost:8080/api/v1/uploads/pause
To resume a paused upload:
masv upload resume UPLOAD_ID
curl -X POST http://localhost:8080/api/v1/uploads/{UPLOAD_ID}/resume
To resume all paused uploads:
masv upload resume all
curl -X POST http://localhost:8080/api/v1/uploads/resume
To delete an upload:
masv upload rm UPLOAD_ID
curl -X DELETE http://localhost:8080/api/v1/uploads/{UPLOAD_ID}
Warning
Please note that deleting a complete upload does not automatically delete the package from MASV's cloud storage, and it may still incur download or storage charges. To delete a package, see our API documentation
To delete all uploads, regardless of state:
masv upload rm all
curl -X DELETE http://localhost:8080/api/v1/uploads
To delete all uploads of a particular state ("paused", "transferring", "complete", "error"), specify the states as a url parameter:
curl -X DELETE http://localhost:8080/api/v1/uploads?states=complete
The states value is a comma separated list, so users can delete uploads of multiple states with the same command:
curl -X DELETE http://localhost:8080/api/v1/uploads?states=complete,transferring