getFiltersPaginated
Search for filters
Details
- Method:
GET - Path:
/rest/api/3/filter/search - Operation ID:
getFiltersPaginated
Parameters
{
"filterName": {
"description": "String used to perform a case-insensitive partial match with `name`.",
"required": false,
"location": "query",
"type": "string"
},
"accountId": {
"description": "User account ID used to return filters with the matching `owner.accountId`. This parameter cannot be used with `owner`.",
"required": false,
"location": "query",
"type": "string"
},
"owner": {
"description": "This parameter is deprecated because of privacy changes. Use `accountId` instead. See the [migration guide](https://developer.atlassian.com/cloud/jira/platform/deprecation-notice-user-privacy-api-migration-guide/) for details. User name used to return filters with the matching `owner.name`. This parameter cannot be used with `accountId`.",
"required": false,
"location": "query",
"type": "string"
},
"groupname": {
"description": "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.",
"required": false,
"location": "query",
"type": "string"
},
"groupId": {
"description": "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.",
"required": false,
"location": "query",
"type": "string"
},
"projectId": {
"description": "Project ID used to returns filters that are shared with a project that matches `sharePermissions.project.id`.",
"required": false,
"location": "query",
"type": "integer",
"format": "int64"
},
"id": {
"description": "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.",
"required": false,
"location": "query",
"type": "array"
},
"orderBy": {
"description": "[Order](#ordering) the results by a field:\n\n * `description` Sorts by filter description. Note that this sorting works independently of whether the expand to display the description field is in use.\n * `favourite_count` Sorts by the count of how many users have this filter as a favorite.\n * `is_favourite` Sorts by whether the filter is marked as a favorite.\n * `id` Sorts by filter ID.\n * `name` Sorts by filter name.\n * `owner` Sorts by the ID of the filter owner.\n * `is_shared` Sorts by whether the filter is shared.",
"required": false,
"location": "query",
"type": "string",
"enum": [
"description",
"-description",
"+description",
"favourite_count",
"-favourite_count",
"+favourite_count",
"id",
"-id",
"+id",
"is_favourite",
"-is_favourite",
"+is_favourite",
"name",
"-name",
"+name",
"owner",
"-owner",
"+owner",
"is_shared",
"-is_shared",
"+is_shared"
]
},
"startAt": {
"description": "The index of the first item to return in a page of results (page offset).",
"required": false,
"location": "query",
"type": "integer",
"format": "int64"
},
"maxResults": {
"description": "The maximum number of items to return per page.",
"required": false,
"location": "query",
"type": "integer",
"format": "int32"
},
"expand": {
"description": "Use [expand](#expansion) to include additional information about filter in the response. This parameter accepts a comma-separated list. Expand options include:\n\n * `description` Returns the description of the filter.\n * `favourite` Returns an indicator of whether the user has set the filter as a favorite.\n * `favouritedCount` Returns a count of how many users have set this filter as a favorite.\n * `jql` Returns the JQL query that the filter uses.\n * `owner` Returns the owner of the filter.\n * `searchUrl` Returns a URL to perform the filter's JQL query.\n * `sharePermissions` Returns the share permissions defined for the filter.\n * `editPermissions` Returns the edit permissions defined for the filter.\n * `isWritable` Returns whether the current user has permission to edit the filter.\n * `approximateLastUsed` \\[Experimental\\] Returns the approximate date and time when the filter was last evaluated.\n * `subscriptions` Returns the users that are subscribed to the filter.\n * `viewUrl` Returns a URL to view the filter.",
"required": false,
"location": "query",
"type": "string"
},
"overrideSharePermissions": {
"description": "EXPERIMENTAL: Whether share permissions are overridden to enable filters with any share permissions to be returned. Available to users with *Administer Jira* [global permission](https://confluence.atlassian.com/x/x4dKLg).",
"required": false,
"location": "query",
"type": "boolean"
},
"isSubstringMatch": {
"description": "When `true` this will perform a case-insensitive substring match for the provided `filterName`. When `false` the filter name will be searched using [full text search syntax](https://support.atlassian.com/jira-software-cloud/docs/search-for-issues-using-the-text-field/).",
"required": false,
"location": "query",
"type": "boolean"
}
}Response Schema
{
"additionalProperties": false,
"description": "A page of items.",
"properties": {
"isLast": {
"description": "Whether this is the last page.",
"readOnly": true,
"type": "boolean"
},
"maxResults": {
"description": "The maximum number of items that could be returned.",
"format": "int32",
"readOnly": true,
"type": "integer"
},
"nextPage": {
"description": "If there is another page of results, the URL of the next page.",
"format": "uri",
"readOnly": true,
"type": "string"
},
"self": {
"description": "The URL of the page.",
"format": "uri",
"readOnly": true,
"type": "string"
},
"startAt": {
"description": "The index of the first item returned.",
"format": "int64",
"readOnly": true,
"type": "integer"
},
"total": {
"description": "The number of items returned.",
"format": "int64",
"readOnly": true,
"type": "integer"
},
"values": {
"description": "The list of items.",
"items": {
"additionalProperties": false,
"description": "Details of a filter.",
"properties": {
"approximateLastUsed": {
"description": "\\[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.",
"format": "date-time",
"readOnly": true,
"type": "string"
},
"description": {
"description": "The description of the filter.",
"type": "string"
},
"editPermissions": {
"description": "The groups and projects that can edit the filter. This can be specified when updating a filter, but not when creating a filter.",
"items": {
"additionalProperties": false,
"description": "Details of a share permission for the filter.",
"properties": {
"group": {
"allOf": [
{
"$ref": "#/components/schemas/GroupName"
}
],
"description": "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."
},
"id": {
"description": "The unique identifier of the share permission.",
"format": "int64",
"readOnly": true,
"type": "integer"
},
"project": {
"allOf": [
{
"$ref": "#/components/schemas/Project"
}
],
"description": "The project that the filter is shared with. This is similar to the project object returned by [Get project](#api-rest-api-3-project-projectIdOrKey-get) but it contains a subset of the properties, which are: `self`, `id`, `key`, `assigneeType`, `name`, `roles`, `avatarUrls`, `projectType`, `simplified`. \nFor a request, specify the `id` for the project."
},
"role": {
"allOf": [
{
"$ref": "#/components/schemas/ProjectRole"
}
],
"description": "The project role that the filter is shared with. \nFor 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": {
"description": "The type of share permission:\n\n * `user` Shared with a user.\n * `group` Shared with a group. If set in a request, then specify `sharePermission.group` as well.\n * `project` Shared with a project. If set in a request, then specify `sharePermission.project` as well.\n * `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`.\n * `global` Shared globally. If set in a request, no other `sharePermission` properties need to be specified.\n * `loggedin` Shared with all logged-in users. Note: This value is set in a request by specifying `authenticated` as the `type`.\n * `project-unknown` Shared with a project that the user does not have access to. Cannot be set in a request.",
"enum": [
"user",
"group",
"project",
"projectRole",
"global",
"loggedin",
"authenticated",
"project-unknown"
],
"type": "string"
},
"user": {
"allOf": [
{
"$ref": "#/components/schemas/UserBean"
}
],
"description": "The user account ID that the filter is shared with. For a request, specify the `accountId` property for the user."
}
},
"required": [
"type"
],
"type": "object"
},
"type": "array"
},
"expand": {
"description": "Expand options that include additional filter details in the response.",
"readOnly": true,
"type": "string",
"xml": {
"attribute": true
}
},
"favourite": {
"description": "Whether the filter is selected as a favorite by any users, not including the filter owner.",
"readOnly": true,
"type": "boolean"
},
"favouritedCount": {
"description": "The count of how many users have selected this filter as a favorite, including the filter owner.",
"format": "int64",
"readOnly": true,
"type": "integer"
},
"id": {
"description": "The unique identifier for the filter.",
"readOnly": true,
"type": "string"
},
"jql": {
"description": "The JQL query for the filter. For example, *project = SSP AND issuetype = Bug*.",
"readOnly": true,
"type": "string"
},
"name": {
"description": "The name of the filter.",
"type": "string"
},
"owner": {
"allOf": [
{
"$ref": "#/components/schemas/User"
}
],
"description": "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.",
"readOnly": true
},
"searchUrl": {
"description": "A URL to view the filter results in Jira, using the [Search for issues using JQL](#api-rest-api-3-filter-search-get) 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*.",
"format": "uri",
"readOnly": true,
"type": "string"
},
"self": {
"description": "The URL of the filter.",
"format": "uri",
"readOnly": true,
"type": "string"
},
"sharePermissions": {
"description": "The groups and projects that the filter is shared with. This can be specified when updating a filter, but not when creating a filter.",
"items": {
"additionalProperties": false,
"description": "Details of a share permission for the filter.",
"properties": {
"group": {
"allOf": [
{
"$ref": "#/components/schemas/GroupName"
}
],
"description": "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."
},
"id": {
"description": "The unique identifier of the share permission.",
"format": "int64",
"readOnly": true,
"type": "integer"
},
"project": {
"allOf": [
{
"$ref": "#/components/schemas/Project"
}
],
"description": "The project that the filter is shared with. This is similar to the project object returned by [Get project](#api-rest-api-3-project-projectIdOrKey-get) but it contains a subset of the properties, which are: `self`, `id`, `key`, `assigneeType`, `name`, `roles`, `avatarUrls`, `projectType`, `simplified`. \nFor a request, specify the `id` for the project."
},
"role": {
"allOf": [
{
"$ref": "#/components/schemas/ProjectRole"
}
],
"description": "The project role that the filter is shared with. \nFor 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": {
"description": "The type of share permission:\n\n * `user` Shared with a user.\n * `group` Shared with a group. If set in a request, then specify `sharePermission.group` as well.\n * `project` Shared with a project. If set in a request, then specify `sharePermission.project` as well.\n * `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`.\n * `global` Shared globally. If set in a request, no other `sharePermission` properties need to be specified.\n * `loggedin` Shared with all logged-in users. Note: This value is set in a request by specifying `authenticated` as the `type`.\n * `project-unknown` Shared with a project that the user does not have access to. Cannot be set in a request.",
"enum": [
"user",
"group",
"project",
"projectRole",
"global",
"loggedin",
"authenticated",
"project-unknown"
],
"type": "string"
},
"user": {
"allOf": [
{
"$ref": "#/components/schemas/UserBean"
}
],
"description": "The user account ID that the filter is shared with. For a request, specify the `accountId` property for the user."
}
},
"required": [
"type"
],
"type": "object"
},
"type": "array"
},
"subscriptions": {
"description": "The users that are subscribed to the filter.",
"items": {
"additionalProperties": false,
"description": "Details of a user or group subscribing to a filter.",
"properties": {
"group": {
"allOf": [
{
"$ref": "#/components/schemas/GroupName"
}
],
"description": "The group subscribing to filter.",
"readOnly": true
},
"id": {
"description": "The ID of the filter subscription.",
"format": "int64",
"readOnly": true,
"type": "integer"
},
"user": {
"allOf": [
{
"$ref": "#/components/schemas/User"
}
],
"description": "The user subscribing to filter.",
"readOnly": true
}
},
"type": "object"
},
"readOnly": true,
"type": "array"
},
"viewUrl": {
"description": "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*.",
"format": "uri",
"readOnly": true,
"type": "string"
}
},
"required": [
"name"
],
"type": "object"
},
"readOnly": true,
"type": "array"
}
},
"type": "object"
}Usage
from ocp_agent import OCPAgent
agent = OCPAgent()
await agent.register_api('jira')
# Call this tool
result = await agent.call_tool('getFiltersPaginated', {
# Add required parameters here
})