Skip to content

Getting started with the MASV API

The MASV API provides a programmatic interface for managing large file workflows, enabling you to integrate MASV directly into your applications, automation systems, and enterprise data pipelines. Through the API, you can create and manage portals, initiate and track file transfers, apply metadata, and orchestrate how files move through your organization and into downstream systems.

MASV is designed to handle the challenges of large-scale data movement over standard internet infrastructure. The API allows you to control and automate these capabilities while MASV manages the complexity of file transfer performance, reliability, and global delivery.

When to use the MASV API

The MASV API is most effective when you need to integrate file transfer capabilities into a broader system or workflow. It is particularly well suited for backend services, SaaS platforms, and enterprise applications that require automation, orchestration, or integration with other tools such as storage systems, media asset managers, or data processing pipelines.

In contrast, MASV also provides other components that are better suited to specific use cases. The MASV Agent is designed for high-performance, automated file transfer from infrastructure such as network-attached storage or cloud environments. The web uploader and portal interfaces are intended for end users who need a simple, browser-based experience for uploading and downloading files.

In most production architectures, the API is used to orchestrate workflows and manage system state, while the Agent and uploader components are responsible for the actual movement of data.

MASV system model

MASV is built around a small number of core concepts that define how files are ingested, transferred, and delivered.

A Team represents the top-level organizational boundary and contains all users, portals, and transfers. Within a team, Portals act as controlled ingestion points, allowing users or external contributors to upload files through a defined interface. When files are uploaded, they are grouped into Packages, which represent the unit of transfer and contain both the files themselves and any associated metadata or delivery configuration. Packages can then be distributed to recipients or integrated with storage and downstream systems.

MASV data model diagram.

A typical workflow begins when a user or system uploads files through a portal. This creates a package, which can then be processed, delivered, or routed according to business logic implemented through the API. This model provides a consistent and flexible structure for building automated file workflows.

Architecture and role of API

MASV separates responsibilities between a control plane and a data plane. This distinction is important for understanding how the API should be used.

The control plane, exposed through the MASV API, is responsible for managing system configuration and workflow orchestration. This includes creating portals, managing users, defining packages, and tracking the state of transfers. The data plane, on the other hand, is responsible for the actual movement of files. This is handled by MASV’s transfer infrastructure, including the Agent and uploader technologies, which manage chunking, acceleration, retries, and delivery over the network.

In practice, your application will use the API to define what should happen, while MASV handles how the data is moved. This separation allows you to build scalable, reliable systems without needing to implement your own file transfer mechanisms.

About MASV API

All user interactions translate to API calls––not necessarily one-to-one, as some actions could translate to multiple API calls depending on what the client needs to perform.

To enhance security and protect data in transit, MASV API requires all connections to use Transport Layer Security (TLS) 1.2 or 1.3.

REST API conventions

  • This API supports a Representational State Transfer model for accessing a set of resources through a fixed set of operations.

  • Use consistent HTTP verb to action mapping:

  • GET to read/list/view/search

  • POST to create/authenticate
  • PUT to update

  • DELETE to delete

  • Use API keys for authorization

  • API base URL https://api.massive.app/v1/

Note

The version (v1) can vary according to endpoint. Please check Route information for individual endpoints.

Note

The MASV API requires a Content-Type: application/json header on every POST and PUT request, otherwise you will receive an unsupported Content-Type error.

Creating a transfer

A typical interaction with the MASV API involves a small sequence of steps that together define and execute a file transfer.

First, you authenticate your requests using an API key associated with a MASV user account. This key is included in the Authorization header of each request and determines what actions your application is permitted to perform.

Next, you retrieve the identifier for the team you are working within. Most API operations are scoped to a specific team, so this identifier is required for creating and managing resources.

Once you have the team context, you create a package. This defines the transfer, including its metadata, recipients, and configuration. After the package is created, files are uploaded using either the MASV Agent or an uploader interface, depending on your architecture and performance requirements.

Finally, the package is finalized, which makes it available for delivery to recipients or for further processing by integrated systems.

This sequence forms the foundation for most MASV API workflows, and can be extended with additional logic such as metadata enrichment, automation triggers, and integration with external services.

Authentication and security

The MASV API uses API keys as its primary authentication mechanism. These keys are associated with individual users and inherit the permissions assigned to those users within the system. As a result, access control is managed through MASV’s role-based permissions model, and API keys should be treated with the same level of security as user credentials.

In addition to API keys, MASV uses scoped web tokens for specific operations such as uploading or downloading files. These tokens are typically short-lived and limited in scope, making them suitable for use in client-side or temporary workflows.

All API communication is conducted over HTTPS using modern TLS encryption, ensuring that data in transit is protected according to industry best practices.

Permissions model

Access to MASV resources is governed by user roles within a team. These roles determine what actions can be performed through both the user interface and the API.

Owners have full control over the team and all associated resources. Administrators can manage most operational aspects, including portals and users. Integration-focused roles, such as Integration Manager, are typically used for API-driven workflows and are granted permissions appropriate for automation and system integration.

Because API keys inherit the permissions of the user who created them, it is important to follow the principle of least privilege when designing integrations. This ensures that applications have only the access they require and reduces risk in the event of credential exposure.

Common use cases

The MASV API supports a wide range of enterprise and industry-specific workflows. In media and entertainment environments, it is often used to build ingest pipelines where files uploaded through a portal are automatically delivered to cloud storage and made available to media asset management systems.

In data-intensive industries such as artificial intelligence, geospatial analysis, and life sciences, the API enables the ingestion and distribution of large datasets, along with associated metadata, into processing pipelines. Enterprises also use the API to replace legacy managed file transfer systems, providing a more scalable and cloud-native approach to secure file exchange.

These use cases are unified by a common pattern: the API is used to orchestrate workflows and integrate MASV into a broader system, while MASV handles the complexities of moving large volumes of data reliably.

API conventions

The MASV API follows standard RESTful design principles, with resources accessed through predictable endpoints and manipulated using standard HTTP methods. All resources are scoped to a team, and each resource is identified by a globally unique identifier.

Timestamps are expressed in ISO 8601 format using UTC, and responses are returned in JSON. Pagination is implemented using cursor-based mechanisms to efficiently handle large result sets.

These conventions are designed to provide consistency and predictability, making it easier to integrate MASV into existing systems and workflows.

Error handling and reliability

The API uses standard HTTP status codes to indicate the outcome of requests. Successful operations return codes in the 2xx range, while client-side errors such as invalid input or insufficient permissions return 4xx codes. Server-side issues are indicated by 5xx responses and should generally be treated as retryable conditions.

When building production integrations, it is recommended to implement retry logic with exponential backoff, as well as comprehensive logging of API interactions. This ensures that transient failures can be handled gracefully and that issues can be diagnosed effectively.

Building production integrations

When designing systems that use the MASV API, it is important to align with the platform’s architectural model. The API should be used for orchestration and control, while data movement should be delegated to MASV’s transfer infrastructure.

Applications should be designed with idempotency in mind, particularly in event-driven architectures where duplicate events may occur. Integration with monitoring and alerting systems is also recommended to provide visibility into workflow execution and system health.

By following these principles, you can build robust, scalable solutions that take full advantage of MASV’s capabilities.

Next steps

To begin working with the MASV API, you should first create an API key and familiarize yourself with the structure of teams and portals. From there, you can build a simple workflow that creates and sends a package, and then expand your implementation to include automation, metadata, and integration with external systems.

Additional documentation provides detailed reference material for API endpoints, as well as guides for using the MASV Agent and uploader technologies in conjunction with the API.

  • Portals represent a website through which users can receive packages.
  • Each Team can have multiple portals (1-N relationship).
  • Each portal has a unique subdomain.

Packages

  • A package represents a set of files sent by a Team member or received by a Portal.
  • Each package can have multiple files.
  • File metadata is stored at the API level, but actual file data is stored in a storage service.
  • A link represents a package share with recipient(s).
  • Each package can have multiple links (1-N relationship).
  • The only ways to download a package are by obtaining a link from one of the package owners or by creating a direct-download link, which requires access to manage the package.
  • Access to recipient links can only by supplied out-of-band, meaning, no API call will ever expose the complete credentials to access the link and download the files through it.
  • A direct-download link can be created without a recipient specified, in which case the ID and download secret will be returned in the initial response only.
  • The link's download secret cannot be retrieved via the API for existing links.