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 each provider, 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

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:

$USER_TOKEN is the auth token returned during auth request (refer to Authorization: Login section of this document)
$TEAM_ID is the team ID returned during auth request (refer to Authorization: Login section of this document)
$TARGETDIRECTORYID is the file path structure in which to place the package folder and files. (ie. "/path/to/my/packages"). Not supported by Reach Engine or Postlab connections.

Example JSON Response

    {
        "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

Attention

At present only the amazon_s3 provider supports the cloud_to_masv direction

curl

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

Where:

$USER_TOKEN is the auth token returned during auth request (refer to Authorization: Login section of this document)
$TEAM_ID is the team ID returned during auth request (refer to Authorization: Login section of this document)
$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.

Example JSON Response

    {
        "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

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

How to upload to box with MASV

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

Create a DigitalOcean Space

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

Minio quickstart guide

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 access policy).

Method	Route
`GET`	`/teams/{team_id}/cloud_connections`

HEADERS

Name	Type	Required	Description
`X-User-Token`	String	Yes	User JSON Web Token

REQUEST

curl

curl -H `X-User-Token: $USER_TOKEN` \
-X GET https://api.massive.app/v1/teams/$TEAM_ID/cloud_connections

Where:

$USER_TOKEN is the auth token returned during auth request (refer to Authorization: Login section of this document)
$TEAM_ID is the team ID returned during auth request (refer to Authorization: Login section of this document)

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.

Example JSON Response

[
    {
        "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 access policy).

Method	Route
`PUT`	`/cloud_connections/{connection_id}`

HEADERS

Name	Type	Required	Description
`X-User-Token`	String	Yes	User JSON Web Token
`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

curl -d "{\"name\": \"$NAME\", \"authorization\": \"$\", \"authorization\": {\"$KEY1\":\"$VALUE1\", \"$KEY2\":\"$VALUE2\"}}" \
-H "X-User-Token: $USER_TOKEN" \
-H "Content-Type: application/json" \
-X PUT https://api.massive.app/v1/cloud_connections/$CONNECTION_ID

Where:

$USER_TOKEN is the auth token returned during auth request (refer to Authorization: Login section of this document)
$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.

Example JSON Response

{
    "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-User-Token`	String	Yes	User JSON Web Token
`Content-Type`	String	Yes	Must be `application/json`

REQUEST

curl

curl -H "X-User-Token: $USER_TOKEN" \
-H "Content-Type: application/json" \
-X DELETE https://api.massive.app/v1/cloud_connections/$CONNECTION_ID

Where:

$USER_TOKEN is the auth token returned during auth request (refer to Authorization: Login section of this document)
$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 attach cloud connections to a portal under any team they belong to (subject to access policy). This is managed by updating the Portal to specify the cloud connection(s) that should be attached to it - to remove a connection simply update without including it in the list of connections.

Method	Route
`PUT`	`/portals/{portal_id}`

HEADERS

Name	Type	Required	Description
`X-User-Token`	String	Yes	User JSON Web Token
`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

curl  -d '{"name": "$NAME", "subdomain": "$PORTAL_SUBDOMAIN", "cloud_connections": [{"id":"$ID1", "target_action":"transfer"}, {"id":"$ID2", "target_action":"transfer"}]}' \
-H "X-User-Token: $USER_TOKEN" \
-H "Content-Type: application/json" \
-X PUT https://api.massive.app/v1/portals/$PORTAL_ID

Where:

$USER_TOKEN is the auth token returned during auth request (refer to Authorization: Login section of this document)
$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.

Example JSON Response

{
        "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-User-Token`	String	Yes	User JSON Web Token

REQUEST

curl

curl -H `X-User-Token: $USER_TOKEN` \
-X GET https://api.massive.app/v1/teams/$TEAM_ID/portals

Where:

$USER_TOKEN is the auth token returned during auth request (refer to Authorization: Login section of this document)
$TEAM_ID is the team ID returned during auth request (refer to Authorization: Login section of this document)

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.

Example JSON Response

[
    {
        "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

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

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"},{"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
$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.

Example JSON Response

    {
        "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

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.

Example JSON Response

[
    {
        "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 package cloud delivery for any package under their team(s) subject to access policy). If the transfer has already been retried or the cloud connection is unavailable or the package has expired or it didn't fail then it cannot be retried.

Method	Route
`POST`	`/transfers/{transfer_id}/retry`

HEADERS

Name	Type	Required	Description
`X-Transfer-Token`	String	Yes	Transfer JSON Web Token

REQUEST

curl

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.

Example JSON Response

    {
        "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"
    }