Retrieve objectives, key results, updates, and comments. Use **expand** to include related entities (teams, periods, labels, etc.) instead of IDs only. Authenticate with the **API-Token** header. For team identifiers and the **Teams** API, see **Teams** in the API overview.
openapi: 3.2.0
info:
title: OKR API query methods API
description: 'REST API for integrating your OKR data (Objectives and Key Results) with external tools and workflows.
## Region (base URL)
Use the server URL that matches your Jira Cloud data residency. The **Servers** list below includes regional endpoints when configured. If unsure, check Jira admin settings or contact support.
## Authentication
Every request must send your token in the **`API-Token`** header. Do **not** use `Authorization` or `Authentication` for this API.
Generate a token in Jira: **Apps** → **OKR for Jira** → **Settings** → **API** → **Generate new token**. Name the token, create it, then copy and store it securely — it cannot be retrieved again later. Users with **API_ADMIN_TABLE_ACCESS** can see, rename, or revoke any organization token on that same **API** settings page.
## Responses
Fetch (query) methods return a common JSON shape; which arrays and fields appear depends on your query parameters (for example **expand**).
## Teams
Objectives and key results include **`teamIds`**: identifiers of teams linked to each entity. When **`expand`** includes **`TEAMS`**, the response also includes a **`teams`** array with **`id`** and **`name`** for each referenced team.
The same identifier appears in **`teamIds`**, in **`teams[].id`**, and when matching expanded rows.
For team fields beyond **`id`** and **`name`**, use the **Teams** endpoints documented in the BigPicture developer documentation alongside this API reference.
## Status values
The Jira app shows user-friendly status labels. **Update** requests must use **displayed** in-progress strings: **NOT STARTED**, **ON TRACK**, **AT RISK**, **OFF TRACK** (the UI label for action required). Completed statuses (e.g. SUCCESS, CANCELED, RESCHEDULED) are not accepted here. Some query responses may still expose internal enum names in places; prefer **displayed** fields where both appear.
## Progress
For the latest progress, rely on **`percentDone`** on objectives and key results rather than inferring it only from update history.
## Rate limiting
Requests may be throttled. On **429**, wait before retrying.
'
contact:
name: OKR for Jira Support
url: https://appfire.atlassian.net/servicedesk/customer/portal/11/group/1237
version: v2
servers:
- url: https://okr-ppm-prod.appfire.com
description: Current instance
- url: https://eu.okr-ppm-prod.appfire.com
description: Europe region
- url: https://au.okr-ppm-prod.appfire.com
description: Australia region
- url: https://ca.okr-ppm-prod.appfire.com
description: Canada region
security:
- API-Token: []
tags:
- name: API query methods
description: Retrieve objectives, key results, updates, and comments. Use **expand** to include related entities (teams, periods, labels, etc.) instead of IDs only. Authenticate with the **API-Token** header. For team identifiers and the **Teams** API, see **Teams** in the API overview.
paths:
/api/v2/api-export/updates:
get:
tags:
- API query methods
summary: Query updates by entity
description: '## Base URL for this request
Select the server matching your Jira Cloud data residency from the **Servers** drop-down before making requests:
- **Europe region:** https://eu.okr-ppm-prod.appfire.com
- **Australia region:** https://au.okr-ppm-prod.appfire.com
- **Canada region:** https://ca.okr-ppm-prod.appfire.com
- **US / Everywhere else:** https://okr-ppm-prod.appfire.com
Updates for objectives or key results, **newest first**. Omit **entityId** to return updates across all entities.
**Progress:** Prefer **`percentDone`** on objectives and key results for the latest progress — not every change produces an update row. Objective updates always have **value** null (objective progress is derived from key results). For **manual** key results, updates can carry **startValue**, **value**, and **desiredValue** to show progress over time. **Auto** key results: system updates when linked issues change may include progress values; manual text-only updates on auto KRs may omit editable progress on the returned update object. **source:** MANUAL (UI), API (public update API), or AUTO (system/linked issues).
**Pagination:** Cursor-based; **nextCursor** in the response means more pages. Absent **nextCursor**, there is no further page.'
operationId: fetchUpdatesByEntityId
parameters:
- name: entityId
in: query
description: ID of a single objective or key result to return updates for. If not provided, updates for all entities will be returned, newest first.
required: false
schema:
type: string
- name: cursor
in: query
description: Cursor for pagination. Use the value of nextCursor from previous response to get the next page.
required: false
schema:
type: string
- name: pageSize
in: query
description: Number of updates to return per page. Takes values from 1 to 1000. Default is 1000.
required: false
schema:
type: integer
format: int32
default: 1000
- name: laterThan
in: query
description: Only return updates later than this date (open interval), in UNIX Epoch milliseconds
required: false
schema:
type: integer
format: int64
- name: earlierThan
in: query
description: Only return updates earlier than this date (open interval), in UNIX Epoch milliseconds
required: false
schema:
type: integer
format: int64
responses:
'200':
description: Successful retrieval of updates
content:
application/json:
schema:
$ref: '#/components/schemas/ApiExportBulkUpdate'
'400':
description: Invalid pagination parameters
content:
application/json:
schema:
type: object
'401':
description: Invalid or missing API token
content:
application/json:
schema:
type: object
/api/v2/api-export/updateComments:
get:
tags:
- API query methods
summary: Query comments on updates
description: '## Base URL for this request
Select the server matching your Jira Cloud data residency from the **Servers** drop-down before making requests:
- **Europe region:** https://eu.okr-ppm-prod.appfire.com
- **Australia region:** https://au.okr-ppm-prod.appfire.com
- **Canada region:** https://ca.okr-ppm-prod.appfire.com
- **US / Everywhere else:** https://okr-ppm-prod.appfire.com
Paged comments on updates — all updates or filtered by **updateId**. Newest first. **nextCursor** requests the next page; no **nextCursor** when exhausted.'
operationId: fetchCommentsByUpdateIds
parameters:
- name: updateId
in: query
description: IDs of updates to retrieve comments for. If not provided, comments for all updates will be returned, newest first.
required: false
schema:
type: array
items:
type: string
- name: cursor
in: query
description: Cursor for pagination. Use the value of nextCursor from previous response to get the next page.
required: false
schema:
type: string
- name: pageSize
in: query
description: Number of comments to return per page. Takes values from 1 to 1000. Default is 1000.
required: false
schema:
type: integer
format: int32
default: 1000
- name: laterThan
in: query
description: Only return comments later than this date (open interval), in UNIX Epoch milliseconds
required: false
schema:
type: integer
format: int64
- name: earlierThan
in: query
description: Only return comments earlier than this date (open interval), in UNIX Epoch milliseconds
required: false
schema:
type: integer
format: int64
responses:
'200':
description: Successful retrieval of comments
content:
application/json:
schema:
$ref: '#/components/schemas/ApiExportBulkUpdateComments'
'400':
description: Invalid pagination parameters
content:
application/json:
schema:
type: object
'401':
description: Invalid or missing API token
content:
application/json:
schema:
type: object
/api/v2/api-export/objectives/byIds:
get:
tags:
- API query methods
summary: Query objectives by IDs
description: '## Base URL for this request
Select the server matching your Jira Cloud data residency from the **Servers** drop-down before making requests:
- **Europe region:** https://eu.okr-ppm-prod.appfire.com
- **Australia region:** https://au.okr-ppm-prod.appfire.com
- **Canada region:** https://ca.okr-ppm-prod.appfire.com
- **US / Everywhere else:** https://okr-ppm-prod.appfire.com
Lists objectives for the given IDs. **expand** controls which related objects are inlined (KEY_RESULTS, TEAMS, PERIODS, LABELS, TYPES, CUSTOM_FIELDS); otherwise you receive IDs only.'
operationId: fetchObjectivesByIds
parameters:
- name: objectiveIds
in: query
description: Objective IDs to retrieve (repeat param or comma-separated, depending on client).
required: true
schema:
type: array
items:
type: string
- name: expand
in: query
description: Related data to expand. KEY_RESULTS, TEAMS, PERIODS, LABELS, TYPES, CUSTOM_FIELDS.
required: false
style: form
explode: false
schema:
type: array
items:
type: string
enum:
- KEY_RESULTS
- TEAMS
- PERIODS
- LABELS
- TYPES
- CUSTOM_FIELDS
responses:
'200':
description: Successful retrieval of objectives
content:
application/json:
schema:
$ref: '#/components/schemas/ApiExportData'
'400':
description: Invalid expand options provided
content:
application/json:
schema:
type: object
'401':
description: Invalid or missing API token
content:
application/json:
schema:
type: object
/api/v2/api-export/objectives/byDate:
get:
tags:
- API query methods
summary: Query objectives by date range
description: '## Base URL for this request
Select the server matching your Jira Cloud data residency from the **Servers** drop-down before making requests:
- **Europe region:** https://eu.okr-ppm-prod.appfire.com
- **Australia region:** https://au.okr-ppm-prod.appfire.com
- **Canada region:** https://ca.okr-ppm-prod.appfire.com
- **US / Everywhere else:** https://okr-ppm-prod.appfire.com
Lists objectives whose **start date** and/or **due date** fall within the query window (epoch milliseconds). Without **expand**, connected entities appear as IDs only. **Permitted expand values:** KEY_RESULTS, TEAMS, PERIODS, LABELS, TYPES, CUSTOM_FIELDS.'
operationId: fetchObjectives
parameters:
- name: startDateEpochMilli
in: query
description: Start date of query time window, in UNIX Epoch time format, in milliseconds
required: true
schema:
type: integer
format: int64
example: 1609459200000
- name: deadlineEpochMilli
in: query
description: End date of query time window, in UNIX Epoch time format, in milliseconds
required: true
schema:
type: integer
format: int64
example: 1748647410000
- name: expand
in: query
description: Related data to expand (comma-separated in HTTP). KEY_RESULTS, TEAMS, PERIODS, LABELS, TYPES, CUSTOM_FIELDS. Omit for IDs only.
required: false
style: form
explode: false
schema:
type: array
items:
type: string
enum:
- KEY_RESULTS
- TEAMS
- PERIODS
- LABELS
- TYPES
- CUSTOM_FIELDS
responses:
'200':
description: Successful retrieval of objectives
content:
application/json:
schema:
$ref: '#/components/schemas/ApiExportData'
'400':
description: Invalid expand options provided
content:
application/json:
schema:
type: object
'401':
description: Invalid or missing API token
content:
application/json:
schema:
type: object
/api/v2/api-export/keyResults/byIds:
get:
tags:
- API query methods
summary: Query key results by IDs
description: '## Base URL for this request
Select the server matching your Jira Cloud data residency from the **Servers** drop-down before making requests:
- **Europe region:** https://eu.okr-ppm-prod.appfire.com
- **Australia region:** https://au.okr-ppm-prod.appfire.com
- **Canada region:** https://ca.okr-ppm-prod.appfire.com
- **US / Everywhere else:** https://okr-ppm-prod.appfire.com
Lists key results for the given IDs. **expand:** OBJECTIVES, TEAMS, PERIODS, LABELS, TYPES, CUSTOM_FIELDS.'
operationId: fetchKeyResultsByIds
parameters:
- name: keyResultIds
in: query
description: Key result IDs to retrieve.
required: true
schema:
type: array
items:
type: string
- name: expand
in: query
description: Related data to expand. OBJECTIVES, TEAMS, PERIODS, LABELS, TYPES, CUSTOM_FIELDS.
required: false
style: form
explode: false
schema:
type: array
items:
type: string
enum:
- OBJECTIVES
- TEAMS
- PERIODS
- LABELS
- TYPES
- CUSTOM_FIELDS
responses:
'200':
description: Successful retrieval of key results
content:
application/json:
schema:
$ref: '#/components/schemas/ApiExportData'
'400':
description: Invalid expand options provided
content:
application/json:
schema:
type: object
'401':
description: Invalid or missing API token
content:
application/json:
schema:
type: object
/api/v2/api-export/keyResults/byDate:
get:
tags:
- API query methods
summary: Query key results by date range
description: '## Base URL for this request
Select the server matching your Jira Cloud data residency from the **Servers** drop-down before making requests:
- **Europe region:** https://eu.okr-ppm-prod.appfire.com
- **Australia region:** https://au.okr-ppm-prod.appfire.com
- **Canada region:** https://ca.okr-ppm-prod.appfire.com
- **US / Everywhere else:** https://okr-ppm-prod.appfire.com
Lists key results whose **start** and/or **due date** fall within the window. **Permitted expand values:** OBJECTIVES, TEAMS, PERIODS, LABELS, TYPES, CUSTOM_FIELDS.'
operationId: fetchKeyResults
parameters:
- name: startDateEpochMilli
in: query
description: Start date of query time window, in UNIX Epoch time format, in milliseconds
required: true
schema:
type: integer
format: int64
example: 1509459200000
- name: deadlineEpochMilli
in: query
description: End date of query time window, in UNIX Epoch time format, in milliseconds
required: true
schema:
type: integer
format: int64
example: 1748647410000
- name: expand
in: query
description: Related data to expand. OBJECTIVES, TEAMS, PERIODS, LABELS, TYPES, CUSTOM_FIELDS.
required: false
style: form
explode: false
schema:
type: array
items:
type: string
enum:
- OBJECTIVES
- TEAMS
- PERIODS
- LABELS
- TYPES
- CUSTOM_FIELDS
responses:
'200':
description: Successful retrieval of key results
content:
application/json:
schema:
$ref: '#/components/schemas/ApiExportData'
'400':
description: Invalid expand options provided
content:
application/json:
schema:
type: object
'401':
description: Invalid or missing API token
content:
application/json:
schema:
type: object
components:
schemas:
ApiExportKeyResult:
type: object
description: A key result linked to an objective
properties:
id:
type: string
description: Unique identifier
examples:
- 62384a6942adda046598b3bd
key:
type: string
description: Human-readable key
examples:
- KR-108
name:
type: string
description: Key result title
examples:
- Close 15 enterprise deals
link:
type: string
description: Deep link to the key result in OKR for Jira
description:
type: string
description: Rich-text description
parentObjectiveId:
type: string
description: ID of the parent objective
examples:
- 62334eac00ee2b102e34fdb7
issueIds:
type: array
description: IDs of linked Jira issues
items:
type: string
typeId:
type: string
description: OKR type ID, when types are enabled
typeName:
type: string
description: OKR type name, when types are enabled
ownerAccountId:
type: string
description: Jira account ID of the owner
examples:
- 557058:5aedf933-2312-40bc-b328-0c21314167f0
collaboratorAccountIds:
type: array
description: Jira account IDs of collaborators
items:
type: string
percentDone:
type: number
format: double
description: Progress percentage (0-100)
examples:
- 45.0
created:
type: string
format: date-time
description: Creation timestamp
examples:
- 2024-01-15T10:30:00+0000
startDate:
type: string
format: date-time
description: Start date
examples:
- 2024-01-01T00:00:00+0000
deadline:
type: string
format: date-time
description: Due date
examples:
- 2024-03-31T23:59:59+0000
expectedEndDate:
type: string
format: date-time
description: Expected end date
examples:
- 2024-03-31T23:59:59+0000
labelIds:
type: array
description: IDs of associated labels
items:
type: string
teamIds:
type: array
description: Team identifiers linked to this key result. Match **teams[].id** when **TEAMS** is expanded. For more team fields, use the **Teams** API documented in the BigPicture developer documentation.
items:
type: string
periodAliasId:
type: string
description: ID of the period this key result belongs to
latestUpdate:
$ref: '#/components/schemas/ApiExportUpdate'
unit:
$ref: '#/components/schemas/ApiExportUnit'
currentProgressDefinition:
$ref: '#/components/schemas/ApiExportProgressDefinition'
weight:
type: integer
format: int32
description: Weight for weighted progress calculation
examples:
- 1
finalGrade:
type: number
format: double
description: Final grade when key result is closed
examples:
- 0.9
customFields:
type: object
additionalProperties: {}
description: Custom field values keyed by field ID. Only includes fields that are visible (not hidden or deleted). Expand CUSTOM_FIELDS to receive field definitions (id, name, type, etc.) as a lookup.
ApiExportUpdate:
type: object
description: A status update for an objective or key result
properties:
updateId:
type: string
description: Unique update identifier
examples:
- 6456a3b200ee2b102e34fdb9
entityId:
type: string
description: ID of the objective or key result this update belongs to
examples:
- 62334eac00ee2b102e34fdb7
status:
type: string
description: Status enum value
enum:
- ON_TRACK
- AT_RISK
- ACTION_REQUIRED
- NOT_STARTED
- SUCCESS
- FINISHED
- ASSUMPTIONS_CHANGED
- DELAYED
- CANCELED
- FAILED
- UNDEFINED
- MISSED_TARGET
examples:
- ON_TRACK
displayedStatus:
type: string
description: Human-readable status label
examples:
- On Track
created:
type: string
format: date-time
description: When the update was created
examples:
- 2024-02-15T14:30:00+0000
value:
type: number
format: double
description: Current progress value (key results only)
examples:
- 13500.5
description:
type: string
description: Update description/comment text
startValue:
type: number
format: double
description: Start value of the progress range
examples:
- 0.0
desiredValue:
type: number
format: double
description: Target/desired value of the progress range
examples:
- 20000.0
source:
type: string
description: 'Origin of the update: MANUAL (UI), API (public API), or AUTO (system/linked issues)'
enum:
- MANUAL
- API
- AUTO
examples:
- MANUAL
ApiExportUpdateComment:
type: object
description: A comment on an update
properties:
commentId:
type: string
description: Unique comment identifier
examples:
- 6456a3b200ee2b102e34fdba
updateId:
type: string
description: ID of the update this comment belongs to
examples:
- 6456a3b200ee2b102e34fdb9
text:
type: string
description: Comment text content
authorAccountId:
type: string
description: Jira account ID of the comment author
examples:
- 557058:5aedf933-2312-40bc-b328-0c21314167f0
replyToCommentId:
type: string
description: ID of the comment this is a reply to, if threaded
created:
type: string
format: date-time
description: When the comment was created
examples:
- 2024-02-15T14:30:00+0000
lastEdited:
type: string
format: date-time
description: When the comment was last edited
examples:
- 2024-02-15T15:00:00+0000
ApiExportBulkUpdate:
type: object
description: Paginated list of updates
properties:
updates:
type: array
description: List of updates, newest first
items:
$ref: '#/components/schemas/ApiExportUpdate'
nextCursor:
type: string
description: Cursor for fetching the next page. Null when there are no more results.
ApiExportTeam:
type: object
description: A team linked to objectives or key results in this export payload
properties:
id:
type: string
description: Team identifier. Matches the corresponding **teamIds** entry on objectives and key results in this response. For additional team properties, use the **Teams** API documented in the BigPicture developer documentation.
examples:
- '2'
- '7'
- '11'
name:
type: string
description: Team name
examples:
- Engineering
ApiExportProgressDefinition:
type: object
description: Progress tracking definition for a key result
properties:
type:
type: string
description: 'Key result type: STANDARD (manual progress) or AUTO (JQL-driven)'
enum:
- STANDARD
- AUTO
examples:
- STANDARD
startValue:
type: number
format: double
description: Start value of the progress range
examples:
- 0.0
desiredValue:
type: number
format: double
description: Target/desired value of the progress range
examples:
- 100.0
jql:
type: string
description: JQL query for auto key results (null for standard key results)
ApiExportData:
type: object
description: Response containing objectives and/or key results with optionally expanded related entities
properties:
okrs:
type: array
description: List of objectives
items:
$ref: '#/components/schemas/ApiExportObjective'
krs:
type: array
description: List of key results (included when expand contains KEY_RESULTS or OBJECTIVES)
items:
$ref: '#/components/schemas/ApiExportKeyResult'
teams:
type: array
description: Teams referenced by objectives and key results (included when **expand** contains **TEAMS**). Each **id** matches the corresponding **teamIds** entry. For more team fields, use the **Teams** API documented in the BigPicture developer documentation.
items:
$ref: '#/components/schemas/ApiExportTeam'
periods:
type: array
description: List of periods (included when expand contains PERIODS)
items:
$ref: '#/components/schemas/ApiExportPeriodAlias'
labels:
type: array
description: List of labels (included when expand contains LABELS)
items:
$ref: '#/components/schemas/ApiExportLabel'
okrTypes:
type: array
description: List of OKR types (included when expand contains TYPES)
items:
$ref: '#/components/schemas/ApiExportOkrType'
customFields:
type: array
description: List of custom field definitions (included when expand contains CUSTOM_FIELDS)
items:
$ref: '#/components/schemas/ApiExportCustomField'
ApiExportObjective:
type: object
description: An OKR objective
properties:
id:
type: string
description: Unique identifier
examples:
- 62334eac00ee2b102e34fdb7
key:
type: string
description: Human-readable key
examples:
- OBJ-42
name:
type: string
description: Objective title
examples:
- Increase revenue by 20%
link:
type: string
description: Deep link to the objective in OKR for Jira
examples:
- https://mysite.atlassian.net/jira/apps/ebe8335e-f3f9-49d1-a3d4-dc939aa419ac/1edb3e3f-2b65-4edd-b3fe-b5417244e1bd#box/ROOT/okr?navigationEntryPoint=modulePicker&clientRoute=L2RldGFpbHMvby82OTI1YzIzMDRiYjBmNWM3ZmI4MzYwNTd
description:
type: string
description: Rich-text description
parentObjectiveId:
type: string
description: ID of the parent objective, if nested
examples:
- 62334eac00ee2b102e34fdb6
okrTypeId:
type: string
description: OKR type ID, when types are enabled
okrTypeName:
type: string
description: OKR type name, when types are enabled
ownerAccountId:
type: string
description: Jira account ID of the owner
examples:
- 557058:5aedf933-2312-40bc-b328-0c21314167f0
collaboratorAccountIds:
type: array
description: Jira account IDs of collaborators
items:
type: string
percentDone:
type: number
format: double
description: Progress percentage (0-100)
examples:
- 67.5
created:
type: string
format: date-time
description: Creation timestamp
examples:
- 2024-01-15T10:30:00+0000
startDate:
type: string
format: date-time
description: Start date
examples:
- 2024-01-01T00:00:00+0000
deadline:
type: string
format: date-time
description: Due date
examples:
- 2024-03-31T23:59:59+0000
expectedEndDate:
type: string
format: date-time
description: Expected end date
examples:
- 2024-03-31T23:59:59+0000
labelIds:
type: array
description: IDs of associated labels
items:
type: string
teamIds:
type: array
description: Team identifiers linked to this objective. Match **teams[].id** when **TEAMS** is expanded. For more team fields, use the **Teams** API documented in the BigPicture developer documentation.
items:
type: string
krIds:
type: array
description: IDs of child key results
items:
type: string
childObjectiveIds:
type: array
description: IDs of child objectives
items:
type: string
latestUpdate:
$ref: '#/components/schemas/ApiExportUpdate'
periodAliasId:
type: string
description: ID of the period this objective belongs to
weight:
type: integer
format: int32
description: Weight for weighted progress calculation
examples:
- 1
finalGrade:
type: number
format: double
description: Final grade when objective is closed
examples:
- 0.85
iconBackgroundColor:
type: string
description: Icon background color hex code
examples:
- '#4C9AFF'
iconTextColor:
type: string
description: Icon text color hex code
examples:
- '#FFFFFF'
customFields:
type: object
additionalProperties: {}
description: Custom field values keyed by field ID. Only includes fields that are visible (not hidden or deleted). Expand CUSTOM_FIELDS to receive field definitions (id, name, type, etc.) as a lookup.
ApiExportLabel:
type: object
description: A label used to categorize OKRs
properties:
id:
type: string
description: Unique label identifier
examples:
- 6123ab
# --- truncated at 32 KB (35 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/appfire/refs/heads/main/openapi/appfire-api-query-methods-api-openapi.yml