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 begin

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 a 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 from the previous step. After initialization, 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

After 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. After 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

After files are 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.