Your Jira Scripts and Automations May Break if they use JQL Search APIs

[#1]

Ohai everyone. Welcome to the latest installment of  "stuff Atlassian may break that you didn't know about".

In today's episode: Atlassian is deprecating some JQL search API endpoints on May 1, 2025.

Now to give them credit, they did send an email about this back in January:

The difficulty in communicating such a message is they (and maybe you) have no idea how YOUR JIRA might break due to these changes. Here's a couple of scenarios I thought of. (And thanks to @Matt Doar _Adaptavist_ for giving me the heads-up about this, because yup, I ignored the email too.)

#1 - ScriptRunner

As they did re: Jira Expression changes, our fine friends at Adaptavist once again sent their own email to their ScriptRunner customers, entitled: Action required: Jira Platform REST endpoint deprecation.

The ScriptRunner team has built-in a tool that searches your any of your scripts (Listeners, Scheduled Jobs, Behaviours) to see if they are using any of the deprecated endpoints and gives you a heads-up if so. That is AWESOME. They also have recommendations on how to rewrite your scripts to use the new endpoints.

So if you've got ScriptRunner, I highly recommend you head over to their Deprecation Reports tool and check it out.

#2 - Automation

Considering Automation has several built in actions/triggers that let you do JQL queries, it's unlikely that you'd be using the deprecated API endpoints to do JQL searches.

But hey, it's technically possible, since we (and others) have been advising people on how to use Web Requests to talk to the Jira REST APIs for a while now.

But it's easy enough to Export all of your automation rules and then do a grep (or find) for these endpoints:

• /rest/api/(2|3|latest)/search
• /rest/api/(2|3|latest)/search/id

(2|3|latest) means that ANY of those could be used in your Automation. Ex:

https://YOURSITE.atlassian.net/rest/api/2/search?jql=project=%20%3D%20HSP

OR

https://YOURSITE.atlassian.net/rest/api/latest/search?jql=project=%20%3D%20HSP

(Do note that the new API contains the search substring: /rest/api/(2|3|latest)/search/jql, so you'll want to search for reference that don't include 'search/jql')

#3 - Custom Python scripts

So, the good news is that the popular Python modules for interfacing with Jira have been updated to support the new API endpoints. Looks like unlike Atlassian, they've updated their code to make sure nothing breaks, so just update your packages and go! Here's the change requests that detail what's new:

• jira: enhancement: Add enhanced_search_issues API for Jira Cloud using new search/jql endpoint (#2326) 
• atlassian-python-api: [JIRA] Add search/jql and search/approximate-count APIs support for Jira Cloud (#1513) 

#4 Custom shell scripts / Jenkins jobs / etc.

So, if you're like me, you may have various bash/zsh or other shell scripting language of your choice calling curl, or maybe you have scripts like that as Jenkins jobs or somesuch.

Welp. You're going to have to dig into those by hand (again, looking for the same strings mentioned above) and change the endpoints and possibly the logic, as pagination has changed.

There's a highly technical article from @Grzegorz Lewandowski that talks about that as well as optimizations and efficiencies. It's a little over my head, but hopefully it helps somebody.

• Avoiding Pitfalls: A Guide to Smooth Migration to Enhanced JQL APIs - Blog Post 

---

At any rate, I hope if you ARE using these deprecated endpoints that you see this and this points you in the right direction. Good luck!

[__ Jimi Wikman]

Great reminder Darryl!

[Rick Westbrock]

I had updated our script listeners based on an e-mail notification from Adaptavist but wasn't aware of the deprecation report so thanks for calling it out.

[Yatish Madhav]

Thanks for this post, @Darryl Lee 

'... stuff Atlassian may break that you didn't know about ...' hehe that's funny!

We found this out the hard way (and worse, i did not even get that email) when some of our automation broke but managed to fix it quite quickly. And even more sore, was that the 'Automated Log Work for Jira' add-on that used the end point broke and is no longer maintained it seems. So we had to further fix our way to continue ... On the plus side, we are developing our own in house scripts to generate reports that the add-on did for us.

API work is tough and deprecations are part of that lifecycle so it is always great to be on top of it.

Thank you

Yatish