Test and connect Jira Cloud, or change the connection
const url = 'https://beta-api.plune.ai/v1/projects/example/integrations/jira';const options = { method: 'PUT', headers: { cookie: 'plune_session=<plune_session>', 'Content-Type': 'application/json' }, body: '{"site":"acme.atlassian.net","tokenKind":"scoped","email":"user@plune.ai","token":"ATATT_EXAMPLE_not_a_real_jira_token_000000000000"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request PUT \ --url https://beta-api.plune.ai/v1/projects/example/integrations/jira \ --header 'Content-Type: application/json' \ --cookie plune_session=<plune_session> \ --data '{ "site": "acme.atlassian.net", "tokenKind": "scoped", "email": "user@plune.ai", "token": "ATATT_EXAMPLE_not_a_real_jira_token_000000000000" }'Owner only. Runs the two checks of POST …/test with what was sent, and saves the connection only if both passed — the token encrypted with the server’s key, bound to this project, never returned — answering with what GET shows. A check that failed saves nothing and answers 422 with the checks. Left out of an edit of the same site, token is the saved one — unless Jira rejected it, which only a new token replaces. A Disconnect or another save landing while the checks ran is not overwritten: the answer is 409 and nothing is saved. Recorded in the audit feed of the project as a jira_connection entry, the token masked and the e-mail left out. At most 10 checks a minute for a project, this and POST …/test together, counted after the role. Needs a tier with issue trackers (Personal and up). Session cookie only.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”An id from GET /v1/projects
Request Body required
Section titled “Request Body required ”A Jira Cloud site and an Atlassian API token (ADR 0072 §1). A field this API does not know is refused, and no refusal quotes a value.
object
Your Jira Cloud site: acme.atlassian.net, or an address on it (https://acme.atlassian.net/jira/…) — the host is kept, lower-cased. A custom domain is not supported yet.
scoped — a token with scopes (read: read:jira-work), asked through api.atlassian.com/ex/jira/{cloudId}; classic — a token without scopes, asked at the site. Plune does not guess: each rejected try brings Jira’s CAPTCHA nearer.
The e-mail of the Atlassian account the token belongs to.
Write-only: the API token. Stored encrypted, bound to the project, and in no response, no log and no error message. Required for a new connection and after Disconnect; left out of an edit of the same site, the saved one is kept.
Example
{ "site": "acme.atlassian.net", "tokenKind": "scoped", "email": "user@plune.ai", "token": "ATATT_EXAMPLE_not_a_real_jira_token_000000000000"}Responses
Section titled “ Responses ”Connected — the same body as GET
object
null when no Jira was ever connected.
object
working; rejected — Jira answered 401: a new token is needed, and Plune does not send this one again; ip_blocked — Jira’s IP allowlist refused Plune; error — another failure, stateReason says which; paused — the project’s tier does not include issue trackers (Free, an expired tier or one switched off) while the operator enforces the tier limits: nothing is asked of Jira and nothing is lost; no_token — disconnected: the settings stay, a token connects it again (a disconnected connection reads no_token, never paused).
The code of the last failure when state is rejected, ip_blocked or error; null otherwise.
When the saved connection was last checked: the save itself, or POST …/test.
When Jira last answered a read — what Plune holds of Jira is as of this time.
userId of the owner who connected it, or last changed it.
userId of the owner who disconnected it; null while connected.
Owner only: the e-mail of the Atlassian account.
The poll by filter (#1070) as a member reads it.
object
When the next pass is due; null while the poll is off.
A pass runs now (it holds the lease). While it does, nextPollAt is a watchdog for a lost pass, not the next poll: the pass sets that when it ends.
The start of the last pass that read to the end: the next asks Jira for what changed since 10 minutes before it.
null until the first pass, and after the filter changed.
object
Issues that wrote nothing: their mirror keeps the same updated, it is detached for a reason other than left_filter, or a bug adopted into Plune holds the issue - it is not mirrored again (decision of 12.11.2026).
null — read to the end, or to its cap of issues (the next pass goes on from there a minute later). rejected / ip_blocked — Jira answered 401 / its IP allowlist refused Plune: the connection takes that state and polling stops. busy — Jira answered 429: the pass is tried again after its Retry-After at the least (retryAt), four tries in all; unreachable — a 5xx, the network, a redirect: the same tries. filter_unavailable — the saved filter is gone, or the account may not see it; filter_invalid — Jira refused the JQL; too_large — a page of the search is over 1 MB; bugs_disabled — the project’s Bugs section is off; bugs_quota — the project holds as many bugs as its plan allows; token_unreadable — this server’s key does not open the saved token. All but the first two are tried again at the next poll.
When a busy or unreachable pass is tried again; null otherwise.
The start of the last full pass (ADR 0072 §3): the whole filter read, not only what changed, and every mirror of the site the filter no longer holds detached with left_filter. The next one is due 24 h later; absent until the first.
The left_filter mirrors this pass attached again: their issue is in the filter again - any pass that brings it, the full one or the window. Absent on an outcome from before the re-attach.
The mirrors this pass detached as left_filter - only a full pass does. Absent on an outcome from before the full pass.
Only when a full pass that read to the end detached nothing by its safety valve: empty - the filter held no issue; too_many - more than half of the site’s filter mirrors, and 5 or more, would have gone at once (fewer than 5 are detached). mirrors: the site’s live mirrors the filter brought; missing: those the pass did not find. Nothing is detached until a full pass finds the filter as it should be.
object
The event → transition table (#1071, Р325): the issue its transitions were read from, and the transition «verified» makes - null, a comment only.
object
object
The addresses Plune calls Jira from, for a Jira that takes requests from an allowlist only (ADR 0072 §9). A change of them is announced 14 days ahead. Empty when the server names none.
true exactly when PUT would be refused now for the tier (403, issue_trackers: TIER_LIMITS_ENFORCE=true and a tier without issue trackers — Free, an expired tier or one switched off); worked out as paused is. Unlike paused it says so with nothing connected and after Disconnect. Always false in report mode.
Example
{ "connection": { "site": "acme.atlassian.net", "tokenKind": "scoped", "state": "working", "stateReason": null, "checkedAt": "2026-09-16T09:12:04.151Z", "lastReadAt": "2026-09-16T09:12:04.151Z", "connectedBy": "u-shop", "connectedAt": "2026-09-16T09:12:04.151Z", "disconnectedBy": null, "disconnectedAt": null, "email": "user@plune.ai", "poll": { "enabled": true, "filterId": "10010", "jql": null, "intervalMinutes": 15, "nextPollAt": "2026-10-29T09:15:00.000Z", "running": false, "lastPolledAt": "2026-09-16T09:12:04.151Z", "last": { "startedAt": "2026-09-16T09:12:04.151Z", "finishedAt": "2026-09-16T09:12:04.151Z", "created": 2, "updated": 1, "unchanged": 4, "error": null, "retryAt": null, "fullPassAt": "2026-09-16T09:12:04.151Z", "reattached": 0, "detached": 0 } }, "write": { "sampleIssue": "ACME-123", "verified": { "id": "31", "name": "Close issue", "toId": "10002", "toName": "Done" } } }, "outboundAddresses": [ "203.0.113.7" ], "paidOnly": false}Invalid body, a site that is not <name>.atlassian.net, or no token where none can be used for the site (none saved, Jira rejected the saved one, or it does not open under this server’s key); the message names the field and never a value. Nothing was sent to Jira
object
Examples
No token, and none saved for this site that can be used
{ "error": "validation failed — token: is required — no token is saved for this site, Jira rejected the saved one, or this server cannot read it"}A custom domain
{ "error": "validation failed — site: must be your Jira Cloud site, as acme.atlassian.net - a custom domain is not supported yet"}No / invalid session — a CLI token is refused here
You are in the project, but 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"}No such project among yours
object
Example
{ "error": "project 'u-shop::default' not found"}The checks passed, but the connection changed while they ran — a Disconnect, another save, or another first connect; nothing was saved: try again
object
Example
{ "error": "the connection changed while it was being checked — try again"}A check failed; nothing was saved. The body is the check, as POST …/test answers it, with error. A failed check carries one of these codes and Plune’s own sentence in message — never what Jira wrote: ip_blocked — Jira’s IP allowlist refused Plune: add the addresses of outboundAddresses to it (its sentence read in the body of an error answer, whatever its status; a 2xx that quotes it is an answer); rejected — a 401: the token is mistyped, expired or revoked, or the other kind of token was chosen; forbidden — a 403; unavailable — a 404: no site there, or no API for this kind of token; busy — a 429: Jira asks Plune to slow down, retryAfterSec when it said how long; invalid — another 4xx, or an answer Plune cannot read; unreachable — a 5xx, the network or the 15 s deadline; redirect — Jira sent Plune elsewhere, which Plune does not follow; too_large — an answer over 1 MB; no_permission — the token reads, but the account may not browse projects.
object
object
Present exactly when result is failed.
Present exactly when result is failed: Plune’s sentence for the page. Never what Jira wrote.
busy only: the seconds Jira asked to wait, when it said.
Example
{ "error": "the connection did not pass its checks — nothing was saved", "ok": false, "steps": [ { "step": "site", "result": "ok" }, { "step": "token", "result": "failed", "code": "rejected", "message": "Jira rejected the token, or the wrong kind of token was chosen - check the token and whether it is a token with scopes." } ], "testedAt": "2026-09-16T09:12:04.151Z"}More than 60 saves a minute from you, or more than 10 checks a minute for this project. 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 tokens under; nothing is saved
object
Example
{ "error": "Jira is not configured on this server — contact your operator"}