7.2.1.10. Named Filters API

Named filters are stored collections of column filters and sorters for the issue table. There are global, centrally managed named filters, as well as 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.