7.2.1.10. Named Filters API

Named Filters are stored collections of column filters and sorters of the issue table. There exist so-called global, centrally managed named filters as well as so-called custom named filters that users can create and manage on their own.

Endpoints

GET

/api/named_filters

Gets the list of all global named filters

POST

/api/named_filters

Creates a new global named filter

GET

/api/named_filters/{id}

Get info for an individual global named filter

PATCH

/api/named_filters/{id}

Edit an existing global named filter

DELETE

/api/named_filters/{id}

Delete an existing global named filter

GET

/api/users/{user}/named_filters

Gets the list of custom named filters of the given user

POST

/api/users/{user}/named_filters

Creates a new custom named filter for the given user

GET

/api/users/{user}/named_filters/{id}

Get info for an individual custom named filter

PATCH

/api/users/{user}/named_filters/{id}

Edit an existing custom named filter

DELETE

/api/users/{user}/named_filters/{id}

Delete an existing custom named filter
GET /api/named_filters

Gets the list of all global named filters.

Since: 7.3.0

Status Codes:
POST /api/named_filters

Creates a new global named filter.

Since: 7.3.0

Request Body:
Status Codes:
GET /api/named_filters/{id}

Get info for an individual global named filter.

Since: 7.3.0

Status Codes:
PATCH /api/named_filters/{id}

Edit an existing global named filter.

Since: 7.3.0

Request Body:
Status Codes:
DELETE /api/named_filters/{id}

Delete an existing global named filter.

Since: 7.3.0

Status Codes:
GET /api/users/{user}/named_filters

Gets the list of custom named filters of the given user.

Since: 7.3.0

Status Codes:
POST /api/users/{user}/named_filters

Creates a new custom named filter for the given user.

Since: 7.3.0

Request Body:
Status Codes:
GET /api/users/{user}/named_filters/{id}

Get info for an individual custom named filter.

Since: 7.3.0

Status Codes:
PATCH /api/users/{user}/named_filters/{id}

Edit an existing custom named filter.

Since: 7.3.0

Request Body:
Status Codes:
DELETE /api/users/{user}/named_filters/{id}

Delete an existing custom named filter.

Since: 7.3.0

Status Codes:

Types

NamedFilterType (enum)

A named filter type

NamedFilterInfo

A Named Filter configuration

NamedFilterVisibility

NamedFilter visibility configuration

IssueKindForNamedFilterCreation (enum)

IssueKind for Named-Filter creation

NamedFilterCreate

Named Filter Creation Request Data

NamedFilterUpdate

Named Filter Update Request Data
NamedFilterType

A named filter type.

  • PREDEFINED - Named filters of this type are immutable and exist out of the box and can be used by everyone

  • GLOBAL - Named filters of this type are usable by everyone and managed by the so called filter managers

  • CUSTOM - Named filters of this type are creatable by everyone but only visible to their owner

NamedFilterInfo

A Named Filter configuration.

Since: 6.9.0

It can consist of the following:

  • Filter values for the individual columns and the path-filter

  • A sort configuration indicating how to sort the table columns

Properties:

  • key (string) Uniquely identifies this filter configuration.

  • displayName (string) The name to use when displaying this filter.

  • url (string) Since 7.3.0. The URL for getting/updating/deleting this named filter.

  • isPredefined (boolean) Whether this filter is a predefined filter.

  • type (string) Possible values: NamedFilterType. Since 7.3.0. * PREDEFINED - Named filters of this type are immutable and exist out of the box and can be used by everyone * GLOBAL - Named filters of this type are usable by everyone and managed by the so called filter managers * CUSTOM - Named filters of this type are creatable by everyone but only visible to their owner

  • canWrite (boolean) Whether the user that requested this object can change or delete this filter configuration

  • filters (object) The actual filters with column-id as key and filter-value as value

    • Possible keys are described here column keys

    • This does not necessarily contain an entry for every column. In fact it may even be empty.

    • A filter value can never be null.

    • May contain references to columns that do not exist in the table column configuration.

  • sorters (array) Element Type: SortInfo. Defines the sort order to apply.

    • The first entry has the highest sort priority and the last one the lowest.

    • No column key may be referenced twice.

    • May contain references to columns that do not exist in the table column configuration.

  • supportsAllIssueKinds (boolean) True if this filter is valid for all issue kinds, false otherwise.

  • issueKindRestrictions (array) Element Type: string. Supported Issue Kinds.

    If supportsAllIssueKinds is false, then this set indicates, which issue kinds are supported.

  • visibility (NamedFilterVisibility) Since 7.3.0. Only applicable for global named filters.

    You may not have access to this information depending on your permissions.

NamedFilterVisibility

NamedFilter visibility configuration.

Since: 7.3.0

Only applicable for global named filters.

You may not have access to this information depending on your permissions.

Properties:

  • groups (array) Element Type: string. IDs of user-groups, that are allowed to see the named filter.

    The named filter is visible to all users, if this property is not given.

IssueKindForNamedFilterCreation

IssueKind for Named-Filter creation.

one of AV, CL, CY, DE, MV, SV, UNIVERSAL

NamedFilterCreate

Named Filter Creation Request Data.

Since: 7.3.0

Contains information to create a named filter from scratch

Properties:

  • displayName (string)

  • kind (string) Possible values: IssueKindForNamedFilterCreation. one of AV, CL, CY, DE, MV, SV, UNIVERSAL

  • filters (object) The actual filters with column-id as key and filter-value as value

    • Possible keys are described here column keys

    • This does not necessarily contain an entry for every column. In fact it may even be empty.

    • A filter value can never be null.

    • May contain references to columns that do not exist in the table column configuration.

  • sorters (array) Element Type: SortInfo. Defines the sort order to apply.

    • The first entry has the highest sort priority and the last one the lowest.

    • No column key may be referenced twice.

    • May contain references to columns that do not exist in the table column configuration.

  • visibility (NamedFilterVisibility) Since 7.3.0. Only applicable for global named filters.

    You may not have access to this information depending on your permissions.

NamedFilterUpdate

Named Filter Update Request Data.

Since: 7.3.0

Contains information to update an existing named filter. Fields that are not given, won’t be touched.

Properties:

  • name (string) An optional new name for the named filter.

    Changing this will also result in a changed ID and URL.

  • filters (object) The actual filters with column-id as key and filter-value as value

    • Possible keys are described here column keys

    • This does not necessarily contain an entry for every column. In fact it may even be empty.

    • A filter value can never be null.

    • May contain references to columns that do not exist in the table column configuration.

  • sorters (array) Element Type: SortInfo. Defines the sort order to apply.

    • The first entry has the highest sort priority and the last one the lowest.

    • No column key may be referenced twice.

    • May contain references to columns that do not exist in the table column configuration.

  • visibility (NamedFilterVisibility) Since 7.3.0. Only applicable for global named filters.

    You may not have access to this information depending on your permissions.