API query methods

The base URL for all API calls is:

if you are in the EU region:
https://eu.okr-jira-prod.appfire.com

everywhere else:
https://okr-jira-prod.appfire.com

Query objectives by date

The query for a list of all objectives, which have a start date or/and due date inside the specified date range.

GET /api/v2/api-export/objectives/byDate

Parameter	Description	Mandatory

Parameter	Description	Mandatory
`startDateEpochMilli`	Start date of query time window, in UNIX Epoch time format, in milliseconds.
`deadlineEpochMilli`	End date of query time window, in UNIX Epoch time format, in milliseconds.
`expand`	A list of objects you want to include expanded in reqeust. By default you receive only ids of connected entities. Permitted values: KEY_RESULTS,TEAMS,PERIODS,LABELS

Example request:

GET https://okr-jira-prod.appfire.com/api/v2/api-export/objectives/byDate?
startDateEpochMilli=1409459200000
&deadlineEpochMilli=1748647410000
&expand=KEY_RESULTS,TEAMS,PERIODS,LABELS

curl --request GET \
  --url 'https://okr-jira-prod.appfire.com/api/v2/api-export/objectives/byDate?startDateEpochMilli=1600647410000&deadlineEpochMilli=1748647410000&expand=KEY_RESULTS,TEAMS,PERIODS,LABELS' \
  --header 'API-Token: {token}' \
  --header 'Content-Type: application/json'

{
	"okrs": [
		{
			"id": "5fda249d289742000406b3e4",
			"key": "O-2",
			"name": "Become more mature company",
			"link": "https://test-okr-prd.atlassian.net/plugins/servlet/ac/com.digitaltoucan.okrforjira/okrs-general-page#!eyJ0eXBlIjoiT0JKRUNUSVZFIiwib2tySWQiOiI1ZmVhZTJmZGNjYTIyMTAwMDMxNWFiMWYifQ%3D%3D",
			"description": "<p>This quarter we will be focusing on improving our performance.</p><p></p>",
			"parentObjectiveId": null,
			"ownerAccountId": "5c12ad9fd3af3b1ccfecbf55",
			"collaboratorAccountIds": [],
			"percentDone": 8.333333333333332,
			"created": "2020-12-16T15:15:41+0000",
			"startDate": "2021-01-01T00:00:00+0000",
			"deadline": "2021-03-31T23:59:59+0000",
			"labelIds": [],
			"teamIds": [],
			"krIds": [
				"605480b190c42b0003385170",
				"6061e921e2f4470003bc3210"
			],
			"childObjectiveIds": [
				"5fdb72c63d2cf000035ceb37",
				"60743135b347480003dc6a9c",
				"61f9367df9aa7f0e4024a6fe"
			],
			"latestUpdate": {
				"entityId": "5fda249d289742000406b3e4",
				"status": "ON_TRACK",
				"created": "2021-05-05T12:15:14+0000",
				"value": null,
				"description": ""
			},
			"periodAliasId": "602a6a2717378700039f342a",
			"weight": 0
		}
	],
	"krs": [
		{
			"id": "605480b190c42b0003385170",
			"key": "KR-8",
			"name": "new auto KR",
			"link": "https://test-okr-prd.atlassian.net/plugins/servlet/ac/com.digitaltoucan.okrforjira/okrs-general-page#!eyJ0eXBlIjoiS1IiLCJrcklkIjoiNjExYTFhMjljMzg1Zjg1YzEzYWM4NjI0In0%3D",
			"description": null,
			"parentObjectiveId": "5fda249d289742000406b3e4",
			"issueIds": [
				"10005",
				"10006",
				"10010"
			],
			"ownerAccountId": "5dbfee8570f1ea0df7698353",
			"collaboratorAccountIds": [
				"5c12ad9fd3af3b1ccfecbf55"
			],
			"percentDone": 33.33333333333333,
			"created": "2021-03-19T10:45:05+0000",
			"startDate": "2021-01-01T00:00:00+0000",
			"deadline": "2021-03-31T23:59:59+0000",
			"labelIds": [],
			"teamIds": [],
			"periodAliasId": "602a6a2717378700039f342a",
			"latestUpdate": {
				"entityId": "620ea538512edb00acf67ac1",
				"status": "ON_TRACK",
				"created": "2022-02-17T19:42:43+0000",
				"value": 1.0,
				"description": null
			},
			"unit": null,
			"currentProgressDefinition": {
				"type": "AUTO",
				"startValue": null,
				"desiredValue": null,
				"jql": "project= TEST"
			},
			"weight": 1
		},
		{
			"id": "6061e921e2f4470003bc3210",
			"key": "KR-9",
			"name": "different start date",
			"link": "https://test-okr-prd.atlassian.net/plugins/servlet/ac/com.digitaltoucan.okrforjira/okrs-general-page#!eyJ0eXBlIjoiS1IiLCJrcklkIjoiNjExYTFhMjljMzg1Zjg1YzEzYWM4NjI0In0%3D",
			"description": null,
			"parentObjectiveId": "5fda249d289742000406b3e4",
			"issueIds": [
				"10000"
			],
			"ownerAccountId": "5dbfee8570f1ea0df7698353",
			"collaboratorAccountIds": [],
			"percentDone": 0.0,
			"created": "2021-03-29T14:50:09+0000",
			"startDate": "2020-04-01T00:00:00+0000",
			"deadline": "2020-06-30T23:59:59+0000",
			"labelIds": [],
			"teamIds": [],
			"periodAliasId": null,
			"latestUpdate": {
				"entityId": "61138f2be5fd454858c3e1ee",
				"status": "AT_RISK",
				"created": "2021-08-11T08:49:47+0000",
				"value": 0.0,
				"description": null
			},
			"unit": {
				"name": "USD",
				"symbol": "$"
			},
			"currentProgressDefinition": {
				"type": "STANDARD",
				"startValue": 0.0,
				"desiredValue": 1.0,
				"jql": null
			},
			"weight": 1
		}
	],
	"teams": [],
	"periods": [
		{
			"id": "602a6a2717378700039f342a",
			"name": "Q1 Y2021",
			"startDate": "2021-01-01T00:00:00+0000",
			"deadline": "2021-03-31T23:59:59+0000"
		}
	],
	"labels": []
}

Query objectives by id

The query for a list of all objectives with specified ids.

GET /api/v2/api-export/objectives/byIds

Parameter	Description	Mandatory

Parameter	Description	Mandatory
`objectiveIds`	Comma separated list of objective ids you want to receive.
`expand`	A list of objects you want to include expanded in reqeust. By default you receive only ids of connected entities. Permitted values: KEY_RESULTS,TEAMS,PERIODS,LABELS

Example request:

GET https://okr-jira-prod.appfire.com/api/v2/api-export/objectives/byIds?objectiveIds=5fda249d289742000406b3e4
&expand=OBJECTIVES,KEY_RESULTS,TEAMS,PERIODS,LABELS

curl --request GET \
  --url 'https://okr-jira-prod.appfire.com/api/v2/api-export/objectives/byIds?expand=OBJECTIVES,KEY_RESULTS,TEAMS,PERIODS,LABELS&objectiveIds=5fda249d289742000406b3e4,5fdb72c63d2cf000035ceb37' \
  --header 'API-Token: {token}' \
  --header 'Content-Type: application/json'

Query key results by date

The query for a list of all key results, which have a start date or/and due date inside the specified date range.

GET /api/v2/api-export/keyResults/byDate

Parameter	Description	Mandatory

Parameter	Description	Mandatory
`startDateEpochMilli`	Start date of query time window, in UNIX Epoch time format, in milliseconds.
`deadlineEpochMilli`	End date of query time window, in UNIX Epoch time format, in milliseconds.
`expand`	A list of objects you want to include expanded in reqeust. By default you receive only ids of connected entities. Permitted values: OBJECTIVES,TEAMS,PERIODS,LABELS

Example request:

GET https://okr-jira-prod.appfire.com/api/v2/api-export/keyResults/byDate?
startDateEpochMilli=1509459200000
&deadlineEpochMilli=1748647410000
&expand=OBJECTIVES,KEY_RESULTS,TEAMS,PERIODS,LABELS

Query key results by id

Query for a list of all key results with specified ids.

GET /api/v2/api-export/keyResults/byIds

Parameter	Description	Mandatory

Parameter	Description	Mandatory
`keyResultIds`	Comma separated list of key result ids you want to receive.
`expand`	A list of objects you want to include expanded in reqeust. By default you receive only ids of connected entities. Permitted values: KEY_RESULTS,TEAMS,PERIODS,LABELS

Example request:

GET https://okr-jira-prod.appfire.com/api/v2/api-export/keyResults/byIds?
expand=OBJECTIVES,KEY_RESULTS,TEAMS,PERIODS,LABELS
&keyResultIds=5fda249d289742000406b3e5

Query updates by entity id

Query for updates for objective or key result, newest first.

NOTE ON PROGRESS:
Updates are not the best way to calculate progress.
Use percentDone field on Objectives and Key Results to get latest progress value.

Updates for non-auto Key Results have startValue, value, and desiredValue fields.
They allow tracking changes in progress of a Key Result. Latest Update for Key Result will have up-to-date value.
As of auto KR updates, there are two kinds of them.
Automatic updates are generated when connected issues change status, and such updates have progress values. You also can create manual update with description, but progress values are not editable and will not be present on Update object fetched through API.

Objective progress can not be traced by its updates. Objective Updates will always have their progress as null. We calculate progress of an objective in-flight, and do not generate an Update for every change in Objectives underlying Key Results.

GET /api/v2/api-export/updates

Parameter	Description	Mandatory

Parameter	Description	Mandatory
`entityId`	Id of a single objective or key result to return updates for. If no id provided, updates for all key results and objectives will be returned, newest first.
`earlierThan`	Only updates earlier than date provided would be returned. Should be provided in UNIX Epoch time format, in milliseconds.
`cursor`	This endopint supports cursor-based pagination. Request returns up to `pageSize` records. If there are more updates, than fit in current page, `nextCursor` field would be populated in response object. You can get next page of updates by using value of `nextCursor` as `cursor` parameter in next request. Lack of `nextCursor` means there are no more updates to return.
`pageSize`	Controls how many updates the request will return in single response. If there are more updates than returned, `nextCursor` field of response object will be populated. Takes values from 1 to 1000. Default value is 1000.

Example request:

GET https://okr-jira-prod.appfire.com/api/v2/api-export/updates?entityId=5fda249d289742000406b3e5&pageSize=100&cursor=MTY0MDYwMDQ5MDI5MA==

Query comments

Query paged comments (all or for given updateIds).

GET /api/v2/api-export/updateComments

Parameter	Description	Mandatory

Parameter	Description	Mandatory
`updateId`	Ids of updates to retrieve comments. If no ids provided, comments for all updates will be returned, newest first.
`cursor`	This endopint supports cursor-based pagination. Request returns up to `pageSize` records. If there are more updates, than fit in current page, `nextCursor` field would be populated in response object. You can get next page of comments by using value of `nextCursor` as `cursor` parameter in next request. Lack of `nextCursor` means there are no more comments to return.
`pageSize`	Controls how many comments the request will return in single response. If there are more comments than returned, `nextCursor` field of response object will be populated. Takes values from 1 to 1000. Default value is 1000.

Example request:

GET https://okr-jira-prod.appfire.com/api/v2/api-export/updateComments?updateId=6453c760a3b1a006776f1c7f&pageSize=1&cursor=MTY4MzIxMjE0MTA1OQ==

OKRs for Jira

This site is moving soon to become part of an integrated Appfire documentation and information site for our apps. This site will remain available during the transition to our new and improved site. Once this site is moved over, this banner will be updated with the new site link for easy access.

API query methods

Query objectives by date

Query objectives by id

Query key results by date

Query key results by id

Query updates by entity id

Query comments

Related pages