POST /rest/api/2/filter

Creates a filter. The filter is shared according to the default share scope. The filter is not selected as a favorite.

Permissions required: Permission to access Jira.

Servers

https://your-domain.atlassian.net

Request headers

Name	Type	Required	Description
`Content-Type`	String	Yes	The media type of the request body. Default value: "application/json"

Query parameters

Name Type Required Description

Name	Type	Required	Description
`expand`	String	No	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]`.
`overrideSharePermissions`	Boolean	No	EXPERIMENTAL: Whether share permissions are overridden to enable filters with any share permissions to be created. Available to users with Administer Jira global permission. Default value: false

expand

String

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].

overrideSharePermissions

Boolean

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

Default value: false

Request body fields

Name	Type	Required	Description
`id`	String	No	The unique identifier for the filter.
`searchUrl`	String	No	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/2/search?jql=project+%3D+SSP+AND+issuetype+%3D+Bug.
`approximateLastUsed`	String	No	[Experimental] Approximate last used time. Returns the date and time when the filter was last used. Returns `null` if the filter hasn't been used after tracking was enabled. For performance reasons, timestamps aren't updated in real time and therefore may not be exactly accurate.
`editPermissions[]`	Array	No	The groups and projects that can edit the filter.
`editPermissions[].id`	Integer	No	The unique identifier of the share permission.
`editPermissions[].type`	String	Yes	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. Possible values: `"global"` `"group"` `"project"` `"project-unknown"` `"projectRole"` `"loggedin"` `"user"` `"authenticated"`
`name`	String	Yes	The name of the filter. Must be unique.
`description`	String	No	A description of the filter.
`self`	String	No	The URL of the filter.
`sharePermissions[]`	Array	No	The groups and projects that the filter is shared with.
`sharePermissions[].id`	Integer	No	The unique identifier of the share permission.
`sharePermissions[].type`	String	Yes	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. Possible values: `"global"` `"group"` `"project"` `"project-unknown"` `"projectRole"` `"loggedin"` `"user"` `"authenticated"`
`favouritedCount`	Integer	No	The count of how many users have selected this filter as a favorite, including the filter owner.
`favourite`	Boolean	No	Whether the filter is selected as a favorite.
`jql`	String	No	The JQL query for the filter. For example, project = SSP AND issuetype = Bug.
`viewUrl`	String	No	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.

How to start integrating

Add HTTP Task to your workflow definition.
Search for the API you want to integrate with and click on the name.
- This loads the API reference documentation and prepares the Http request settings.
Click Test request to test run your request to the API and see the API's response.