Download files with the MASV API

Download files directly from MASV’s private cloud infrastructure.

MASV makes the following downloads available:

• Each individual file that was uploaded as part of the package.
• A zip file for Microsoft Windows and Linux platforms.
• A zip file for macOS platforms.

Diagram source

sequenceDiagram
    participant Client
    participant API as MASV API
    participant Storage as Cloud Storage

    Client->>API: Get link info (link ID + secret)
    API-->>Client: Package ID + package token

    Client->>API: List files in Package
    API-->>Client: File list (IDs, names, sizes)

    loop For each file
        Client->>API: Get download URL (file ID)
        API-->>Client: Pre-signed download URL

        Client->>Storage: Download file (GET)
        Storage-->>Client: File data
    end

Step 1: Obtain package link information

The package link information can be obtained from the recipient’s email. The package information requires the link_id and secret. See the Links page for more details.

Method	Route
GET	/links/{link_id}

Headers

Name	Type	Required	Description
X-Link-Password	String	No	Sender-supplied password associated with the package

URL parameters

Name	Type	Required	Description
secret	String	Yes	Secret token associated with the download link

Request

curl -H "X-Link-Password: $PACKAGE_PASSWORD" \
  -X GET "https://api.massive.app/v1/links/$LINK_ID?secret=$SECRET"

Response

After a successful request, this endpoint returns 200 OK:

{
  "branding": {
    "primary_color": "#1DD4CA"
  },
  "expiry": "2019-02-13T21:33:50.944Z",
  "id": "01D2TMG9F5GHMHX8RWZ453VA35",
  "name": "MASV Package",
  "package_id": "01D2TMG9F0J6JD5SJ55NY27MXJ",
  "package_size": 28176354,
  "package_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "recipient_email": "someoneelse@masv.io",
  "sender_email": "someone@masv.io"
}

Note

The package_id and package_token are required to list the files associated with the package. Requests for packages containing greater than 10,000 files are rate limited to once every 5 seconds.

Step 2: Obtain file listing for the package

Method	Route
GET	/packages/{package_id}/files

Headers

Name	Type	Required	Description
X-Package-Token	String	Yes	Package token

URL parameters

Name	Type	Required	Description
package_id	String	Yes	Package ID obtained from step 1

Request

curl -H "X-Package-Token: $PACKAGE_TOKEN" \
  -X GET "https://api.massive.app/v1/packages/$PACKAGE_ID/files"

Response

After a successful request, this endpoint returns 200 OK:

[
  {
    "id": "01D2TMGA09VHKVW6G3MJH2EP57",
    "kind": "file",
    "last_modified": "0001-01-01T00:00:00.000Z",
    "name": "Hawaii_4_27Retina_L.jpg",
    "size": 14914472,
    "virus_detected": false
  },
  {
    "id": "01D2TMGZMRZNDWD3852NNASF4D",
    "kind": "zip_windows",
    "last_modified": "2019-02-03T21:34:13.655Z",
    "name": "windows.zip",
    "virus_detected": false
  },
  {
    "id": "01D2TMGZMSGYSXFB7MV5V9ZM0X",
    "kind": "zip_mac",
    "last_modified": "2019-02-03T21:34:13.657Z",
    "name": "mac.zip",
    "virus_detected": false
  }
]

Note

Files with virus_detected: true indicate that a virus has been detected and the file cannot be downloaded. A 403 status code is returned if an attempt is made to download it.

Step 3: Obtain download links for the files

Direct file download URLs are short-lived and not intended for sharing or publishing. They are designed to be used immediately following the request. Use the package download URL (https://get.massive.io/{link_id}?secret={secret}) for sharing, which is active until the package expires or is deleted.

If you are building a custom download page, call the MASV API to get the download URL on demand when the user starts the download. You can include an optional expiry parameter to request a specific time for the URL to become inactive, but this cannot exceed the earliest of the authenticated link expiry time or 7 days.

Method	Route
GET	/packages/{package_id}/files/{file_id}/download

Headers

Name	Type	Required	Description
X-Package-Token	String	Yes	Package token

URL parameters

Name	Type	Required	Description
package_id	String	Yes	Package ID obtained from step 1
file_id	String	Yes	File ID obtained from step 2
expiry	Date-time	No	Optional custom expiry time for the download URL. Format: ISO 8601

Request

curl -H "X-Package-Token: $PACKAGE_TOKEN" \
  -X GET "https://api.massive.app/v1/packages/$PACKAGE_ID/files/$FILE_ID/download"

Response

After a successful request, this endpoint returns 200 OK:

{
  "method": "GET",
  "url": "https://masv3-storage-stag-wdc.s3-accelerate.amazonaws.com/..."
}

Step 4: Download the file

Note

Direct file URLs should not be shared or published. See step 3 above for details.

Use the method and url from the previous step to download the file:

curl -X $METHOD "$URL" > /path/to/target/file