Upload files with the MASV API

Upload files directly to MASV’s private cloud infrastructure using the API.

Tip

The recommended way to upload files is to use MASV Agent. It abstracts the complexities of directly using the MASV API for uploading and offers features for managing automations, multiple connections, rate limits, and local storage. Use the MASV API for uploading when your application’s host OS is not supported by the MASV Agent or you need finer-grained control.

Be aware of storage expiry when planning your upload workflow:

Caution

MASV stores an uploaded package in MASV storage until its expiry time. When packages expire, MASV deletes the package and its content. For details, see Pricing and How extended storage works.

Packages and authorization

Files uploaded to MASV belong to a package object — a virtual directory inside of MASV. Each package contains a token that can be used to upload files to that specific virtual directory. A package can be created by interacting with different API endpoints (for example, Portals or Teams).

All requests to upload endpoints require a token passed as an HTTP header, X-Package-Token. This token authorizes the user to add and remove files from the package until the package is finalized.

Lifecycle of an upload

For each file in the package:

1. Add file to the package (API action)
2. Create the file in cloud storage
3. Collect metadata from cloud storage service
4. Identify the number of file chunks
5. Obtain authorized URLs to upload each chunk
6. Upload all chunks to cloud storage
7. Collect metadata for each uploaded chunk
8. After all chunks are uploaded, finalize the file

Then finalize the package.

Diagram source

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

    Client->>API: Create Package
    API-->>Client: Package ID + access token

    loop For each file
        Client->>API: Add file to Package
        API-->>Client: Create blueprint

        Client->>Storage: Create file in cloud storage (blueprint)
        Storage-->>Client: Upload ID

        Client->>API: Obtain upload URLs (chunk count)
        API-->>Client: Pre-signed URLs (blueprints)

        loop For each chunk
            Client->>Storage: Upload chunk (PUT)
            Storage-->>Client: ETag
        end

        Client->>API: Finalize file (ETags + upload ID)
        API-->>Client: File finalized
    end

    Client->>API: Finalize Package
    API-->>Client: Package finalized — delivery triggered

Note

After the uploaded package has been finalized, the transfer is locked and cannot be further modified. Finalization dispatches the file to the intended destination immediately.

MASV blueprints

MASV’s API abstracts interactions with cloud storage services by creating a Blueprint object with four properties:

Name	Type	Description
url	String	URL that the request should be forwarded to
method	String	The HTTP method to use (GET, POST, PUT, DELETE)
headers	JSON	Key-value map of header names and their values
body	String	HTTP request body

Chunk size

MASV lets you set the chunk size, which divides larger files into segments for transfer. The default chunk size is 100 MiB, but you can adjust the chunk_size parameter to optimize for speed or reliability.

Storage services like Amazon S3 limit the number and size range for chunks. MASV uses the endpoint https://api.massive.app/v1/system/packages/spec to pass chunk parameters:

Parameter	Description
max_chunk_count	Maximum number of chunks permitted (10,000 for S3)
max_chunk_size	Maximum chunk size in bytes (5 GiB for S3)
min_chunk_size	Minimum chunk size in bytes (5 MiB for S3)

Upload API interaction

Each package belongs to either a Team or Portal on MASV. To create a package for a Team, you must provide an API key. To create a package for a Portal, you do not need an API key (but must provide an access code if the Portal requires it).

Step 1a — Create a Team package

Method	Route
POST	/teams/{team_id}/packages

Headers

Name	Type	Required	Description
X-API-KEY	String	Yes	API key
Content-Type	String	Yes	Must be application/json

Body

Name	Type	Required	Description
access_limit	Integer	No	Override default number of downloads
description	String	Yes	Description of the package
name	String	Yes	Name of the package
password	String	No	Password required to download
recipients	String[]	Yes	Email address of recipient(s)
unlimited_storage	Boolean	No	Enable unlimited extended storage
chunk_size	Integer	No	Chunk size in bytes for all file uploads in this package

Request

# Store your API key in an environment variable — never hardcode it.
# See /api/api-keys/ for key management best practices.
curl -d '{"access_limit":$ACCESS_LIMIT, "description":"$DESCRIPTION", "name":"$NAME", "password": "$PASSWORD", "recipients":["$RECIPIENT_EMAIL"]}' \
  -H "X-API-KEY: $API_KEY" \
  -H "Content-Type: application/json" \
  -X POST https://api.massive.app/v1/teams/$TEAM_ID/packages

Response

Returns 201 Created with the package object including id and access_token.

Note

Take note of the id and the access_token as they are required to interact with the upload API.

Step 1b — Create a Portal package

Tip

If a Custom Form is enabled for the Portal, you must submit a form response for required custom fields before the package can be created.

Method	Route
POST	/portals/{portal_id}/packages

Headers

Name	Type	Required	Description
Content-Type	String	Yes	Must be application/json
X-Access-Code	String	No	URI encoded upload password (if required by Portal settings)

Body

Name	Type	Required	Description
description	String	Yes	Description of the package
name	String	Yes	Name of the package
sender	String	Yes	Email address of the Portal package sender
form_data_id	String	No*	Form response ID. *Required if the Portal has an enabled custom form.
chunk_size	Integer	No	Chunk size in bytes

Step 2: Add a file to the package

Method	Route
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	Yes	Type of file: file or directory
name	String	Yes	File name
path	String	Yes	File’s relative path
last_modified	String	Yes	File’s last modified date (UTC)
size	Integer	No	File size in bytes (strongly recommended)
chunk_size	Integer	No	Override the package-level chunk size

Request

curl -d '{"kind":"file", "name":"my_video.mpeg", "path": "", "last_modified":"2018-12-17T16:14:34.450Z"}' \
  -H "X-Package-Token: $PACKAGE_TOKEN" \
  -H "Content-Type: application/json" \
  -X POST https://api.massive.app/v1/packages/$PACKAGE_ID/files

Response

Returns 201 Created with create_blueprint and file objects.

Step 3: Create the file in MASV’s cloud storage

Use the create_blueprint from step 2 to construct an HTTP request to the cloud storage service. The response is XML containing an UploadId needed for subsequent steps.

Step 4: Obtain upload URLs

Request pre-signed upload URLs for each of a file’s parts.

Method	Route
POST	/packages/{package_id}/files/{file_id}?start={start}&count={count}

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
upload_id	String	Yes	ID for the initiated multi-part upload

Query parameters

Name	Type	Required	Description
start	Integer	Yes	Starting index of the chunk (zero-indexed)
count	Integer	Yes	Number of chunk requests to generate

Request

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

Response

Returns an array of blueprints in ascending order based on the chunk index.

Tip

Do not request more chunk URLs than necessary and do not skip any of the URLs provided.

Step 5: Upload the file chunks

Use each blueprint to upload the corresponding chunk as binary data in the request body.

curl -X PUT "$BLUEPRINT_URL" \
  --data-binary @<(dd if=my_video.mpeg skip=0 count=104857600 iflag=skip_bytes,count_bytes)

Note

For each uploaded chunk, collect the partNumber (from the URL parameters) and ETag (from the response header).

Step 6: Publish upload progress

Note

This feature is only available to customers with this feature enabled. Contact team@masv.io to request access.

MASV integrates with PubNub to indicate overall file upload progress on each package.

Step 7: Finalize the file

After all chunks have been uploaded, inform the API that the file upload is complete.

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

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
chunk_extras	Object[]	Yes	Information about all chunks
chunk_extras[].part_number	String	Yes	Chunk part number
chunk_extras[].etag	String	Yes	Chunk part hash
file_extras.upload_id	String	Yes	The upload ID from step 3
size	Integer	Yes	The file size
chunk_size	Integer	Recommended	The chunk size used when uploading

Request

curl -d '{"chunk_extras":[{"part_number":"1","etag":"\"7be1b3cc95a04a6dd07d157ad6fae64a\""}], "file_extras":{"upload_id":"$UPLOAD_ID"}, "size":$FILE_SIZE, "chunk_size":$CHUNK_SIZE}' \
  -H "X-Package-Token: $PACKAGE_TOKEN" \
  -H "Content-Type: application/json" \
  -X POST https://api.massive.app/v1/packages/$PACKAGE_ID/files/$FILE_ID/finalize

Response

Returns 204 No Content.

Note

Repeat steps 2–7 for each additional file in the package.

Each file must match its declared size exactly:

Caution

If the file size submitted does not match the actual size of the object in storage, the service will respond with 409 Conflict.

Step 8: Finalize the package

After all files have been uploaded and finalized, indicate that the package is ready to be dispatched.

Method	Route
POST	/packages/{package_id}/finalize

Headers

Name	Type	Required	Description
X-Package-Token	String	Yes	Package JSON Web Token
Content-Type	String	Yes	Must be application/json

Request

curl -H "X-Package-Token: $PACKAGE_TOKEN" \
  -H "Content-Type: application/json" \
  -X POST https://api.massive.app/v1/packages/$PACKAGE_ID/finalize

Response

Returns 204 No Content.

Caution

Make sure all uploaded files have been completed and finalized before finalizing the package. Any in-flight, non-finalized files will be dropped. If no files were uploaded/finalized, this API call will fail.

Creating additional links

You can create additional direct-download links or send a link to a specific email recipient after the upload has been finalized. See the Links page for more details.