OGSM API

The API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Authentication

Authentication is done using the HTTP "Basic" schema. Admin accounts can setup the credentials through Settings -> API -> click on the cog icon. If you're missing this menu option contact our support team to enable the API for you.

Errors

Conventional HTTP response codes are used to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided, for example a missing required field. Codes in the 5xx range indicate an error with our servers.

Body formats

All body information you send needs to be encoded in JSON format. Don't forget to send the correct header with it:

Content-Type: application/json

Resources

The following resources are available through the API. Some of them only currently support read access. Let our support team know if you need to be able to create or update these resources so we can extend the API with it.

Objectives

The objective object looks like this:

{
  id: 123,
  title: "Objective title",
  labels: [{ name: "label 1" }, { name: "Label 2" }],
  description: "<p>Description</p>",
  assignee: { name: "Firstname Lastname" },
  ogsm_canvases: [{ id: 789, row_order: 91 }],
  archived: false
}

All API calls regarding objectives use this structure.

List all objectives

GET /api/v2/objectives.json

This will return an array of objective objects.

Goals

The goal object looks like this:

{
  id: 123,
  title: "Goal title",
  labels: [{ name: "label 1" }, { name: "Label 2" }],
  description: "<p>Description</p>",
  target_unit: "EUR",
  assignee: { name: "Firstname Lastname" },
  ogsm_canvases: [{ id: 789, row_order: 91 }],
  traffic_light: "red",
  archived: false,
  chart_vertical_min: null,
  aggregation_method: "sum",
  chart_type: "line"
}

All API calls regarding goals use this structure.

List all goals

GET /api/v2/goals.json

This will return an array of goal objects.

Goal measurements

The goal measurement object looks like this:

{
  id: 123,
  goal: {id: 456},
  at: "2024-01-01",
  current_value: 78.9,
  target_value: null,
  traffic_light: "green",
  show_in_ogsm: false,
  description: "Example"
}

All API calls regarding goal measurements use this structure.

List all goal measurements

GET /api/v2/goal_reports.json

This will return an array of goal measurement objects.

Create a measurement for a goal

POST /api/v2/goal_reports.json

{ "goal_report": { "goal": { "id": 123 }, "at": "2022-12-14", "current_value": 45.6 } }

Send a JSON encoded goal measurement object as the body to create the measurement. You can leave out the id, it will be generated by the system. When the creation is succesfull you'll receive the complete goal measurement object as response including the newly generated id.

For example to create a measurement with value 45.6 for the goal with id 123 you could use the following curl command:

curl -H "content-type: application/json" -d '{"goal_report": {"goal": {"id": 123}, "at": "2024-10-09", "current_value": 45.6}}' -u username:password https://yoursubdomain.ogsm.online/api/v2/goal_reports.json

Strategies

The strategy object looks like this:

{
  id: 123,
  title: "Strategy title",
  labels: [{ name: "label 1" }, { name: "Label 2" }],
  description: "<p>Description</p>",
  assignee: { name: "Firstname Lastname" },
  ogsm_canvases: [{ id: 789, row_order: 91 }],
  archived: false
}

All API calls regarding strategies use this structure.

List all strategies

GET /api/v2/strategies.json

This will return an array of strategy objects.

KPI

{
  id: 123,
  title: "KPI title",
  labels: [{ name: "label 1" }, { name: "Label 2" }],
  description: "<p>Description</p>",
  target_unit: "EUR",
  assignee: { name: "Firstname Lastname" },
  strategies: [{ id: 456 }],
  ogsm_canvases: [{ id: 789, row_order: 91 }],
  traffic_light: "red",
  archived: false,
  chart_vertical_min: null,
  aggregation_method: "sum",
  chart_type: "line"
}

List all KPIs

GET /api/v2/indicators.json

KPI measurements

{
  id: 123,
  indicator: {id: 456},
  at: "2024-01-01",
  current_value: 78.9,
  target_value: null,
  traffic_light: "green",
  show_in_ogsm: false,
  description: "Example"
}

List all KPI measurements

GET /api/v2/indicator_reports.json

Create a measurement for a KPI

POST /api/v2/indicator_reports.json


{ "indicator_report": { "indicator": { "id": 123 }, "at": "2022-12-14", "current_value": 45.6 } }

curl -H "content-type: application/json" -d '{"indicator_report": {"indicator": {"id": 123}, "at": "2024-10-09", "current_value": 45.6}}' -u username:password https://yoursubdomain.ogsm.online/api/v2/indicator_reports.json

Actions

The action object looks like this:

{
  id: 123,
  title: "Action title",
  labels: [{ name: "label 1" }, { name: "Label 2" }],
  strategies: [{ id: 456 }],
  description: "<p>Description</p>",
  assignee: { name: "Firstname Lastname" },
  involved: [{ name: "Another name" }],
  start: "2024-01-01", due: "2024-12-31",
  status: { name: "doing" },
  ogsm_canvases: [{ id: 789, row_order: 91 }],
  traffic_light: "green",
  progress: 50,
  archived: false
}

All API calls regarding actions use this structure.

List all actions

GET /api/v2/actions.json

This will return an array of action objects.