Calling the Board APIs

To collaborate on projects Board allows users to work visually by sharing Ideas and to communicate with each other in real-time in a single place.

Using Klaxoon API you can build integrations that enable data exchange between a Board and an external application.

Full details on the Board API endpoints can be found on the API Reference.

To use Board APIs in your app you need to :

• Register your application. See the Create an App section
• Implement OAuth 2 authorization protocol for a Klaxoon users to authorize your application to read or write on their Boards.

Understand users permissions on Board

A Klaxoon user with access to a Board can be either Host or Participant.

Host:

• Add and modify Ideas on the Board
• Add and modify Board Colors, Board Categories and Board Dimension
• Set participants rights to one of the following mode

Participant :

• Add and modify Ideas on the Board or add Ideas to the Board Inbox depending on the Board settings.

📘

These permissions are not set via API but apply when you are using the Board APIs.

Board

Board is the parent item. It's the space where all types of content can be visually organized.

The API allows to :

• Create a new Board
• Get the list of Boards available
• Retrieve a specific Board

{
  "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "title": "My board",
  "description": "This is my first board",
  "accessCode": "ABCDEF",
  "state": "draft",
  "author": {
    "id": "string"
  },
  "createdAt": "2023-02-20T16:51:14.482Z",
  "updatedAt": "2023-02-20T16:51:14.482Z"
}

Board Idea

Using the Board API you can add, retrieve and modify the Ideas of a Board. An Idea has a position, a content, a color and can associated with a Category and a dimension.

Position and Board Inbox:

A Board Idea can de added into at a specific position.

• If the position is not specified the Idea will be place at position 0,0.
• If the position is set to null the Idea will be place into the Board Inbox.

The x and y coordinates position the top left corner of an idea on the Board.

The z value specifies the stack order of the Idea. A higher value means the Idea will be closer to the top of the stacking order.

Color :

The set colors available for an Idea is defined by the Board Colors.

By default a Board has the following color collection :

When an Idea is created via the API if the associated Color is not specified the first one of the Board Color collection will be assigned.

{
  "position": {
    "x": 0,
    "y": 0,
    "z": 0
  },
  "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "type": "IDEA",
  "createdAt": "2023-01-26T10:24:43.161Z",
  "updatedAt": "2023-01-26T10:24:43.161Z",
  "author": {
    "id": "string"
  },
  "isLocked": false,
  "data": {
    "content": "string",
    "color": {
      "href": "string",
      "id": "string"
    },
    "category": {
      "href": "string",
      "id": "string"
    },
    "dimensions": [
      {
        "href": "string",
        "id": "ID of the current dimension",
        "value": "Short text for the targeted dimension"
      }
    ]
  }
}

Board Color

Each Board is associated with a collection of Colors. A Board Color can be assign to any Idea of the Board. It is defined with an id, a label (e.g 'Yellow') and a value as a hexadecimal color code (e.g #ffe775).

{
  "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "label": "My color",
  "value": "#ffe151",
  "createdAt": "2023-01-26T10:28:41.115Z",
  "updatedAt": "2023-01-26T10:28:41.115Z"
}

Board Category

Each Board is associated with a collection of Categories. Categories make it easier to organize Ideas. It allows users to assign categories to their ideas. The Host can then use categories to sort ideas and group them together on the board.

{
  "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "label": "My category"
}

Board Dimension

Each Board is associated with a collection of Dimensions. In addition to Categories, Dimensions are used as a means of further defining ideas. Dimensions are displayed as free fields below each Idea. Users can use them to enter any additional details as required (e.g.: their first name, a date, a keyword, etc.). The Host can then use these criteria to sort ideas more precisely.

{
  "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "label": "My dimension"
}