Skip to content

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 finalized.
  • complete: the upload has been finalized and the package has been sent to the desired destination.
  • 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.

Send 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.

The following command will create a team upload:

curl -X POST -H "Content-Type: application/json" http://localhost:8080/api/v1/uploads -d '{
  "subdomain":"TEAM_SUBDOMAIN",
  "paths":["/path/to/file/or/folder", "/path/to/another/file/or/folder"],
  "package_name": "Optional package name",
  "package_description": "Optionali package description",
  "recipients": ["[email protected]", "[email protected]"],
  "password": "optional_download_password"
}'

Where:

  • subdomain is the subdomain of the 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.

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.

Upload a package to a portal

The agent can also upload packages to any MASV portal. This functionality does not require a user session since portal uploads do require login.

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": "Optionali 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.

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. Once all files are transferred for a given upload, it will transition to the idle state. It is up to you to finalize the upload and get the package delivered, by posting a finalize request to transition the upload to the complete state.

To pause an upload:

curl -X POST -H "Content-Type: application/json" http://localhost:8080/api/v1/uploads/{UPLOAD_ID}/pause

To resume a paused upload:

curl -X POST -H "Content-Type: application/json" http://localhost:8080/api/v1/uploads/{UPLOAD_ID}/resume

When an upload has finished transferring all files (transitioned to idle state), it can be finalized as follows:

curl -X POST -H "Content-Type: application/json" http://localhost:8080/api/v1/uploads/{UPLOAD_ID}/finalize

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

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

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

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}