Add filter as favorite

PUT

/rest/api/3/filter/{id}/favourite

Add a filter as a favorite for the user.

Permissions required: Permission to access Jira, however, the user can only favorite:

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.

Request Example

Shell

JavaScript

Java

Swift

curl --location --request PUT 'http://jira.local:8080/jira/rest//rest/api/3/filter//favourite'

Response Example

200 - Success

{"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":true,"favouritedCount":0,"sharePermissions":[],"editPermissions":[],"subscriptions":{"size":0,"items":[],"max-results":0,"start-index":0,"end-index":0}}

Request

Path Params

integer

required

The ID of the filter.

Query Params

expand

string

optional

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

sharedUsers Returns the users that the filter is shared with. This includes users that can browse projects that the filter is shared with. If you don't specify sharedUsers, then the sharedUsers object is returned but it doesn't list any users. The list of users returned is limited to 1000, to access additional users append [start-index:end-index] to the expand request. For example, to access the next 1000 users, use ?expand=sharedUsers[1001:2000].

subscriptions Returns the users that are subscribed to the filter. If you don't specify subscriptions, the subscriptions object is returned but it doesn't list any subscriptions. The list of subscriptions returned is limited to 1000, to access additional subscriptions append [start-index:end-index] to the expand request. For example, to access the next 1000 subscriptions, use ?expand=subscriptions[1001:2000].

Responses

🟢200Returned if the request is successful.

application/json

Body

Details about a filter.

description

string

optional

A description of the filter.

editPermissions

array[object (SharePermission) {6}]

optional

The groups and projects that can edit the filter.

group

object

optional

The group that the filter is shared with. For a request, specify the groupId or name property for the group. As a group's name can change, use of groupId is recommended.

integer <int64>

read-onlyoptional

The unique identifier of the share permission.

project

object

optional

The project that the filter is shared with. This is similar to the project object returned by Get project but it contains a subset of the properties, which are: self, id, key, assigneeType, name, roles, avatarUrls, projectType, simplified.
For a request, specify the id for the project.

role

object

optional

The project role that the filter is shared with.
For a request, specify the id for the role. You must also specify the project object and id for the project that the role is in.

type

enum<string>

required

The type of share permission:

user Shared with a user.

group Shared with a group. If set in a request, then specify sharePermission.group as well.

project Shared with a project. If set in a request, then specify sharePermission.project as well.

projectRole Share with a project role in a project. This value is not returned in responses. It is used in requests, where it needs to be specify with projectId and projectRoleId.

global Shared globally. If set in a request, no other sharePermission properties need to be specified.

loggedin Shared with all logged-in users. Note: This value is set in a request by specifying authenticated as the type.

project-unknown Shared with a project that the user does not have access to. Cannot be set in a request.

Allowed values:

usergroupprojectprojectRolegloballoggedinauthenticatedproject-unknown

user

object

optional

The user account ID that the filter is shared with. For a request, specify the accountId property for the user.

favourite

boolean

optional

Whether the filter is selected as a favorite.

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

optional

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

name

string

required

The name of the filter. Must be unique.

owner

object

read-onlyoptional

The user who owns the filter. This is defaulted 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.

group

object

optional

The group that the filter is shared with. For a request, specify the groupId or name property for the group. As a group's name can change, use of groupId is recommended.

integer <int64>

read-onlyoptional

The unique identifier of the share permission.

project

object

optional

role

object

optional

The project role that the filter is shared with.
For a request, specify the id for the role. You must also specify the project object and id for the project that the role is in.

type

enum<string>

required

The type of share permission:

user Shared with a user.

group Shared with a group. If set in a request, then specify sharePermission.group as well.

project Shared with a project. If set in a request, then specify sharePermission.project as well.

projectRole Share with a project role in a project. This value is not returned in responses. It is used in requests, where it needs to be specify with projectId and projectRoleId.

global Shared globally. If set in a request, no other sharePermission properties need to be specified.

loggedin Shared with all logged-in users. Note: This value is set in a request by specifying authenticated as the type.

project-unknown Shared with a project that the user does not have access to. Cannot be set in a request.

Allowed values:

usergroupprojectprojectRolegloballoggedinauthenticatedproject-unknown

user

object

optional

The user account ID that the filter is shared with. For a request, specify the accountId property for the user.

sharedUsers

object

read-onlyoptional

A paginated list of the users that the filter is shared with. This includes users that are members of the groups or can browse the projects that the filter is shared with.

end-index

integer <int32>

read-onlyoptional

The index of the last item returned on the page.

items

array [object]

read-onlyoptional

The list of items.

max-results

integer <int32>

read-onlyoptional

The maximum number of results that could be on the page.

size

integer <int32>

read-onlyoptional

The number of items on the page.

start-index

integer <int32>

read-onlyoptional

The index of the first item returned on the page.

subscriptions

object

read-onlyoptional

A paginated list of the users that are subscribed to the filter.

end-index

integer <int32>

read-onlyoptional

The index of the last item returned on the page.

items

array[object (FilterSubscription) {3}]

read-onlyoptional

The list of items.

max-results

integer <int32>

read-onlyoptional

The maximum number of results that could be on the page.

size

integer <int32>

read-onlyoptional

The number of items on the page.

start-index

integer <int32>

read-onlyoptional

The index of the first item returned on the page.

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: * the filter is not found. * the user does not have permission to favorite the filter.

Modified at 2023-07-13 03:27:27

Reset columns

Remove filter as favorite