OGSM API

The API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-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.

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.

Create an action

POST /api/v2/actions.json

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

Update an action

PATCH /api/v2/actions/<id>.json

Send a JSON encoded action object as the body to update the action. You can leave out the fields you're not modifying. When the update is succesfull you'll receive the complete action object as response including the newly changed fields.

Delete an action

DELETE /api/v2/actions/<id>.json

This request doesn't need a body. The deleted action is returned as a JSON object.