Skip to content

Quick Start: Upload a file in 5 minutes with the MASV Web Uploader SDK

In this tutortial, you'll build an end-to-end flow to upload a file from your web application to MASV using a Portal.

You will:

  • Install the MASV Web Uploader SDK.
  • Resolve a Portal from its subdomain.
  • Create a package for upload.
  • Initialize the uploader.
  • Select a file in the browser.
  • Upload it to MASV.

This is the simplest path to a working browser-based upload integration.

What you’ll build

By the end of this guide, you will have:

  • A simple web page with a file picker.
  • A JavaScript flow that creates a MASV package.
  • An uploader instance bound to that package.
  • A successful file upload to MASV.

Before you start

You will need:

  • A MASV account.
  • A Portal configured in MASV.
  • The Portal’s subdomain (for example: example1234.portal.massive.io).
  • A JavaScript project where you can install npm packages.

Step 1: Install the Web Uploader SDK

Install the MASV Web Uploader package:

yarn add @masvio/uploader

or:

npm install @masvio/uploader

This is the current MASV browser uploader SDK. Use this package for all new web integrations.

Step 2: Choose the Portal you want to upload to

Uploads using the Web Uploader are typically sent to a Portal.

Each Portal has a subdomain, for example:

https://example1234.portal.massive.io

You will use the subdomain (example1234) to look up the Portal ID in the next step.

Step 3: Get the Portal ID from the subdomain

The uploader flow requires a Portal ID, not just the subdomain.

Call the MASV API to resolve the subdomain:

GET https://api.massive.app/v1/subdomains/portals/{subdomain}

This returns the Portal object, including its id.

Why this step matters: All uploads are tied to a package, and packages are created against a specific Portal. The Portal ID is required to create that package.

Step 4: Create a package for the upload

Uploads are always performed into a package.

Create a package using the Portal ID:

POST https://api.massive.app/v1/portals/{portalID}/packages

The response includes:

  • id (the package ID)
  • access_token (the package token)

You will use both of these values to initialize the uploader.

Think of the package as the upload session container.

Step 5: Initialize the uploader

Create a new uploader instance using the package credentials:

  • Package ID
  • Package token
  • MASV API URL (https://api.massive.app)

This binds the uploader to the package you just created.

Once initialized, the uploader is ready to accept files.

Step 6: Add a file picker to your page

The Web Uploader does not provide a UI. You supply your own.

The simplest approach is a standard HTML file input:

<input type="file" id="fileInput" />

When a user selects a file, your application reads it from the browser and prepares it for upload.

Step 7: Convert selected files into MASV uploader file objects

The uploader expects files in a specific structure.

Each file must include:

  • A unique id
  • The browser File object
  • A path

Example structure:

{
  id: "unique-file-id",
  file: <File>,
  path: "filename.ext"
}

Why this step matters: The path allows MASV to preserve folder structure during upload.

Step 8: Add the files to the uploader

Once your files are prepared, pass them to the uploader.

uploader.addFiles([...])

As soon as files are added:

  • The uploader begins processing.
  • The upload starts automatically.

There is no separate “start” call required.

Step 9: Show progress and completion

To make the upload visible to users, listen for uploader events.

Typical events include:

  • Upload progress
  • Upload completion
  • Upload errors

Attach event listeners to the uploader and update your UI accordingly.

At minimum, you should:

  • Show upload progress.
  • Confirm when upload is complete.
  • Handle errors gracefully.

Important: No explicit start or finalize required

Unlike raw API-based uploads or MASV Agent workflows, the Web Uploader:

  • Does not require a manual start step.
  • Does not require a finalize step.

Once files are added, the upload proceeds automatically.

This is what makes the Web Uploader the fastest path to a working integration.

Summary

The minimum upload flow is:

  1. Install the Web Uploader SDK
  2. Resolve the Portal ID from the subdomain
  3. Create a package
  4. Initialize the uploader
  5. Let the user select a file
  6. Convert the file into a MASV uploader object
  7. Add the file to the uploader

Once added, the upload begins immediately.

What’s next

After your first successful upload, you can extend your integration to:

  • Upload multiple files or folders.
  • Attach metadata to uploads.
  • Customize the upload UI.
  • Add pause, retry, and cancel controls.
  • Upload to Teams instead of Portals.
  • Handle upload lifecycle events in more detail.