Getting started with the MASV API

The MASV API provides a programmatic interface for managing large file workflows. Use it to create and manage Portals, initiate and track file transfers, apply metadata, and orchestrate how files move through your organization and into downstream systems.

Choosing the right tool

We recommend that you review the functionality offered by the MASV Agent and browser-based Web Uploader and Web Downloader before diving into the MASV API. These tools are designed to optimize file transfers out-of-the-box. Use the API when you need fine-grained control or your platform isn’t supported by the MASV Agent.

This guide walks you through the essentials: authenticating your requests, understanding the system model, and executing a typical transfer workflow.

Prerequisites

Before you begin, make sure you have:

• A MASV account with Owner, Admin, or Custom role with API permissions.
• An API key (see API Keys for creation steps)
• A tool for making HTTP requests (curl, Postman, or your language’s HTTP client)

API basics

The MASV API is a RESTful service at https://api.massive.app/v1/.

All connections require TLS 1.2 or 1.3. Requests use standard HTTP methods:

Method	Action
GET	Read, list, or search
POST	Create or authenticate
PUT	Update
DELETE	Delete

Every POST and PUT request must include a Content-Type: application/json header.

List endpoints use page-based pagination (page and limit query parameters). The API also enforces rate limits — if you exceed them, you’ll receive a 429 response with a Retry-After header.

Note

The version prefix (v1) can vary by endpoint. Check the route information for individual endpoints in the API reference pages.

Authentication

The MASV API uses API keys as the primary authentication mechanism. An API key is tied to a specific user and inherits that user’s role-based permissions.

Include your API key in the X-API-KEY header on every request:

# Store your API key in an environment variable — never hardcode it.
# See /api/api-keys/ for key management best practices.
curl -X GET "https://api.massive.app/v1/teams" \
  -H "X-API-KEY: $MASV_API_KEY"

For operations like uploading or downloading files, MASV also uses scoped web tokens. These are short-lived, limited-scope tokens suitable for client-side or temporary workflows. See Package & Transfer Tokens for details.

Tip

API keys are returned only once at creation time. Store them securely — you cannot retrieve the key value later. Rotate your API keys at least every 90 days. If you suspect a key has been compromised, rotate it immediately and review your Team’s recent API activity.

For a full overview of authorization options, see Authorization.

System model overview

MASV is built around a few core objects:

• Team — The top-level organizational boundary. Contains users, Portals, Teamspaces, and Packages.
• Portal — A controlled ingestion point where users or external contributors upload files.
• Package — The unit of transfer. Contains files plus metadata and delivery configuration.
• Link — A shareable reference that gives recipients download access to a Package.

A typical flow: files are uploaded through a Portal, creating a Package. That Package is then shared via Links or routed to storage and downstream systems.

Diagram source

graph LR
    Team --> Portal
    Team --> Package
    Portal --> Package
    Package --> Link

For a deeper look at Teams, Users, Roles, Teamspaces, Metadata, and how these objects relate, see Core Concepts.

Control plane vs. data plane

MASV separates responsibilities between two layers:

• Control plane (API) — Manages configuration and orchestration: creating Portals, defining Packages, tracking transfer state, managing users.
• Data plane (Agent / Uploader) — Handles the actual movement of files: chunking, acceleration, retries, and delivery.

Your application uses the API to define what should happen. MASV’s transfer infrastructure handles how the data moves. This means you don’t need to build your own file transfer mechanisms.

Creating your first transfer

Upload lifecycle

The following diagram shows the full upload lifecycle when using the MASV API directly. Each file goes through a create → chunk → finalize cycle before the Package itself is finalized.

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

Download lifecycle

Downloading follows a simpler flow. The client resolves a Link, lists the available files, obtains download URLs, and downloads each file directly from cloud storage.

Diagram source

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

    Client->>API: Get link info (link ID + secret)
    API-->>Client: Package ID + package token

    Client->>API: List files in Package
    API-->>Client: File list (IDs, names, sizes)

    loop For each file
        Client->>API: Get download URL (file ID)
        API-->>Client: Pre-signed download URL

        Client->>Storage: Download file (GET)
        Storage-->>Client: File data
    end

A typical API-driven transfer follows these steps:

Step 1: Get your Team ID

Most API operations are scoped to a Team. Retrieve your Team ID first:

curl -X GET "https://api.massive.app/v1/teams" \
  -H "X-API-KEY: $MASV_API_KEY"

The response includes your Team’s id field.

Step 2: Create a Package

Create a Package to define the transfer. Include the Team ID and any metadata:

curl -X POST "https://api.massive.app/v1/teams/{team_id}/packages" \
  -H "X-API-KEY: $MASV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My First Package",
    "description": "Test transfer via API",
    "recipients": ["recipient@example.com"]
  }'

The response returns the Package id you’ll use in subsequent steps.

Step 3: Upload files

Add a file to the Package, then upload its contents in chunks using pre-signed URLs:

# Add a file to the Package
curl -X POST "https://api.massive.app/v1/packages/{package_id}/files" \
  -H "X-Package-Token: $PACKAGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "file",
    "name": "video.mp4",
    "path": "",
    "size": 104857600,
    "last_modified": "2026-01-15T10:00:00Z"
  }'

The response includes a create_blueprint for initializing the file in cloud storage and the file ID. Use the blueprint to create the file in storage, then request pre-signed URLs for each chunk:

# Obtain upload URLs for chunks (start=0, count=number_of_chunks)
curl -X POST "https://api.massive.app/v1/packages/{package_id}/files/{file_id}?start=0&count=2" \
  -H "X-Package-Token: $PACKAGE_TOKEN" \
  -H "Content-Type: application/json"

Upload each chunk to its pre-signed URL with a PUT request, then finalize the file by submitting the ETags returned from each chunk upload.

For the complete chunking workflow (blueprint usage, chunk sizing, and file finalization), see Uploads.

Step 4: Finalize the Package

After all files are uploaded, finalize the package to make it available for delivery:

curl -X POST "https://api.massive.app/v1/teams/{team_id}/packages/{package_id}/finalize" \
  -H "X-API-KEY: $MASV_API_KEY" \
  -H "Content-Type: application/json"

After finalization, recipients receive download access and any configured integrations (webhooks, cloud connections) are triggered.

Error handling

The API uses standard HTTP status codes:

Range	Meaning
2xx	Success
4xx	Client error (invalid input, auth failure)
5xx	Server error (retryable)

For production integrations, implement retry logic with exponential backoff for 5xx responses, and log all API interactions for diagnostics.

Next steps

• Core Concepts — Understand Teams, Portals, Packages, Links, Teamspaces, and Metadata in depth.
• Authorization — Explore API key and web token authentication patterns.
• Uploads — Learn the full upload lifecycle.
• Downloads — Learn how to download Packages and files.
• Portals — Set up controlled ingestion points for external contributors.
• Webhooks — Receive event notifications for automation workflows.