Skip to content

Cloud Connect

The MASV API allows authorized users to connect their Portals to an external cloud storage provider by way of Cloud Connect. The connection details are entered once and can be reused across multiple portals. Each portal can have one or more connections attached and as new uploads are received they will be transferred automatically to each external cloud storage account.

Create Cloud Connection

Authorized users can create cloud connections under any team they belong to (subject to access policy).

Method Route
POST /teams/{{ team_id }}/cloud_connections
HEADERS
Name Type Required Description
X-API-KEY String Yes API key
Content-Type String Yes Must be application/json
BODY
Name Type Required Description
name String No Name of the connection to create
provider String Yes Cloud storage provider to connect
direction String No Direction of the cloud connection. Valid values are masv_to_cloud and cloud_to_masv. Defaults to masv_to_cloud if unspecified.
authorization Object Yes Authorization credentials, specific to each provider. See examples below.
target_directory_id String No Custom directory path in which to place the package folder and files. Only used in masv_to_cloud direction.
source_directory_ids String[] No Directories in the source cloud storage account that the filepicker should display. Useful in the case where a restricted access key is used. Only used in the cloud_to_masv direction.
REQUESTS
MASV To Cloud
curl -d "{\"name\": \"$NAME\", \"provider\": \"$PROVIDER\", \"direction\": \"masv_to_cloud\", \"authorization\": {\"$KEY1\":\"$VALUE1\", \"$KEY2\":\"$VALUE2\"}, \"target_directory_id\":\"$TARGETDIRECTORYID\"}" \
-H "X-API-KEY: $API_KEY" \
-H "Content-Type: application/json" \
-X POST https://api.massive.app/v1/teams/$TEAM_ID/cloud_connections

Where:

  • $API_KEY is a MASV API key.
  • $TEAM_ID is a MASV Team ID.
  • $TARGETDIRECTORYID is the file path structure in which to place the package folder and files. Example: "/path/to/my/packages". Not supported by Reach Engine or Postlab connections.
    {
        "created_at": "2020-10-06T12:44:19.369Z",
        "direction": "masv_to_cloud",
        "id": "01EKYZ1VH9GTS9GYMCMSR4NR9G",
        "name": "Sample Connection",
        "provider": "amazon_s3",
        "state": "ok",
        "updated_at": "2020-10-06T12:44:19.369Z"
    }

Where:

  • id is the created connection ID.
Cloud To MASV

For the cloud_to_masv direction, your application can send from the amazon_s3 and wasabi_s3 providers.

curl -d "{\"name\": \"$NAME\", \"provider\": \"$PROVIDER\", \"direction\": \"cloud_to_masv\", \"authorization\": {\"$KEY1\":\"$VALUE1\", \"$KEY2\":\"$VALUE2\"}, \"source_directory_ids\":[\"$SOURCEDIRECTORYID1\",\"$SOURCEDIRECTORYID2\"]}" \
-H "X-API-KEY: $API_KEY" \
-H "Content-Type: application/json" \
-X POST https://api.massive.app/v1/teams/$TEAM_ID/cloud_connections

Where:

  • $API_KEY is a MASV API key.
  • $TEAM_ID is a MASV Team ID.
  • $SOURCEDIRECTORYID(N) is a path in the source cloud storage account that the provided authorization grants read access to.

The credentials will be validated to ensure proper access to the storage provider account. After a successful request where a cloud connection has been created, this endpoint will return an HTTP response with a status code of 201 Created and a body similar to the one below.

    {
        "created_at": "2020-10-06T12:44:19.369Z",
        "direction": "cloud_to_masv",
        "id": "01EKYZ1VH9GTS9GYMCMSR4NR9G",
        "name": "Sample Connection",
        "provider": "amazon_s3",
        "source_directory_ids": ["$SOURCEDIRECTORYID1", "$SOURCEDIRECTORYID2"],
        "state": "ok",
        "updated_at": "2020-10-06T12:44:19.369Z"
    }

Where:

  • id is the created connection ID.

Provider Examples

MASV currently integrates with a plethora of cloud storage providers. The following examples show the provider value and authorization object that is specific to each of them.

Attention

All provider authorization fields are required, unless noted otherwise

Amazon S3

MASV supports uploading to an Amazon S3 bucket in any region.

For the masv_to_cloud case, the key must be scoped with the following permissions on the bucket:

  • s3:PutObject
  • s3:AbortMultipartUpload
  • s3:ListBucket
  • s3:DeleteObject
  • s3:GetBucketLocation

For the cloud_to_masv case, the key must be scoped with the following permissions on the bucket:

  • s3:GetObject
  • s3:ListBucket

The provider value is amazon_s3

Sample Authorization
Name Type Description
client_id String Access key ID generated in AWS with access to this bucket
client_secret String Access key secret provided by AWS for the key ID above
destination String In the masv_to_cloud case, this field denotes the name of the destination bucket that files will be transferred to. For cloud_to_masv, this field denotes the name of the source bucket.
region String AWS region that the bucket is located in (ie. us-east-1, etc.). This must match one of the region codes listed here
storage_class String The S3 storage class you want to use for transferred files. Must be one of: STANDARD, INTELLIGENT_TIERING, STANDARD_IA, ONEZONE_IA, GLACIER_IR, GLACIER, or DEEP_ARCHIVE. The default STANDARD is used if a preference is not specified in the request.
References

Azure Storage

MASV supports uploading to an Azure storage container using a Shared Access Signature (SAS) URI. This URI must be generated with access to the Blob service on resource types Object and Container and permission to Read, Write, Delete, List, Add, Create, and Update selected. The URI expiry should be set in the future at which point a new SAS URI will need to be generated and provided.

The provider value is azure

Sample Authorization
Name Type Description
blob_service_sas_url String A Blob service SAS URL generated in Azure (permissions defined above)
destination String Name of the bucket that files will be transferred to
References

Backblaze B2

MASV supports uploading to a Backblaze B2 bucket using an Application Key with Read and Write access on the target bucket.

The provider value is backblazeb2

Sample Authorization
Name Type Description
client_id String Key ID generated in Backblaze with access to this bucket
client_secret String Application key provided by Backblaze for the key ID above
destination String Name of the bucket that files will be transferred to
References

Box

MASV supports uploading to Box using a Custom Box Application that must be created first and then the contents of the configuration file must be provided as described below.

The provider value is box

Sample Authorization
Name Type Description
client_id String Client ID value in the Public/Private keypair json file generated for the Box application
client_secret String Client secret value in the Public/Private keypair json file generated for the Box application
public_key_id String Public key id value in the Public/Private keypair json file generated for the Box application
private_key String Private key value in the Public/Private keypair json file generated for the Box application. The entire key including "-----BEGIN ENCRYPTED PRIVATE KEY..." to "...END ENCRYPTED PRIVATE KEY-----" must be provided unaltered.
passphrase String Passphrase value in the Public/Private keypair json file generated for the Box application
enterprise_id String Enterprise ID value in the Public/Private keypair json file generated for the Box application
References

DigitalOcean

MASV supports uploading to a DigitalOcean Space in any region. The key must be scoped with access to read and write objects on the specified bucket.

The provider value is digital_ocean_s3

Sample Authorization
Name Type Description
client_id String Access key ID generated in DigitalOcean with access to this bucket
client_secret String Access key secret provided by DigitalOcean for the key ID above
destination String Name of the bucket that files will be transferred to
endpoint String Region URL that the bucket is stored in (ie. sfo2.digitaloceanspaces.com, nyc3.digitaloceanspaces.com, ams3.digitaloceanspaces.com)
region String DigitalOcean region that the bucket is located in (ie. sfo2, nyc3, ams3, etc.)
References

Frame.io

MASV supports uploading to a specific Frame.io project using a custom Developer Token that has the following scopes:

  • Teams: read
  • Assets: delete, create, update, read
  • Account: read
  • Project: read

The provider value is frameio

Sample Authorization
Name Type Description
developer_token String Frame.io developer token
account_id String Frame.io account that the team and project belong to
team_id String Frame.io team id that the project belongs to
project_id String Frame.io project that the files will be uploaded to
References

Google Cloud Storage

MASV supports uploading to Google Cloud Storage using a Service Account that must be created first and then the contents of the configuration file must be provided as described below. The Service Account must have the 'Storage Object Admin' role on your bucket.

The provider value is google_cloud_storage

Sample Authorization
Name Type Description
client_email String Client Email of the GCS Service Account
private_key String Private Key from the GCS Service Account. The entire key including "-----BEGIN PRIVATE KEY..." to "...END PRIVATE KEY-----" must be provided unaltered.
destination String Name of the bucket that files will be transferred to
References

Iconik

MASV supports uploading to a Iconik using a custom Application Token in Iconik. This application token is tied to a user inside of the Iconik platform.

The provider value is iconik

Iconik Permissions

The user that creates an application token must be an admin user. A power user should be tied to the application with the following permissions enabled:

Name Permissions
assets create, delete, purge, write
collections create, delete, purge, write
files delete, purge, read, write
formats create, write
jobs delete, write
metadata fields read, write
metadata views read, write
storages read
transcode jobs create
Sample Authorization
Name Type Description
application_id String Iconik application id
application_token String Iconik application token
storage_id String Iconik storage account that files should be placed in
References

Minio

MASV supports uploading to a Minio bucket using an access key. The key must be scoped with access to read and write objects on the specified bucket.

The provider value is minio_s3

Sample Authorization
Name Type Description
client_id String Access key ID generated in Minio with access to this bucket
client_secret String Access key secret provided by Minio for the key ID above
destination String Name of the bucket that files will be transferred to
endpoint String URL for the bucket
region String Region URL that the bucket is stored, typically "default" unless you have configured special regions or subdomains for the minio bucket
force_s3_path_style String Boolean indicates whether the bucket name should be placed as a subdomain or as part of the path (ie. https://bucketname.endpoint/ vs https://endpoint/bucketname)
References

PostLab

MASV supports uploading to a specific PostLab team using a team key.

The provider value is postlab

Sample Authorization
Name Type Description
team_id String Postlab team key - You can obtain the team key by opening Postlab app Preferences, then going to Integrations > MASV.

Object Matrix

MASV supports uploading to an Object Matrix storage bucket using an access key and secret. The key must be scoped with access to read and write objects on the specified bucket.

The provider value is object_matrix_s3

Sample Authorization
Name Type Description
client_id String Access key ID generated in Object Matrix with access to this bucket
client_secret String Access key secret provided by Object Matrix for the key ID above
destination String Name of the bucket that files will be transferred to
endpoint String URL that the bucket is stored in (ie. spacename.matrixstore.cloud:12323)
region String Must be eu as Object Matrix only supports one region

Reach Engine

MASV supports uploading to Reach Engine using an API Key and API Base Path. This key is tied to a user inside of the Reach Engine platform.

The provider value is reach_engine

Reach Engine Permissions

An admin user should be tied to the API Key with the following roles enabled. Many of these are granted automatically to admins:

Name Permissions
Modify Asset Categories true
Modify Asset Details true
Create Collections true
Modify Collection Contents true
Modify Timeline Contents true
Sample Authorization
Name Type Description
api_base_path String Reach Engine api base
api_key String API Key generated in Reach Engine
workflow_id String Reach Engine workflow that uploads are tied to
storage_id String Reach Engine storage account that files should be placed in

We recommend using the "Panel Ingest Folder to Collection with Sidecar" (workflow_id: panelIngestFolderToCollectionWithSidecar) workflow with the checkForDuplicate setting disabled to avoid the possibility of files that have the same name being combined.

Wasabi

MASV supports uploading to a Wasabi Cloud Storage in any region using an access key. The key must be scoped with access to read and write objects on the specified bucket.

The provider value is wasabi_s3

Sample Authorization
Name Type Description
client_id String Access key ID generated in Wasabi with access to this bucket
client_secret String Access key secret provided by Wasabi for the key ID above
destination String Name of the bucket that files will be transferred to
endpoint String Region URL that the bucket is stored in (ie. s3.us-east-1.wasabisys.com)
region String Wasabi region that the bucket is located in (ie. us-east-1, us-east-2, us-west-1, etc.)
References

Seagate Lyve Cloud

MASV supports uploading to a Seagate Lyve Cloud Storage in any region using an access key. The key must be scoped with access to read and write objects on the specified bucket.

The provider value is lyve_cloud_s3

Sample Authorization
Name Type Description
client_id String Access key ID generated in Lyve Cloud with access to this bucket
client_secret String Access key secret provided by Lyve Cloud for the key ID above
destination String Name of the bucket that files will be transferred to
endpoint String Region URL that the bucket is stored in (ie. s3.us-west-1.lyvecloud.seagate.com)
region String Lyve Cloud region that the bucket is located in (ie. us-east-1, us-east-2, us-west-1, etc.)
References

Storj

MASV supports uploading to Storj object storage bucket using an Amazon S3 compatible access key. The key must be scoped with access to read and write objects on the specified bucket.

The provider value is storj_s3

Sample Authorization
Name Type Description
client_id String Access key ID generated in Storj with access to this bucket
client_secret String Access key secret provided by Storj for the key ID above
destination String Name of the bucket that files will be transferred to
endpoint String URL provided by Storj that the bucket is stored in (ie. https://gateway.storjshare.io)
region String Should be hardcoded to default on requests
References

Other S3 Compatible Storage

MASV supports uploading to any S3 Compatible cloud storage provider. The access key must be scoped so that it can read and write objects on the specified bucket.

The provider value is generic_s3

Sample Authorization
Name Type Description
client_id String Access key ID generated in provider with access to this bucket
client_secret String Access key secret provided by provider for the key ID above
destination String Name of the bucket that files will be transferred to
endpoint String URL for the bucket
region String Region URL that the bucket is stored - if there isn't one you may pass "default"
force_s3_path_style String Boolean indicates whether the bucket name should be placed as a subdomain or as part of the path (ie. https://bucketname.endpoint/ vs https://endpoint/bucketname)

List Cloud Connections

Authorized users can list all cloud connections under any Team they belong to, subject to the MASV access policy.

Method Route
GET /teams/{team_id}/cloud_connections
HEADERS
Name Type Required Description
X-API-KEY String Yes API key
REQUEST
curl -H -H "X-API-KEY: $API_KEY" \
-X GET https://api.massive.app/v1/teams/$TEAM_ID/cloud_connections

Where:

After a successful request, this endpoint will return an HTTP response with a status code of 200 OK and a body similar to the one below.

[
    {
        "connections": 1,
        "created_at": "2020-08-18T13:29:06.698Z",
        "id": "01EG0W4MWA5CA1DXXZRFBRC4VM",
        "name": "Backblaze Bucket",
        "provider": "backblazeb2",
        "state": "ok",
        "target_directory_id": "/path/to/my/packages",
        "updated_at": "2020-08-18T09:29:06.701Z"
    },
    {
        "created_at": "2020-08-28T14:03:05.623Z",
        "id": "01EGTP220QMPHMMF9JDN1KJQTE",
        "name": "Postlab Account",
        "provider": "postlab",
        "state": "ok",
        "updated_at": "2020-08-28T10:04:31.337Z",
        "destination": "transfers",
        "region": "us-east-1"
    },
    ...
]

Note

The destination and region properties are returned for supported providers (Amazon S3, Minio, etc)

Update Cloud Connection

Authorized users can update cloud connections under any Team they belong to, subject to the MASV access policy.

Method Route
PUT /cloud_connections/{connection_id}
HEADERS
Name Type Required Description
X-API-KEY String Yes API key
Content-Type String Yes Must be application/json
BODY
Name Type Required Description
name String No Name of the connection
authorization Object No Authorization credentials - specific each provider
REQUEST
curl -d "{\"name\": \"$NAME\", \"authorization\": \"$\", \"authorization\": {\"$KEY1\":\"$VALUE1\", \"$KEY2\":\"$VALUE2\"}}" \
-H "X-API-KEY: $API_KEY" \
-H "Content-Type: application/json" \
-X PUT https://api.massive.app/v1/cloud_connections/$CONNECTION_ID

Where:

  • $API_KEY is a MASV API key
  • $CONNECTION_ID is the connection ID returned during creation

Any authorization properties that are not provided will be assumed to be unchanged. The credentials will be validated to ensure proper access to the storage provider account.

After a successful request where a cloud connection has been updated, this endpoint will return an HTTP response with a status code of 200 OK and a body similar to the one below.

{
    "created_at": "2020-10-06T12:44:19.369Z",
    "id": "01EKYZ1VH9GTS9GYMCMSR4NR9G",
    "name": "Sample Connection",
    "provider": "amazon_s3",
    "state": "ok",
    "updated_at": "2020-10-06T12:44:19.369Z",
    "destination": "transfers",
    "region": "us-east-1"
}

Note

The destination and region properties are returned for supported providers (Amazon S3, Minio, etc)

Delete Cloud Connection

Authorized users can delete cloud connections under any team they belong to (subject to access policy).

Method Route
DELETE /cloud_connections/{connection_id}
HEADERS
Name Type Required Description
X-API-KEY String Yes API key
Content-Type String Yes Must be application/json
REQUEST
curl -H "X-API-KEY: $API_KEY" \
-H "Content-Type: application/json" \
-X DELETE https://api.massive.app/v1/cloud_connections/$CONNECTION_ID

Where:

  • $API_KEY is a MASV API key
  • $CONNECTION_ID is the connection ID returned during creation

After a successful deletion request, this endpoint will return an HTTP response with a status code of 204 No Content and an empty body. Any transfers that are in progress at the time of deletion will complete normally, however the associated portal recipients may not be notified. Any failed transfers will not be retriable once the connection has been deleted.

Using Cloud Connections

Once cloud connections are created, they have to be connected to any number of portals in order to enable automated delivery of packages uploaded to these portals into the specified connection. This section demonstrates how this can be achieved and show you how you can monitor the state of package deliveries.

Note

This section is focused on managing cloud connections only, for more details on managing Portals and a description of each property please refer to the Portals section of the API documentation

Attach Cloud Connection to Portal

Authorized users can enable a cloud connections for a Portal under any Team they belong to, subject to access policy. This is managed by updating the Portal with a list of cloud connections to enable for it. To disable a connection for a Portal, simply update the Portal without including it in the list of connections.

Method Route
PUT /portals/{portal_id}
HEADERS
Name Type Required Description
X-API-KEY String Yes API key
Content-Type String Yes Must be application/json
BODY
Name Type Required Description
cloud_connections Array of connections No List of associated connections
name String Yes Name of the portal to update
subdomain String Yes Subdomain of the portal to update
access_code String If has_access_code true Access code to be able to access portal upload page
has_access_code Boolean No Enable/disable access code for portal page
active Boolean Yes Enable/disable portal page
configure_cloud_connections Boolean Yes Tells the api we want to update cloud_connections
# CLOUD CONNECTION
Name Type Required Description
id String Yes ID of cloud connection
target_action String Yes Action to be taken with cloud connection
REQUEST
curl  -d '{"name": "$NAME", "subdomain": "$PORTAL_SUBDOMAIN", "cloud_connections": [{"id":"$ID1", "target_action":"transfer"}, {"id":"$ID2", "target_action":"transfer"}]}' \
-H "X-API-KEY: $API_KEY" \
-H "Content-Type: application/json" \
-X PUT https://api.massive.app/v1/portals/$PORTAL_ID

Where:

  • $API_KEY is a MASV API key
  • $PORTAL_ID is the Portal ID to update
  • $NAME is the Portal name (all Portal properties are required on update)
  • $ID1 the first cloud connection, $ID2 the second cloud connection, etc.

Attention

All attached cloud connections must be provided in each update or else they will be removed.

After a successful request where a portal has been updated, this endpoint will return an HTTP response with a status code of 200 OK and a body similar to the one below.

{
        "active": true,
        "cloud_connections": [
            {
                "connections": 1,
                "created_at": "2020-09-15T13:32:27.906Z",
                "id": "01EJ8ZEXC2T8D1Y3ZAR3E6GGFB",
                "name": "Frame.io",
                "provider": "frameio",
                "state": "ok",
                "target_action": "transfer",
                "updated_at": "2020-09-15T10:34:39.442Z"
            },
            {
                "connections": 1,
                "created_at": "2020-09-15T13:46:37.854Z",
                "id": "01EJ908VCYMECVH5SPAV9YN92B",
                "name": "BackBlaze",
                "provider": "backblazeb2",
                "state": "ok",
                "target_action": "transfer",
                "updated_at": "2020-09-15T10:33:31.962Z"
            }
        ],
        "created_at": "2020-01-09T10:45:01.437Z",
        "id": "01DY5FNYFXQDZ5NBX482ZAMRG8",
        "name": "My Portal",
        "recipients": [],
        "subdomain": "myportal",
        "updated_at": "2020-10-06T16:18:28.034Z"
    }

List Portal Cloud Connections

Authorized users can list the cloud connections on a Portal under any Team they belong to (subject to access policy). This is visible by retrieving the list of Portals.

Method Route
GET /teams/{team_id}/portals
HEADERS
Name Type Required Description
X-API-KEY String Yes API key
REQUEST
curl -H "X-API-KEY: $API_KEY" \
-X GET https://api.massive.app/v1/teams/$TEAM_ID/portals

Where:

After a successful request, this endpoint will return an HTTP response with a status code of 200 OK and a body similar to the one below.

[
    {
        "id": "01CNH24NGPTJTMXWWM2J8E2V8V",
        "message": "Hello world!",
        "name": "My portal",
        "subdomain": "myportal",
        "has_access_code": false,
        "recipients": [
            "[email protected]",
            "[email protected]"
        ],
        "cloud_connections": [
            {
                "connections": 1,
                "created_at": "2020-09-15T13:32:27.906Z",
                "id": "01EJ8ZEXC2T8D1Y3ZAR3E6GGFB",
                "name": "Frame.io",
                "provider": "frameio",
                "state": "ok",
                "target_action": "transfer",
                "updated_at": "2020-09-15T10:34:39.442Z"
            },
            {
                "connections": 2,
                "created_at": "2020-09-15T13:46:37.854Z",
                "id": "01EJ908VCYMECVH5SPAV9YN92B",
                "name": "BackBlaze",
                "provider": "backblazeb2",
                "state": "ok",
                "target_action": "transfer",
                "updated_at": "2020-09-15T10:33:31.962Z"
            }
        ],

    },
    {
        "id": "01CNEM9H2AG0MVH33X0EVDY8AQ",
        "message": "Hello world, again!",
        "name": "My other portal",
        "subdomain": "myotherportal",
        "has_access_code": false,
        "recipients": [
            "[email protected]"
        ],
        "cloud_connections": [
            {
                "connections": 5,
                "created_at": "2020-09-15T13:32:27.906Z",
                "id": "01EJ8ZEXC2T8D1Y3ZAR3E6GGFB",
                "name": "Amazon S3",
                "provider": "amazon_s3",
                "state": "ok",
                "target_action": "transfer",
                "updated_at": "2020-09-15T10:34:39.442Z"
            },
            {
                "connections": 2,
                "created_at": "2020-09-15T13:46:37.854Z",
                "id": "01EJ908VCYMECVH5SPAV9YN92B",
                "name": "BackBlaze",
                "provider": "backblazeb2",
                "state": "ok",
                "target_action": "transfer",
                "updated_at": "2020-09-15T10:33:31.962Z"
            }
        ],
    },
    ...
]

Initiate a Manual Package Transfer

Authorized users can manually initiate a package transfer using an existing cloud connection for any package under their Team(s) (subject to access policy).

Method Route
POST /packages/{package_id}/transfer
HEADERS
Name Type Required Description
X-Package-Token String Yes Package JSON Web Token
BODY
Name Type Required Description
cloud_connection_id String Yes ID of Cloud Connection to send the package to
notify_email String No Email address to notify when transfer has completed
files Object[] No List of files/directories that the connection should transfer. Only valid in the cloud_to_masv direction.
REQUEST
MASV To Cloud
curl -H "X-Package-Token: $PACKAGE_TOKEN" -H "Content-Type: application/json" -X POST https://api.massive.app/v1/packages/$PACKAGE_ID/transfer \ 
    -d '{"notify_email": "$EMAIL", "cloud_connection_id": "$CONNECTIONID"}'

Where:

  • $PACKAGE_ID is the ID of the package
  • $PACKAGE_TOKEN is the package access token
Cloud To MASV

In the Cloud To MASV direction, an empty team package must first be created by the user (Create a team package). This package will act as the destination for all of the files included in the transfer. The ID/Token fields of the created package are required when initiating the Cloud To MASV transfer. Remember not to add any files to the Cloud To MASV package or manually finalize the package, as the cloud uploader will perform both of these operations after the cloud transfer is initiated.

curl -H "X-Package-Token: $PACKAGE_TOKEN" -H "Content-Type: application/json" -X POST https://api.massive.app/v1/packages/$PACKAGE_ID/transfer \ 
    -d '{"notify_email": "$EMAIL", "cloud_connection_id": "$CONNECTIONID", "files":[{"id":"$FILEID","name":"$FILENAME","path":"$FILEPATH","kind":"file","size": $FILE_SIZE},{"id":"$DIR","kind":"directory"}]}'

Where:

  • $PACKAGE_ID is the ID of the package to which to transfer the files
  • $PACKAGE_TOKEN is the package access token to which to transfer files
  • $FILEID is the id of a single file in cloud storage to add to the transfer
  • $FILENAME is the name that will be assigned to the single file once transferred to the package
  • $FILEPATH is relative path within the package of the single file
  • $FILE_SIZE is the size in bytes of the file (not needed for directories)
  • $DIR is the id of a directory in cloud storage. The entire directory contents will be added to the transfer recursively

Attention

Passing both an individual file and a directory containing said individual file will result in a package containing duplicate items.

After a successful request, this endpoint will return an HTTP response with a status code of 201 Created and a body similar to the one below.

    {
        "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2MDI4NjE1NDAsImltcCI6ZmFsc2UsImxpZCI6IjAxRUszNzdDM1IzMzNBMFZWMFFZVjcyWjRaIiwibHZsIjoiIiwicGlkIjoiMDFFSzM3N0MxU0pDQlQ3VzY3S0ZNWTY5S1oiLCJzdWIiOiIwMUVNNzlFMFJCRUFGRkMzOTZSRkczTlJOQiIsInR5cCI6InRyYW5zZmVyIn0.hFw1C_ME4xlhKFBzoI7L8ZZuqKS_DwvifTLi-y428MY",
        "created_at": "2020-10-06T19:25:54.206Z",
        "id": "01EKZP15MYQGJKW90N60AJHC9N",
        "provider": "google_cloud_storage",
        "retriable": false,
        "state": "pending",
        "updated_at": "2020-10-06T19:28:50.003Z"
    }

View Package Cloud Delivery Status

Authorized users can list package cloud deliveries for any package under their Team(s) subject to access policy). The listing will include all transfers that are a associated to the uploaded package.

Method Route
GET /packages/{package_id}/transfer
HEADERS
Name Type Required Description
X-Package-Token String Yes Package JSON Web Token
REQUEST
curl -H "X-Package-Token: $PACKAGE_TOKEN" \
-X GET https://api.massive.app/v1/packages/$PACKAGE_ID/transfer

Where:

  • $PACKAGE_ID is the ID of the package
  • $PACKAGE_TOKEN is the package access token

After a successful request, this endpoint will return an HTTP response with a status code of 200 OK and a body similar to the one below.

[
    {
        "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2MDI4NjE1NDAsImltcCI6ZmFsc2UsImxpZCI6IjAxRUszNzdDM1IzMzNBMFZWMFFZVjcyWjRaIiwibHZsIjoiIiwicGlkIjoiMDFFSzM3N0MxU0pDQlQ3VzY3S0ZNWTY5S1oiLCJzdWIiOiIwMUVNNzlFMFJCRUFGRkMzOTZSRkczTlJOQiIsInR5cCI6InRyYW5zZmVyIn0.hFw1C_ME4xlhKFBzoI7L8ZZuqKS_DwvifTLi-y428MY",
        "created_at": "2020-10-06T19:25:54.206Z",
        "id": "01EKZP15MYQGJKW90N60AJHC9N",
        "provider": "google_cloud_storage",
        "retriable": false,
        "state": "completed",
        "updated_at": "2020-10-06T19:28:50.003Z"
    },
    {
        "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2MDI4NjE1NDAsImltcCI6ZmFsc2UsImxpZCI6IjAxRUszNzdDM1IzMzNBMFZWMFFZVjcyWjRaIiwibHZsIjoiIiwicGlkIjoiMDFFSzM3N0MxU0pDQlQ3VzY3S0ZNWTY5S1oiLCJzdWIiOiIwMUVNNzlFMFJCRUFGRkMzOTZSRkczTlJOQiIsInR5cCI6InRyYW5zZmVyIn0.hFw1C_ME4xlhKFBzoI7L8ZZuqKS_DwvifTLi-y428MY",
        "created_at": "2020-10-06T19:23:42.521Z",
        "error_message": "insufficient_space",
        "id": "01EKZNX51ST2ZH1Z1AN2BBJ5WM",
        "provider": "frameio",
        "retriable": true,
        "state": "error",
        "updated_at": "2020-10-06T19:23:42.522Z"
    },
    ...
]

Where:

  • id is the transfer ID
  • state is the state of transfer, can be one of:
    • pending: the transfer has been queued and/or is in progress
    • completed: the transfer has finished successfully
    • cancelled: the transfer was aborted
    • error: the transfer failed, look at the error_message for a reason
  • error_message is an error key indicating why the transfer failed (if state is error), can be one of:
    • authentication_failed: the credentials supplied in the cloud connection were rejected by the cloud storage provider, either because they are invalid or have insufficient permissions
    • provider_unavailable: the cloud storage provider was unavailable and all automatic retry attempts were unsuccessful, possibly due to an outage or incorrect configuration
    • insufficient_space: the cloud storage provider indicated that there is not enough space for the package or that usage limits have been exceeded
    • directory_not_found: the target directory to place the package in does not exist or could not be created
    • provider_upload_limit_exceeded: the upload limit for the cloud storage provider has been exceeded
    • provider_activity_limit_exceeded: an activity quota for the cloud storage provider has been exceeded due to too many requests in a short period of time
    • provider_item_limit_exceeded: the cloud storage provider indicated that there are too many items in a single directory
  • provider is the cloud storage provider
  • retriable indicates if this transfer can be retried (refer to Cloud Connect: Retry a Failed Transfer of this document)
  • access_token is an authentication token used for managing the transfer on subsequent requests

Retry a Failed Transfer

Authorized users can retry a failed MASV-to-cloud delivery of any package in their Teams subject to the access policy). Cloud-to-MASV transfers cannot be retried, they must be re-created.

Retrying a cloud delivery will have no effect in any of these situations:

  • The transfer has already been retried.
  • The cloud connection is unavailable.
  • The package has expired.
  • The cloud delivery didn't fail.
Method Route
POST /transfers/{transfer_id}/retry
HEADERS
Name Type Required Description
X-Transfer-Token String Yes Transfer JSON Web Token
REQUEST
curl -H "X-Transfer-Token: $TRANSFER_TOKEN" \
-X POST https://api.massive.app/v1/transfers/$TRANSFER_ID/retry

Where:

  • $TRANSFER_TOKEN is the transfer access token
  • $TRANSFER_ID is the transfer to be retried

After a successful request, this endpoint will return an HTTP response with a status code of 201 Created and a body similar to the one below.

    {
        "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2MDI4NjE1NDAsImltcCI6ZmFsc2UsImxpZCI6IjAxRUszNzdDM1IzMzNBMFZWMFFZVjcyWjRaIiwibHZsIjoiIiwicGlkIjoiMDFFSzM3N0MxU0pDQlQ3VzY3S0ZNWTY5S1oiLCJzdWIiOiIwMUVNNzlFMFJCRUFGRkMzOTZSRkczTlJOQiIsInR5cCI6InRyYW5zZmVyIn0.hFw1C_ME4xlhKFBzoI7L8ZZuqKS_DwvifTLi-y428MY",
        "created_at": "2020-10-06T19:25:54.206Z",
        "id": "01EKZP15MYQGJKW90N60AJHC9N",
        "provider": "google_cloud_storage",
        "retriable": false,
        "state": "pending",
        "updated_at": "2020-10-06T19:28:50.003Z"
    }