Skip to content

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-API-KEY String Yes API key
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 -d '{"name": "$NAME"}' \
  -H "X-API-KEY: $API_KEY" \
  -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.

{
  "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-API-KEY String Yes API key
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 -H "X-API-KEY: $API_KEY" \
  -X GET https://api.massive.app/v1/teams/$TEAM_ID/tags

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

[
  {
      "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-API-KEY String Yes API key
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 -H "X-API-KEY: $API_KEY" \
  -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:

  1. If id was provided:
    1. Get tag by ID,
    2. If found, use this tag.
    3. If not found, continue to name check (2)
  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-API-KEY String Yes API key
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.
{
  "name": "Test Package Name",
  "description": "Test Package Description",
  "recipients": [ "[email protected]" ],
  "tag": {
    "id": "01FZK59ETEWFW3ZBFA34A83YME"
  }
}
{
  "name": "Test Package Name",
  "description": "Test Package Description",
  "recipients": [ "[email protected]" ],
  "tag": {
    "name": "test tag"
  }
}
REQUEST
  curl -d '{"name":"$NAME","description":"$DESCRIPTION","recipients":[$RECIPIENTS],"tag":{"name":"test tag"}}' \
  -H "X-API-KEY: $API_KEY" \
  -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.

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

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

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