Find an issue of the project’s Jira by its link or key
const url = 'https://beta-api.plune.ai/v1/bugs/jira/find';const options = { method: 'POST', headers: { cookie: 'plune_session=<plune_session>', 'Content-Type': 'application/json' }, body: '{"ref":"https://acme.atlassian.net/browse/ACME-123"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://beta-api.plune.ai/v1/bugs/jira/find \ --header 'Content-Type: application/json' \ --cookie plune_session=<plune_session> \ --data '{ "ref": "https://acme.atlassian.net/browse/ACME-123" }'The first step of «Import from Jira» (#1069, ADR 0072 §2): reads the issue once and writes nothing - not even a bug. The session cookie alone, as on the routes of the Jira connection: a CLI token is refused (401), since a leaked one must not read the customer’s Jira through the owner’s token. The owner’s alone, with a tier that has issue trackers, the Bugs section on and the project’s Jira connection working; otherwise Jira is not asked. A link must be to the site of the connection (400 jira_other_site, with site) and hold a key in its path or query (400 jira_no_key, as does text with no key in it); a bare key is read on that site. existing names the live bug that mirrors the issue already. A read Jira answered sets the connection’s lastReadAt; a 401 or Jira’s IP allowlist sets its state, as a check does. At most 60 calls a minute from you.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Header Parameters
Section titled “Header Parameters ”Which of your projects to act in — an id from GET /v1/projects. Absent, your default project. A project you are not a member of answers 404, the same as one that does not exist. Ignored under a bearer token, which is bound to the project it was minted in.
Request Body required
Section titled “Request Body required ”object
A link to the issue on the site of the project’s connection, or its key (ACME-123, any case) - trimmed. The first link anywhere in the text decides - in a sentence, in <…>, in Markdown or in quotes - and its key is the first one in its path or query; only text with no link is searched for a key. A link is one of three forms - scheme://…, //host…, or [user@]host[:port] right before /, ?, # or \; anything else is text: an e-mail address, host:port, word:, a word with a dot (2.4, log.txt). A link of any scheme but http(s) is to another site.
Examples
A link to the issue
{ "ref": "https://acme.atlassian.net/browse/ACME-123"}Its key
{ "ref": "acme-123"}Responses
Section titled “ Responses ”The issue
An issue of the project’s Jira as the import dialog shows it (#1069). Nothing of it is stored.
object
Jira’s key of the issue.
The key of the link or the text, in upper case. Another than key when the issue moved to another project, which Jira answers with its new key.
https://<site>/browse/<key>.
The summary, cut at 200 characters (the last one «…»); the key when the summary is blank.
The description as plain text - paragraphs, headings, lists, code and the text of links kept, pictures and macros left out - cut at 16384 bytes between two characters; null when there is none.
new, indeterminate, done or undefined, as Jira gives it.
The name Jira shows - never the e-mail.
The first 100.
object
Bytes, as Jira counts them.
How many files the issue has.
When the issue last changed in Jira.
The live bug that mirrors the issue already - an import brings it up to date; null when there is none.
object
Example
{ "key": "ACME-123", "askedKey": "ACME-123", "url": "https://acme.atlassian.net/browse/ACME-123", "title": "Checkout total ignores the coupon", "description": "Apply SAVE10, then pay: the total is the full price.", "status": "In Progress", "statusCategory": "indeterminate", "priority": "High", "assignee": "John Doe", "attachments": [ { "id": "10001", "filename": "screen.png", "size": 219136, "mimeType": "image/png" }, { "id": "10002", "filename": "checkout.log", "size": 4096, "mimeType": "text/plain" } ], "attachmentsTotal": 2, "updated": "2026-10-31T10:05:00.000Z", "existing": null}Invalid body, a link to another site (code: jira_other_site, with site), or no key in it (code: jira_no_key); Jira was not asked
object
Examples
A link to another Jira
{ "error": "the link is not to acme.atlassian.net, the Jira this project is connected to", "code": "jira_other_site", "site": "acme.atlassian.net"}No key in it
{ "error": "no issue key in it — paste a link to the issue or its key, as ACME-123", "code": "jira_no_key"}No / invalid session — a CLI token is refused here, as on the routes of the Jira connection
object
Example
{ "error": "sign in required"}You are in the project as a reader, or not as its owner; or (only once the operator sets TIER_LIMITS_ENFORCE=true) a tier without the issue_trackers permission, answered in English then Ukrainian, naming the feature, with feature and tier
object
Example
{ "error": "project owner only"}Jira did not give the issue — a 404 or a 403: it does not exist, or the account of the connection may not see it, which Jira does not tell apart (code: jira_issue_unavailable, with key); or the project of X-Plune-Project is not one of yours (project '…' not found, as for a project nobody has, and Jira is not asked)
object
Example
{ "error": "Jira did not give issue ACME-999: it does not exist, or the account of the connection may not see it", "code": "jira_issue_unavailable", "key": "ACME-999"}The Bugs section is off in this project (code: bugs_disabled); or the project’s Jira connection is not working (code: jira_not_working, state one of rejected, ip_blocked, paused, no_token, error, none — none when it was never connected, no_token after a Disconnect, error when this server cannot read the saved token; paused is not met here, a tier that refuses Jira is the 403); Jira was not asked
object
Examples
The connection was disconnected
{ "error": "the project’s Jira connection is not working — its owner sees why in Settings → Integrations", "code": "jira_not_working", "state": "no_token"}The Bugs section is off
{ "error": "the Bugs section is off for this project: an owner turns it on in the project settings", "code": "bugs_disabled"}Jira did not give the issue for a reason of its own; what Jira wrote is never passed on. jira_token_rejected — a 401: the connection becomes rejected and its token is not sent again until the owner connects anew; jira_ip_blocked — Jira’s IP allowlist refused Plune: the connection becomes ip_blocked; jira_rate_limited — a 429, with retryAfterSec (Jira’s Retry-After, else 30); jira_unreachable — a 5xx, the network, the 15 s deadline, a redirect, an answer over 1 MB or one Plune cannot read. A 424 and not a 502/504: a proxy replaces the body of those
object
Examples
Jira rejected the token
{ "error": "Jira rejected the token of the project’s connection — its owner connects it again with a new token", "code": "jira_token_rejected"}The IP allowlist refused Plune
{ "error": "your company’s Jira accepts requests only from a list of addresses — add Plune’s address to it", "code": "jira_ip_blocked"}Jira asked Plune to slow down
{ "error": "Jira asked Plune to slow down — try again in 30 seconds", "code": "jira_rate_limited", "retryAfterSec": 30}Jira did not answer
{ "error": "Jira did not answer — try again in a few minutes", "code": "jira_unreachable"}Rate-limited: the per-route throttle, or the per-minute request limit of the plan an API token counts by (#1442; the body names the plan, #2092). Retry-After carries the seconds until the window rolls over.
object
Example generated
{ "error": "example"}Headers
Section titled “Headers ”Seconds until the window rolls over
The server has no key to keep Jira tokens under; Jira was not asked
object
Example
{ "error": "Jira is not configured on this server — contact your operator"}