Skip to content
Developer Platform

Core Concepts

MASV organizes file transfer workflows around a small set of core objects. Understanding how these objects relate helps you choose the right integration pattern and navigate the API effectively.

This page is a conceptual overview. For hands-on steps, see Getting Started.

---
title: MASV Data Model
---
erDiagram
    Team ||--o{ User : has
    Team ||--o{ Portal : has
    Team ||--o{ Teamspace : contains
    Portal ||--o{ Package : receives
    Package ||--o{ File : contains
    Package ||--o{ Link : "shared via"
    Portal ||--o| MetadataForm : "may have"

    Team {
        string id
        string name
    }
    User {
        string id
        string email
        string role
    }
    Portal {
        string id
        string subdomain
    }
    Package {
        string id
        string name
        string state
        datetime expiry
    }
    File {
        string id
        string name
        integer size
    }
    Link {
        string id
        string recipient_email
    }
    Teamspace {
        string id
        string name
    }
    MetadataForm {
        string id
        string fields
    }

Teams

Section titled “Teams”

A Team is the top-level organizational boundary in MASV. Most objects — Portals, Teamspaces, Packages, Users, and API keys — belong to a Team directly or indirectly.

When designing an integration, treat the Team as the root scope for configuration and ownership. Your application typically starts by identifying the Team it operates against, then creates or queries resources within that Team.

Users and Roles

Section titled “Users and Roles”

Users act within a Team according to their assigned role. MASV authorization is role-aware: an API key carries the same privileges as the user who created it.

Key role behaviors:

  • Owner — Full administrative control. Can manage all API keys for the Team.
  • Admin — Can create and manage their own API keys. Has broad access to Team resources.
  • Integration Manager — Can create and manage their own API keys. Designed for automation and integration use cases.

Authorization in MASV is not just about whether a request is authenticated — it also depends on whether the underlying user’s role permits the action. Portal creation, Teamspace visibility, and API key management are all subject to role-based access.

For details on authentication mechanisms, see Authorization.

Packages

Section titled “Packages”

A Package is the core transfer object in MASV. It represents a set of files sent by a Team member or received through a Portal.

You don’t upload “into MASV” in the abstract — you upload files into a specific Package. That Package then becomes the unit you manage, share, download, expire, or inspect. Think of it as a virtual directory that holds one transfer’s worth of content.

Packages can contain one or many Files, carry metadata, and be shared with recipients through Links.

For the upload and download workflows, see Uploads and Downloads.

Files

Section titled “Files”

Files are the contents of a Package. A Package may include one or many Files, and file metadata is represented at the API layer while the underlying file data is stored in MASV’s storage infrastructure.

This separation is useful for integrations. Your code interacts with Package and File metadata through API resources, while the actual upload and download operations are carried out through authorized transfer flows and MASV-managed storage endpoints.

Section titled “Links”

A Link represents a share of a Package to one or more recipients. A Package can have multiple Links, each granting download access.

The only way to download a Package is to obtain a Link from a Package owner or to create a direct-download Link (which requires Package management access). Recipient Link credentials are supplied out of band rather than exposed through the API.

This is an important security boundary: Package ownership and Link possession are distinct concepts. Your application may create or manage Packages, but download access is intentionally mediated through Link-based mechanisms.

For Link management, see Links.

Portals

Section titled “Portals”

A Portal is MASV’s external-facing upload surface. Each Portal has a unique subdomain and is created under a Team.

Portals let external contributors submit files into your MASV environment without exposing your internal administration model. They serve as both a user experience surface and an integration boundary.

Use cases

Section titled “Use cases”
  • Vendor delivery — Standardize how incoming content is received from external partners.
  • Client submissions — Collect files from clients without requiring them to have a MASV account.
  • Media ingest — Receive content from creators and route it to downstream workflows.

Portal security

Section titled “Portal security”

Portal access is configurable. Options include upload access codes, upload and download password protection, Teamspace assignment, and private Portal access rules. Some Portals are broadly reachable with minimal friction; others are tightly controlled for authenticated users or Teamspace members.

Treat Portal security as part of your business workflow, not as a fixed platform behavior.

For Portal configuration, see Portals.

Teamspaces

Section titled “Teamspaces”

A Teamspace is a way to organize a subset of Team members into a smaller group. Teamspaces serve as both an organizational construct and an access-control mechanism — use them to group people by project, client, or department.

Where a Team gives you the enterprise boundary, a Teamspace gives you the project boundary. If your application manages multiple productions, vendors, customers, or departments, Teamspaces are the natural place to mirror that structure.

For example, you might create one Teamspace per show, client account, or ingest workflow. Packages, Portals, and membership can then be aligned so users see only the work relevant to them.

For Teamspace management, see Teamspaces.

Metadata

Section titled “Metadata”

Metadata in MASV is structured information collected from senders during Portal uploads. A Portal can have a custom metadata form, and when that form exists, a form response is required before the Portal Package can be created.

Metadata forms

Section titled “Metadata forms”

An admin creates a form, configures its fields, the sender submits a response, and the Package is created with that response attached. When the Package is finalized, the metadata is delivered in JSON, CSV, XML, or email-body format.

Field types

Section titled “Field types”

MASV provides default fields for new metadata forms: Sender Email, Package Name, and Package Description. Forms can also collect data through checkbox, dropdown select, radio button, email, and date picker fields.

Use metadata fields not only for human-readable context, but also for operational values — routing codes, production IDs, file categories, delivery targets, or downstream workflow selectors.

Integration considerations

Section titled “Integration considerations”

Metadata is a first-class integration surface. Treat it as structured input to downstream automation, storage routing, indexing, or MAM ingestion rather than just a note attached to a transfer.

For metadata configuration, see Custom Metadata.

How the concepts fit together

Section titled “How the concepts fit together”
---
title: Control Plane vs. Data Plane
---
flowchart LR
    App["Your Application"]

    subgraph ControlPlane["Control Plane — MASV API"]
        API["REST API\nhttps://api.massive.app/v1"]
        Portals["Portals"]
        Packages["Packages"]
        Links["Links"]
        Metadata["Metadata"]
        Teams["Teams & Users"]
    end

    subgraph DataPlane["Data Plane — Transfer Infrastructure"]
        Agent["MASV Agent"]
        Uploader["Web Uploader"]
        Storage["Cloud Storage\n(S3-accelerated)"]
    end

    App -- "configure & orchestrate" --> API
    API --- Portals
    API --- Packages
    API --- Links
    API --- Metadata
    API --- Teams
    API -- "pre-signed URLs &\nblueprints" --> Storage
    Agent -- "chunked upload/download" --> Storage
    Uploader -- "chunked upload" --> Storage
    App -- "transfer files" --> Agent
    App -- "transfer files" --> Uploader

A typical MASV workflow follows this pattern:

  1. Your application authenticates with an API key associated with a Team user.
  2. It creates or manages Team-level resources such as Teamspaces and Portals.
  3. External contributors upload through a Portal.
  4. Their submission creates a Package containing one or more Files.
  5. If the Portal uses a metadata form, the sender submits structured metadata as part of the Package creation flow.
  6. Recipients access the Package through download Links, subject to MASV’s authorization model.

Choosing the right building block

Section titled “Choosing the right building block”
ConceptUse when you need…
TeamA top-level administrative scope
TeamspaceProject or group-level organization inside a Team
PortalA controlled intake surface for external senders
PackageThe actual unit of transfer
LinkA way for recipients to access downloads
Metadata formStructured business context alongside file uploads

Next steps

Section titled “Next steps”