Quick Start: Upload with the Web Uploader

In this tutorial, you’ll build an end-to-end flow to upload a file from your web application to MASV using a Portal and the Web Uploader SDK.

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 tutorial, 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 — sign up or log in
• A Portal configured in MASV
• The Portal’s subdomain (for example: example1234 from 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:

npm install @masvio/uploader

Or with Yarn:

yarn add @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. See the Portals reference for full endpoint details.

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

This returns the Portal object, including its id.

Tip

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. See the Packages reference for the full endpoint specification.

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.

Step 5: Initialize the uploader

Create a new uploader instance using the Package credentials:

import { Uploader } from "@masvio/uploader";

const uploader = new Uploader(packageId, accessToken, "https://api.massive.app");

This binds the uploader to the Package you just created. Once initialized, the uploader is ready to accept files.

See the Web Uploader API Reference for full constructor details.

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 uploader file objects

The uploader expects files in a specific structure. Each file must include:

• A unique id
• The browser File object
• A path (used to preserve folder structure)

Example structure:

const files = Array.from(fileInput.files).map((file, index) => ({
  id: `file-${index}`,
  file,
  path: file.name,
}));

Step 8: Add the files to the uploader

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

uploader.addFiles(...files);

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

Track upload progress and completion by subscribing to uploader events:

uploader.on(Uploader.UploaderEvents.Progress, (event) => {
  console.log("Upload progress:", event.data);
});

uploader.on(Uploader.UploaderEvents.Finished, (event) => {
  console.log("Upload complete:", event.data);
});

uploader.on(Uploader.UploaderEvents.Error, (event) => {
  console.error("Upload error:", event.data);
});

At minimum, you should:

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

Note

Unlike the MASV API and MASV Agent workflows, the Web Uploader does not require a manual start or finalize step. Once files are added, the upload proceeds automatically.

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 an uploader file object
7. Add the file to the uploader

Once added, the upload begins immediately.

Next steps

• Web Uploader Getting Started — Full guide with a complete code example.
• Web Uploader API Reference — Constructor, methods, and events documentation.
• MASV API — Uploads — Understand the underlying upload lifecycle.
• MASV API — Portals — Learn more about Portal configuration and management.