API Reference

Complete documentation of all Northly REST API endpoints.

Base URL: https://api.northlyapp.com/v1

Objectives

Create, read, update, and delete Objectives.

GET/objectives

developers.apiRef.endpoints.objectives.list

Query Parameters

Name	Type	Required	Description
`page`	integer	No	Page number for pagination, default: 1.
`per_page`	integer	No	Items per page, default: 25, max: 100.
`cycle_id`	string	No	Filter by OKR cycle.
`team_id`	string	No	Filter by team.

pageinteger

Page number for pagination, default: 1.

per_pageinteger

Items per page, default: 25, max: 100.

cycle_idstring

Filter by OKR cycle.

team_idstring

Filter by team.

Example Request

bash

curl -X GET "https://api.northlyapp.com/v1/objectives?page=1&per_page=25" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Example Response

json

{
  "data": [
    {
      "id": "obj_abc123",
      "title": "Increase customer retention",
      "description": "Focus on reducing churn...",
      "owner_id": "usr_xyz",
      "cycle_id": "cyc_q1_2026",
      "team_id": "team_product",
      "progress": 0.65,
      "status": "on_track",
      "created_at": "2026-01-15T10:00:00Z",
      "updated_at": "2026-03-01T14:30:00Z"
    }
  ],
  "meta": { "page": 1, "per_page": 25, "total": 42 }
}

GET/objectives/:id

developers.apiRef.endpoints.objectives.get

Example Request

bash

curl -X GET "https://api.northlyapp.com/v1/objectives/obj_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Example Response

json

{
  "data": {
    "id": "obj_abc123",
    "title": "Increase customer retention",
    "description": "Focus on reducing churn...",
    "owner_id": "usr_xyz",
    "cycle_id": "cyc_q1_2026",
    "team_id": "team_product",
    "progress": 0.65,
    "status": "on_track",
    "key_results": [
      {
        "id": "kr_001",
        "title": "Reduce monthly churn to < 2%",
        "current_value": 2.3,
        "target_value": 2.0,
        "progress": 0.7
      }
    ],
    "created_at": "2026-01-15T10:00:00Z",
    "updated_at": "2026-03-01T14:30:00Z"
  }
}

POST/objectives

developers.apiRef.endpoints.objectives.create

Request Body

Name	Type	Required	Description
`title`	string	Yes	Title of the objective.
`description`	string	No	Description of the objective.
`cycle_id`	string	Yes	ID of the OKR cycle.
`team_id`	string	No	ID of the team.
`owner_id`	string	No	ID of the responsible user.

titlestringRequired

Title of the objective.

descriptionstring

Description of the objective.

cycle_idstringRequired

ID of the OKR cycle.

team_idstring

ID of the team.

owner_idstring

ID of the responsible user.

Example Request

bash

curl -X POST "https://api.northlyapp.com/v1/objectives" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Launch developer platform",
    "description": "Build and ship public API...",
    "cycle_id": "cyc_q2_2026",
    "owner_id": "usr_xyz"
  }'

Example Response

json

{
  "data": {
    "id": "obj_new456",
    "title": "Launch developer platform",
    "description": "Build and ship public API...",
    "owner_id": "usr_xyz",
    "cycle_id": "cyc_q2_2026",
    "progress": 0,
    "status": "not_started",
    "created_at": "2026-03-09T12:00:00Z",
    "updated_at": "2026-03-09T12:00:00Z"
  }
}

PUT/objectives/:id

developers.apiRef.endpoints.objectives.update

Request Body

Name	Type	Required	Description
`title`	string	No	Title of the objective.
`description`	string	No	Description of the objective.
`status`	string	No	Status: not_started, on_track, at_risk, behind, completed.
`owner_id`	string	No	ID of the responsible user.

titlestring

Title of the objective.

descriptionstring

Description of the objective.

statusstring

Status: not_started, on_track, at_risk, behind, completed.

owner_idstring

ID of the responsible user.

Example Request

bash

curl -X PUT "https://api.northlyapp.com/v1/objectives/obj_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Increase customer retention (updated)",
    "status": "at_risk"
  }'

Example Response

json

{
  "data": {
    "id": "obj_abc123",
    "title": "Increase customer retention (updated)",
    "status": "at_risk",
    "updated_at": "2026-03-09T15:00:00Z"
  }
}

DELETE/objectives/:id

developers.apiRef.endpoints.objectives.delete

Example Request

bash

curl -X DELETE "https://api.northlyapp.com/v1/objectives/obj_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

json

{
  "data": {
    "id": "obj_abc123",
    "deleted": true
  }
}

Key Results

Manage Key Results within Objectives.

GET/objectives/:id/key-results

developers.apiRef.endpoints.keyResults.list

Query Parameters

Name	Type	Required	Description
`page`	integer	No	Page number for pagination, default: 1.
`per_page`	integer	No	Items per page, default: 25, max: 100.

pageinteger

Page number for pagination, default: 1.

per_pageinteger

Items per page, default: 25, max: 100.

Example Request

bash

curl -X GET "https://api.northlyapp.com/v1/objectives/obj_abc123/key-results" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

json

{
  "data": [
    {
      "id": "kr_001",
      "objective_id": "obj_abc123",
      "title": "Reduce monthly churn to < 2%",
      "metric_type": "percentage",
      "start_value": 4.5,
      "current_value": 2.3,
      "target_value": 2.0,
      "progress": 0.88,
      "owner_id": "usr_xyz",
      "created_at": "2026-01-15T10:00:00Z"
    }
  ],
  "meta": { "page": 1, "per_page": 25, "total": 3 }
}

GET/objectives/:id/key-results/:krId

developers.apiRef.endpoints.keyResults.get

Example Request

bash

curl -X GET "https://api.northlyapp.com/v1/objectives/obj_abc123/key-results/kr_001" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

json

{
  "data": {
    "id": "kr_001",
    "objective_id": "obj_abc123",
    "title": "Reduce monthly churn to < 2%",
    "metric_type": "percentage",
    "start_value": 4.5,
    "current_value": 2.3,
    "target_value": 2.0,
    "progress": 0.88,
    "owner_id": "usr_xyz",
    "check_ins": [
      { "id": "ci_01", "value": 3.1, "note": "Improved onboarding flow", "created_at": "2026-02-01T09:00:00Z" }
    ]
  }
}

POST/objectives/:id/key-results

developers.apiRef.endpoints.keyResults.create

Request Body

Name	Type	Required	Description
`title`	string	Yes	Title of the key result.
`metric_type`	string	Yes	Metric type: number, percentage, currency, boolean.
`start_value`	number	Yes	Starting value of the metric.
`target_value`	number	Yes	Target value of the metric.
`owner_id`	string	No	ID of the responsible user.

titlestringRequired

Title of the key result.

metric_typestringRequired

Metric type: number, percentage, currency, boolean.

start_valuenumberRequired

Starting value of the metric.

target_valuenumberRequired

Target value of the metric.

owner_idstring

ID of the responsible user.

Example Request

bash

curl -X POST "https://api.northlyapp.com/v1/objectives/obj_abc123/key-results" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Increase NPS from 30 to 50",
    "metric_type": "number",
    "start_value": 30,
    "target_value": 50
  }'

Example Response

json

{
  "data": {
    "id": "kr_new789",
    "objective_id": "obj_abc123",
    "title": "Increase NPS from 30 to 50",
    "metric_type": "number",
    "start_value": 30,
    "current_value": 30,
    "target_value": 50,
    "progress": 0,
    "created_at": "2026-03-09T12:00:00Z"
  }
}

PUT/objectives/:id/key-results/:krId

developers.apiRef.endpoints.keyResults.update

Request Body

Name	Type	Required	Description
`title`	string	No	Title of the key result.
`current_value`	number	No	Current value of the metric.
`target_value`	number	No	Target value of the metric.

titlestring

Title of the key result.

current_valuenumber

Current value of the metric.

target_valuenumber

Target value of the metric.

Example Request

bash

curl -X PUT "https://api.northlyapp.com/v1/objectives/obj_abc123/key-results/kr_001" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "current_value": 2.1 }'

Example Response

json

{
  "data": {
    "id": "kr_001",
    "title": "Reduce monthly churn to < 2%",
    "current_value": 2.1,
    "progress": 0.96,
    "updated_at": "2026-03-09T15:00:00Z"
  }
}

DELETE/objectives/:id/key-results/:krId

developers.apiRef.endpoints.keyResults.delete

Example Request

bash

curl -X DELETE "https://api.northlyapp.com/v1/objectives/obj_abc123/key-results/kr_001" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

json

{
  "data": {
    "id": "kr_001",
    "deleted": true
  }
}

Check-ins

Record and manage progress updates for Key Results.

GET/key-results/:id/check-ins

developers.apiRef.endpoints.checkIns.list

Query Parameters

Name	Type	Required	Description
`page`	integer	No	Page number for pagination, default: 1.
`per_page`	integer	No	Items per page, default: 25, max: 100.

pageinteger

Page number for pagination, default: 1.

per_pageinteger

Items per page, default: 25, max: 100.

Example Request

bash

curl -X GET "https://api.northlyapp.com/v1/key-results/kr_001/check-ins" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

json

{
  "data": [
    {
      "id": "ci_01",
      "key_result_id": "kr_001",
      "value": 2.3,
      "note": "Improved onboarding reduced churn significantly",
      "author_id": "usr_xyz",
      "created_at": "2026-03-01T09:00:00Z"
    }
  ],
  "meta": { "page": 1, "per_page": 25, "total": 8 }
}

POST/key-results/:id/check-ins

developers.apiRef.endpoints.checkIns.create

Request Body

Name	Type	Required	Description
`value`	number	Yes	Current metric value at the time of the check-in.
`note`	string	No	Optional note for the check-in.

valuenumberRequired

Current metric value at the time of the check-in.

notestring

Optional note for the check-in.

Example Request

bash

curl -X POST "https://api.northlyapp.com/v1/key-results/kr_001/check-ins" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "value": 2.1,
    "note": "New retention campaign launched"
  }'

Example Response

json

{
  "data": {
    "id": "ci_09",
    "key_result_id": "kr_001",
    "value": 2.1,
    "note": "New retention campaign launched",
    "author_id": "usr_xyz",
    "created_at": "2026-03-09T12:00:00Z"
  }
}

PUT/key-results/:id/check-ins/:checkInId

developers.apiRef.endpoints.checkIns.update

Request Body

Name	Type	Required	Description
`value`	number	No	Current metric value at the time of the check-in.
`note`	string	No	Optional note for the check-in.

valuenumber

Current metric value at the time of the check-in.

notestring

Optional note for the check-in.

Example Request

bash

curl -X PUT "https://api.northlyapp.com/v1/key-results/kr_001/check-ins/ci_09" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "value": 2.0,
    "note": "Updated: target reached!"
  }'

Example Response

json

{
  "data": {
    "id": "ci_09",
    "value": 2.0,
    "note": "Updated: target reached!",
    "updated_at": "2026-03-09T15:00:00Z"
  }
}

Cycles

Manage OKR cycles, e.g. quarters.

GET/cycles

developers.apiRef.endpoints.cycles.list

Query Parameters

Name	Type	Required	Description
`page`	integer	No	Page number for pagination, default: 1.
`per_page`	integer	No	Items per page, default: 25, max: 100.
`status`	string	No	Filter by cycle status: active, planned, completed.

pageinteger

Page number for pagination, default: 1.

per_pageinteger

Items per page, default: 25, max: 100.

statusstring

Filter by cycle status: active, planned, completed.

Example Request

bash

curl -X GET "https://api.northlyapp.com/v1/cycles?status=active" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

json

{
  "data": [
    {
      "id": "cyc_q1_2026",
      "name": "Q1 2026",
      "starts_at": "2026-01-01T00:00:00Z",
      "ends_at": "2026-03-31T23:59:59Z",
      "status": "active",
      "objectives_count": 12,
      "overall_progress": 0.58
    }
  ],
  "meta": { "page": 1, "per_page": 25, "total": 4 }
}

GET/cycles/:id

developers.apiRef.endpoints.cycles.get

Example Request

bash

curl -X GET "https://api.northlyapp.com/v1/cycles/cyc_q1_2026" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

json

{
  "data": {
    "id": "cyc_q1_2026",
    "name": "Q1 2026",
    "starts_at": "2026-01-01T00:00:00Z",
    "ends_at": "2026-03-31T23:59:59Z",
    "status": "active",
    "objectives_count": 12,
    "overall_progress": 0.58
  }
}

POST/cycles

developers.apiRef.endpoints.cycles.create

Request Body

Name	Type	Required	Description
`name`	string	Yes	Name of the cycle, e.g. Q2 2026.
`starts_at`	string	Yes	Start date of the cycle in ISO 8601.
`ends_at`	string	Yes	End date of the cycle in ISO 8601.

namestringRequired

Name of the cycle, e.g. Q2 2026.

starts_atstringRequired

Start date of the cycle in ISO 8601.

ends_atstringRequired

End date of the cycle in ISO 8601.

Example Request

bash

curl -X POST "https://api.northlyapp.com/v1/cycles" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q2 2026",
    "starts_at": "2026-04-01T00:00:00Z",
    "ends_at": "2026-06-30T23:59:59Z"
  }'

Example Response

json

{
  "data": {
    "id": "cyc_q2_2026",
    "name": "Q2 2026",
    "starts_at": "2026-04-01T00:00:00Z",
    "ends_at": "2026-06-30T23:59:59Z",
    "status": "planned",
    "objectives_count": 0,
    "overall_progress": 0
  }
}

PUT/cycles/:id

developers.apiRef.endpoints.cycles.update

Request Body

Name	Type	Required	Description
`name`	string	No	Name of the cycle, e.g. Q2 2026.
`starts_at`	string	No	Start date of the cycle in ISO 8601.
`ends_at`	string	No	End date of the cycle in ISO 8601.

namestring

Name of the cycle, e.g. Q2 2026.

starts_atstring

Start date of the cycle in ISO 8601.

ends_atstring

End date of the cycle in ISO 8601.

Example Request

bash

curl -X PUT "https://api.northlyapp.com/v1/cycles/cyc_q2_2026" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Q2 2026 (Extended)", "ends_at": "2026-07-15T23:59:59Z" }'

Example Response

json

{
  "data": {
    "id": "cyc_q2_2026",
    "name": "Q2 2026 (Extended)",
    "ends_at": "2026-07-15T23:59:59Z",
    "updated_at": "2026-03-09T15:00:00Z"
  }
}

Teams

Read team information and team objectives.

GET/teams

developers.apiRef.endpoints.teams.list

Query Parameters

Name	Type	Required	Description
`page`	integer	No	Page number for pagination, default: 1.
`per_page`	integer	No	Items per page, default: 25, max: 100.

pageinteger

Page number for pagination, default: 1.

per_pageinteger

Items per page, default: 25, max: 100.

Example Request

bash

curl -X GET "https://api.northlyapp.com/v1/teams" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

json

{
  "data": [
    {
      "id": "team_product",
      "name": "Product Team",
      "members_count": 8,
      "objectives_count": 4,
      "created_at": "2025-10-01T10:00:00Z"
    }
  ],
  "meta": { "page": 1, "per_page": 25, "total": 5 }
}

GET/teams/:id

developers.apiRef.endpoints.teams.get

Example Request

bash

curl -X GET "https://api.northlyapp.com/v1/teams/team_product" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

json

{
  "data": {
    "id": "team_product",
    "name": "Product Team",
    "members": [
      { "id": "usr_xyz", "name": "Anna Schmidt", "role": "lead" }
    ],
    "members_count": 8,
    "objectives_count": 4,
    "created_at": "2025-10-01T10:00:00Z"
  }
}

GET/teams/:id/objectives

developers.apiRef.endpoints.teams.objectives

Query Parameters

Name	Type	Required	Description
`cycle_id`	string	No	Filter by OKR cycle.

cycle_idstring

Filter by OKR cycle.

Example Request

bash

curl -X GET "https://api.northlyapp.com/v1/teams/team_product/objectives?cycle_id=cyc_q1_2026" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

json

{
  "data": [
    {
      "id": "obj_abc123",
      "title": "Increase customer retention",
      "progress": 0.65,
      "status": "on_track"
    }
  ],
  "meta": { "page": 1, "per_page": 25, "total": 4 }
}

Users

Retrieve user information.

GET/users/me

developers.apiRef.endpoints.users.me

Example Request

bash

curl -X GET "https://api.northlyapp.com/v1/users/me" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

json

{
  "data": {
    "id": "usr_xyz",
    "name": "Anna Schmidt",
    "email": "anna@example.com",
    "role": "admin",
    "teams": ["team_product", "team_engineering"],
    "created_at": "2025-08-01T10:00:00Z"
  }
}

GET/users

developers.apiRef.endpoints.users.list

Query Parameters

Name	Type	Required	Description
`page`	integer	No	Page number for pagination, default: 1.
`per_page`	integer	No	Items per page, default: 25, max: 100.
`team_id`	string	No	Filter by team.

pageinteger

Page number for pagination, default: 1.

per_pageinteger

Items per page, default: 25, max: 100.

team_idstring

Filter by team.

Example Request

bash

curl -X GET "https://api.northlyapp.com/v1/users?team_id=team_product" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

json

{
  "data": [
    {
      "id": "usr_xyz",
      "name": "Anna Schmidt",
      "email": "anna@example.com",
      "role": "admin"
    }
  ],
  "meta": { "page": 1, "per_page": 25, "total": 15 }
}

Alignments

Manage objective dependencies and alignments.

GET/alignments

developers.apiRef.endpoints.alignments.list

Query Parameters

Name	Type	Required	Description
`objective_id`	string	No	Filter by objective ID.

objective_idstring

Filter by objective ID.

Example Request

bash

curl -X GET "https://api.northlyapp.com/v1/alignments?objective_id=obj_company_01" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

json

{
  "data": [
    {
      "id": "align_001",
      "parent_objective_id": "obj_company_01",
      "child_objective_id": "obj_abc123",
      "alignment_type": "supports",
      "created_at": "2026-01-15T10:00:00Z"
    }
  ],
  "meta": { "page": 1, "per_page": 25, "total": 6 }
}

POST/alignments

developers.apiRef.endpoints.alignments.create

Request Body

Name	Type	Required	Description
`parent_objective_id`	string	Yes	ID of the parent objective.
`child_objective_id`	string	Yes	ID of the child objective.
`alignment_type`	string	No	Alignment type: supports, contributes_to.

parent_objective_idstringRequired

ID of the parent objective.

child_objective_idstringRequired

ID of the child objective.

alignment_typestring

Alignment type: supports, contributes_to.

Example Request

bash

curl -X POST "https://api.northlyapp.com/v1/alignments" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "parent_objective_id": "obj_company_01",
    "child_objective_id": "obj_team_05"
  }'

Example Response

json

{
  "data": {
    "id": "align_new002",
    "parent_objective_id": "obj_company_01",
    "child_objective_id": "obj_team_05",
    "alignment_type": "supports",
    "created_at": "2026-03-09T12:00:00Z"
  }
}

Webhooks

Create and manage webhook subscriptions.

GET/webhooks

developers.apiRef.endpoints.webhooks.list

Example Request

bash

curl -X GET "https://api.northlyapp.com/v1/webhooks" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

json

{
  "data": [
    {
      "id": "wh_001",
      "url": "https://example.com/webhooks/northly",
      "events": ["objective.updated", "check_in.created"],
      "active": true,
      "created_at": "2026-02-01T10:00:00Z"
    }
  ],
  "meta": { "page": 1, "per_page": 25, "total": 2 }
}

POST/webhooks

developers.apiRef.endpoints.webhooks.create

Request Body

Name	Type	Required	Description
`url`	string	Yes	URL to receive webhook events.
`events`	string[]	Yes	Array of event types to subscribe to.
`secret`	string	No	Optional secret key for signature verification.

urlstringRequired

URL to receive webhook events.

eventsstring[]Required

Array of event types to subscribe to.

secretstring

Optional secret key for signature verification.

Example Request

bash

curl -X POST "https://api.northlyapp.com/v1/webhooks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/northly",
    "events": ["objective.updated", "check_in.created"]
  }'

Example Response

json

{
  "data": {
    "id": "wh_new003",
    "url": "https://example.com/webhooks/northly",
    "events": ["objective.updated", "check_in.created"],
    "active": true,
    "secret": "whsec_...",
    "created_at": "2026-03-09T12:00:00Z"
  }
}

DELETE/webhooks/:id

developers.apiRef.endpoints.webhooks.delete

Example Request

bash

curl -X DELETE "https://api.northlyapp.com/v1/webhooks/wh_001" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

json

{
  "data": {
    "id": "wh_001",
    "deleted": true
  }
}

Ready to close the gap between strategy and results?

Start free with Northly — the Outcome OS that combines AI coaching, Strategy Maps, and contextual check-ins. No credit card. No compliance headache.