The MASV API - Go On, Give It A Try!

Welcome to the MASV API!

With our API you can interact with all the major features on the MASV Transfer Service. Some examples include automating uploads to our service, Monitoring Portals for new packages and triggering an automated download script to store files in on-prem storage or in your own cloud storage, and anything else you would like to do with it! Check out our API reference and guides for examples and feel free to reach out at any time if you have questions.

Guides    API Reference

MASV 3.0 API Guide

Getting Started

Welcome to the MASV transfer API.

Our API has been designed to help you automate or manually upload files to the MASV service through MASV’s “send files” or “portals” features.

You can also automate or manually download files from the MASV service to place deliveries into on-prem storage or push data into cloud storage

With the MASV transfer API, you can quickly automate sending or receiving packages without size limits or subscriptions. Deliveries expire after 10 days.

Use the MASV transfer API to:

  • Send files from point A to point B
  • Receive files from others
  • Set distribution lists and ‘teams’
  • Transfer up to 1TB or more, including folders, while preserving file structure
  • Transfers expire after 10 days

About MASV 3 API

MASV 3 was designed from the ground up with one goal in mind: API-first approach. All user interactions should translate to API calls - not necessarily one-to-one, as some actions could translate to multiple API calls depending on what the client needs to perform.

REST API

  • This API supports a Representational State Transfer (REST) model for accessing a set of resources through a fixed set of operations.
  • Use consistent HTTP verb to action mapping:
    • GET to read/list/view/search
    • POST to create/authenticate
    • PUT to update
    • DELETE to delete
  • Utilize JSON Web Token (JWT) for authentication and authorization for maximum scalability.
  • api.massive.app/v1/

Data Model

Users:

  • Represents a registered user.
  • Identified by an email.
  • Authenticated by a password.

Teams

  • Represents a “shared workspace” where multiple users can collaborate.
  • Each team can have multiple users (M-N relationship), called members
  • One user is the owner of the team.
  • Membership is governed by a role. Each member has a certain role in a team that gives them specific access privileges
  • All other data entities are related to the team (packages, portals, credit cards)
  • Each team has a unique subdomain.

Portals

  • Portals represent a website through which users can receive packages.
  • Each team can have multiple portals (1-N relationship).
  • Each portal has a unique subdomain.

Packages

  • A package represents a set of files sent by a team member (referred to as a MASV Rush) or received by a team portal (referred to as MASV Portals)
  • Each package can have multiple files.
  • Files metadata is stored at the API level, but actual file data is stored in a storage service.

Links

  • A link represents a package share (with a recipient).
  • Each package can have multiple links (1-N relationship).
  • The only way to download a package is by obtaining a link from one of the package owners.
  • Access to links can only by supplied out-of-band, meaning, no API call will ever expose the complete credentials to access the link and download the files through it.

API Deep-Dive

We’ll be using curl command line tool to demonstrate API interaction because it’s very verbose and exposes all aspects of the request.

A JSON Web Token (JWT) must be included on all requests other than the authorize request.

Note

The MASV API requires a Content-Type: application/json header on every POST and PUT request, otherwise you will receive an "Unsupported Content-Type" error.

Authorization: Login

When you or a user starts your app / script / etc, it/they will be required to login using the endpoint. The LOGIN will provide a User JSON Web Token (JWT) that will be required for user-related API calls.

POST /auth

To retrieve your JWT/Login, send a request with your email and password.

HEADERS

Name
Type
Required
Description

Content-Type

String

Yes

Must be application/json

BODY

Name
Type
Required
Description

email

String

Yes

Email address

password

String

Yes

Password

curl -H 'Content-Type: application/json' -s -X POST https://api.massive.app/v1/auth -d '{"email": "$EMAIL_ADDRESS", "password": "$PASSWORD"}'

Where:

  • $EMAIL_ADDRESS is the email address associated with your MASV account
  • $PASSWORD is the password associated with your MASV account

If you successfully authenticate, this endpoint will return an HTTP response with a status code of 200 and a body similar to the as the one below.

{
  "teams": [
    {
      "id": "01D377KWTJDPC8JQC6XVGPMHDW",
      "name": "Default Team",
      "subdomain": "a8fc91fa"
    }
  ],
  "token": "eyJhbGciOiJIUcI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE1NTQ0MDUzNjQsImV4dCI6e30sImltcCI6ZmFsc2UsInN1YiI6IjAxRDM5OEtXTjlBWEI3NkgyRUZONFcwOVFIIn0.DlqkZSTg68wQ9bjkZlcYigvb41owmPlRK2KJloiGUUw",
  "user": {
    "email": "api@masv.io",
    "id": "01D398ZWSXWS8YBZKXCW56BF4H",
    "level": "basic",
    "name": "MASV API",
    "time_zone": "EST"
  }
}

Where:

  • teams is an array of all teams the logged-in user belongs to
  • token is the auth token that is required for all user-related API calls. The token must be passed as a header value named X-User-Token with every request that requires a user token.
  • user is the logged in user info

Transfer: Upload

MASV clients upload files directly to a MASV’s third-party storage service provider (such as Microsoft Azure Blob Storage or Amazon AWS S3). The MASV API supplies authorized links to clients in order to carry out the uploads to these storage services. This is achieved by providing pre-signed URL’s for each specific service and abstracting the interaction needed for each step of the file upload process.

Upload transfers created through the APIs expire after 10 days. A transfer request consists of the endpoint itself, the headers, and the body, which can contain a message and must contain a list of file objects. Clients MUST supply the API with file metadata (name, modified date, path and size) while uploading the file contents to cloud storage.

Once the upload package has been finalized, the transfer is locked and cannot be further modified.

Packages and Authorization Mechanism

Each file uploaded to MASV cloud storage belongs to a package. A package can be created by interacting with a different API endpoint (for example, portals or teams). Once a package is created, the client obtains a package token that can be used to upload files for that specific package.

The package token must be passed with any requests going to the upload API endpoints by means of an HTTP header called X-Package-Token. This token gives the client full ownership over the package, so it can add/remove files from the package or remove the package entirely - until the package is finalized.

Lifecycle Of An Upload

When uploading single or multiple files as part of a package, the following steps generalizes the upload interaction:

  • Create package
  • For each file in the package
    • Add file to the package obtain storage request blueprint to create file in MASV’s third party storage service
    • Create the file in cloud storage
    • Collect metadata returned by the cloud storage service for the created file
    • Identify the number of chunks the file will be split up into
    • Obtain authorized URL’s to upload each chunk
    • Upload all chunks to cloud storage
    • Collect metadata returned by the cloud storage service for each uploaded chunk
    • Once all chunks are uploaded, send a request to API to finalize the file
  • Finalize package

Note

Once a file is finalized, no more chunks can be added to it and it cannot be modified.

Once a package is finalized, no more files can be added or deleted from the package. The package will be dispatched to the intended recipient immediately upon the finalize call.

MASV Blueprints

MASV’s API abstracts the interaction with cloud storage services by instructing the clients on which request they need to execute next during the file upload process. This abstraction is defined by a createBlueprint data structure, which holds all the information required to represent an HTTP request. Each blueprint has four properties (some optional):

  • url which is the URL to which the request should be forwarded. This includes the scheme, host, path and parameters
  • method which identifies the HTTP method type like GET, POST, PUT or DELETE
  • headers which is a key-value map of header names and their corresponding values that need to accompany the request
  • body is the request’s body

Upload API Interaction

1. Create a package (MASV Rush).

POST /teams/{team_id}/packages

HEADERS

Name
Type
Required
Description

X-User-Token

String

Yes

User JSON Web Token

Content-Type

String

Yes

Must be application/json

BODY

Name
Type
Required
Description

access_limit

String

No

Override default number of downloads for the package.

description

String

Yes

Description of the package.

name

String

Yes

Name of package.

password

String

No

Password to protect download access to the package.

recipients

Array Of Strings

Yes

Email address of recipient(s).

curl -H 'X-User-Token: $USER_TOKEN ' -H 'Content-Type: application/json' -s -X POST https://api.massive.app/v1/teams/$TEAM_ID/packages  -d '{“access_limit”:”$ACCESS_LIMIT”, "description":"$DESCRIPTION",   "name":"$NAME", “password”: "$PASSWORD", "recipients":["$R1_EMAIL”,”$R2_EMAIL”]}'

Where:

  • $USER_TOKEN is the auth token returned during auth request (refer to Authorization: Login section of this document)
  • $TEAM_ID is the team ID returned during auth request (refer to Authorization: Login section of this document)

After a successful request where a package has been created, this endpoint will return an HTTP response with a status code of 201 and a body similar to the one below.

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ8.eyJleHAiOjE1NTQzOTk4NzAsImltcCI6ZmFsc2UsImx2bCI6InUiLCJzdWIiOiIwMUQ3MlBFRTVBSDc0TlI5RUc0Q1pTMjlKVyIsInR5cCI6InBhY2thZ2UiLCJ1aWQiOiIwMUQzOThLV1NYV1M4WUJaS1hDVzU2QkY0SCJ9.ko0MKECmwu12LIQgyPOCAGx1WtaBPyhwcBdF41DdhvE",
  "completed": false,
  "created_at": "2019-03-28T17:44:30.122Z",
  "description": "Hello world",
  "expiry": "2019-04-07T17:44:30.122Z",
  "extras": {
    "storage_id": "aws-wdc"
  },
  "id": "01D72PEE5AH74NR9EG4CZS29JZ",
  "name": "Test package",
  "recipients": [
    "someone@someproductionhouse.com",
    "someoneelse@someproductionhouse.com "
  ],
  "updated_at": "2019-03-28T17:44:30.122Z",
  "usage_updated_at": "2019-03-28T17:44:30.122Z"
}

Note

Theidand the access_token as they are required to interact with the upload API.

2. Add a file to the package.

POST /packages/{package_id}/files

HEADERS

Name
Type
Required
Description

X-Package-Token

String

Yes

Package JSON Web Token

Content-Type

String

Yes

Must be application/json

BODY

Name
Type
Required
Description

kind

String

No

Type of file: file, directory. zip_mac, or zip_windows.

name

String

Yes

Filename (in the file system).

path

String

Yes

File's relative path.

last_modified

String

Yes

File’s last modified date in the file system (in UTC format).

File Example

For the following request we will use a specific file example:

  • Kind: file
  • Name: my_video.mpeg.
  • Path: Same as where the curl command is being executed.
  • Size: 210 MiB in size.
curl -H 'X-Package-Token: $PACKAGE_TOKEN ' -H 'Content-Type: application/json' -s -X POST https://api.massive.app/v1/pacakage/$PACKAGE_ID/files  -d '{“kind”:”file”, "name":"my_video.mpeg", “path”: "", "last_modified":"2018-12-17T16:14:34.450Z"}'

Where:

  • $PACKAGE_TOKEN is the access token obtained from Step 1
  • $PACKAGE_ID is the id obtained from Step 1

After a successful request where a file has been added to the package, this endpoint will return an HTTP response with a status code of 201 and a body similar to the one below.

{
  "storageType": "s3",
  "maxChunkSize": 5368709120,
  "maxChunksCount": 10000,
  "createBlueprint": {
    "headers": {
      "Content-Disposition": "attachment; filename=\"my_video.mpeg\"; filename*=UTF-8my_video.mpeg"
    },
    "method": "POST",
    "url": "https://masv3-storage-prod-wdc.s3-accelerate.amazonaws.com/01D3MNHA6P4XFXDMHJDTXT61CB/01D3MP8G3RBA7A1P0K98VEV2V3?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAJT7DTCC6DRVEACYQ%2F20190214%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20190214T002448Z&X-Amz-Expires=172799&X-Amz-SignedHeaders=host&uploads=&X-Amz-Signature=4bc45729a1e768a04b655f4a5972b548db1f8b359be16e719434bc5cc7ffd019"
  },
  "file": {
    "id": "01D3MP8G3RBA7A1P0K98VEV2V3",
    "last_modified": "2018-12-17T16:14:34.450Z",
    "name": "my_video.mpeg"
  }
}

Where:

  • storageType is the type of cloud storage service the file should be uploaded to. Currently this can be s3 or azure. The value of this property dictates the behaviour of metadata collection after each direct interaction with the storage.
  • maxChunkSize is the maximum allowed chunk size by the cloud storage service (in bytes)
  • maxChunkCount is the maximum number of chunks allowed for the file
  • createBlueprint is the request blueprint for creating the file in storage
  • file is the file metadata. Take note of the file.id value as it will be needed to interact later with the upload API.

3. Create the file in MASV’s cloud storage.

From Step 2, use the createBlueprint and construct a corresponding HTTP request based on the supplied information. For example, using the createBlueprint above, one can construct a curl request as follows:

curl -H "$BLUE_PRINT_HDR" -s -X $BLUE_PRINT_METHOD '$BLUE_PRINT_URL' 

Where:

  • $BLUE_PRINT_HDR is the headers value returned in create createBlueprint obtained in Step 2
  • $BLUE_PRINT_METHOD is the method value returned in create createBlueprint obtained in Step 2
  • $BLUE_PRINT_URL is the url value returned in create createBlueprint obtained in Step 2

The cloud storage service (in this case Amazon AWS S3) response will be similar to the following:

<?xml version="1.0" encoding="UTF-8"?>
<InitiateMultipartUploadResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
    <Bucket>masv3-storage-prod-wdc</Bucket>
    <Key>01D3MNHA6P4XFXDMHJDTXT61CB/01D3MP8G3RBA7A1P0K98VEV2V3</Key>
    <UploadId>Gng8Oh.yKzM41CmGxMRzHkO20GbP2RarZfTJVHHyPGqTVwrHHRgIZKqxMykJBjzDLZ9o3.pyYPwbVbtSI2LDOEa96Mllx6roowA47KHu2GkXcH6PC7qJTFDtYS38SwqI</UploadId>
</InitiateMultipartUploadResult>

Note

Data format in the response will be XML.

Note

Ensure to store uploadId from Step 3 as it is metadata required for interacting with the upload API methods related to this file.

4. Split up the file for upload (chunks).

To be able to upload a file, it must be split into parts and then each part will be uploaded to pre-signed URLs. These upload URLs are essentially limited access to a storage.
At this point, the client should decide on a chunking strategy for the file. The chunk size should not exceed the maxChunkSize from Step 2, and the total number of chunks per file should not exceed the maxChunkCount. MASV’s web and desktop client use a minimum chunk size of 100 MiB, which is adapted for larger files so the chunk count never exceeds maxChunkCount.

For our example file (which is 210MiB in size), we’ll use a 100MiB chunk size so it will be split up into three chunks (2x100MiB chunks and 1x10MiB chunk).

Chunking in and of itself does not have to be physical, but rather logical. The client just needs to decide on which byte range of the file belongs to each chunk. Depending on the environment, this might not be strictly possible, but most modern filesystems allow random read access to any file.
Please note that if the file is too small, then it will be uploaded as a single chunk file.  

5. Obtain upload urls (blueprints for chunks).

This endpoint is used to get pre-signed upload URLS for each of a file's parts. These upload URLs are essentially limited access to storage.

Note

Upload URLs are valid for a limited amount of time and must be re-requested if they expire.

The client can request upload urls in bulk which will save a lot of back-and-forth communication with the MASV API.

POST /packages/{package_id}/files/{file_id}

HEADER

Name
Type
Required
Description

X-Package-Token

String

Yes

Package JSON Web Token

Content-Type

String

Yes

Must be application/json

BODY

Name
Type
Required
Description

uploadId

String

Yes

ID for the initiated multi-part upload

QUERY

Name
Type
Required
Descriptiom

start

String

Integer 64

Starting index of the chunk.

count

String

Integer 64

Number of chunk requests to generate.

curl -H 'X-Package-Token: $PACKAGE_TOKEN ' -H 'Content-Type: application/json' -s -X POST https://api.massive.app/v1/pacakage/$PACKAGE_ID/files/$FILE_ID?start=$START&count=$COUNT  -d '{"uploadId":"$UPLOAD_ID”}’

Where:

  • $PACKAGE_ID is the id obtained from Step 1
  • $PACKAGE_TOKEN is the access token obtained from Step 1
  • $FILE_ID is the id obtained from Step 3
  • $START is the start index (zero-indexed) of the chunk
  • $COUNT is the number of chunk requests to generate
  • $UPLOAD_ID is the upload ID (uploadId) obtained from Step 4

Using our example, the client requires 3 blueprints (for the 3 chunks it’s trying to upload $START=0 and $COUNT=3).

The start and count parameters give clients control over how many bulk chunk requests they want to obtain. This is particularly useful for clients that do not know the total file size upfront (such as data streams for example).

The server will respond with an array of blueprints. The array size will be equal to the count parameter. The array elements are ordered so that the first blueprint should be used for chunk at index start, which is 0 in this case.

Continuing with our my_video.mpeg example, the output should be similar to the following:

[
  {
    "method": "PUT",
    "url": "https://masv3-storage-prod-wdc.s3-accelerate.amazonaws.com/01D3MNHA6P4XFXDMHJDTXT61CB/01D3MP8G3RBA7A1P0K98VEV2V3?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAJT7DTCC6DRVEACYQ%2F20190214%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20190214T011216Z&X-Amz-Expires=86399&X-Amz-SignedHeaders=host&partNumber=1&uploadId=Gng8Oh.yKzM41CmGxMRzHkO20GbP2RarZfTJVHHyPGqTVwrHHRgIZKqxMykJBjzDLZ9o3.pyYPwbVbtSI2LDOEa96Mllx6roowA47KHu2GkXcH6PC7qJTFDtYS38SwqI&X-Amz-Signature=a1ac9186728c3b45d21afc48a70d1535f7597b4f885b0c6ce8cafbbdcde72c72"
  },
  {
    "method": "PUT",
    "url": "https://masv3-storage-prod-wdc.s3-accelerate.amazonaws.com/01D3MNHA6P4XFXDMHJDTXT61CB/01D3MP8G3RBA7A1P0K98VEV2V3?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAJT7DTCC6DRVEACYQ%2F20190214%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20190214T011216Z&X-Amz-Expires=86399&X-Amz-SignedHeaders=host&partNumber=2&uploadId=Gng8Oh.yKzM41CmGxMRzHkO20GbP2RarZfTJVHHyPGqTVwrHHRgIZKqxMykJBjzDLZ9o3.pyYPwbVbtSI2LDOEa96Mllx6roowA47KHu2GkXcH6PC7qJTFDtYS38SwqI&X-Amz-Signature=fba71b0a4eaf033ac47c12aaaf310cba5f78280b75e44cb2176d9f3b0e64b794"
  },
  {
    "method": "PUT",
    "url": "https://masv3-storage-prod-wdc.s3-accelerate.amazonaws.com/01D3MNHA6P4XFXDMHJDTXT61CB/01D3MP8G3RBA7A1P0K98VEV2V3?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAJT7DTCC6DRVEACYQ%2F20190214%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20190214T011216Z&X-Amz-Expires=86399&X-Amz-SignedHeaders=host&partNumber=3&uploadId=Gng8Oh.yKzM41CmGxMRzHkO20GbP2RarZfTJVHHyPGqTVwrHHRgIZKqxMykJBjzDLZ9o3.pyYPwbVbtSI2LDOEa96Mllx6roowA47KHu2GkXcH6PC7qJTFDtYS38SwqI&X-Amz-Signature=0e6c68340af207d43efe23812e831ccc93a0f83a2bbf9ca0181051b9798cd6d8"
  }
]

6. Upload the file (in chunks).

Time to actually upload (chunks of) your file. With the chunk upload blueprints at hand, the client is now responsible for uploading each chunk by executing the corresponding request blueprint, but this time using the chunk binary data as request body.

curl -i -s -X $BLUE_PRINT_METHOD '$BLUE_PRINT_URL' –-data-binary @$FILE_CHUNK

Where:

  • $BLUE_PRINT_METHOD is the method value returned in createBlueprint obtained in Step 5
  • $BLUE_PRINT_URL is the url value returned in createBlueprint obtained in Step 5
  • $FILE_CHUNK is the file chunk to be uploaded

For example, to upload the chunks of our example file, we’ll have to execute three requests (one for each chunk). Note that the <() syntax is bash magic to read a byte range of a file without having to physically chunk it. Also, notice the -i flag for curl which prints out he response headers:

curl -i -s -X PUT 'https://masv3-storage-prod-wdc.s3-accelerate.amazonaws.com/01D3MNHA6P4XFXDMHJDTXT61CB/01D3MP8G3RBA7A1P0K98VEV2V3?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAJT7DTCC6DRVEACYQ%2F20190214%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20190214T011216Z&X-Amz-Expires=86399&X-Amz-SignedHeaders=host&partNumber=1&uploadId=Gng8Oh.yKzM41CmGxMRzHkO20GbP2RarZfTJVHHyPGqTVwrHHRgIZKqxMykJBjzDLZ9o3.pyYPwbVbtSI2LDOEa96Mllx6roowA47KHu2GkXcH6PC7qJTFDtYS38SwqI&X-Amz-Signature=a1ac9186728c3b45d21afc48a70d1535f7597b4f885b0c6ce8cafbbdcde72c72' --data-binary @<(dd if=my_video.mpeg skip=0 count=104857600 iflag=skip_bytes,count_bytes)
Content-Length: 0
Connection: keep-alive
x-amz-id-2: NgcsGsD8A5YSO+uNfp5plgERV1Y1uPuAAz2mHSQB++1g/MdNBYh6kXrK7zkVHzOxhzSmv4jAu1w=
x-amz-request-id: 65CAB8D270C820CB
Date: Thu, 14 Feb 2019 01:47:39 GMT
ETag: "7be1b3cc95a04a6dd07d157ad6fae64a"
Server: AmazonS3
X-Cache: Miss from cloudfront
Via: 1.1 56f9e0effaf2e1930aee6248ba70abb7.cloudfront.net (CloudFront)
X-Amz-Cf-Id: giSjIOdkcJ4qbIAcPBq--uItpHaRXb-8ER4YUjvQcx-yKTUOjNRQ4w==

Note

For each uploaded chunk, the following metadata must be collected:

  • partNumber which is part of the chunk upload request URL parameters
  • ETag which is returned as a response header by the storage service

7. Finalize the file.

Once all chunks have been uploaded, the client must tell the API that the file has been successfully uploaded to the cloud storage service and supply all collected metadata needed by the API to seal the file in storage.

This call informs your the MASV backend that all the uploading for your file is done.

POST /packages/{package_id}/files/{file_id}/finalize

HEADER

Name
Type
Required
Description

X-Package-Token

String

Yes

Package JSON Web Token

Content-Type

String

Yes

Must be application/json

BODY

Name
Type
Required
Description

chunkExtras

Array Of Objects

Yes

Information about all the chunks that make up the file.

Contains:

  • partNumber for chunk
  • etag that corresponds to the partNumber

fileExtras

Array Of Objects

Yes

Currently only required to provide the uploadId.

size

Integer 64

Yes

The total size of the file in bytes.

curl -H 'X-Package-Token: $PACKAGE_TOKEN ' -H 'Content-Type: application/json' -s -X POST https://api.massive.app/v1/pacakage/$PACKAGE_ID/files/$FILE_ID/finalize -d {“chunkExtras”:[{"partNumber": $CHUNK_PART_NUMBER, "etag": $CHUNK_ETAG}], “fileExtras”:[{“uploadId”: $UPLOAD_ID}], “size”: $FILE_SIZE}

Where:

  • $PACKAGE_ID is the id obtained from Step 1
  • $PACKAGE_TOKEN is the access token obtained from Step 1
  • $FILE_ID is the id obtained from Step 3
  • $UPLOAD_ID is the upload ID (uploadId) obtained from Step 4
  • chunkExtras is an array of metadata collected in Step 6, which corresponds to each chunk upload’s partNumber from request URL parameter and ETag header value from

Continuing with our specific, the request body would be:

{
  "size": 147778580,
  "fileExtras": {
    "uploadId": "Gng8Oh.yKzM41CmGxMRzHkO20GbP2RarZfTJVHHyPGqTVwrHHRgIZKqxMykJBjzDLZ9o3.pyYPwbVbtSI2LDOEa96Mllx6roowA47KHu2GkXcH6PC7qJTFDtYS38SwqI"
  },
  "chunkExtras": [
    {
      "partNumber": "1",
      "etag": "\"7be1b3cc95a04a6dd07d157ad6fae64a\""
    },
    {
      "partNumber": "2",
      "etag": "\"ca8e85fc588f90d07449d0303e9cf329\""
    },
    {
      "partNumber": "3",
      "etag": "\"a6a6aa6836a7a70c28a06dec02dbf199\""
    }
  ]
}

On success, the server will respond with an empty body and a 204 status code.

Note

The client has to repeat steps 2-7 for each additional file in the package.

8. Finalize the package.

Once all files have been uploaded, the client must indicate that the package has been completed and ready to be dispatched to the intended recipient.

This call informs that MASV backend that package is ready to be dispatched to the intended recipient. The package will be dispatched to the intended recipient immediately upon the finalize call.

POST /packages/{package_id}/finalize

HEADER

Name
Type
Required
Description

X-Package-Token

String

Yes

Package JSON Web Token

Content-Type

String

Yes

Must be application/json

curl -H 'X-Package-Token: $PACKAGE_TOKEN ' -H 'Content-Type: application/json' -s -X POST https://api.massive.app/v1/pacakage/$PACKAGE_ID/finalize

Where:

  • $PACKAGE_ID is the id obtained from Step 1
  • $PACKAGE_TOKEN is the access token obtained from Step 1

On success, the server will respond with an empty body and a 204 status code.

Transfer: Download

MASV clients download files directly from MASV’s third-party storage service provider (such as Microsoft Azure Blob Storage or Amazon AWS S3).
The following downloads will be 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 MAC OS platforms.

1. Obtain package link information.

The package link information can be obtained from the recipient email. The package information requires link id and secret.

GET /links/{link_id}

HEADER

Name
Type
Required
Description

X-Link-Password

String

No

Sender supplied password associated with the package.

QUERY

Name
Type
Required
Description

secret

String

Yes

Secret token associated with the download link.

curl -H 'X-Link-Password: $PACKAGE_PASSWORD' -X GET ‘https://api.massive.app/v1/links/$LINK_ID?secret=$SECRET
{
  "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.eyJleHAiOjE1NDk5ODQ2OTksImltcCI6ZmFsc2UsImxpZCI6IjAxRDJUTUc5RjVHSE1IWDhSV1o0NTNWQTM1IiwibHZsIjoiZCIsInN1YiI6IjAxRDJUTUc5RjBKNkpENVNKNTVOWTI3TVhKIiwidHlwIjoicGFja2FnZSJ9.aq1f0UpKDPac8fkdOlPV2_S2eYBKOh-wUydv-GBFXZw",
  "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.

2. Obtain file listing for the package.

GET /packages/{package_id}/files

HEADER

Name
Type
Required
Description

X-Package-Token

String

Yes

Package JSON Web Token

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

Where:

  • $PACKAGE_ID is the id obtained from Step 1
  • $PACKAGE_TOKEN is the access token obtained from Step 1
[
  {
    "id": "01D2TMGA09VHKVW6G3MJH2EP57",
    "kind": "file",
    "last_modified": "0001-01-01T00:00:00.000Z",
    "name": "Hawaii_4_27Retina_L.jpg",
    "size": 14914472
  },
  {
    "id": "01D2TMGA09RBKG9H29HVZPGSMX",
    "kind": "file",
    "last_modified": "0001-01-01T00:00:00.000Z",
    "name": "Hawaii_4_27Retina_R.jpg",
    "size": 13261882
  },
  {
    "id": "01D2TMGZMRZNDWD3852NNASF4D",
    "kind": "zip_windows",
    "last_modified": "2019-02-03T21:34:13.655Z",
    "name": "windows.zip"
  },
  {
    "id": "01D2TMGZMSGYSXFB7MV5V9ZM0X",
    "kind": "zip_mac",
    "last_modified": "2019-02-03T21:34:13.657Z",
    "name": "mac.zip"
  }
]

3. Obtain download links for the files in the package.

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

HEADER

Name
Type
Required
Description

X-Package-Token

String

Yes

Package JSON Web Token

curl -H 'X-Package-Token: $PACKAGE_TOKEN' -X GET ‘https://api.massive.app/v1/packages/$PACKAGE_ID/files/$FILES_ID/download’

Where:

  • $PACKAGE_ID is the id obtained from Step 1
  • $PACKAGE_TOKEN is the access token obtained from Step 1
  • $FILES_ID is the file id obtained from Step 2
{
  "method": "GET",
  "url": "https://masv3-storage-stag-wdc.s3-accelerate.amazonaws.com/01D2TMG9F0J6JD5SJ55NY27MXJ/01D2TMGA09VHKVW6G3MJH2EP57?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAJT7DTCC6DRVEACYQ%2F20190205%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20190205T152017Z&X-Amz-Expires=86399&X-Amz-SignedHeaders=host&x-custom_id=01D20E4YGW8D777N8X0FF2F78P&x-custom_imp=0&x-custom_link_id=01D2TMG9F5GHMHX8RWZ453VA35&x-custom_pkg_id=01D2TMG9F0J6JD5SJ55NY27MXJ&X-Amz-Signature=fbfa915207a87c17a5bcb56442d08e16bfc8dda55ca2310b797e14480bd81e5c"
}

4. Download the file.

curl-X $METHOD $URL

Where:

  • $METHODis the method obtained from Step 3
  • $URL is the url obtained from Step 3

Portals: Portal Creation

Authorized users can create portals under any team they belong to (subject to access policy).

POST /teams/{team_id}/portals

HEADERS

Name
Type
Required
Description

X-User-Token

String

Yes

User JSON Web Token

Content-Type

String

Yes

Must be application/json

BODY

Name
Type
Required
Description

'name'

String

Yes

Name of the portal to create

'subdomain'

String

Yes

Subdomain of the portal to create

'message'

String

No

Message displayed on the portal upload page

'access_code'

String

No

Access code to be able to access portal upload page

'has_access_code'

String

No

Enable/disable access code for portal page.

'active'

String

Yes

Enable/disable portal page

'logo_url'

String

No

URL for logo to be displayed on portal page

'background_url'

String

No

URL for background image of the portal page

'primary_color'

String

No

HTML hex code for primary color used on portal page

'recipients'

Array of Strings

Yes

Email(s) that will receive notifications for portal uploads

curl -H 'X-User-Token: $USER_TOKEN' -H 'Content-Type: application/json' -s -X POST https://api.massive.app/v1/teams/$TEAM_ID/portals -d '{"name": "$NAME", "message": "$MESSAGE", "subdomain": "$SUBDOMAIN", "recipients": ["$R1_EMAIL”,”$R2_EMAIL”], "access_code": "$ACCESSCODE"}'

Where:

  • $USER_TOKEN is the auth token returned during auth request (refer to Authorization: Login section of this document)
  • $TEAM_ID is the team ID returned during auth request (refer to Authorization: Login section of this document)

After a successful request where a portal has been created, this endpoint will return an HTTP response with a status code of 201 and a body similar to the one below.

{
  "active": true,
  "id": "01CTDNW11G67NKHQW5JE8TP2TJ",
  "message": "Hello world!",
  "name": "My portal",
  "recipients": [
    "test@gmail.com",
    "test@yahoo.com"
  ],
  "subdomain": "customesub"
}

Where id is the created portal ID.

Portals: Listing Portals

Authorized users can list all portals under any team they belong to (subject to access policy).

GET /teams/{team_id}/portals

HEADERS

Name
Type
Required
Description

X-User-Token

String

Yes

User JSON Web Token

curl -H 'X-User-Token: $USER_TOKEN'-s -X GET https://api.massive.app/v1/teams/$TEAM_ID/portals 

Where:

  • $USER_TOKEN is the auth token returned during auth request (refer to Authorization: Login section of this document)
  • $TEAM_ID is the team ID returned during auth request (refer to Authorization: Login section of this document)

After a successful request, this endpoint will return an HTTP response with a status code of 200 and a body similar to the one below.

[
    {
        "id": "01CNH24NGPTJTMXWWM2J8E2V8V",
        "message": "Hello world!",
        "name": "My portal",
        "subdomain": "myportal",
        "has_access_code": false,
        "recipients": [
            "test@gmail.com",
            "test@yahoo.com"
        ]
    },
    {
        "id": "01CNEM9H2AG0MVH33X0EVDY8AQ",
        "message": "Hello world, again!",
        "name": "My other portal",
        "subdomain": "myotherportal",
        "has_access_code": false,
        "recipients": [
            "test@snailmail.com"
        ]
    },
    ...
]

Portals: Listing Packages

Authorized users can list packages uploaded to any portal under their team(s) subject to access policy). The listing will only include packages that have been completed.

GET /portals/{portal_id}/packages

HEADERS

Name
Type
Required
Description

X-User-Token

String

Yes

User JSON Web Token

curl -H 'X-User-Token: $USER_TOKEN' -s -X GET https://api.massive.app/v1/portals/$PORTAL_ID/packages

Where:

  • $USER_TOKEN is the auth token returned during auth request (refer to Authorization: Login section of this document)
  • $PORTAL_ID is the portal ID returned during creat request (refer to Portals: Creating Team Portals of this document) or listing of team portals request.(refer to Portals: Listing Team Portals of this document)

After a successful request, this endpoint will return an HTTP response with a status code of 200 and a body similar to the one below.

[
  {
    "id": "01CNH4M62513B3FT70FXNFS6YS",
    "created_at": "2018-08-22T11:39:07.717-04:00",
    "updated_at": "2018-08-22T11:39:10.271-04:00"
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE1MzU1NTgxMDksImx2bCI6ImYiLCJzdWIiOiIwMUNOSDRNNjI1MTNCM0ZUNzBGWE5GUzZZUyIsInR5cCI6InBhY2thZ2UifQ.T1tTJkqcaaptWtHg59Ta94LcYl8DomtnY8ieYVdqP_I",
    "completed": true,
    "name": "Test package #1",
    "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit",
    "sender": "test@test.com",
  },
  {
    "id": "01CNH4WNNKZC5FWVG1V100JTXH",
    "created_at": "2018-08-22T11:43:45.843-04:00",
    "updated_at": "2018-08-22T11:43:47.111-04:00"
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE1MzU1NTgxMDksImx2bCI6ImYiLCJzdWIiOiIwMUNOSDRXTk5LWkM1RldWRzFWMTAwSlRYSCIsInR5cCI6InBhY2thZ2UifQ.Y2gI_a_utNNlU_nujZch0zLIDdZ5EDMtQpohIFifvXA",
    "completed": true,
    "name": "Another package",
    "description": "At vero eos et accusamus et iusto odio dignissimos ducimus qui blanditiis praesentium",
    "sender": "test2@test2.com",
  }
]

Where:

  • id is the package ID, which is needed to interact with the package (like downloading or deleting)
  • created_at and updated_at are the date/time at which the package was created and last updated
  • access_token is the auth token required to interact with the package (like downloading or deleting)
  • completed whether this package has been uploaded completely or not. Packages in transit will have this value set to false

Portals: Listing Package Files

Authorized users can list package files uploaded to any portal under their team(s) subject to access policy). The listing will include all files that are a part of the uploaded package.

GET /packages/{package_id}/files

HEADERS

Name
Type
Required
Description

X-Package-Token

String

Yes

Package Token

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

Where:

  • $PACKAGE_ID is the ID of the package (refer to Portals: Listing Packages of this document)
  • $PACKAGE_TOKEN is the package access token (refer to Portals: Listing Packages of this document)

After a successful request, this endpoint will return an HTTP response with a status code of 200 and a body similar to the one below.

[
  {
    "id": "01CNH4M62EFJFX5F7XTC9GZWDF",
    "kind": "file",
    "name": "photo.jpg",
    "path": "/some/directory",
    "size": 193022
    "last_modified": "2018-08-22T11:39:10.280-04:00",
  },
  {
    "id": "01CNH4M86PKYWPKSK8EWEFEQPS",
    "kind": "file",
    "name": "my-image.png",
    "path": "/anotherpath",
    "size": 72012
    "last_modified": "2018-08-22T11:39:10.280-04:00",
  },
  {
    "id": "01CNH4M8J88WSVS7P3NMB1HG42",
    "kind": "zip_windows",
    "name": "windows.zip"
    "last_modified": "2018-08-22T11:39:10.280-04:00",
  },
  {
    "id": "01CNH4M8JMXHTWCTTS8R2PJFVE",
    "kind": "zip_mac",
    "name": "mac.zip"
    "last_modified": "2018-08-22T11:39:10.292-04:00",
  },
  ...
]

Where:

  • id is the file ID
  • kind is the type of file, can be one of:
    • file: a regular file uploaded by the sender
    • directory: an empty directory as part of a directory structure
    • zip_windows: a zip file generated by MASV that contains all files/directories with preserved structure, compatible with Windows and Linux operatin systems
    • zip_mac: a zip file generated by MASV that contains all files/directories with preserved structure but the zip format is only compatible with Mac OS
  • name is the file or directory name
  • path is the relative path in file system where if the file belongs inside a directory structure
  • size is the file size in bytes, if applicable
  • last_modified is the file’s last modification date in the uploader’s filesystem

MASV 3.0 API Guide


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.