Uploads

MASV Agent supports two types of uploads:

• Team uploads — Packages sent to email recipients or shared via a download Link. Requires a valid user session.
• Portal uploads — Packages sent to a specific MASV Portal. Does not require a user session.

All uploads are managed the same way after creation — only the creation step differs. Each upload transitions through these states:

State	Description
transferring	The upload is currently transferring data.
paused	The upload is paused by the user.
idle	The upload has finished transferring data and can accept additional files or be finalized.
complete	The upload has been finalized and the Package has been sent to the intended recipients.
error	A fatal error was encountered. This may or may not be recoverable depending on the error type.

Caution

MASV Agent ignores the following files because they tend to change during the upload process, which causes failures: desktop.ini, .DS_Store, .fcpcache.

Common parameters

These parameters are supported by all upload types.

CLI

Name	Type	Required	Default	Description
chunk-size	String	No	""	Custom chunk size for the upload. Overrides the server-level chunk-size flag.
description	String	No	""	Package description.
name	String	No	N/A	Package name.
priority	Integer	No	0	Upload priority. Higher values mean higher priority.

REST API

Name	Type	Required	Default	Description
chunk_size	Integer	No	104857600	Target chunk size for the upload. Overrides the server-level chunk-size flag.
package_description	String	No	""	Package description.
package_name	String	No	N/A	Package name.
paths	Array	Yes	N/A	Array of file or directory paths to include in the upload.
priority	Integer	No	0	Upload priority. Higher values mean higher priority.

---

Send to email recipients

Team Packages are sent to email recipients. A valid user session is required.

Note

When an upload is initiated, MASV Agent starts uploading files immediately. After all files are uploaded, the upload transitions to idle state. In this state, the intended recipients will not be notified. To finalize the upload and transition it to complete, see Finalize an upload.

CLI

masv upload start email \
  --emails='recipient1@domain.tld,recipient2@domain.tld' \
  --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

REST API

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": ["recipient1@domain.tld", "recipient2@domain.tld"],
    "password": "optional_download_password"
  }'

Email-specific parameters

Includes all Common parameters and the shareable Link parameters below.

CLI

Name	Type	Required	Description
emails	String	Yes	Comma-separated list of email recipients. Example: 'a@example.com,b@example.com'

REST API

Name	Type	Required	Description
recipients	Array	Yes	Array of email recipients of the Package.

---

Send as a shareable Link

Create a Team upload and generate a shareable download Link that can be shared with any recipient.

CLI

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

If successful, MASV Agent starts the upload and outputs a shareable Link:

Upload 5c8b2cd9-55fc-4462-9c01-87f4df03814a started. Shareable link: https://get.massive.io/{LINK_ID}?secret={SECRET}

The Link becomes active as soon as the upload finalizes. You can create additional shareable Links for existing uploads:

masv upload link {UPLOAD_ID}

REST API

To create a Link, the upload must be in the complete state and the upload type must be team:

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

Optional fields can be specified in the POST body:

curl -X POST -H "Content-Type: application/json" \
  http://localhost:8080/api/v1/uploads/{UPLOAD_ID}/link -d '{
    "active": "true",
    "access_limit": 10,
    "email": "recipient@domain.tld",
    "expiry": "2021-06-18T10:00:00Z",
    "password": "PASSWORD"
  }'

The response includes the Link ID and secret:

{
  "email": "me@domain.tld",
  "expiry": "2020-12-31T23:59:59.999",
  "locked": false,
  "id": "01ECSWWC8R6J1N8Y46S094CRGT",
  "secret": "dDaNpsSTqlRDnTBe"
}

Construct the download URL: https://get.massive.io/{id}?secret={secret}

Shareable Link parameters

Includes all Common parameters.

CLI

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

REST API

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.

---

Send to a Portal

MASV Agent can upload Packages to any MASV Portal. This does not require a user session.

Note

When an upload is initiated, MASV Agent starts uploading files immediately. After all files are uploaded, the upload transitions to idle state. In this state, the intended recipients will not be notified. To finalize the upload and transition it to complete, see Finalize an upload.

CLI

masv upload start portal \
  --subdomain=PORTAL_SUBDOMAIN \
  --sender='your-email@domain.tld' \
  --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

REST API

curl -X POST -H "Content-Type: application/json" \
  http://localhost:8080/api/v1/portals/uploads -d '{
    "subdomain": "PORTAL_SUBDOMAIN",
    "sender_email": "me@domain.tld",
    "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"
  }'

Portal-specific parameters

Includes all Common parameters.

CLI

Name	Type	Required	Default	Description
metadata	String	No	N/A	Key-value pairs to submit as Portal metadata: 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 Portal URL is https://acme.portal.massive.io, the subdomain is acme.

REST API

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. Example: { "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 Portal URL is https://acme.portal.massive.io, the subdomain is acme.

---

Finalize an upload

After all files in a Package are uploaded, the upload transitions to the idle state and the Package is automatically finalized. Once finalized, no more files can be added, and the upload transitions to complete. When an upload is complete, the intended recipients are notified.

To disable auto-finalize, start the server with masv server start --auto-finalize=false, then finalize manually:

CLI

masv upload finalize UPLOAD_ID

REST API

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

---

View upload status

List all uploads managed by MASV Agent:

CLI

masv upload ls

REST API

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

View full details for a specific upload, including individual file states:

CLI

masv upload status UPLOAD_ID

REST API

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

---

Manage uploads

MASV Agent starts uploading file data at the time of upload creation. Uploads can be paused, resumed, and deleted.

Pause an upload

CLI

masv upload pause UPLOAD_ID

REST API

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

Pause all uploads

CLI

masv upload pause all

REST API

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

Resume an upload

CLI

masv upload resume UPLOAD_ID

REST API

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

Resume all uploads

CLI

masv upload resume all

REST API

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

Delete an upload

CLI

masv upload rm UPLOAD_ID

REST API

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

Caution

Deleting a complete upload does not automatically delete the Package from MASV cloud storage. It may still incur download or storage charges. To delete a Package, see the Packages API reference.

Delete all uploads

CLI

masv upload rm all

REST API

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

Delete uploads by state

curl -X DELETE http://localhost:8080/api/v1/uploads?states=complete,error

---

Next steps

• Downloads — Initiate, monitor, and manage file downloads.
• Automations — Set up automated download and upload workflows.
• Storage Gateway — Connect storage devices to MASV.