/
REST API - Jira Cloud (Forge)

REST API - Jira Cloud (Forge)

This page is a work in progress.

When replacing parameters indicated by <PARAMETER_NAME>, be sure to remove the ‘<' '>’ characters as well.

For example:

  • <active_only> replaced by true or false

Authorization

Our application exposes a few custom REST endpoints to enable custom integration in various tools. The official technical Atlassian documentation can be accessed here: https://developer.atlassian.com/platform/forge/access-rest-apis-exposed-by-a-forge-app/

  1. Enable Rest API in Connected Apps > Capacity Tracker

  2. Go to https://developer.atlassian.com/console/myapps/

  3. Create new “OAuth 2.0 integration” app

    image-20260307-213838.png

     

    1. In Permission tab

      1. Click “Add Marketplace app”

        1. Select your Jira instance

        2. Select Capacity Tracker

        3. Select which scopes you would like this API integration to get

      2. Next to Jira API, click “Add”

        1. Configure following granular scopes:

          1. read:forge-app:jira

    2. In Authorization tab

      1. Click “Configure”

      2. Under callback URL, put the URL of the webserver you will use to receive your authorization code. If you don’t have one, you can simply put the URL of your Jira instance.

      3. Copy the link under Marketplace App: Capacity Tracker

    3. In Settings tab

      1. Take a note of your Client ID and Secret, you will need them later.

  4. Now that we have a custom OAuth2 app and the authorization URL, it’s time to generate a one-time authorization code.
    We will need to manually adjust the URL to make it work with automated integrations.
    Your URL should look like this:

https://auth.atlassian.com/authorize?[something]scope=<customscopes>%20read:forge-app:jira%20offline_access[something]

  1. Open this link in your browser and follow the instructions to approve request access

    1. After consent, you'll be redirected to the callback URL with a code query parameter. Copy this authorization code.

  2. Follow this documentation to generate a Refresh token and Access token from authorization code.

    1. Save those refresh & access tokens

  3. You can now call the different API endpoints with your Access token (replace <MY_ACCESS_TOKEN> with the previously created token).

    curl -H "Authorization: Bearer <MY_ACCESS_TOKEN>" -H "Content-Type: application/json" https://<jira-cloud-instance>.atlassian.net/gateway/api/svc/jira/apps/00d8b211-ac90-4861-8796-a70e68ae5990_1840e131-0b89-4f2e-ae8f-b10998df9543/<endpoint>

  4. Your access token is only valid for a short amount of time. Once expired, you need to generate a new access token based on the previously generated refresh token (https://developer.atlassian.com/cloud/confluence/oauth-2-3lo-apps/#use-a-refresh-token-to-get-another-access-token-and-refresh-token-pair )

    1. This will give you a new pair of refresh token and access token.

Endpoints

Get capacity report

Returns the capacity report for a specific work period. In case none were specified, the most recent active one will be used.

Method

Endpoint

Method

Endpoint

GET

/capacityReport/board/<board_id>/report?workPeriodId=<my_work_period_id>

Parameter

Type

Required

Default Value

Description

Parameter

Type

Required

Default Value

Description

<board_id>

Number

Yes

 

ID of your Jira Board (or RapidView).

<my_work_period_id>

Number

No

0

ID of your sprint or version.

Get consolidated capacity report

Returns the consolidated capacity report including all work periods.

Method

Endpoint

Method

Endpoint

GET

/capacityReport/board/<board_id>/reportConsolidated?activeOnly=<active_only>

Parameter

Type

Required

Default Value

Description

Parameter

Type

Required

Default Value

Description

<board_id>

Number

Yes

 

ID of your Jira Board (or RapidView).

<active_only>

Boolean

No

false

Only return active work periods (i.e. future work periods will not be included in the results).

Get consolidated capacity report (flat)

Returns the consolidated capacity report including all work periods in a flat schema (the report will be returned as a list of records with all necessary columns instead of a nested JSON object).

This call is mostly used to integrate with Excel/PowerBI.

Method

Endpoint

Method

Endpoint

GET

/capacityReport/board/<board_id>/reportConsolidatedFlat?activeOnly=<active_only>&includeUnassigned=<include_unassigned>&filterDaysOff=<filter_days_off>

Parameter

Type

Required

Default Value

Description

Parameter

Type

Required

Default Value

Description

<board_id>

Number

Yes

 

ID of your Jira Board (or RapidView).

<active_only>

Boolean

No

false

Only return active work periods (i.e. future work periods will not be included in the results).

<include_unassigned>

Boolean

No

false

Include unassigned issues in your capacity report.

<filter_days_off>

Boolean

No

false

Filter days off based on the work period start/end dates.
By default, all days off are returned even if they are outside the work period date ranges.

Get user days off

Returns the full list of user days off.

Method

Endpoint

Method

Endpoint

GET

/userDaysOff

Update user days off

Updates the user days off directly without using the Capacity Tracker UI.

Method

Endpoint

Request Body

Method

Endpoint

Request Body

PUT

/userDaysOff

Capacity Tracker supports two different kinds of days off:

  • Full day

YYYY-MM-DD

or

YYYY-MM-DD F

  • Half day

YYYY-MM-DD H

 

Two modes are supported:

Set

{     "set": {         "jira_user_account_id_1": [ "2023-06-05",             "2023-06-06 H",             "2023-06-07 H",             "2023-06-08"         ], "jira_user_account_id_2": [ "2023-06-05",             "2023-06-06 H",             "2023-06-07 H",             "2023-06-08"         ]     } }

This mode will completely replace the days off for the given user account IDs (all existing days off will be removed).

Add / remove

{     "remove": {         "jira_user_account_id_1": [             "2023-06-05",             "2023-06-06 H",             "2023-06-07 H",             "2023-06-08"         ] "jira_user_account_id_2": [             "2023-06-05",             "2023-06-06 H",             "2023-06-07 H",             "2023-06-08"         ]     },     "add": {         "jira_user_account_id_1": [             "2023-06-31"         ] "jira_user_account_id_2": [             "2023-06-31"         ]     } }

This mode will always execute the operations in this order: Remove, then Add.

  • Remove

    • The given days off will be removed for the specific account IDs.

    • Removing a full day will also remove a half day.

    • Attempting to remove a half day when a full day was previously stored will be ignored.

  • Add

    • The given days off will be added for the specific account IDs.

    • Note: this behaves like a partial set. For example, if a user has a full day off on 2023-05-01 but you are adding a half day (2023-05-01 H), the full day will be replaced by the half day.

Get list of templates

Returns the list of global templates.

Method

Endpoint

Method

Endpoint

GET

/template

Get template details

Returns the details of a specific global template.

Method

Endpoint

Method

Endpoint

GET

/template/<templateId>

Parameter

Type

Required

Default Value

Description

Parameter

Type

Required

Default Value

Description

<template_id>

String

Yes

 

ID of your global template.