Introduction

Kanban Tool provides an API, which makes it extremely easy for any developer to integrate external systems with our platform - adding their own layer of awesomeness on the top of the Kanban Tool.

Using the API, you can create your own useful plugins (created exactly to fit your needs), synchronize tasks with other platforms or even code a customized backup solution - anything you want!

Getting started

Obtaining your access token

To interact with the API, you need to have a unique, personal access token, which is used to authenticate yourself within the API.

To generate your access token, you should:

1. Click on the My profile tab in the main menu:

   

2. Click on the API access link:

   

3. Click on the Enable API access button to generate a new token:

   

4. Note down your newly generated token - you are going to need it soon:

   

Accessing the API

Using wrappers

An example using our SDK:

KT.init(YOUR_DOMAIN, YOUR_TOKEN).then(() => {
  console.log(
    KT.currentUser.get('name')
  );
});

// -- You can use KT.call to make simple REST API queries: //

KT.call('GET', 'tasks/' + TASK_ID).then((response) => {
  console.log(response);
});

Instead of executing requests on your own, you can use our SDK library: https://kanbantool.com/assets/kanbantool-sdk.js

It provides a fluent, modern interface, which allows you to easily communicate with our API, without worrying about the internals. You can learn more about it on the SDK documentation page.

Using cURL

An example using cURL:

$ curl 'https://YOUR_DOMAIN.kanbantool.com/api/v3/users/current.json?access_token=YOUR_TOKEN'

# or (whichever suits you best)

$ curl 'https://YOUR_DOMAIN.kanbantool.com/api/v3/users/current.json' \
    -H 'Authorization: Bearer YOUR_TOKEN'

cURL is a sophisticated library (and a command-line application) which lets you send HTTP requests directly from your command line - it is available out-of-the-box in many Linux distributions.

If you are familiar with working in the console environment, you should have no trouble using cURL.

Using your web browser

An example using a web browser (enter the URL in the address bar):

https://YOUR_DOMAIN.kanbantool.com/api/v3/users/current.json?access_token=YOUR_TOKEN

Last but not least: you can fully interact with our API directly from your browser! No third-party software or any complex development tools are required.

Using other tools

There are also numerous other tools, which simplify the process of fiddling with our API - just to name a few:

• Advanced REST Client,
• Insomnia REST Client,
• HTTPie.

Requests & Responses

Requests

The Kanban Tool API is built with REST in mind, providing a simple, human-readable interface.

Example requests

DELETE /api/v3/some_action.json

POST /api/v3/some_action.json

The _m parameter

In case you have problem with using RESTful verbs, you can always pass the _m parameter, which defines the method you want to call:

GET /api/v3/some_action.json?_m=delete

Responses

The API supports returning data in json and jsonp formats. The response type is dependent on the extension you pass:

GET /api/v3/some_action.json?parameter=value

GET /api/v3/some_action.json?callback=myFunction&parameter=value

Authentication

Example code:

KT.init(YOUR_DOMAIN, YOUR_TOKEN).then(() => {
   // code after a successful authentication 
});

# Using Authorization header:

$ curl 'https://YOUR_DOMAIN.kanbantool.com/api/v3/some_action.json' \
    -H 'Authorization: Bearer YOUR_TOKEN'

To use our API, you must first obtain your own access token - from now on we're going to assume you already have one.

You can authenticate by passing your token in the Authorization HTTP header (Authorization: Bearer YOUR_TOKEN).

Working with Users

Fetching users

This command returns information about given user.

Request

GET /api/v3/users/:user_id.json

Response

This command returns a user object.

Errors

• This command returns a 404 Not Found response when given an invalid user_id.

Fetching current user

Example code:

// KT.currentUser is loaded automatically upon a call to KT.init(...)
KT.onInit(() => {
  console.log(KT.currentUser);
});

KT.init(YOUR_DOMAIN, API_TOKEN);

curl 'https://YOUR_DOMAIN.kanbantool.com/api/v3/users/current.json' \
  -H 'Authorization: Bearer ...'

Example response:

{
  "id": 1000,
  "version": 22,
  "name": "Jon Snow",
  "initials": "JS",
  "timezone": "Winterfell",

  /* ... */  
}

This command returns information about currently authenticated user.

It is an equivalent of fetching the user, if you already know its id.

Request

GET /api/v3/users/current.json

Response

This command returns a user object.

Errors

This command usually does not fail.

Working with Boards

Listing accessible boards

Example code:

console.log(
    KT.currentUser.get('boards')
);

curl 'https://YOUR_DOMAIN.kanbantool.com/api/v3/users/current.json' \
  -H 'Authorization: Bearer ...'

Example response:

{
  /* ... */

  "boards": [
    {
      "id": 100000,
      "name": "First Board",
      "folder": null,
      "position": null,
      "last_activity_on": "2018-01-01",

      "permissions": [
        "create_tasks",
        "read_tasks",
        "update_tasks",
        "delete_tasks",
        "move_tasks"
      ]
    },

    {
      "id": 100001,

      /* ... */
    }

    /* ... */
  ],

  /* ... */
}

To list all boards user has access to, you should fetch the user and access its boards field.

Fetching boards

Example code:

KT.boards.stub(BOARD_ID).preload().then((board) => {
    console.log(board);
});

curl 'https://YOUR_DOMAIN.kanbantool.com/api/v3/boards/:board_id/preload.json' \
  -H 'Authorization: Bearer ...'

Example response:

{
  "id": 100000,
  "version": 1,
  "external_id_sequence": 1,
  "account_id": 200000,
  "owner_id": 300000,
  "folder_id": null,
  "board_template_id": "personal_timedriven",

  "position": null,
  "name": "First Board",
  "description": "This is my first board.",

  "created_at": "2018-01-01T12:00:00.000+01:00",
  "updated_at": "2018-01-01T12:00:00.000+01:00",
  "settings_updated_at": "2018-01-01T12:00:00.000+01:00",
  "last_activity_on": "2018-01-01",
  "deleted_at": null,

  "swimlanes": [
    /* ... */
  ],

  "workflow_stages": [
    /* ... */
  ],

  "card_types": [
   /* ... */
  ],

  "collaborators": [
   /* ... */
  ],

  "stats": [
    /* ... */
  ],

  "card_template": {
    /* ... */
  },

  "settings": {
   /* ... */
  }
}

This command returns overall information about given board.

Request

GET /api/v3/boards/:board_id/preload.json

Response

This command returns a board object.

Errors

• This command returns a 404 Not Found response when given an invalid board_id.

Fetching boards' details

Example code:

KT.boards.stub(BOARD_ID).load().then((board) => {
    console.log(board);
});

curl 'https://YOUR_DOMAIN.kanbantool.com/api/v3/boards/:board_id.json' \
  -H 'Authorization: Bearer ...'

Example response:

{
  "id": 100000,
  "version": 1,
  "external_id_sequence": 1,
  "account_id": 200000,
  "owner_id": 300000,
  "folder_id": null,
  "board_template_id": "personal_timedriven",

  "position": null,
  "name": "First Board",
  "description": "This is my first board.",

  "created_at": "2018-01-01T12:00:00.000+01:00",
  "updated_at": "2018-01-01T12:00:00.000+01:00",
  "settings_updated_at": "2018-01-01T12:00:00.000+01:00",
  "last_activity_on": "2018-01-01",
  "deleted_at": null,

  "swimlanes": [
    /* ... */
  ],

  "workflow_stages": [
    /* ... */
  ],

  "tasks": [
    /* ... */
  ],

  "card_types": [
    /* ... */
  ],

  "collaborators": [
    /* ... */
  ],

  "stats": [
    /* ... */
  ],

  "card_template": {
    /* ... */
  },

  "settings": {
    /* ... */
  }
}

This command returns detailed information about given board and its tasks.

Request

GET /api/v3/boards/:board_id.json

Response

This command returns a board object.

Errors

• This command returns a 404 Not Found response when given an invalid board_id.

Listing boards' changelogs

Example code:

KT.boards.stub(BOARD_ID).load().then((board) => {
    console.log(
        board.get('changelogs')
    );
});

// -- or -- //

KT.boards.load(BOARD_ID, (board) => {
    console.log(
        board.get('changelogs')
    );
});

curl 'https://YOUR_DOMAIN.kanbantool.com/api/v3/boards/:board_id/changelog.json' \
  -H 'Authorization: Bearer ...'
  -d 'before=100000000'

Example response:

[
  {
    "id": 10000000,
    "board_id": 100000,
    "board_version": 32,
    "workflow_stage_id": 200000,
    "swimlane_id": 300000,
    "user_id": null,

    "what": "cloned",
    "description": "'Do something' has recurred",

    "changed_object_id": 200000,
    "changed_object_type": "Task",
    "changed_object_version": 5,

    "created_at": "2018-01-01T12:00:00.000+01:00",

    "data": {
      "task_id": 200000,
      "task_name": "Do something",
      "task_external_id": "",

      "workflow_stage_id": 200000,
      "workflow_stage_name": "In progress",

      "swimlane_id": 300000,
      "swimlane_name": "Team A"
    },
  },

  {
    /* ... */
  },

  /* ... */
]

This command returns a list of all the changelogs from given board.

Request

GET /api/v3/boards/:board_id/changelog.json

Parameters

This command accepts a JSON object with following fields:

Parameter	Type	Required	Description
before	integer	Yes	When present, returns only changelogs matching id < :before.
after	integer	Yes	When present, returns only changelogs matching id > :after.
limit	integer	No	Maximum number of items to return.

Response

This command returns a list of changelog objects.

Errors

• This command returns a 404 Not Found response when given an invalid board_id.

Working with Tasks

Listing board's tasks

Example code:

KT.boards.stub(BOARD_ID).load().then((board) => {
  console.log(
    board.tasks()
  );
});

// -- or -- //

KT.boards.load(BOARD_ID, () => {
  console.log(
    KT.tasks.where({
        board_id: BOARD_ID,
    })
  );
});

curl 'https://YOUR_DOMAIN.kanbantool.com/api/v3/boards/:board_id.json' \
  -H 'Authorization: Bearer ...'

Example response:

{
  "id": 100000,

  /* ... */

  "name": "First board",
  "description": "This is my first board.",

  /* ... */

  "tasks": [
    {
      "id": 500000,
      "board_id": 100000,
      "workflow_stage_id": 200000,

      "position": 1,
      "name": "Make Mary a sandwich.",
      "description": null,

      "priority": 0,
      "tags": "",
      "recurring_schedule": null,

      "created_at": "2018-01-01T12:00:00.000+01:00",
      "updated_at": "2018-01-01T12:00:00.000+01:00",
      "deleted_at": null,

      "subtasks": [
        /* ... */
      ],

      /* ... */
    },

    {
      /* ... */
    },

    /* ... */
  ],
}

To list board's tasks, you should fetch the board's details and access its tasks field. To get archived tasks, you should use the task search endpoint and set the board_id and archived=1 parameters.

Searching for tasks

KT.call('GET', 'tasks/search', {
  q: YOUR_QUERY,
});

curl 'https://YOUR_DOMAIN.kanbantool.com/api/v3/tasks/search.json' \
  -H 'Authorization: Bearer ...'

This command allows to search through all the tasks user has access to.

Request

GET /api/v3/tasks/search.json

Parameters

This command accepts the following query parameters:

Parameter	Type	Required	Description
q	string	Yes	Query used to filter tasks (see paragraph below for reference). Required, but may be an empty string.
limit	integer	No	Maximum number of items to return, or number of items per page if given.
page	integer	No	Page number. If set additional pagination info is returned together with results.
board_id	string	No	Comma separated list of board IDs to narrow the search to.
archived	integer	No	Set to 1 to search through archived tasks.

Query filters

Filter	Example	Description
-	any text	Does a full-text search (by task names, their descriptions etc.).
@	@xz	Filters by tasks' assignee's initials.
id	id<=100000	Filters by tasks' ids.
name	name:XYZ	Filters by tasks' names.
description	description:XYZ	Filters by tasks' description.
board_id	board_id=100000	Filters by boards' ids.
priority	priority:-1	Filters by tasks' priority (three options are possible: 0 (normal), 1 (high) and -1 (low)).
tags	tags:"external work"	Filters by tasks' tags.
external_id	external_id:673409	Filters by tasks' external id.
timers_total	timers_total>2:15	Filters by sum of tasks' timers. 2:15 determines time (2 minutes & 15 seconds in this case).
custom_field_3	custom_field_3=3735928559	Filters by tasks' custom fields.
subtasks_count	subtasks_count<5	Filters by number of subtasks.
subtasks_completed_count	subtasks_completed_count<5	Filters by number of subtasks that have been completed.
comments_count	coments_count>3	Filters by number of comments.
attachments_count	attachments_count=2	Filters by number of attachments.
size_estimate	size_estimate>=2	Filters by tasks' difficulty field.
is	is=in_progress	Filters by lane types. Available options: backlog_inventory, waiting, in_progress or done.
type	type:=Default	Filters by card types.
due_date	due_date=2017-04-01	Filters by tasks' due date date (you can use statements like 2.days.from_now or 3.days.ago)
created_at	created_at>:2021-03-17	Filters by tasks' creation date
updated_at	updated_at<:2021-03-17	Filters by tasks' update date
recurring_schedule	recurring_schedule:2017-03-20	Filters by tasks' date to recur
external_link	external_link:docs.google	Filters by tasks' external link
block_reason	block_reason:?	Filters by tasks' block reason
time_estimate	time_estimate>10:12	Filters by tasks' time estimate
timers_active_count	timers_active_count>=3	Filters by number of users who working on the task at the time of querying

Response

This command returns a list of simplified tasks' objects or an object consisting of pagination ({results_count,page,pages_count}) and results (array of simplified tasks' objects) if page parameter is set.

Field	Type	Description
id	integer	Task's unique identifier.
board_id	integer	Id of the board to which this task belongs to.
archived_at	?dateTime	Date & time when task was archived - if it's been archived.
card_type_name	string	Name of a task's card type
card_type_color_ref	string	Task's card's background color name (e.g. yellow).
card_color_in_rgb	string	Task's card's background color value (e.g. #ffeB3b).
card_color_invert	?boolean	If equal to true, task's card's foreground (text) color should be white (instead of the default black one), for it to be readable.

Errors

This command usually does not fail.

Fetching tasks

Example code:

KT.tasks.stub(TASK_ID).preload().then((task) => {
  console.log(task);
});

// -- or -- //

KT.tasks.preload(TASK_ID, (task) => {
  console.log(task);
});

// -- or -- //

KT.call('GET', 'tasks/' + TASK_ID).then((response) => {
  console.log(response);
});

curl 'https://YOUR_DOMAIN.kanbantool.com/api/v3/tasks/:task_id/preload.json' \
  -H 'Authorization: Bearer ...'

Example response:

{
  "id": 500000,
  "board_id": 100000,
  "workflow_stage_id": 200000,

  "position": 1,
  "name": "Make Mary a sandwich.",
  "description": null,

  "priority": 0,
  "tags": "",
  "recurring_schedule": null,

  "created_at": "2018-01-01T12:00:00.000+01:00",
  "updated_at": "2018-01-01T12:00:00.000+01:00",
  "deleted_at": null,

  /* ... */
},

This command returns overall information about given task.

Request

GET /api/v3/tasks/:task_id/preload.json

Response

This command returns a task object.

Errors

• This command returns a 404 Not Found response when given an invalid task_id.

Fetching tasks' details

Example code:

KT.tasks.stub(TASK_ID).load().then((task) => {
    console.log(task);
});

// -- or -- //

KT.call('GET', 'tasks/' + TASK_ID).then((response) => {
  console.log(response);
});

curl 'https://YOUR_DOMAIN.kanbantool.com/api/v3/tasks/:task_id.json' \
  -H 'Authorization: Bearer ...'

Example response:

{
  "id": 500000,
  "board_id": 100000,
  "workflow_stage_id": 200000,

  "position": 1,
  "name": "Make Mary a sandwich.",
  "description": null,

  "priority": 0,
  "tags": "",
  "recurring_schedule": null,

  "created_at": "2018-01-01T12:00:00.000+01:00",
  "updated_at": "2018-01-01T12:00:00.000+01:00",
  "deleted_at": null,

  "search_tags": [
    /* ... */
  ],

  "collaborators": [
    /* ... */
  ],

  "comments": [
    /* ... */
  ],

  "subtasks": [
    /* ... */
  ],

  "attachments": [
    /* ... */
  ],

  "changelogs": [
    /* ... */
  ],

  "time_trackers": [
    /* ... */
  ]
}

This command returns detailed information about given task.

Request

GET /api/v3/tasks/:task_id.json

Response

This command returns a task object.

Errors

• This command returns a 404 Not Found response when given an invalid task_id.

Creating tasks

Example code:

const task = KT.tasks.create({
    board_id: 100000,
    name: 'Make Mary a sandwich.'
});

console.log(task);

curl 'https://YOUR_DOMAIN.kanbantool.com/api/v3/tasks.json' \
  -X 'POST' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ...' \
  -d '{"board_id":123, "name": "Make Mary a sandwich."}'

Example response:

{
  "id": 500000,
  "board_id": 123,
  "workflow_stage_id": 200000,

  "position": 1,
  "name": "Make Mary a sandwich.",
  "description": null,

  "priority": 0,
  "tags": "",
  "recurring_schedule": null,

  "created_at": "2018-01-01T12:00:00.000+01:00",
  "updated_at": "2018-01-01T12:00:00.000+01:00",
  "deleted_at": null,

  "search_tags": [
    /* ... */
  ],

  "collaborators": [
    /* ... */
  ],

  "comments": [
    /* ... */
  ],

  "subtasks": [
    /* ... */
  ],

  "attachments": [
    /* ... */
  ],

  "changelogs": [
    /* ... */
  ],

  "time_trackers": [
    /* ... */
  ]
}

This command creates a new task.

Request

POST /api/v3/tasks.json

Parameters

This command accepts task's data wrapped in a task array, e.g.: task[name]. The required parameters are task[name] and task[board_id].

Unless specified with task[workflow_stage_id], task[swimlane_id] and task[card_type_id], new tasks will be created in the top-left cell using the default card type.

Response

This command returns a task object.

Errors

• This command returns a 404 Not Found response when given an invalid board_id (or when it hasn't been specified at all).

• This command returns a 422 Unprocessable Entity response when any field is missing or has an invalid format.

Additional options

Parameter	Description
task[task_attachment_ids]	Array of IDs of previously uploaded attachments which should be attached to this task.
task[subtask_ids]	Array of IDs of previously created subtasks which should be attached to this task.
assert_has_unique_external_id	If set, verifies that task with given external_id does not already exist on this board.

Updating tasks

Example code:

const task = KT.tasks.stub(TASK_ID);

task.set('name', 'Make Jenny a sandwich.');

task.save().then(() => {
   console.log('Task has been updated.');
});

// -- you can also update many options at once: -- //

task.save({
    name: 'Make Jenny a sandwich.',
    description: 'And do it now!',
});

// -- or use plain KT.call: -- //

KT.call('PATCH', 'tasks/' + TASK_ID, {
  'task[name]': 'Make Jenny a sandwich.',
}).then((response) => {
  console.log('Task has been updated.');
  console.log(response.task);
});

curl 'https://YOUR_DOMAIN.kanbantool.com/api/v3/tasks/:task_id.json' \
  -X 'PATCH' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ...' \
  -d '{"name":"Make Jenny a sandwich.", "description": "And do it now!"}'

Example response:

{
  "id": 500000,
  "board_id": 100000,
  "workflow_stage_id": 200000,

  "position": 1,
  "name": "Make Jenny a sandwich.",
  "description": null,

  /* ... */

  "created_at": "2018-01-01T12:00:00.000+01:00",
  "updated_at": "2018-01-01T12:00:00.000+01:00",
  "deleted_at": null,

  /* ... */
}

This commands updates a task.

Request

PATCH /api/v3/tasks/:task_id.json

Parameters

This command accepts task's data wrapped in a task array, e.g.: task[name].

Response

This command returns a task object.

Errors

• This command returns a 404 Not Found response when given an invalid task_id, task[board_id] (if specified) and so on.

Archiving tasks

Example code:

KT.tasks
    .groupUpdate([TASK_ID], { _action: 'archive' })
    .then(() => {
        console.log('Task has been archived.');
    });

curl 'https://YOUR_DOMAIN.kanbantool.com/api/v3/tasks/:task_id.json' \
  -X 'PATCH' \
  -H 'Authorization: Bearer ...' \
  -H 'Content-Type: application/json' \
  -d '{"_action":"archive"}' 

Example response:

{
  "id": 500000,
  "board_id": 100000,
  "workflow_stage_id": 200000,

  "position": 1,
  "name": "Make Jenny a sandwich.",
  "description": null,

  /* ... */

  "created_at": "2018-01-01T12:00:00.000+01:00",
  "updated_at": "2018-01-01T12:00:00.000+01:00",
  "deleted_at": null,

  /* ... */
}

This command archives a task.

Request

PATCH /api/v3/tasks/:task_id.json

Parameters

This command accepts a JSON object with following field:

Parameter	Type	Required	Value
_action	string	Yes	archive

Response

This command returns a task object.

Errors

• This command returns a 404 Not Found response when given an invalid task_id.

Unarchiving tasks

Example code:

KT.tasks
    .groupUpdate([TASK_ID], { _action: 'unarchive' })
    .then(() => {
        console.log('Task has been unarchived.');
    });

curl 'https://YOUR_DOMAIN.kanbantool.com/api/v3/tasks/:task_id.json' \
  -X 'PATCH' \
  -H 'Authorization: Bearer ...' \
  -H 'Content-Type: application/json' \
  -d '{"_action":"unarchive"}' 

Example response:

{
  "id": 500000,
  "board_id": 100000,
  "workflow_stage_id": 200000,

  "position": 1,
  "name": "Make Jenny a sandwich.",
  "description": null,

  /* ... */

  "created_at": "2018-01-01T12:00:00.000+01:00",
  "updated_at": "2018-01-01T12:00:00.000+01:00",
  "deleted_at": null,

  /* ... */
}

This command unarchives a task.

Request

PATCH /api/v3/tasks/:task_id.json

Parameters

This command accepts a JSON object with following field:

Parameter	Type	Required	Value
_action	string	Yes	unarchive

Response

This command returns a task object.

Errors

• This command returns a 404 Not Found response when given an invalid task_id.

Deleting tasks

Example code:

KT.tasks
    .groupUpdate([TASK_ID], { _action: 'delete' })
    .then(() => {
        console.log('Task has been deleted.');
    });

curl 'https://YOUR_DOMAIN.kanbantool.com/api/v3/tasks/:task_id.json' \
  -X 'PATCH' \
  -H 'Authorization: Bearer ...' \
  -H 'Content-Type: application/json' \
  -d '{"_action":"delete"}' 

Example response:

{
  "id": 500000,
  "board_id": 100000,
  "workflow_stage_id": 200000,

  "position": 1,
  "name": "Make Jenny a sandwich.",
  "description": null,

  /* ... */

  "created_at": "2018-01-01T12:00:00.000+01:00",
  "updated_at": "2018-01-01T12:00:00.000+01:00",
  "deleted_at": "2018-01-01T12:00:00.000+01:00",

  /* ... */
}

This command deletes a task.

Request

PATCH /api/v3/tasks/:task_id.json

Parameters

This command accepts a JSON object with following field:

Parameter	Type	Required	Value
_action	string	Yes	delete

Response

This command returns a task object.

Errors

• This command returns a 404 Not Found response when given an invalid task_id.

Restoring tasks

Example code:

KT.tasks
    .groupUpdate([TASK_ID], { _action: 'undelete' })
    .then(() => {
        console.log('Task has been restored.');
    });

curl 'https://YOUR_DOMAIN.kanbantool.com/api/v3/tasks/:task_id.json' \
  -X 'PATCH' \
  -H 'Authorization: Bearer ...' \
  -H 'Content-Type: application/json' \
  -d '{"_action":"undelete"}' 

Example response:

{
  "id": 500000,
  "board_id": 100000,
  "workflow_stage_id": 200000,

  "position": 1,
  "name": "Make Jenny a sandwich.",
  "description": null,

  /* ... */

  "created_at": "2018-01-01T12:00:00.000+01:00",
  "updated_at": "2018-01-01T12:00:00.000+01:00",
  "deleted_at": null,

  /* ... */
}

This command restores a task.

Request

PATCH /api/v3/tasks/:task_id.json

Parameters

This command accepts a JSON object with following field:

Parameter	Type	Required	Value
_action	string	Yes	undelete

Response

This command returns a task object.

Errors

• This command returns a 404 Not Found response when given an invalid task_id.

Working with Subtasks

Listing subtasks

There's no endpoint dedicated only to listing subtasks - you should fetch the task's details and access its subtasks field.

Creating subtasks

Example code:

const task = KT.tasks.stub(TASK_ID);

const subtask = task.subtasks().create({
    name: 'Take out the bread.',
});

console.log(subtask);

curl 'https://YOUR_DOMAIN.kanbantool.com/api/v3/subtasks.json' \
  -X 'POST' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ...' \
  -d '{"task_id": 123, "name": "Take out the bread."}'

Example response:

{
  "id": 600000,

  "task_version": 1,
  "task_id": 123,

  "created_by_id": 900,
  "assigned_user_id": null,

  "name": "Take out the bread.",
  "position": 1,
  "is_completed": false,

  "created_at": "2018-01-01T12:00:00.000+01:00",
  "updated_at": "2018-01-01T12:00:00.000+01:00",
  "deleted_at": null
}

This command creates a new subtask.

Request

POST /api/v3/subtasks.json

Parameters

This command accepts a JSON object with following fields:

Parameter	Type	Required	Default value
name	string	Yes	-
task_id	?integer	No	null
assigned_user_id	?integer	No	null
is_completed	boolean	No	false

Response

This command returns a subtask object.

Errors

• This command returns a 400 Bad Request response when given no parameters.

• This command returns a 422 Unprocessable Entity when given an invalid parameter (eg. empty subtask's name).

Updating subtasks

Example code:

KT.tasks.load(TASK_ID, (task) => {
  subtask = task.subtasks().get(SUBTASK_ID);

  subtask.set('name', 'Buy a bread.');

  subtask.save().then(() => {
    console.log('Subtask has been updated.');
  });
}),

// -- you can also update many options and save at once: -- //

subtask.save({
    name: 'Buy a bread.',
    assigned_user_id: 1000,
});

curl 'https://YOUR_DOMAIN.kanbantool.com/api/v3/subtasks/:subtask_id.json' \
  -X 'PATCH' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ...' \
  -d '{"name": "Buy a bread."}'

Example response:

{
  "id": 600000,

  "task_version": 1,
  "task_id": 500000,

  "created_by_id": 900,
  "assigned_user_id": null,

  "name": "Buy a bread.",
  "position": 1,
  "is_completed": false,

  "created_at": "2018-01-01T12:00:00.000+01:00",
  "updated_at": "2018-01-01T12:00:00.000+01:00",
  "deleted_at": null
}

This command updates a subtask.

Request

PATCH /api/v3/subtasks/:subtask_id.json

Parameters

This command accepts a JSON object with following fields:

Parameter	Type
name	string
task_id	?integer
assigned_user_id	?integer
is_completed	boolean

Response

This command returns a subtask object.

Errors

• This command returns a 404 Not Found when given an invalid subtask_id.

Deleting subtasks

Example code:

KT.call('DELETE', 'tasks/' + TASK_ID + '/comments/' + COMMENT_ID).then(() => {
  console.log('Comment has been deleted.');
});

// -- or -- //

KT.tasks.load(TASK_ID, (task) => {
  subtask = task.subtasks().get(SUBTASK_ID);

  subtask.destroy().then(() => {
    console.log('Subtask has been deleted.');
  });
});

curl 'https://YOUR_DOMAIN.kanbantool.com/api/v3/subtasks/:subtask_id.json' \
  -X 'DELETE' \
  -H 'Authorization: Bearer ...'

Example response:

{
  "id": 600000,

  "task_version": 1,
  "task_id": 500000,

  "created_by_id": 900,
  "assigned_user_id": null,

  "name": "Buy a bread.",
  "position": 1,
  "is_completed": false,

  "created_at": "2018-01-01T12:00:00.000+01:00",
  "updated_at": "2018-01-01T12:00:00.000+01:00",
  "deleted_at": "2018-01-01T12:00:00.000+01:00"
}

This command soft-deletes a subtask.

Request

DELETE /api/v3/subtasks/:subtask_id.json

Response

This command returns a subtask object.

Errors

• This command returns a 404 Not Found response when given an invalid subtask_id.

Reordering subtasks

Example code:

KT.call('PUT', 'subtasks/reorder', {
  task_id: TASK_ID,
  ids: COMMA_SEPARATED_COMMENT_IDS,
});

// -- or -- //

KT.tasks.load(TASK_ID, (task) => {
  subtasks = task.subtasks();

  subtasks
    .reorder([FIRST_SUBTASK_ID, SECOND_SUBTASK_ID, ...])
    .then(() => {
      console.log('Subtasks have been reordered.');
    });
});

curl 'https://YOUR_DOMAIN.kanbantool.com/api/v3/subtasks/reorder.json' \
  -X 'PUT' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ...' \
  -d '{"task_id": "7000", "ids": "30000,10000,20000"}'

Example response:

[
  {
    "id": 600000,

    "task_version": 1,
    "task_id": 500000,

    "created_by_id": 900,
    "assigned_user_id": null,

    "name": "Buy bread.",
    "position": 1,
    "is_completed": false,

    "created_at": "2018-01-01T12:00:00.000+01:00",
    "updated_at": "2018-01-01T12:00:00.000+01:00",
    "deleted_at": null
  },

  {
    /* ... */
  },

  /* ... */
]

This command reorders all subtasks of given task.

Request

PUT /api/v3/subtasks/reorder.json

Parameters

This command accepts a JSON object with following fields:

Parameter	Type	Required	Description
task_id	integer	Yes	Id of the task in which subtasks should be reordered.
ids	string	Yes	Comma-separated ids of the subtasks in the new order.

Response

This command returns a list of subtask objects.

Errors

• This command returns a 404 Not Found response when given an invalid task_id.

Working with Comments

Listing comments

Example code:

KT.tasks.stub(TASK_ID).load().then((task) => {
  console.log(
    task.get('comments')
  );
});

// -- or -- //

KT.call('GET', 'tasks/' + TASK_ID).then((response) => {
  console.log(response.comments);
});

curl 'https://YOUR_DOMAIN.kanbantool.com/api/v3/tasks/:task_id.json' \
  -H 'Authorization: Bearer ...'

Example response:

{
  "id": 500000,

  /* ... */

  "comments": [
    {
      "id": 900000,
      "user_id": 4000,
      "commentable_version": 1,
      "content": "Hey, who turned out the lights?",

      /* ... */
    },

    /* ... */
  ],

  /* ... */
}

To list task's comments, you should fetch the task's details and access its comments field.

Creating comments

Example code:

const task = KT.tasks.stub(TASK_ID);

const comment = task.comments().create({
  content: 'Do not forget about the Order 66.',
});

console.log(comment);

curl 'https://YOUR_DOMAIN.kanbantool.com/api/v3/tasks/:task_id/comments.json' \
  -X 'POST' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ...' \
  -d '{"content": "Do not forget about the Order 66."}'

Example response:

{
  "comment": {
    "id": 500000,
    "user_id": 100000,
    "commentable_version": 5,

    "content": "Do not forget about the Order 66.",

    "created_at": "2018-01-01T12:00:00.000+01:00",
    "updated_at": "2018-01-01T12:00:00.000+01:00",
    "deleted_at": null,

    "recipients": null,

    "attachments": [
      /* ... */      
    ]
  }
}

This command creates a new comment.

Request

POST /api/v3/tasks/:task_id/comments.json

Parameters

This command accepts a JSON object with following fields:

Parameter	Type	Required	Default value
content	string	Yes	-

Response

This command returns a comment object.

Errors

• This command returns a 400 Bad Request response when given no parameters.

• This command returns a 422 Unprocessable Entity when given an invalid parameter (empty comment's content).

Deleting comments

Example code:

KT.tasks.load(TASK_ID, (task) => {
  comment = task.comments().get(COMMENT_ID);

  comment.destroy().then(() => {
    console.log('Comment has been deleted.');
  });
});

curl 'https://YOUR_DOMAIN.kanbantool.com/api/v3/tasks/:task_id/comments/:comment_id.json' \
  -X 'DELETE' \
  -H 'Authorization: Bearer ...'

Example response:

{
    "id": 900000,
    "user_id": 4000,
    "commentable_version": 1,
    "content": "Hey, who turned out the lights?",

    /* ... */
}

This command soft-deletes a comment.

Request

DELETE /api/v3/tasks/:task_id/comments/:comment_id.json

Response

This command returns a comment object.

Errors

• This command returns a 404 Not Found response when given an invalid task_id or comment_id.

Working with Attachments

Listing attachments

There's no endpoint dedicated only to listing attachments - you should fetch the task's details and access its attachments field.

Creating attachments

Example code:

window.myCallback = (attachments) => {
  const successfullyUploadedAttachments = attachments[0];
  const attachment = successfullyUploadedAttachments[0];

  console.log(attachment);
};

KT.Attachments.upload({
  callback: 'myCallback',
  'attachments[][name]': 'some-file.gif',
  'attachments[][url]': 'https://i.imgur.com/yed5Zfk.gif',
});

curl 'https://YOUR_DOMAIN.kanbantool.com/api/v3/attachments.json' \
  -X 'POST' \
  -H 'Authorization: Bearer ...' \
  -F 'files[]=@fileName.png' \
  -F 'attachable=Board#100000'

Example response:

[
  [
    {
      "id": 900000000,
      "name": "fileName.png",
      "content_type": "application\/octet-stream",
      "size": 123456,
      "data": null,
      "created_at": "2018-01-01T12:00:00.000+01:00",
      "updated_at": "2018-01-01T12:00:00.000+01:00",
      "url": "\/system\/attachments\/abdef-ghijk\/fileName.png"
    }
  ],

  /* ... */
]

This method creates an attachment and optionally binds it to given object.

Request

POST /api/v3/attachments.json

Parameters

This command accepts a JSON object with following fields:

Parameter	Type	Required	Description
files[]	blob	Yes	File to upload (like in a regular multipart/form-data form).
attachable	string	No	String representing attachable to which attachment should be bound. See paragraph below for reference.

Attachables

Syntax	Example	Description
Board#:board_id	Board#100000	Represents a board with given id.
Task#:task_id	Task#200000	Represents a task with given id.

Response

This command returns an array of attachment objects.

First array item contains attachments which were uploaded successfully.

Second array item contains attachments which failed to upload.

Third array item contains all the above attachments.

Errors

• This command fails when no files[] item is present in the request.

• This command returns a 404 Not Found response when given an invalid attachable.

Detaching attachments

Example code:

KT.tasks.load(TASK_ID, (task) => {
  attachment = task.attachments().get(ATTACHMENT_ID);
  attachment.detach(task);
});

curl 'https://YOUR_DOMAIN.kanbantool.com/api/v3/attachments/:attachment_id/detach.json' \
  -X 'DELETE' \
  -H 'Authorization: Bearer ...'

This command detaches given attachment from specified object.

Request

DELETE /api/v3/attachments/:attachment_id/detach.json

Parameters

This command accepts a JSON object with following fields:

Parameter	Type	Required	Description
attachable	string	No	String representing attachable from which attachment should be detached. See paragraph on Creating attachments for reference.

Response

This command returns no response.

Errors

• This command returns a 403 Forbidden when given an invalid or un-detachable attachment.

Setting the mode attribute

Example code:

KT.tasks.load(TASK_ID, (task) => {
  attachment = task.attachments().get(ATTACHMENT_ID);
  attachment.toggleModeFlag(task, 'PIN');
});

curl 'https://YOUR_DOMAIN.kanbantool.com/api/v3/attachments/:attachment_id/set_mode.json?mode=0' \
  -H 'Authorization: Bearer ...'

This command sets the attachment's mode attribute, which is used by the frontend code to store custom binary flags, currently determining whether attachment is pinned to the card (1), and if it is set as a cover image for a card (2).

Request

PATCH /api/v3/attachments/:attachment_id/set_mode.json?mode=:mode&attachable=:attachable

Parameters

This command accepts the following parameters:

Parameter	Type	Required	Description
attachable	string	Yes	String representing attachable from which mode should be set. See paragraph on Creating attachments for reference.
mode	integer	yes	Integer describing binary flags set on the attachment: 0 - none, 1 - pinned to the card, 2 - set as card cover, 3 - pinned & cover.

Response

This command returns no response.

Errors

• This command returns a 403 Forbidden when given an invalid attachable.

Working with Time Trackers

Listing time trackers for current user

To list user's time trackers, you should fetch the user and access its time_trackers field.

Creating time trackers

Example code:

KT.call('POST', 'time_trackers', {
    board_id: BOARD_ID,
    task_id: TASK_ID,
}).then(() => {
  console.log('Time tracker has been created.');
});

curl 'https://YOUR_DOMAIN.kanbantool.com/api/v3/time_trackers.json' \
  -X 'POST' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ...' \
  -d '{"board_id": 200000, "task_id": 300000}'

Example response:

{
  "time_tracker": {
    "id": 700000,
    "user_id": 100000,
    "board_id": 200000,
    "task_id": 300000,
    "position": null,
    "listed": true,
    "seconds_from_resumed_sprint": 0,
    "started_at": "2018-01-01T12:00:00.000+01:00",
    "ended_at": "2018-01-01T12:00:00.000+01:00",
    "highlighted_at": null,
    "enlist_at": null,
    "created_at": "2018-01-01T12:00:00.000+01:00",
    "updated_at": "2018-01-01T12:00:00.000+01:00"
  }
}

This command creates a new time tracker.

Request

POST /api/v3/time_trackers.json

Parameters

This command accepts a JSON object with following fields:

Parameter	Type	Required	Default value
board_id	integer	Yes	-
task_id	integer	Yes	-
position	?integer	No	1
listed	boolean	No	true
started_at	dateTime	No	current date and time
ended_at	?dateTime	No	null
highlighted_at	?dateTime	No	null

Response

This command returns a time tracker object.

Errors

• This command returns a 404 Not Found response when given an invalid board_id or task_id.

• This command returns a 422 Unprocessable Entity response when given an invalid input (ended_at in past, wrong format of some field and so on).

Updating time trackers

Example code:

KT.call('PUT', 'time_trackers/' + TIME_TRACKER_ID, {
    started_at: '2018-01-01T13:00:00.000+01:00',
    ended_at: '2018-01-01T13:30:00.000+01:00',
}).then(() => {
  console.log('Time tracker has been updated.');
});

curl 'https://YOUR_DOMAIN.kanbantool.com/api/v3/time_trackers/:time_tracker_id.json' \
  -X 'PUT' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ...' \
  -d '{"started_at": "2018-01-01T13:00:00.000+01:00", "ended_at": "2018-01-01T13:30:00.000+01:00"}'

Example response:

{
  "time_tracker": {
    "id": 700000,
    "user_id": 100000,
    "board_id": 200000,
    "task_id": 300000,
    "position": null,
    "listed": true,
    "seconds_from_resumed_sprint": 0,
    "started_at": "2018-01-01T13:00:00.000+01:00",
    "ended_at": "2018-01-01T13:30:00.000+01:00",
    "highlighted_at": null,
    "enlist_at": null,
    "created_at": "2018-01-01T12:00:00.000+01:00",
    "updated_at": "2018-01-01T12:00:00.000+01:00"
  }
}

This commands updates a time tracker.

Request

PUT /api/v3/time_trackers/:time_tracker_id.json

Parameters

Parameter	Type
position	?integer
listed	boolean
started_at	?dateTime
ended_at	?dateTime
highlighted_at	?dateTime

Response

This command returns a time tracker object.

Errors

• This command returns a 400 Bad Request response when no time_tracker parameter is present in the request.

• This command returns a 404 Not Found response when given an invalid time_tracker_id.

• This command returns a 422 Unprocessable Entity response when given an invalid started_at or ended_at date (e.g. ended_at is in the past).

Deleting time trackers

Example code:

KT.call('DELETE', 'time_trackers/' + TIME_TRACKER_ID).then(() => {
  console.log('Time tracker has been deleted.');
});

curl 'https://YOUR_DOMAIN.kanbantool.com/api/v3/time_trackers/:time_tracker_id.json' \
  -X 'DELETE' \
  -H 'Authorization: Bearer ...'

Example response:

{
  "time_tracker": {
    "id": 700000,
    "user_id": 100000,
    "board_id": 200000,
    "task_id": 300000,
    "position": null,
    "listed": true,
    "seconds_from_resumed_sprint": 0,
    "started_at": "2018-01-01T12:00:00.000+01:00",
    "ended_at": "2018-01-01T12:00:00.000+01:00",
    "highlighted_at": null,
    "enlist_at": null,
    "created_at": "2018-01-01T12:00:00.000+01:00",
    "updated_at": "2018-01-01T12:00:00.000+01:00"
  }
}

This commands deletes a time tracker.

Request

DELETE /api/v3/time_trackers/:time_tracker_id.json

Response

This command returns a time tracker object.

Errors

• This command returns a 404 Not Found response when given an invalid time_tracker_id.

Types Reference

Our API utilizes following types:

Type	Description	Example
boolean	true or false	true
date	date in Y-m-d format	2018-02-20
dateTime	date in c format	2018-02-20T09:18:15.000+01:0
float	a floating-point number with . used as the separator	123.45
integer	a 32-bit signed integer	12345678
string	an UTF-8 string of variadic length	Hello World!

Objects Reference

Field availability

For optimization purposes, some commands return only a brief of object's data.

For example: when requesting /api/v3/users/current.json, you'll receive list of all the boards user has access to, but it will not contain the board's tasks (since that'd yield a pretty huge object).

To annotate this fact, we've created an Available in column in the objects references' tables, which denotes which fields are available in which commands.

Board (object)

Note: If you look for a human-friendly definition of board, you should go to the board's definition.

Abbreviations used in the Available in column:
F = fetching
D = fetching details

This object defines a single board; it contains both the board's basic data (like its name & position) and its relationships (like tasks or changelogs).

Field	Type	Available in	Description
id	integer	F, D	Board's unique identifier.
version	integer	F, D	Board's version. Counted from 1.
external_id_sequence	?integer	F, D	Board's custom id, optional. Can be used to keep track of the board when synchronizing with other platforms.
board_template_id	string	F, D	If board's been cloned, this field contains id of that base board. Otherwise, this field contains name of the template used to create this board.
folder_id	?integer	F, D	Board's folder id, if it belongs to any.
owner_id	integer	F, D	Id of the user who owns this board.
position	integer	F, D	Board's position in the list of all the boards. Counted from 1.
name	string	F, D	Board's name.
description	string	F, D	Board's description.
last_activity_on	date	F, D	Date of latest activity on the board.
settings_updated_at	?dateTime	F, D	Date & time when board's settings were updated for the last time - if they have been updated.
created_at	dateTime	F, D	Date & time when board's been created.
updated_at	dateTime	F, D	Date & time when board's been updated for the last time.
deleted_at	?dateTime	F, D	Date & time when board's been deleted - if it's been deleted.
card_template	Board.Settings.CardTemplateField[]	F, D	Data of the card template which belongs to this board. A shortcut for board.settings.card_template.
card_types	CardType[]	F, D	List of all the card types which belong to this board.
swimlanes	Swimlane[]	F, D	List of all the swimlanes which belong to this board.
workflow_stages	WorkflowStage[]	F, D	List of all the workflow stages which belong to this board.
tasks	Task[]	D	List of all the tasks which belong to this board.
settings	Board.Settings	F, D	Data of the board's settings.
stats	Board.Statistic[]	F, D	List of all the board's statistics.
collaborators	Collaborator[]	F, D	List of all the board's collaborators.
changelogs	Changelog[]	D	List of all the changelogs which belong to this board.

Board.Statistic (nested object)

This object defines a single board's statistic.

It is a read-only, automatically generated object for each of the board's swimlanes and workflow stages.

Field	Type	Description
swimlane_id	integer	Statistic's swimlane's id.
workflow_stage_id	integer	Statistic's workflow stage's id.
visible_tasks	integer	Number of visible tasks in above swimlane & workflow stage's pair.
archived_tasks	integer	Number of archived tasks in above swimlane & workflow stage's pair.

Board.Settings (nested object)

This object defines settings for a single board - it is a part of the board object, but has been created a section of it's own because of its complexity.

The board settings define:

• board's card template, which is a template for all the board's tasks,
• board's power-ups' settings (e.g. if you've enabled the Checklist templates power-up, its configuration will be present here).

Field	Type	Description
card_template	Board.Settings.CardTemplateField[]	Defines settings of the board's tasks' card template.
powerups	Board.Settings.PowerUp[]	Defines settings of the board's power-ups.

Board.Settings.CardTemplateField (nested object)

This object can be thought of as a schema for each task. It describes a single field present in each of the board's tasks - defines whether that field it's required, what's its default value and so on.

By the default, this object contains following properties, but - depending on the specific field - there can be more of them:

Property	Type	Description
enabled	boolean	If equal to true, field is enabled.
position	integer	Position of the field in the board's settings. Counted from 1.

Additional properties for the external_id field

The external_id field contains these additional properties:

Property	Type	Description
show_on_card	boolean	If equal to true, the external id is visible on the task's card.
editable	boolean	If equal to true, the external id can be modified by users (from the interface). If equal to false, it can be modified only be the API.
auto_generate	boolean	If equal to true, the external id field is generated automatically (in an auto increment fashion). If equal to false, you must fill the external id's value manually when creating a task.
sequential	boolean	If equal to true, the external id field is forced to be a unique, sequential value throughout all the boards. If equal to false, this field is not validated and it's uniqueness is not enforced in any way.

Additional properties for the size_estimate field

The size_estimate field contains these additional properties:

Property	Type	Description
show_on_card	boolean	If equal to true, the size estimate field is visible on the task's card.
default	string	Defines the default value for the size estimate field.
values	string	Describes all the possible size estimates. It's for user information only - it's not parsed anywhere in the system.

Additional properties for the custom_field_N fields

The custom_field_N fields (custom_field_1, custom_field_2 and so on) contain these additional properties:

Property	Type	Description
label	string	Custom field's label (e.g. Difficulty points).
type	string	Custom field's type, one of: text, link, number, select, date, user.
width	string	Custom field's percentage width when rendering; one of: 25, 50, 75, 100.
options	string	When this field represents a custom dropdown (select type), this field contains comma-separated list of possible values.
multiple	string	When this field represents a dropdown (select or user type), this field determines whether one can choose many values or only one.
multiline	string	When this field represents a text (text type), this field determines whether one can write multi-line text inside.

Board.Settings.PowerUp (nested object)

This is the base for all the power-ups' settings - each power-up can put any configuration data it requires in this object:

Property	Type	Description
enabled	boolean	If equal to true, power-up is enabled.

Since it's power-up-dependent and highly internal, we're not going to cover those settings - if you need to do anything more than just enabling / disabling power-ups, you're on your own.

Card Type (object)

This object defines the overall look of of task's card type - it determines e.g. the task's background color.

Field	Type	Description
id	integer	Card type's unique identifier.
board_id	integer	Id of the board to which this card type belongs to.
name	string	Card type's label; unique to the board.
color_ref	string	Card type's color. See table below for reference.
is_default	boolean	If equal to true, all future tasks created at given board will be set this card type by the default
is_disabled	boolean	If equal to true, card type is marked as disabled.
position	integer	Position of the card type in the board's card type list. Counted from 1.
color_attrs	CardType.ColorAttrs	Object describing card type's color.

CardType.color_ref (field)

color_ref	CSS equivalent	Preview
turquoise	#00BCD4
light_blue	#03A9F4
blue	#2196F3
navy	#3F51B5
violet	#673AB7
fuchsia	#9C27B0
pink	#E91E63
strong_red	#D83535
red	#f44336
carrot	#FF5722
orange	#FF9800
sand	#FFC107
yellow	#FFEB3B
lemon	#CDDC39
green_light	#8BC34A
green	#4CAF50
green_dark	#388E3C
brown	#795548
black	#262626
gray_dark	#595959
gray_medium	#9E9E9E
white	#E8E8E8

CardType.ColorAttrs (nested object)

Field	Type	Description
rgb	string	A hex value representing the color, prepended with a hash (e.g. #123456).
position	integer	Position of the color on the colors' list. Counted from 1.
default	boolean	If equal to true, color is marked as the default one. By the default the yellow color is marked as such.

Changelog (object)

This object defines a single change made on a given object (a task or a subtask).

Field	Type	Description
id	integer	Changelog's unique identifier.
board_id	integer	Id of the board on which change has been made.
board_version	integer	Version of the board at the time of the change.
swimlane_id	integer	Id of the swimlane to which this changelog refers to.
workflow_stage_id	integer	Id of the workflow stage to which this changelog refers to.
user_id	integer	Id of the user who made this change.
changed_object_type	?string	Changed object's type (e.g. Task). May not be present when context is obvious (e.g. when fetching just the task's changelogs).
changed_object_id	integer	Changed object's identifier (e.g. modified task's identifier).
changed_object_version	integer	Changed object's version at the time of the change.
what	string	Change's type (e.g. created). See table below for reference.
description	string	Change's description (e.g. XX added task 'yy' to the board).
data	?object	Additional data about the deleted object, optional. See table below for reference.
created_at	dateTime	Date & time when this change was created.

Changelog.what (field)

This field determines type of change that has been made. It contains one of these values:

- deleted

Meaning: task changed_object_id has been deleted.

Value of the data field: none.

- comment_deleted

Meaning: comment changed_object_id has been deleted.

Value of the data field:

Field	Type	Description
comment_id	integer	Id of the deleted comment.
comment_content	string	Contents of that comment.
task_id	integer	Id of the task to which the comment belongs to.
task_external_id	string	External id of that task.
task_name	string	Name of that task.
swimlane_id	integer	Same as changelog.swimlane_id.
swimlane_name	string	Name of that swimlane.
workflow_stage_id	integer	Same as changelog.workflow_stage_id.
workflow_stage_name	string	Name of that workflow stage.
user_id	integer	Same as changelog.user_id.
user_initials	string	Initials of that user.

- subtask_checked, subtask_unchecked

Meaning: subtask changed_object_id has been checked or unchecked.

Value of the data field:

Field	Type	Description
subtask_id	integer	Id of the (un)checked subtask.
subtask_name	string	Name of that subtask.
task_id	integer	Id of the task to which the subtask belongs to.
task_external_id	string	External id of that task.
task_name	string	Name of that task.
swimlane_id	integer	Same as changelog.swimlane_id.
swimlane_name	string	Name of that swimlane.
workflow_stage_id	integer	Same as changelog.workflow_stage_id.
workflow_stage_name	string	Name of that workflow stage.
user_id	integer	Same as changelog.user_id.
user_initials	string	Initials of that user.

Collaborator (object)

This object contains data of user who modified another object.

You can receive this object as a part of a board or task.

Field	Type	Description
id	integer	User's id.
name	string	User's full name (e.g. Foo Bar).
initials	string	User's initials (e.g. FB).
active	boolean	If equal to true, user's account is still active.

Comment (object)

This object defines a single comment.

By the design, all comments can be only bound to tasks.

Field	Type	Description
id	integer	Comment's unique identifier.
user_id	integer	Id of the user who created this comment.
commentable_version	integer	Version of the object, to which comment is bound, at the time of creating the comment. If the comment's bound to a task for example, this field contains that task's version. Counted from 1.
content	string	Comment's message. Markdown formatting is supported.
recipients	?string[]	Comment's recipients, if any - e.g.: ['Foo Bar <123>', 'Asdf Asdf <312>'].
created_at	dateTime	Date & time when comment was created.
updated_at	dateTime	Date & time when comment was updated for the last time.
deleted_at	?dateTime	Date & time when comment was deleted - if it's been deleted.
attachments	Comment.Attachment[]	Comment's attachments.

Comment.Attachment (nested object)

Field	Type	Description
id	integer	Attachment's unique identifier.
name	string	Attachment's file name (e.g. final-diagram-final-final-2018.png).
content_type	string	Attachment's MIME type (e.g. image/jpeg).
size	integer	Attachment's size, in bytes (e.g. 123321).
url	string	Attachment's URL, relative to the account's domain (e.g. /system/attachments/sn9837gvn592/dskj123409fg.jpg).
created_at	dateTime	Date & time when attachment was created.
updated_at	dateTime	Date & time when attachment was updated for the last time.

Subtask (object)

Note: If you look for a human-friendly definition of subtask, you should go to the task's definition.

This object defines a single subtask.

Field	Type	Description
id	integer	Subtask's unique identifier.
task_id	integer	Id of the task to which this subtask belongs to.
task_version	integer	Version of that task.
created_by_id	integer	Id of user who created this subtask.
assigned_user_id	?integer	Id of user to whom the subtask has been assigned.
position	integer	Subtask's position on the task's subtasks list. Counted from 1.
name	string	Subtask's name.
is_completed	boolean	If equal to true, subtask has been marked as completed.
created_at	dateTime	Date & time when subtask was created.
updated_at	dateTime	Date & time when subtask was updated for the last time.
deleted_at	?dateTime	Date & time when subtask was deleted - if it's been deleted.

Task (object)

Note: If you look for a human-friendly definition of task, you should go to the task's definition.

Abbreviations used in the Available in column:
L = listing
F = fetching
D = fetching details

This object defines a single task; it contains both the basic task's data (like its name & priority) and its relationships (like subtasks or changelogs).

Field	Type	Available in	Description
id	integer	L, F, D	Task's unique identifier.
version	integer	L, F, D	Task's version. It's automatically incrementing counter, counted from 1.
external_id	?integer	L, F, D	Task's custom identifier; optional. Can be used to keep track of the task when synchronizing with other platforms.
external_link	?string	L, F, D	Task's custom URL; optional. Functions as above.
board_id	integer	L, F, D	Id of the board to which this task belongs to.
board_version	integer	L, F, D	Version of the board when this task was created.
swimlane_id	integer	L, F, D	Id of the swimlane this task belongs to.
workflow_stage_id	integer	L, F, D	Id of the workflow stage this task belongs to.
card_type_id	integer	L, F, D	Id of the card type this task belongs to.
card_color	string	L, F, D	Task's card's background color name (e.g. yellow).
card_color_in_rgb	string	L, F, D	Task's card's background color value (e.g. #ffeB3b).
card_color_invert	boolean	L, F, D	If equal to true, task's card's foreground (text) color should be white (instead of the default black one), for it to be readable.
created_by_id	integer	L, F, D	Id of the user who created this task.
assigned_user_id	?integer	L, F, D	Id of user to which this task has been assigned; optional.
position	integer	L, F, D	Position of the task in the swimlane & board window. See board definition.
name	string	L, F, D	Task's name.
description	?string	L, F, D	Task's description; optional. HTML tags are supported.
priority	integer	L, F, D	Task's priority; one of: -1 (low), 0 (normal) or 1 (high).
tags	string	L, F, D	Comma-separated list of tags associated with task, e.g. bug,chrome,something-else.
search_tags	string[]	L, F, D	Read-only list of tags / keywords related to this task, e.g. ['Some Task', 'yellow']. It's generated automatically basing on the task's contents.
time_estimate	?integer	L, F, D	Task's time estimate, measured in number of seconds; optional.
size_estimate	string	L, F, D	Task's difficulty as measured by a number; optional. Typically: 0.1 = relatively easy, 1.0 = moderately difficult, 5.0 = 5 times harder than an average task.
size_estimate_description	string	L, F, D	Read-only description of the task's difficulty, e.g.: small and relatively easy.
due_date	?date	L, F, D	Date to which the task is due; optional.
postponed_until	?date	L, F, D	Date to which the task has been postponed; optional.
created_at	dateTime	L, F, D	Date & time when task was created.
updated_at	dateTime	L, F, D	Date & time when task was updated for the last time.
archived_at	?dateTime	L, F, D	Date & time when task was archived - if it's been archived.
deleted_at	?dateTime	L, F, D	Date & time when task was deleted - if it's been deleted.
comments	Comment[]	F, D	List of all the task's comments.
comments_count	integer	L, F, D	Number of the task's comments.
timers_total	?integer	L, F, D	Total number of seconds logged from the finished timers. Equal to null if no time has been logged yet.
timers_total_updated_at	?dateTime	L, F, D	Date & time when any of the task's timers was updated for the last time. Equal to null if no timer-related changes have been ever made.
timers_active_count	integer	L, F, D	Number of currently active (running) timers.
timers_listed_count	integer	L, F, D	Total number of timers associated with this task (but not necessarily running right now).
subtasks	Subtask[]	L, F, D	List of all the task's subtasks (checklist points).
subtasks_count	integer	L, F, D	Number of all the subtasks.
subtasks_completed_count	integer	L, F, D	Number of all the completed subtasks.
attachments	Attachment[]	F, D	List of all the task's attachments.
attachments_count	integer	L, F, D	Number of all the task's attachments.
time_trackers	TimeTracker[]	F, D	List of all the task's time trackers.
collaborators	Collaborator[]	F, D	List of all the task's collaborators.
changelogs	Changelog[]	F, D	List of all the task's changelogs.
block_reason	?string	L, F, D	If the Card block power-up is active, this field describes reason for blocking this task. Equal to null if task has not been blocked.
recurring_schedule	?Task.RecurringSchedule	L, F, D	If the Recurring tasks power-up is active, this field describes the recurring schedule data related to this task.
custom_field_N	?string	L, F, D	Task's custom fields; can contain arbitrary data related to e.g. synchronizing the tasks.

Task.RecurringSchedule (nested object)

This section describes recurring schedule for a task when the Recurring tasks power-up is active.

task.recurring_schedule contains a string in form: [dateTime] + [JSON object], where:

• dateTime describes the nearest date when task will be re-created,
• JSON object describes the schedule itself.

Example recurring_schedule value:

2018-03-06T05:00Z{"type":"d","h":"6","m":"0","multi":"1","start":"2018-03-06","tz":"Warsaw","ts":1520249122}

Daily recurring schedule

Example: daily, on 12:30, every 3 days starting from 2018-01-01.

Object:

type  = d
h     = 12
m     = 30
multi = 3
start = 2018-01-01
tz    = Warsaw

Tasks can be scheduled to be created daily, at given hour and minute.

Field	Type	Description
type	string	Describes the schedule's type. Equal to d when dealing with daily recurring schedule.
h	integer	Hour at which schedule's tasks should be created.
m	integer	Minute at which schedule's tasks should be created.
multi	integer	Tasks will be created every multi day(s) starting from given start date (e.g. value 3 means that schedule will be applied every 3 days).
start	date	Tasks will be created every multi day(s) starting from given start date (e.g. value 2018-01-01 means that schedule will begin to be applied from 2018-01-01).
tz	string	Timezone, e.g.: Warsaw.

Weekly recurring schedule

Example: weekly, on 12:30, at every Monday and Friday.

Object:

type = w
h    = 12
m    = 30
wd_0 = 0
wd_1 = 1
wd_2 = 0
wd_3 = 0
wd_4 = 0
wd_5 = 1
wd_6 = 0
tz   = Warsaw

Tasks can be scheduled to be created weekly, at each given day of week, hour and minute.

Field	Type	Description
type	string	Describes the schedule's type. Equal to w when dealing with weekly recurring schedule.
h	integer	Hour at which schedule's tasks should be created.
m	integer	Minute at which schedule's tasks should be created.
wd_0	integer	If equal to 1, schedule is enabled for Sundays - equal to 0 otherwise.
wd_1	integer	If equal to 1, schedule is enabled for Mondays - equal to 0 otherwise.
wd_2	integer	If equal to 1, schedule is enabled for Tuesdays - equal to 0 otherwise.
wd_3	integer	If equal to 1, schedule is enabled for Wednesdays - equal to 0 otherwise.
wd_4	integer	If equal to 1, schedule is enabled for Thursdays - equal to 0 otherwise.
wd_5	integer	If equal to 1, schedule is enabled for Fridays - equal to 0 otherwise.
wd_6	integer	If equal to 1, schedule is enabled for Saturdays - equal to 0 otherwise.
tz	string	Timezone, e.g.: Warsaw.

Monthly recurring schedule

Example: monthly, on 12:30, at every first, fifth and tenth day of each month.

Object:

type = m
h    = 12
m    = 30
days = 1,5,10
tz   = Warsaw

Tasks can be scheduled to be created monthly, at each given day of month, hour and minute.

Field	Type	Description
type	string	Describes the schedule's type. Equal to m when dealing with monthly recurring schedule.
h	integer	Hour at which schedule's tasks should be created.
m	integer	Minute at which schedule's tasks should be created.
days	string	Comma-separated days at which tasks should be created. E.g. 1,5,10 for first, fifth and tenth day of each month.
tz	string	Timezone, e.g.: Warsaw.

Custom recurring schedule

Example: custom, on 12:30, at 2018-01-01, 2018-02-03, 2018-09-12.

Object:

type = c
h    = 12
m    = 30
days = 2018-01-01,2018-02-03,2018-09-12
tz   = Warsaw

Field	Type	Description
type	string	Describes the schedule's type. Equal to c when dealing with custom recurring schedule.
h	integer	Hour at which schedule's tasks should be created.
m	integer	Minute at which schedule's tasks should be created.
dates	string	Comma-separated dates at which tasks should be created. E.g. 2018-01-01,2018-02-03,2018-09-12 etc.
tz	string	Timezone, e.g.: Warsaw.

User (object)

This object defines a single user.

Field	Type	Description
id	integer	User's unique identifier.
version	integer	User's version. Counted from 1.
name	string	User's full name (e.g. Jon Snow).
initials	string	User's initials (e.g. JS).
timezone	string	User's timezone. See here for reference.
locale	string	User's locale. It's a simple, two-letter representation of the language, e.g. en or pl.
is_project_manager	boolean	If equal to true, user is a project manager.
is_account_admin	boolean	If equal to true, user is an administrator of that account.
is_account_owner	boolean	If equal to true, user is an owner of the account to which it's linked.
is_suspended	boolean	If equal to true, user is suspended.
last_login_at	dateTime	Date & time when user's logged in for the last time.
last_activity_on	date	Date of user's latest activity.
created_at	dateTime	Date & time when user's been created.
updated_at	dateTime	Date & time when user's been modified for the last time.
account	Account	Account to which user's bound.
boards	Board[]	List of user's boards.
time_trackers	TimeTracker[]	List of user's time trackers.

Roles / permissions

Users can be assigned permissions, namely:

Project manager

Project managers can create new boards, share them and invite others. They can only manage the boards they have created and cannot see or access other boards, unless they have been shared with them. They can invite new users, but cannot access the People tab to modify their details.

Account administrator

Administrators can create, access and manage all dashboard items within given account. They cannot access the Account settings tab.

Account owner

Account owners can do everything with and within their account. This includes: viewing billing details, invoices and terminating the account.

Workflow Stage (object)

Note: If you look for a human-friendly definition of workflow stage, you should go to the workflow stage's definition.

This object defines a workflow stage.

Workflow stage can be fetched as a part of a board object.

Field	Type	Description
id	integer	Workflow stage's unique identifier.
board_id	integer	Id of the board to which this workflow stage belongs to.
board_version	integer	Version of the board at the time of workflow stage's creation.
parent_id	?integer	Id of the workflow stage's parent - used to construct a hierarchy of workflow stages.
lft	integer	Used to construct a hierarchy of workflow stages (https://www.sitepoint.com/hierarchical-data-database-2).
rgt	integer	Used to construct a hierarchy of workflow stages (https://www.sitepoint.com/hierarchical-data-database-2).
position	integer	Position of the workflow stage on the board.
name	string	Workflow stage's name (To do, In progress etc.).
description	?string	Workflow stage's description, optional.
wip_limit	?integer	Maximum number of the WIP indicator value which can be put in this workflow stage. Equal to null if no limit should be imposed.
wip_limit_type	?string	Type of indicator for the WIP limit. See below for reference..
lane_type_id	?integer	Type of workflow stage's line. One of: 1 (Backlog / Inventory), 2 (Queue / Waiting), 3 (In Progress), 4 (Done) or null.
lane_type	?string	(read-only) If lane_type_id is set, this field contains a string representation of the lane_type_id value. One of: backlog_inventory, waiting, in_progress, done or null.
lane_width	integer	Number of cards per each row of the lane (e.g. value of 2 means that when rendering this workflow stage, two cards should be placed next to each other, the next two should be in a new row etc.).
archive_enabled	boolean	If equal to true, tasks being in this stage can be archived. Usually set to true for final stages (like Done).

WorkflowStage.wip_limit_type (field)

The wip_limit_type accepts null or one of these values:

wip_limit_type	Description
tasks_count	Number of tasks bound to this workflow stage.
tasks_size	Sum of tasks' difficulty points.
time_estimate	Sum of tasks' estimated hours.
assignments	Number of tasks per user.

Definitions

Since some concepts used when talking about kanban boards are not necessarily obvious, we've prepared a few descriptions accompanied with screenshots to help you understand our tool better.

Board (definition)

Note: If you look for a programmer-friendly definition of board, you should go to the board's object reference.

Board is a fundamental piece of the Kanban Tool - this is where all the magic happens.

Board consists of:

• workflow stages, which group tasks horizontally into statuses,
• swimlanes, which group tasks vertically into e.g. teams,
• tasks.

An example board can look like:

You can see here:

• 7 workflow stages: To do, Scheduled (Soon, Tomorrow, Today), In progress and Done,
• 2 swimlanes (Team A, Team B),
• 8 tasks.

Swimlane (definition)

Note: If you look for a programmer-friendly definition of swimlane, you should go to the swimlane's object reference.

Swimlanes are used to group tasks vertically - for example to easily distribute work against many teams:

Each board has its own set of swimlanes, which can be altered in any way you like.

Task (definition)

Note: If you look for a programmer-friendly definition of task, you should go to the task's object reference.

Task is a note, which belongs to a certain board, swimlane and a workflow stage.

Task is also defined by its:

• title,
• description,
• attachments,
• card type,
• priority,
• due date,
• assigned user.

Additionally, each task can contain from zero to a lots of subtasks - the task presented above has 4 of them.

Workflow Stage (definition)

Note: If you look for a programmer-friendly definition of workflow stage, you should go to the workflow stage's object reference.

Workflow stage determines the status of your task - it can be In progress, Done and so on:

Each board has its own set of workflow stages, which can be altered in any way you like.

Moreover - workflow stages can be 'stacked' on top of each other, creating a hierarchy: