Skip to content

Test and connect Jira Cloud, or change the connection

PUT
/v1/projects/{id}/integrations/jira
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.

id
required
string

An id from GET /v1/projects

Media type application/json

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
site
required

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.

string
<= 300 characters
tokenKind
required

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.

string
Allowed values: scoped classic
email
required

The e-mail of the Atlassian account the token belongs to.

string
<= 254 characters
token

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.

string
>= 1 characters <= 1024 characters
Example
{
"site": "acme.atlassian.net",
"tokenKind": "scoped",
"email": "user@plune.ai",
"token": "ATATT_EXAMPLE_not_a_real_jira_token_000000000000"
}

Connected — the same body as GET

Media type application/json
object
connection
required

null when no Jira was ever connected.

object
site
required
string
tokenKind
required
string
Allowed values: scoped classic
state
required

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).

string
Allowed values: working rejected ip_blocked error paused no_token
stateReason
required

The code of the last failure when state is rejected, ip_blocked or error; null otherwise.

string
nullable
checkedAt
required

When the saved connection was last checked: the save itself, or POST …/test.

string format: date-time
nullable
lastReadAt
required

When Jira last answered a read — what Plune holds of Jira is as of this time.

string format: date-time
nullable
connectedBy
required

userId of the owner who connected it, or last changed it.

string
connectedAt
required
string format: date-time
disconnectedBy
required

userId of the owner who disconnected it; null while connected.

string
nullable
disconnectedAt
required
string format: date-time
nullable
email

Owner only: the e-mail of the Atlassian account.

string
poll
required

The poll by filter (#1070) as a member reads it.

object
enabled
required
boolean
filterId
required
string
nullable
jql
required
string
nullable
intervalMinutes
required
integer
nextPollAt
required

When the next pass is due; null while the poll is off.

string format: date-time
nullable
running
required

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.

boolean
lastPolledAt
required

The start of the last pass that read to the end: the next asks Jira for what changed since 10 minutes before it.

string format: date-time
nullable
last
required

null until the first pass, and after the filter changed.

object
startedAt
required
string format: date-time
finishedAt
required
string format: date-time
created
required
integer
updated
required
integer
unchanged
required

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).

integer
error
required

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.

string
nullable
Allowed values: rejected ip_blocked busy unreachable filter_unavailable filter_invalid too_large bugs_disabled bugs_quota token_unreadable
retryAt
required

When a busy or unreachable pass is tried again; null otherwise.

string format: date-time
nullable
fullPassAt

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.

string format: date-time
reattached

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.

integer
detached

The mirrors this pass detached as left_filter - only a full pass does. Absent on an outcome from before the full pass.

integer
detachSkipped

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
reason
required
string
Allowed values: empty too_many
mirrors
required
integer
missing
required
integer
write
required

The event → transition table (#1071, Р325): the issue its transitions were read from, and the transition «verified» makes - null, a comment only.

object
sampleIssue
required
string
nullable
verified
required
object
id
required
string
name
required
string
toId
required
string
toName
required
string
outboundAddresses
required

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.

Array<string>
paidOnly
required

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.

boolean
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

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

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

Media type application/json
object
error
required
string
Example
{
"error": "project owner only"
}

No such project among yours

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

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

Media type application/json
object
ok
required
boolean
steps
required
Array<object>
object
step
required
string
Allowed values: site token
result
required
string
Allowed values: ok failed skipped
code

Present exactly when result is failed.

string
Allowed values: ip_blocked rejected forbidden unavailable busy invalid unreachable redirect too_large no_permission
message

Present exactly when result is failed: Plune’s sentence for the page. Never what Jira wrote.

string
retryAfterSec

busy only: the seconds Jira asked to wait, when it said.

integer
testedAt
required
string format: date-time
error
required
string
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

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 tokens under; nothing is saved

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