KanbanTool API Documentation

Introduction
Getting Started
Samples & Wrappers
Interface & Protocols
Authentication
Boards
Tasks
ToDo lists
Comments

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?

Read our Getting Started guide »

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

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

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

 # 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
 # limit - limit number of results (max. 1000)
 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&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"/>
     <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

 # 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_pageapi_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>

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"/>
   <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_5] => 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

 # 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

 # 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

 # 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

 # 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

 # 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

 # 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

 # 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

Listing comments for given task

 # 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

 # 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

 # 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

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