API Methods for OKR board
- 1 Get all Workspaces
- 2 Get List of Intervals for a Workspace
- 3 Get List of Groups
- 4 Get List of Levels
- 5 Get List of Users from Workspace
- 6 Objectives
- 7 Key Results
- 7.1 Get a list of Key Results
- 7.1.1 Request
- 7.2 Update Key Result
- 7.2.1 Request
- 7.3 Create Key Result
- 7.4 Remove Objective From Workspace
- 7.1 Get a list of Key Results
Before we start, check the auth guide.
Get all Workspaces
GET /api/v1/workspaces – returns all the workspaces for the OKR board.
Request
GET https://backend.okr-api.com/api/v1/workspaces
Example
GET https://backend.okr-api.com/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 /api/v1/intervals – returns all intervals for a given workspace.
Request
Example
Field | Required | Description |
---|---|---|
workspaceId | Yes | The if of workspace. |
Response
Get List of Groups
GET /api/v1/groups – returns all teams for a given workspace.
Request
Example
Field | Required | Description |
---|---|---|
workspaceId | Yes | The ID of workspace. |
includeServiceGroups | No | Use includeServiceGroups = true if you need to get an id for “no group“ entity. |
Response
Get List of Levels
GET /api/v1/levels – returns all levels for a given workspace.
Request
Example
Field | Required | Description |
---|---|---|
workspaceId | Yes | The ID of workspace. |
Response
Get List of Users from Workspace
GET /api/v1/users – returns all users for a given workspace.
Request
Example
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
Objectives
Get a list of objectives deprecated
Please use /api/v1/elements below
GET /api/v1/objectives – returns all objectives for a given workspace.
Request
Example
Get a list of elements New
GET /api/v1/elements – returns all objectives for a given workspace.
Request
Example
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 /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. |
Create an objective
POST /api/v1/objectives – create an objective.
Request
Example
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 Jun 10, 2021 Updated | Yes | Type of the objective to create |
levelId | Yes | Type of the OKR GET /api/v1/levels |
parentObjectiveId | No | Put here 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
Update Objective
PUT /api/v1/objectives – update an objective.
If the parameter is NOT SET in the body, then it will be set to NULL
Request
Example
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 Jun 10, 2021 Updated | Yes | Type of the objective to create |
levelId | Yes | Type of the OKR GET /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
Remove Objective From Workspace
Delete /api/v1/objectives – remove objective and all the nested items
Request
Example
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
Get Nested Items for an Objective deprecated
Get /api/v1/objectives/children – returns only the nested items for the given objective
Please use /api/v1/elements/nested
Request
Example
Field | Required? | Description |
---|---|---|
objectiveId | Yes | Id of the objective to be deleted. |
workspaceId | Yes | The ID of the workspace where the objective is located. |
Get Nested Items for an item new
Get /api/v2/elements/nested – returns only the nested items for the given objective
Request
Example
Field | Required? | Description |
---|---|---|
parentId | Yes | Id of the objective to be deleted. |
workspaceId | Yes | The ID of the workspace where the objective is located. |
searchType | Yes | 1 - First-level nested items, 2- Full structure |
intervalIds | Yes | Id of an interval |
Key Results
Get a list of Key Results
GET /api/v1/objectives – returns all objectives for a given workspace.
Request
Example
Fields are the same as for getting objective (above).
Update Key Result
PUT /api/v1/key-results – update key result
Request
Example
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 | Owner of the KR |
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 |
Create Key Result
POST
/api/v1/key-results – update key result
Request
Example
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 |
Response
Remove Objective From Workspace
Delete /api/v1/key-results – remove objective and all the nested items
Request
Example
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. |