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

Add 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	Yes	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" \
  -X POST https://api.massive.app/v1/teams/$TEAM_ID/tags

Response

After a successful request, this endpoint returns 201 Created:

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

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

Fetch a Team’s tags

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

Headers

Name	Type	Required	Description
`X-API-KEY`	String	Yes	API key

URL parameters

Name	Type	Required	Description
`team_id`	String	Yes	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

Response

After a successful request, this endpoint returns 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"
  }
]

Delete 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

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

Response

After a successful request, this endpoint returns 204 No Content with no body.

Tagging

Tags can be applied to multiple entities. This section covers how to apply tags to entities that 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 checks your Team’s tags for a matching ID. If the tag does not exist, no tag will be attached and no error is returned.

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

The order of operations for applying tags:

If id was provided: get tag by ID. If found, use this tag. If not found, continue to name check.
If name was provided: check if your Team has a tag with this name. If it does, use this tag. If not, create a tag with the provided name and use it.

Packages

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

Creation

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 required to download the package
`recipients`	String[]	Yes	Email address of recipient(s)
`tag`	Tag	No	A tag object used to set the package’s 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" \
  -X POST https://api.massive.app/v1/teams/$TEAM_ID/packages

Response

After a successful request, this endpoint returns 201 Created with the package object including the applied tag.

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, provide the complete package object. To update a package’s tag, include a tag object as described in the Tag Objects section above. To remove a tag from a package, remove the tag property from the request body.

Request

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