[torrresagus]

What changed in the API

Notice jira-cloud-change-2046-search-jql about atlassian.net's API describes this change, published 2024-10-31 and effective 2025-05-01. It is not signed by atlassian.net: it was read from a file the person running Tiltmeter trusts.

The notice's summary:

Jira Cloud removed GET and POST /rest/api/3/search and /rest/api/2/search, which now answer 410
Gone, in favor of /rest/api/3/search/jql and /rest/api/2/search/jql, which page with nextPageToken
instead of startAt, return no total, and return only issue ids unless the request names its fields.
Jira Server and Data Center keep the old endpoints: code that serves both must switch only for Cloud
sites. Source: https://developer.atlassian.com/changelog/#CHANGE-2046

GET https://your-domain.atlassian.net/rest/api/2/search

Severity	Change	Path	Before	After
breaking	endpoint_removed	$	—	(gone), moved to GET https://your-domain.atlassian.net/rest/api/2/search/jql
breaking	field_removed	$.startAt	—	(absent)
breaking	field_removed	$.total	—	(absent)
breaking	field_removed	$.maxResults	—	(absent)

POST https://your-domain.atlassian.net/rest/api/2/search

Severity	Change	Path	Before	After
breaking	endpoint_removed	$	—	(gone), moved to POST https://your-domain.atlassian.net/rest/api/2/search/jql
breaking	field_removed	$.startAt	—	(absent)
breaking	field_removed	$.total	—	(absent)
breaking	field_removed	$.maxResults	—	(absent)

The notice's notes:

GET /rest/api/2/search: Query parameters: jql, nextPageToken instead of startAt, maxResults, fields,
expand. fields defaults to id only: pass the fields the code reads, such as fields=*navigable. Only
Jira Cloud (*.atlassian.net, api.atlassian.com/ex/jira) removed it; Server and Data Center sites
keep the old endpoint.
$.startAt: Pages are fetched with nextPageToken: pass the nextPageToken of the previous page; isLast
is true on the last page.
$.total: To count matching issues, POST /rest/api/2/search/approximate-count with body {"jql":
"..."}; it returns {"count": n}.
POST /rest/api/2/search: Body: jql, nextPageToken instead of startAt, maxResults, fields (a list),
expand (a string). fields defaults to id only: send the fields the code reads, such as
["*navigable"]. Only Jira Cloud (*.atlassian.net, api.atlassian.com/ex/jira) removed it; Server and
Data Center sites keep the old endpoint.

What this pull request changes

Jira Cloud has removed /rest/api/2/search. Sites on *.atlassian.net and api.atlassian.com/ex/jira now use /rest/api/2/search/jql, which pages with nextPageToken and ends on isLast. Server and Data Center sites keep the old startAt/total paging unchanged. The Cloud path still sends the explicit fields and changelog expand, refuses to confirm a checkpoint if it gets an empty page or no token before the last page, and has new tests.

• crates/utopia-server/src/jira_issues.rs

Left for a human

• Nothing was compiled or tested because no shell was available. Please run cargo fmt --all --check, cargo clippy --workspace --all-targets -- -D warnings and cargo test --workspace before merging.
• CONTRIBUTING.md asks for a DCO sign-off (git commit -s) and a PR against dev rather than main. Edits can't do either; whoever commits and opens the PR needs to.
• If a Cloud response leaves out isLast, it is read as false. Then a page with no nextPageToken fails loudly instead of ending the sync. That is safe for checkpoints, but it has not been checked against a live Cloud site.

---

This pull request was generated automatically by Tiltmeter from the unsigned notice jira-cloud-change-2046-search-jql about atlassian.net's API. An AI agent (Claude Code with claude-opus-5-5) wrote these edits; review them like any other change.

[WaylandYang]

Thanks — Cloud-only switch, token paging and the early-end guard look right. Merging; I'll update the docs' note on Jira's total (sources.md, ADR 0072) separately.