API reference

Issue reports and dashboards

Reports over any query, timesheets, and dashboards of gadgets.

`GET /v1/orgs/:orgId/issues/reports/timesheet`

Work logged between two instants (at most 92 days) by people: users (ids, comma-separated), a team, or the caller.

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

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

Query parameter	Type	Required	Notes
`users`	`string`	No	up to 10,000 characters
`team`	`string`	No	up to 64 characters
`from`	`integer`	Yes	≥ 0; coerced from a string
`to`	`integer`	Yes	≥ 0; coerced from a string

Response 200

{
  worklogs: {
    worklogId: string
    issueId: string
    spaceId: string
    authorId: string
    started: number
    seconds: number
    comment: string
    createdAt: number
    updatedAt: number
  }[]
  issues: {
    issueId: string
    key: string
    summary: string
    spaceId: string
    typeId: string
  }[]
  people: {
    userId: string
    name?: string
    email?: string
  }[]
}

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

Runs a report: createdVsResolved, cumulativeFlow, averageAge and resolutionTime are trends over days in interval buckets; controlChart gives cycle times of resolved issues; statistics and twoDimensional group by groupBy (and groupBy2); timeTracking, workload and epicProgress summarize estimates, assignees and epics.

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

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

Query parameter	Type	Required	Default	Notes
`type`	`"createdVsResolved" \| "cumulativeFlow" \| "controlChart" \| "statistics" \| "twoDimensional" \| "averageAge" \| "resolutionTime" \| "timeTracking" \| "workload" \| "epicProgress"`	Yes
`jql`	`string`	No	`""`	up to 10,000 characters
`days`	`integer`	No		1–730; coerced from a string
`interval`	`"day" \| "week" \| "month"`	No
`cumulative`	`"0" \| "1"`	No
`groupBy`	`string`	No		up to 64 characters
`groupBy2`	`string`	No		up to 64 characters
`from`	`"inprogress" \| "created"`	No
`tzOffset`	`integer`	No		-840–840; coerced from a string

Response 200

{
  type: "createdVsResolved"
  interval: "day" | "month" | "week"
  cumulative: boolean
  rows: {
    at: number
    created: number
    resolved: number
    unresolved: number
  }[]
  jql: string
  total: number
  generatedAt: number
} | {
  type: "cumulativeFlow"
  interval: "day" | "month" | "week"
  statuses: {
    statusId: string
    name: string
    category: "done" | "todo" | "inprogress"
  }[]
  rows: {
    at: number
  }[]
  jql: string
  total: number
  generatedAt: number
} | {
  type: "controlChart"
  from: "created" | "inprogress"
  stats: {
    count: number
    mean: number
    median: number
    min: number
    max: number
    stddev: number
  }
  points: {
    rolling?: number
    issueId: string
    key: string
    summary: string
    typeId: string
    start: number
    end: number
    ms: number
  }[]
  jql: string
  total: number
  generatedAt: number
} | {
  type: "statistics"
  groupBy: string
  rows: {
    percent: number
    label: string
    count: number
    points: number
    key: string
  }[]
  jql: string
  total: number
  generatedAt: number
} | {
  type: "twoDimensional"
  x: string
  y: string
  columns: {
    label: string
    total: number
    key: string
  }[]
  rows: {
    label: string
    total: number
    cells: {
      [key: string]: number
    }
    key: string
  }[]
  jql: string
  total: number
  generatedAt: number
} | {
  type: "averageAge"
  interval: "day" | "month" | "week"
  rows: {
    at: number
    unresolved: number
    days: number
  }[]
  jql: string
  total: number
  generatedAt: number
} | {
  type: "resolutionTime"
  interval: "day" | "month" | "week"
  rows: {
    at: number
    resolved: number
    days: number
  }[]
  jql: string
  total: number
  generatedAt: number
} | {
  type: "timeTracking"
  totals: {
    original: number
    spent: number
    remaining: number
  }
  accuracy: null | number
  rows: {
    issueId: string
    key: string
    summary: string
    statusId: string
    original: number
    spent: number
    remaining: number
  }[]
  jql: string
  total: number
  generatedAt: number
} | {
  type: "workload"
  rows: {
    label: string
    issues: number
    points: number
    remaining: number
    overdue: number
    key: string
  }[]
  jql: string
  total: number
  generatedAt: number
} | {
  type: "epicProgress"
  rows: {
    issueId: string
    key: string
    summary: string
    statusId: string
    dueDate?: string
    total: number
    todo: number
    inprogress: number
    done: number
    points: number
    pointsDone: number
  }[]
  jql: string
  total: number
  generatedAt: number
}

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

Dashboards the caller owns or that are shared with them (default and starred first).

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

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

Response 200

{
  dashboards: {
    gadgetCount: number
    dashboardId: string
    name: string
    description: string
    ownerId?: string
    sharing: {
      org: boolean
      teams: string[]
      users: string[]
    }
    layout: "1" | "2" | "3" | "2-1" | "1-2"
    starred: boolean
    isDefault: boolean
    editable: boolean
    version: number
    updatedAt: number
  }[]
}

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

Creates a dashboard; without gadgets it starts with a useful default set.

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
`layout`	`"1" \| "2" \| "3" \| "2-1" \| "1-2"`	No
`gadgets`	`object[]`	No	up to 30 items
`gadgets[].id`	`string`	No	up to 40 characters
`gadgets[].type`	`"filterResults" \| "assignedToMe" \| "statistics" \| "createdVsResolved" \| "twoDimensional" \| "averageAge" \| "resolutionTime" \| "workload" \| "sprintBurndown" \| "velocity" \| "epicProgress" \| "text"`	Yes
`gadgets[].title`	`string`	No	up to 100 characters
`gadgets[].column`	`integer`	Yes	0–2
`gadgets[].config`	`object`	Yes	values: any JSON
`baseVersion`	`integer`	No	≥ 0
`name`	`string`	Yes	1–100 characters; trimmed

Response 201

{
  dashboard: {
    dashboardId: string
    name: string
    description: string
    ownerId?: string
    sharing: {
      org: boolean
      teams: string[]
      users: string[]
    }
    layout: "1" | "2" | "3" | "2-1" | "1-2"
    gadgets: {
      id: string
      type: "text" | "velocity" | "createdVsResolved" | "statistics" | "twoDimensional" | "averageAge" | "resolutionTime" | "workload" | "epicProgress" | "filterResults" | "assignedToMe" | "sprintBurndown"
      title?: string
      column: number
      config: {
        [key: string]: unknown
      }
    }[]
    starred: boolean
    isDefault: boolean
    editable: boolean
    version: number
    updatedAt: number
  }
}

`PUT /v1/orgs/:orgId/issues/dashboards/default`

Makes a dashboard the caller's default (dashboardId: null clears it).

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

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

Request body

Field	Type	Required	Notes
`dashboardId`	`string`	Yes	up to 64 characters; can be `null`

Response 200

{
  dashboardId: null | string
}

`GET /v1/orgs/:orgId/issues/dashboards/:dashboardId`

A dashboard with its gadgets.

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

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

Response 200

{
  dashboard: {
    dashboardId: string
    name: string
    description: string
    ownerId?: string
    sharing: {
      org: boolean
      teams: string[]
      users: string[]
    }
    layout: "1" | "2" | "3" | "2-1" | "1-2"
    gadgets: {
      id: string
      type: "text" | "velocity" | "createdVsResolved" | "statistics" | "twoDimensional" | "averageAge" | "resolutionTime" | "workload" | "epicProgress" | "filterResults" | "assignedToMe" | "sprintBurndown"
      title?: string
      column: number
      config: {
        [key: string]: unknown
      }
    }[]
    starred: boolean
    isDefault: boolean
    editable: boolean
    version: number
    updatedAt: number
  }
}

`PATCH /v1/orgs/:orgId/issues/dashboards/:dashboardId`

Changes a dashboard (its owner, or org admins); pass baseVersion to avoid overwriting newer edits.

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

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

Request body

Field	Type	Required	Notes
`name`	`string`	No	1–100 characters; trimmed
`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
`layout`	`"1" \| "2" \| "3" \| "2-1" \| "1-2"`	No
`gadgets`	`object[]`	No	up to 30 items
`gadgets[].id`	`string`	No	up to 40 characters
`gadgets[].type`	`"filterResults" \| "assignedToMe" \| "statistics" \| "createdVsResolved" \| "twoDimensional" \| "averageAge" \| "resolutionTime" \| "workload" \| "sprintBurndown" \| "velocity" \| "epicProgress" \| "text"`	Yes
`gadgets[].title`	`string`	No	up to 100 characters
`gadgets[].column`	`integer`	Yes	0–2
`gadgets[].config`	`object`	Yes	values: any JSON
`baseVersion`	`integer`	No	≥ 0

Response 200

{
  dashboard: {
    dashboardId: string
    name: string
    description: string
    ownerId?: string
    sharing: {
      org: boolean
      teams: string[]
      users: string[]
    }
    layout: "1" | "2" | "3" | "2-1" | "1-2"
    gadgets: {
      id: string
      type: "text" | "velocity" | "createdVsResolved" | "statistics" | "twoDimensional" | "averageAge" | "resolutionTime" | "workload" | "epicProgress" | "filterResults" | "assignedToMe" | "sprintBurndown"
      title?: string
      column: number
      config: {
        [key: string]: unknown
      }
    }[]
    starred: boolean
    isDefault: boolean
    editable: boolean
    version: number
    updatedAt: number
  }
}

`POST /v1/orgs/:orgId/issues/dashboards/:dashboardId/copy`

Copies a dashboard into a new private one owned by the caller.

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

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

Request body

Field	Type	Required	Notes
`name`	`string`	No	1–100 characters; trimmed

Response 201

{
  dashboard: {
    dashboardId: string
    name: string
    description: string
    ownerId?: string
    sharing: {
      org: boolean
      teams: string[]
      users: string[]
    }
    layout: "1" | "2" | "3" | "2-1" | "1-2"
    gadgets: {
      id: string
      type: "text" | "velocity" | "createdVsResolved" | "statistics" | "twoDimensional" | "averageAge" | "resolutionTime" | "workload" | "epicProgress" | "filterResults" | "assignedToMe" | "sprintBurndown"
      title?: string
      column: number
      config: {
        [key: string]: unknown
      }
    }[]
    starred: boolean
    isDefault: boolean
    editable: boolean
    version: number
    updatedAt: number
  }
}

`POST /v1/orgs/:orgId/issues/dashboards/:dashboardId/star`

Stars or unstars a dashboard for the caller.

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

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

Request body

Field	Type	Required	Notes
`starred`	`boolean`	Yes

Response 200

{
  dashboard: {
    dashboardId: string
    name: string
    description: string
    ownerId?: string
    sharing: {
      org: boolean
      teams: string[]
      users: string[]
    }
    layout: "1" | "2" | "3" | "2-1" | "1-2"
    gadgets: {
      id: string
      type: "text" | "velocity" | "createdVsResolved" | "statistics" | "twoDimensional" | "averageAge" | "resolutionTime" | "workload" | "epicProgress" | "filterResults" | "assignedToMe" | "sprintBurndown"
      title?: string
      column: number
      config: {
        [key: string]: unknown
      }
    }[]
    starred: boolean
    isDefault: boolean
    editable: boolean
    version: number
    updatedAt: number
  }
}

`DELETE /v1/orgs/:orgId/issues/dashboards/:dashboardId`

Deletes a dashboard (its owner, or org admins).

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

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

Response 200

{
  dashboardId: string
}

Issue reports and dashboards

On this page