Uploads

MASV has two types of uploads (or packages sent):

Team uploads: Packages sent to email recipient or packages 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.
paused the 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 while upload is running which would cause the upload to fail:

desktop.ini
.DS_Store
.fcpcache

Initiate sending a team package

Team packages are packages that are meant to be sent to email recipient or shared as a download link. A valid user session is required to initiate sending a team package.

Note

When an upload is initiated, the agent will start uploading files immediately. Once 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.

The following command will create a team upload:

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"
}'

Where:

team_id is the ID of a team that the currently logged-in user belongs to, from which the package will be sent.
paths is an array of files or directories paths to be sent. Paths should be absolute. For directories, the agent will traverse them and automatically pick up all files inside.
recipients is an optional array of recipient emails.

The team_id parameter can be obtained by listing the teams to which the currently logged-in user belongs, simply by calling:

curl http://localhost:8080/api/v1/teams

If successful, the agent will respond with a JSON object that indicates the newly created upload_id that can be used to query or modify the upload state.

Initiate a portal upload

The 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, the agent will start uploading files immediately. Once 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:

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": "Optional package description"
}'

Where:

subdomain is the desired portal subdomain. For example, if the portal URL is https://acme.portal.massive.app, then the subdomain will be acme
sender_email is the sender's email address
paths is an array of files or directories paths to be sent. Paths should be absolute. For directories, the agent will traverse them and automatically pick up all files inside.
access_code is the portal access code if the portal was password-protected

If successful, the agent will respond with a JSON object that indicates the newly created upload upload_id that can be used to query or modify the upload state.

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:

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, call:

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 request:

curl -X GET http://localhost:8080/api/v1/uploads/{UPLOAD_ID}

Manage uploads

The agent will start uploading file data at the time of upload creation. Uploads can be paused and resumed, as well as deleted. Once all files are transferred for a given upload, it will transition to the idle state.

To pause an upload:

curl -X POST http://localhost:8080/api/v1/uploads/{UPLOAD_ID}/pause

To resume a paused upload:

curl -X POST http://localhost:8080/api/v1/uploads/{UPLOAD_ID}/resume

To delete an upload, regardless of what state it was in:

curl -X DELETE http://localhost:8080/api/v1/uploads/{UPLOAD_ID}

To delete all uploads, regardless of state:

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

Create shareable links for team uploads

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",
}'

Where:

active is an optional field that can be used to created inactive links.
access_limit is the number of times that the generated link can be used to download the package.
email is the recipient email. If set, then the recipient email will be sent an email notification containing the download link. Note that the link secret is not returned to the user who created the link in this case, and the link will therefore only be usable by those with access to the specified email.
expiry is a date-time (RFC 3339, section 5.6) that specifies when the generated link will expire. The link expiry must be before the package expiry.
password is the password that downloaders will need to input when they attempt to start downloading from the generated link.

The 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}