/rest/api/3/filter/search unofficial query params

Forge
1

Hi,

I’m using the Jira Cloud REST API endpoint:

GET /rest/api/3/filter/search?query=myQuery

and I’m seeing a different result set when I include the query parameter compared to when I call the same endpoint without it, e.g.:

GET /rest/api/3/filter/search
GET /rest/api/3/filter/search?query=myQuery

However, in the official Jira Cloud REST API documentation for GET /rest/api/3/filter/search there is no query parameter listed – only parameters like filterName, accountId, owner, groupname, groupId, projectId, id, expand, overrideSharePermissions, startAt, and maxResults.developer.atlassian

My questions are:

  1. Is the query parameter officially supported on /rest/api/3/filter/search?

  2. If yes, what exactly does it filter on (name, description, owner, JQL, etc.)?

  3. If it is an experimental or internal parameter, is it safe to rely on it in production code, or should we only use the documented parameters like filterName?

  4. Are there any plans to document this behavior (similar to how overrideSharePermissions was documented as an experimental parameter for this endpoint)?

Right now I’m hesitant to depend on query in production, because it’s not mentioned in the public docs, but it clearly affects the results in my environment.

Thanks in advance for any clarification from the Jira Cloud REST API team.

2

Hi Simon,

Great question, and totally understandable why this is confusing!

The query parameter is not listed in the official Jira Cloud REST API documentation for GET /rest/api/3/filter/search. The documented parameters for this endpoint are: filterName, accountId, owner, groupname, groupId, projectId, id, expand, overrideSharePermissions, startAt, and maxResults.

Since query is undocumented:

  • Its behavior is not officially specified : what it searches on (name, description, JQL, etc.) is not guaranteed.

  • It offers no stability guarantee

  • It’s not recommended for production use for these reasons.

For a reliable, supported approach, use the filterName parameter to search filters by name:

GET /rest/api/3/filter/search?filterName=myQuery

For Example, filterName returns exactly 1 match

$ curl -s -u "$EMAIL:$API_TOKEN" 
"https://YOUR-SITE.atlassian.net/rest/api/3/filter/search?filterName=CBB&maxResults=5" | python3 -m json.tool

{
    "self": "https://YOUR-SITE.atlassian.net/rest/api/3/filter/search?maxResults=5&filterName=CBB&startAt=0",
    "maxResults": 5,
    "startAt": 0,
    "total": 1,
    "isLast": true,
    "values": [
        {
            "expand": "description,owner,jql,viewUrl,searchUrl,favourite,favouritedCount,sharePermissions,editPermissions,isWritable,approximateLastUsed,subscriptions",
            "self": "https://YOUR-SITE.atlassian.net/rest/api/3/filter/10012",
            "id": "10012",
            "name": "Filter for CBB board"
        }
    ]
}

Where as query results 27 entries with max 5 results incorrect match


$ curl -s -u "$EMAIL:$API_TOKEN"
"https://YOUR-SITE.atlassian.net/rest/api/3/filter/search?query=CBB&maxResults=5" | python3 -m json.tool

{
    "self": "https://YOUR-SITE.atlassian.net/rest/api/3/filter/search?maxResults=5&query=CBB&startAt=0",
    "nextPage": "https://YOUR-SITE.atlassian.net/rest/api/3/filter/search?maxResults=5&query=CBB&startAt=5",
    "maxResults": 5,
    "startAt": 0,
    "total": 27,
    "isLast": false,
    "values": [
        {
            "expand": "description,owner,jql,viewUrl,searchUrl,favourite,favouritedCount,sharePermissions,editPermissions,isWritable,approximateLastUsed,subscriptions",
            "self": "https://YOUR-SITE.atlassian.net/rest/api/3/filter/10076",
            "id": "10076",
            "name": "dashboard_check"
        },
        {
            "expand": "description,owner,jql,viewUrl,searchUrl,favourite,favouritedCount,sharePermissions,editPermissions,isWritable,approximateLastUsed,subscriptions",
            "self": "https://YOUR-SITE.atlassian.net/rest/api/3/filter/10075",
            "id": "10075",
            "name": "dashboard_test"
        },
        {
            "expand": "description,owner,jql,viewUrl,searchUrl,favourite,favouritedCount,sharePermissions,editPermissions,isWritable,approximateLastUsed,subscriptions",
            "self": "https://YOUR-SITE.atlassian.net/rest/api/3/filter/10243",
            "id": "10243",
            "name": "Filter for CATTST1 board"
        },
        {
            "expand": "description,owner,jql,viewUrl,searchUrl,favourite,favouritedCount,sharePermissions,editPermissions,isWritable,approximateLastUsed,subscriptions",
            "self": "https://YOUR-SITE.atlassian.net/rest/api/3/filter/10244",
            "id": "10244",
            "name": "Filter for CATTST2 board"
        },
        {
            "expand": "description,owner,jql,viewUrl,searchUrl,favourite,favouritedCount,sharePermissions,editPermissions,isWritable,approximateLastUsed,subscriptions",
            "self": "https://YOUR-SITE.atlassian.net/rest/api/3/filter/10012",
            "id": "10012",
            "name": "Filter for CBB board"
        }
    ]
}

If you need broader, multi-field search capabilities, it’s worth raising a feature request on the Jira Cloud issue tracker — that’s the best way to get it prioritized and potentially officially documented.

Hope this helps clarify things! :slightly_smiling_face: