Before we start, check the auth guide.
GET /rest/oboard/1.0/api/v1/workspaces – returns all the workspaces for the OKR board.
GET https://jirainstanceurl/rest/oboard/1.0/api/v1/workspaces |
Example
GET https://jirainstanceurl/rest/oboard/1.0/api/v1/workspaces |
No parameters
[ { "id": 163, "iss": "aaaa-02cd-aaa-aaa-0c946df6b24b", "name": "GIANT", "key": "GG" }, { "id": 164, "iss": "aaaa-02cd-aaa-aaa-0c946df6b24b", "name": "WS for Tests", "key": "CR" } ] |
GET /rest/oboard/1.0/api/v1/intervals – returns all intervals for a given workspace.
GET https://jirainstanceurl/rest/oboard/1.0/api/v1/intervals?workspaceId={{put_here_id}} |
Example
GET https://jirainstanceurl/rest/oboard/1.0/api/v1/intervals?workspaceId=1 |
Field | Required | Description |
---|---|---|
workspaceId | Yes | The if of workspace. |
[ { "id": 1902, "name": "Future (backlog)", "startDate": "2020-10-27T09:00:30.000Z", "endDate": "2020-10-27T09:00:30.000Z", "open": true, "backlog": true }, { "id": 2009, "name": "AD", "startDate": "2020-12-31T23:00:00.000Z", "endDate": "2021-03-31T21:59:59.000Z", "open": false, "backlog": false } ] |
GET /rest/oboard/1.0/api/v1/groups – returns all groupIds for a given workspace.
GET https://jirainstanceurl/rest/oboard/1.0/api/v1/groups?workspaceId={{put_here_id}}&includeServiceGroups={{true/false}} |
Example
GET https://jirainstanceurl/rest/oboard/1.0/api/v1/groups?workspaceId=141&includeServiceGroups=true |
Field | Required | Description |
---|---|---|
workspaceId | Yes | The ID of workspace. |
includeServiceGroups | No | Use includeServiceGroups = true if you need to get an id for the “no group“ entity. |
Response
[ { "workspaceId": 141, "id": 1227, "name": "No Group", "description": "The group to store users until any other group has been assigned", "syncWithJira": false, "userCount": 1, "associatedJiraGroups": [] }, { "workspaceId": 141, "id": 1259, "name": "tes", "description": "", "syncWithJira": false, "userCount": 2, "associatedJiraGroups": [] } ] |
GET /rest/oboard/1.0/api/v1/users – returns all users for a given workspace.
GET https://jirainstanceurl/rest/oboard/1.0/api/v1/users?workspaceId={{put_here_id}}&roleId={{put_here_roleid}} |
Example
GET https://jirainstanceurl/rest/oboard/1.0/api/v1/users?workspaceId=141&roleId=1 |
Field | Required? | Description |
---|---|---|
workspaceId | Yes | The ID of workspace. |
roleId | No | Id of the user role.
|
groupid (will be ready soon) | No | Get users from a certain group. |
[ { "id": 347, "workspaceId": 164, "accountId": "5bfef3333c48883c86379fd3", "defaultTeamId": 1301, "teams": [ { "workspaceId": 164, "id": 1301, "name": "No Group", "description": "The group to store users until other group has assigned", "syncWithJira": false, "userCount": 1, "associatedJiraGroups": null } ], "roleId": 3, "name": "oboard test", "oboardUser": true, "userName": "5bfef3333c48883c86379fd3" }, { "id": 350, "workspaceId": 164, "accountId": "5bfef3333c48883c86379fd3", "defaultTeamId": 1302, "teams": [ { "workspaceId": 164, "id": 1302, "name": "Group1", "description": "", "syncWithJira": false, "userCount": 1, "associatedJiraGroups": null } ], "roleId": 1, "name": "Dmitry Test", "oboardUser": true, "userName": "5bfef3333c48883c86379fd3" } ] |
Please use /rest/oboard/1.0/api/v1/elements below |
GET /rest/oboard/1.0/api/v1/objectives – returns all objectives for a given workspace.
GET https://jirainstanceurl/rest/oboard/1.0/api/v1/objectives?workspaceIds={{put_here_id}} |
Example
GET https://jirainstanceurl/rest/oboard/1.0/api/v1/objectives?workspaceIds=141&typeIds=3&groupIds=1276&userIds=333fef7de6c48883c86379fd3&userIds=3337594642daa474bc92c19e&hasParent=true&maxGrade=50 |
GET /rest/oboard/1.0/api/v1/elements – returns all objectives for a given workspace.
GET https://jirainstanceurl/rest/oboard/1.0/api/v1/elements?workspaceIds={{put_here_id}} |
Example
GET https://jirainstanceurl/rest/oboard/1.0/api/v1/elements?workspaceIds=141&typeIds=1 |
Field | Required? | Description | |
---|---|---|---|
workspaceId [array] | Yes | The ID of workspace. ⚠️Here and for other “array“ parameters you need to send 2 get-parameters in the request with the same name.
| |
groupIds [array] | No | Array of a group ids. | |
userIds [array] | No | Array of a owner ids. | |
typeIds [array] | Yes | Type of the objective
| |
levelIds [array] | Yes | The id of Objective level (e.g. Company-level) use /rest/oboard/1.0/api/v1/levels to get the id of level for a given WS | |
hasParent | No | Flag to check if an objective has a parent obj. | |
intervalId | No | ID of the Interval | |
minGrade | No | Filter objectives with a grade above this value. | |
maxGrade | No | Filter objectives with up to %value% grade. | |
limit | No (default 50) | A number of objectives returned in the response.
| |
startAt | No | Offset for the request. Default = 0. |
POST /rest/oboard/1.0/api/v1/objectives – create an objective.
POST https://jirainstanceurl/rest/oboard/1.0/api/v1/objectives |
Example
POST https://jirainstanceurl/rest/oboard/1.0/api/v1/objectives { "groupId": 1303, "name": "Company Objective not contribute owner description", "workspaceId": 164, "intervalId":2022, "typeId":3, "ownerId":"33fef7de6c48883c86379fd3", "contribute":false, "description":"Company Objective not contribute owner description", "parentObjectiveId":"4537" } |
Field | Required | Description | |
---|---|---|---|
workspaceId | Yes | The ID of workspace. | |
intervalId | Yes | The ID of interval in the workspace. | |
groupId | Yes | Group to be assigned for this objective. | |
ownerId | No (yes if typeid=1) | User ID (in the plugin). | |
typeId | Yes | Type of the objective to create
| |
levelId | Yes | Type of the OKR GET /rest/oboard/1.0/api/v1/levels | |
parentObjectiveId | No | Put here the id of the objective if you want to set a parent objective. | |
contribute | No | If OKR is contributing or not to parent objective (if exists). | |
description | No (up to 1024 symbols) | Description for the OKR | |
name | Yes (up to 512 symbols) | Title for the OKR |
{ "workspaceId": 164, "id": 6601, "name": "Company Objective not contribute owner description", "description": "Company Objective not contribute owner description", "ownerId": "33fef7de6c48883c86379fd3", "typeId": 3, "statusId": 1, "createDate": "2020-11-18T10:07:06.000Z", "lastUpdateDate": "2020-11-18T10:07:06.000Z", "contribute": false, "innerId": 1016, "parentObjectiveId": 4537, "intervalId": 2022, "groupId": 1303 } |
PUT /rest/oboard/1.0/api/v1/objectives – update an objective.
If you want to delete non-required fields you need: |
PUT https://jirainstanceurl/rest/oboard/1.0/api/v1/objectives |
Example
PUT https://jirainstanceurl/rest/oboard/1.0/api/v1/objectives { "objectiveId":123, "groupId": 1302, "name": "Company Objective", "workspaceId": 164, "intervalId":2023, "typeId":2 } |
Field | Required | Description | |
---|---|---|---|
objectiveId | Yes | Objective ID that has to be changed. | |
workspaceId | Yes | The ID of workspace. ⚠️The WS cannot be changed, it’s needed only for validation purposes. | |
groupId | No | Group to be assigned for this objective. | |
ownerId | No (yes if typeid=1) | User ID (in the plugin). | |
typeId | Yes | Type of the objective to create
| |
levelId | Yes | Type of the OKR GET /rest/oboard/1.0/api/v1/levels | |
parentObjectiveId | No | Put here the id of the objective if you want to set a parent objective. | |
contribute | No | If OKR is contributing or not to parent objective (if exists). | |
description | No | Description for the OKR | |
name | Yes | The title of OKR | |
Interval ID (coming soon) | Yes | The ID of interval in the workspace. |
Response
{ "workspaceId": 164, "id": 6602, "name": "Company Objective Wednesday, November 18, 2020 11:24 AM", "description": "", "ownerId": null, "typeId": 2, "statusId": 1, "createDate": "2020-11-18T10:24:11.000Z", "lastUpdateDate": "2020-11-18T10:24:11.000Z", "contribute": true, "innerId": 1017, "parentObjectiveId": null, "intervalId": 2023, "groupId": 1302 } |
Delete /rest/oboard/1.0/api/v1/objectives – remove objective and all the nested items
DELETE https://jirainstanceurl/rest/oboard/1.0/api/v1/objectives |
Example
DELETE https://jirainstanceurl/rest/oboard/1.0/api/v1/objectives { "objectiveId":1111, "workspaceId":164 } |
Field | Required | Description |
---|---|---|
objectiveId | Yes | Objective ID that has to be changed. |
workspaceId | Yes | The ID of workspace. |
removeNestedItems* coming soon | No | The flag if the nested items need to be removed. |
Objective was successfully removed |
Get /rest/oboard/1.0/api/v1/objectives/children – returns only the nested items for the given objective
Please use /rest/oboard/1.0/api/v1/elements/nested |
Request
GET https://jirainstanceurl/rest/oboard/1.0/api/v1/objectives/children?parentId={{objectiveid}}&workspaceIds={{workspaced}} |
Example
GET https://jirainstanceurl/rest/oboard/1.0/api/v1/objectives/children?parentId=2239&workspaceIds=222 |
Get /rest/oboard/1.0/api/v2/elements/nested – returns only the nested items for the given objective
GET https://backend.okr-api.com/rest/oboard/1.0/api/v2/elements/nested?parentId={{objectiveid}}&workspaceIds={{workspaced}} |
Example
GET https://backend.okr-api.com/rest/oboard/1.0/api/v2/elements/nested?parentId=2239&workspaceIds=222 |
Field | Required? | Description |
---|---|---|
parentId | Yes | Id of the objective. |
workspaceId | Yes | The ID of the workspace where the objective is located. |
searchType=1 | Yes | First-level nested items |
searchType=2 | Yes | Full structure |
We re-use method GET /rest/oboard/1.0/api/v1/objectives for now, but the type_id=4.
We re-use method GET /rest/oboard/1.0/api/v1/objectives for now, but the type_id=4.
GET /rest/oboard/1.0/api/v1/objectives – returns all objectives for a given workspace.
GET https://jirainstanceurl/rest/oboard/1.0/api/v1/objectives?typeIds=4&workspaceIds={{put_here_id}} |
Example
GET https://jirainstanceurl/rest/oboard/1.0/api/v1/objectives?workspaceIds=141&typeIds=4&groupIds=1276&userIds=333fef7de6c48883c86379fd3&userIds=3337594642daa474bc92c19e&hasParent=true&maxGrade=50 |
Fields are the same as for getting objective (above).
[ { "type": "KR", "objective": { "workspaceId": 163, "id": 6570, "parentObjectiveId": 6567, "parentTypeId": null, "name": "KR &&&@@@Tuesday, November 17, 2020 8:40 AM", "description": "", "ownerId": "557058-904f8904e553", "ownerDisplayName": "Vladyslav Test", "ownerName": "557058-904f8904e553", "typeId": 4, "statusId": 1, "createDate": "2020-11-17T07:40:49.000Z", "lastUpdateDate": "2020-11-17T07:40:49.000Z", "grade": 0, "gradeColor": "grade-red", "innerId": 7, "childCount": 0, "expanded": false, "tasks": [], "keyResults": [], "childObjectives": [], "parentObjectives": [], "level": 0, "contribute": true, "existContributeChildren": false, "originalValue": 20.0, "currentValue": 20.0, "targetValue": 40.0, "intervalId": 2022, "weight": null, "weightMultiplier": null, "fieldTypeId": 1, "groupId": 1300, "groupName": "df", "displayId": "GG-KR-7" } }] |
If the parameter is NOT SET in the body, then it will be set to NULL |
PUT /rest/oboard/1.0/api/v1/key-results – update key result
PUT https://jirainstanceurl/rest/oboard/1.0/api/v1/key-results |
Example
PUT https://jirainstanceurl/rest/oboard/1.0/api/v1/key-results { "keyResultId":3442, "groupId": 1302, "name": "Changed KR", "workspaceId": 164, "objectiveId":2938, "ownerId":"ccc356c363cbaa729c4c4f88", "fieldTypeId":3, "originalValue":60, "currentValue": 100, "targetValue":90 } |
Field | Required | Description | |
---|---|---|---|
keyResultId | Yes | The id of a key result to update | |
workspaceId | Yes | The ID of the workspace where the KR is located. | |
groupId | Yes | Assigned group | |
ownerId | Yes | Assignee | |
fieldTypeId | No | Type of the KR result.
| |
currentValue | Yes | Current Value for the KR ⚠️Pls note the for a binary KR you should use either 0 or 1 | |
originalValue | Yes | Starting value for the KR ⚠️Pls note the for a binary KR you should use 0 | |
targetValue | Yes | Filter By Target Value ⚠️Pls note the for a binary KR you should use 1 | |
name | Yes | Name of a KR | |
description | No | Description of a KR |
If the parameter is NOT SET in the body, then it will be set to NULL |
POST
/rest/oboard/1.0/api/v1/key-results – update key result
POST https://jirainstanceurl/rest/oboard/1.0/api/v1/key-results |
Example
POST https://jirainstanceurl/rest/oboard/1.0/api/v1/key-results { "groupId": 1302, "name": "Changed KR", "workspaceId": 164, "objectiveId":2938, "ownerId":"ccc356c363cbaa729c4c4f88", "fieldTypeId":3, "originalValue":60, "currentValue": 100, "targetValue":90 } |
Field | Required | Description | |
---|---|---|---|
keyResultId | Yes | The id of a key result to update | |
workspaceId | Yes | The ID of the workspace where the KR is located. | |
groupId | Yes | Assigned group | |
ownerId | Yes | Assignee | |
fieldTypeId | No | Type of the KR result.
| |
originalValue | Yes | Starting value for the KR ⚠️Pls note the for a binary KR you should use 0 | |
targetValue | Yes | Filter By Target Value ⚠️Pls note the for a binary KR you should use 1 | |
name | Yes | Name of a KR | |
description | No | Description of a KR |
{ "workspaceId": 164, "workspaceKey": "CR", "workspaceName": "WS for Tests", "id": 6612, "parentObjectiveId": 6611, "parentTypeId": null, "name": "NEW KR c6917a98-c796-4f62-809a-e2e7eb761ee5", "description": "", "ownerId": "5bfef7de6c48883c86379fd3", "ownerIcon": "https://secure.gravatar.com/avatar/ae81713d22489934bded5afee1b332a4?d=https%3A%2F%2Favatar-management--avatars.us-west-2.prod.public.atl-paas.net%2Finitials%2FDZ-0.png", "ownerDisplayName": "Dmitry Test", "ownerName": "5bfef7de6c48883c86379fd3", "typeId": 4, "statusId": 1, "createDate": "2020-11-18T16:28:33.000Z", "lastUpdateDate": "2020-11-18T16:28:33.000Z", "grade": 0, "gradeColor": "", "innerId": 309, "childCount": 0, "expanded": false, "tasks": [], "keyResults": [], "childObjectives": [], "parentObjectives": [], "permissions": [], "level": 0, "contribute": true, "existContributeChildren": false, "originalValue": 20.0, "currentValue": 20.0, "targetValue": 40.0, "intervalId": 2022, "intervalName": "Q4 2020", "orderValue": 0.0, "weight": null, "weightMultiplier": null, "fieldTypeId": 1, "groupId": 1303, "groupName": "Group2", "displayId": null, "dueDate": "2020-12-31T00:00:00.000Z" } |
DELETE https://jirainstanceurl/rest/oboard/1.0/api/v1/key-results |
Example
DELETE https://jirainstanceurl/rest/oboard/1.0/api/v1/objectives { "keyResultId":12345, "workspaceId":164 } |
Field | Required? | Description |
---|---|---|
keyResultId | Yes | The id of a key result to update |
workspaceId | Yes | The ID of the workspace where the KR is located. |
KeyResult was successfully removed |