Search for filters - JIRA 7.6.1

Returns a paginated list of filters. Use this operation to get:

specific filters, by defining id only.

filters that match all of the specified attributes. For example, all filters for a user with a particular word in their name. When multiple attributes are specified only filters matching all attributes are returned.

This operation can be accessed anonymously.

Permissions required: None, however, only the following filters that match the query parameters are returned:

filters owned by the user.

filters shared with a group that the user is a member of.

filters shared with a private project that the user has Browse projects project permission for.

filters shared with a public project.

filters shared with the public.

{ "self": "https://your-domain.atlassian.net/rest/api/3/filter/search?accountId=&maxResults=50&filterName=&orderBy=name&startAt=0&expand=description,owner,jql,searchUrl,viewUrl,favourite,favouritedCount,sharePermissions,editPermissions,isWritable,subscriptions", "maxResults": 100, "startAt": 0, "total": 2, "isLast": true, "values": [ { "expand": "description,owner,jql,searchUrl,viewUrl,favourite,favouritedCount,sharePermissions,editPermissions,isWritable,subscriptions", "self": "https://your-domain.atlassian.net/rest/api/3/filter/10000", "id": "10000", "name": "All Open Bugs", "description": "Lists all open bugs", "owner": { "self": "https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g", "key": "", "accountId": "5b10a2844c20165700ede21g", "accountType": "atlassian", "name": "", "avatarUrls": { "48x48": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=48&s=48", "24x24": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=24&s=24", "16x16": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=16&s=16", "32x32": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=32&s=32" }, "displayName": "Mia Krystof", "active": false }, "jql": "type = Bug and resolution is empty", "viewUrl": "https://your-domain.atlassian.net/issues/?filter=10000", "searchUrl": "https://your-domain.atlassian.net/rest/api/3/search?jql=type%20%3D%20Bug%20and%20resolutino%20is%20empty", "favourite": false, "favouritedCount": 0, "sharePermissions": [], "editPermissions": [], "subscriptions": [] }, { "expand": "description,owner,jql,searchUrl,viewUrl,favourite,favouritedCount,sharePermissions,editPermissions,isWritable,subscriptions", "self": "https://your-domain.atlassian.net/rest/api/3/filter/10010", "id": "10010", "name": "My issues", "description": "Issues assigned to me", "owner": { "self": "https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g", "key": "", "accountId": "5b10a2844c20165700ede21g", "accountType": "atlassian", "name": "", "avatarUrls": { "48x48": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=48&s=48", "24x24": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=24&s=24", "16x16": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=16&s=16", "32x32": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=32&s=32" }, "displayName": "Mia Krystof", "active": false }, "jql": "assignee = currentUser() and resolution is empty", "viewUrl": "https://your-domain.atlassian.net/issues/?filter=10010", "searchUrl": "https://your-domain.atlassian.net/rest/api/3/search?jql=assignee+in+%28currentUser%28%29%29+and+resolution+is+empty", "favourite": true, "favouritedCount": 123, "sharePermissions": [ { "id": 10000, "type": "global" }, { "id": 10010, "type": "project", "project": { "self": "https://your-domain.atlassian.net/rest/api/3/project/EX", "id": "10000", "key": "EX", "name": "Example", "avatarUrls": { "48x48": "https://your-domain.atlassian.net/secure/projectavatar?size=large&pid=10000", "24x24": "https://your-domain.atlassian.net/secure/projectavatar?size=small&pid=10000", "16x16": "https://your-domain.atlassian.net/secure/projectavatar?size=xsmall&pid=10000", "32x32": "https://your-domain.atlassian.net/secure/projectavatar?size=medium&pid=10000" }, "projectCategory": { "self": "https://your-domain.atlassian.net/rest/api/3/projectCategory/10000", "id": "10000", "name": "FIRST", "description": "First Project Category" }, "simplified": false, "style": "classic", "insight": { "totalIssueCount": 100, "lastIssueUpdateTime": "2023-07-12T06:03:00.831+0000" } } } ], "editPermissions": [ { "id": 10010, "type": "project", "project": { "self": "https://your-domain.atlassian.net/rest/api/3/project/MKY", "id": "10002", "key": "MKY", "name": "Example", "avatarUrls": { "48x48": "https://your-domain.atlassian.net/secure/projectavatar?size=large&pid=10002", "24x24": "https://your-domain.atlassian.net/secure/projectavatar?size=small&pid=10002", "16x16": "https://your-domain.atlassian.net/secure/projectavatar?size=xsmall&pid=10002", "32x32": "https://your-domain.atlassian.net/secure/projectavatar?size=medium&pid=10002" }, "projectCategory": { "self": "https://your-domain.atlassian.net/rest/api/3/projectCategory/10000", "id": "10000", "name": "FIRST", "description": "First Project Category" }, "simplified": false, "style": "classic", "insight": { "totalIssueCount": 100, "lastIssueUpdateTime": "2023-07-12T06:03:00.831+0000" }, "deleted": true, "retentionTillDate": "2023-09-10T06:03:00.832+0000", "deletedDate": "2023-07-12T06:03:00.832+0000", "deletedBy": { "self": "https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g", "key": "", "accountId": "5b10a2844c20165700ede21g", "accountType": "atlassian", "name": "", "avatarUrls": { "48x48": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=48&s=48", "24x24": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=24&s=24", "16x16": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=16&s=16", "32x32": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=32&s=32" }, "displayName": "Mia Krystof", "active": false } }, "role": { "self": "https://your-domain.atlassian.net/rest/api/3/project/MKY/role/10360", "name": "Developers", "id": 10360, "description": "A project role that represents developers in a project", "actors": [ { "id": 10240, "displayName": "jira-developers", "type": "atlassian-group-role-actor", "name": "jira-developers", "actorGroup": { "name": "jira-developers", "displayName": "jira-developers", "groupId": "952d12c3-5b5b-4d04-bb32-44d383afc4b2" } }, { "id": 10241, "displayName": "Mia Krystof", "type": "atlassian-user-role-actor", "actorUser": { "accountId": "5b10a2844c20165700ede21g" } } ], "scope": { "type": "PROJECT", "project": { "id": "10000", "key": "KEY", "name": "Next Gen Project" } } } }, { "id": 10010, "type": "group", "group": { "name": "jira-administrators", "groupId": "276f955c-63d7-42c8-9520-92d01dca0625", "self": "https://your-domain.atlassian.net/rest/api/3/group?groupId=276f955c-63d7-42c8-9520-92d01dca0625" } } ], "subscriptions": [ { "id": 1, "user": { "self": "https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g", "key": "", "accountId": "5b10a2844c20165700ede21g", "accountType": "atlassian", "name": "", "emailAddress": "mia@example.com", "avatarUrls": { "48x48": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=48&s=48", "24x24": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=24&s=24", "16x16": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=16&s=16", "32x32": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=32&s=32" }, "displayName": "Mia Krystof", "active": true, "timeZone": "Australia/Sydney", "groups": { "size": 3, "items": [] }, "applicationRoles": { "size": 1, "items": [] } } } ] } ] }

Request

Query Params

filterName

string

optional

String used to perform a case-insensitive partial match with name.

accountId

string

optional

User account ID used to return filters with the matching owner.accountId. This parameter cannot be used with owner.

owner

string

optional

This parameter is deprecated because of privacy changes. Use accountId instead. See the migration guide for details. User name used to return filters with the matching owner.name. This parameter cannot be used with accountId.

groupname

string

optional

As a group's name can change, use of groupId is recommended to identify a group. Group name used to returns filters that are shared with a group that matches sharePermissions.group.groupname. This parameter cannot be used with the groupId parameter.

groupId

string

optional

Group ID used to returns filters that are shared with a group that matches sharePermissions.group.groupId. This parameter cannot be used with the groupname parameter.

projectId

integer

optional

Project ID used to returns filters that are shared with a project that matches sharePermissions.project.id.

array[string]

optional

The list of filter IDs. To include multiple IDs, provide an ampersand-separated list. For example, id=10000&id=10001. Do not exceed 200 filter IDs.

orderBy

string

optional

Order the results by a field:

description Sorts by filter description. Note that this sorting works independently of whether the expand to display the description field is in use.

favourite_count Sorts by the count of how many users have this filter as a favorite.

is_favourite Sorts by whether the filter is marked as a favorite.

id Sorts by filter ID.

name Sorts by filter name.

owner Sorts by the ID of the filter owner.

is_shared Sorts by whether the filter is shared.

startAt

integer

optional

The index of the first item to return in a page of results (page offset).

maxResults

integer

optional

The maximum number of items to return per page.

expand

string

optional

Use expand to include additional information about filter in the response. This parameter accepts a comma-separated list. Expand options include:

description Returns the description of the filter.

favourite Returns an indicator of whether the user has set the filter as a favorite.

favouritedCount Returns a count of how many users have set this filter as a favorite.

jql Returns the JQL query that the filter uses.

owner Returns the owner of the filter.

searchUrl Returns a URL to perform the filter's JQL query.

sharePermissions Returns the share permissions defined for the filter.

editPermissions Returns the edit permissions defined for the filter.

isWritable Returns whether the current user has permission to edit the filter.

subscriptions Returns the users that are subscribed to the filter.

viewUrl Returns a URL to view the filter.

overrideSharePermissions

string

optional

EXPERIMENTAL: Whether share permissions are overridden to enable filters with any share permissions to be returned. Available to users with Administer Jira global permission.

Responses

🟢200Returned if the request is successful.

application/json

Body

A page of items.

isLast

boolean

read-onlyoptional

Whether this is the last page.

maxResults

integer <int32>

read-onlyoptional

The maximum number of items that could be returned.

string <uri>

read-onlyoptional

If there is another page of results, the URL of the next page.

self

string <uri>

read-onlyoptional

The URL of the page.

startAt

integer <int64>

read-onlyoptional

The index of the first item returned.

total

integer <int64>

read-onlyoptional

The number of items returned.

values

array[object (FilterDetails) {14}]

read-onlyoptional

The list of items.

description

string

optional

The description of the filter.

editPermissions

array[object (SharePermission) {6}]

optional

The groups and projects that can edit the filter. This can be specified when updating a filter, but not when creating a filter.

expand

string

read-onlyoptional

Expand options that include additional filter details in the response.

favourite

boolean

read-onlyoptional

Whether the filter is selected as a favorite by any users, not including the filter owner.

favouritedCount

integer <int64>

read-onlyoptional

The count of how many users have selected this filter as a favorite, including the filter owner.

string

read-onlyoptional

The unique identifier for the filter.

jql

string

read-onlyoptional

The JQL query for the filter. For example, project = SSP AND issuetype = Bug.

name

string

required

The name of the filter.

owner

object

read-onlyoptional

The user who owns the filter. Defaults to the creator of the filter, however, Jira administrators can change the owner of a shared filter in the admin settings.

searchUrl

string <uri>

read-onlyoptional

A URL to view the filter results in Jira, using the Search for issues using JQL operation with the filter's JQL string to return the filter results. For example, https://your-domain.atlassian.net/rest/api/3/search?jql=project+%3D+SSP+AND+issuetype+%3D+Bug.

self

string <uri>

read-onlyoptional

The URL of the filter.

sharePermissions

array[object (SharePermission) {6}]

optional

The groups and projects that the filter is shared with. This can be specified when updating a filter, but not when creating a filter.

subscriptions

array[object (FilterSubscription) {3}]

read-onlyoptional

The users that are subscribed to the filter.

viewUrl

string <uri>

read-onlyoptional

A URL to view the filter results in Jira, using the ID of the filter. For example, https://your-domain.atlassian.net/issues/?filter=10100.

🟠400Returned if: * `owner` and `accountId` are provided. * `expand` includes an invalid value. * `orderBy` is invalid. * `id` identifies more than 200 filter IDs.

🟠401Returned if the authentication credentials are incorrect or missing.