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.

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 Integration Manager role
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.

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:

curl -X GET "https://api.massive.app/v1/teams" \
  -H "X-API-KEY: your-api-key-here"

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 Web Tokens for details.

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.

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.

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

The upload lifecycle sequence: the client creates a Package via the API and receives an access token. For each file, the client adds the file to the Package, creates it in cloud storage using a blueprint, obtains pre-signed upload URLs for each chunk, uploads the chunks directly to cloud storage, then finalizes the file. After all files are uploaded, the client finalizes the Package to trigger delivery.

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.

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

The download lifecycle sequence: the client obtains link information (Package ID and token) from the API using a link ID and secret. It then lists the files in the Package. For each file, the client requests a pre-signed download URL from the API and downloads the file directly from cloud storage.

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: your-api-key-here"

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: your-api-key-here" \
  -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

Upload files to the Package. The actual file transfer is handled by MASV’s transfer infrastructure — use the MASV Agent or Web Uploader depending on your architecture.

For details on the upload flow (adding files, obtaining upload URLs, chunked uploads, finalization), see Uploads.

Step 4 — Finalize the Package

Once 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: your-api-key-here" \
  -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.