Filters

The MASV API allows Team Owners and Admins to route files within a package to specific Portal cloud connections by creating and applying filters.

A filter is a named collection of filter rules used to determine which files should be transferred to the associated connection. This allows you to ingest packages with a single MASV Portal and transfer only specific files to the connections you want. For example, for a package that includes three different file types, you can apply a MASV filter to route each file type to a different connection.

A filter combines all rules into a single expression using the AND operation. A filter must have at least one rule. The maximum number of rules per filter is 20. Each rule in the filter must reference a unique criterion. For example, you cannot have two rules in the same filter with a criterion set to file_name.

Filter rules

A filter rule is composed of the following components:

An action
A criterion
An operator
Value(s)

The basic structure of a filter rule is: “action files when/where criterion operator values”. For example, “include files where file name regex matches \.(?i)(jpe?g|png|gif)$”.

Name	Type	Required	Description
`action`	String	Yes	The action for the filter rule
`criterion`	String	Yes	The criterion for the filter rule
`operator`	String	Yes	The operator for the filter rule
`values`	String[]	Yes	The values for the filter rule

Filter rule actions

Action	Description
`include`	Includes any files that match this rule in the transfer
`exclude`	Excludes any files that match this rule from the transfer

Filter rule criteria

Criterion	Description
`file_name`	Extracts the file name from the file for comparison in the rule

Filter rule operators

Operator	Description
`regex_match`	Evaluates to true if the criterion regex matches the pattern specified by the value

Filter rule values

A value refers to the input specified for a rule and uses a pattern determined by the type of operator and criterion. Values are constrained by the following requirements:

If the file_name criterion is selected and the operator is regex_match, the value must be a valid regex string.

Creating a filter

Method	Route
`POST`	`/v1/teams/{team_id}/filters`

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	Yes	Name of the filter
`rules`	FilterRule[]	Yes	An array of filter rules to associate with this filter

Request

curl -d '{"name": "$FILTER_NAME", "rules": [$FILTER_RULES]}' \
  -H "X-API-KEY: $API_KEY" \
  -H "Content-Type: application/json" \
  -X POST https://api.massive.app/v1/teams/$TEAM_ID/filters

Response

After a successful request, this endpoint returns 201 Created:

{
  "name": "Test Filter",
  "id": "01FV2TB1KHRFQJ76MEWPKDX2G9",
  "created_at": "2025-10-07T19:07:09.101Z",
  "updated_at": "2025-10-07T19:07:09.101Z",
  "rules": [
    {
      "action": "include",
      "criterion": "file_name",
      "operator": "regex_match",
      "values": ["\\.(?i)(jpe?g|png|gif)$"]
    }
  ]
}

Getting a filter

Method	Route
`GET`	`/v1/filters/{filter_id}`

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/filters/$FILTER_ID

Response

Returns 200 OK with the filter object including its rules.

Updating a filter

Method	Route
`PUT`	`/v1/filters/{filter_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	Updated name of the filter
`rules`	FilterRule[]	Yes	An array of filter rules to overwrite on this filter

Request

curl -d '{"name": "$UPDATED_FILTER_NAME", "rules": [$UPDATED_FILTER_RULES]}' \
  -H "X-API-KEY: $API_KEY" \
  -H "Content-Type: application/json" \
  -X PUT https://api.massive.app/v1/filters/$FILTER_ID

Response

Returns 200 OK with the updated filter object.

Deleting a filter

Method	Route
`DELETE`	`/v1/filters/{filter_id}`

Headers

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

Request

curl -H "X-API-KEY: $API_KEY" \
  -X DELETE https://api.massive.app/v1/filters/$FILTER_ID

Response

Returns 204 No Content.

Adding a filter to a Portal connection

To apply a filter to a Portal connection, provide the filter_id when updating the Portal.

Removing a filter from a Portal connection

To remove a filter from a Portal connection, update the Portal and omit the filter_id.