Skip to content

Import from Jira by filter, on a schedule

PUT
/v1/projects/{id}/integrations/jira/poll
curl --request PUT \
--url https://beta-api.plune.ai/v1/projects/example/integrations/jira/poll \
--header 'Content-Type: application/json' \
--cookie plune_session=<plune_session> \
--data '{ "enabled": true, "filterId": "10010", "intervalMinutes": 15 }'

Owner only. Sets the poll by filter (#1070, ADR 0072 §3, §10): a saved filter of Jira by its id (its JQL is read from Jira at every poll) or JQL typed here, every intervalMinutes (15 on a new connection, the saved one when left out, 5 at the most often, a day at the least often), and the switch. Each pass asks Jira for what the filter holds that changed since 10 minutes before the start of the last pass, oldest first, and brings every issue in as the import by link does — a new bug, or the mirror brought up to date; an issue that did not change is left alone. Jira is not asked here: the first pass runs within a minute and GET shows what it did (poll.last). Another filter starts over, from the whole of it. { "enabled": false } stops it and keeps the saved filter and interval, so it can be switched on again as it was. A connection that is not working, disconnected, or paused for the tier, is not polled. Recorded in the audit feed of the project as a jira_connection entry; the bugs a pass makes or changes are bug entries of the actor system:jira-poll. Needs a tier with issue trackers. Session cookie only.

id
required
string

An id from GET /v1/projects

Media type application/json

The poll by filter (#1070). enabled needs filterId or jql, not both; { "enabled": false } keeps the saved filter and interval.

object
enabled
required
boolean
filterId

A saved filter of Jira, by its id: its JQL is read from Jira at every poll, so an edit there takes effect without Plune.

string
/^[0-9]{1,18}$/
jql

JQL typed in Plune. Its ORDER BY is dropped: a poll asks for the oldest change first.

string
>= 1 characters <= 2000 characters
intervalMinutes

Every N minutes: left out, the saved interval stays (15 on a new connection); 5 at the most often.

integer
>= 5 <= 1440
Example
{
"enabled": true,
"filterId": "10010",
"intervalMinutes": 15
}

Set — 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: an interval outside its bounds, a filter id that is not digits, JQL over its length, both a filter and JQL, or enabled with neither

Media type application/json
object
error
required
string
Example
{
"error": "validation failed — intervalMinutes: Too small: expected number to be >=5"
}

No / invalid session — a CLI token is refused here

You are in the project, but not as its owner; or (with TIER_LIMITS_ENFORCE=true) a tier without the issue_trackers permission

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

No such project among yours, or no Jira was ever connected

Media type application/json
object
error
required
string
Examples

No such project among yours

{
"error": "project 'u-shop::default' not found"
}

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 tokens under

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