KanbanTool API Documentation

KanbanTool API v1.1 Guide

KanbanTool provides API which makes it easy for developers to integrate external systems
and add their own layer of awesomeness on top of the KanbanTool platform.

This version of API is still under development, but any future changes will be backward compatible.


Your custom code
JSONP REST
API interface
Kanban Tool

What can you do with it?

  • Develop useful plugins and integrations
  • Sync tasks and work with external systems
  • Automate your workflow
  • Customize notification channels
  • Backup data on in-house systems

Ready to get started?

Getting started with the API

1. Generate your API token
To interact with API you will need to generate an unique, personal API token, which will be used to sign each request and authenticate yourself with the API. Without or with invalid API token all your requests would be rejected with HTTP 403 Forbidden status. Please note that API token has similar role as username and password combination, so once you generate it, make sure to keep it safe and share with trusted applications only.

1.1. Click on the "My profile" tab in main navigation:
My profile tab

1.2. Click on "API access" link:
Api access tab

1.3. Press "Enable API access" button to generate API token.
Api access button

1.4. Note down your new API token, you are going to need it soon:
Api access token

Samples & Wrappers

1. Grab API Wrapper
If you are a programmer, one of the first things to do is to check whether there are some ready-made libraries which will help you interact with KanbanTool from your favourite programming language. A list of API bindings for popular languages together with some examples can be found on our GitHub account: http://github.com/kanbantool/api


2. Or try it from your browser
You can also fully interact with the API directly from your browser. No third party-software or complex development environments are needed. To get started, just go to the following URL, first replacing YOUR_ACCOUNT_DOMAIN with your account domain name (i.e. mycompany for mycompany.kanbantool.com account) and YOUR_API_TOKEN with your API token:

 http://YOUR_ACCOUNT_DOMAIN.kanbantool.com/api/v1/boards.xml?api_token=YOUR_API_TOKEN
This will show you a machine friendly listing of boards on your account, similar to the one below:

Api response example for get boards

Let's take this a step further and view tasks for one of the boards. To do this, simply note the number in <id> part for selected board. (for the example above, this would be 11619 for "A test board") Next enter following address in your browser:
 http://YOUR_ACCOUNT_DOMAIN.kanbantool.com/api/v1/boards/BOARD_ID/tasks.xml?api_token=YOUR_API_TOKEN
Replacing YOUR_ACCOUNT_DOMAIN, YOUR_API_TOKEN with appropriate values and BOARD_ID with the number from previous step. This will show you machine friendly listing of tasks for selected board, similar to the one below:

Api response example for get board tasks

OK, so let's take this even one step further and create a new task. To do this you only need to know two things - the board ID number, which you retrieved in one of the previous steps, and the title you would like to give to the newly created task.

 http://YOUR_ACCOUNT_DOMAIN.kanbantool.com/api/v1/boards/BOARD_ID/tasks.xml?api_token=YOUR_API_TOKEN&task[name]=TITLE_FOR_YOUR_NEW_TASK&_m=POST
Api response example for create task


You can use any other API method directly from your browser. Just remember to add api_token=... to each request, and to use _m=... parameter when you would like to perform PUT, POST or DELETE requests (i.e. _m=DELETE for deleting an object).

API Interface

The KanbanTool API is implemented as a REST and JSONP New interface allowing to interact with resources stored on the server using HTTP verbs such as GET, POST, PUT and DELETE, with server returning either XML or JSON response.

When your library or client protocol does not support RESTful verbs, or when you are using JSONP protocol, you can pass HTTP verb inside the "_m" HTTP parameter like below:

 # Following requests are equivalent:
 DELETE https://domain.kanbantool.com/api/v1/boards/board_id/tasks/task_id.xml
 GET https://domain.kanbantool.com/api/v1/boards/board_id/tasks/task_id.xml?_m=delete
Both XML and JSON response formats are supported for all API requests:
 # To get task details in JSON format ({name:"..."})
 GET https://domain.kanbantool.com/api/v1/boards/board_id/tasks/task_id.json

 # To get task details in XML format (<task><name>...</name></task>)
 GET https://domain.kanbantool.com/api/v1/boards/board_id/tasks/task_id.xml
For JSONP the callback function reference should be passed in "callback" parameter: New
 # Get task details in JSON format ({name:"..."}) and wrap them into myFunction function call:
 GET https://domain.kanbantool.com/api/v1/boards/board_id/tasks/task_id.json?callback=myFunction

 # Would return following result
 myFunction({"task":{"name": ... }})
Board, Task and User ID mapping warning
Please note that in the current API version, there is an inconsistency between board IDs which appear in the website URLs and the same board IDs when retrieved using API. The IDs appearing in the website URLs are shifted by 20, so that a proper way to access board http://test.kanbantool.com/boards/123-some-board through the API would be http://test.kanbantool.com/api/v1/boards/103.xml.
This is likely to be fixed at some point, but the API IDs are guaranteed not to change.

JSON response format warning
In the current API version, there is an inconsistency in the way JSON responses are encoded.
For some API methods response will contain immediate object attributes like {title:''}, while for others they would be packed into respective object namespace like { task:{title:''} }.
To make sure JSON response can be accessed in uniform way, you can use the snippet below.

 /**
  * A function to unwrap JSON responses,
  * making sure that each response can be accessed in uniform and predictable way.
  * +Please note+ that when using methods from KanbanTool JSONP API wrapper library (api.js)
  * this is already being done by the KanbanTool.Api.call method, and is not needed.
  */
 function unwrapJSON( data, what ){
   if( jQuery.isArray(data) ){
     return jQuery.map(data, function(e){return e[what] ? e[what] : e});
   } else {
     return ( data[what] ? data[what] : data );
   }
 };

 /* You can use it in the following way */
 var boards = unwrapJSON( raw_json_response_from_kanbantool, 'board' );

Authentication

Each request needs to be authenticated with the secret api_token, which is unique to every user account and can be generated on the "My Info" » "API Access" page. API token can be passed for verification in two ways, either as HTTP request parameter with "api_token" name, or as HTTP request header named "X-KanbanToolToken":

 # Each request needs to be authenticated using api_token in one of two ways.
 # Following requests are equivalent:

 # api_token as HTTP parameter
 GET https://domain.kanbantool.com/api/v1/boards.xml?api_token=api_token

 # api_token as HTTP header
 GET https://domain.kanbantool.com/api/v1/boards.xml
 X-KanbanToolToken: api_token
If API token is invalid, a response with status code 401 (Unauthorized) and error message will be returned:
 # XML error response for invalid api_token, returned with 401 HTTP status code
 <error>
   <message>API token is invalid</message>
   <status type="integer">401</status>
 </error>

Permissions

API requests are always made on behalf of registered users, and executed with their permissions. This means that the permissions of api_token owner are always being checked when you make API calls. Note that if your plan allows you to add more people to your account then you can dedicate a new user account for your API needs.

If API user does not have sufficient permissions, a 403 (Forbidden) status code will be returned together with short error description.

 # sample XML error response for insufficient privileges, returned with 403 HTTP status code
 <error>
   <message>Permission to read tasks required for user 110</message>
   <status type="integer">403</status>
 </error>

SSL Encryption

KanbanTool API supports SSL encryption. Both unencrypted (http) and encrypted (https) requests are fully supported.

Working with Boards

Listing accessible boards

 # Listing all accessible boards in XML format
 GET https://domain.kanbantool.com/api/v1/boards.xml?api_token=api_token

 # Sample Response
 <boards type="array">
   <board>
     <created-at type="datetime">2010-01-14T13:02:22+01:00</created-at>
     <description>Main project board</description>
     <folder-id type="integer">1</folder-id>
     <id type="integer">6</id>
     <last-activity-on type="date">2011-02-07</last-activity-on>
     <name>Kanban Tool</name>
     <position type="integer">1</position>
     <version type="integer">3860</version>

     <folder>
       <created-at type="datetime">2010-01-09T18:40:47+01:00</created-at>
       <description>kanbantool.com development & support</description>
       <id type="integer">1</id>
       <name>Kanban Tool</name>
       <position type="integer">2</position>
     </folder>
   </board>
 </boards>

Viewing board structure and settings

 # Viewing board structure in XML format
 GET https://domain.kanbantool.com/api/v1/boards/board_id.xml?api_token=api_token

 # Sample Response
 <board>
   <created-at type="datetime">2010-01-09T18:44:06+01:00</created-at>
   <description>Web development tool</description>
   <folder-id type="integer">1</folder-id>
   <id type="integer">1</id>
   <last-activity-on type="date">2011-02-11</last-activity-on>
   <name>Kanban board</name>
   <position type="integer">4</position>
   <version type="integer">904</version>

   <swimlanes type="array">
     <swimlane>
       <board-id type="integer">1</board-id>
       <id type="integer">1</id>
       <limit type="integer" nil="true"/>
       <name/>
       <position type="integer">1</position>
     </swimlane>
   </swimlanes>

   <workflow-stages type="array">
     <workflow-stage>
       <board-id type="integer">1</board-id>
       <id type="integer">1</id>
       <lane-width type="integer">1</lane-width>
       <limit type="integer" nil="true"/>
       <name nil="true"/>
       <parent-id type="integer" nil="true"/>
       <position type="integer">1</position>
     </workflow-stage>

     <workflow-stage>
       <board-id type="integer">1</board-id>
       <id type="integer">2</id>
       <lane-width type="integer">2</lane-width>
       <limit type="integer" nil="true"/>
       <name>Doing</name>
       <parent-id type="integer" nil="true"/>
       <position type="integer">2</position>
     </workflow-stage>

     <workflow-stage>
       <board-id type="integer">1</board-id>
       <id type="integer">3</id>
       <lane-width type="integer">1</lane-width>
       <limit type="integer" nil="true"/>
       <name>Done</name>
       <parent-id type="integer" nil="true"/>
       <position type="integer">3</position>
     </workflow-stage>
   </workflow-stages>

   <card-types type="array">
     <card-type>
       <board-id type="integer">1</board-id>
       <color-ref>yellow</color-ref>
       <id type="integer">1</id>
       <is-default type="boolean">true</is-default>
       <is-disabled type="boolean">false</is-disabled>
       <name>Feature</name>
       <position type="integer">1</position>
     </card-type>

     <card-type>
       <board-id type="integer">1</board-id>
       <color-ref>red</color-ref>
       <id type="integer">2</id>
       <is-default type="boolean">false</is-default>
       <is-disabled type="boolean">false</is-disabled>
       <name>Bug</name>
       <position type="integer">2</position>
     </card-type>
   </card-types>
 </board>

Listing users and permissions for given board

 # Listing user permissions in XML format
 GET https://domain.kanbantool.com/api/v1/boards/board_id/users.xml?api_token=api_token

 # Sample Response
 <shared-item-users type="array">
   <shared-item-user>  # Current API user (caller) is returned always as the first record
     <can-create-tasks type="boolean">true</can-create-tasks>
     <can-delete-tasks type="boolean">true</can-delete-tasks>
     <can-move-tasks type="boolean">true</can-move-tasks>
     <can-read-tasks type="boolean">true</can-read-tasks>
     <can-update-tasks type="boolean">true</can-update-tasks>
     <id type="integer">153</id>
     <updated-at type="datetime">2011-04-22T14:00:12+02:00</updated-at>
     <user-id type="integer">1</user-id>
     <user>
       <id type="integer">1</id>
       <initials>API</initials>
       <is-suspended type="boolean">false</is-suspended>
       <name>API Access - Joe Six-Pack</name>
     </user>
   </shared-item-user>
   <shared-item-user> # Active users are listed next
     <can-create-tasks type="boolean">true</can-create-tasks>
     <can-delete-tasks type="boolean">true</can-delete-tasks>
     <can-move-tasks type="boolean">true</can-move-tasks>
     <can-read-tasks type="boolean">true</can-read-tasks>
     <can-update-tasks type="boolean">true</can-update-tasks>
     <id type="integer">156</id>
     <updated-at type="datetime">2011-04-26T17:39:28+02:00</updated-at>
     <user-id type="integer">3</user-id>
     <user>
       <id type="integer">3</id>
       <initials>BZ</initials>
       <is-suspended type="boolean">false</is-suspended>
       <name>Bernard Zent</name>
     </user>
   </shared-item-user>
   <shared-item-user> # And finally the suspended users
     <can-create-tasks type="boolean">true</can-create-tasks>
     <can-delete-tasks type="boolean">true</can-delete-tasks>
     <can-move-tasks type="boolean">true</can-move-tasks>
     <can-read-tasks type="boolean">true</can-read-tasks>
     <can-update-tasks type="boolean">true</can-update-tasks>
     <id type="integer">165</id>
     <updated-at type="datetime">2011-04-22T14:13:12+02:00</updated-at>
     <user-id type="integer">2330</user-id>
     <user>
       <id type="integer">2330</id>
       <initials>AL</initials>
       <is-suspended type="boolean">true</is-suspended>
       <name>Adam Lee</name>
     </user>
   </shared-item-user>
 </shared-item-users>

Listing recent activity for board New

 # Recent activity feed for board in XML format. Optional parameters include:
 # from - date in YY-MM-DDThh:mm format (i.e. 2011-11-23T23:11)
 # to - date in YY-MM-DDThh:mm format (i.e. 2011-11-23T23:11)
 # user_id - show only activity for given user ID
 # offset - beginning with the given value
 # limit - limit number of results (max. 1000)
 # before - return only changelogs from before given ID
 GET https://domain.kanbantool.com/api/v1/boards/board_id/changelog.xml?api_token=api_token&from=from_date&to=to_date&user_id=user_id&offset=offset&limit=results_limit

 # Sample Response
 <changelogs type="array">
   <changelog>
     <id type="integer">2554580</id>
     <changed-object-type>Task</changed-object-type>
     <changed-object-id type="integer">383844</changed-object-id>
     <user-id type="integer">6305</user-id>
     <swimlane-id type="integer">24185</swimlane-id>
     <workflow-stage-id type="integer" nil="true"></workflow-stage-id>
     <what>comment_deleted</what>
     <description>Adam has deleted recent comment</description>
     <created-at type="datetime">2011-11-25T12:31:31+00:00</created-at>
   </changelog>
   <changelog>
     <id type="integer">2954579</id>
     <changed-object-type>Task</changed-object-type>
     <changed-object-id type="integer">383844</changed-object-id>
     <user-id type="integer">6305</user-id>
     <swimlane-id type="integer">24185</swimlane-id>
     <workflow-stage-id type="integer" nil="true"></workflow-stage-id>
     <what>comment_added</what>
     <description>Adam has commented on task 'Buy wine': dry or sweet?</description>
     <created-at type="datetime">2011-11-25T12:31:27+00:00</created-at>
   </changelog>
 </changelogs>

Manipulating Tasks

Listing tasks from given board

 # Listing tasks from given board in XML format
 GET https://domain.kanbantool.com/api/v1/boards/board_id/tasks.xml?api_token=api_token

 # Sample Response
 <tasks type="array">
   <task>
     <archived-at type="datetime" nil="true"/>
     <assigned-user-id type="integer">3</assigned-user-id>
     <card-type-id type="integer">5</card-type-id>
     <comments-count type="integer">1</comments-count>
     <created-at type="datetime">2010-01-09T18:48:06+01:00</created-at>
     <custom-field-1 nil="true"/>
     <custom-field-2 nil="true"/>
     <custom-field-3 nil="true"/>
     <custom-field-4 nil="true"/>
     <custom-field-5 nil="true"/>
     <custom-field-6 nil="true"/>
     <custom-field-7 nil="true"/>
     <custom-field-8 nil="true"/>
     <custom-field-9 nil="true"/>
     <custom-field-10 nil="true"/>
     <description>We need to finally add some API to KT</description>
     <due-date type="date" nil="true"/>
     <external-link nil="true"/>
     <id type="integer">1</id>
     <name>Add API to KanbanTool</name>
     <position type="integer">4</position>
     <priority type="integer">0</priority>
     <size-estimate type="decimal">1.0</size-estimate>
     <subtasks-completed-count type="integer">0</subtasks-completed-count>
     <subtasks-count type="integer">1</subtasks-count>
     <swimlane-id type="integer">1</swimlane-id>
     <tags/>
     <updated-at type="datetime">2011-02-09T15:12:35+01:00</updated-at>
     <workflow-stage-id type="integer">2</workflow-stage-id>
     <assigned-user>
       <initials>JS</initials>
       <name>Joe Stuart</name>
     </assigned-user>
   </task>
 </tasks>

Listing archived tasks from given board New

 # Listing archived tasks from given board in XML format
 GET https://domain.kanbantool.com/api/v1/boards/board_id/tasks.xml?archived=1&page=page&per_page=per_page&api_token=api_token
 
 GET PARAMETERS:
 archived=1   => List archived tasks

 OPTIONAL POST PARAMETERS:
 page       => Page number with 1 being the first page (default: 1)
 per_page   => Number of tasks to show on single page (default: 50, max: 175)

 COMMENT:
 Results of this API call are paginated to facilitate quick operations on large archives.
 Each response contains additional information about pagination.
 Tasks are returned in order determined by archived_at with the most recently archived first.
 

 # Sample Response
 <tasks type="array">
   <task>
     <archived-at type="datetime" nil="true"/>
     <assigned-user-id type="integer">3</assigned-user-id>
     <card-type-id type="integer">5</card-type-id>
     .......
   </task>
   .......
   <pagination>
     <page>1</page>
     <total_pages>2</total_pages>
     <total_entries>53</total_entries>
     <previous_page></previous_page>
     <next_page>2</next_page>
   </pagination>
 </tasks>

Listing tasks from given board, swimlane and workflow stage New

 # Listing tasks from given board and swimlane and/or workflow stage in XML format
 GET https://domain.kanbantool.com/api/v1/boards/board_id/tasks.xml?swimlane_id=123&workflow_stage_id=321&page=page&per_page=per_page&api_token=api_token
 

 OPTIONAL PARAMETERS:
 swimlane_id        => List tasks only from given swimlane
 workflow_stage_id  => List tasks only from given workflow stage
 archived=1         => List archived tasks
 page               => Page number with 1 being the first page (default: 1)
 per_page           => Number of tasks to show on single page (default: 50, max: 175)
 

 # Sample Response
 <tasks type="array">
 <task>
 <archived-at type="datetime" nil="true"/>
 <assigned-user-id type="integer">3</assigned-user-id>
 <card-type-id type="integer">5</card-type-id>
 .......
 </task>
 .......
 <pagination>
 <page>1</page>
 <total_pages>2</total_pages>
 <total_entries>53</total_entries>
 <previous_page></previous_page>
 <next_page>2</next_page>
 </pagination>
 </tasks>

Viewing task details

 # Viewing task details in XML format
 GET https://domain.kanbantool.com/api/v1/boards/board_id/tasks/task_id.xml?api_token=api_token

 # Sample Response
 <task>
   <archived-at type="datetime" nil="true"/>
   <assigned-user-id type="integer">3</assigned-user-id>
   <card-type-id type="integer">5</card-type-id>
   <comments-count type="integer">1</comments-count>
   <created-at type="datetime">2010-01-09T18:48:06+01:00</created-at>
   <custom-field-1 nil="true"/>
   <custom-field-2 nil="true"/>
   <custom-field-3 nil="true"/>
   <custom-field-4 nil="true"/>
   <custom-field-5 nil="true"/>
   <custom-field-6 nil="true"/>
   <custom-field-7 nil="true"/>
   <custom-field-8 nil="true"/>
   <custom-field-9 nil="true"/>
   <custom-field-10 nil="true"/>
   <description>We need to finally add some API to KT</description>
   <due-date type="date" nil="true"/>
   <external-link nil="true"/>
   <id type="integer">1</id>
   <name>Add API to KanbanTool</name>
   <position type="integer">4</position>
   <priority type="integer">0</priority>
   <size-estimate type="decimal">1.0</size-estimate>
   <subtasks-completed-count type="integer">0</subtasks-completed-count>
   <subtasks-count type="integer">1</subtasks-count>
   <swimlane-id type="integer">1</swimlane-id>
   <tags/>
   <updated-at type="datetime">2011-02-09T15:12:35+01:00</updated-at>
   <workflow-stage-id type="integer">2</workflow-stage-id>

   <comments type="array">
     <comment>
       <content>Sample Comment</content>
       <created-at type="datetime">2011-02-09T11:39:39+01:00</created-at>
       <id type="integer">12946</id>
       <updated-at type="datetime">2011-02-09T11:39:39+01:00</updated-at>
       <user-id type="integer">3</user-id>
       <user>
         <initials>JS</initials>
         <name>Joe Stuart</name>
       </user>
     </comment>
   </comments>

   <assigned-user>
     <initials>JS</initials>
     <name>Joe Stuart</name>
   </assigned-user>

   <changelogs type="array">
     <changelog>
       <created-at type="datetime">2010-01-09T18:48:06+01:00</created-at>
       <description>
         JS added task Add API to KanbanTool to the board
       </description>
       <id type="integer">1</id>
       <swimlane-id type="integer" nil="true"/>
       <user-id type="integer" nil="true"/>
       <what>created</what>
       <workflow-stage-id type="integer" nil="true"/>
     </changelog>
     <changelog>
       <created-at type="datetime">2011-02-09T11:39:40+01:00</created-at>
       <description>
         JS has commented on task 'Add API to KanbanTool': Sample Comment
       </description>
       <id type="integer">581070</id>
       <swimlane-id type="integer">1</swimlane-id>
       <user-id type="integer">1</user-id>
       <what>comment_added</what>
       <workflow-stage-id type="integer" nil="true"/>
     </changelog>
   </changelogs>

   <subtasks type="array">
     <subtask>
       <assigned-user-id type="integer">3</assigned-user-id>
       <created-at type="datetime">2011-02-09T11:39:31+01:00</created-at>
       <id type="integer">21598</id>
       <is-completed type="boolean">false</is-completed>
       <name>ToDo1</name>
       <position type="integer">1</position>
       <task-id type="integer">1</task-id>
       <updated-at type="datetime">2011-02-09T11:39:31+01:00</updated-at>
       <assigned-user>
         <initials>JS</initials>
         <name>Joe Stuart</name>
       </assigned-user>
     </subtask>
   </subtasks>

 </task>

Manipulating tasks

Creating tasks

 # Creating tasks with response in XML format
 POST https://domain.kanbantool.com/api/v1/boards/board_id/tasks.xml?api_token=api_token
 
 POST PARAMETERS:
 task[name] => Task title

 OPTIONAL POST PARAMETERS:
 task[description]       => Description of task in HTML / Rich Text format,
 task[assigned_user_id]  => Assigned user identifier,
 task[card_type_id]      => One of valid card type identifiers for this board,
 task[due_date]          => Due date in YYYY-MM-DD format,
 task[external_link]     => External link, if any.
 task[priority]          => Tak priority as numeric value, where p < 0 - low ; p==0 - normal ; p > 0 - high.
 task[swimlane_id]       => Swimline identifier to create the task in, may be left blank.
 task[workflow_stage_id] => Workflow stage (column) identifier to create the task in, may be left blank.
 task[custom_field_1] .. task[custom_field_10] => Custom fields values

 DEFAULT VALUES:
 Unless otherwise specified, tasks will be created in the top swimlane, leftmost column,
 at the bottom of the list, with the default card type, priority and size estimate of 1.0
 

 # Response
 See "Viewing task details"

 # Sample XML Error Response
 <error>
   <message>Name cannot be blank, Size estimate must be numeric</message>
   <status type="integer">400</status>
 </error>

Modifying/Updating tasks

 # Updating tasks with response in XML format
 PUT https://domain.kanbantool.com/api/v1/boards/board_id/tasks/task_id.xml?api_token=api_token
 
 HTTP PARAMETERS: the same as when creating tasks, except:
 swimlane_id, workflow_stage_id, position which have no effect

 # Response
 See "Viewing task details"

Moving tasks

 # Moving tasks with response in XML format
 PUT https://domain.kanbantool.com/api/v1/boards/board_id/tasks/task_id/move.xml?api_token=api_token
 
 HTTP PARAMETERS (OPTION 1):
 direction => one of: up, down, prev_stage, next_stage, prev_swimlane, next_swimlane
 override  => Reason for overriding the WIP limit (optional)
              If set, the WIP limit on the target column is not checked.


 HTTP PARAMETERS (OPTION 2):
 Any set of following parameters:
 workflow_stage_id =>  target column id to which task should be moved to.
                       If position is not given, it will be appended to the bottom of the list.
 swimlane_id       =>  target swimlane task should be moved to.
                       If position is not given, it will be appended to the bottom of the list.
 position          =>  position task should be moved to inside the target column.
                       IMPORTANT:  Position parameter is not supported yet,
                                   and will be implemented in future API releases.
 override          =>  Reason for overriding the WIP limit (optional)
                       If set, the WIP limit on the target column is not checked.

 # Response
 See "Viewing task details"

 # Sample XML error response
 <error>
   <message>WIP Limit exceeded for target column and override not specified</message>
   <status type="integer">409</status>
 </error>

 

Deleting tasks

 # Deleting tasks with response in XML format (task must not be archived)
 DELETE https://domain.kanbantool.com/api/v1/boards/board_id/tasks/task_id.xml?api_token=api_token
 
 # Response
 Returns deleted task. See "Viewing task details".

 # Sample XML error response
 <error>
   <message>Task is archived, please unarchive it first</message>
   <status type="integer">400</status>
 </error>

Archiving tasks

 # Archiving tasks with response in XML format (task must be in the last column)
 PUT https://domain.kanbantool.com/api/v1/boards/board_id/tasks/task_id/archive.xml?api_token=api_token
 
 # Response
 See "Viewing task details"

 # Sample XML error response
 <error>
   <message>Task is not ready to be archived</message>
   <status type="integer">422</status>
 </error>

Unarchiving tasks New

 # Unarchiving task with response in XML format (task must be archived)
 PUT https://domain.kanbantool.com/api/v1/boards/board_id/tasks/task_id/unarchive.xml?api_token=api_token
 
 # Response
 See "Viewing task details"

 # Sample XML error response
 <error>
   <message>Task is not archived</message>
   <status type="integer">422</status>
 </error>

Modifying Task ToDo list (subtasks)

Listing subtasks for given task New

 # Listing subtasks with response in XML format
 GET https://domain.kanbantool.com/api/v1/boards/board_id/tasks/task_id/subtasks.xml?api_token=api_token

 # Sample Response
 <subtasks type="array">
   <subtask>
     <id type="integer">102448</id>
     <name>A first ToDo entry</name>
     <position type="integer">1</position>
     <task-id type="integer">383248</task-id>
     <created-at type="datetime">2011-12-05T14:04:55+00:00</created-at>
     <is-completed type="boolean">true</is-completed>
     <updated-at type="datetime">2011-12-05T14:11:44+00:00</updated-at>
     <assigned-user-id type="integer" nil="true"></assigned-user-id>
   </subtask>
   <subtask>
     <id type="integer">102445</id>
     <name>A second and last ToDo entry</name>
     <position type="integer">2</position>
     <task-id type="integer">383248</task-id>
     <created-at type="datetime">2011-12-05T13:59:07+00:00</created-at>
     <is-completed type="boolean">false</is-completed>
     <updated-at type="datetime">2011-12-05T14:11:44+00:00</updated-at>
     <assigned-user-id type="integer" nil="true"></assigned-user-id>
   </subtask>
 </subtasks>

Viewing subtask details New

 # Subtask details with response in XML format
 GET https://domain.kanbantool.com/api/v1/boards/board_id/tasks/task_id/subtasks/subtask_id.xml?api_token=api_token

 # Sample Response
 <subtask>
   <id type="integer">102448</id>
   <name>A first ToDo entry</name>
   <position type="integer">1</position>
   <task-id type="integer">383248</task-id>
   <created-at type="datetime">2011-12-05T14:04:55+00:00</created-at>
   <is-completed type="boolean">true</is-completed>
   <updated-at type="datetime">2011-12-05T14:11:44+00:00</updated-at>
   <assigned-user-id type="integer" nil="true"></assigned-user-id>
 </subtask>

Creating new subtasks New

 # Creating new subtask with response in XML format
 # New subtasks are always added to the bottom of the list. You can later reorder them by calling reorder method.
 POST https://domain.kanbantool.com/api/v1/boards/board_id/tasks/task_id/subtasks.xml?api_token=api_token

 
 # HTTP PARAMETERS:
 Subtask mandatory and optional parameters:
 subtask[name]              => a name of the new subtask (string, mandatory).
 subtask[is_completed]      => whether this subtask is completed or not (optional, default is false)
 subtask[assigned_user_id]  => ID of user assigned to this subtask (optional, default is null).

 # Response
 See "Viewing subtask details"

 # Sample XML error response
 <error>
   <message>Name can't be blank</message>
   <status type="integer">422</status>
 </error>

Updating existing subtasks New

 # Updating existing subtask with response in XML format
 # This method will not modify subtask position. To reorder subtasks call reorder method.
 PUT https://domain.kanbantool.com/api/v1/boards/board_id/tasks/task_id/subtasks/subtask_id.xml?api_token=api_token

 HTTP PARAMETERS (all parameters are optional; missing attributes will not be updated):
 subtask[name]              => a name of the new subtask (string).
 subtask[is_completed]      => whether this subtask is completed or not (boolean).
 subtask[assigned_user_id]  => ID of user assigned to this subtask (integer).

 # Response
 Updated subtask - see "Viewing subtask details" for details.

 # Sample XML error response
 <error>
   <message>Name can't be blank</message>
   <status type="integer">422</status>
 </error>

Deleting subtasks New

 # Deleting existing subtask with response in XML format
 DELETE https://domain.kanbantool.com/api/v1/boards/board_id/tasks/task_id/subtasks/subtask_id.xml?api_token=api_token

 # Response
 Deleted subtask - see "Viewing subtask details" for details
 

Reordering subtasks list New

 # Reordering subtasks list with response in XML format
 PUT https://domain.kanbantool.com/api/v1/boards/board_id/tasks/task_id/subtasks/reorder.xml?api_token=api_token

 
 # HTTP PARAMETERS:
 order =>  A string of comma separated subtask IDs in the new order i.e. "345,2113,123".
           A list must contain all subtask IDs for this method to work.

 # Response
 Array of subtasks in the new order - see "Listing subtasks" for details.

 # Sample XML error response
 <error>
   <message>Not all subtasks have been included in the list.</message>
   <status type="integer">422</status>
 </error>

Working with Task Comments New

Listing comments for given task New

 # Listing comments with response in XML format
 GET https://domain.kanbantool.com/api/v1/boards/board_id/tasks/task_id/comments.xml?api_token=api_token

 # Sample Response
 # please note that the second comment has been made by user which is no loger existing (has been deleted)
 <comments type="array">
   <comment>
     <id type="integer">51999</id>
     <created-at type="datetime">2011-12-05T13:28:19+00:00</created-at>
     <updated-at type="datetime">2011-12-05T13:28:19+00:00</updated-at>
     <user-id type="integer">6405</user-id>
     <content>A first comment</content>
   </comment>
   <comment>
     <id type="integer">52000</id>
     <created-at type="datetime">2011-12-05T13:31:35+00:00</created-at>
     <updated-at type="datetime">2011-12-05T13:31:35+00:00</updated-at>
     <user-id type="integer" nil="true"></user-id>
     <content>A second, and last comment.</content>
   </comment>
 </comments>

Viewing comment details New

 # Comment details with response in XML format
 GET https://domain.kanbantool.com/api/v1/boards/board_id/tasks/task_id/comments/comment_id.xml?api_token=api_token

 # Sample Response
 <comment>
   <id type="integer">51999</id>
   <created-at type="datetime">2011-12-05T13:28:19+00:00</created-at>
   <updated-at type="datetime">2011-12-05T13:28:19+00:00</updated-at>
   <user-id type="integer">6405</user-id>
   <content>A first comment</content>
 </comment>

Posting new comments New

 # Creating new comments with response in XML format
 # New comments are always added to the end of conversation and cannot be modified.
 POST https://domain.kanbantool.com/api/v1/boards/board_id/tasks/task_id/comments.xml?api_token=api_token

 
 # HTTP PARAMETERS:
 Comment mandatory and optional parameters:
 comment[content]           => a content of the new comment (string, mandatory).

 # Response
 A newly created comment - see "Viewing comment details" for details

 # Sample XML error response
 <error>
   <message>Content can't be blank</message>
   <status type="integer">422</status>
 </error>

Deleting recent comments New

 # Deleting recent comment with response in XML format
 # User can only delete recent comments made by himself.
 DELETE https://domain.kanbantool.com/api/v1/boards/board_id/tasks/task_id/comments/comment_id.xml?api_token=api_token

 
 # Response
 A deleted comment - see "Viewing comment details" for details

 # Sample XML error response
 <error>
   <message>This comment cannot be deleted. Please note that only last, recent made comments can be deleted.</message>
   <status type="integer">422</status>
 </error>

Working with Time Tracking New

Time tracking API is currently in beta and supports responses in JSON format only.

Time Tracker object reference

 id {Integer} unique identifier of the time_tracker object
 user_id {Integer} ID of user who has started this tracker
 board_id {Integer} ID of the board on which this tracker has been started
 task_id {Integer} ID of the task for which this tracker has been started
 listed {Boolean} true if this time_tracker is visible on the list of timers in the side panel
 started_at {Datetime} date and time on which this tracker has been started
 ended_at {Datetime} date and time on which this tracker has been stopped (may be null for running timers)
 seconds_from_resumed_sprint {Integer} number of seconds from previous trackers related to the same user and task
 created_at {Datetime} creation time
 updated_at {Datetime} last modification time

Listing timers for current user

 # List timers in JSON format for the current api_user
 GET https://domain.kanbantool.com/api/v1/time_trackers.json?api_token=api_token

 
   # OPTIONAL HTTP PARAMETERS:
   task_id - ID of task for which time trackers should be listed.
   active - set to 1 to get running timers, or to 0 to get finished timers
   listed - set to 1 to get timers which are visible on the list for the current api_user
   expand - set to 1 to add information about associated task, workflow_stage and card_type to each of time_trackers

   # Response
   JSON serialized array of time-tracker objects
 

Creating new time entries for current user

 # Create new time-tracker for the current api_user
 POST https://domain.kanbantool.com/api/v1/time_trackers.json?api_token=api_token

 
 # HTTP PARAMETERS:
 time_tracker[board_id] => board_id for which the time tracker should be created
 time_tracker[task_id] => task_id for which the time tracker should be created
 time_tracker[started_at]  => start date and time
 time_tracker[ended_at] => end date and time or null for running timers

 # Response
 A JSON serialized, newly created time tracker object.

Updating existing time entries

 # Update selected time-tracker, which either belongs to the API user, belongs to the board owned by API user, or belongs to any board if API user has at least account administrator privileges.
 PUT https://domain.kanbantool.com/api/v1/time_trackers/time_tracker_id.json?api_token=api_token

 
 # HTTP PARAMETERS:
 time_tracker[started_at]  => new start time
 time_tracker[ended_at] => new end time

 # Response
 A JSON serialized, updated time tracker object.

Deleting time entries

 # Delete selected time-tracker, which either belongs to the API user, belongs to the board owned by API user, or belongs to any board if API user has at least account administrator privileges.
 DELETE https://domain.kanbantool.com/api/v1/time_trackers/time_tracker_id.json?api_token=api_token

 
 # Response
 A JSON serialized, time tracker object representing the previous timer for the same task and user combination.

Working with Time Reporting New

Time tracking API is currently in beta and supports responses in JSON format only.

Generating time report

 # Generate time report
 GET https://domain.kanbantool.com/api/v1/time_report.json?api_token=api_token

 
 # HTTP PARAMETERS:
 report_type - one of 'summary' or 'detailed'
 board_id - a comma separated list of board IDs for which the report should be generated. All boards need to have at least read_tasks permission for the current api_user.
 include_filter_options - [0 or 1] whether the response should include 'filter_options' as one of attributes, which contains all valid filter options for given timeframe.

 expand - should hash keys of the resulting report be expanded into JSON serialized Hashes with :id and :name attributes
 from - a beginning of timeframe for this report
 to - an end of timeframe for this report
 group_by - a comma separated list of attributes by which this report should be grouped by. Currently one of 'board_id', 'task_id', 'user_id', 'sprint_id'.

 # OPTIONAL HTTP PARAMETERS (FILTERS):
 user_id - comma separated list of user_ids
 task_id - comma separated list of task_ids
 tasks.card_type_id - comma separated list of card_type_ids
 tasks.tags - comma separated list of tags

 # Response
 JSON serialized report