API reference
Issue filters
Saved queries with sharing, stars and email subscriptions.
See Issues.
GET /v1/orgs/:orgId/issues/filters
Filters the caller owns or that are shared with them, starred first.
Auth: user access token or platform agent key · Scope: issues:read
| Path parameter | Description |
|---|---|
:orgId | Organization id (org_…). |
Response 200
{
filters: {
filterId: string
name: string
description: string
jql: string
ownerId?: string
sharing: {
org: boolean
teams: string[]
users: string[]
}
columns?: string[]
subscriptions: {
userId: string
frequency: "daily" | "weekly"
hour: number
weekday?: number
lastSentAt?: number
}[]
starred: boolean
editable: boolean
version: number
updatedAt: number
}[]
}POST /v1/orgs/:orgId/issues/filters
Saves a query as a filter (private until shared).
Auth: user access token or platform agent key · Scope: issues:read
| Path parameter | Description |
|---|---|
:orgId | Organization id (org_…). |
Request body
| Field | Type | Required | Notes |
|---|---|---|---|
description | string | No | up to 1,000 characters |
sharing | object | No | |
sharing.org | boolean | Yes | |
sharing.teams | string[] | Yes | up to 50 items; each up to 64 characters |
sharing.users | string[] | Yes | up to 200 items; each up to 64 characters |
columns | string[] | No | up to 30 items; each up to 64 characters |
name | string | Yes | 1–100 characters; trimmed |
jql | string | Yes | up to 10,000 characters |
Response 201
{
filter: {
filterId: string
name: string
description: string
jql: string
ownerId?: string
sharing: {
org: boolean
teams: string[]
users: string[]
}
columns?: string[]
subscriptions: {
userId: string
frequency: "daily" | "weekly"
hour: number
weekday?: number
lastSentAt?: number
}[]
starred: boolean
editable: boolean
version: number
updatedAt: number
}
}GET /v1/orgs/:orgId/issues/filters/:filterId
A filter the caller can see.
Auth: user access token or platform agent key · Scope: issues:read
| Path parameter | Description |
|---|---|
:orgId | Organization id (org_…). |
:filterId | Filter id: a mail filter (flt_…) or a saved issue filter (ifl_…). |
Response 200
{
filter: {
filterId: string
name: string
description: string
jql: string
ownerId?: string
sharing: {
org: boolean
teams: string[]
users: string[]
}
columns?: string[]
subscriptions: {
userId: string
frequency: "daily" | "weekly"
hour: number
weekday?: number
lastSentAt?: number
}[]
starred: boolean
editable: boolean
version: number
updatedAt: number
}
}PATCH /v1/orgs/:orgId/issues/filters/:filterId
Changes a filter (its owner, or org admins).
Auth: user access token or platform agent key · Scope: issues:read
| Path parameter | Description |
|---|---|
:orgId | Organization id (org_…). |
:filterId | Filter id: a mail filter (flt_…) or a saved issue filter (ifl_…). |
Request body
| Field | Type | Required | Notes |
|---|---|---|---|
name | string | No | 1–100 characters; trimmed |
description | string | No | up to 1,000 characters |
jql | string | No | up to 10,000 characters |
sharing | object | No | |
sharing.org | boolean | Yes | |
sharing.teams | string[] | Yes | up to 50 items; each up to 64 characters |
sharing.users | string[] | Yes | up to 200 items; each up to 64 characters |
columns | string[] | No | up to 30 items; each up to 64 characters |
Response 200
{
filter: {
filterId: string
name: string
description: string
jql: string
ownerId?: string
sharing: {
org: boolean
teams: string[]
users: string[]
}
columns?: string[]
subscriptions: {
userId: string
frequency: "daily" | "weekly"
hour: number
weekday?: number
lastSentAt?: number
}[]
starred: boolean
editable: boolean
version: number
updatedAt: number
}
}DELETE /v1/orgs/:orgId/issues/filters/:filterId
Deletes a filter and its subscriptions (its owner, or org admins).
Auth: user access token or platform agent key · Scope: issues:read
| Path parameter | Description |
|---|---|
:orgId | Organization id (org_…). |
:filterId | Filter id: a mail filter (flt_…) or a saved issue filter (ifl_…). |
Response 200
{
filterId: string
}POST /v1/orgs/:orgId/issues/filters/:filterId/star
Stars or unstars a filter for the caller.
Auth: user access token or platform agent key · Scope: issues:read
| Path parameter | Description |
|---|---|
:orgId | Organization id (org_…). |
:filterId | Filter id: a mail filter (flt_…) or a saved issue filter (ifl_…). |
Request body
| Field | Type | Required | Notes |
|---|---|---|---|
starred | boolean | Yes |
Response 200
{
filter: {
filterId: string
name: string
description: string
jql: string
ownerId?: string
sharing: {
org: boolean
teams: string[]
users: string[]
}
columns?: string[]
subscriptions: {
userId: string
frequency: "daily" | "weekly"
hour: number
weekday?: number
lastSentAt?: number
}[]
starred: boolean
editable: boolean
version: number
updatedAt: number
}
}PUT /v1/orgs/:orgId/issues/filters/:filterId/subscription
Emails the caller the filter's issues daily or weekly at an hour (UTC); subscription: null stops it.
Auth: user access token or platform agent key · Scope: issues:read
| Path parameter | Description |
|---|---|
:orgId | Organization id (org_…). |
:filterId | Filter id: a mail filter (flt_…) or a saved issue filter (ifl_…). |
Request body
| Field | Type | Required | Notes |
|---|---|---|---|
subscription | object | Yes | can be null |
subscription.frequency | "daily" | "weekly" | Yes | |
subscription.hour | integer | Yes | 0–23 |
subscription.weekday | integer | No | 0–6 |
Response 200
{
filter: {
filterId: string
name: string
description: string
jql: string
ownerId?: string
sharing: {
org: boolean
teams: string[]
users: string[]
}
columns?: string[]
subscriptions: {
userId: string
frequency: "daily" | "weekly"
hour: number
weekday?: number
lastSentAt?: number
}[]
starred: boolean
editable: boolean
version: number
updatedAt: number
}
}