API reference

Issue automation and webhooks

Automation rules and their runs, incoming automation webhooks, outgoing webhooks, and notifications.

`POST /v1/hooks/issues/:orgId/:ruleId/:token`

Runs an incoming-webhook rule: on issues (keys) when given, otherwise on the rule's query; payload is available as {{payload.…}}.

Auth: none

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:ruleId`	Rule id: a storage lifecycle rule (as returned by the settings or lifecycle routes) or an issue automation rule (`rul_…`).
`:token`	The rule's incoming-webhook token (shown once when issued).

Response 200

{
  status: string
  matched: number
}

Errors

Status	Message
`400`	Send JSON.
`400`	Send { issues?: string[], payload?: any }.

`GET /v1/orgs/:orgId/issues/notifications`

Notifications, newest first (unread=1 for unread only); page with cursor.

Auth: user access token or platform agent key · Scope: issues:read

Path parameter	Description
`:orgId`	Organization id (`org_…`).

Query parameter	Type	Required	Notes
`unread`	`"0" \| "1"`	No
`cursor`	`string`	No	up to 2,000 characters
`limit`	`integer`	No	1–100; coerced from a string

Response 200

{
  notifications: {
    notificationId: string
    issueId: string
    issueKey?: string
    kind: "created" | "deleted" | "assigned" | "updated" | "transitioned" | "commented" | "mentioned" | "resolved"
    actorId?: string
    title: string
    body: string
    read: boolean
    createdAt: number
  }[]
  cursor: null | string
}

`GET /v1/orgs/:orgId/issues/notifications/count`

How many notifications are unread.

Auth: user access token or platform agent key · Scope: issues:read

Path parameter	Description
`:orgId`	Organization id (`org_…`).

Response 200

{
  unread: number
}

`POST /v1/orgs/:orgId/issues/notifications/read`

Marks notifications read (or unread with read: false); all: true for every one.

Auth: user access token or platform agent key · Scope: issues:read

Path parameter	Description
`:orgId`	Organization id (`org_…`).

Request body

Field	Type	Required	Notes
`ids`	`string[]`	No	up to 500 items; each up to 64 characters
`all`	`boolean`	No
`read`	`boolean`	No

Response 200

{
  updated: number
}

`GET /v1/orgs/:orgId/issues/notifications/settings`

Email on or off, notifications about your own changes, and muted events.

Auth: user access token or platform agent key · Scope: issues:read

Path parameter	Description
`:orgId`	Organization id (`org_…`).

Response 200

{
  settings: {
    email: boolean
    own: boolean
    muted: string[]
  }
}

`PUT /v1/orgs/:orgId/issues/notifications/settings`

Changes what the caller hears about.

Auth: user access token or platform agent key · Scope: issues:read

Path parameter	Description
`:orgId`	Organization id (`org_…`).

Request body

Field	Type	Required	Notes
`email`	`boolean`	No
`own`	`boolean`	No
`muted`	`("created" \| "updated" \| "assigned" \| "transitioned" \| "commented" \| "mentioned" \| "resolved" \| "deleted")[]`	No	up to 10 items

Response 200

{
  settings: {
    email: boolean
    own: boolean
    muted: string[]
  }
}

`GET /v1/orgs/:orgId/issues/automation`

Rules the caller can see (space narrows to one space), with the trigger types there are.

Auth: user access token or platform agent key · Scope: issues:read

Path parameter	Description
`:orgId`	Organization id (`org_…`).

Query parameter	Type	Required	Notes
`space`	`string`	No	up to 64 characters

Response 200

{
  rules: {
    ruleId: string
    name: string
    description: string
    enabled: boolean
    spaceIds: string[]
    trigger: {
      type: "issueCreated"
    } | {
      type: "issueTransitioned"
      from?: string[]
      to?: string[]
    } | {
      type: "issueUpdated"
      fields?: string[]
    } | {
      type: "issueAssigned"
    } | {
      type: "commentAdded"
      visibility?: "any" | "public" | "internal"
      by?: "agent" | "reporter" | "anyone"
    } | {
      type: "slaBreached"
      slaIds?: string[]
    } | {
      type: "scheduled"
      interval: "hourly" | "daily" | "weekly"
      hour?: number
      weekday?: number
      jql?: string
    } | {
      type: "incoming"
      jql?: string
    } | {
      type: "manual"
    }
    conditions: {
      type: "jql"
      jql: string
    } | {
      type: "fieldChanged"
      field: string
    } | {
      type: "notActor"
      actor: "assignee" | "reporter" | "automation"
    }[]
    actions: {
      type: "transition"
      transition: string
    } | {
      type: "assign"
      to: "user" | "actor" | "reporter" | "lead" | "unassigned"
      userId?: string
    } | {
      type: "setField"
      field: string
      value: unknown
    } | {
      type: "addLabels"
      labels: string[]
    } | {
      type: "removeLabels"
      labels: string[]
    } | {
      type: "comment"
      body: string
      visibility?: "public" | "internal"
    } | {
      type: "createIssue"
      summary: string
      issueType?: string
      space?: string
      subtask?: boolean
      description?: string
    } | {
      type: "link"
      linkType: string
      issue: string
    } | {
      type: "addWatcher"
      who: "user" | "actor" | "assignee" | "reporter"
      userId?: string
    } | {
      type: "webhook"
      url: string
    } | {
      type: "email"
      to: ("assignee" | "reporter" | "watchers")[]
      subject: string
      body: string
    }[]
    ownerId?: string
    hasToken: boolean
    editable: boolean
    version: number
    updatedAt: number
  }[]
  triggers: ["issueCreated", "issueTransitioned", "issueUpdated", "issueAssigned", "commentAdded", "slaBreached", "scheduled", "incoming", "manual"]
}

`POST /v1/orgs/:orgId/issues/automation`

Creates a rule. Rules for every space need issues:admin; space admins can automate their spaces.

Auth: user access token or platform agent key · Scope: issues:write

Path parameter	Description
`:orgId`	Organization id (`org_…`).

Request body

Field	Type	Required	Notes
`description`	`string`	No	up to 1,000 characters
`enabled`	`boolean`	No
`spaceIds`	`string[]`	No	up to 50 items; each up to 64 characters
`conditions`	`(object \| object \| object)[]`	No	up to 10 items
`baseVersion`	`integer`	No	≥ 0
`name`	`string`	Yes	1–100 characters; trimmed
`trigger`	`object \| object \| object \| object \| object \| object \| object \| object \| object`	Yes
`actions`	`(object \| object \| object \| object \| object \| object \| object \| object \| object \| object \| object)[]`	Yes	1–20 items

Response 201

{
  rule: {
    editable: boolean
    ruleId: string
    name: string
    description: string
    enabled: boolean
    spaceIds: string[]
    trigger: {
      type: "issueCreated"
    } | {
      type: "issueTransitioned"
      from?: string[]
      to?: string[]
    } | {
      type: "issueUpdated"
      fields?: string[]
    } | {
      type: "issueAssigned"
    } | {
      type: "commentAdded"
      visibility?: "any" | "public" | "internal"
      by?: "agent" | "reporter" | "anyone"
    } | {
      type: "slaBreached"
      slaIds?: string[]
    } | {
      type: "scheduled"
      interval: "hourly" | "daily" | "weekly"
      hour?: number
      weekday?: number
      jql?: string
    } | {
      type: "incoming"
      jql?: string
    } | {
      type: "manual"
    }
    conditions: {
      type: "jql"
      jql: string
    } | {
      type: "fieldChanged"
      field: string
    } | {
      type: "notActor"
      actor: "assignee" | "reporter" | "automation"
    }[]
    actions: {
      type: "transition"
      transition: string
    } | {
      type: "assign"
      to: "user" | "actor" | "reporter" | "lead" | "unassigned"
      userId?: string
    } | {
      type: "setField"
      field: string
      value: unknown
    } | {
      type: "addLabels"
      labels: string[]
    } | {
      type: "removeLabels"
      labels: string[]
    } | {
      type: "comment"
      body: string
      visibility?: "public" | "internal"
    } | {
      type: "createIssue"
      summary: string
      issueType?: string
      space?: string
      subtask?: boolean
      description?: string
    } | {
      type: "link"
      linkType: string
      issue: string
    } | {
      type: "addWatcher"
      who: "user" | "actor" | "assignee" | "reporter"
      userId?: string
    } | {
      type: "webhook"
      url: string
    } | {
      type: "email"
      to: ("assignee" | "reporter" | "watchers")[]
      subject: string
      body: string
    }[]
    ownerId?: string
    hasToken: boolean
    version: number
    updatedAt: number
  }
}

`GET /v1/orgs/:orgId/issues/automation/:ruleId`

A rule.

Auth: user access token or platform agent key · Scope: issues:read

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:ruleId`	Rule id: a storage lifecycle rule (as returned by the settings or lifecycle routes) or an issue automation rule (`rul_…`).

Response 200

{
  rule: {
    editable: boolean
    ruleId: string
    name: string
    description: string
    enabled: boolean
    spaceIds: string[]
    trigger: {
      type: "issueCreated"
    } | {
      type: "issueTransitioned"
      from?: string[]
      to?: string[]
    } | {
      type: "issueUpdated"
      fields?: string[]
    } | {
      type: "issueAssigned"
    } | {
      type: "commentAdded"
      visibility?: "any" | "public" | "internal"
      by?: "agent" | "reporter" | "anyone"
    } | {
      type: "slaBreached"
      slaIds?: string[]
    } | {
      type: "scheduled"
      interval: "hourly" | "daily" | "weekly"
      hour?: number
      weekday?: number
      jql?: string
    } | {
      type: "incoming"
      jql?: string
    } | {
      type: "manual"
    }
    conditions: {
      type: "jql"
      jql: string
    } | {
      type: "fieldChanged"
      field: string
    } | {
      type: "notActor"
      actor: "assignee" | "reporter" | "automation"
    }[]
    actions: {
      type: "transition"
      transition: string
    } | {
      type: "assign"
      to: "user" | "actor" | "reporter" | "lead" | "unassigned"
      userId?: string
    } | {
      type: "setField"
      field: string
      value: unknown
    } | {
      type: "addLabels"
      labels: string[]
    } | {
      type: "removeLabels"
      labels: string[]
    } | {
      type: "comment"
      body: string
      visibility?: "public" | "internal"
    } | {
      type: "createIssue"
      summary: string
      issueType?: string
      space?: string
      subtask?: boolean
      description?: string
    } | {
      type: "link"
      linkType: string
      issue: string
    } | {
      type: "addWatcher"
      who: "user" | "actor" | "assignee" | "reporter"
      userId?: string
    } | {
      type: "webhook"
      url: string
    } | {
      type: "email"
      to: ("assignee" | "reporter" | "watchers")[]
      subject: string
      body: string
    }[]
    ownerId?: string
    hasToken: boolean
    version: number
    updatedAt: number
  }
}

`PATCH /v1/orgs/:orgId/issues/automation/:ruleId`

Changes a rule; pass baseVersion to avoid overwriting newer edits.

Auth: user access token or platform agent key · Scope: issues:write

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:ruleId`	Rule id: a storage lifecycle rule (as returned by the settings or lifecycle routes) or an issue automation rule (`rul_…`).

Request body

Field	Type	Required	Notes
`name`	`string`	No	1–100 characters; trimmed
`description`	`string`	No	up to 1,000 characters
`enabled`	`boolean`	No
`spaceIds`	`string[]`	No	up to 50 items; each up to 64 characters
`trigger`	`object \| object \| object \| object \| object \| object \| object \| object \| object`	No
`conditions`	`(object \| object \| object)[]`	No	up to 10 items
`actions`	`(object \| object \| object \| object \| object \| object \| object \| object \| object \| object \| object)[]`	No	1–20 items
`baseVersion`	`integer`	No	≥ 0

Response 200

{
  rule: {
    editable: boolean
    ruleId: string
    name: string
    description: string
    enabled: boolean
    spaceIds: string[]
    trigger: {
      type: "issueCreated"
    } | {
      type: "issueTransitioned"
      from?: string[]
      to?: string[]
    } | {
      type: "issueUpdated"
      fields?: string[]
    } | {
      type: "issueAssigned"
    } | {
      type: "commentAdded"
      visibility?: "any" | "public" | "internal"
      by?: "agent" | "reporter" | "anyone"
    } | {
      type: "slaBreached"
      slaIds?: string[]
    } | {
      type: "scheduled"
      interval: "hourly" | "daily" | "weekly"
      hour?: number
      weekday?: number
      jql?: string
    } | {
      type: "incoming"
      jql?: string
    } | {
      type: "manual"
    }
    conditions: {
      type: "jql"
      jql: string
    } | {
      type: "fieldChanged"
      field: string
    } | {
      type: "notActor"
      actor: "assignee" | "reporter" | "automation"
    }[]
    actions: {
      type: "transition"
      transition: string
    } | {
      type: "assign"
      to: "user" | "actor" | "reporter" | "lead" | "unassigned"
      userId?: string
    } | {
      type: "setField"
      field: string
      value: unknown
    } | {
      type: "addLabels"
      labels: string[]
    } | {
      type: "removeLabels"
      labels: string[]
    } | {
      type: "comment"
      body: string
      visibility?: "public" | "internal"
    } | {
      type: "createIssue"
      summary: string
      issueType?: string
      space?: string
      subtask?: boolean
      description?: string
    } | {
      type: "link"
      linkType: string
      issue: string
    } | {
      type: "addWatcher"
      who: "user" | "actor" | "assignee" | "reporter"
      userId?: string
    } | {
      type: "webhook"
      url: string
    } | {
      type: "email"
      to: ("assignee" | "reporter" | "watchers")[]
      subject: string
      body: string
    }[]
    ownerId?: string
    hasToken: boolean
    version: number
    updatedAt: number
  }
}

`DELETE /v1/orgs/:orgId/issues/automation/:ruleId`

Deletes a rule.

Auth: user access token or platform agent key · Scope: issues:write

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:ruleId`	Rule id: a storage lifecycle rule (as returned by the settings or lifecycle routes) or an issue automation rule (`rul_…`).

Response 200

{
  ruleId: string
}

`GET /v1/orgs/:orgId/issues/automation/:ruleId/runs`

The last 50 runs of a rule.

Auth: user access token or platform agent key · Scope: issues:read

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:ruleId`	Rule id: a storage lifecycle rule (as returned by the settings or lifecycle routes) or an issue automation rule (`rul_…`).

Response 200

{
  runs: {
    runId: string
    status: string
    trigger: string
    issueIds: string[]
    log: {
      issue?: string
      action?: string
      ok: boolean
      message: string
    }[]
    ms?: number
    at: number
  }[]
}

`POST /v1/orgs/:orgId/issues/automation/:ruleId/run`

Runs a manual rule on issues now.

Auth: user access token or platform agent key · Scope: issues:write

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:ruleId`	Rule id: a storage lifecycle rule (as returned by the settings or lifecycle routes) or an issue automation rule (`rul_…`).

Request body

Field	Type	Required	Notes
`issues`	`string[]`	Yes	1–100 items; each up to 64 characters

Response 200

{
  status: string
  matched: number
  log: {
    issue?: string
    action?: string
    ok: boolean
    message: string
  }[]
}

`POST /v1/orgs/:orgId/issues/automation/:ruleId/token`

Issues a new token for an incoming-webhook rule and returns its URL (shown once; the old one stops working).

Auth: user access token or platform agent key · Scope: issues:write

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:ruleId`	Rule id: a storage lifecycle rule (as returned by the settings or lifecycle routes) or an issue automation rule (`rul_…`).

Response 200

{
  token: string
  path: string
  url: string
}

`GET /v1/orgs/:orgId/issues/webhooks`

Webhooks of the organization, with the events they can subscribe to.

Auth: user access token or platform agent key · Scope: issues:admin

Path parameter	Description
`:orgId`	Organization id (`org_…`).

Response 200

{
  webhooks: {
    webhookId: string
    name: string
    url: string
    events: ("issue.created" | "issue.updated" | "issue.transitioned" | "issue.deleted" | "issue.moved" | "issue.sla_breached" | "issue.ranked" | "issue.watchers" | "issue.votes" | "comment.created" | "comment.updated" | "comment.deleted" | "worklog.created" | "attachment.created" | "link.created" | "link.deleted" | "sprint.started" | "sprint.completed" | "version.released" | "space.deleted")[]
    spaceIds: string[]
    jql: string
    enabled: boolean
    secretHint: string
    createdBy?: string
    version: number
    updatedAt: number
  }[]
  events: ("issue.created" | "issue.updated" | "issue.transitioned" | "issue.deleted" | "issue.moved" | "issue.sla_breached" | "issue.ranked" | "issue.watchers" | "issue.votes" | "comment.created" | "comment.updated" | "comment.deleted" | "worklog.created" | "attachment.created" | "link.created" | "link.deleted" | "sprint.started" | "sprint.completed" | "version.released" | "space.deleted")[]
}

`POST /v1/orgs/:orgId/issues/webhooks`

Creates a webhook; the signing secret is in the response this once.

Auth: user access token or platform agent key · Scope: issues:admin

Path parameter	Description
`:orgId`	Organization id (`org_…`).

Request body

Field	Type	Required	Notes
`spaceIds`	`string[]`	No	up to 50 items; each up to 64 characters
`jql`	`string`	No	up to 10,000 characters
`enabled`	`boolean`	No
`name`	`string`	Yes	1–100 characters; trimmed
`url`	`string`	Yes	up to 2,000 characters
`events`	`("issue.created" \| "issue.updated" \| "issue.transitioned" \| "issue.deleted" \| "issue.moved" \| "issue.sla_breached" \| "comment.created" \| "comment.updated" \| "comment.deleted" \| "worklog.created" \| "attachment.created" \| "link.created" \| "link.deleted" \| "sprint.started" \| "sprint.completed" \| "version.released")[]`	Yes	1–30 items

Response 201

{
  webhook: {
    webhookId: string
    name: string
    url: string
    events: ("issue.created" | "issue.updated" | "issue.transitioned" | "issue.deleted" | "issue.moved" | "issue.sla_breached" | "issue.ranked" | "issue.watchers" | "issue.votes" | "comment.created" | "comment.updated" | "comment.deleted" | "worklog.created" | "attachment.created" | "link.created" | "link.deleted" | "sprint.started" | "sprint.completed" | "version.released" | "space.deleted")[]
    spaceIds: string[]
    jql: string
    enabled: boolean
    secretHint: string
    createdBy?: string
    version: number
    updatedAt: number
  }
  secret: string
}

`GET /v1/orgs/:orgId/issues/webhooks/:webhookId`

A webhook.

Auth: user access token or platform agent key · Scope: issues:admin

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:webhookId`	Webhook id (`whk_…`).

Response 200

{
  webhook: {
    webhookId: string
    name: string
    url: string
    events: ("issue.created" | "issue.updated" | "issue.transitioned" | "issue.deleted" | "issue.moved" | "issue.sla_breached" | "issue.ranked" | "issue.watchers" | "issue.votes" | "comment.created" | "comment.updated" | "comment.deleted" | "worklog.created" | "attachment.created" | "link.created" | "link.deleted" | "sprint.started" | "sprint.completed" | "version.released" | "space.deleted")[]
    spaceIds: string[]
    jql: string
    enabled: boolean
    secretHint: string
    createdBy?: string
    version: number
    updatedAt: number
  }
}

`PATCH /v1/orgs/:orgId/issues/webhooks/:webhookId`

Changes a webhook.

Auth: user access token or platform agent key · Scope: issues:admin

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:webhookId`	Webhook id (`whk_…`).

Request body

Field	Type	Required	Notes
`name`	`string`	No	1–100 characters; trimmed
`url`	`string`	No	up to 2,000 characters
`events`	`("issue.created" \| "issue.updated" \| "issue.transitioned" \| "issue.deleted" \| "issue.moved" \| "issue.sla_breached" \| "comment.created" \| "comment.updated" \| "comment.deleted" \| "worklog.created" \| "attachment.created" \| "link.created" \| "link.deleted" \| "sprint.started" \| "sprint.completed" \| "version.released")[]`	No	1–30 items
`spaceIds`	`string[]`	No	up to 50 items; each up to 64 characters
`jql`	`string`	No	up to 10,000 characters
`enabled`	`boolean`	No

Response 200

{
  webhook: {
    webhookId: string
    name: string
    url: string
    events: ("issue.created" | "issue.updated" | "issue.transitioned" | "issue.deleted" | "issue.moved" | "issue.sla_breached" | "issue.ranked" | "issue.watchers" | "issue.votes" | "comment.created" | "comment.updated" | "comment.deleted" | "worklog.created" | "attachment.created" | "link.created" | "link.deleted" | "sprint.started" | "sprint.completed" | "version.released" | "space.deleted")[]
    spaceIds: string[]
    jql: string
    enabled: boolean
    secretHint: string
    createdBy?: string
    version: number
    updatedAt: number
  }
}

`DELETE /v1/orgs/:orgId/issues/webhooks/:webhookId`

Deletes a webhook.

Auth: user access token or platform agent key · Scope: issues:admin

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:webhookId`	Webhook id (`whk_…`).

Response 200

{
  webhookId: string
}

`POST /v1/orgs/:orgId/issues/webhooks/:webhookId/secret`

Replaces the signing secret (returned this once).

Auth: user access token or platform agent key · Scope: issues:admin

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:webhookId`	Webhook id (`whk_…`).

Response 200

{
  webhook: {
    webhookId: string
    name: string
    url: string
    events: ("issue.created" | "issue.updated" | "issue.transitioned" | "issue.deleted" | "issue.moved" | "issue.sla_breached" | "issue.ranked" | "issue.watchers" | "issue.votes" | "comment.created" | "comment.updated" | "comment.deleted" | "worklog.created" | "attachment.created" | "link.created" | "link.deleted" | "sprint.started" | "sprint.completed" | "version.released" | "space.deleted")[]
    spaceIds: string[]
    jql: string
    enabled: boolean
    secretHint: string
    createdBy?: string
    version: number
    updatedAt: number
  }
  secret: string
}

`POST /v1/orgs/:orgId/issues/webhooks/:webhookId/ping`

Sends a ping event now and returns the outcome.

Auth: user access token or platform agent key · Scope: issues:admin

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:webhookId`	Webhook id (`whk_…`).

Response 200

{
  ok: boolean
  status?: number
  error?: string
  attempts: number
  ms: number
}

`GET /v1/orgs/:orgId/issues/webhooks/:webhookId/deliveries`

The last 50 deliveries.

Auth: user access token or platform agent key · Scope: issues:admin

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:webhookId`	Webhook id (`whk_…`).

Response 200

{
  deliveries: {
    deliveryId: string
    event: string
    status?: number
    ok: boolean
    error?: string
    attempts: number
    ms?: number
    at: number
  }[]
}

Issue automation and webhooks

On this page