API Integration

Find out how you can gain advantage by using the Kanbanize Restful API

General information

In order to use the kanbanize RESTful API, you need to send a POST (no other method will work) http request to the following address: http://kanbanize.com/index.php/api/kanbanize/<function>

Where <function> is one of the following:

Function Limit per hour (per API KEY) Function Limit per hour (per API KEY)
login 30 get_projects_and_boards 30
get_board_structure 30 get_board_settings 30
create_new_task 30 delete_task 60
get_task_details 60 get_all_tasks 60
add_comment 30 move_task 60
edit_task 30 get_history 60
block_task 30

API key

To authenticate yourself to the system, you need to specify the API key as a header. To generate such a key, login to the system and go to the My account->API panel. If your role allows it, you will be able to access the tab and generate a unique key.

Note: Header name must be "apikey".

Input parameters

Depending on the function you are accessing, you need to specify certain parameters so that the request could be processed properly. The way parameters are set is by embedding them either into the request URI or into the request body. For example:

  1. 1. Sending a parameter "boardid" with value 22 as part of the request URI:
    1. a. http://<url>/index.php/api/kanbanize/<function>/boardid/22
  2. 2. Sending a parameter "boardid" with value 22 and parameter "taskid" with value 14 as part of the request URI:
    1. a. http://<url>/index.php/api/kanbanize/<function>/boardid/22/taskid/14
  3. 3. Sending a parameter "boardid" with value 22 and parameter "taskid" with value 14 as part of the rquest BODY. The BODY needs to be a valid JSON string. If a value is set in both the BODY and the URI, the BODY value is taken. If you use the backslash (\) or a double quote (") you need to escape them with the backslash character: (\\) or (\")
    1. a. The request URI: http://<url>/index.php/api/kanbanize/<function>
    2. b. The request body: {"boardid":22,"taskid":14}

You can also specify the format of the result. Available formats are:

  1. 1. XML (default if formatting parameter is not provided)
    1. a. http://<url>/index.php/api/kanbanize/<function>/<parameters>/format/xml
  2. 2. JSON (for more information check this website http://www.json.org/)
    1. a. http://<url>/index.php/api/kanbanize/<function>/<parameters>/format/json

Login/ login

Required
email Your email address
pass Your password
Optional
None
Output
email Your email address
username Your username
realname Your name
companyname Company name
timezone Your time zone
apykey Your API key.
Example request http://kanbanize.com/index.php/api/kanbanize/login/email/test%40test.com/pass/test
back to top

Projects and boards/ get_projects_and_boards

Required
None
Optional
None
Output
projects Array of the projects.
projects[][name] The name of the project
projects[][id] The ID of the project
projects[][boards] Array of details for any boards in current project ( name, id )
Example request (Do not forget to send a valid header containing your API key): http://kanbanize.com/index.php/api/kanbanize/get_projects_and_boards/
back to top

Board structure/ get_board_structure

Required
boardid The ID of the board whose structure you want to get. You can see the board ID on the dashboard screen, in the upper right corner of each board.
Optional
None
Output
columns Array containing the board columns (only the columns on last level are returned)
columns[][position] The position of the column
columns[][lcname] The name of the column.
columns[][description] The description of the column or swimlane.
lanes Array containing the board swimnales.
lanes[][lcname] The name of the swimlane.
lanes[][color] The color of the swimlane.
lanes[][description] The description of the column or swimlane.
Example request (Do not forget to send a valid header containing your API key): http://kanbanize.com/index.php/api/kanbanize/get_board_structure/boardid/2
back to top

Board settings/ get_board_settings

Required
boardid The ID of the board you want get settings. You can see the board ID on the dashboard screen, in the upper right corner of each board.
Optional
None
Output
usernames Array containing the usernames of the board members.
templates Array containing the templates available to this board.
types Array containing the types available to this board.
Example request (Do not forget to send a valid header containing your API key): http://kanbanize.com/index.php/api/kanbanize/get_board_settings/boardid/2
back to top

Create new task / create_new_task

All tasks are created in the Backlog section of the board.

Required
boardid The ID of the board you want the new task created into. You can see the board ID on the dashboard screen, in the upper right corner of each board.
Optional
title Title of the task
description Description of the task
priority One of the following: Low, Average, High
assignee Username of the assignee (must be a valid username)
color Any color code (e.g. 99b399) DO NOT PUT the # sign in front of the code!!!
size Size of the task
tags Space separated list of tags
deadline Dedline in the format: yyyy-mm-dd (e.g. 2011-12-13)
extlink A link in the following format: https:\\github.com\philsturgeon. If the parameter is embedded in the request BODY, use a standard link: https://github.com/philsturgeon.
type The name of the type you want to set.
template The name of the template you want to set. If you specify any property as part of the request, the one specified in the template will be overwritten.
Output
id The ID of the newly created task
Example request (Do not forget to send a valid header containing your API key): http://kanbanize.com/index.php/api/kanbanize/create_new_task/boardid/17/title/test task/description/task description/priority/High/assignee/mitaka/color/FFCC00/tags/tag1 tag2/deadline/2011-12-13/extlink/https:\\github.com\philsturgeon\codeigniter-restserver
back to top

Delete task / delete_task

Required
boardid The ID of the board where the task to be deleted is. You can see the board ID on the dashboard screen, in the upper right corner of each board.
taskid The ID of the task to be deleted.
Optional
None
Output
status The status of the operation (1 or error).
Example request (Do not forget to send a valid header containing your API key): http://kanbanize.com/index.php/api/kanbanize/delete_task/boardid/17/taskid/173
back to top

Get task details / get_task_details

Required
boardid The ID of the board where the task is located. You can see the board ID on the dashboard screen, in the upper right corner of each board.
taskid The ID of the task which details you want to get.
Optional
history Set to "yes" if you want to get history for the task.
event Only applicable if "history" is set to "yes". Accepts the following events: move, create, update, block, delete, comment, archived, subtask, loggedtime. If the parameter is not set, all of the events will be returned.
Output
taskid The ID of the task
title Title of the task
description Description of the task
type The task type
assignee Username of the assignee
subtasks Number of subtasks
subtaskscomplete Number of completed subtasks
color Task color
priority Task priority
size Task size
deadline Task deadline in format Day Month (e.g. 01 Aug)
deadlineoriginalformat Task deadline in format yyyy-mm-dd (e.g. 2012-08-01)
extlink Task external link
tags Task tags
leadtime Leadtime in days
blocked Is the task blocked (0 - no/ 1 - yes)
blockedreason Why the task is blocked
subtaskdetails Details of any subtasks (subtask id, subtask assignee, subtask title, subtask date of completion).
historydetails Details of task history (eventtype, historyevent, details, author, date, history id).
columnname The name of the column in which the task is located.
lanename The name of the swim-lane in which the task is located.
columnid The ID of the column in which the task is located.
laneid The ID of the swim-lane in which the task is located.
columnpath The full path to the card column in the format: "Column.Subcolumn1.Subcolumn2". If the task is located in a main column this will be the same as "columnname".
loggedtime The accumulated logged time of the task in hours.
Example request (Do not forget to send a valid header containing your API key): http://kanbanize.com/index.php/api/kanbanize/get_task_details/boardid/17/taskid/173
back to top

Get all tasks / get_all_tasks

Required
boardid The ID of the board where the tasks are located. You can see the board ID on the dashboard screen, in the upper right corner of each board.
Optional
subtasks Set to "yes" if you want to get subtask details for each task.
container Set to "archive" if you want to get tasks from archive.
fromdate Only applicable if container is set to "archive". The date after which the tasks of interest have been archived. Accepts the following formats: '2012-05-05', 'now', '10 September 2012', '-1 day', '-1 week 2 days', 'last Monday'. Default valuе is '1970-01-01'
todate Only applicable if container is set to "archive". The date before which the tasks of interest have been archived. Accepts the following formats: '2012-05-05', 'now', '10 September 2012', '-1 day', '-1 week 2 days', 'last Monday'. Default valuе is 'now'
version Gives the tasks from the specified archive version. The fromdate and todate parameters are ignored.
page With this parameter you control which page number to get. The method returns 30 tasks per page.
Output
taskid The ID of the task
position The position of the task
type The task type
assignee Username of the assignee
title Title of the task
description Description of the task
subtasks Number of subtasks
subtaskscomplete Number of completed subtasks
color Task color
priority Task priority
size Task size
deadline Task deadline in format Day Month (e.g. 01 Aug)
deadlineoriginalformat Task deadline in format yyyy-mm-dd (e.g. 2012-08-01)
extlink Task external link
tags Task tags
columnid The ID of the column in which the task is located.
laneid The ID of the swim-lane in which the task is located.
leadtime Leadtime in days
blocked Is the task blocked (0 - no/ 1 - yes)
blockedreason Why the task is blocked
subtaskdetails Details of any subtasks (subtask id, subtask assignee, subtask title, subtask date of completion).
columnname The name of the column in which the task is located.
lanename The name of the swim-lane in which the task is located.
columnpath The full path to the card column in the format: "Column.Subcolumn1.Subcolumn2". If the task is located in a main column this will be the same as "columnname".
loggedtime The accumulated logged time of the task in hours.
Example request (Do not forget to send a valid header containing your API key): http://kanbanize.com/index.php/api/kanbanize/get_all_tasks/boardid/17
back to top

Add comment / add_comment

Required
taskid The ID of the task you want to comment.
comment The comment.
Optional
None
Output
id ID of the history event
author Author of the comment
date Current date
Example request (Do not forget to send a valid header containing your API key): http://kanbanize.com/index.php/api/kanbanize/add_comment/taskid/173/comment/this is a test comment
back to top

Move task / move_task

With this action you can move tasks on the board by specifying the column name and optionally the swim-lane name.

Required
boardid The ID of the board where the task to be moved is located. You can see the board ID on the dashboard screen, in the upper right corner of each board.
taskid The ID of the task to move.
column The name of the column to move the task into. If the name of the column is unique, you can specify it alone, but if there are more than one columns with that name, you must specify it as columnname1 . columnname2 . columnname3.
Optional
lane The name of the swim-lane to move the task into. If omitted, the swimlane doesn't change.
position The position of the task in the new column (zero-based). If omitted, the task will be placed at the bottom of the column.'
exceedingreason If you can exceed a limit with a reason, supply it with this parameter.
Output
status The status of the operation (1 or error).
Example request (Do not forget to send a valid header containing your API key): http://kanbanize.com/index.php/api/kanbanize/move_task/boardid/17/taskid/24/column/MyColumn/
http://kanbanize.com/index.php/api/kanbanize/move_task/boardid/17/taskid/24/column/MainColumn.SubColumn.MyColumn/
http://kanbanize.com/index.php/api/kanbanize/move_task/boardid/17/taskid/24/column/MainColumn.SubColumn.MyColumn/lane/Bugs
back to top

Edit task / edit_task

With this action you can update the task details.

Required
boardid The ID of the board where the task to be edited is located. You can see the board ID on the dashboard screen, in the upper right corner of each board.
taskid The ID of the task to edit
Optional
title Title of the task
description Description of the task
priority One of the following: Low, Average, High
assignee Username of the assignee (must be a valid username)
color Any color code (e.g. 99b399) DO NOT PUT the # sign in front of the code!!!
size Size of the task
tags Space separated list of tags
deadline Dedline in the format: yyyy-mm-dd (e.g. 2011-12-13)
extlink A link in the following format: https:\\github.com\philsturgeon. If the parameter is embedded in the request BODY, use a standard link: https://github.com/philsturgeon.
type The name of the type you want to set.
Output
status The status of the operation (1 or error).
Example request (Do not forget to send a valid header containing your API key): http://kanbanize.com/index.php/api/kanbanize/edit_task/boardid/17/taskid/24/title/My new title/description/My new description/size/24
back to top

Block task / block_task

Required
boardid The ID of the board where the task to be blocked/unblocked is located. You can see the board ID on the dashboard screen, in the upper right corner of each board.
taskid The ID of the task
event Possible valules:
'block' - block a task
'editblock' - edit the blocked reason
'unblock' - unblock a task
blockreason Required if event is set to 'block' or 'editblock'
Optional
None
Output
status The status of the operation (1 or error).
Example request (Do not forget to send a valid header containing your API key): http://kanbanize.com/index.php/api/kanbanize/block_task/boardid/2/taskid/1173/event/block/blockreason/Reason text
http://kanbanize.com/index.php/api/kanbanize/block_task/boardid/2/taskid/1173/event/unblock
back to top

Get board activities / get_board_activities

With this action you can get all activities for a particular board.

Required
boardid The ID of the board. You can see the board ID on the dashboard screen, in the upper right corner of each board.
fromdate The date after which the activities of interest happened. Accepts the following formats: '2012-05-05', 'now', '10 September 2012', '-1 day', '-1 week 2 days', 'last Monday'.
todate The date before which the activities of interest happened. Accepts the following formats: '2012-05-05', 'now', '10 September 2012', '-1 day', '-1 week 2 days', 'last Monday'.
Optional
page Default is 1
resultsperpage Default is 30
author Default is ALL
eventtype Options : Transitions, Updates, Comments, Blocks. Default is ALL
Output
allactivities The number of all activities for the corresponding time window specified by the fromdate and todate parameters.
page The current page.
activities Array containing the board activities.
activities[][author] Who performed the action.
activities[][event] Type of the event (Task moved, Task blocked, Task archived etc.)
activities[][text] History details.
activities[][date] When the event happened.
activities[][taskid] The id of the task which was updated/moved/blocked, etc.
Example request (Do not forget to send a valid header containing your API key): http://kanbanize.com/index.php/api/kanbanize/get_board_activities/boardid/2/fromdate/2012-08-05/todate/now/page/2
http://kanbanize.com/index.php/api/kanbanize/get_board_activities/boardid/2/fromdate/-1 week/todate/12 Aug/page/3/eventtype/comments
back to top