# Get environment filters

`GET /v1/environments/{environmentId}/operations/filters`

Available as MCP tool `get-env-filters` (Read).

Filter endpoints allow you to review and manage filters for async messages. A filter can contain multiple rules, but you can only create one filter per subscription. [Learn about filters](https://docs.redoxengine.com/permalink/Zn8kiEw3GdyBFaSwQNSAN).

You can retrieve, create, update, or delete filters, as well as review and manage filter links.  

### Get environment filters

Retrieve a list of existing filters for a specific environment within a Redox organization. You can only retrieve a list from one environment per query.

## Request parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `environmentId` | path | string | Yes | Identifies the specific environment that you're operating in or on behalf of. |
| `_page` | query | number | No | Indicates a specific page of results to return. This value typically comes from a previous response's `page` object. |
| `_count` | query | number | No | Defines the number of results to return per page. The maximum value per page is 50. |
| `name` | query | string | No | Specifies the name of the filter. This can be a partial name. |
| `connectionId` | query | string | No | Specifies the unique identifier of the connection where the filter is linked. |
| `dataModel` | query | string | No | Identifies the Redox data model or FHIR resource that the filter is linked to. |
| `sourceId` | query | string | No | Specifies the unique identifier of the source that the filter is linked to. |
| `destinationId` | query | string | No | Specifies the unique identifier of the destination that the filter is linked to. |
| `showDeleted` | query | boolean | No | Indicates that any previously deleted filters (including older versions of filters) should be included in the query response. |

## Request example

```bash
curl 'https://api.redoxengine.com/platform/v1/environments/{environmentId}/operations/filters' \
--request GET \
--header 'Authorization: Bearer $API_TOKEN' \
--header 'accept: application/json'
```

## Responses

### 200

Contains a payload object with a list of filters for the specified environment.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `meta` | object | No | Contains metadata about paginated results of returned data. |
| `meta.version` | string | No | Lists the major and minor version number for the format of the returned payload. The payload format or shape may change between minor versions, like including additional or extended fields in later versions. We include the version data in each response so that you have the option to handle the signaled differences. |
| `meta.totalRecords` | number | No | Specifies the total number of records across all pages for the result set. |
| `meta.links` | object | No |  |
| `meta.links.self` | string | No | Links to the current page of results. |
| `meta.links.next` | string | No | Links to the next page of results. |
| `meta.links.prev` | string | No | Links to the previous page of results, which returns the page based on the current page you're on. |
| `meta.links.first` | string | No | Links to the first page of results. |
| `meta.links.last` | string | No | Links to the last page of results. |
| `meta.currentPage` | number | No | Specifies the current page number. |
| `meta.pageType` | string | No | Describes the pagination algorithm. Value: offest |
| `meta.pageSize` | number | No | Describes the number of records included in each page of the current result set. |
| `payload` | object | No |  |
| `payload.filters` | Array of object | No | Contains an array of filters. |
| `payload.filters[].usage` | Array of object | No | Contains details about where the filter is being used. |
| `payload.filters[].usage[].linkId` | string (uuid) | No | Contains the unique identifier of the link for a specified asset. |
| `payload.filters[].usage[].organization` | object | No | Describes the Redox organization that the asset belongs to. |
| `payload.filters[].usage[].organization.id` | number | No | Contains the unique identifier of the Redox organization. |
| `payload.filters[].usage[].organization.name` | string, nullable | No | Contains the human-readable name of the Redox organization. |
| `payload.filters[].usage[].connectingOrganization` | object | No | Specifies the organization the asset is connected to when the subscription relates to a partner organization. |
| `payload.filters[].usage[].connectingOrganization.id` | number | No | Contains the unique identifier of the Redox organization. |
| `payload.filters[].usage[].connectingOrganization.name` | string, nullable | No | Contains the human-readable name of the Redox organization. |
| `payload.filters[].usage[].subscription` | object | No |  |
| `payload.filters[].usage[].subscription.id` | string (uuid) | No | Contains the unique identifier of the subscription. |
| `payload.filters[].usage[].subscription.dataModel` | string | No | Specifies the Redox data model that the link applies to or should apply to. |
| `payload.filters[].usage[].subscription.source` | object | No | Specifies the source of the subscription that an asset is or should be linked to. |
| `payload.filters[].usage[].subscription.source.id` | string (uuid) | Yes | Contains the unique identifier of the source. |
| `payload.filters[].usage[].subscription.source.name` | string, nullable | No | Specifies the name of the source. |
| `payload.filters[].usage[].subscription.destination` | object | No | Specifies the destination of the subscription that an asset is or should be linked to. |
| `payload.filters[].usage[].subscription.destination.id` | string (uuid) | Yes | Contains the unique identifier of the destination. |
| `payload.filters[].usage[].subscription.destination.name` | string, nullable | No | Specifies the name of the destination. |
| `payload.filters[].usage[].filterId` | string (uuid) | No | Contains the unique identifier of the asset being linked. |
| `payload.filters[].usage[].version` | string | No | Contains the API schema version used for this asset. |
| `payload.filters[].usage[].eventType` | string, nullable | No | Specifies the specific event type for a data model that the link applies to or should apply to. |
| `payload.filters[].usage[].createdAt` | string | No | Displays the date and time that the asset was originally created in ISO 8601 format. |
| `payload.filters[].usage[].createdBy` | object | No | Contains the metadata about the user who created the asset. |
| `payload.filters[].usage[].createdBy.id` | number | No | Contains the unique identifier of the user. |
| `payload.filters[].usage[].createdBy.name` | string, nullable | No | Displays the user's full name. |
| `payload.filters[].usage[].updatedAt` | string | No | Displays the date and time that the asset was last updated in ISO 8601 format. |
| `payload.filters[].usage[].updatedBy` | object | No | Contains the metadata about the user who last updated the asset. |
| `payload.filters[].usage[].updatedBy.id` | number | No | Contains the unique identifier of the user. |
| `payload.filters[].usage[].updatedBy.name` | string, nullable | No | Displays the user's full name. |
| `payload.filters[].usage[].deletedAt` | string, nullable | No | Displays the date and time that the asset was deleted. Returns a `null` value if the asset hasn't been deleted. |
| `payload.filters[].usage[].deletedBy` | object, nullable | No | Contains the metadata about the user who deleted the asset. |
| `payload.filters[].usage[].deletedBy.id` | number | No | Contains the unique identifier of the user. |
| `payload.filters[].usage[].deletedBy.name` | string, nullable | No | Displays the user's full name. |
| `payload.filters[].promotionAssociations` | Array of object | No | Contains a list of promotions associated with this asset. |
| `payload.filters[].promotionAssociations[].organization` | object | No | Describes the Redox organization that the asset belongs to. |
| `payload.filters[].promotionAssociations[].organization.id` | number | No | Contains the unique identifier of the Redox organization. |
| `payload.filters[].promotionAssociations[].organization.name` | string, nullable | No | Contains the human-readable name of the Redox organization. |
| `payload.filters[].promotionAssociations[].fromAsset` | object | No | Describes the original asset that was created in staging and promoted to production. |
| `payload.filters[].promotionAssociations[].fromAsset.id` | string (uuid) | No | Contains the unique identifier of the asset. |
| `payload.filters[].promotionAssociations[].fromAsset.environment` | object | No | Describes the Redox environment that the asset belongs to. |
| `payload.filters[].promotionAssociations[].fromAsset.environment.id` | string (uuid) | No | Contains the unique identifier of the Redox environment. |
| `payload.filters[].promotionAssociations[].fromAsset.type` | string | No | Possible values: configModifier, filter, translationSet |
| `payload.filters[].promotionAssociations[].fromAsset.latestVersion` | number | No | Displays the most recent version of the original asset in staging. This may vary from the version number in production. A different version number may indicate you need to re-promote the asset to production. |
| `payload.filters[].promotionAssociations[].toAsset` | object | No | Describes the promoted asset that can be used or linked to subscriptions in production. |
| `payload.filters[].promotionAssociations[].toAsset.id` | string (uuid) | No | Contains the unique identifier of the asset. |
| `payload.filters[].promotionAssociations[].toAsset.environment` | object | No | Describes the Redox environment that the asset belongs to. |
| `payload.filters[].promotionAssociations[].toAsset.environment.id` | string (uuid) | No | Contains the unique identifier of the Redox environment. |
| `payload.filters[].promotionAssociations[].toAsset.type` | string | No | Possible values: configModifier, filter, translationSet |
| `payload.filters[].promotionAssociations[].toAsset.latestVersion` | number | No | Displays the most recent version of the promoted asset in production. This may vary from the version number in staging. A different version number may indicate you need to re-promote the staging asset to production. |
| `payload.filters[].promotionAssociations[].toAsset.outOfDate` | boolean | No | Indicates whether the version of the promoted asset in production is different from the version of the original asset in staging. |
| `payload.filters[].promotionAssociations[].createdAt` | string | No | Displays the date and time that the asset was originally created in ISO 8601 format. |
| `payload.filters[].promotionAssociations[].createdBy` | object | No | Contains the metadata about the user who created the asset. |
| `payload.filters[].promotionAssociations[].createdBy.id` | number | No | Contains the unique identifier of the user. |
| `payload.filters[].promotionAssociations[].createdBy.name` | string, nullable | No | Displays the user's full name. |
| `payload.filters[].promotionAssociations[].updatedAt` | string | No | Displays the date and time that the asset was last updated in ISO 8601 format. |
| `payload.filters[].promotionAssociations[].updatedBy` | object | No | Contains the metadata about the user who last updated the asset. |
| `payload.filters[].promotionAssociations[].updatedBy.id` | number | No | Contains the unique identifier of the user. |
| `payload.filters[].promotionAssociations[].updatedBy.name` | string, nullable | No | Displays the user's full name. |
| `payload.filters[].promotionAssociations[].deletedAt` | string, nullable | No | Displays the date and time that the asset was deleted. Returns a `null` value if the asset hasn't been deleted. |
| `payload.filters[].promotionAssociations[].deletedBy` | object, nullable | No | Contains the metadata about the user who deleted the asset. |
| `payload.filters[].promotionAssociations[].deletedBy.id` | number | No | Contains the unique identifier of the user. |
| `payload.filters[].promotionAssociations[].deletedBy.name` | string, nullable | No | Displays the user's full name. |
| `payload.filters[].id` | string (uuid) | No | Contains the unique identifier of the asset. |
| `payload.filters[].name` | string | No | Contains the human-readable name of the asset. |
| `payload.filters[].rules` | Array of object | No | Contains a list of rules that determine when the filter is applied to a message. A filter is only applied if ALL rules are met. |
| `payload.filters[].rules[].path` | string | No | Specifies the path to the field(s) that should be evaluated when the filter is applied. This should be a `jsonpath` value. |
| `payload.filters[].rules[].values` | Array of string | No | Contains an array of string values that are matched against the path value when the rule is evaluated. |
| `payload.filters[].rules[].allowList` | boolean | No | Indicates whether the rule is an allow-list (matches when the value at the specified path is in the values array) or a deny-list (matches when the value at the specified path is NOT in the values array). Defaults to `true` (allow-list). |
| `payload.filters[].action` | string | No | Defines what action should be performed when the filter is applied to a message. Possible values: block-all, send |
| `payload.filters[].pathType` | string | No | Specifies the format of the field paths defined for this filter's rules. Both FHIR and data model filters use the `jsonpath` path type. Value: jsonpath |
| `payload.filters[].version` | string | No | Contains the API schema version used for this asset. |
| `payload.filters[].filterVersion` | number | No | Contains the numeric version of the asset. Version numbers start at 1 and increment in whole numbers whenever the asset is updated. |
| `payload.filters[].createdAt` | string | No | Displays the date and time that the asset was originally created in ISO 8601 format. |
| `payload.filters[].createdBy` | object | No | Contains the metadata about the user who created the asset. |
| `payload.filters[].createdBy.id` | number | No | Contains the unique identifier of the user. |
| `payload.filters[].createdBy.name` | string, nullable | No | Displays the user's full name. |
| `payload.filters[].updatedAt` | string | No | Displays the date and time that the asset was last updated in ISO 8601 format. |
| `payload.filters[].updatedBy` | object | No | Contains the metadata about the user who last updated the asset. |
| `payload.filters[].updatedBy.id` | number | No | Contains the unique identifier of the user. |
| `payload.filters[].updatedBy.name` | string, nullable | No | Displays the user's full name. |
| `payload.filters[].deletedAt` | string, nullable | No | Displays the date and time that the asset was deleted. Returns a `null` value if the asset hasn't been deleted. |
| `payload.filters[].deletedBy` | object, nullable | No | Contains the metadata about the user who deleted the asset. |
| `payload.filters[].deletedBy.id` | number | No | Contains the unique identifier of the user. |
| `payload.filters[].deletedBy.name` | string, nullable | No | Displays the user's full name. |
| `payload.filters[].environment` | object | No | Describes the Redox environment that the asset belongs to. |
| `payload.filters[].environment.id` | string (uuid) | No | Contains the unique identifier of the Redox environment. |
| `payload.filters[].organization` | object | No | Describes the Redox organization that the asset belongs to. |
| `payload.filters[].organization.id` | number | No | Contains the unique identifier of the Redox organization. |
| `payload.filters[].organization.name` | string, nullable | No | Contains the human-readable name of the Redox organization. |

_Generated from the schema: the values are placeholders, not a real payload._

```json
{
  "meta": {
    "version": "1.0.0",
    "totalRecords": 0,
    "links": {
      "self": "string",
      "next": "string",
      "prev": "string",
      "first": "string",
      "last": "string"
    },
    "currentPage": 1,
    "pageType": "offest",
    "pageSize": 0
  },
  "payload": {
    "filters": [
      {
        "usage": [
          {
            "linkId": "009f739c-6620-43b0-978e-b245e723c57a",
            "organization": {
              "id": 122,
              "name": "string"
            },
            "connectingOrganization": {
              "id": 122,
              "name": "string"
            },
            "subscription": {
              "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
              "dataModel": "PatientAdmin",
              "source": {
                "name": "string",
                "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
              },
              "destination": {
                "name": "string",
                "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
              }
            },
            "filterId": "aff0ee0f-f371-4b82-82c6-dc3b96f05c91",
            "version": "1.0.0",
            "eventType": "string",
            "createdAt": "2024-04-25T18:17:16.719Z",
            "createdBy": {
              "id": 0,
              "name": "string"
            },
            "updatedAt": "2024-04-25T18:17:16.719Z",
            "updatedBy": {
              "id": 0,
              "name": "string"
            },
            "deletedAt": "2024-04-25T18:17:16.719Z",
            "deletedBy": {
              "id": 0,
              "name": "string"
            }
          }
        ],
        "promotionAssociations": [
          {
            "organization": {
              "id": 122,
              "name": "string"
            },
            "fromAsset": {
              "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
              "environment": {
                "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
              },
              "type": "configModifier",
              "latestVersion": 0
            },
            "toAsset": {
              "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
              "environment": {
                "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
              },
              "type": "configModifier",
              "latestVersion": 0,
              "outOfDate": true
            },
            "createdAt": "2024-04-25T18:17:16.719Z",
            "createdBy": {
              "id": 0,
              "name": "string"
            },
            "updatedAt": "2024-04-25T18:17:16.719Z",
            "updatedBy": {
              "id": 0,
              "name": "string"
            },
            "deletedAt": "2024-04-25T18:17:16.719Z",
            "deletedBy": {
              "id": 0,
              "name": "string"
            }
          }
        ],
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "name": "string",
        "rules": [
          {
            "path": "$.Patient.Demographics.FirstName",
            "values": [
              "string"
            ],
            "allowList": true
          }
        ],
        "action": "send",
        "pathType": "jsonpath",
        "version": "1.0.0",
        "filterVersion": 2,
        "createdAt": "2024-04-25T18:17:16.719Z",
        "createdBy": {
          "id": 0,
          "name": "string"
        },
        "updatedAt": "2024-04-25T18:17:16.719Z",
        "updatedBy": {
          "id": 0,
          "name": "string"
        },
        "deletedAt": "2024-04-25T18:17:16.719Z",
        "deletedBy": {
          "id": 0,
          "name": "string"
        },
        "environment": {
          "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
        },
        "organization": {
          "id": 122,
          "name": "string"
        }
      }
    ]
  }
}
```

### 400

Bad Request

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `payload` | object | No | Contains the error message. |
| `payload.error` | object | No | Contains the error message details. |
| `payload.error.id` | string | No | Contains a unique identifier for the given error instance. |
| `payload.error.title` | string | No | Displays the high-level error message, typically something succinct like `Bad Request`. |
| `payload.error.code` | string | No | Contains an alternative ID for the error type, which can be used to find relevant troubleshooting information. |
| `payload.error.detail` | string | No | Contains the specific error details for this message. |
| `payload.error.status` | number | No | Displays the corresponding HTTP status code for the error. |
| `payload.error.transient` | boolean | No | Describes whether the error will resolve itself. If `true`, no further action needs to be taken. If `false`, you may need to troubleshoot on your end to resolve the issue before the error can be processed. |

```json
{
  "payload": {
    "error": {
      "title": "Bad Request",
      "code": "validation.error.bad.request",
      "detail": "Error details",
      "status": 400,
      "transient": false
    }
  }
}
```

### 403

Forbidden

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `payload` | object | No | Contains the error message. |
| `payload.errors` | Array of object | No |  |
| `payload.errors[].title` | string | No | Displays the high-level error message, typically something succinct like `Forbidden`. |
| `payload.errors[].code` | string | No | Contains an alternative ID for the error type, which can be used to find relevant troubleshooting information. |

```json
{
  "payload": {
    "errors": [
      {
        "title": "Forbidden",
        "code": "authorization.forbidden"
      }
    ]
  }
}
```

### 500

Internal Server Error

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `payload` | object | No | Contains the error message. |
| `payload.error` | object | No | Contains the error message details. |
| `payload.error.title` | string | No | Displays the high-level error message, typically something succinct like `Failed in step X`. |
| `payload.error.code` | string | No | Contains an alternative ID for the error type, which can be used to find relevant troubleshooting information. |
| `payload.error.detail` | string | No | Contains the specific error details for this message. |
| `payload.error.status` | number | No | Displays the corresponding HTTP status code for the error. |
| `payload.error.transient` | boolean | No | Describes whether the error will resolve itself. If `true`, no further action needs to be taken. If `false`, you may need to troubleshoot on your end to resolve the issue before the error can be processed. |

```json
{
  "payload": {
    "error": {
      "title": "Internal Server Error",
      "code": "failed.db.lookup",
      "detail": "Error details",
      "status": 500,
      "transient": true
    }
  }
}
```
