Klaro Cards API v1 (0.234.1)

Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.

Introduction

Welcome to the Klaro Cards API documentation. If you have experience with RESTFul APIs, you should not be surprised.

Make sure you read the About Klaro Cards section that contains important information about the various Klaro Cards concepts and the way they are represented on the API.

API Version and Stability

The API is a V1 ; it's the version of the API used by the Klaro Cards desktop and mobile applications. It has been designed as a decent RESTFul API, but with a main focus on the needs of those applications.

We make a strong effort to make the API stable and backward compatible for several years ahead. In particular, we adopt the following practices:

Resources (urls) and Verbs may be deprecated, but won't be removed in V1
Fields can be added to resources, but never removed
We make a strong effort not to change the semantics attached to fields

Please reach the technical team with suggestions or to get help. You can either use support@klaro.cards or reach us on social networks.

API Endpoints

# GET stories on the project hosted at helloworld.klaro.cards and board all
curl \
  -H "Authorization: Bearer ..."
  -H "Accept: application/json"
  -H "X-Klaro-Project-Subdomain: helloworld"
  -H "X-Klaro-ViewAs: admins"
  -X GET
  https://api.klaro.cards/v1/boards/all/stories/

You typically use the API against :

a specific Klaro Cards instance, typically the public cloud hosted under klaro.cards
within the context of a given Klaro Cards project, hosted on a subdomain of the instance
a specific version, v1 for now

Given an instance, say klaro.cards, you have two possible endpoints :

Either use, https://api.klaro.cards/v1/ and specify the project via the headers below
Or use https://yourproject.klaro.cards/api/v1/ and skip the project header.

If your company bought or runs a dedicated instance, simply replace klaro.cards above by domain of your instance, e.g. mycompany.klaro.cards, or klaro.yourcompany.com.

Test or Sandbox

There are ways to use the API for tests :

Either duplicate your project in Klaro Cards (see the Danger zone of the Settings screen) and run your tests against that project.
Use the staging.klaro.cards instance. You can create temporary projects and use the API on them. Note that the staging instance can be redeployed and its database reset at any time.

HTTP Headers

Most resources require an authorization token. See the Authentication section and the POST /auth/tokens/ service for details. If you use public boards, data about boards and their cards will be served without requiring any such token/header, though.

More generally, the following headers are supported. Some of them may be required according to the endpoint and service you use.

Header	Semantics
`X-Klaro-Project-Id`	The UUID of the project you want to manipulate via the API
`X-Klaro-Project-Subdomain`	A human friendly alternative to specify the project
`X-Klaro-ViewAs`	A specific workspace to use if your user belongs to many workspaces
`Authorization`	A valid Authorization token obtained via `POST /auth/tokens`
`Content-Type`	The content type of the input data on non-GET requests (use `application/json`)
`Accept`	The content type of the output data (use `application/json`)

Verbs and semantics

The API consistently uses the following HTTP Verb conventions :

Verb	URL of	Description	Idempotent
GET	Resource & Collection	Get the representation of the resource or collection	Yes
POST	Collection	Create a new resource or bunch of resources in the collection	No
POST	Action	Execute the resource action	No
PATCH	Resource	Update a resource via a representation patch	No
DELETE	Resource	Delete the resource	No
DELETE	Collection	Delete some or all resources in the collection	No

Note that PATCH and DELETE are not idempotent as sometimes suggested by RESTful. Notably, trying to delete an already deleted resource will return a 404.

Resource, Collection, Patch

// This could be a card resource
{ id: "...", title: "Hello world", progress: "todo" }

// This is a collection of cards
[
  { id: "...", title: "Hello world", progress: "todo" },
  { id: "...", title: "And all developers there", progress: "done" },
]

// This is a card patch
{ progress: "abandonned" }

The V1 API uses simple and unconvoluted/flat representations for Resources and Collections. That is, most web services simply follow the following conventions :

Resources are represented as Plain Old Json Objects (POJO)
Collections are arrays of POJOs
A resource patch is a subset of its POJO

Most services accept and serve application/json. Some of them also support other content types, notably text/csv.

Pagination

The API does not support pagination for now. Favor filters.

We know, it's a big short for an API, we're still working on it. If that's blocking for your use case, reach us immediately.

Common success codes

The API uses the following codes on successful requests :

Success Code	Name	Reason
200	OK	Your request is valid, the representation/data can be found in body
201	Created	A resource has been created, it's representation can be found in body
204	No Content	The request has been executed but no data or representation is returned.

Common error codes

The following error codes may be observed on all services. We make a strong effort to use their semantics where applicable.

All 4xx errors have a body with error details encoded in JSON using the schema shown at right:

// Error schema, with a unique code and description of the issue
{
  code        : String
  description : String
}

Error Code	Name	Reason
400	Bad Request	Your request is invalid ; typically your input data violates the input schema
401	Unauthorized	Your request is missing a token or the token is invalid or expired.
403	Forbidden	You don't have the necessary permissions for that action.
404	Not Found	The specified resource could not be found.
406	Not Acceptable Error	The `Accept` http header is missing or unrecognized.
409	Conflit Error	Your request is valid but ends up violating a data constraint.
415	Unsupported Media Type	The format of your input data cannot be used, check your `Content-Type` header.
500	Internal Server Error	We had a problem with our server. Try again later.
501	Not Implemented Error	You clearly use the API on an edge case we don't cover yet.
503	Service Unavailable	We're temporarily offline for maintenance. Please try again later.

About Klaro Cards

Core concepts

The API is structured around main Klaro Cards concepts :

Projects, which are independent databases of cards
Cards, formally called Stories on the API for historical reasons
Dimensions, that enrich cards with structured data and allow filtering them in boards
Boards, that select a subset of a cards and visualize them in a certain way
Board cards, that designate the subset of cards visible in a board given its filters.
Danger zone, which is the set of potentially destructive project actions

There are plenty of other resources of course, but that are considered second class citizen according to Klaro Cards' core value proposition.

Conceptual model

Within a Klaro Cards project, a board displays a subset of the project cards. A card has a few fixed fields, as well as fields contributed by the project dimensions. A Dimension has a list of values, that are used enrich the cards and install the board filters.

Cards & Dimensions

// Let's say you have the following card
{
  id: "...",
  title: "Hello world",
  progress: "todo",
  // ...
}

// The following dimensions explains that representation:
[
  {
    id: "...",
    code: "title",
    label: "Card title",
    datatype: "Title",
    // ...
  },
  {
    id: "...",
    code: "progress",
    label: "Progress",
    datatype: "UserDefined",
    values: [
      { id: "todo", label: "Todo" },
      { id: "ongoing", label: "Ongoing" },
      // ...
    ]
  },
  // ...
]

// A board showing ongoing cards will have the following filters :
{
  id: "...",
  name: "Ongoing tasks",
  filters: {
    progress: ["ongoing"]
  }
  // ...
}

// A kanban board by progress, showing the assignee on cards will have the
// folllowing anchors :
{
  id: "...",
  name: "Ongoing tasks",
  anchors: {
    displayBy: ["progress"],
    cards: ["assignee"]
  }
  // ...
}

The cards fixed fields are id, identifier, project, attachments, and linked.

System dimensions contribute the fields title, specification (aka card description), createdAt, updatedAt.

All other card fields are contributed by configurable dimensions. The rules simply are:

The field name is the dimension code
The field value is the id of a dimension value (unless the dimension captures a scalar, e.g. numbers and dates)

Board Filters & Anchors

Boards use dimensions both for filters and for spacial organisation of cards (and more generally the user interface) via anchors.

Filters currently capture a simple Conjunctive Normal Form over dimensions values. They are represented by an object mapping dimension codes to ids of dimension values. The actual filtering logic is implemented by dimension values themselves, and depend on the Dimension datatype (UserDefined, Date, ProjectMember, etc.) and value semantics.
Anchors capture the use of dimensions to arrange cards in rows and columns, choose what dimensions are shown on cards in a board, or what dimensions are visible in the filter decks. Anchors are represented by an object mapping the anchor name to a list of dimension codes.

Tips & Tricks

Use boards, even for creating stories

Board filters are used to automatically enrich created stories with default values. This allows you to create stories without having to specify all fields.

FAQ

Where is the markdown card description ?

For historical reasons, cards are called stories on the V1 API, and their description is called the specification. Sorry for the confusion introduced.

Why no GET /stories web service

You should always access stories/cards via a given board. See GET /boards/{id}/stories instead.

---

Authentication

oAuth2 authentication. The API implements an OAuth2 authentication mechanism, using tokens served from user credentials by POST /auth/tokens.

The token scopes follow the user permission model of the Klaro Cards app. The scope documented on web services is the minimum scope required, knowing that the hierarchy below applies.

Owner > Admin > Member > User > Anonymous

- Flow: clientCredentials

- Token URL = /auth/token/

Scope	Scope Description
Anonymous	The requester may skip authentication
User	The requester must be a user of the instance/server
Member	The requester must be a member of the current project
Admin	The requester must be an admin of the current project
Owner	The requester must be the owner of the current project

Auth Token

Create token

Code samples

const inputBody = '{
  "grant_type": "client_credentials",
  "client_id": "bernard@klaro.cards",
  "client_secret": "password"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json'
};

fetch('/auth/tokens',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json'
}

result = RestClient.post '/auth/tokens',
  params: {
  }, headers: headers

p JSON.parse(result)

# You can also use wget
curl -X POST /auth/tokens \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

POST /auth/tokens

Allows creating a fresh new token from user credentials. The token can then be used during 5 days. Consider revoking it when done.

Body parameter

Create a token with a valid user/password pair

{
  "grant_type": "client_credentials",
  "client_id": "bernard@klaro.cards",
  "client_secret": "password"
}

Parameters

Name	In	Type	Required	Description
grant_type	body	string	true	Use 'client_credentials'
client_id	body	string	true	Use user login
client_secret	body	string	true	Use user password
redirect_to	body	string	false	Reserved for Klaro Cards app

Example responses

Create a token with a valid user/password pair

{
  "token_type": "Bearer",
  "access_token": "eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoiYTBlYmRlMzctMTIzNC00NDliLWI1NjQtMzllZmFjYTBmMzdmIiwiaWF0IjoxNzQzMDk0OTMxLCJleHAiOjE3NDM1MjY5MzF9.Kr4OcGkz9Pj129p81ANIHf0aqmC-ULB9YNY6G1XzJb4",
  "expires_in": 432000
}

Responses

Status	Meaning	Description	Schema
201	Created	none	Inline

Response Schema

Status Code 201

Name	Type	Required	Restrictions	Description
» token_type	string	true	none	Type of token, typically Bearer
» access_token	string	true	none	The token to pass in Authorization header
» expires_in	integer	true	none	Expiration in seconds

Revoke token

Code samples


const headers = {
  'Authorization':'Bearer {access-token}'
};

fetch('/auth/tokens/self',
{
  method: 'DELETE',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.delete '/auth/tokens/self',
  params: {
  }, headers: headers

p JSON.parse(result)

# You can also use wget
curl -X DELETE /auth/tokens/self \
  -H 'Authorization: Bearer {access-token}'

DELETE /auth/tokens/self

Allows revoking a token without waiting for it to expire, e.g. when the user logs out or the script is finished.

Just call the web service with the usual Authentication header, the token will be revoked

Responses

Status	Meaning	Description	Schema
204	No Content	none	None

User

Get user

Code samples


const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('/auth/me',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.get '/auth/me',
  params: {
  }, headers: headers

p JSON.parse(result)

# You can also use wget
curl -X GET /auth/me \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

GET /auth/me

Returns information about the current user and their preferences on the current project

Example responses

Get information about the current project user

{
  "id": "a0ebde37-1234-449b-b564-39efaca0f37f",
  "email": "bernard@klaro.cards",
  "emailValidated": true,
  "passwordChangedAt": "2025-03-26T17:02:11+00:00",
  "firstname": "Bernard",
  "lastname": "Lambeau",
  "lang": "en",
  "createdAt": "2024-06-15T10:23:05+00:00",
  "nickname": "Bernard",
  "isOwner": true,
  "preferences": {
    "homeBoard": null,
    "homeWorkspace": null,
    "lang": null,
    "syncMode": null,
    "labs": null
  },
  "workspaces": [
    {
      "id": "aaa27578-be58-4634-a24f-35057759bd46",
      "code": "admins",
      "name": "Admins",
      "space": {
        "id": "dbe8cc25-8c98-4ead-b1a9-36e2d95424fb"
      },
      "ordering": 0,
      "createdAt": "2025-03-21T16:30:16+00:00"
    }
  ],
  "isMember": true
}

Responses

Status	Meaning	Description	Schema
200	OK	none	Inline

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» id	string	true	none	User unique id
» email	string	true	none	User's email
» emailValidated	boolean	true	none	Whether the email has been verified
» firstname	string	true	none	User's first name
» lastname	string	true	none	User's last name
» nickname	string	false	none	User's nickname on the project
» isOwner	boolean	true	none	Whether the user owns the current project
» lang	string	true	none	Prefered language for communications with Klaro Cards
» isMember	boolean	true	none	Whether the user is a member of the current project
» createdAt	string	true	none	When was the user created on the project
» workspaces	[object]	true	none	Information about the user's membership to workspaces
»» id	string	true	none	Workspace unique id
»» code	string	true	none	Workspace unique code (used in urls and dimension values)
»» name	string	true	none	Workspace human readable name
»» space	object	true	none	Associated klaro space (reserved)
»»» id	string	true	none	none
»» ordering	integer	true	none	Order of workspace in the all workspaces
»» createdAt	string	true	none	When the workspace has been created
» preferences	object	true	none	The user preferences on this current project
»» homeWorkspace	string	true	none	Which workspace is used as home page, if any
»» homeBoard	string	true	none	Which board is used as home page, if any
»» lang	string	true	none	Prefered user language on the current project
»» syncMode	string	true	none	Prefered board synchronization mode on the current project
»» labs	object	false	none	Which labs are currently enabled and their configuration
»»» additionalProperties	object	false	none	none
»»»» additionalProperties	any	false	none	none
»»»» enabled	boolean	true	none	Whether the lab is enabled on the current project
» passwordChangedAt	string	true	none	Last time the password has been changed

Save user & preferences

Code samples

const inputBody = '{
  "firstname": "Foo",
  "lastname": "Bar",
  "preferences": {
    "homeBoard": "kanban",
    "homeWorkspace": "admins",
    "lang": "fr",
    "syncMode": "onDemand"
  }
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('/auth/me',
{
  method: 'PATCH',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.patch '/auth/me',
  params: {
  }, headers: headers

p JSON.parse(result)

# You can also use wget
curl -X PATCH /auth/me \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

PATCH /auth/me

Updates the user profile and their preferences on the current project

Body parameter

Update the user name and preferences

{
  "firstname": "Foo",
  "lastname": "Bar",
  "preferences": {
    "homeBoard": "kanban",
    "homeWorkspace": "admins",
    "lang": "fr",
    "syncMode": "onDemand"
  }
}

Parameters

Name	In	Type	Required	Description
firstname	body	string	false	User's first name
lastname	body	string	false	User's last name
lang	body	string	false	Prefered language for communications with Klaro Cards
preferences	body	object	false	The user preferences on this current project
» homeWorkspace	body	string	true	Which workspace is used as home page, if any
» homeBoard	body	string	true	Which board is used as home page, if any
» lang	body	string	true	Prefered user language on the current project
» syncMode	body	string	true	Prefered board synchronization mode on the current project
» labs	body	object	false	Which labs are currently enabled and their configuration
»» additionalProperties	body	object	false	none
»»» additionalProperties	body	any	false	none
»»» enabled	body	boolean	true	Whether the lab is enabled on the current project

Example responses

Update the user name and preferences

{
  "id": "a0ebde37-1234-449b-b564-39efaca0f37f",
  "email": "bernard@klaro.cards",
  "emailValidated": true,
  "passwordChangedAt": "2025-03-26T17:02:11+00:00",
  "firstname": "Foo",
  "lastname": "Bar",
  "lang": "en",
  "createdAt": "2024-06-15T10:23:05+00:00",
  "nickname": "Bernard",
  "isOwner": true,
  "preferences": {
    "homeBoard": "kanban",
    "homeWorkspace": "admins",
    "lang": "fr",
    "syncMode": "onDemand",
    "labs": {}
  },
  "workspaces": [
    {
      "id": "aaa27578-be58-4634-a24f-35057759bd46",
      "code": "admins",
      "name": "Admins",
      "space": {
        "id": "dbe8cc25-8c98-4ead-b1a9-36e2d95424fb"
      },
      "ordering": 0,
      "createdAt": "2025-03-21T16:30:16+00:00"
    }
  ],
  "isMember": true
}

Responses

Status	Meaning	Description	Schema
200	OK	none	Inline

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» id	string	true	none	User unique id
» email	string	true	none	User's email
» emailValidated	boolean	true	none	Whether the email has been verified
» firstname	string	true	none	User's first name
» lastname	string	true	none	User's last name
» nickname	string	false	none	User's nickname on the project
» isOwner	boolean	true	none	Whether the user owns the current project
» lang	string	true	none	Prefered language for communications with Klaro Cards
» isMember	boolean	true	none	Whether the user is a member of the current project
» createdAt	string	true	none	When was the user created on the project
» workspaces	[object]	true	none	Information about the user's membership to workspaces
»» id	string	true	none	Workspace unique id
»» code	string	true	none	Workspace unique code (used in urls and dimension values)
»» name	string	true	none	Workspace human readable name
»» space	object	true	none	Associated klaro space (reserved)
»»» id	string	true	none	none
»» ordering	integer	true	none	Order of workspace in the all workspaces
»» createdAt	string	true	none	When the workspace has been created
» preferences	object	true	none	The user preferences on this current project
»» homeWorkspace	string	true	none	Which workspace is used as home page, if any
»» homeBoard	string	true	none	Which board is used as home page, if any
»» lang	string	true	none	Prefered user language on the current project
»» syncMode	string	true	none	Prefered board synchronization mode on the current project
»» labs	object	false	none	Which labs are currently enabled and their configuration
»»» additionalProperties	object	false	none	none
»»»» additionalProperties	any	false	none	none
»»»» enabled	boolean	true	none	Whether the lab is enabled on the current project
» passwordChangedAt	string	true	none	Last time the password has been changed

Projects

Get project

Code samples


const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('/',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.get '/',
  params: {
  }, headers: headers

p JSON.parse(result)

# You can also use wget
curl -X GET / \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

GET

Returns information about the current project

Example responses

Get the details of the current project

{
  "id": "8c34924f-21ca-406b-aaaa-749ad3d2f4fb",
  "name": "Todolist OpenAPI",
  "subdomain": "openapi",
  "isPublic": false,
  "isTemplate": false,
  "isBlocked": false,
  "isLocked": true,
  "logoUrl": null,
  "timezone": "Europe/Brussels",
  "locale": "en-be",
  "imageUrl": null,
  "thumbUrl": null,
  "blogUrl": null,
  "revision": 3,
  "title": null,
  "summary": null,
  "description": "",
  "createdAt": "2025-03-21T16:30:11+00:00",
  "updatedAt": "2025-03-21T16:30:22+00:00",
  "template": {
    "id": "168d1896-f509-4cfa-8a12-9e86152e122b",
    "subdomain": "blank",
    "name": "Blank",
    "isPublic": true
  },
  "category": null,
  "settings": {
    "max_upload_size": 10
  },
  "integrations": null,
  "url": "http://openapi.klaro.devel/",
  "imgBaseUrl": "http://openapi.klaro.devel/"
}

Responses

Status	Meaning	Description	Schema
200	OK	none	Inline

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» id	string	true	none	Project's unique ID
» name	string	true	none	Project's human friendly name
» subdomain	string	true	none	Subdomain of the instance where the project is hosted
» isPublic	boolean	true	none	Whether this project is public
» isTemplate	boolean	true	none	Whether this project is a template
» isBlocked	boolean	true	none	Whether this project has been blocked by administrators
» isLocked	boolean	true	none	(deprecated)
» timezone	string	true	none	Project's timezone
» locale	string	true	none	Project's locale, e.g. en-US or fr-BE
» url	string	true	none	URL where users can reach the project
» imgBaseUrl	string	true	none	Base URL for card images
» logoUrl	string	true	none	URL for the project logo
» revision	integer	true	none	Revision number of the project (increased when settings change)
» createdAt	string	true	none	When was the project created
» updatedAt	string	true	none	When was the project last updated
» title	string	true	none	Project marketing title, if any
» summary	string	true	none	Project marketing summary, if any
» description	string	true	none	Project marketing description, if any
» imageUrl	string	true	none	URL of the marketing image, if any
» thumbUrl	string	true	none	URL of the marketing thumbnail, if any
» blogUrl	string	true	none	URL of the blog post or internet page presenting the project, if any
» template	object	true	none	Parent template, if any
»» id	string	true	none	none
»» name	string	true	none	none
»» subdomain	string	true	none	none
»» isPublic	boolean	true	none	none
» category	object	true	none	Project category, if any
»» id	string	true	none	Category unique id
»» name	string	true	none	Category name
»» color	string	true	none	Category color
»» code	string	true	none	Category code (used in URLs)
»» summary	string	true	none	Category short summary, if any
» settings	object	true	none	Project settings
»» additionalProperties	object	false	none	none
» integrations	object	true	none	Integration availabilities, if any
»» additionalProperties	object	false	none	none
»»» available	boolean	true	none	Whether the integration is available on the project

Create project

Code samples

const inputBody = '{
  "name": "Hello klaro",
  "subdomain": "hello-klaro",
  "template": "todolist",
  "dryRun": false
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('/',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.post '/',
  params: {
  }, headers: headers

p JSON.parse(result)

# You can also use wget
curl -X POST / \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

POST

Allows creating a fresh new project and/or instantiate a template. The resulting project can be found at the location returned in output data.

Body parameter

Instantiate a template as a fresh new project

{
  "name": "Hello klaro",
  "subdomain": "hello-klaro",
  "template": "todolist",
  "dryRun": false
}

Parameters

Name	In	Type	Required	Description
additionalProperties	body	any	false	none
name	body	string	true	Project name
subdomain	body	string	true	Subdomain where the project will he bosted on the instance
dryRun	body	boolean	true	Set it to true to check the subdomain availability
template	body	string	false	Optional template, use either its UUID or subdomain

Example responses

Instantiate a template as a fresh new project

{
  "location": "http://hello-klaro.klaro.devel/"
}

Responses

Status	Meaning	Description	Schema
201	Created	none	Inline

Response Schema

Update project

Code samples

const inputBody = '{
  "description": "My Personal Todolist",
  "locale": "fr-be"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('/',
{
  method: 'PATCH',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.patch '/',
  params: {
  }, headers: headers

p JSON.parse(result)

# You can also use wget
curl -X PATCH / \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

PATCH

Allows modifying the current project

Body parameter

Update the description and locale of the current project

{
  "description": "My Personal Todolist",
  "locale": "fr-be"
}

Parameters

Name	In	Type	Required	Description
name	body	string	false	Project's human friendly name
subdomain	body	string	false	Subdomain of the instance where the project is hosted
timezone	body	string	false	Project's timezone
locale	body	string	false	Project's locale, e.g. en-US or fr-BE
logoUrl	body	string	false	URL for the project logo
description	body	string	false	Project marketing description, if any
imageUrl	body	string	false	URL of the marketing image, if any
thumbUrl	body	string	false	URL of the marketing thumbnail, if any
blogUrl	body	string	false	URL of the blog post or internet page presenting the project, if any
category	body	object	false	Project category, if any
» additionalProperties	body	any	false	none
» id	body	string	true	Category unique id

Example responses

Update the description and locale of the current project

{
  "id": "8c34924f-21ca-406b-aaaa-749ad3d2f4fb",
  "name": "Todolist OpenAPI",
  "subdomain": "openapi",
  "isPublic": false,
  "isTemplate": false,
  "isBlocked": false,
  "isLocked": true,
  "logoUrl": null,
  "timezone": "Europe/Brussels",
  "locale": "fr-be",
  "imageUrl": null,
  "thumbUrl": null,
  "blogUrl": null,
  "revision": 4,
  "title": null,
  "summary": null,
  "description": "My Personal Todolist",
  "createdAt": "2025-03-21T16:30:11+00:00",
  "updatedAt": "2025-03-27T17:02:17+00:00",
  "template": {
    "id": "168d1896-f509-4cfa-8a12-9e86152e122b",
    "subdomain": "blank",
    "name": "Blank",
    "isPublic": true
  },
  "category": null,
  "settings": {
    "max_upload_size": 10
  },
  "integrations": null,
  "url": "http://openapi.klaro.devel/",
  "imgBaseUrl": "http://openapi.klaro.devel/"
}

Responses

Status	Meaning	Description	Schema
200	OK	none	Inline

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» id	string	true	none	Project's unique ID
» name	string	true	none	Project's human friendly name
» subdomain	string	true	none	Subdomain of the instance where the project is hosted
» isPublic	boolean	true	none	Whether this project is public
» isTemplate	boolean	true	none	Whether this project is a template
» isBlocked	boolean	true	none	Whether this project has been blocked by administrators
» isLocked	boolean	true	none	(deprecated)
» timezone	string	true	none	Project's timezone
» locale	string	true	none	Project's locale, e.g. en-US or fr-BE
» url	string	true	none	URL where users can reach the project
» imgBaseUrl	string	true	none	Base URL for card images
» logoUrl	string	true	none	URL for the project logo
» revision	integer	true	none	Revision number of the project (increased when settings change)
» createdAt	string	true	none	When was the project created
» updatedAt	string	true	none	When was the project last updated
» title	string	true	none	Project marketing title, if any
» summary	string	true	none	Project marketing summary, if any
» description	string	true	none	Project marketing description, if any
» imageUrl	string	true	none	URL of the marketing image, if any
» thumbUrl	string	true	none	URL of the marketing thumbnail, if any
» blogUrl	string	true	none	URL of the blog post or internet page presenting the project, if any
» template	object	true	none	Parent template, if any
»» id	string	true	none	none
»» name	string	true	none	none
»» subdomain	string	true	none	none
»» isPublic	boolean	true	none	none
» category	object	true	none	Project category, if any
»» id	string	true	none	Category unique id
»» name	string	true	none	Category name
»» color	string	true	none	Category color
»» code	string	true	none	Category code (used in URLs)
»» summary	string	true	none	Category short summary, if any
» settings	object	true	none	Project settings
»» additionalProperties	object	false	none	none
» integrations	object	true	none	Integration availabilities, if any
»» additionalProperties	object	false	none	none
»»» available	boolean	true	none	Whether the integration is available on the project

Dimensions

Get dimension

Code samples


const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('/dimensions/{id}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.get '/dimensions/{id}',
  params: {
  }, headers: headers

p JSON.parse(result)

# You can also use wget
curl -X GET /dimensions/{id} \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

GET /dimensions/{id}

Returns a given dimension

Parameters

Name	In	Type	Required	Description
id	path	string	true	Either the dimension id or code

Example responses

Get a dimension, you can use either its ID or code as URL parameter

{
  "code": "progress",
  "ordering": 120000,
  "label": "Progress",
  "tagging": true,
  "multiple": false,
  "required": false,
  "id": "8582be6e-283e-4633-9cc5-2f2ab96a43bb",
  "deleted": false,
  "deletedAt": null,
  "deletedBy": null,
  "description": null,
  "semanticsType": null,
  "datatype": "Progress",
  "datatypeOptions": {},
  "relevantKinds": [],
  "values": [
    {
      "id": null,
      "label": "No value",
      "semantics": null,
      "ordering": -1,
      "color": "#ffffff",
      "description": null,
      "deprecated": false
    },
    {
      "id": "todo",
      "label": "Todo",
      "ordering": 10000,
      "color": "#e01514",
      "semantics": null,
      "description": null,
      "deprecated": false
    },
    {
      "id": "ongoing",
      "label": "Ongoing",
      "ordering": 20000,
      "color": "#f77d00",
      "semantics": null,
      "description": null,
      "deprecated": false
    },
    {
      "id": "done",
      "label": "Done",
      "ordering": 30000,
      "color": "#00b048",
      "semantics": null,
      "description": null,
      "deprecated": false
    }
  ],
  "attribute": false,
  "supportsMultiple": false,
  "supportsRequired": true,
  "supportsTagging": true,
  "supportsAlphabeticalOrdering": true,
  "supportsColor": true,
  "userEditable": true
}

Responses

Status	Meaning	Description	Schema
200	OK	none	Inline

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» id	string	true	none	Dimension unique ID
» code	string	true	none	Dimension code (used in URLs, filters, anchors, etc.)
» datatype	string	true	none	Dimension datatype (e.g. UserDefined, Date, ProjectMember, etc.)
» datatypeOptions	object	true	none	Options of the datatype, configuring behavior
»» additionalProperties	object	false	none	none
» label	string	true	none	Dimension human friendly name
» description	string	true	none	Dimension long description, if any
» required	boolean	true	none	Whether a value is required on cards
» supportsRequired	boolean	true	none	Whether the users can decided whether the dimension is required
» tagging	boolean	true	none	Whether users can add/edit values in boards and cards (aka unlocked)
» supportsTagging	boolean	true	none	Whether users can choose to lock/unlock the dimension
» multiple	boolean	true	none	Whether multiple values can be choosen on cards
» supportsMultiple	boolean	true	none	Whether the dimension datatype supports multiple values
» supportsAlphabeticalOrdering	boolean	true	none	Whether values can be ordered alphabetically
» userEditable	boolean	true	none	Whether values can be choosen by end-users on cards
» attribute	boolean	true	none	Whether this dimension is a fixed card attribute (deprecated)
» supportsColor	boolean	true	none	Whether the dimension supports colors on values
» ordering	integer	true	none	Order index of the dimension in the project
» semanticsType	string	true	none	Semantics of the dimension values
» relevantKinds	[string]	true	none	For what card kinds this dimension is relevant
» values	[object]	true	none	The dimension list of values
»» additionalProperties	object	false	none	none
»» id	string	true	none	ID for the value (unique inside the dimension)
»» label	string	true	none	Human friendly label of the value
»» semantics	string	true	none	Filtering semantics, if any
»» color	string	true	none	Value color, if any
»» ordering	integer	true	none	Ordering of the value within the collection
»» description	string	false	none	Description of the value, if any
»» placeholder	string	false	none	Placeholder of the value, if any
»» deprecated	boolean	true	none	Whether the value is deprecated
» deleted	boolean	true	none	Whether the dimension has been deleted
» deletedAt	string	true	none	When this dimension was deleted, if deleted
» deletedBy	string	true	none	Who deleted this dimension, if deleted

Update dimension

Code samples

const inputBody = '{
  "label": "Status"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('/dimensions/{id}',
{
  method: 'PATCH',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.patch '/dimensions/{id}',
  params: {
  }, headers: headers

p JSON.parse(result)

# You can also use wget
curl -X PATCH /dimensions/{id} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

PATCH /dimensions/{id}

Allows updating an existing project dimension

Body parameter

Update a dimension, you can use either its ID or code as URL parameter

{
  "label": "Status"
}

Parameters

Name	In	Type	Required	Description
id	path	string	true	Either the dimension id or code
label	body	string	false	Dimension human friendly name
description	body	string	false	Dimension long description, if any
tagging	body	boolean	false	Whether users can add/edit values in boards and cards (aka unlocked)
required	body	boolean	false	Whether a value is required on cards
multiple	body	boolean	false	Whether multiple values can be choosen on cards
ordering	body	integer	false	Order index of the dimension in the project
datatypeOptions	body	object	false	Options of the datatype, configuring behavior
» additionalProperties	body	object	false	none
semanticsType	body	string	false	Semantics of the dimension values
relevantKinds	body	[string]	false	For what card kinds this dimension is relevant

Example responses

Update a dimension, you can use either its ID or code as URL parameter

{
  "code": "status",
  "ordering": 120000,
  "label": "Status",
  "tagging": true,
  "multiple": false,
  "required": false,
  "id": "8582be6e-283e-4633-9cc5-2f2ab96a43bb",
  "deleted": false,
  "deletedAt": null,
  "deletedBy": null,
  "description": null,
  "semanticsType": null,
  "datatype": "Progress",
  "datatypeOptions": {},
  "relevantKinds": [],
  "values": [
    {
      "id": null,
      "label": "No value",
      "semantics": null,
      "ordering": -1,
      "color": "#ffffff",
      "description": null,
      "deprecated": false
    },
    {
      "id": "todo",
      "label": "Todo",
      "semantics": null,
      "ordering": 10000,
      "color": "#e01514",
      "description": null,
      "deprecated": false
    },
    {
      "id": "ongoing",
      "label": "Ongoing",
      "semantics": null,
      "ordering": 20000,
      "color": "#f77d00",
      "description": null,
      "deprecated": false
    },
    {
      "id": "done",
      "label": "Done",
      "semantics": null,
      "ordering": 30000,
      "color": "#00b048",
      "description": null,
      "deprecated": false
    }
  ],
  "attribute": false,
  "supportsMultiple": false,
  "supportsRequired": true,
  "supportsTagging": true,
  "supportsAlphabeticalOrdering": true,
  "supportsColor": true,
  "userEditable": true
}

Responses

Status	Meaning	Description	Schema
200	OK	none	Inline

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» id	string	true	none	Dimension unique ID
» code	string	true	none	Dimension code (used in URLs, filters, anchors, etc.)
» datatype	string	true	none	Dimension datatype (e.g. UserDefined, Date, ProjectMember, etc.)
» datatypeOptions	object	true	none	Options of the datatype, configuring behavior
»» additionalProperties	object	false	none	none
» label	string	true	none	Dimension human friendly name
» description	string	true	none	Dimension long description, if any
» required	boolean	true	none	Whether a value is required on cards
» supportsRequired	boolean	true	none	Whether the users can decided whether the dimension is required
» tagging	boolean	true	none	Whether users can add/edit values in boards and cards (aka unlocked)
» supportsTagging	boolean	true	none	Whether users can choose to lock/unlock the dimension
» multiple	boolean	true	none	Whether multiple values can be choosen on cards
» supportsMultiple	boolean	true	none	Whether the dimension datatype supports multiple values
» supportsAlphabeticalOrdering	boolean	true	none	Whether values can be ordered alphabetically
» userEditable	boolean	true	none	Whether values can be choosen by end-users on cards
» attribute	boolean	true	none	Whether this dimension is a fixed card attribute (deprecated)
» supportsColor	boolean	true	none	Whether the dimension supports colors on values
» ordering	integer	true	none	Order index of the dimension in the project
» semanticsType	string	true	none	Semantics of the dimension values
» relevantKinds	[string]	true	none	For what card kinds this dimension is relevant
» values	[object]	true	none	The dimension list of values
»» additionalProperties	object	false	none	none
»» id	string	true	none	ID for the value (unique inside the dimension)
»» label	string	true	none	Human friendly label of the value
»» semantics	string	true	none	Filtering semantics, if any
»» color	string	true	none	Value color, if any
»» ordering	integer	true	none	Ordering of the value within the collection
»» description	string	false	none	Description of the value, if any
»» placeholder	string	false	none	Placeholder of the value, if any
»» deprecated	boolean	true	none	Whether the value is deprecated
» deleted	boolean	true	none	Whether the dimension has been deleted
» deletedAt	string	true	none	When this dimension was deleted, if deleted
» deletedBy	string	true	none	Who deleted this dimension, if deleted

Delete dimension

Code samples


const headers = {
  'Authorization':'Bearer {access-token}'
};

fetch('/dimensions/{id}',
{
  method: 'DELETE',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.delete '/dimensions/{id}',
  params: {
  }, headers: headers

p JSON.parse(result)

# You can also use wget
curl -X DELETE /dimensions/{id} \
  -H 'Authorization: Bearer {access-token}'

DELETE /dimensions/{id}

Allows deleting a dimension

Parameters

Name	In	Type	Required	Description
id	path	string	true	Either the dimension id or code

Responses

Status	Meaning	Description	Schema
204	No Content	none	None

Get dimensions

Code samples


const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('/dimensions',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.get '/dimensions',
  params: {
  }, headers: headers

p JSON.parse(result)

# You can also use wget
curl -X GET /dimensions \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

GET /dimensions

Returns the list of project dimensions

Example responses

Get the dimensions

[
  {
    "code": "identifier",
    "ordering": 1000,
    "label": "Card n°",
    "tagging": false,
    "multiple": false,
    "required": true,
    "id": "af352fc7-8c9b-4030-934e-da0b1f737741",
    "deleted": false,
    "deletedAt": null,
    "deletedBy": null,
    "description": null,
    "semanticsType": null,
    "datatype": "Identifier",
    "datatypeOptions": {},
    "relevantKinds": [],
    "values": [
      {
        "id": null,
        "label": "No value",
        "semantics": null,
        "ordering": -1,
        "color": "#ffffff",
        "description": null,
        "deprecated": false
      }
    ],
    "attribute": true,
    "supportsMultiple": false,
    "supportsRequired": false,
    "supportsTagging": false,
    "supportsAlphabeticalOrdering": false,
    "supportsColor": false,
    "userEditable": false
  },
  {
    "code": "title",
    "ordering": 1010,
    "label": "Card title",
    "tagging": false,
    "multiple": false,
    "required": false,
    "id": "4e5bf2b8-b0d3-4f5d-b966-e017f7feadda",
    "deleted": false,
    "deletedAt": null,
    "deletedBy": null,
    "description": "Card title",
    "semanticsType": null,
    "datatype": "Title",
    "datatypeOptions": {},
    "relevantKinds": [],
    "values": [
      {
        "id": null,
        "label": "No value",
        "semantics": null,
        "ordering": -1,
        "color": "#ffffff",
        "description": null,
        "deprecated": false
      }
    ],
    "attribute": true,
    "supportsMultiple": false,
    "supportsRequired": false,
    "supportsTagging": false,
    "supportsAlphabeticalOrdering": false,
    "supportsColor": false,
    "userEditable": true
  },
  {
    "code": "specification",
    "ordering": 1011,
    "label": "Card description",
    "tagging": false,
    "multiple": false,
    "required": false,
    "id": "039fdea8-4dd7-488f-85f5-38f2c11eff8a",
    "deleted": false,
    "deletedAt": null,
    "deletedBy": null,
    "description": "Card (Markdown) description",
    "semanticsType": null,
    "datatype": "Specification",
    "datatypeOptions": {},
    "relevantKinds": [],
    "values": [
      {
        "id": null,
        "label": "No value",
        "semantics": null,
        "ordering": -1,
        "color": "#ffffff",
        "description": null,
        "deprecated": false
      }
    ],
    "attribute": true,
    "supportsMultiple": false,
    "supportsRequired": false,
    "supportsTagging": false,
    "supportsAlphabeticalOrdering": false,
    "supportsColor": false,
    "userEditable": true
  },
  {
    "code": "kind",
    "ordering": 20000,
    "label": "Kind",
    "tagging": true,
    "multiple": false,
    "required": true,
    "id": "0d3c755c-b3d3-4940-947e-e90de07e571f",
    "deleted": false,
    "deletedAt": null,
    "deletedBy": null,
    "description": null,
    "semanticsType": null,
    "datatype": "Kind",
    "datatypeOptions": {},
    "relevantKinds": [],
    "values": [
      {
        "id": null,
        "label": "No value",
        "semantics": null,
        "ordering": -1,
        "color": "#ffffff",
        "description": null,
        "deprecated": false
      },
      {
        "id": "todo",
        "label": "Todo",
        "color": "#b7137e",
        "ordering": 1000000,
        "semantics": null,
        "colorDimension": null,
        "description": null,
        "placeholder": null,
        "deprecated": false,
        "summaryDimensions": []
      }
    ],
    "attribute": false,
    "supportsMultiple": false,
    "supportsRequired": true,
    "supportsTagging": true,
    "supportsAlphabeticalOrdering": true,
    "supportsColor": true,
    "userEditable": true
  },
  {
    "code": "progress",
    "ordering": 120000,
    "label": "Progress",
    "tagging": true,
    "multiple": false,
    "required": false,
    "id": "8582be6e-283e-4633-9cc5-2f2ab96a43bb",
    "deleted": false,
    "deletedAt": null,
    "deletedBy": null,
    "description": null,
    "semanticsType": null,
    "datatype": "Progress",
    "datatypeOptions": {},
    "relevantKinds": [],
    "values": [
      {
        "id": null,
        "label": "No value",
        "semantics": null,
        "ordering": -1,
        "color": "#ffffff",
        "description": null,
        "deprecated": false
      },
      {
        "id": "todo",
        "label": "Todo",
        "ordering": 10000,
        "color": "#e01514",
        "semantics": null,
        "description": null,
        "deprecated": false
      },
      {
        "id": "ongoing",
        "label": "Ongoing",
        "ordering": 20000,
        "color": "#f77d00",
        "semantics": null,
        "description": null,
        "deprecated": false
      },
      {
        "id": "done",
        "label": "Done",
        "ordering": 30000,
        "color": "#00b048",
        "semantics": null,
        "description": null,
        "deprecated": false
      }
    ],
    "attribute": false,
    "supportsMultiple": false,
    "supportsRequired": true,
    "supportsTagging": true,
    "supportsAlphabeticalOrdering": true,
    "supportsColor": true,
    "userEditable": true
  },
  {
    "code": "assignee",
    "ordering": 220000,
    "label": "Assignee",
    "tagging": true,
    "multiple": false,
    "required": false,
    "id": "0334196e-1aba-4049-9769-b8fde2eb2227",
    "deleted": false,
    "deletedAt": null,
    "deletedBy": null,
    "description": null,
    "semanticsType": null,
    "datatype": "ProjectMember",
    "datatypeOptions": {},
    "relevantKinds": [],
    "values": [
      {
        "id": null,
        "label": "No value",
        "semantics": null,
        "ordering": -1,
        "color": "#ffffff",
        "description": null,
        "deprecated": false
      },
      {
        "id": "Bernard",
        "label": "Bernard",
        "ordering": 1000000,
        "color": "#ffffff",
        "semantics": "Bernard",
        "description": null,
        "deprecated": false
      },
      {
        "id": "Victor",
        "label": "Victor",
        "ordering": 2000000,
        "color": "#ffffff",
        "semantics": "Victor",
        "description": null,
        "deprecated": false
      },
      {
        "id": "Marc",
        "label": "Marc",
        "ordering": 3000000,
        "color": "#ffffff",
        "semantics": "Marc",
        "description": null,
        "deprecated": false
      }
    ],
    "attribute": false,
    "supportsMultiple": true,
    "supportsRequired": true,
    "supportsTagging": true,
    "supportsAlphabeticalOrdering": true,
    "supportsColor": true,
    "userEditable": true
  },
  {
    "code": "due_date",
    "ordering": 320000,
    "label": "Due date",
    "tagging": false,
    "multiple": false,
    "required": false,
    "id": "44c78647-0a68-48a2-b6e0-0fd926752f4f",
    "deleted": false,
    "deletedAt": null,
    "deletedBy": null,
    "description": null,
    "semanticsType": "DateRange",
    "datatype": "DueDate",
    "datatypeOptions": {},
    "relevantKinds": [],
    "values": [
      {
        "id": null,
        "label": "No value",
        "semantics": null,
        "ordering": -1,
        "color": "#ffffff",
        "description": null,
        "deprecated": false
      },
      {
        "id": "late_",
        "label": "Late!",
        "ordering": 10000,
        "color": "#202020",
        "semantics": "-BOT",
        "description": null,
        "deprecated": false
      },
      {
        "id": "late_tomorrow",
        "label": "Late tomorrow",
        "ordering": 20000,
        "color": "#e01514",
        "semantics": "+P1D",
        "description": null,
        "deprecated": false
      },
      {
        "id": "late_in_3_days",
        "label": "Late in 3 days",
        "ordering": 30000,
        "color": "#a85319",
        "semantics": "+P1D .. +P3D",
        "description": null,
        "deprecated": false
      },
      {
        "id": "next_7_days",
        "label": "Next 7 days",
        "ordering": 40000,
        "color": "#ffba00",
        "semantics": "+P3D .. +P7D",
        "description": null,
        "deprecated": false
      },
      {
        "id": "next_15_days",
        "label": "Next 15 days",
        "ordering": 50000,
        "color": "#99cc2d",
        "semantics": "+P7D .. +P15D",
        "description": null,
        "deprecated": false
      },
      {
        "id": "next_30_days",
        "label": "Next 30 days",
        "ordering": 60000,
        "color": "#00b048",
        "semantics": "+P15D .. +P30D",
        "description": null,
        "deprecated": false
      },
      {
        "id": "later",
        "label": "Later",
        "ordering": 70000,
        "color": "#00b048",
        "semantics": "+P30D .. P100Y",
        "description": null,
        "deprecated": false
      }
    ],
    "attribute": false,
    "supportsMultiple": false,
    "supportsRequired": true,
    "supportsTagging": true,
    "supportsAlphabeticalOrdering": false,
    "supportsColor": true,
    "userEditable": true
  }
]

Responses

Status	Meaning	Description	Schema
200	OK	none	Inline

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» id	string	true	none	Dimension unique ID
» code	string	true	none	Dimension code (used in URLs, filters, anchors, etc.)
» datatype	string	true	none	Dimension datatype (e.g. UserDefined, Date, ProjectMember, etc.)
» datatypeOptions	object	true	none	Options of the datatype, configuring behavior
»» additionalProperties	object	false	none	none
» label	string	true	none	Dimension human friendly name
» description	string	true	none	Dimension long description, if any
» required	boolean	true	none	Whether a value is required on cards
» supportsRequired	boolean	true	none	Whether the users can decided whether the dimension is required
» tagging	boolean	true	none	Whether users can add/edit values in boards and cards (aka unlocked)
» supportsTagging	boolean	true	none	Whether users can choose to lock/unlock the dimension
» multiple	boolean	true	none	Whether multiple values can be choosen on cards
» supportsMultiple	boolean	true	none	Whether the dimension datatype supports multiple values
» supportsAlphabeticalOrdering	boolean	true	none	Whether values can be ordered alphabetically
» userEditable	boolean	true	none	Whether values can be choosen by end-users on cards
» attribute	boolean	true	none	Whether this dimension is a fixed card attribute (deprecated)
» supportsColor	boolean	true	none	Whether the dimension supports colors on values
» ordering	integer	true	none	Order index of the dimension in the project
» semanticsType	string	true	none	Semantics of the dimension values
» relevantKinds	[string]	true	none	For what card kinds this dimension is relevant
» values	[object]	true	none	The dimension list of values
»» additionalProperties	object	false	none	none
»» id	string	true	none	ID for the value (unique inside the dimension)
»» label	string	true	none	Human friendly label of the value
»» semantics	string	true	none	Filtering semantics, if any
»» color	string	true	none	Value color, if any
»» ordering	integer	true	none	Ordering of the value within the collection
»» description	string	false	none	Description of the value, if any
»» placeholder	string	false	none	Placeholder of the value, if any
»» deprecated	boolean	true	none	Whether the value is deprecated
» deleted	boolean	true	none	Whether the dimension has been deleted
» deletedAt	string	true	none	When this dimension was deleted, if deleted
» deletedBy	string	true	none	Who deleted this dimension, if deleted

Create dimension

Code samples

const inputBody = '{
  "label": "Priority",
  "required": true,
  "multiple": true,
  "tagging": false,
  "datatype": "UserDefined",
  "datatypeOptions": {},
  "values": [
    {
      "id": "low",
      "label": "Low"
    },
    {
      "id": "medium",
      "label": "Medium"
    },
    {
      "id": "high",
      "label": "High"
    }
  ]
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('/dimensions',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.post '/dimensions',
  params: {
  }, headers: headers

p JSON.parse(result)

# You can also use wget
curl -X POST /dimensions \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

POST /dimensions

Creates a new project dimension

Body parameter

Use the UserDefined datatype to create a new "Track your own list" dimension

{
  "label": "Priority",
  "required": true,
  "multiple": true,
  "tagging": false,
  "datatype": "UserDefined",
  "datatypeOptions": {},
  "values": [
    {
      "id": "low",
      "label": "Low"
    },
    {
      "id": "medium",
      "label": "Medium"
    },
    {
      "id": "high",
      "label": "High"
    }
  ]
}

Parameters

Name	In	Type	Required	Description
additionalProperties	body	any	false	none
label	body	string	true	Dimension human friendly name
description	body	string	false	Dimension long description, if any
tagging	body	boolean	true	Whether users can add/edit values in boards and cards (aka unlocked)
required	body	boolean	true	Whether a value is required on cards
multiple	body	boolean	true	Whether multiple values can be choosen on cards
ordering	body	integer	false	Order index of the dimension in the project
datatype	body	string	false	Dimension datatype (e.g. UserDefined, Date, ProjectMember, etc.)
datatypeOptions	body	object	false	Options of the datatype, configuring behavior
» additionalProperties	body	object	false	none
semanticsType	body	string	false	Semantics of the dimension values
relevantKinds	body	[string]	false	For what card kinds this dimension is relevant
values	body	[object]	false	The dimension list of values
» additionalProperties	body	any	false	none
» dimension	body	string	false	Dimension id or code
» id	body	string	false	Value id
» label	body	string	true	Human friendly label of the value
» semantics	body	string	false	Filtering semantics, if any
» color	body	string	false	Value color, if any
» ordering	body	integer	false	Ordering of the value within the collection
» description	body	string	false	Description of the value, if any
» placeholder	body	string	false	Placeholder of the value, if any

Example responses

Use the UserDefined datatype to create a new "Track your own list" dimension

{
  "code": "priority",
  "ordering": 420000,
  "label": "Priority",
  "tagging": false,
  "multiple": true,
  "required": true,
  "id": "b443a4b5-13d8-4b77-ae74-0f084268877c",
  "deleted": false,
  "deletedAt": null,
  "deletedBy": null,
  "description": null,
  "semanticsType": null,
  "datatype": "UserDefined",
  "datatypeOptions": {},
  "relevantKinds": [],
  "values": [
    {
      "id": null,
      "label": "No value",
      "semantics": null,
      "ordering": -1,
      "color": "#ffffff",
      "description": null,
      "deprecated": false
    },
    {
      "id": "low",
      "label": "Low",
      "ordering": 10000,
      "color": "#ffffff",
      "semantics": null,
      "description": null,
      "deprecated": false
    },
    {
      "id": "medium",
      "label": "Medium",
      "ordering": 20000,
      "color": "#ffffff",
      "semantics": null,
      "description": null,
      "deprecated": false
    },
    {
      "id": "high",
      "label": "High",
      "ordering": 30000,
      "color": "#ffffff",
      "semantics": null,
      "description": null,
      "deprecated": false
    }
  ],
  "attribute": false,
  "supportsMultiple": true,
  "supportsRequired": true,
  "supportsTagging": true,
  "supportsAlphabeticalOrdering": true,
  "supportsColor": true,
  "userEditable": true
}

Responses

Status	Meaning	Description	Schema
201	Created	none	Inline

Response Schema

Status Code 201

Name	Type	Required	Restrictions	Description
» id	string	true	none	Dimension unique ID
» code	string	true	none	Dimension code (used in URLs, filters, anchors, etc.)
» datatype	string	true	none	Dimension datatype (e.g. UserDefined, Date, ProjectMember, etc.)
» datatypeOptions	object	true	none	Options of the datatype, configuring behavior
»» additionalProperties	object	false	none	none
» label	string	true	none	Dimension human friendly name
» description	string	true	none	Dimension long description, if any
» required	boolean	true	none	Whether a value is required on cards
» supportsRequired	boolean	true	none	Whether the users can decided whether the dimension is required
» tagging	boolean	true	none	Whether users can add/edit values in boards and cards (aka unlocked)
» supportsTagging	boolean	true	none	Whether users can choose to lock/unlock the dimension
» multiple	boolean	true	none	Whether multiple values can be choosen on cards
» supportsMultiple	boolean	true	none	Whether the dimension datatype supports multiple values
» supportsAlphabeticalOrdering	boolean	true	none	Whether values can be ordered alphabetically
» userEditable	boolean	true	none	Whether values can be choosen by end-users on cards
» attribute	boolean	true	none	Whether this dimension is a fixed card attribute (deprecated)
» supportsColor	boolean	true	none	Whether the dimension supports colors on values
» ordering	integer	true	none	Order index of the dimension in the project
» semanticsType	string	true	none	Semantics of the dimension values
» relevantKinds	[string]	true	none	For what card kinds this dimension is relevant
» values	[object]	true	none	The dimension list of values
»» additionalProperties	object	false	none	none
»» id	string	true	none	ID for the value (unique inside the dimension)
»» label	string	true	none	Human friendly label of the value
»» semantics	string	true	none	Filtering semantics, if any
»» color	string	true	none	Value color, if any
»» ordering	integer	true	none	Ordering of the value within the collection
»» description	string	false	none	Description of the value, if any
»» placeholder	string	false	none	Placeholder of the value, if any
»» deprecated	boolean	true	none	Whether the value is deprecated
» deleted	boolean	true	none	Whether the dimension has been deleted
» deletedAt	string	true	none	When this dimension was deleted, if deleted
» deletedBy	string	true	none	Who deleted this dimension, if deleted

Dimension values

Get dimension value

Code samples


const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('/dimensions/{dimension}/values/{id}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.get '/dimensions/{dimension}/values/{id}',
  params: {
  }, headers: headers

p JSON.parse(result)

# You can also use wget
curl -X GET /dimensions/{dimension}/values/{id} \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

GET /dimensions/{dimension}/values/{id}

Returns the details of a dimension value

Parameters

Name	In	Type	Required	Description
dimension	path	string	true	none
id	path	string	true	none

Example responses

Getting the ongoing value of the progress dimension

{
  "id": "ongoing",
  "label": "Ongoing",
  "ordering": 20000,
  "color": "#f77d00",
  "semantics": null,
  "description": null,
  "deprecated": false
}

Responses

Status	Meaning	Description	Schema
200	OK	none	Inline

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» additionalProperties	object	false	none	none
» id	string	true	none	ID for the value (unique inside the dimension)
» label	string	true	none	Human friendly label of the value
» semantics	string	true	none	Filtering semantics, if any
» color	string	true	none	Value color, if any
» ordering	integer	true	none	Ordering of the value within the collection
» description	string	false	none	Description of the value, if any
» placeholder	string	false	none	Placeholder of the value, if any
» deprecated	boolean	true	none	Whether the value is deprecated

Update dimension value

Code samples

const inputBody = '{
  "label": "Current work"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('/dimensions/{dimension}/values/{id}',
{
  method: 'PATCH',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.patch '/dimensions/{dimension}/values/{id}',
  params: {
  }, headers: headers

p JSON.parse(result)

# You can also use wget
curl -X PATCH /dimensions/{dimension}/values/{id} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

PATCH /dimensions/{dimension}/values/{id}

Allows updating a dimension value

Body parameter

Changing the label of the Ongoing progress step

{
  "label": "Current work"
}

Parameters

Name	In	Type	Required	Description
dimension	path	string	true	Dimension id or code
id	path	string	true	Value id
additionalProperties	body	any	false	none
label	body	string	false	Human friendly label of the value
semantics	body	string	false	Filtering semantics, if any
color	body	string	false	Value color, if any
ordering	body	integer	false	Ordering of the value within the collection
description	body	string	false	Description of the value, if any
placeholder	body	string	false	Placeholder of the value, if any

Example responses

Changing the label of the Ongoing progress step

{
  "id": "ongoing",
  "label": "Current work",
  "ordering": 20000,
  "color": "#f77d00",
  "semantics": null,
  "description": null,
  "deprecated": false
}

Responses

Status	Meaning	Description	Schema
200	OK	none	Inline

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» additionalProperties	object	false	none	none
» id	string	true	none	ID for the value (unique inside the dimension)
» label	string	true	none	Human friendly label of the value
» semantics	string	true	none	Filtering semantics, if any
» color	string	true	none	Value color, if any
» ordering	integer	true	none	Ordering of the value within the collection
» description	string	false	none	Description of the value, if any
» placeholder	string	false	none	Placeholder of the value, if any
» deprecated	boolean	true	none	Whether the value is deprecated

Delete dimension value

Code samples

const inputBody = '{
  "onExisting": "replace",
  "replaceBy": "todo"
}';
const headers = {
  'Content-Type':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('/dimensions/{dimension}/values/{id}',
{
  method: 'DELETE',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.delete '/dimensions/{dimension}/values/{id}',
  params: {
  }, headers: headers

p JSON.parse(result)

# You can also use wget
curl -X DELETE /dimensions/{dimension}/values/{id} \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {access-token}'

DELETE /dimensions/{dimension}/values/{id}

Deletes a given dimension value, replacing it by another value if needed

Body parameter

Dropping the ongoing step, and moving all cards to todo

{
  "onExisting": "replace",
  "replaceBy": "todo"
}

Parameters

Name	In	Type	Required	Description
dimension	path	string	true	Dimension id or code
id	path	string	true	Value id
onExisting	body	string	true	Behavior if a value is used (fail, setNone, or replace)
replaceBy	body	string	false	ID of the replacement value, if any

Responses

Status	Meaning	Description	Schema
204	No Content	none	None

Create dimension value

Code samples

const inputBody = '{
  "code": "abandonned",
  "label": "Abandonned",
  "color": "black",
  "ordering": 99,
  "semantics": null,
  "description": "Drop here when a task has been abandonned"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('/dimensions/{dimension}/values',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.post '/dimensions/{dimension}/values',
  params: {
  }, headers: headers

p JSON.parse(result)

# You can also use wget
curl -X POST /dimensions/{dimension}/values \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

POST /dimensions/{dimension}/values

Creates a new dimension value

Body parameter

Creating an Abandonned step along the progress dimension

{
  "code": "abandonned",
  "label": "Abandonned",
  "color": "black",
  "ordering": 99,
  "semantics": null,
  "description": "Drop here when a task has been abandonned"
}

Parameters

Name	In	Type	Required	Description
dimension	path	string	true	Dimension id or code
additionalProperties	body	any	false	none
id	body	string	false	Value id
label	body	string	true	Human friendly label of the value
semantics	body	string	false	Filtering semantics, if any
color	body	string	false	Value color, if any
ordering	body	integer	false	Ordering of the value within the collection
description	body	string	false	Description of the value, if any
placeholder	body	string	false	Placeholder of the value, if any

Example responses

Creating an Abandonned step along the progress dimension

{
  "id": "abandonned",
  "label": "Abandonned",
  "ordering": 99,
  "color": "black",
  "semantics": null,
  "description": "Drop here when a task has been abandonned",
  "deprecated": false
}

Responses

Status	Meaning	Description	Schema
201	Created	none	Inline

Response Schema

Status Code 201

Name	Type	Required	Restrictions	Description
» additionalProperties	object	false	none	none
» id	string	true	none	ID for the value (unique inside the dimension)
» label	string	true	none	Human friendly label of the value
» semantics	string	true	none	Filtering semantics, if any
» color	string	true	none	Value color, if any
» ordering	integer	true	none	Ordering of the value within the collection
» description	string	false	none	Description of the value, if any
» placeholder	string	false	none	Placeholder of the value, if any
» deprecated	boolean	true	none	Whether the value is deprecated

Stories (aka Cards)

Get story

Code samples


const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('/stories/{id}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.get '/stories/{id}',
  params: {
  }, headers: headers

p JSON.parse(result)

# You can also use wget
curl -X GET /stories/{id} \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

GET /stories/{id}

Returns full details of a story, including attachments and linked cards.

Parameters

Name	In	Type	Required	Description
id	path	any	true	The UUID and autoincrement identifier are supported

Example responses

Get a story using it's uuid

{
  "id": "8ed76538-ee9a-4b39-9407-6b392a7ddc35",
  "identifier": 2,
  "project": "8c34924f-21ca-406b-aaaa-749ad3d2f4fb",
  "title": "Document the RESTful API",
  "createdAt": "2025-03-21T16:32:17+00:00",
  "createdBy": "Bernard",
  "updatedAt": "2025-03-24T13:23:07+00:00",
  "specification": "",
  "kind": "todo",
  "progress": "ongoing",
  "assignee": "Bernard",
  "due_date": null,
  "attachments": [],
  "linked": []
}

Responses

Status	Meaning	Description	Schema
200	OK	none	Inline

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» additionalProperties	object	false	none	none
» id	string	true	none	Unique story ID
» identifier	integer	true	none	Unique story identifier (autonumber)
» title	string	true	none	Story title
» specification	string	true	none	Story specification, also known as description
» createdBy	string	true	none	Who created the story
» createdAt	string	true	none	When was the story created
» updatedAt	string	true	none	When was the story last updated
» linked	[object]	true	none	Linked stories
»» additionalProperties	object	false	none	none
»» id	string	true	none	Unique story ID
»» identifier	integer	true	none	Unique story identifier (autonumber)
»» title	string	true	none	Story title
»» createdBy	string	false	none	Who created the story
»» createdAt	string	false	none	When was the story created
»» updatedAt	string	false	none	When was the story last updated
» attachments	[object]	true	none	Story attachments
»» id	string	true	none	Attachement unique ID
»» filename	string	true	none	Attachment file name
»» url	string	true	none	URL of the attachement, relative to the project's imgBaseUrl
»» description	string	true	none	Attachment description, if any
»» sizeInBytes	integer	true	none	Attachment size in bytes
»» isCover	boolean	true	none	Whether the attachment is used as story cover
»» createdAt	string	true	none	When was the attachent created
»» createdBy	string	true	none	Who created the attachent

Update story

Code samples

const inputBody = '{
  "title": "A new title for the todo",
  "assignee": "Marc"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('/stories/{id}',
{
  method: 'PATCH',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.patch '/stories/{id}',
  params: {
  }, headers: headers

p JSON.parse(result)

# You can also use wget
curl -X PATCH /stories/{id} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

PATCH /stories/{id}

Updates a story using a patch representation

Body parameter

Apply a patch to modify a few story fields

{
  "title": "A new title for the todo",
  "assignee": "Marc"
}

Parameters

Name	In	Type	Required	Description
id	path	string	true	ID or identifier of the story
additionalProperties	body	object	false	none
board	body	string	false	Board id or location in which the update takes place
title	body	string	false	Story title
specification	body	string	false	Story specification, also known as description

Example responses

Apply a patch to modify a few story fields

{
  "id": "8ed76538-ee9a-4b39-9407-6b392a7ddc35",
  "identifier": 2,
  "project": "8c34924f-21ca-406b-aaaa-749ad3d2f4fb",
  "title": "A new title for the todo",
  "createdAt": "2025-03-21T16:32:17+00:00",
  "createdBy": "Bernard",
  "updatedAt": "2025-03-27T17:02:18+00:00",
  "specification": "",
  "kind": "todo",
  "progress": "ongoing",
  "assignee": "Marc",
  "due_date": null,
  "attachments": [],
  "linked": []
}

Responses

Status	Meaning	Description	Schema
200	OK	none	Inline

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» additionalProperties	object	false	none	none
» id	string	true	none	Unique story ID
» identifier	integer	true	none	Unique story identifier (autonumber)
» title	string	true	none	Story title
» specification	string	true	none	Story specification, also known as description
» createdBy	string	true	none	Who created the story
» createdAt	string	true	none	When was the story created
» updatedAt	string	true	none	When was the story last updated
» linked	[object]	true	none	Linked stories
»» additionalProperties	object	false	none	none
»» id	string	true	none	Unique story ID
»» identifier	integer	true	none	Unique story identifier (autonumber)
»» title	string	true	none	Story title
»» createdBy	string	false	none	Who created the story
»» createdAt	string	false	none	When was the story created
»» updatedAt	string	false	none	When was the story last updated
» attachments	[object]	true	none	Story attachments
»» id	string	true	none	Attachement unique ID
»» filename	string	true	none	Attachment file name
»» url	string	true	none	URL of the attachement, relative to the project's imgBaseUrl
»» description	string	true	none	Attachment description, if any
»» sizeInBytes	integer	true	none	Attachment size in bytes
»» isCover	boolean	true	none	Whether the attachment is used as story cover
»» createdAt	string	true	none	When was the attachent created
»» createdBy	string	true	none	Who created the attachent

Delete story

Code samples

const inputBody = '{}';
const headers = {
  'Content-Type':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('/stories/{id}',
{
  method: 'DELETE',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.delete '/stories/{id}',
  params: {
  }, headers: headers

p JSON.parse(result)

# You can also use wget
curl -X DELETE /stories/{id} \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {access-token}'

DELETE /stories/{id}

Allows deleting a story. The story attachments are removed as well, but not the linked cards.

Body parameter

Delete a story by UUID

{}

Parameters

Name	In	Type	Required	Description
id	path	string	true	none
onExisting	body	string	false	none
replaceBy	body	integer	false	none

Responses

Status	Meaning	Description	Schema
204	No Content	none	None

Create story

Code samples

const inputBody = '{
  "kind": "todo",
  "progress": "ongoing",
  "assignee": "Bernard",
  "title": "Document the API"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('/stories',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.post '/stories',
  params: {
  }, headers: headers

p JSON.parse(result)

# You can also use wget
curl -X POST /stories \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

POST /stories

Allows creating a new project story (aka card).

Body parameter

Create a new story

{
  "kind": "todo",
  "progress": "ongoing",
  "assignee": "Bernard",
  "title": "Document the API"
}

Parameters

Name	In	Type	Required	Description
additionalProperties	body	object	false	none
id	body	string	false	ID or identifier of the story
title	body	string	true	Story title
specification	body	string	false	Story specification, also known as description
attachments	body	[object]	false	List of story attachments to create
» filename	body	string	true	Attachment file name
» url	body	string	true	URL of the attachement, relative to the project's imgBaseUrl
» isCover	body	boolean	true	Whether the attachment is used as story cover
» description	body	string	true	Whether the attachment is used as story cover
» sizeInBytes	body	integer	true	Attachment size in bytes

Example responses

Create a new story

{
  "id": "2d408a92-901e-4b96-9294-6b5a45c461aa",
  "identifier": 5,
  "project": "8c34924f-21ca-406b-aaaa-749ad3d2f4fb",
  "title": "Document the API",
  "createdAt": "2025-03-27T17:02:18+00:00",
  "createdBy": "Bernard",
  "updatedAt": "2025-03-27T17:02:18+00:00",
  "specification": "",
  "kind": "todo",
  "progress": "ongoing",
  "assignee": "Bernard",
  "due_date": null,
  "attachments": [],
  "linked": []
}

Responses

Status	Meaning	Description	Schema
201	Created	none	Inline

Response Schema

Status Code 201

Name	Type	Required	Restrictions	Description
» additionalProperties	object	false	none	none
» id	string	true	none	Unique story ID
» identifier	integer	true	none	Unique story identifier (autonumber)
» title	string	true	none	Story title
» specification	string	true	none	Story specification, also known as description
» createdBy	string	true	none	Who created the story
» createdAt	string	true	none	When was the story created
» updatedAt	string	true	none	When was the story last updated
» linked	[object]	true	none	Linked stories
»» additionalProperties	object	false	none	none
»» id	string	true	none	Unique story ID
»» identifier	integer	true	none	Unique story identifier (autonumber)
»» title	string	true	none	Story title
»» createdBy	string	false	none	Who created the story
»» createdAt	string	false	none	When was the story created
»» updatedAt	string	false	none	When was the story last updated
» attachments	[object]	true	none	Story attachments
»» id	string	true	none	Attachement unique ID
»» filename	string	true	none	Attachment file name
»» url	string	true	none	URL of the attachement, relative to the project's imgBaseUrl
»» description	string	true	none	Attachment description, if any
»» sizeInBytes	integer	true	none	Attachment size in bytes
»» isCover	boolean	true	none	Whether the attachment is used as story cover
»» createdAt	string	true	none	When was the attachent created
»» createdBy	string	true	none	Who created the attachent

Boards

Get board

Code samples


const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('/boards/{id}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.get '/boards/{id}',
  params: {
  }, headers: headers

p JSON.parse(result)

# You can also use wget
curl -X GET /boards/{id} \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

GET /boards/{id}

Returns the complete definition of a board

Parameters

Name	In	Type	Required	Description
id	path	string	true	Either the board id or location

Example responses

When getting a board, you can use both the board ID of the human-friendly location field in URL.

{
  "id": "7a95ea0d-b029-41c8-a95d-b65a4a356ea4",
  "label": "Kanban",
  "location": "kanban",
  "mode": "kanban",
  "objective": "",
  "objectiveModal": false,
  "decksOpen": false,
  "coloredDimension": "progress",
  "compactDisplay": false,
  "compactDecks": false,
  "explorerDecks": false,
  "background": "lagoon",
  "anchors": {
    "displayBy": [
      "progress"
    ],
    "cards": [
      "assignee"
    ],
    "required": [
      "progress"
    ]
  },
  "filters": {
    "kind": [
      "todo"
    ],
    "progress": [
      "todo",
      "ongoing"
    ]
  },
  "summaries": [],
  "workspacePermissions": [
    {
      "workspace": "admins",
      "canRead": true,
      "canWrite": true,
      "canManage": true
    }
  ],
  "createdBy": "Bernard",
  "createdAt": "2025-03-21T16:32:45+00:00",
  "dimensions": [
    {
      "code": "kind",
      "ordering": 20000,
      "label": "Kind",
      "tagging": true,
      "multiple": false,
      "required": true,
      "id": "0d3c755c-b3d3-4940-947e-e90de07e571f",
      "deleted": false,
      "deletedAt": null,
      "deletedBy": null,
      "description": null,
      "semanticsType": null,
      "datatype": "Kind",
      "datatypeOptions": {},
      "relevantKinds": [],
      "values": [
        {
          "id": null,
          "label": "No value",
          "semantics": null,
          "ordering": -1,
          "color": "#ffffff",
          "description": null,
          "deprecated": false
        },
        {
          "id": "todo",
          "label": "Todo",
          "color": "#b7137e",
          "ordering": 1000000,
          "semantics": null,
          "colorDimension": null,
          "description": null,
          "placeholder": null,
          "deprecated": false,
          "summaryDimensions": []
        }
      ],
      "attribute": false,
      "supportsMultiple": false,
      "supportsRequired": true,
      "supportsTagging": true,
      "supportsAlphabeticalOrdering": true,
      "supportsColor": true,
      "userEditable": true
    },
    {
      "code": "identifier",
      "ordering": 1000,
      "label": "Card n°",
      "tagging": false,
      "multiple": false,
      "required": true,
      "id": "af352fc7-8c9b-4030-934e-da0b1f737741",
      "deleted": false,
      "deletedAt": null,
      "deletedBy": null,
      "description": null,
      "semanticsType": null,
      "datatype": "Identifier",
      "datatypeOptions": {},
      "relevantKinds": [],
      "values": [
        {
          "id": null,
          "label": "No value",
          "semantics": null,
          "ordering": -1,
          "color": "#ffffff",
          "description": null,
          "deprecated": false
        }
      ],
      "attribute": true,
      "supportsMultiple": false,
      "supportsRequired": false,
      "supportsTagging": false,
      "supportsAlphabeticalOrdering": false,
      "supportsColor": false,
      "userEditable": false
    },
    {
      "code": "title",
      "ordering": 1010,
      "label": "Card title",
      "tagging": false,
      "multiple": false,
      "required": false,
      "id": "4e5bf2b8-b0d3-4f5d-b966-e017f7feadda",
      "deleted": false,
      "deletedAt": null,
      "deletedBy": null,
      "description": "Card title",
      "semanticsType": null,
      "datatype": "Title",
      "datatypeOptions": {},
      "relevantKinds": [],
      "values": [
        {
          "id": null,
          "label": "No value",
          "semantics": null,
          "ordering": -1,
          "color": "#ffffff",
          "description": null,
          "deprecated": false
        }
      ],
      "attribute": true,
      "supportsMultiple": false,
      "supportsRequired": false,
      "supportsTagging": false,
      "supportsAlphabeticalOrdering": false,
      "supportsColor": false,
      "userEditable": true
    },
    {
      "code": "specification",
      "ordering": 1011,
      "label": "Card description",
      "tagging": false,
      "multiple": false,
      "required": false,
      "id": "039fdea8-4dd7-488f-85f5-38f2c11eff8a",
      "deleted": false,
      "deletedAt": null,
      "deletedBy": null,
      "description": "Card (Markdown) description",
      "semanticsType": null,
      "datatype": "Specification",
      "datatypeOptions": {},
      "relevantKinds": [],
      "values": [
        {
          "id": null,
          "label": "No value",
          "semantics": null,
          "ordering": -1,
          "color": "#ffffff",
          "description": null,
          "deprecated": false
        }
      ],
      "attribute": true,
      "supportsMultiple": false,
      "supportsRequired": false,
      "supportsTagging": false,
      "supportsAlphabeticalOrdering": false,
      "supportsColor": false,
      "userEditable": true
    },
    {
      "code": "progress",
      "ordering": 120000,
      "label": "Progress",
      "tagging": true,
      "multiple": false,
      "required": false,
      "id": "8582be6e-283e-4633-9cc5-2f2ab96a43bb",
      "deleted": false,
      "deletedAt": null,
      "deletedBy": null,
      "description": null,
      "semanticsType": null,
      "datatype": "Progress",
      "datatypeOptions": {},
      "relevantKinds": [],
      "values": [
        {
          "id": null,
          "label": "No value",
          "semantics": null,
          "ordering": -1,
          "color": "#ffffff",
          "description": null,
          "deprecated": false
        },
        {
          "id": "todo",
          "label": "Todo",
          "ordering": 10000,
          "color": "#e01514",
          "semantics": null,
          "description": null,
          "deprecated": false
        },
        {
          "id": "ongoing",
          "label": "Ongoing",
          "ordering": 20000,
          "color": "#f77d00",
          "semantics": null,
          "description": null,
          "deprecated": false
        },
        {
          "id": "done",
          "label": "Done",
          "ordering": 30000,
          "color": "#00b048",
          "semantics": null,
          "description": null,
          "deprecated": false
        }
      ],
      "attribute": false,
      "supportsMultiple": false,
      "supportsRequired": true,
      "supportsTagging": true,
      "supportsAlphabeticalOrdering": true,
      "supportsColor": true,
      "userEditable": true
    },
    {
      "code": "assignee",
      "ordering": 220000,
      "label": "Assignee",
      "tagging": true,
      "multiple": false,
      "required": false,
      "id": "0334196e-1aba-4049-9769-b8fde2eb2227",
      "deleted": false,
      "deletedAt": null,
      "deletedBy": null,
      "description": null,
      "semanticsType": null,
      "datatype": "ProjectMember",
      "datatypeOptions": {},
      "relevantKinds": [],
      "values": [
        {
          "id": null,
          "label": "No value",
          "semantics": null,
          "ordering": -1,
          "color": "#ffffff",
          "description": null,
          "deprecated": false
        },
        {
          "id": "Bernard",
          "label": "Bernard",
          "ordering": 1000000,
          "color": "#ffffff",
          "semantics": "Bernard",
          "description": null,
          "deprecated": false
        },
        {
          "id": "Victor",
          "label": "Victor",
          "ordering": 2000000,
          "color": "#ffffff",
          "semantics": "Victor",
          "description": null,
          "deprecated": false
        },
        {
          "id": "Marc",
          "label": "Marc",
          "ordering": 3000000,
          "color": "#ffffff",
          "semantics": "Marc",
          "description": null,
          "deprecated": false
        }
      ],
      "attribute": false,
      "supportsMultiple": true,
      "supportsRequired": true,
      "supportsTagging": true,
      "supportsAlphabeticalOrdering": true,
      "supportsColor": true,
      "userEditable": true
    },
    {
      "code": "due_date",
      "ordering": 320000,
      "label": "Due date",
      "tagging": false,
      "multiple": false,
      "required": false,
      "id": "44c78647-0a68-48a2-b6e0-0fd926752f4f",
      "deleted": false,
      "deletedAt": null,
      "deletedBy": null,
      "description": null,
      "semanticsType": "DateRange",
      "datatype": "DueDate",
      "datatypeOptions": {},
      "relevantKinds": [],
      "values": [
        {
          "id": null,
          "label": "No value",
          "semantics": null,
          "ordering": -1,
          "color": "#ffffff",
          "description": null,
          "deprecated": false
        },
        {
          "id": "late_",
          "label": "Late!",
          "ordering": 10000,
          "color": "#202020",
          "semantics": "-BOT",
          "description": null,
          "deprecated": false
        },
        {
          "id": "late_tomorrow",
          "label": "Late tomorrow",
          "ordering": 20000,
          "color": "#e01514",
          "semantics": "+P1D",
          "description": null,
          "deprecated": false
        },
        {
          "id": "late_in_3_days",
          "label": "Late in 3 days",
          "ordering": 30000,
          "color": "#a85319",
          "semantics": "+P1D .. +P3D",
          "description": null,
          "deprecated": false
        },
        {
          "id": "next_7_days",
          "label": "Next 7 days",
          "ordering": 40000,
          "color": "#ffba00",
          "semantics": "+P3D .. +P7D",
          "description": null,
          "deprecated": false
        },
        {
          "id": "next_15_days",
          "label": "Next 15 days",
          "ordering": 50000,
          "color": "#99cc2d",
          "semantics": "+P7D .. +P15D",
          "description": null,
          "deprecated": false
        },
        {
          "id": "next_30_days",
          "label": "Next 30 days",
          "ordering": 60000,
          "color": "#00b048",
          "semantics": "+P15D .. +P30D",
          "description": null,
          "deprecated": false
        },
        {
          "id": "later",
          "label": "Later",
          "ordering": 70000,
          "color": "#00b048",
          "semantics": "+P30D .. P100Y",
          "description": null,
          "deprecated": false
        }
      ],
      "attribute": false,
      "supportsMultiple": false,
      "supportsRequired": true,
      "supportsTagging": true,
      "supportsAlphabeticalOrdering": false,
      "supportsColor": true,
      "userEditable": true
    }
  ],
  "ordering": 2,
  "ganttScale": null,
  "displayDimensionLabels": false,
  "manualDimensionsInDecks": false,
  "displayDimensionsOnCards": true,
  "displayNoneOnCards": false,
  "connector": "BaseConnector",
  "importers": [],
  "extraSettings": {
    "onCardClick": {
      "type": "fullEdit",
      "options": {}
    }
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	none	Inline

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» id	string	true	none	Board unique ID
» label	string	true	none	Board human friendly name
» location	string	true	none	Board friendly location (used in url)
» mode	string	true	none	Board mode (e.g. grid, list, kanban)
» connector	string	true	none	Reserved (use BaseConnector)
» objective	string	true	none	Board objective (shown to users on load)
» objectiveModal	boolean	true	none	Whether the objective must be shown to users
» decksOpen	boolean	true	none	Whether the filter decks are open on board load
» coloredDimension	string	true	none	Dimension (code) used for card colors
» compactDisplay	boolean	true	none	Whether empty columns/rows/categories are hidden
» compactDecks	boolean	true	none	Whether unused values are hidden in filters
» explorerDecks	boolean	true	none	Whether the filter decks use left-to-right layout
» background	string	true	none	Name of the board background
» createdBy	string	true	none	Who created the board
» createdAt	string	true	none	When was the board created
» ordering	integer	true	none	Order index of the board in the collection
» ganttScale	string	true	none	Scale used in the gantt mode
» manualDimensionsInDecks	boolean	true	none	Whether the user selected specific dimensions to be shown in decks
» displayDimensionsOnCards	boolean	true	none	Whether dimensions are shown on cards
» displayDimensionLabels	boolean	true	none	Whether dimension labels are shown on cards
» displayNoneOnCards	boolean	true	none	Whether empty values are shown on carts
» dimensions	[object]	true	none	List of board dimensions
»» id	string	true	none	Dimension unique ID
»» code	string	true	none	Dimension code (used in URLs, filters, anchors, etc.)
»» datatype	string	true	none	Dimension datatype (e.g. UserDefined, Date, ProjectMember, etc.)
»» datatypeOptions	object	true	none	Options of the datatype, configuring behavior
»»» additionalProperties	object	false	none	none
»» label	string	true	none	Dimension human friendly name
»» description	string	true	none	Dimension long description, if any
»» required	boolean	true	none	Whether a value is required on cards
»» supportsRequired	boolean	true	none	Whether the users can decided whether the dimension is required
»» tagging	boolean	true	none	Whether users can add/edit values in boards and cards (aka unlocked)
»» supportsTagging	boolean	true	none	Whether users can choose to lock/unlock the dimension
»» multiple	boolean	true	none	Whether multiple values can be choosen on cards
»» supportsMultiple	boolean	true	none	Whether the dimension datatype supports multiple values
»» supportsAlphabeticalOrdering	boolean	true	none	Whether values can be ordered alphabetically
»» userEditable	boolean	true	none	Whether values can be choosen by end-users on cards
»» attribute	boolean	true	none	Whether this dimension is a fixed card attribute (deprecated)
»» supportsColor	boolean	true	none	Whether the dimension supports colors on values
»» ordering	integer	true	none	Order index of the dimension in the project
»» semanticsType	string	true	none	Semantics of the dimension values
»» relevantKinds	[string]	true	none	For what card kinds this dimension is relevant
»» values	[object]	true	none	The dimension list of values
»»» additionalProperties	object	false	none	none
»»» id	string	true	none	ID for the value (unique inside the dimension)
»»» label	string	true	none	Human friendly label of the value
»»» semantics	string	true	none	Filtering semantics, if any
»»» color	string	true	none	Value color, if any
»»» ordering	integer	true	none	Ordering of the value within the collection
»»» description	string	false	none	Description of the value, if any
»»» placeholder	string	false	none	Placeholder of the value, if any
»»» deprecated	boolean	true	none	Whether the value is deprecated
»» deleted	boolean	true	none	Whether the dimension has been deleted
»» deletedAt	string	true	none	When this dimension was deleted, if deleted
»» deletedBy	string	true	none	Who deleted this dimension, if deleted
» anchors	object	true	none	List of board anchors, see Data Model
»» additionalProperties	any	false	none	none
»» decks	[string]	false	none	Dimensions to show in filters deck
»» displayBy	[string]	false	none	Dimension(s) used to group cards in board
»» cards	[string]	false	none	Dimensions to show on cards
»» ordering	[string]	false	none	Dimensions to use to sort cards in board
»» required	[string]	false	none	Dimensions required in the board
»» gantt	[string]	false	none	Dimensions used for Gantt mode
»» hierarchyBy	[string]	false	none	Dimensions used to hierarchy in List mode
»» seriesBy	[string]	false	none	Dimensions used to as series in Chart mode
»» rowsBy	[string]	false	none	Dimensions used as rows in Matrix mode
» filters	object	true	none	List of board filters, see Data Model
» workspacePermissions	[object]	true	none	List of workspaces permissions on this board
»» workspace	string	true	none	Workspace code
»» canRead	boolean	true	none	Whether the users can read cards
»» canWrite	boolean	true	none	Whether the users can write cards
»» canManage	boolean	true	none	Whether the users can manage cards
» summaries	[object]	true	none	List of board summaries shown
»» code	string	true	none	Summary function code
»» label	string	true	none	Summary function label
»» expr	string	true	none	Formal expression
»» ordering	integer	true	none	Summary order index in collection
» importers	[object]	false	none	List of board importers
» extraSettings	object	true	none	Extra board settings used by the various modes
»» onCardClick	object	false	none	Behavior on card click
»»» type	string	true	none	Type of action
»»» options	object	true	none	Action options
»»»» additionalProperties	string	false	none	none
»» swipeGestures	object	false	none	Behavior when swiping on mobile
»»» left	object	false	none	Behavior when swipping left
»»»» type	string	true	none	Type of action
»»»» value	string	false	none	Dimension value ID, if any
»»» right	object	false	none	Behavior when swipping right
»»»» type	string	true	none	Type of action
»»»» value	string	false	none	Dimension value ID, if any
»»» up	object	false	none	Behavior when swipping up
»»»» type	string	true	none	Type of action
»»»» value	string	false	none	Dimension value ID, if any
»»» down	object	false	none	Behavior when swipping down
»»»» type	string	true	none	Type of action
»»»» value	string	false	none	Dimension value ID, if any
»» chartOptions	object	false	none	Options for chart mode
»»» type	string	true	none	none

Save board

Code samples

const inputBody = '{
  "label": "A new label",
  "location": "a-new-location"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('/boards/{id}',
{
  method: 'PATCH',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.patch '/boards/{id}',
  params: {
  }, headers: headers

p JSON.parse(result)

# You can also use wget
curl -X PATCH /boards/{id} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

PATCH /boards/{id}

Updates the definition of a board

Body parameter

Update some fields of a board. Both the ID or the board location can be used as URL parameter.

{
  "label": "A new label",
  "location": "a-new-location"
}

Parameters

Name	In	Type	Required	Description
id	path	string	true	Either the board id or location
additionalProperties	body	any	false	none
label	body	string	false	Board human friendly name
location	body	string	false	Board friendly location (used in url)
mode	body	string	false	Board mode (e.g. grid, list, kanban)
objective	body	string	false	Board objective (shown to users on load)
objectiveModal	body	boolean	false	Whether the objective must be shown to users
decksOpen	body	boolean	false	Whether the filter decks are open on board load
coloredDimension	body	string	false	Dimension (code) used for card colors
compactDisplay	body	boolean	false	Whether empty columns/rows/categories are hidden
compactDecks	body	boolean	false	Whether unused values are hidden in filters
explorerDecks	body	boolean	false	Whether the filter decks use left-to-right layout
displayDimensionLabels	body	boolean	false	Whether dimension labels are shown on cards
manualDimensionsInDecks	body	boolean	false	Whether the user selected specific dimensions to be shown in decks
displayDimensionsOnCards	body	boolean	false	Whether dimensions are shown on cards
displayNoneOnCards	body	boolean	false	Whether empty values are shown on carts
background	body	string	false	Name of the board background
ganttScale	body	string	false	Scale used in the gantt mode
anchors	body	object	false	List of board anchors, see Data Model
» additionalProperties	body	any	false	none
» decks	body	[string]	false	Dimensions to show in filters deck
» displayBy	body	[string]	false	Dimension(s) used to group cards in board
» cards	body	[string]	false	Dimensions to show on cards
» ordering	body	[string]	false	Dimensions to use to sort cards in board
» required	body	[string]	false	Dimensions required in the board
» gantt	body	[string]	false	Dimensions used for Gantt mode
» hierarchyBy	body	[string]	false	Dimensions used to hierarchy in List mode
» seriesBy	body	[string]	false	Dimensions used to as series in Chart mode
» rowsBy	body	[string]	false	Dimensions used as rows in Matrix mode
filters	body	object	false	List of board filters, see Data Model
summaries	body	[object]	false	List of board summaries shown
» additionalProperties	body	any	false	none
» code	body	string	true	Summary function code
» label	body	string	false	Summary function label
» ordering	body	integer	false	Summary order index in collection
» expr	body	string	false	Formal expression
workspacePermissions	body	[object]	false	List of workspaces permissions on this board
» workspace	body	string	true	Workspace code
» canRead	body	boolean	true	Whether the users can read cards
» canWrite	body	boolean	true	Whether the users can write cards
» canManage	body	boolean	true	Whether the users can manage cards
extraSettings	body	object	false	Extra board settings used by the various modes
» onCardClick	body	object	false	Behavior on card click
»» type	body	string	true	Type of action
»» options	body	object	true	Action options
»»» additionalProperties	body	string	false	none
» swipeGestures	body	object	false	Behavior when swiping on mobile
»» left	body	object	false	Behavior when swipping left
»»» type	body	string	true	Type of action
»»» value	body	string	false	Dimension value ID, if any
»» right	body	object	false	Behavior when swipping right
»»» type	body	string	true	Type of action
»»» value	body	string	false	Dimension value ID, if any
»» up	body	object	false	Behavior when swipping up
»»» type	body	string	true	Type of action
»»» value	body	string	false	Dimension value ID, if any
»» down	body	object	false	Behavior when swipping down
»»» type	body	string	true	Type of action
»»» value	body	string	false	Dimension value ID, if any
» chartOptions	body	object	false	Options for chart mode
»» type	body	string	true	none

Example responses

Update some fields of a board. Both the ID or the board location can be used as URL parameter.

{
  "id": "7a95ea0d-b029-41c8-a95d-b65a4a356ea4",
  "label": "A new label",
  "location": "a-new-location",
  "mode": "kanban",
  "objective": "",
  "objectiveModal": false,
  "decksOpen": false,
  "coloredDimension": "progress",
  "compactDisplay": false,
  "compactDecks": false,
  "explorerDecks": false,
  "background": "lagoon",
  "anchors": {
    "cards": [
      "assignee"
    ],
    "displayBy": [
      "progress"
    ],
    "required": [
      "progress"
    ]
  },
  "filters": {
    "kind": [
      "todo"
    ],
    "progress": [
      "todo",
      "ongoing"
    ]
  },
  "summaries": [],
  "workspacePermissions": [
    {
      "workspace": "admins",
      "canRead": true,
      "canWrite": true,
      "canManage": true
    }
  ],
  "createdBy": "Bernard",
  "createdAt": "2025-03-21T16:32:45+00:00",
  "dimensions": [
    {
      "code": "kind",
      "ordering": 20000,
      "label": "Kind",
      "tagging": true,
      "multiple": false,
      "required": true,
      "id": "0d3c755c-b3d3-4940-947e-e90de07e571f",
      "deleted": false,
      "deletedAt": null,
      "deletedBy": null,
      "description": null,
      "semanticsType": null,
      "datatype": "Kind",
      "datatypeOptions": {},
      "relevantKinds": [],
      "values": [
        {
          "id": null,
          "label": "No value",
          "semantics": null,
          "ordering": -1,
          "color": "#ffffff",
          "description": null,
          "deprecated": false
        },
        {
          "id": "todo",
          "label": "Todo",
          "color": "#b7137e",
          "ordering": 1000000,
          "semantics": null,
          "colorDimension": null,
          "description": null,
          "placeholder": null,
          "deprecated": false,
          "summaryDimensions": []
        }
      ],
      "attribute": false,
      "supportsMultiple": false,
      "supportsRequired": true,
      "supportsTagging": true,
      "supportsAlphabeticalOrdering": true,
      "supportsColor": true,
      "userEditable": true
    },
    {
      "code": "identifier",
      "ordering": 1000,
      "label": "Card n°",
      "tagging": false,
      "multiple": false,
      "required": true,
      "id": "af352fc7-8c9b-4030-934e-da0b1f737741",
      "deleted": false,
      "deletedAt": null,
      "deletedBy": null,
      "description": null,
      "semanticsType": null,
      "datatype": "Identifier",
      "datatypeOptions": {},
      "relevantKinds": [],
      "values": [
        {
          "id": null,
          "label": "No value",
          "semantics": null,
          "ordering": -1,
          "color": "#ffffff",
          "description": null,
          "deprecated": false
        }
      ],
      "attribute": true,
      "supportsMultiple": false,
      "supportsRequired": false,
      "supportsTagging": false,
      "supportsAlphabeticalOrdering": false,
      "supportsColor": false,
      "userEditable": false
    },
    {
      "code": "title",
      "ordering": 1010,
      "label": "Card title",
      "tagging": false,
      "multiple": false,
      "required": false,
      "id": "4e5bf2b8-b0d3-4f5d-b966-e017f7feadda",
      "deleted": false,
      "deletedAt": null,
      "deletedBy": null,
      "description": "Card title",
      "semanticsType": null,
      "datatype": "Title",
      "datatypeOptions": {},
      "relevantKinds": [],
      "values": [
        {
          "id": null,
          "label": "No value",
          "semantics": null,
          "ordering": -1,
          "color": "#ffffff",
          "description": null,
          "deprecated": false
        }
      ],
      "attribute": true,
      "supportsMultiple": false,
      "supportsRequired": false,
      "supportsTagging": false,
      "supportsAlphabeticalOrdering": false,
      "supportsColor": false,
      "userEditable": true
    },
    {
      "code": "specification",
      "ordering": 1011,
      "label": "Card description",
      "tagging": false,
      "multiple": false,
      "required": false,
      "id": "039fdea8-4dd7-488f-85f5-38f2c11eff8a",
      "deleted": false,
      "deletedAt": null,
      "deletedBy": null,
      "description": "Card (Markdown) description",
      "semanticsType": null,
      "datatype": "Specification",
      "datatypeOptions": {},
      "relevantKinds": [],
      "values": [
        {
          "id": null,
          "label": "No value",
          "semantics": null,
          "ordering": -1,
          "color": "#ffffff",
          "description": null,
          "deprecated": false
        }
      ],
      "attribute": true,
      "supportsMultiple": false,
      "supportsRequired": false,
      "supportsTagging": false,
      "supportsAlphabeticalOrdering": false,
      "supportsColor": false,
      "userEditable": true
    },
    {
      "code": "progress",
      "ordering": 120000,
      "label": "Progress",
      "tagging": true,
      "multiple": false,
      "required": false,
      "id": "8582be6e-283e-4633-9cc5-2f2ab96a43bb",
      "deleted": false,
      "deletedAt": null,
      "deletedBy": null,
      "description": null,
      "semanticsType": null,
      "datatype": "Progress",
      "datatypeOptions": {},
      "relevantKinds": [],
      "values": [
        {
          "id": null,
          "label": "No value",
          "semantics": null,
          "ordering": -1,
          "color": "#ffffff",
          "description": null,
          "deprecated": false
        },
        {
          "id": "todo",
          "label": "Todo",
          "ordering": 10000,
          "color": "#e01514",
          "semantics": null,
          "description": null,
          "deprecated": false
        },
        {
          "id": "ongoing",
          "label": "Ongoing",
          "ordering": 20000,
          "color": "#f77d00",
          "semantics": null,
          "description": null,
          "deprecated": false
        },
        {
          "id": "done",
          "label": "Done",
          "ordering": 30000,
          "color": "#00b048",
          "semantics": null,
          "description": null,
          "deprecated": false
        }
      ],
      "attribute": false,
      "supportsMultiple": false,
      "supportsRequired": true,
      "supportsTagging": true,
      "supportsAlphabeticalOrdering": true,
      "supportsColor": true,
      "userEditable": true
    },
    {
      "code": "assignee",
      "ordering": 220000,
      "label": "Assignee",
      "tagging": true,
      "multiple": false,
      "required": false,
      "id": "0334196e-1aba-4049-9769-b8fde2eb2227",
      "deleted": false,
      "deletedAt": null,
      "deletedBy": null,
      "description": null,
      "semanticsType": null,
      "datatype": "ProjectMember",
      "datatypeOptions": {},
      "relevantKinds": [],
      "values": [
        {
          "id": null,
          "label": "No value",
          "semantics": null,
          "ordering": -1,
          "color": "#ffffff",
          "description": null,
          "deprecated": false
        },
        {
          "id": "Bernard",
          "label": "Bernard",
          "ordering": 1000000,
          "color": "#ffffff",
          "semantics": "Bernard",
          "description": null,
          "deprecated": false
        },
        {
          "id": "Victor",
          "label": "Victor",
          "ordering": 2000000,
          "color": "#ffffff",
          "semantics": "Victor",
          "description": null,
          "deprecated": false
        },
        {
          "id": "Marc",
          "label": "Marc",
          "ordering": 3000000,
          "color": "#ffffff",
          "semantics": "Marc",
          "description": null,
          "deprecated": false
        }
      ],
      "attribute": false,
      "supportsMultiple": true,
      "supportsRequired": true,
      "supportsTagging": true,
      "supportsAlphabeticalOrdering": true,
      "supportsColor": true,
      "userEditable": true
    },
    {
      "code": "due_date",
      "ordering": 320000,
      "label": "Due date",
      "tagging": false,
      "multiple": false,
      "required": false,
      "id": "44c78647-0a68-48a2-b6e0-0fd926752f4f",
      "deleted": false,
      "deletedAt": null,
      "deletedBy": null,
      "description": null,
      "semanticsType": "DateRange",
      "datatype": "DueDate",
      "datatypeOptions": {},
      "relevantKinds": [],
      "values": [
        {
          "id": null,
          "label": "No value",
          "semantics": null,
          "ordering": -1,
          "color": "#ffffff",
          "description": null,
          "deprecated": false
        },
        {
          "id": "late_",
          "label": "Late!",
          "ordering": 10000,
          "color": "#202020",
          "semantics": "-BOT",
          "description": null,
          "deprecated": false
        },
        {
          "id": "late_tomorrow",
          "label": "Late tomorrow",
          "ordering": 20000,
          "color": "#e01514",
          "semantics": "+P1D",
          "description": null,
          "deprecated": false
        },
        {
          "id": "late_in_3_days",
          "label": "Late in 3 days",
          "ordering": 30000,
          "color": "#a85319",
          "semantics": "+P1D .. +P3D",
          "description": null,
          "deprecated": false
        },
        {
          "id": "next_7_days",
          "label": "Next 7 days",
          "ordering": 40000,
          "color": "#ffba00",
          "semantics": "+P3D .. +P7D",
          "description": null,
          "deprecated": false
        },
        {
          "id": "next_15_days",
          "label": "Next 15 days",
          "ordering": 50000,
          "color": "#99cc2d",
          "semantics": "+P7D .. +P15D",
          "description": null,
          "deprecated": false
        },
        {
          "id": "next_30_days",
          "label": "Next 30 days",
          "ordering": 60000,
          "color": "#00b048",
          "semantics": "+P15D .. +P30D",
          "description": null,
          "deprecated": false
        },
        {
          "id": "later",
          "label": "Later",
          "ordering": 70000,
          "color": "#00b048",
          "semantics": "+P30D .. P100Y",
          "description": null,
          "deprecated": false
        }
      ],
      "attribute": false,
      "supportsMultiple": false,
      "supportsRequired": true,
      "supportsTagging": true,
      "supportsAlphabeticalOrdering": false,
      "supportsColor": true,
      "userEditable": true
    }
  ],
  "ordering": 2,
  "ganttScale": null,
  "displayDimensionLabels": false,
  "manualDimensionsInDecks": false,
  "displayDimensionsOnCards": true,
  "displayNoneOnCards": false,
  "connector": "BaseConnector",
  "importers": [],
  "extraSettings": {
    "onCardClick": {
      "type": "fullEdit",
      "options": {}
    }
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	none	Inline

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» id	string	true	none	Board unique ID
» label	string	true	none	Board human friendly name
» location	string	true	none	Board friendly location (used in url)
» mode	string	true	none	Board mode (e.g. grid, list, kanban)
» connector	string	true	none	Reserved (use BaseConnector)
» objective	string	true	none	Board objective (shown to users on load)
» objectiveModal	boolean	true	none	Whether the objective must be shown to users
» decksOpen	boolean	true	none	Whether the filter decks are open on board load
» coloredDimension	string	true	none	Dimension (code) used for card colors
» compactDisplay	boolean	true	none	Whether empty columns/rows/categories are hidden
» compactDecks	boolean	true	none	Whether unused values are hidden in filters
» explorerDecks	boolean	true	none	Whether the filter decks use left-to-right layout
» background	string	true	none	Name of the board background
» createdBy	string	true	none	Who created the board
» createdAt	string	true	none	When was the board created
» ordering	integer	true	none	Order index of the board in the collection
» ganttScale	string	true	none	Scale used in the gantt mode
» manualDimensionsInDecks	boolean	true	none	Whether the user selected specific dimensions to be shown in decks
» displayDimensionsOnCards	boolean	true	none	Whether dimensions are shown on cards
» displayDimensionLabels	boolean	true	none	Whether dimension labels are shown on cards
» displayNoneOnCards	boolean	true	none	Whether empty values are shown on carts
» dimensions	[object]	true	none	List of board dimensions
»» id	string	true	none	Dimension unique ID
»» code	string	true	none	Dimension code (used in URLs, filters, anchors, etc.)
»» datatype	string	true	none	Dimension datatype (e.g. UserDefined, Date, ProjectMember, etc.)
»» datatypeOptions	object	true	none	Options of the datatype, configuring behavior
»»» additionalProperties	object	false	none	none
»» label	string	true	none	Dimension human friendly name
»» description	string	true	none	Dimension long description, if any
»» required	boolean	true	none	Whether a value is required on cards
»» supportsRequired	boolean	true	none	Whether the users can decided whether the dimension is required
»» tagging	boolean	true	none	Whether users can add/edit values in boards and cards (aka unlocked)
»» supportsTagging	boolean	true	none	Whether users can choose to lock/unlock the dimension
»» multiple	boolean	true	none	Whether multiple values can be choosen on cards
»» supportsMultiple	boolean	true	none	Whether the dimension datatype supports multiple values
»» supportsAlphabeticalOrdering	boolean	true	none	Whether values can be ordered alphabetically
»» userEditable	boolean	true	none	Whether values can be choosen by end-users on cards
»» attribute	boolean	true	none	Whether this dimension is a fixed card attribute (deprecated)
»» supportsColor	boolean	true	none	Whether the dimension supports colors on values
»» ordering	integer	true	none	Order index of the dimension in the project
»» semanticsType	string	true	none	Semantics of the dimension values
»» relevantKinds	[string]	true	none	For what card kinds this dimension is relevant
»» values	[object]	true	none	The dimension list of values
»»» additionalProperties	object	false	none	none
»»» id	string	true	none	ID for the value (unique inside the dimension)
»»» label	string	true	none	Human friendly label of the value
»»» semantics	string	true	none	Filtering semantics, if any
»»» color	string	true	none	Value color, if any
»»» ordering	integer	true	none	Ordering of the value within the collection
»»» description	string	false	none	Description of the value, if any
»»» placeholder	string	false	none	Placeholder of the value, if any
»»» deprecated	boolean	true	none	Whether the value is deprecated
»» deleted	boolean	true	none	Whether the dimension has been deleted
»» deletedAt	string	true	none	When this dimension was deleted, if deleted
»» deletedBy	string	true	none	Who deleted this dimension, if deleted
» anchors	object	true	none	List of board anchors, see Data Model
»» additionalProperties	any	false	none	none
»» decks	[string]	false	none	Dimensions to show in filters deck
»» displayBy	[string]	false	none	Dimension(s) used to group cards in board
»» cards	[string]	false	none	Dimensions to show on cards
»» ordering	[string]	false	none	Dimensions to use to sort cards in board
»» required	[string]	false	none	Dimensions required in the board
»» gantt	[string]	false	none	Dimensions used for Gantt mode
»» hierarchyBy	[string]	false	none	Dimensions used to hierarchy in List mode
»» seriesBy	[string]	false	none	Dimensions used to as series in Chart mode
»» rowsBy	[string]	false	none	Dimensions used as rows in Matrix mode
» filters	object	true	none	List of board filters, see Data Model
» workspacePermissions	[object]	true	none	List of workspaces permissions on this board
»» workspace	string	true	none	Workspace code
»» canRead	boolean	true	none	Whether the users can read cards
»» canWrite	boolean	true	none	Whether the users can write cards
»» canManage	boolean	true	none	Whether the users can manage cards
» summaries	[object]	true	none	List of board summaries shown
»» code	string	true	none	Summary function code
»» label	string	true	none	Summary function label
»» expr	string	true	none	Formal expression
»» ordering	integer	true	none	Summary order index in collection
» importers	[object]	false	none	List of board importers
» extraSettings	object	true	none	Extra board settings used by the various modes
»» onCardClick	object	false	none	Behavior on card click
»»» type	string	true	none	Type of action
»»» options	object	true	none	Action options
»»»» additionalProperties	string	false	none	none
»» swipeGestures	object	false	none	Behavior when swiping on mobile
»»» left	object	false	none	Behavior when swipping left
»»»» type	string	true	none	Type of action
»»»» value	string	false	none	Dimension value ID, if any
»»» right	object	false	none	Behavior when swipping right
»»»» type	string	true	none	Type of action
»»»» value	string	false	none	Dimension value ID, if any
»»» up	object	false	none	Behavior when swipping up
»»»» type	string	true	none	Type of action
»»»» value	string	false	none	Dimension value ID, if any
»»» down	object	false	none	Behavior when swipping down
»»»» type	string	true	none	Type of action
»»»» value	string	false	none	Dimension value ID, if any
»» chartOptions	object	false	none	Options for chart mode
»»» type	string	true	none	none

Delete board

Code samples


const headers = {
  'Authorization':'Bearer {access-token}'
};

fetch('/boards/{id}',
{
  method: 'DELETE',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.delete '/boards/{id}',
  params: {
  }, headers: headers

p JSON.parse(result)

# You can also use wget
curl -X DELETE /boards/{id} \
  -H 'Authorization: Bearer {access-token}'

DELETE /boards/{id}

Deletes a single board and all its dependencies

Parameters

Name	In	Type	Required	Description
id	path	string	true	Either the board id or location

Responses

Status	Meaning	Description	Schema
204	No Content	none	None

Create board

Code samples

const inputBody = '{
  "connector": "BaseConnector",
  "label": "Todo grid",
  "location": "todo-grid",
  "mode": "grid",
  "objective": "Show the todos in a grid view",
  "decksOpen": false,
  "coloredDimension": "kind",
  "compactDisplay": true,
  "compactDecks": true,
  "explorerDecks": true,
  "manualDimensionsInDecks": true,
  "displayDimensionLabels": false,
  "displayDimensionsOnCards": true,
  "displayNoneOnCards": true,
  "background": "sunset",
  "anchors": {},
  "summaries": [],
  "filters": {
    "progress": "todo"
  },
  "workspacePermissions": [
    {
      "workspace": "admins",
      "canRead": true,
      "canWrite": true,
      "canManage": true
    }
  ]
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('/boards',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.post '/boards',
  params: {
  }, headers: headers

p JSON.parse(result)

# You can also use wget
curl -X POST /boards \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

POST /boards

Allows creating a new board

Body parameter

Create a new grid board with a filter along the progress dimension

{
  "connector": "BaseConnector",
  "label": "Todo grid",
  "location": "todo-grid",
  "mode": "grid",
  "objective": "Show the todos in a grid view",
  "decksOpen": false,
  "coloredDimension": "kind",
  "compactDisplay": true,
  "compactDecks": true,
  "explorerDecks": true,
  "manualDimensionsInDecks": true,
  "displayDimensionLabels": false,
  "displayDimensionsOnCards": true,
  "displayNoneOnCards": true,
  "background": "sunset",
  "anchors": {},
  "summaries": [],
  "filters": {
    "progress": "todo"
  },
  "workspacePermissions": [
    {
      "workspace": "admins",
      "canRead": true,
      "canWrite": true,
      "canManage": true
    }
  ]
}

Parameters

Name	In	Type	Required	Description
additionalProperties	body	any	false	none
label	body	string	true	Board human friendly name
location	body	string	true	Board friendly location (used in url)
mode	body	string	true	Board mode (e.g. grid, list, kanban)
connector	body	string	false	Reserved (use BaseConnector)
objective	body	string	true	Board objective (shown to users on load)
decksOpen	body	boolean	true	Whether the filter decks are open on board load
coloredDimension	body	string	true	Dimension (code) used for card colors
compactDisplay	body	boolean	true	Whether empty columns/rows/categories are hidden
compactDecks	body	boolean	true	Whether unused values are hidden in filters
explorerDecks	body	boolean	true	Whether the filter decks use left-to-right layout
displayDimensionLabels	body	boolean	true	Whether dimension labels are shown on cards
manualDimensionsInDecks	body	boolean	true	Whether the user selected specific dimensions to be shown in decks
displayDimensionsOnCards	body	boolean	true	Whether dimensions are shown on cards
displayNoneOnCards	body	boolean	true	Whether empty values are shown on carts
background	body	string	true	Name of the board background
anchors	body	object	true	List of board anchors, see Data Model
» additionalProperties	body	any	false	none
» decks	body	[string]	false	Dimensions to show in filters deck
» displayBy	body	[string]	false	Dimension(s) used to group cards in board
» cards	body	[string]	false	Dimensions to show on cards
» ordering	body	[string]	false	Dimensions to use to sort cards in board
» required	body	[string]	false	Dimensions required in the board
» gantt	body	[string]	false	Dimensions used for Gantt mode
» hierarchyBy	body	[string]	false	Dimensions used to hierarchy in List mode
» seriesBy	body	[string]	false	Dimensions used to as series in Chart mode
» rowsBy	body	[string]	false	Dimensions used as rows in Matrix mode
filters	body	object	true	List of board filters, see Data Model
summaries	body	[object]	true	List of board summaries shown
» additionalProperties	body	any	false	none
» code	body	string	true	Summary function code
» label	body	string	false	Summary function label
» ordering	body	integer	false	Summary order index in collection
» expr	body	string	false	Formal expression
workspacePermissions	body	[object]	true	List of workspaces permissions on this board
» workspace	body	string	true	Workspace code
» canRead	body	boolean	true	Whether the users can read cards
» canWrite	body	boolean	true	Whether the users can write cards
» canManage	body	boolean	true	Whether the users can manage cards
extraSettings	body	object	false	Extra board settings used by the various modes
» onCardClick	body	object	false	Behavior on card click
»» type	body	string	true	Type of action
»» options	body	object	true	Action options
»»» additionalProperties	body	string	false	none
» swipeGestures	body	object	false	Behavior when swiping on mobile
»» left	body	object	false	Behavior when swipping left
»»» type	body	string	true	Type of action
»»» value	body	string	false	Dimension value ID, if any
»» right	body	object	false	Behavior when swipping right
»»» type	body	string	true	Type of action
»»» value	body	string	false	Dimension value ID, if any
»» up	body	object	false	Behavior when swipping up
»»» type	body	string	true	Type of action
»»» value	body	string	false	Dimension value ID, if any
»» down	body	object	false	Behavior when swipping down
»»» type	body	string	true	Type of action
»»» value	body	string	false	Dimension value ID, if any
» chartOptions	body	object	false	Options for chart mode
»» type	body	string	true	none

Example responses

Create a new grid board with a filter along the progress dimension

{
  "id": "2affec7a-050a-4a9b-b86f-e3eb8b8828a0",
  "label": "Todo grid",
  "location": "todo-grid",
  "mode": "grid",
  "objective": "Show the todos in a grid view",
  "objectiveModal": false,
  "decksOpen": false,
  "coloredDimension": "kind",
  "compactDisplay": true,
  "compactDecks": true,
  "explorerDecks": true,
  "background": "sunset",
  "anchors": {},
  "filters": {
    "progress": [
      "todo"
    ]
  },
  "summaries": [],
  "workspacePermissions": [
    {
      "workspace": "admins",
      "canRead": true,
      "canWrite": true,
      "canManage": true
    }
  ],
  "createdBy": "Bernard",
  "createdAt": "2025-03-27T17:02:14+00:00",
  "dimensions": [
    {
      "code": "kind",
      "ordering": 20000,
      "label": "Kind",
      "tagging": true,
      "multiple": false,
      "required": true,
      "id": "0d3c755c-b3d3-4940-947e-e90de07e571f",
      "deleted": false,
      "deletedAt": null,
      "deletedBy": null,
      "description": null,
      "semanticsType": null,
      "datatype": "Kind",
      "datatypeOptions": {},
      "relevantKinds": [],
      "values": [
        {
          "id": null,
          "label": "No value",
          "semantics": null,
          "ordering": -1,
          "color": "#ffffff",
          "description": null,
          "deprecated": false
        },
        {
          "id": "todo",
          "label": "Todo",
          "color": "#b7137e",
          "ordering": 1000000,
          "semantics": null,
          "colorDimension": null,
          "description": null,
          "placeholder": null,
          "deprecated": false,
          "summaryDimensions": []
        }
      ],
      "attribute": false,
      "supportsMultiple": false,
      "supportsRequired": true,
      "supportsTagging": true,
      "supportsAlphabeticalOrdering": true,
      "supportsColor": true,
      "userEditable": true
    },
    {
      "code": "identifier",
      "ordering": 1000,
      "label": "Card n°",
      "tagging": false,
      "multiple": false,
      "required": true,
      "id": "af352fc7-8c9b-4030-934e-da0b1f737741",
      "deleted": false,
      "deletedAt": null,
      "deletedBy": null,
      "description": null,
      "semanticsType": null,
      "datatype": "Identifier",
      "datatypeOptions": {},
      "relevantKinds": [],
      "values": [
        {
          "id": null,
          "label": "No value",
          "semantics": null,
          "ordering": -1,
          "color": "#ffffff",
          "description": null,
          "deprecated": false
        }
      ],
      "attribute": true,
      "supportsMultiple": false,
      "supportsRequired": false,
      "supportsTagging": false,
      "supportsAlphabeticalOrdering": false,
      "supportsColor": false,
      "userEditable": false
    },
    {
      "code": "title",
      "ordering": 1010,
      "label": "Card title",
      "tagging": false,
      "multiple": false,
      "required": false,
      "id": "4e5bf2b8-b0d3-4f5d-b966-e017f7feadda",
      "deleted": false,
      "deletedAt": null,
      "deletedBy": null,
      "description": "Card title",
      "semanticsType": null,
      "datatype": "Title",
      "datatypeOptions": {},
      "relevantKinds": [],
      "values": [
        {
          "id": null,
          "label": "No value",
          "semantics": null,
          "ordering": -1,
          "color": "#ffffff",
          "description": null,
          "deprecated": false
        }
      ],
      "attribute": true,
      "supportsMultiple": false,
      "supportsRequired": false,
      "supportsTagging": false,
      "supportsAlphabeticalOrdering": false,
      "supportsColor": false,
      "userEditable": true
    },
    {
      "code": "specification",
      "ordering": 1011,
      "label": "Card description",
      "tagging": false,
      "multiple": false,
      "required": false,
      "id": "039fdea8-4dd7-488f-85f5-38f2c11eff8a",
      "deleted": false,
      "deletedAt": null,
      "deletedBy": null,
      "description": "Card (Markdown) description",
      "semanticsType": null,
      "datatype": "Specification",
      "datatypeOptions": {},
      "relevantKinds": [],
      "values": [
        {
          "id": null,
          "label": "No value",
          "semantics": null,
          "ordering": -1,
          "color": "#ffffff",
          "description": null,
          "deprecated": false
        }
      ],
      "attribute": true,
      "supportsMultiple": false,
      "supportsRequired": false,
      "supportsTagging": false,
      "supportsAlphabeticalOrdering": false,
      "supportsColor": false,
      "userEditable": true
    },
    {
      "code": "progress",
      "ordering": 120000,
      "label": "Progress",
      "tagging": true,
      "multiple": false,
      "required": false,
      "id": "8582be6e-283e-4633-9cc5-2f2ab96a43bb",
      "deleted": false,
      "deletedAt": null,
      "deletedBy": null,
      "description": null,
      "semanticsType": null,
      "datatype": "Progress",
      "datatypeOptions": {},
      "relevantKinds": [],
      "values": [
        {
          "id": null,
          "label": "No value",
          "semantics": null,
          "ordering": -1,
          "color": "#ffffff",
          "description": null,
          "deprecated": false
        },
        {
          "id": "todo",
          "label": "Todo",
          "ordering": 10000,
          "color": "#e01514",
          "semantics": null,
          "description": null,
          "deprecated": false
        },
        {
          "id": "ongoing",
          "label": "Ongoing",
          "ordering": 20000,
          "color": "#f77d00",
          "semantics": null,
          "description": null,
          "deprecated": false
        },
        {
          "id": "done",
          "label": "Done",
          "ordering": 30000,
          "color": "#00b048",
          "semantics": null,
          "description": null,
          "deprecated": false
        }
      ],
      "attribute": false,
      "supportsMultiple": false,
      "supportsRequired": true,
      "supportsTagging": true,
      "supportsAlphabeticalOrdering": true,
      "supportsColor": true,
      "userEditable": true
    },
    {
      "code": "assignee",
      "ordering": 220000,
      "label": "Assignee",
      "tagging": true,
      "multiple": false,
      "required": false,
      "id": "0334196e-1aba-4049-9769-b8fde2eb2227",
      "deleted": false,
      "deletedAt": null,
      "deletedBy": null,
      "description": null,
      "semanticsType": null,
      "datatype": "ProjectMember",
      "datatypeOptions": {},
      "relevantKinds": [],
      "values": [
        {
          "id": null,
          "label": "No value",
          "semantics": null,
          "ordering": -1,
          "color": "#ffffff",
          "description": null,
          "deprecated": false
        },
        {
          "id": "Bernard",
          "label": "Bernard",
          "ordering": 1000000,
          "color": "#ffffff",
          "semantics": "Bernard",
          "description": null,
          "deprecated": false
        },
        {
          "id": "Victor",
          "label": "Victor",
          "ordering": 2000000,
          "color": "#ffffff",
          "semantics": "Victor",
          "description": null,
          "deprecated": false
        },
        {
          "id": "Marc",
          "label": "Marc",
          "ordering": 3000000,
          "color": "#ffffff",
          "semantics": "Marc",
          "description": null,
          "deprecated": false
        }
      ],
      "attribute": false,
      "supportsMultiple": true,
      "supportsRequired": true,
      "supportsTagging": true,
      "supportsAlphabeticalOrdering": true,
      "supportsColor": true,
      "userEditable": true
    },
    {
      "code": "due_date",
      "ordering": 320000,
      "label": "Due date",
      "tagging": false,
      "multiple": false,
      "required": false,
      "id": "44c78647-0a68-48a2-b6e0-0fd926752f4f",
      "deleted": false,
      "deletedAt": null,
      "deletedBy": null,
      "description": null,
      "semanticsType": "DateRange",
      "datatype": "DueDate",
      "datatypeOptions": {},
      "relevantKinds": [],
      "values": [
        {
          "id": null,
          "label": "No value",
          "semantics": null,
          "ordering": -1,
          "color": "#ffffff",
          "description": null,
          "deprecated": false
        },
        {
          "id": "late_",
          "label": "Late!",
          "ordering": 10000,
          "color": "#202020",
          "semantics": "-BOT",
          "description": null,
          "deprecated": false
        },
        {
          "id": "late_tomorrow",
          "label": "Late tomorrow",
          "ordering": 20000,
          "color": "#e01514",
          "semantics": "+P1D",
          "description": null,
          "deprecated": false
        },
        {
          "id": "late_in_3_days",
          "label": "Late in 3 days",
          "ordering": 30000,
          "color": "#a85319",
          "semantics": "+P1D .. +P3D",
          "description": null,
          "deprecated": false
        },
        {
          "id": "next_7_days",
          "label": "Next 7 days",
          "ordering": 40000,
          "color": "#ffba00",
          "semantics": "+P3D .. +P7D",
          "description": null,
          "deprecated": false
        },
        {
          "id": "next_15_days",
          "label": "Next 15 days",
          "ordering": 50000,
          "color": "#99cc2d",
          "semantics": "+P7D .. +P15D",
          "description": null,
          "deprecated": false
        },
        {
          "id": "next_30_days",
          "label": "Next 30 days",
          "ordering": 60000,
          "color": "#00b048",
          "semantics": "+P15D .. +P30D",
          "description": null,
          "deprecated": false
        },
        {
          "id": "later",
          "label": "Later",
          "ordering": 70000,
          "color": "#00b048",
          "semantics": "+P30D .. P100Y",
          "description": null,
          "deprecated": false
        }
      ],
      "attribute": false,
      "supportsMultiple": false,
      "supportsRequired": true,
      "supportsTagging": true,
      "supportsAlphabeticalOrdering": false,
      "supportsColor": true,
      "userEditable": true
    }
  ],
  "ordering": 3,
  "ganttScale": null,
  "displayDimensionLabels": false,
  "manualDimensionsInDecks": true,
  "displayDimensionsOnCards": true,
  "displayNoneOnCards": true,
  "connector": "BaseConnector",
  "importers": [],
  "extraSettings": {}
}

Responses

Status	Meaning	Description	Schema
201	Created	none	Inline

Response Schema

Status Code 201

Name	Type	Required	Restrictions	Description
» id	string	true	none	Board unique ID
» label	string	true	none	Board human friendly name
» location	string	true	none	Board friendly location (used in url)
» mode	string	true	none	Board mode (e.g. grid, list, kanban)
» connector	string	true	none	Reserved (use BaseConnector)
» objective	string	true	none	Board objective (shown to users on load)
» objectiveModal	boolean	true	none	Whether the objective must be shown to users
» decksOpen	boolean	true	none	Whether the filter decks are open on board load
» coloredDimension	string	true	none	Dimension (code) used for card colors
» compactDisplay	boolean	true	none	Whether empty columns/rows/categories are hidden
» compactDecks	boolean	true	none	Whether unused values are hidden in filters
» explorerDecks	boolean	true	none	Whether the filter decks use left-to-right layout
» background	string	true	none	Name of the board background
» createdBy	string	true	none	Who created the board
» createdAt	string	true	none	When was the board created
» ordering	integer	true	none	Order index of the board in the collection
» ganttScale	string	true	none	Scale used in the gantt mode
» manualDimensionsInDecks	boolean	true	none	Whether the user selected specific dimensions to be shown in decks
» displayDimensionsOnCards	boolean	true	none	Whether dimensions are shown on cards
» displayDimensionLabels	boolean	true	none	Whether dimension labels are shown on cards
» displayNoneOnCards	boolean	true	none	Whether empty values are shown on carts
» dimensions	[object]	true	none	List of board dimensions
»» id	string	true	none	Dimension unique ID
»» code	string	true	none	Dimension code (used in URLs, filters, anchors, etc.)
»» datatype	string	true	none	Dimension datatype (e.g. UserDefined, Date, ProjectMember, etc.)
»» datatypeOptions	object	true	none	Options of the datatype, configuring behavior
»»» additionalProperties	object	false	none	none
»» label	string	true	none	Dimension human friendly name
»» description	string	true	none	Dimension long description, if any
»» required	boolean	true	none	Whether a value is required on cards
»» supportsRequired	boolean	true	none	Whether the users can decided whether the dimension is required
»» tagging	boolean	true	none	Whether users can add/edit values in boards and cards (aka unlocked)
»» supportsTagging	boolean	true	none	Whether users can choose to lock/unlock the dimension
»» multiple	boolean	true	none	Whether multiple values can be choosen on cards
»» supportsMultiple	boolean	true	none	Whether the dimension datatype supports multiple values
»» supportsAlphabeticalOrdering	boolean	true	none	Whether values can be ordered alphabetically
»» userEditable	boolean	true	none	Whether values can be choosen by end-users on cards
»» attribute	boolean	true	none	Whether this dimension is a fixed card attribute (deprecated)
»» supportsColor	boolean	true	none	Whether the dimension supports colors on values
»» ordering	integer	true	none	Order index of the dimension in the project
»» semanticsType	string	true	none	Semantics of the dimension values
»» relevantKinds	[string]	true	none	For what card kinds this dimension is relevant
»» values	[object]	true	none	The dimension list of values
»»» additionalProperties	object	false	none	none
»»» id	string	true	none	ID for the value (unique inside the dimension)
»»» label	string	true	none	Human friendly label of the value
»»» semantics	string	true	none	Filtering semantics, if any
»»» color	string	true	none	Value color, if any
»»» ordering	integer	true	none	Ordering of the value within the collection
»»» description	string	false	none	Description of the value, if any
»»» placeholder	string	false	none	Placeholder of the value, if any
»»» deprecated	boolean	true	none	Whether the value is deprecated
»» deleted	boolean	true	none	Whether the dimension has been deleted
»» deletedAt	string	true	none	When this dimension was deleted, if deleted
»» deletedBy	string	true	none	Who deleted this dimension, if deleted
» anchors	object	true	none	List of board anchors, see Data Model
»» additionalProperties	any	false	none	none
»» decks	[string]	false	none	Dimensions to show in filters deck
»» displayBy	[string]	false	none	Dimension(s) used to group cards in board
»» cards	[string]	false	none	Dimensions to show on cards
»» ordering	[string]	false	none	Dimensions to use to sort cards in board
»» required	[string]	false	none	Dimensions required in the board
»» gantt	[string]	false	none	Dimensions used for Gantt mode
»» hierarchyBy	[string]	false	none	Dimensions used to hierarchy in List mode
»» seriesBy	[string]	false	none	Dimensions used to as series in Chart mode
»» rowsBy	[string]	false	none	Dimensions used as rows in Matrix mode
» filters	object	true	none	List of board filters, see Data Model
» workspacePermissions	[object]	true	none	List of workspaces permissions on this board
»» workspace	string	true	none	Workspace code
»» canRead	boolean	true	none	Whether the users can read cards
»» canWrite	boolean	true	none	Whether the users can write cards
»» canManage	boolean	true	none	Whether the users can manage cards
» summaries	[object]	true	none	List of board summaries shown
»» code	string	true	none	Summary function code
»» label	string	true	none	Summary function label
»» expr	string	true	none	Formal expression
»» ordering	integer	true	none	Summary order index in collection
» importers	[object]	false	none	List of board importers
» extraSettings	object	true	none	Extra board settings used by the various modes
»» onCardClick	object	false	none	Behavior on card click
»»» type	string	true	none	Type of action
»»» options	object	true	none	Action options
»»»» additionalProperties	string	false	none	none
»» swipeGestures	object	false	none	Behavior when swiping on mobile
»»» left	object	false	none	Behavior when swipping left
»»»» type	string	true	none	Type of action
»»»» value	string	false	none	Dimension value ID, if any
»»» right	object	false	none	Behavior when swipping right
»»»» type	string	true	none	Type of action
»»»» value	string	false	none	Dimension value ID, if any
»»» up	object	false	none	Behavior when swipping up
»»»» type	string	true	none	Type of action
»»»» value	string	false	none	Dimension value ID, if any
»»» down	object	false	none	Behavior when swipping down
»»»» type	string	true	none	Type of action
»»»» value	string	false	none	Dimension value ID, if any
»» chartOptions	object	false	none	Options for chart mode
»»» type	string	true	none	none

Board stories

Get story

Code samples


const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('/boards/{board}/stories/{story}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.get '/boards/{board}/stories/{story}',
  params: {
  }, headers: headers

p JSON.parse(result)

# You can also use wget
curl -X GET /boards/{board}/stories/{story} \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

GET /boards/{board}/stories/{story}

Returns a single story

Parameters

Name	In	Type	Required	Description
board	path	string	true	none
story	path	any	true	none

Example responses

Get a story that belongs to the board

{
  "id": "8ed76538-ee9a-4b39-9407-6b392a7ddc35",
  "identifier": 2,
  "project": "8c34924f-21ca-406b-aaaa-749ad3d2f4fb",
  "title": "Document the RESTful API",
  "createdAt": "2025-03-21T16:32:17+00:00",
  "createdBy": "Bernard",
  "updatedAt": "2025-03-24T13:23:07+00:00",
  "specification": "",
  "kind": "todo",
  "progress": "ongoing",
  "assignee": "Bernard",
  "due_date": null,
  "attachments": [],
  "linked": []
}

Responses

Status	Meaning	Description	Schema
200	OK	none	Inline

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» additionalProperties	object	false	none	none
» id	string	true	none	Unique story ID
» identifier	integer	true	none	Unique story identifier (autonumber)
» title	string	true	none	Story title
» specification	string	true	none	Story specification, also known as description
» createdBy	string	true	none	Who created the story
» createdAt	string	true	none	When was the story created
» updatedAt	string	true	none	When was the story last updated
» linked	[object]	true	none	Linked stories
»» additionalProperties	object	false	none	none
»» id	string	true	none	Unique story ID
»» identifier	integer	true	none	Unique story identifier (autonumber)
»» title	string	true	none	Story title
»» createdBy	string	false	none	Who created the story
»» createdAt	string	false	none	When was the story created
»» updatedAt	string	false	none	When was the story last updated
» attachments	[object]	true	none	Story attachments
»» id	string	true	none	Attachement unique ID
»» filename	string	true	none	Attachment file name
»» url	string	true	none	URL of the attachement, relative to the project's imgBaseUrl
»» description	string	true	none	Attachment description, if any
»» sizeInBytes	integer	true	none	Attachment size in bytes
»» isCover	boolean	true	none	Whether the attachment is used as story cover
»» createdAt	string	true	none	When was the attachent created
»» createdBy	string	true	none	Who created the attachent

Update story

Code samples

const inputBody = '{
  "title": "A new title"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('/boards/{board}/stories/{story}',
{
  method: 'PATCH',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.patch '/boards/{board}/stories/{story}',
  params: {
  }, headers: headers

p JSON.parse(result)

# You can also use wget
curl -X PATCH /boards/{board}/stories/{story} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

PATCH /boards/{board}/stories/{story}

Patches a single story

Body parameter

Update the title of a story whose id is known

{
  "title": "A new title"
}

Parameters

Name	In	Type	Required	Description
board	path	string	true	Board id or location in which the update takes place
additionalProperties	body	object	false	none
id	body	string	false	ID or identifier of the story
title	body	string	false	Story title
specification	body	string	false	Story specification, also known as description

Example responses

Update the title of a story whose id is known

{
  "id": "8ed76538-ee9a-4b39-9407-6b392a7ddc35",
  "identifier": 2,
  "project": "8c34924f-21ca-406b-aaaa-749ad3d2f4fb",
  "title": "A new title",
  "createdAt": "2025-03-21T16:32:17+00:00",
  "createdBy": "Bernard",
  "updatedAt": "2025-03-27T17:02:13+00:00",
  "specification": "",
  "kind": "todo",
  "progress": "ongoing",
  "assignee": "Bernard",
  "due_date": null,
  "attachments": [],
  "linked": []
}

Responses

Status	Meaning	Description	Schema
200	OK	none	Inline

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» additionalProperties	object	false	none	none
» id	string	true	none	Unique story ID
» identifier	integer	true	none	Unique story identifier (autonumber)
» title	string	true	none	Story title
» specification	string	true	none	Story specification, also known as description
» createdBy	string	true	none	Who created the story
» createdAt	string	true	none	When was the story created
» updatedAt	string	true	none	When was the story last updated
» linked	[object]	true	none	Linked stories
»» additionalProperties	object	false	none	none
»» id	string	true	none	Unique story ID
»» identifier	integer	true	none	Unique story identifier (autonumber)
»» title	string	true	none	Story title
»» createdBy	string	false	none	Who created the story
»» createdAt	string	false	none	When was the story created
»» updatedAt	string	false	none	When was the story last updated
» attachments	[object]	true	none	Story attachments
»» id	string	true	none	Attachement unique ID
»» filename	string	true	none	Attachment file name
»» url	string	true	none	URL of the attachement, relative to the project's imgBaseUrl
»» description	string	true	none	Attachment description, if any
»» sizeInBytes	integer	true	none	Attachment size in bytes
»» isCover	boolean	true	none	Whether the attachment is used as story cover
»» createdAt	string	true	none	When was the attachent created
»» createdBy	string	true	none	Who created the attachent

Delete story

Code samples


const headers = {
  'Authorization':'Bearer {access-token}'
};

fetch('/boards/{board}/stories/{story}',
{
  method: 'DELETE',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.delete '/boards/{board}/stories/{story}',
  params: {
  }, headers: headers

p JSON.parse(result)

# You can also use wget
curl -X DELETE /boards/{board}/stories/{story} \
  -H 'Authorization: Bearer {access-token}'

DELETE /boards/{board}/stories/{story}

Deletes a single story

Parameters

Name	In	Type	Required	Description
board	path	string	true	none
story	path	any	true	none

Responses

Status	Meaning	Description	Schema
204	No Content	none	None

Create story/stories

Code samples

const inputBody = '{
  "kind": "todo",
  "progress": "ongoing",
  "assignee": "Bernard",
  "title": "Document the API"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('/boards/{board}/stories',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.post '/boards/{board}/stories',
  params: {
  }, headers: headers

p JSON.parse(result)

# You can also use wget
curl -X POST /boards/{board}/stories \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

POST /boards/{board}/stories

Creates a new story within the board.

The service also supports an Array of stories as input, and will create all of them and return them.

Body parameter

Create a new story within the board

{
  "kind": "todo",
  "progress": "ongoing",
  "assignee": "Bernard",
  "title": "Document the API"
}

Parameters

Name	In	Type	Required	Description
additionalProperties	body	object	false	none
id	body	string	false	ID or identifier of the story
title	body	string	true	Story title
specification	body	string	false	Story specification, also known as description
attachments	body	[object]	false	List of story attachments to create
» filename	body	string	true	Attachment file name
» url	body	string	true	URL of the attachement, relative to the project's imgBaseUrl
» isCover	body	boolean	true	Whether the attachment is used as story cover
» description	body	string	true	Whether the attachment is used as story cover
» sizeInBytes	body	integer	true	Attachment size in bytes

Example responses

Create a new story within the board

{
  "id": "c87062d2-2c5e-4c72-8185-e21311de1fbe",
  "identifier": 5,
  "project": "8c34924f-21ca-406b-aaaa-749ad3d2f4fb",
  "title": "Document the API",
  "createdAt": "2025-03-27T17:02:14+00:00",
  "createdBy": "Bernard",
  "updatedAt": "2025-03-27T17:02:14+00:00",
  "specification": "",
  "kind": "todo",
  "progress": "ongoing",
  "assignee": "Bernard",
  "due_date": null,
  "attachments": [],
  "linked": []
}

Responses

Status	Meaning	Description	Schema
201	Created	none	Inline

Response Schema

Status Code 201

Name	Type	Required	Restrictions	Description
» additionalProperties	object	false	none	none
» id	string	true	none	Unique story ID
» identifier	integer	true	none	Unique story identifier (autonumber)
» title	string	true	none	Story title
» specification	string	true	none	Story specification, also known as description
» createdBy	string	true	none	Who created the story
» createdAt	string	true	none	When was the story created
» updatedAt	string	true	none	When was the story last updated
» linked	[object]	true	none	Linked stories
»» additionalProperties	object	false	none	none
»» id	string	true	none	Unique story ID
»» identifier	integer	true	none	Unique story identifier (autonumber)
»» title	string	true	none	Story title
»» createdBy	string	false	none	Who created the story
»» createdAt	string	false	none	When was the story created
»» updatedAt	string	false	none	When was the story last updated
» attachments	[object]	true	none	Story attachments
»» id	string	true	none	Attachement unique ID
»» filename	string	true	none	Attachment file name
»» url	string	true	none	URL of the attachement, relative to the project's imgBaseUrl
»» description	string	true	none	Attachment description, if any
»» sizeInBytes	integer	true	none	Attachment size in bytes
»» isCover	boolean	true	none	Whether the attachment is used as story cover
»» createdAt	string	true	none	When was the attachent created
»» createdBy	string	true	none	Who created the attachent

Update stories

Code samples

const inputBody = '{
  "patch": [
    {
      "identifier": 2,
      "progress": "done"
    },
    {
      "identifier": 4,
      "progress": "done"
    }
  ]
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('/boards/{board}/stories',
{
  method: 'PATCH',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.patch '/boards/{board}/stories',
  params: {
  }, headers: headers

p JSON.parse(result)

# You can also use wget
curl -X PATCH /boards/{board}/stories \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

PATCH /boards/{board}/stories

Applies the same patch to many stories of the board

Body parameter

Assigning multiple stories a once

{
  "patch": [
    {
      "identifier": 2,
      "progress": "done"
    },
    {
      "identifier": 4,
      "progress": "done"
    }
  ]
}

Parameters

Name	In	Type	Required	Description
board	path	string	true	Either the board id or location
patch	body	[anyOf]	true	Story patches to apply
» anonymous	body	object	false	none
»» additionalProperties	body	object	false	none
»» id	body	string	true	Story unique ID
» anonymous	body	object	false	none
»» additionalProperties	body	object	false	none
»» identifier	body	integer	true	Story unique identifier

Example responses

Assigning multiple stories a once

[
  {
    "id": "8ed76538-ee9a-4b39-9407-6b392a7ddc35",
    "identifier": 2,
    "project": "8c34924f-21ca-406b-aaaa-749ad3d2f4fb",
    "title": "Document the RESTful API",
    "createdAt": "2025-03-21T16:32:17+00:00",
    "createdBy": "Bernard",
    "updatedAt": "2025-03-27T17:02:14+00:00",
    "kind": "todo",
    "progress": "done",
    "assignee": "Bernard",
    "due_date": null
  },
  {
    "id": "64751a76-d7dc-4695-b6c4-139f7082fc52",
    "identifier": 4,
    "project": "8c34924f-21ca-406b-aaaa-749ad3d2f4fb",
    "title": "Make sur the World knows about us",
    "createdAt": "2025-03-21T16:32:17+00:00",
    "createdBy": "Bernard",
    "updatedAt": "2025-03-27T17:02:14+00:00",
    "kind": "todo",
    "progress": "done",
    "assignee": "Marc",
    "due_date": null
  }
]

Responses

Status	Meaning	Description	Schema
200	OK	none	Inline

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» additionalProperties	object	false	none	none
» id	string	true	none	Unique story ID
» identifier	integer	true	none	Unique story identifier (autonumber)
» title	string	true	none	Story title
» createdBy	string	false	none	Who created the story
» createdAt	string	false	none	When was the story created
» updatedAt	string	false	none	When was the story last updated

Delete stories

Code samples

const inputBody = '{
  "stories": [
    {
      "identifier": 1
    },
    {
      "identifier": 2
    }
  ]
}';
const headers = {
  'Content-Type':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('/boards/{board}/stories',
{
  method: 'DELETE',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.delete '/boards/{board}/stories',
  params: {
  }, headers: headers

p JSON.parse(result)

# You can also use wget
curl -X DELETE /boards/{board}/stories \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {access-token}'

DELETE /boards/{board}/stories

Deletes many stories present in the board

Body parameter

Deleting many stories, based on their identifier

{
  "stories": [
    {
      "identifier": 1
    },
    {
      "identifier": 2
    }
  ]
}

Parameters

Name	In	Type	Required	Description
board	path	string	true	Either the board id or location
stories	body	[anyOf]	true	List of story references to delete
» anonymous	body	object	false	none
»» id	body	string	true	none
» anonymous	body	object	false	none
»» identifier	body	integer	true	none

Responses

Status	Meaning	Description	Schema
204	No Content	none	None

Get stories

Code samples


const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('/boards/{id}/stories',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.get '/boards/{id}/stories',
  params: {
  }, headers: headers

p JSON.parse(result)

# You can also use wget
curl -X GET /boards/{id}/stories \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

GET /boards/{id}/stories

Returns the stories visible in the board.

Parameters

Name	In	Type	Required	Description
id	path	string	true	Either the board id or location

Example responses

Getting the stories in the kanban board, filtered on assignee

[
  {
    "id": "64751a76-d7dc-4695-b6c4-139f7082fc52",
    "identifier": 4,
    "project": "8c34924f-21ca-406b-aaaa-749ad3d2f4fb",
    "title": "Make sur the World knows about us",
    "createdAt": "2025-03-21T16:32:17+00:00",
    "createdBy": "Bernard",
    "updatedAt": "2025-03-24T13:23:10+00:00",
    "kind": "todo",
    "progress": "ongoing",
    "assignee": "Marc",
    "due_date": null
  },
  {
    "id": "8ed76538-ee9a-4b39-9407-6b392a7ddc35",
    "identifier": 2,
    "project": "8c34924f-21ca-406b-aaaa-749ad3d2f4fb",
    "title": "Document the RESTful API",
    "createdAt": "2025-03-21T16:32:17+00:00",
    "createdBy": "Bernard",
    "updatedAt": "2025-03-24T13:23:07+00:00",
    "kind": "todo",
    "progress": "ongoing",
    "assignee": "Bernard",
    "due_date": null
  }
]

Responses

Status	Meaning	Description	Schema
200	OK	none	Inline

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» additionalProperties	object	false	none	none
» id	string	true	none	Unique story ID
» identifier	integer	true	none	Unique story identifier (autonumber)
» title	string	true	none	Story title
» createdBy	string	false	none	Who created the story
» createdAt	string	false	none	When was the story created
» updatedAt	string	false	none	When was the story last updated

Danger zone

Delete all stories

Code samples


const headers = {
  'Authorization':'Bearer {access-token}'
};

fetch('/danger-zone/delete-all-stories',
{
  method: 'POST',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.post '/danger-zone/delete-all-stories',
  params: {
  }, headers: headers

p JSON.parse(result)

# You can also use wget
curl -X POST /danger-zone/delete-all-stories \
  -H 'Authorization: Bearer {access-token}'

POST /danger-zone/delete-all-stories

Deletes all stories of the current project

Responses

Status	Meaning	Description	Schema
204	No Content	none	None

Delete project

Code samples


const headers = {
  'Authorization':'Bearer {access-token}'
};

fetch('/danger-zone/delete-project',
{
  method: 'POST',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.post '/danger-zone/delete-project',
  params: {
  }, headers: headers

p JSON.parse(result)

# You can also use wget
curl -X POST /danger-zone/delete-project \
  -H 'Authorization: Bearer {access-token}'

POST /danger-zone/delete-project

Deletes the current project

Responses

Status	Meaning	Description	Schema
204	No Content	none	None

Duplicate project

Code samples

const inputBody = '{
  "name": "Hello Klaro",
  "subdomain": "a-duplicate",
  "keepCards": true,
  "keepMembers": false
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'
};

fetch('/danger-zone/duplicate-project',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.post '/danger-zone/duplicate-project',
  params: {
  }, headers: headers

p JSON.parse(result)

# You can also use wget
curl -X POST /danger-zone/duplicate-project \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

POST /danger-zone/duplicate-project

Duplicates a project, with the option to keep the cards or the members.

Body parameter

Duplicating a project while keeping cards but not members

{
  "name": "Hello Klaro",
  "subdomain": "a-duplicate",
  "keepCards": true,
  "keepMembers": false
}

Parameters

Name	In	Type	Required	Description
name	body	string	true	none
subdomain	body	string	true	none
keepCards	body	boolean	true	none
keepMembers	body	boolean	true	none

Example responses

Duplicating a project while keeping cards but not members

{
  "location": "http://a-duplicate.klaro.devel/"
}

Responses

Status	Meaning	Description	Schema
201	Created	none	Inline

Response Schema

Status Code 201

Name	Type	Required	Restrictions	Description
» location	string	true	none	none