Tutorial: Upload a File with MASV Agent (Docker)

In this tutorial, you’ll follow the steps your application goes through to send a file with MASV. You’ll use the MASV Agent running in a Docker container to upload a single file to a MASV Team.

MASV Agent abstracts much of the MASV API for you. It is a fast, reliable, and flexible way to add file transfers to your application. Because your application interacts with MASV Agent via a RESTful web API, you can run it locally, on-premises, or in the cloud.

What you’ll learn

When you’re done, you’ll know how to:

• Set up MASV Agent in Docker
• Authenticate your application
• Start an upload
• Monitor the upload’s progress
• Finalize the upload

Before you begin

You’ll need:

• A MASV account with the Owner or Admin role — sign up here
• A command line shell (this tutorial uses GNU Bash on Linux)
• curl — to interact with the MASV Agent HTTP API
• jq — to format JSON output
• Docker — Docker Desktop or the Docker CLI with Docker Compose
• A file to send (keep it under 1 MB for this tutorial)

Step 1: Set up MASV Agent

Create a folder to run the MASV Agent. The Agent stores data in two Docker volumes:

• config — MASV Agent configuration
• data — uploaded and downloaded files

Create local folders for these volumes before starting the container. If these folders don’t exist, Docker creates them with root as the owner.

mkdir -p send-tutorial/config send-tutorial/data

In your text editor, create the compose.yaml file below and save it in the send-tutorial folder. Replace YOUR-PATH with the full path to your local send-tutorial folder.

version: "3"
services:
  transferagent:
    image: masvio/masv-agent:latest
    container_name: masv-agent
    environment:
      - TZ=UTC
      - API_KEY=${API_KEY}
    volumes:
      - YOUR-PATH/send-tutorial/config/:/config
      - YOUR-PATH/send-tutorial/data/:/data
    ports:
      - 8080:8080
    restart: unless-stopped
    command: ["-api-key", "$API_KEY"]

The compose.yaml uses a Docker environment variable, API_KEY, to authenticate requests to the MASV Agent. You’ll create the API key in the next step.

For full Docker setup details, see the Docker setup guide.

Tip

Your application can also use Docker secrets to pass the API key to the MASV Agent container.

Step 2: Get an API key

To authenticate with the MASV Agent, your application needs an API key.

To create an API key, you must be the MASV account Owner or Admin for a Team.

Caution

Keep the API key secure. It acts like a password that MASV uses to authenticate your requests. Any application that uses this key has the full privileges of your MASV user account.

Store the API key in a file named .env in the send-tutorial folder. Docker Compose uses this file to pass environment variables to the container.

To get an API key:

1. Sign in to the MASV Web App as the account Owner or Admin.
2. Follow the steps to create an API key.
3. Create a .env file in the send-tutorial folder with your key:

API_KEY='your-api-key-here'

Step 3: Start MASV Agent

Open a new terminal window to start the container (so you can see the Agent log while working in the first terminal):

docker compose up

Tip

If you don’t have permission to run Docker, you may need to add your user to the docker group.

After Docker loads the image and the Agent starts, you’ll see output like this:

masv-agent  | [INFO] 20:47:22: Backend: https://api.massive.app
masv-agent  | [INFO] 20:47:22: API Server listening on [::]:8080

Confirm that the Agent has started a session:

curl --head --request GET http://localhost:8080/api/v1/login

A successful response:

HTTP/1.1 200 OK
Content-Type: application/json

If you receive a 401 Unauthorized response, your API key was not accepted. Create a new key, update the .env file, and restart the container.

Step 4: Get your Team ID

You need a Team ID to specify which MASV Team to upload to. The teams endpoint returns a JSON array of Team objects:

curl --silent --request GET http://localhost:8080/api/v1/teams | jq '.[] | { name, id }'

Example response:

{
  "name": "First Unit Team",
  "id": "0EGXTA6M1PNLGEV2DJ53FJKGBD"
}
{
  "name": "Second Unit Team",
  "id": "E1XNAZMFP8LDEJ1HKTW5EBAVNM"
}

Choose a Team and save its id in a shell variable:

TEAM_ID='your-team-id-here'

Step 5: Start the upload

A MASV Package is like a virtual folder inside MASV. From the end user’s point of view, a Package contains all the files and folders of a single transfer.

The Docker volume for /data contains the files that MASV Agent uploads and downloads. Copy your file into the data folder:

FILE=cat.jpg
cp /path/to/your/"$FILE" send-tutorial/data

Now start the upload. Your application provides the Team ID, file paths (absolute paths starting with the container’s /data folder), and a Package name and description:

curl --silent --request POST \
  -H "Content-Type: application/json" \
  http://localhost:8080/api/v1/uploads -d "{ \
  \"team_id\":\"$TEAM_ID\", \
  \"paths\":[\"/data/$FILE\"], \
  \"package_name\": \"My first package\", \
  \"package_description\": \"A cat in a package\" \
}" | jq

MASV Agent starts uploading immediately in the background and returns:

{
  "package_id": "01ENXTA4MFP1LWEXEDKQK7XKV",
  "upload_id": "ccea8dc3-3af3-4e0e-b8f0-8cf23d9968e7"
}

• package_id — unique ID for the Package that MASV Agent created
• upload_id — unique ID for tracking and managing the upload

Save the upload ID:

UPLOAD_ID="your-upload-id-here"

For full details on upload types and options, see the Agent Uploads guide.

Step 6: Track progress

Use the upload ID to poll the Agent for progress. Poll no more frequently than every 5 seconds.

curl --request GET http://localhost:8080/api/v1/uploads/$UPLOAD_ID | jq

Example response (shortened):

{
  "items": [ "..." ],
  "name": "My first package",
  "progress": 417216,
  "size": 417216,
  "state": "idle",
  "package_name": "My first package",
  "package_id": "01ENXTA4MFP1LWEXEDKQK7XKV",
  "upload_id": "ccea8dc3-3af3-4e0e-b8f0-8cf23d9968e7"
}

Key properties:

• items — array of files in the Package with individual progress details
• progress and size — bytes uploaded so far and total Package size
• state — current upload status

Step 7: Finalize the upload

After the Agent finishes uploading and the state is idle, finalize the Package. Finalizing lets MASV know the Package is ready — MASV can then notify recipients, save to cloud integrations, and process any configured automations.

curl --silent --request POST http://localhost:8080/api/v1/uploads/$UPLOAD_ID/finalize | jq

Response:

{
  "code": 200
}

Your Package is ready

Your application has authenticated, created a Package, uploaded a file, and finalized the upload. The Package is now available for download in the MASV Web App.

Next steps

• MASV Agent — Full details about adding MASV transfers and automations to your application.
• Agent Docker Setup — Complete Docker configuration reference.
• Agent Uploads — All upload types with CLI and REST API examples.
• Web Uploader — A browser-based uploader SDK for web applications.
• MASV API — The RESTful API for interacting directly with the MASV cloud.