http://167.99.210.191/rest/oboard/1.0/api/v1/objectives?typeIds=3&typeIds=1&workspaceIds=2&typeIds=2
Before we start, check the auth guide.
Get all Workspaces
GET /rest/oboard/1.0/api/v1/workspaces – returns all the workspaces for the OKR board.
Request
GET https://jirainstanceurl/rest/oboard/1.0/api/v1/workspaces
Example
GET https://jirainstanceurl/rest/oboard/1.0/api/v1/workspaces
No parameters
Response
[ { "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 List of Intervals for a Workspace
GET /rest/oboard/1.0/api/v1/intervals – returns all intervals for a given workspace.
Request
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. |
Response
[ { "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 List of Groups
GET /rest/oboard/1.0/api/v1/groups – returns all groupIds for a given workspace.
Request
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
Response
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 List of Users from Workspace
GET /rest/oboard/1.0/api/v1/users – returns all users for a given workspace.
Request
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. |
Response
[ { "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" } ]
Objectives
Get a list of objectives DEPRECATED
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.
Request
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 a list of elements NEW
GET /rest/oboard/1.0/api/v1/elements – returns all objectives for a given workspace.
Request
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. workspaceId=111&workspaceId=222 |
groupIds [array] | No | Array of a group ids. |
userIds [array] | No | Array of a owner ids. |
typeIds [array] | Yes | Type of the objective 1 - Objective 4 - KR |
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. Max number is 100. Default is 50. |
startAt | No | Offset for the request. Default = 0. |
Create an objective
POST /rest/oboard/1.0/api/v1/objectives – create an objective.
Request
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 UPDATED | Yes | Type of the objective to create 1 - Objective 4 - KR |
levelId NEW | 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 |
Response
{ "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 }
Update Objective
PUT /rest/oboard/1.0/api/v1/objectives – update an objective.
If you want to delete non-required fields you need:
Put ““ for string values, and null for non-sting.
e.g. "description":"",
"ownerId":null
Request
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 UPDATED | Yes | Type of the objective to create 1 - Objective 4 - KR |
levelId NEW | 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 }
Remove Objective From Workspace
Delete /rest/oboard/1.0/api/v1/objectives – remove objective and all the nested items
Request
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. |
Response
Objective was successfully removed
Get Nested Items for an Objective DEPRECATED
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 Nested Items for an item NEW
Get /rest/oboard/1.0/api/v1/elements/nested – returns only the nested items for the given objective
Request
GET https://backend.okr-api.com/rest/oboard/1.0/api/v1/elements/nested?parentId={{objectiveid}}&workspaceIds={{workspaced}}
Example
GET https://backend.okr-api.com/rest/oboard/1.0/api/v1/elements/nested?parentId=2239&workspaceIds=222
Field | Required? | Description |
---|---|---|
parentId | Yes | Id of the objective to be deleted. |
workspaceId | Yes | The ID of the workspace where the objective is located. |
Key Results
Get a list of Key Results
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.
Request
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).
Response
[ { "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" } }]
Update Key Result
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
Request
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. 1 - Metric 2 - Percent 3 - Binary |
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 |
Create Key Result
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
Request
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. 1 - Metric 2 - Percent 3 - Binary |
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 |
Response
{ "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" }
Remove Objective From Workspace
Delete /rest/oboard/1.0/api/v1/key-results – remove objective and all the nested items
Request
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. |
Response
KeyResult was successfully removed