North provides a RESTful API for developers to use. This document covers the
available API authentication and various endpoints.
Contents
Authentication
Before you can use the API, you will first need to get an auth token. In order to do so,
- Click on your profile name on the bottom left, then click API in the
floating menu. - On the API screen, you will need to create a token. Provide a token name
(any name that helps you recognize it later), select the applicable scopes, and click Create. - This creates a new token that will be displayed on screen. Please copy the
token and keep it safe as it is shown only once.
The screenshots below indicate where you can find these screens.
Endpoints
The base endpoint for all North APIs is https://to.thenorth.io/
Scope: Basic
Current user info
- URL: /api/user/
- Method: GET
Returns information about the current user.
Example request:
GET /api/user/ HTTP/1.1
Authorization: Bearer $TOKEN
Host: to.thenorth.io
Example response:
HTTP/1.1 200 OK
content-type: application/json
{
"first_name": "Alyssa",
"has_saved_profile": true,
"id": 2,
"last_name": "P Hacker",
"otype": "user",
"photo_id": "17b894a8-75de-4a44-9fe9-54e6ff3cefd5",
"referral_details": "",
"referral_sources": [],
"work_function": "Developer",
"work_level": "Executive"
}
Other user public info
- URL: /api/users/$user_id/
- Method: GET
Returns information about another user. The user_id
should be a numeric id of
the other user — this will be made available by other APIs (e.g. team
membership related APIs).
Example request:
GET /api/users/3/ HTTP/1.1
Authorization: Bearer $TOKEN
Host: to.thenorth.io
Example response:
HTTP/1.1 200 OK
content-type: application/json
{
"first_name": "Ben",
"id": 3,
"last_name": "Bitdiddle",
"otype": "user",
"photo_id": "3a834388-d4b2-42ff-9065-1952d31e67c3"
}
Scope: Org management
List user organizations
- URL: /api/orgs/
- Method: GET
Returns a list of organizations that a user belongs to.
Example request:
GET /api/orgs/ HTTP/1.1
Authorization: Bearer $TOKEN
Host: to.thenorth.io
Example response:
HTTP/1.1 200 OK
content-type: application/json
[
{
"demo_org_expires_on": null,
"description": "",
"estimated_size": "",
"external_object_providers": [],
"id": 1,
"is_billed_offline": false,
"is_demo_org": false,
"name": "ACME",
"root_team_id": 1,
"tzname": "UTC"
}
]
Organization details
- URL: /api/orgs/$org_id/
- Method: GET
Returns details for a single organization. The id
in the URL should be the
numeric id of the organization present in the id
field.
Example request:
GET /api/orgs/1/ HTTP/1.1
Authorization: Bearer $TOKEN
Host: to.thenorth.io
Example response:
HTTP/1.1 200 OK
content-type: application/json
{
"demo_org_expires_on": null,
"description": "",
"estimated_size": "",
"external_object_providers": [],
"feature_summary": {
"allow_tasks": true
},
"id": 1,
"is_billed_offline": false,
"is_demo_org": false,
"name": "ACME",
"root_team_id": 1,
"tzname": "UTC"
}
List teams in an organizations
- URL: /api/orgs/$org_id/teams/
- Method: GET
Lists the teams in an organization. org_id
should be the numeric id of an
organization.
Example request:
GET /api/orgs/1/teams/ HTTP/1.1
Authorization: Bearer $TOKEN
Host: to.thenorth.io
Example response:
HTTP/1.1 200 OK
content-type: application/json
[
{
"archived_at": null,
"archiver_id": null,
"created_at": "2023-12-10T19:55:16.760775Z",
"id": 1,
"is_archived": false,
"is_explicitly_archived": false,
"is_org_like": true,
"is_private": false,
"name": "ACME",
"organization_id": 1,
"parent_id": null,
"updated_at": "2024-01-08T08:42:39.193352Z"
},
{
"archived_at": null,
"archiver_id": null,
"created_at": "2023-12-10T19:55:16.847385Z",
"id": 4,
"is_archived": false,
"is_explicitly_archived": false,
"is_org_like": false,
"is_private": false,
"name": "Design",
"organization_id": 1,
"parent_id": 1,
"updated_at": "2024-01-08T08:43:49.155647Z"
},
{
"archived_at": null,
"archiver_id": null,
"created_at": "2023-12-10T19:55:16.829584Z",
"id": 3,
"is_archived": false,
"is_explicitly_archived": false,
"is_org_like": false,
"is_private": false,
"name": "Engineering",
"organization_id": 1,
"parent_id": 1,
"updated_at": "2024-01-08T08:43:31.757663Z"
},
{
"archived_at": null,
"archiver_id": null,
"created_at": "2023-12-10T19:55:16.865006Z",
"id": 5,
"is_archived": false,
"is_explicitly_archived": false,
"is_org_like": false,
"is_private": false,
"name": "HR",
"organization_id": 1,
"parent_id": 1,
"updated_at": "2024-01-08T08:43:11.626079Z"
}
]
Details about a single team
- URL: /api/orgs/$org_id/teams/$team_id/
- Method: GET
Returns details about a single team. org_id
should be the numeric id of the
organization and $id
should be the numeric id of the team.
Notice that parent_id
field in a team. This field will be null
for one and
only team in an organization – the root team which encompasses all the org
members. This is the team with which all org level goals, KRs and initiatives are
associated. The root team id is also returned by the org detail API in theroot_team_id
field.
Every other team will have its parent_id
set to a numeric field. Most of the
time this will be the id of the root team.
Example request:
GET /api/orgs/1/teams/3/ HTTP/1.1
Authorization: Bearer $TOKEN
Host: to.thenorth.io
Example response:
HTTP/1.1 200 OK
content-type: application/json
{
"archived_at": null,
"archiver_id": null,
"created_at": "2023-12-10T19:55:16.829584Z",
"id": 3,
"is_archived": false,
"is_explicitly_archived": false,
"is_org_like": false,
"is_private": false,
"name": "Engineering",
"organization_id": 1,
"parent_id": 1,
"updated_at": "2024-01-08T08:43:31.757663Z"
}
List team memberships
- URL: /api/orgs/$org_id/teams/$team_id/memberships/
- Method: GET
Returns a list of team memberships. Each membership object contains three
fields:
type
— the type of membership. Can be one ofowner
,regular
,guest
orguest-no-access
.user_id
— id of the user who’s member of the teamuser
— an object containing more details about a user. Note that this will
return additional information as compared to the other user public info
endpoint.
Example request:
GET /api/orgs/1/teams/3/memberships/ HTTP/1.1
Authorization: Bearer $TOKEN
Connection: keep-alive
Host: to.thenorth.io
Example response:
HTTP/1.1 200 OK
content-type: application/json
[
{
"type": "owner",
"user": {
"email": "eva@example.com",
"first_name": "Eva",
"id": 5,
"last_login": null,
"last_name": "lu Ator",
"otype": "user",
"photo_id": "cfd6f1d6-f8a1-485b-9f09-2d3670f04eba",
"work_function": "Developer",
"work_level": "Executive"
},
"user_id": 5
},
{
"type": "regular",
"user": {
"email": "cy@example.com",
"first_name": "Cy",
"id": 4,
"last_login": null,
"last_name": "D Fect",
"otype": "user",
"photo_id": "1b04fde2-5d20-4d41-bd89-d5535248c728",
"work_function": "Developer",
"work_level": "Executive"
},
"user_id": 4
},
{
"type": "owner",
"user": {
"email": "alyssa@example.com",
"first_name": "Alyssa",
"id": 2,
"last_login": "2024-01-07T03:07:01.454153Z",
"last_name": "P Hacker",
"otype": "user",
"photo_id": "17b894a8-75de-4a44-9fe9-54e6ff3cefd5",
"work_function": "Developer",
"work_level": "Executive"
},
"user_id": 2
}
]
Return about a single membership
- URL: /api/orgs/$org_id/teams/$team_id/memberships/$user_id/
- Method: GET
Returns detail about a single membership. user_id
should be the numeric id of
the user.
Example request:
GET /api/orgs/1/teams/3/memberships/4/ HTTP/1.1
Authorization: Bearer $TOKEN
Host: to.thenorth.io
Example response:
HTTP/1.1 200 OK
content-type: application/json
{
"type": "regular",
"user": {
"email": "cy@example.com",
"first_name": "cy",
"id": 4,
"last_login": null,
"last_name": "d fect",
"otype": "user",
"photo_id": "1b04fde2-5d20-4d41-bd89-d5535248c728",
"work_function": "Developer",
"work_level": "Executive"
},
"user_id": 4
}
Update a single membership
- URL: /api/orgs/$org_id/teams/$team_id/memberships/$user_id/
- Method: PATCH
Can be used to update the membership type of a single membership.
Example request:
PATCH /api/orgs/1/teams/3/memberships/4/ HTTP/1.1
Authorization: Bearer $TOKEN
Content-Type: application/json
Content-Length: 17
Host: to.thenorth.io
{
"type": "owner"
}
Example response:
HTTP/1.1 200 OK
content-length: 244
content-type: application/json
{
"type": "owner",
"user": {
"email": "cy@example.com",
"first_name": "Cy",
"id": 4,
"last_login": null,
"last_name": "D Fect",
"otype": "user",
"photo_id": "1b04fde2-5d20-4d41-bd89-d5535248c728",
"work_function": "Developer",
"work_level": "Executive"
},
"user_id": 4
}
Delete a single membership
- URL: /api/orgs/$org_id/teams/$team_id/memberships/$user_id/
- Method: PATCH
Can be used to delete a single membership.
Note: if a user is deleted from the root team they will be deleted from all
other teams in an organization.
Example request:
DELETE /api/orgs/1/teams/3/memberships/4/ HTTP/1.1
Authorization: Bearer $TOKEN
Host: to.thenorth.io
Example response:
HTTP/1.1 204 No Content
content-length: 0
Scope: OKRs and initiatives
List of goals
- URL: /api/orgs/$org_id/goals/
- Method: GET
List goals visible to a user in an organization.
Query params available to filter out goals:
team_id
– id of the team to which the returned goals belongowner_id
– given user is either an owner or co-owner of goals or KRsprimary_owner_id
– given user is the primary owner or goals or KRsgoal_owner_id
– given user is either an owner or co-owner of goalsprimary_goal_owner_id
– given user is the primary owner of goalskr_owner_id
– given user is either an owner or co-owner of KRsprimary_kr_owner_id
– given user is the primary owner of KRsis_archived
– whether the goals returned are archived or not (value can be eithertrue
orfalse
).parent_id
– id of the goal to which returned goals are aligned
Goal details
- URL: /api/orgs/$org_id/goals/$goal_id/
- Method: GET
Returns details about a single goal.
Goal events
- URL: /api/orgs/$org_id/goals/$goal_id/events/
- Method: GET
Returns an array of all events related to a goal.
List of KRs
- URL: /api/orgs/$org_id/key_results/
- Method: GET
List KRs visible to a user in an organization.
Query params available to filter out KRs:
team_id
– id of the team to which the returned KRs belongowner_id
– given user is either an owner or co-owner of goals or KRsprimary_owner_id
– given user is the primary owner or goals or KRsstatus
– status of the returned KRs. Can be one ofon-track
,behind
orat-risk
.is_archived
– whether the KRs returned are archived or not (value can be eithertrue
orfalse
).
KR details
- URL: /api/orgs/$org_id/key_results/$kr_id/
- Method: GET
Returns details about a single KR.
KR events
- URL: /api/orgs/$org_id/key_results/$kr_id/events/
- Method: GET
Returns an array of events related to a single KR.
List of initiatives
- URL: /api/orgs/$org_id/initiatives/
- Method: GET
List initiatives visible to a user in an organization.
Query params available to filter out initiatives:
team_id
– id of the team to which initiatives belongowner_id
– given user is an owner or co-owner of initiativesstatus
– status of the returned initiatives. Can be one ofnot-started
,on-track
,behind
,at-risk
ordone
.is_archived
– whether the initiative is archived or notis_closed
– whether the initiative is closed or notnql
– for advanced filtering needs, one can provide NQL in this query param
Initiative details
- URL: /api/orgs/$org_id/initiatives/$initiative_id/
- Method: GET
Returns details about a single initiative.
Initiative events
- URL: /api/orgs/$org_id/initiatives/$initiative_id/events/
- Method: GET
Returns an array of events about a single initiative.