Skip to content

Find an issue of the project’s Jira by its link or key

POST
/v1/bugs/jira/find
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.

X-Plune-Project
string

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.

Media type application/json
object
ref
required

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.

string
>= 1 characters <= 2048 characters
Examples

A link to the issue

{
"ref": "https://acme.atlassian.net/browse/ACME-123"
}

The issue

Media type application/json

An issue of the project’s Jira as the import dialog shows it (#1069). Nothing of it is stored.

object
key
required

Jira’s key of the issue.

string
askedKey
required

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.

string
url
required

https://<site>/browse/<key>.

string
title
required

The summary, cut at 200 characters (the last one «…»); the key when the summary is blank.

string
>= 1 characters <= 200 characters
description
required

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.

string
nullable
status
required
string
statusCategory
required

new, indeterminate, done or undefined, as Jira gives it.

string
<= 64 characters
priority
required
string
nullable
assignee
required

The name Jira shows - never the e-mail.

string
nullable
attachments
required

The first 100.

Array<object>
<= 100 items
object
id
required
string
filename
required
string
size
required

Bytes, as Jira counts them.

integer
mimeType
required
string
nullable
attachmentsTotal
required

How many files the issue has.

integer
updated
required

When the issue last changed in Jira.

string format: date-time
existing
required

The live bug that mirrors the issue already - an import brings it up to date; null when there is none.

object
id
required
string format: uuid
number
required
integer
>= 1
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

Media type application/json
object
error
required
string
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 / invalid session — a CLI token is refused here, as on the routes of the Jira connection

Media type application/json
object
error
required
string
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

Media type application/json
object
error
required
string
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)

Media type application/json
object
error
required
string
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

Media type application/json
object
error
required
string
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"
}

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

Media type application/json
object
error
required
string
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"
}

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.

Media type application/json
object
error
required
string
Example generated
{
"error": "example"
}
Retry-After
integer

Seconds until the window rolls over

The server has no key to keep Jira tokens under; Jira was not asked

Media type application/json
object
error
required
string
Example
{
"error": "Jira is not configured on this server — contact your operator"
}