Calling the Board APIs
How to use 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
Mode | Permission |
---|---|
Controlled mode | Participants can send ideas. Ideas will be stored in the Board Inbox. |
Free modes | Participants can send ideas and move them on the Board |
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"
}
Objects and Attributes | Description |
---|---|
id | Unique identifier for the Board |
title | Title of the Board |
description | Short description of the Board |
accessCode | Unique Access Code use to join the Board in Klaxoon |
state | Current board state. can be one of the followingdraft , published or closed |
author | Author of the Board |
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.
Position attributes | Description |
---|---|
x | X-axis coordinate on the board |
y | Y-axis coordinate on the board |
z | Z-index on the board |
Color :
The set colors available for an Idea is defined by the Board Colors.
By default a Board has the following color collection :
- #ffe775
- #c3f18c
- #ffb1b1
- #99dcff
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"
}
]
}
}
Objects and Attributes | Description |
---|---|
id | Unique identifier for the board Idea |
position | Position of the Idea in the board including Z-index |
content | Content text of the idea |
Category Id | ID of the current category |
dimension id | ID of the current dimension |
dimension value | Short text for the targeted dimension |
isLocked | State of the Idea. A Locked Idea cannot be moved. |
author id | ID of the author Idea |
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"
}
Attributes | Descriptions |
---|---|
id | Unique identifier for the Board Color |
label | Label associated with the Board Color |
value | Hexadecimal color code |
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"
}
Attributes | Descriptions |
---|---|
id | Unique identifier for the Board Category |
label | Label associated with the Board 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"
}
Attributes | Descriptions |
---|---|
id | Unique identifier for the Board Dimension |
label | Label associated with the Board Category |
Updated 11 months ago