Tags

Tags can be assigned to packages to facilitate better package tracking and searching. One package can only have one active tag at a time.

Tag Management

Adding a new tag

Method	Route
`POST`	`/teams/{team_id}/tags`

HEADERS

Name	Type	Required	Description
`X-User-Token`	String	Yes	User JSON Web Token
`Content-Type`	String	Yes	Must be `application/json`

URL Parameters

Name	Type	Required	Description
`team_id`	String	In `/teams` routes	The team id to bind the tag to.

BODY

Name	Type	Required	Description
`name`	String	Yes	The name you want to give the new tag.

REQUEST

curl

  curl -d '{"name": "$NAME"}' \
  -H "X-User-Token: $USER_TOKEN" \
  -H "Content-Type: application/json" \
  -s -X POST https://api.massive.app/v1/teams/$TEAM_ID/tags

After a successful request where a tag 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

{
  "id": "01FZGG2QQQTJV9CJ1Q2ZNXVKCQ",
  "name": "test",
  "team_id": "01FX8CYWMQAEGW8AYSNQRGAMRM",
  "active": true,
  "created_at": "2022-03-31T17:23:57.815Z",
  "updated_at": "2022-03-31T13:23:57.815Z"
}

Response Properties:

Property	Description
`id`	The ID of the newly created tag.
`name`	The name you gave the tag.
`team_id`	The ID of the team this tag belongs to.
`active`	Whether or not this tag is active.
`created_at`	When this tag was created.
`updated_at`	When this tag was last updated at.

Fetching a team's tags

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

HEADERS

Name	Type	Required	Description
`X-User-Token`	String	Yes	User JSON Web Token
`Content-Type`	String	Yes	Must be `application/json`

URL Parameters

Name	Type	Required	Description
`team_id`	String	In `/teams` route	The ID of the team whose tags you are fetching.

REQUEST

curl

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

After a successful request, this endpoint will return HTTP status code 200 OK.

Example JSON Response

[
  {
      "id": "01FZGG2QQQTJV9CJ1Q2ZNXVKCQ",
      "name": "test",
      "team_id": "01FX8CYWMQAEGW8AYSNQRGAMRM",
      "active": true,
      "created_at": "2022-03-31T17:23:57.815Z",
      "updated_at": "2022-03-31T13:23:57.815Z"
  },
  ...
]

Response Properties:

Property	Description
`id`	The ID of the newly created tag
`name`	The name you gave the tag
`team_id`	The ID of the team this tag belongs to
`active`	Whether or not this tag is active
`created_at`	When this tag was created
`updated_at`	When this tag was last updated at

Deleting a tag

To delete a tag, you will need its ID.

Method	Route
`DELETE`	`/tags/{tag_id}`

HEADERS

Name	Type	Required	Description
`X-User-Token`	String	Yes	User JSON Web Token
`Content-Type`	String	Yes	Must be `application/json`

URL Parameters

Name	Type	Required	Description
`tag_id`	String	Yes	The ID of the tag you wish to delete.

REQUEST

curl

  curl -H "X-User-Token: $USER_TOKEN" \
  -X DELETE https://api.massive.app/v1/tags/$TAG_ID

After a successful request, this endpoint will return HTTP status code 204 No Content and no body data will be returned.

Tagging

Tags can be applied to multiple entities. This section will cover how to apply tags to entities which support it.

Tag Objects

Tags are received as a JSON object containing one or more of the following properties:

Name	Type	Description
`id`	String	The ID of the tag you wish to apply.
`name`	String	The name of the tag you wish to apply.

If ID is provided, the API will check your team's tags to see if you have a tag matching that ID. If the tag does not exist, no tag will be attached. An error will not be returned.

If name was provided and ID was either not provided or invalid, a tag will be found or created on your team using the provided name.

To summarize, the order of operations for applying tags is as follows:

If id was provided:
1. Get tag by ID,
2. If found, use this tag.
3. If not found, continue to name check (2)
If name was provided:
1. Check if your team has a tag with this name,
2. If it does, use this tag.
3. If not, create a tag with the provided name and use it.

Note

If the tag object is not provided or is empty, no tag will be applied. In the case of updating tags, tag being empty or missing will result in the current tag being removed.

Packages

You can tag packages on creation or on update using the correct API endpoints.

Creation

Note

This section exclusively is for team packages, not portal packages. Portal packages are covered in a later section.

Method	Route
`POST`	`/teams/{team_id}/packages`

HEADERS

Name	Type	Required	Description
`X-User-Token`	String	Yes	User JSON Web Token
`Content-Type`	String	Yes	Must be `application/json`

URL PARAMETERS

Name	Type	Required	Description
`team_id`	String	Yes	The ID of the team to create a package on.

BODY

Name	Type	Required	Description
`access_limit`	Integer	No	Override default number of downloads for the package
`description`	String	Yes	Description of the package
`name`	String	Yes	Name of the package
`password`	String	No	Password to protect download access to the package
`recipients`	String[]	Yes	Email address of recipient(s)
`tag`	Tag (see above)	No	A tag object used to set the package's tag.

Example Request Body (1)

{
  "name": "Test Package Name",
  "description": "Test Package Description",
  "recipients": [ "[email protected]" ],
  "tag": {
    "id": "01FZK59ETEWFW3ZBFA34A83YME"
  }
}

Example Request Body (2)

{
  "name": "Test Package Name",
  "description": "Test Package Description",
  "recipients": [ "[email protected]" ],
  "tag": {
    "name": "test tag"
  }
}

REQUEST

curl

  curl -d '{"name":"$NAME","description":"$DESCRIPTION","recipients":[$RECIPIENTS],"tag":{"name":"test tag"}}' \
  -H "X-User-Token: $USER_TOKEN" \
  -H "Content-Type: application/json" \
  -s -X POST https://api.massive.app/v1/teams/$TEAM_ID/packages

After a successful request where a package 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 Response

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2NDk4NjUwNTUsImltcCI6ZmFsc2UsImx2bCI6ImYiLCJzdWIiOiIwMUZaWlM0UEJNRk1aUVZSODk0S0tBTkJWUCIsInR5cCI6InBhY2thZ2UiLCJ1aWQiOiIwMUZYOENZV01QVFhYNThXUTBLMkhQUlZWNyJ9.9HUYpEG3_TulBq8O87qwfT4oAl2Wyct1o3ubLQmJAlM",
  "created_at": "2022-04-06T15:50:55.604Z",
  "custom_expiry": false,
  "description": "Test Package Description",
  "expiry": "2022-04-16T15:50:55.600Z",
  "extra_storage": false,
  "extra_storage_updated_at": "2022-04-06T15:50:55.604Z",
  "extras": {
    "storage_id": "minio-local"
  },
  "id": "01FZZS4PBMFMZQVR894KKANBVP",
  "name": "Test Package Name",
  "progress_channels": [],
  "recipients": [
    "[email protected]"
  ],
  "state": "new",
  "tag": {
    "id": "01FZZS4PBG0F2VCJ3ANGSYPCDC",
    "name": "test tag"
  },
  "updated_at": "2022-04-06T15:50:55.604Z",
  "usage_updated_at": "2022-04-06T15:50:55.604Z"
}

Updating

Method	Route
`PUT`	`/packages/{package_id}`

HEADERS

Name	Type	Required	Description
`X-Package-Token`	String	Yes	Package JSON Web Token with write access
`Content-Type`	String	Yes	Must be `application/json`

URL PARAMETERS

Name	Type	Required	Description
`package_id`	String	Yes	The ID of the package being updated.

BODY

When updating a package, you should provide the complete package object. All fields will not be listed here for sake of brevity.

To update a package's tag, you provide a tag object just like in the above package creation section. See the above "Tag Objects" section to see how tags are set/updated.

To remove a tag from a package, remove the tag property from the request body.

Example Request Body

{
  "created_at": "2022-04-06T15:58:09.620Z",
  "custom_expiry": false,
  "description": "Test Package Description",
  "expiry": "2022-04-16T15:58:09.620Z",
  "extra_storage": false,
  "extra_storage_updated_at": "2022-04-06T15:58:09.620Z",
  "id": "01FZZSHY6MW6HVJWQJRED053BQ",
  "name": "Test Package Name",
  "sender": "[email protected]",
  "size": 5559,
  "state": "finalized",
  "tag": {
      "id": "<updated tag ID>",
      OR
      "name": "<updated tag name>"
  },
  "total_files": 1,
  "updated_at": "2022-04-06T11:58:17.762Z",
  "usage_updated_at": "2022-04-06T15:58:09.620Z"
}

REQUEST

curl

  curl -d '{"tag":{"name":"new tag name"}}' \
  -H "X-Package-Token: $PACKAGE_TOKEN" \
  -H "Content-Type: application/json" \
  -s -X PUT https://api.massive.app/v1/packages/$PACKAGE_ID

Note

The above curl example only includes the tag field. You should include all package fields in your own requests.

After a successful request where a package 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 Response

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2NDk4NjU1MjEsImltcCI6ZmFsc2UsImx2bCI6ImYiLCJzdWIiOiIwMUZaWlNIWTZNVzZIVkpXUUpSRUQwNTNCUSIsInR5cCI6InBhY2thZ2UiLCJ1aWQiOiIwMUZaWlNIWTZNVzZIVkpXUUpSRUQwNTNCUSJ9.TZoLAKB97IYM0RkfBC_zXlD0Oh6vf6sgaKyrrzqXsV8",
  "contains_virus": false,
  "created_at": "2022-04-06T15:58:09.620Z",
  "custom_expiry": false,
  "description": "Test Package Description",
  "expiry": "2022-04-16T15:58:09.620Z",
  "extra_storage": false,
  "extra_storage_updated_at": "2022-04-06T15:58:09.620Z",
  "id": "01FZZSHY6MW6HVJWQJRED053BQ",
  "name": "Test Package Name",
  "sender": "[email protected]",
  "size": 5559,
  "state": "finalized",
  "tag": {
      "id": "01FZK59ETEWFW3ZBFA34A56LKA",
      "name": "new tag name"
  },
  "total_files": 1,
  "updated_at": "2022-04-06T11:58:17.762Z",
  "usage_updated_at": "2022-04-06T15:58:09.620Z"
}