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 cURL

An example using cURL:

$ curl 'https://YOUR_DOMAIN.kanbantool.com/api/v1/boards.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 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/v1/some_action.json

POST /api/v1/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/v1/some_action.json?_m=delete

Responses

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

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

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

GET /api/v1/some_action.xml?parameter=value

Authentication

$ curl 'https://YOUR_DOMAIN.kanbantool.com/api/v1/boards.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 Boards

Listing accessible boards

Example code:

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

Example response:

[
  {
    "board": {
      "id": 123123,
      "owner_id": 234234,
      "account_id": 345345,
      "folder_id": null,      
      "position": null,
      "version": 5,

      "name": "Hello",
      "description": "Hello World!",

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

      "last_activity_on": "2018-01-01",
      "settings_updated_at": "2018-01-01T12:00:00.000+01:00",

      /* ... */
    }
  },

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

  /* ... */
]

This command returns a list of all the boards accessible by currently authenticated user.

Request

GET /api/v1/boards.json

Response

This command returns a list of board objects.

Errors

This command usually does not fail.

Fetching boards' details

Example code:

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

Example response:

{
  "board": {
    "id": 100000,
    "owner_id": 100000,
    "account_id": 100000,
    "folder_id": null,      
    "position": null,
    "version": 5,

    "name": "Hello",
    "description": "Hello World!",

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

    "last_activity_on": "2018-01-01",
    "settings_updated_at": "2018-01-01T12:00:00.000+01:00",

    /* ... */

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

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

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

This command returns detailed information about given board.

Request

GET /api/v1/board/: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' users & permissions

Example code:

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

Example response:

[
  {
    "shared_item_user": {
      "id": 123123,
      "user_id": 234234,

      "can_create_tasks": true,
      "can_read_tasks": true,
      "can_update_tasks": true,
      "can_delete_tasks": true,
      "can_move_tasks": true,

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

      "user": {
        "id": 234234,
        "name": "Foo Bar",
        "initials": "FB",
        "is_suspended": false
      }
    }
  },

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

  /* ... */
]

This command returns a list of all the board's permissions related to given board.

Request

GET /api/v1/boards/:board_id/users.json

Response

This command returns a list of board's permission objects.

Errors

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

Listing boards' changelogs

Example code:

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

Example response:

[
  {
    "changelog": {
      "id": 123123,
      "board_id": 234234,
      "board_version": 5,
      "user_id": 345345,
      "swimlane_id": 456456,
      "workflow_stage_id": 567567,

      "changed_object_type": "Task",
      "changed_object_id": 678678,
      "changed_object_version": 2,

      "what": "created",
      "description": "FB added task 'Foo' to the board",

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

      /* ... */
  },

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

  /* ... */
]

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

Request

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

Parameters

Parameter	Type	Required	Description
from	dateTime	No	When present, returns only changelogs matching created_at >= :from.
to	dateTime	No	When present, returns only changelogs matching created_at <= :to.
user_id	integer	No	When present, returns only changelogs with matching user_id.
before	integer	No	When present, returns only changelogs matching id < :before.
after	integer	No	When present, returns only changelogs matching id > :after.
offset	integer	No	Used to paginate the results.
limit	integer	No	Used to paginate the results.

Response

This command returns a list of changelog objects.

Errors

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

• This command returns a 404 Not Found response when passed before parameter is not a valid changelog's id.

• This command returns a 500 Internal Server Error response when passed offset or limit parameter is not valid (e.g. equal to -123).

Working with Tasks

Listing tasks

Example code:

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

Example response:

[
  {
    "id": 123123,
    "board_id": 234234,
    "swimlane_id": 345345,
    "workflow_stage_id": 456456,
    "card_type_id": 567567,

    /* ... */

    "position": 6,
    "name": "foo bar zar api mar!",
    "description": null,
    "priority": 0,

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

    /* ... */
  },

  {
    "id": 789789,

    /* ... */
  },

  /* ... */
]

This command returns a list of tasks from given board.

By the default, only non-archived tasks are returned - this behavior can be changed using the archived parameter.

Request

GET /api/v1/boards/:board_id/tasks.json

Parameters

Parameter	Type	Required	Description
archived	integer	No	When equal to 1, returns only archived tasks.
swimlane_id	integer	No	When present, returns only tasks with matching swimlane_id.
workflow_stage_id	integer	No	When present, returns only tasks with matching workflow_stage_id.
page	integer	No	Used to paginate the results - determines page number.
per_page	integer	No	Used to paginate the results - determines number of tasks per page.

Response

This command returns a list of task objects.

Errors

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

Fetching tasks' details

Example code:

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

Example response:

{
  "task": {
    "id": 123123,
    "external_id": null,
    "external_link": null,
    "board_id": 234234,
    "board_version": 30,

    /* ... */

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

    "comments": [
      {
        /* ... */

        "content": "Some comment",

        /* ... */
      },

      /* ... */
    ],

    /* ... */

    "subtasks": [
      {
        /* ... */

        "position": 1,
        "name": "Teach XYZ how to use the Docker",

        /* ... */
      },

      /* ... */
    ],

    /* ... */

    "changelogs": [
      {
        /* ... */

        "what": "created",
        "description": "FB added task 'Teach XYZ how to use the Docker' to the board",
        "created_at": "2018-01-01T12:00:00.000+01:00",

        /* ... */
      },

      /* ... */
    ]
  }
}

This command returns detailed information about given task.

To fetch a task, user must have can_read_tasks permission on the task's board.

Request

GET /api/v1/boards/:board_id/tasks/:task_id.json

Response

This command returns a task object.

Errors

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

Creating tasks

Example code:

curl 'https://YOUR_DOMAIN.kanbantool.com/api/v1/boards/:board_id/tasks.json' \
  -X 'POST' \
  -H 'Authorization: Bearer ...' \
  -d 'task[name]=Hello World!'

Example response:

{
  "task": {
    "id": 123123,
    "board_id": 234234,
    "swimlane_id": 345345,
    "workflow_stage_id": 456456,
    "card_type_id": 567567,

    "position": 7,
    "name": "Hello World!",
    "description": null,
    "priority": 0,

    "created_at": "2018-02-27T09:52:34.000+01:00",
    "updated_at": "2018-02-27T09:52:34.000+01:00",

    /* ... */
  }
}

This command creates a new task on given board.

To create a task, user must have can_create_tasks permission on the task's board.

Request

POST /api/v1/boards/:board_id/tasks.json

Parameters

Parameter	Type	Required	Default value
task[name]	string	Yes	-
task[external_id]	?integer	No	null
task[external_link]	?string	No	null
task[swimlane_id]	integer	No	Swimlane with first position.
task[workflow_stage_id]	integer	No	Workflow stage with first position.
task[card_type_id]	integer	No	Card type marked as the default one.
task[assigned_user_id]	?integer	No	null
task[position]	integer	No	Next available position number (1, 2, 3 and so on)
task[description]	?string	No	null
task[priority]	integer	No	0 (normal priority)
task[due_date]	?date	No	null
task[postponed_until]	?date	No	null
task[size_estimate]	float	No	1.0
task[time_estimate]	?integer	No	null
task[custom_field_N]	?string	No	null

Response

This command returns a task object.

Errors

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

• This command returns a 422 Unprocessable Entity response when given an invalid input (missing task[name] parameter, wrong format of some field and so on).

Updating tasks

Example code:

curl 'https://YOUR_DOMAIN.kanbantool.com/api/v1/boards/:board_id/tasks/:task_id.json' \
  -X 'PUT' \
  -H 'Authorization: Bearer ...' \
  -d 'task[name]=Hello, Modified World!'

Example response:

{
  "task": {
    "id": 123123,
    "board_id": 234234,
    "swimlane_id": 345345,
    "workflow_stage_id": 456456,
    "card_type_id": 567567,

    "position": 7,
    "name": "Hello, Modified World!",
    "description": null,
    "priority": 0,

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

    /* ... */
  }
}

This commands updates a task.

To update a task, user must have can_update_tasks permission on the task's board.

Request

PUT /api/v1/boards/:board_id/tasks/:task_id.json

Parameters

Parameter	Type
task[name]	string
task[external_id]	?integer
task[external_link]	?string
task[card_type_id]	integer
task[assigned_user_id]	?integer
task[description]	?string
task[priority]	integer
task[due_date]	?date
task[postponed_until]	?date
task[size_estimate]	float
task[time_estimate]	?integer
task[custom_field_N]	?string

Response

This command returns a task 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 (missing task[name] parameter, wrong format of some field and so on).

Moving tasks

Example code:

curl 'https://YOUR_DOMAIN.kanbantool.com/api/v1/boards/:board_id/tasks/:task_id/move.json' \
  -X 'PUT' \
  -H 'Authorization: Bearer ...' \
  -d 'direction=up'

Example response:

{
  "task": {
    "id": 123123,
    "task_id": 234234,
    "task_version": 5,
    "created_by_id": 345345,
    "assigned_user_id": null,

    "position": 5,
    "name": "Sing: Java song, Java song...",

    "is_completed": false,

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

This command moves task in given direction or at given place.

To update a task, user must have can_move_tasks permission on the task's board.

Request

PUT /api/v1/boards/:board_id/tasks/:task_id/move.json

Parameters

There are 2 ways to move the task: with using the direction parameter (first table), or with swimlane_id and workflow_stage_id parameters (second table).

Parameter	Type	Required	Description
direction	string	Yes	Direction where the task should be moved. One of: up, down, prev_stage, next_stage, prev_swimlane, next_swimlane.
override	?string	No	Reason for overriding the WIP limit, optional.

or

Parameter	Type	Required	Description
swimlane_id	integer	Yes (either one or both)	Swimlane to which task should be moved in to.
workflow_stage_id	integer	Yes (either one or both)	Workflow stage to which task should be moved in to.
position	integer	No	Position in column where task should be placed, counted from 1. When left unspecified, task is appended onto the end of the column.
override	?string	No	Reason for overriding the WIP limit, optional.

Response

This command returns a task object.

Errors

• This command returns a 400 Bad Request response when given an invalid input (invalid direction parameter value and so on).

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

Archiving and unarchiving tasks

Example code:

curl 'https://YOUR_DOMAIN.kanbantool.com/api/v1/boards/:board_id/tasks/:task_id/archive.json' \
  -X 'PUT' \
  -H 'Authorization: Bearer ...'

Example response:

{
  "task": {
    "id": 123123,
    "task_id": 234234,
    "task_version": 5,
    "created_by_id": 345345,
    "assigned_user_id": null,

    "position": 5,
    "name": "Sing: Java song, Java song...",

    "is_completed": false,

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

This command makes it possible to archive & unarchive (restore) the tasks.

Only tasks being in archivable swimlanes can be archived.

Request

Archiving

PUT /api/v1/boards/:board_id/tasks/:task_id/archive.json

Unarchiving

PUT /api/v1/boards/:board_id/tasks/:task_id/unarchive.json

Response

This command returns a task 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 task cannot be (un)archived (because e.g. it's in an unarchivable workflow stage).

Deleting tasks

Example code:

curl 'https://YOUR_DOMAIN.kanbantool.com/api/v1/boards/:board_id/tasks/:task_id.json' \
  -X 'DELETE' \
  -H 'Authorization: Bearer ...'

Example response:

{
  "task": {
    "id": 123123,
    "board_id": 234234,
    "swimlane_id": 345345,
    "workflow_stage_id": 456456,
    "card_type_id": 567567,

    "position": 7,
    "name": "Hello World!",
    "description": null,
    "priority": 0,

    "created_at": "2018-02-27T09:52:34.000+01:00",
    "updated_at": "2018-02-27T09:52:34.000+01:00",
    "deleted_at": "2018-02-27T12:34:56.000+01:00",

    /* ... */
  }
}

This command deletes a task.

To delete a task, user must have can_delete_tasks permission on the task's board.

Request

DELETE /api/v1/boards/:board_id/tasks/:task_id.json

Response

This command returns a task object.

Errors

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

Working with Subtasks

Listing subtasks

Example code:

curl 'https://YOUR_DOMAIN.kanbantool.com/api/v1/boards/:board_id/tasks/:task_id/subtasks.json' \
  -H 'Authorization: Bearer ...'

Example response:

[
  {
    "subtask": {
      "id": 123123,
      "task_id": 234234,
      "task_version": 5,
      "created_by_id": 345345,
      "assigned_user_id": null,

      "position": 1,
      "name": "Set up the development environment",

      "is_completed": true,

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

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

  /* ... */
]

This command returns a list of subtasks which belong to given task.

Request

GET /api/v1/boards/:board_id/tasks/:task_id/subtasks.json

Response

This command returns a list of subtask objects.

Errors

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

Fetching subtasks' details

Example code:

curl 'https://YOUR_DOMAIN.kanbantool.com/api/v1/boards/:board_id/tasks/:task_id/subtasks/:subtask_id.json' \
  -H 'Authorization: Bearer ...'

Example response:

{
  "subtask": {
    "id": 123123,
    "task_id": 234234,
    "task_version": 5,
    "created_by_id": 345345,
    "assigned_user_id": null,

    "position": 1,
    "name": "Set up the development environment",

    "is_completed": true,

    "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 detailed information about given subtask.

Request

GET /api/v1/boards/:board_id/tasks/:task_id/subtasks/:subtask_id.json

Response

This command returns a subtask object.

Errors

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

Creating subtasks

Example code:

curl 'https://YOUR_DOMAIN.kanbantool.com/api/v1/boards/:board_id/tasks/:task_id/subtasks.json' \
  -X 'POST' \
  -H 'Authorization: Bearer ...' \
  -d 'subtask[name]=Hello World!'

Example response:

{
  "subtask": {
    "id": 123123,
    "task_id": 234234,
    "task_version": 5,
    "created_by_id": 345345,
    "assigned_user_id": null,

    "position": 1,
    "name": "Hello World!",

    "is_completed": true,

    "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 in given task.

Request

POST /api/v1/boards/:board_id/tasks/:task_id/subtasks.json

Parameters

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

Response

This command returns a subtask object.

Errors

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

• 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 (missing subtask[name] parameter, wrong format of some field and so on).

Updating subtasks

Example code:

curl 'https://YOUR_DOMAIN.kanbantool.com/api/v1/boards/:board_id/tasks/:task_id/subtasks/:subtask_id.json' \
  -X 'PUT' \
  -H 'Authorization: Bearer ...' \
  -d 'subtask[name]=It is my new name!'

Example response:

{
  "subtask": {
    "id": 123123,
    "task_id": 234234,
    "task_version": 5,
    "created_by_id": 345345,
    "assigned_user_id": null,

    "position": 1,
    "name": "It is my new name!",

    "is_completed": true,

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

This commands updates a subtask.

Request

PUT /api/v1/boards/:board_id/tasks/:task_id/subtasks/:subtask_id.json

Parameters

Parameter	Type
subtask[name]	string
subtask[is_completed]	boolean
subtask[assigned_user_id]	?integer

Response

This command returns a subtask object.

Errors

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

• This command returns a 422 Unprocessable Entity response when given an invalid input (subtask[name] parameter having invalid format and so on).

Reordering subtasks

Example code:

curl 'https://YOUR_DOMAIN.kanbantool.com/api/v1/boards/:board_id/tasks/:task_id/subtasks/reorder.json' \
  -X 'PUT' \
  -H 'Authorization: Bearer ...' \
  -d 'order=123,72,333,666'

Example response:

[
  {
    "subtask": {
      "id": 123123,
      "task_id": 234234,
      "task_version": 5,
      "created_by_id": 345345,
      "assigned_user_id": null,

      "position": 1,
      "name": "Set up the development environment",

      "is_completed": true,

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

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

  /* ... */
]

This commands reorders (changes positions) of all the task's subtasks.

Request

PUT /api/v1/boards/:board_id/tasks/:task_id/subtasks/reorder.json

Parameters

Parameter	Type	Description
order	string	Comma-separated ids of the subtasks in the new order. All subtasks must be specified.

Response

This command returns a list of subtask objects.

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 not enough subtask ids (as described in the parameter's description).

Deleting subtasks

Example code:

curl 'https://YOUR_DOMAIN.kanbantool.com/api/v1/boards/:board_id/tasks/:task_id/subtasks/:subtask_id.json' \
  -X 'DELETE' \
  -H 'Authorization: Bearer ...'

Example response:

{
  "subtask": {
    "id": 123123,
    "task_id": 234234,
    "task_version": 5,
    "created_by_id": 345345,
    "assigned_user_id": null,

    "position": 1,
    "name": "Set up the development environment",

    "is_completed": true,

    "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 subtask.

Request

DELETE /api/v1/boards/:board_id/tasks/:task_id/subtasks/:subtask_id.json

Response

This command returns a subtask object.

Errors

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

Working with Comments

Listing comments

Example code:

curl 'https://YOUR_DOMAIN.kanbantool.com/api/v1/boards/:board_id/tasks/:task_id/comments.json' \
  -H 'Authorization: Bearer ...'

Example response:

[
  {
    "comment": {
      "id": 123123,
      "user_id": 234234,
      "commentable_version": 35,
      "content": "Hello World!",

      "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": [
        /* ... */
      ]
    }
  },

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

  /* ... */
]

This command returns a list of comments from task.

Request

GET /api/v1/boards/:board_id/tasks/:task_id/comments.json

Response

This command returns a list of comment objects.

Errors

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

Fetching comments' details

Example code:

curl 'https://YOUR_DOMAIN.kanbantool.com/api/v1/boards/:board_id/tasks/:task_id/comments/:comment_id.json' \
  -H 'Authorization: Bearer ...'

Example response:

{
  "comment": {
    "id": 123123,
    "user_id": 234234,
    "commentable_version": 35,
    "content": "Hello World!",

    "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 returns detailed information about given comment.

Request

GET /api/v1/boards/:board_id/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 board_id, task_id or comment_id.

Creating comments

Example code:

curl 'https://YOUR_DOMAIN.kanbantool.com/api/v1/boards/:board_id/tasks/:task_id/comments.json' \
  -X 'POST' \
  -H 'Authorization: Bearer ...' \
  -d 'comment[content]=Hello World!'

Example response:

{
  "comment": {
    "id": 123123,
    "user_id": 234234,
    "commentable_version": 41,

    "content": "Hello World!",

    "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 bound to given task.

Request

POST /api/v1/boards/:board_id/tasks/:task_id/comments.json

Parameters

Parameter	Type	Required	Default value
comment[content]	string	Yes	-

Response

This command returns a comment object.

Errors

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

• 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 (missing or empty comment[content] parameter).

Deleting comments

Example code:

curl 'https://YOUR_DOMAIN.kanbantool.com/api/v1/boards/:board_id/tasks/:task_id/comments/COMMENT_ID.json' \
  -X 'DELETE' \
  -H 'Authorization: Bearer ...'

Example response:

{
  "comment": {
    "id": 123123,
    "user_id": 234234,
    "commentable_version": 41,

    "content": "Hello World!",

    "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",

    "recipients": null,

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

This command allows to remove the most recent comment from given task.

Request

DELETE /api/v1/boards/:board_id/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 board_id, task_id or comment_id.

• This command returns a 422 Unprocessable Entity response when given comment is not the latest comment in the given task.

Working with Time Trackers

Listing time trackers for current user

Example code:

curl 'https://YOUR_DOMAIN.kanbantool.com/api/v1/time_trackers.json' \
  -H 'Authorization: Bearer ...'

Example response:

[
  {
    "time_tracker": {
      "id": 123123,
      "user_id": 234234,
      "board_id": 345345,
      "task_id": 456456,
      "sprint_id": 567567,
      "position": 2,
      "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"
    }
  },

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

  /* ... */
]

This command returns a list of time trackers related to currently authenticated user.

Request

GET /api/v1/time_trackers.json

Parameters

Parameter	Type	Required	Description
task_id	integer	No	When present, returns only time trackers with matching task_id.
active	integer	No	When equal to 1, returns only the running trackers. When equal to 0, returns only the finished ones.
listed	integer	No	When equal to 1, returns only the trackers listed in the My work section.
expand	integer	No	When equal to 1, each tracker is enriched with additional data about associated objects (task).

Response

This command returns a list of time tracker objects.

Errors

This command usually does not fail.

Creating time trackers

Example code:

curl 'https://YOUR_DOMAIN.kanbantool.com/api/v1/time_trackers.json' \
  -X 'POST' \
  -H 'Authorization: Bearer ...' \
  -d 'time_tracker[board_id]=123123' \
  -d 'time_tracker[task_id]=234234'

Example response:

{
  "time_tracker": {
    "id": 123123,
    "user_id": 234234,
    "board_id": 345345,
    "task_id": 456456,
    "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/v1/time_trackers.json

Parameters

Parameter	Type	Required	Default value
time_tracker[board_id]	`integer	Yes	-
time_tracker[task_id]	`integer	Yes	-
time_tracker[position]	`?integer	No	1
time_tracker[listed]	`boolean	No	true
time_tracker[started_at]	`dateTime	No	current date and time
time_tracker[ended_at]	`?dateTime	No	null
time_tracker[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).

• This command returns a 500 Internal Server Error response when no time_tracker parameter is present in the request.

Updating time trackers

Example code:

curl 'https://YOUR_DOMAIN.kanbantool.com/api/v1/time_trackers/TIME_TRACKER_ID.json' \
  -X 'PUT' \
  -H 'Authorization: Bearer ...' \
  -d 'time_tracker[started_at]=...' \
  -d 'time_tracker[ended_at]=...'

Example response:

{
  "time_tracker": {
    "id": 123123,
    "user_id": 234234,
    "board_id": 345345,
    "task_id": 456456,
    "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 updates a time tracker.

Request

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

Parameters

Parameter	Type
time_tracker[position]	?integer
time_tracker[listed]	boolean
time_tracker[started_at]	?dateTime
time_tracker[ended_at]	?dateTime
time_tracker[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:

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

Example response:

{
  "time_tracker": {
    "id": 123123,
    "user_id": 234234,
    "board_id": 345345,
    "task_id": 456456,
    "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/v1/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.

Working with Time Reporting

Generating time reports

Example code:

curl 'https://YOUR_DOMAIN.kanbantool.com/api/v1/time_report.json' \
  -X 'POST' \
  -H 'Authorization: Bearer ...' \
  -d 'report_type=summary' \
  -d 'board_id=123123' \
  -d 'from=2018-03-01' \
  -d 'to=2018-03-14' \
  -d 'group_by=board_id'

Example response:

{
  "summary": {
    "123123": [
      {
        "date": "2018-01-01",
        "duration": 12345
      },

      {
        "date": "2018-01-02",
        "duration": 12345
      },

      {
        "date": "2018-01-03",
        "duration": 12345
      },

      /* ... */
    ],

    /* ... */
  }
}

This command returns a summarized or detailed report about one's logged time.

Request

GET /api/v1/time_report.json

Parameters

Parameter	Type	Required	Description
report_type	string	Yes	Type of report to generate - one of: summary, detailed.
board_id	integer	Yes	Id of board for which report should be generated.
from	date	Yes	Date from which report should be generated; inclusive.
to	date	Yes	Date to which report should be generated; inclusive.
group_by	string	Yes	Field by which rows should be grouped when generating a summary report. One of: board_id, task_id, user_id, sprint_id.
include_filter_options	integer	Yes	When equal to 1, an additional filter_options structure is returned, which contains data facilitating filtering the report.
expand	integer	Yes	When equal to 1, JSONed data of the group-by object's data is used to construct array keys. Otherwise, group-by object's id is used.
user_id	integer	No	Imposes a filter on the user.
task_id	integer	No	Imposes a filter on the task.
tasks.card_type_id	integer	No	Imposes a filter on the task's card type.
tasks.tags	string	No	Imposes a filter on the task's tags.

Response for a summary report

When generating a summary report, a list containing instances of following object is returned:

Field	Type	Description
date	date	Date of the time log.
duration	integer	Number of seconds logged on given object (defined by the group_by parameter).

Response for a detailed report

When generating a detailed report, a list of time trackers is returned, with the task field filled.

Filter Options (returned object)

This structure describes all the objects by which report can be filtered:

Field	Type	Description
user_id[].id	integer	User's id.
user_id[].name	string	User's name.
card_type_id[].id	integer	Card type's id.
card_type_id[].name	string	Card type's name.
card_type_id[].group_id	integer	Board's id.
card_type_id[].group_name	string	Board's name.
swimlane_id[].id	integer	Swimlane's id.
swimlane_id[].name	string	Swimlane's name.
swimlane_id[].group_id	integer	Board's id.
swimlane_id[].group_name	string	Board's name.
tags[]	{id: integer, name: string}	All possible tags which can be filtered.

Examples

Generating a summarized report for given board

    GET /api/v1/time_report.json?
        &report_type=summary
        &board_id=123123
        &from=2018-03-01
        &to=2018-03-14
        &group_by=board_id

Generating a summarized report for given board and user, with rows grouped by tasks

    GET /api/v1/time_report.json?
        &report_type=summary
        &board_id=123123
        &user_id=234234
        &from=2018-03-01
        &to=2018-03-14
        &group_by=task_id

Generating a detailed report for given board and task

    GET /api/v1/time_report.json?
        &report_type=detailed
        &board_id=123123
        &task_id=234234
        &from=2018-03-01
        &to=2018-03-14
        &group_by=board_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/v1/boards.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.

Note: XML responses use dashes in place of the underscores.

Field	Type	Available in	Description
id	integer	listing, fetching	Board's unique identifier.
owner_id	integer	listing, fetching	Id of the user who owns this board.
account_id	integer	listing, fetching	Id of the account (subdomain) to which this board belongs. Not used anywhere in the API, so can be safely omitted.
folder_id	?integer	listing, fetching	Id of the folder to which this board belongs, if any.
position	?integer	listing, fetching	Board's position in the list of all the boards; counted from 1.
version	integer	listing, fetching	Board's version; counted from 1.
name	string	listing, fetching	Board's name.
description	string	listing, fetching	Board's description.
created_at	dateTime	listing, fetching	Date & time when board was created.
updated_at	dateTime	listing, fetching	Date & time when board was updated for the last time.
deleted_at	?dateTime	listing, fetching	Date & time when board was deleted - if it's been deleted.
settings_updated_at	?dateTime	listing, fetching	Date & time when board had its settings changed for the last time - if it had.
last_activity_on	date	listing, fetching	Date of latest activity on the board (changing board's settings, updating board's tasks etc.).
swimlanes	Swimlane[]	fetching	A list of all the swimlanes which belong to this board.
workflow_stages	WorkflowStage[]	fetching	A list of all the workflow stages which belong to this board.
card_types	CardType[]	fetching	A list fo all the card types which belong to this board.

Board Permission (object)

Note: XML responses use dashes in place of the underscores.

Field	Type	Description
id	integer	Permission's unique identifier.
user_id	integer	Id of user to whom permission applies to.
user	BoardPermission.User	User to whom permission applies to.
can_create_tasks	boolean	If equal to true, user can create tasks on given board. false otherwise.
can_read_tasks	boolean	If equal to true, user can read tasks present on given board. false otherwise.
can_update_tasks	boolean	If equal to true, user can update tasks on given board. false otherwise.
can_delete_tasks	boolean	If equal to true, user can delete tasks from given board. false otherwise.
can_move_tasks	boolean	If equal to true, user can move tasks in given board. false otherwise.
updated_at	dateTime	Date & time when permission was updated for the last time.

BoardPermission.User (nested object)

Field	Type	Description
id	integer	User's unique identifier.
name	string	User's full name (e.g. Foo Bar).
initials	string	User's initials (e.g. FB).
is_suspended	boolean	If equal to true, user is suspended - false otherwise.

Card Type (object)

Note: XML responses use dashes in place of the underscores.

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)

Note: XML responses use dashes in place of the underscores.

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 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 (contents) of that subtask.
task_id	integer	Id of the task 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.

Comment (object)

Note: XML responses use dashes in place of the underscores.

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.
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.

Note: XML responses use dashes in place of the underscores.

Field	Type	Description
id	integer	Subtask's unique identifier.
task_id	integer	Id of the task this subtask belongs to.
task_version	integer	Version of the task when this subtask was created.
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 list. Counted from 1.
name	string	Subtask's name (description).
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.

Swimlane (object)

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

Note: XML responses use dashes in place of the underscores.

Field	Type	Description
id	integer	Swimlane's unique identifier.
board_id	integer	Id of the board to which this swimlane belongs to.
position	integer	Position of the swimlane in the board's view. Counted from 1.
name	string	Swimlane's name.
description	?string	Swimlane's description; optional.
limit	?integer	Maximum number of tasks which can be put in this swimlane; optional.

Task (object)

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

Note: XML responses use dashes in place of the underscores.

Field	Type	Available in	Description
id	integer	listing, fetching	Task's unique identifier.
external_id	?integer	listing, fetching	Task's custom id; optional. Can be used to keep track of the task when synchronizing with other platforms.
external_link	?string	listing, fetching	Task's custom url; optional. Can be used to keep track of the task when synchronizing with other platforms.
board_id	integer	listing, fetching	Id of the board to which this task belongs to.
board_version	integer	listing, fetching	Version of the board when this task was created at.
swimlane_id	integer	listing, fetching	Id of the swimlane this task belongs to.
workflow_stage_id	integer	listing, fetching	Id of the workflow stage this task belongs to.
card_type_id	integer	listing, fetching	Id of the card type this task belongs to.
created_by_id	integer	listing, fetching	Id of user who created this task.
assigned_user_id	?integer	listing, fetching	Id of user to which this task has been assigned; optional.
assigned_user	?Task.AssignedUser	listing, fetching	Object describing the assigned user; optional.
position	integer	listing, fetching	Position of the task in the card. Counted from 1.
name	string	listing, fetching	Task's name.
description	?string	listing, fetching	Task's description; HTML tags allowed.
priority	integer	listing, fetching	Task's priority. One of: -1 (low), 0 (normal) or 1 (high).
tags	string	listing, fetching	Comma-separated list of tags associated with task.
time_estimate	?integer	listing, fetching	Task's time estimate, measured in number of seconds; optional.
size_estimate	float	listing, fetching	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.
due_date	?date	listing, fetching	Date to which the task is due; optional.
postponed_until	?date	listing, fetching	Date to which the task has been postponed; optional.
created_at	dateTime	listing, fetching	Date & time when task was created.
updated_at	dateTime	listing, fetching	Date & time when task was updated for the last time.
archived_at	?dateTime	listing, fetching	Date & time when task was archived - if it's been archived.
deleted_at	?dateTime	listing, fetching	Date & time when task was deleted - if it's been deleted.
comments	?Comment[]	fetching	List of all the task's comments.
comments_count	integer	listing, fetching	Number of the task's comments.
timers_total	?integer	listing, fetching	Total number of seconds logged from the finished timers. Equal to null if no time has been logged yet.
timers_total_updated_at	?dateTime	listing, fetching	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	listing, fetching	Number of currently active (running) timers.
timers_listed_count	integer	listing, fetching	Total number of timers associated with this task (but not necessarily active right now).
subtasks	?Subtask[]	fetching	List of all the task's subtasks (checklist points).
subtasks_count	integer	listing, fetching	Number of all the subtasks.
subtasks_completed_count	integer	listing, fetching	Number of all the completed subtasks.
attachments_count	integer	listing, fetching	Number of all the task's attachments.
changelogs	?Changelog[]	fetching	List of all the task's changelogs.
block_reason	?string	listing, fetching	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	listing, fetching	If the Recurring tasks power-up is active, this field describes the recurring schedule data related to this task.
custom_field_N	?string	listing, fetching	Task's custom fields; can contain arbitrary data related to e.g. synchronizing the tasks.

Task.AssignedUser (nested object)

Field	Type	Description
name	string	User's full name (e.g. Foo Bar).
initials	string	User's initials (e.g. FB).

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.

Time Tracker (object)

Note: XML responses use dashes in place of the underscores.

Note: For the expanded listing explanation, take a look into the listing's expanded parameter.

Field	Type	Available in	Description
id	integer	listing	Time tracker's unique identifier.
user_id	integer	listing	Id of the user who created this tracker.
board_id	integer	listing	Id of the board this tracker belongs to.
task_id	integer	listing	Id of the task this tracker belongs to.
task	TimeTracker.Task	expanded listing	Data of the task this tracker belongs to.
sprint_id	integer	listing	Id of the sprint to which this tracker is bound.
position	?integer	listing	Position of the tracker in the My work section. Counted from 1.
listed	boolean	listing	Equal to true, if tracker is visible in the list of all the trackers in the side panel of the board.
started_at	dateTime	listing	Date & time when tracker was started.
ended_at	?dateTime	listing	Date & time when tracker was stopped (null for running timers).
highlighted_at	?dateTime	listing	Each tracker is bound to a task - when that task changes, this field is also updated to reflect that time tracker's task need to be seen by the user. In the My work section, such trackers are highlighted - hence the name.
created_at	dateTime	listing	Date & time when tracker was created.
updated_at	dateTime	listing	Date & time when tracker was updated for the last time.

TimeTracker.Task (nested object)

Field	Type	Description
id	integer	Task's unique identifier.
board_id	integer	Id of the board this task belongs to.
card_type_id	integer	Id of the card type this task has.
card_color_in_rgb	string	A hex value representing the color, prepended with a hash (e.g. #123456).
name	string	Task's name.
tags	string	Comma-separated list of tags associated with task.
priority	integer	Task's priority. One of: -1 (low), 0 (normal) or 1 (high).
due_date	?dateTime	Task's due to date, optional.
archived_at	?dateTime	Task's archiving date, optional.

Workflow Stage (object)

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

Note: XML responses use dashes in place of the underscores.

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: