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 which are 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:

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

BODY

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.

EXAMPLE

{
  "action": "include",
  "criterion": "file_name",
  "operator": "regex_match",
  "values": ["\\.(?i)(jpe?g|png|gif)$"]
}

Filter Rule Actions

An action determines what should be done when a filter rule is matched.

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

A criterion selects the attribute(s) that will be examined by this rule.

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

Filter Rule Operators

An operator performs a comparison using the selected criterion and the provided values.

Operator	Description
`regex_match`	Evalutes the rule to be true if the criterion regex matches the pattern specified by the value.

Note

The type of regex being used by the regex_match operator is RE2.

Filter Rule Value(s)

A value refers to the input specified for a rule and uses a pattern determined by the type of operator and criterion. For example, the value in "include files where file name regex matches \\.(?i)(jpe?g|png|gif)$" would be the regex pattern \\.(?i)(jpe?g|png|gif)$. 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.

curl

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

EXAMPLE

Example Request BodyExample Response Body

{
    "name": "Test Filter",
    "rules": [
        {
            "action": "include",
            "criterion": "file_name",
            "operator": "regex_match",
            "values": [
                "\\.(?i)(jpe?g|png|gif)$"
            ]
        }
    ]
}

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

curl

curl -H "X-API-KEY: $API_KEY" \
-H "Content-Type: application/json" \
-X GET https://api.massive.app/v1/filters/$FILTER_ID

EXAMPLE

Example Response Body

{
    "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)$"
            ]
        }
    ]
}

Updating a Filter

Note

Updating a filter will replace all existing rules with the new set of rules provided.

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.

curl

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

EXAMPLE

Example Request BodyExample Response Body

{
    "name": "Test Filter",
    "rules": [
        {
            "action": "include",
            "criterion": "file_name",
            "operator": "regex_match",
            "values": [
                "\\.(?i)(jpe?g|png|gif)$"
            ]
        }
    ]
}

{
    "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)$"
            ]
        }
    ]
}

Deleting a Filter

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

HEADERS

Name	Type	Required	Description
`X-API-KEY`	String	Yes	API key
Content-Type	String	Yes	Must be `application/json`

curl

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

Adding a Filter to a Portal Connection

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

Note

Filters cannot be applied to storage gateway connections. All other connections are supported.

Removing a Filter from a Portal Connection

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