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://<subdomain>.kanbanize.com/index.php/api/kanbanize/<function>

Where:

<subdomain> is the subdomain part for your premium account. If using the community version skip the subdomain part.

<function> is one of the following:

Function Limit per hour (per API KEY) Function Limit per hour (per API KEY)
login 30 get_board_structure 30
get_projects_and_boards 30 get_full_board_structure 30
get_board_settings 30 get_board_activities 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 block_task 30
add_subtask 30 edit_subtask 30

API Wrappers in Ruby, PHP, Python and .NET

Before you start developing your own code, make sure to check what people from the community have already submitted. You can find more details about the available API wrappers on the Apps page.

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
apikey Your API key.
Example request http://<subdomain>.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://<subdomain>.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://<subdomain>.kanbanize.com/index.php/api/kanbanize/get_board_structure/boardid/2
back to top

Full board structure / get_full_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
columns[][position] The position of the column
columns[][lcname] The name of the column.
columns[][path] Unique identifier which contains the id of the column with all its parent columns. E.g. progress_17_1478 means that the column id is 1478, its parent is the column with id 17 and the parent area is IN PROGRESS.
columns[][description] The description of the column or swimlane.
columns[][lcid] Lane/Column ID. This is the ID of the column, which is the last part of the path parameter described above.
columns[][children[]]* If the column has sub-columns, they are returned in the children array recursively.
lanes Array containing the board swimnales.
lanes[][position] The position of the swimlane.
lanes[][lcname] The name of the swimlane.
lanes[][path] Unique identifier of the swimlane which concatenates the string "lane_" concatenated with the swimlane ID.
lanes[][color] The color of the swimlane.
lanes[][description] The description of the column or swimlane.
lanes[][lcid] Lane/Column ID. This is the ID of the swimlane, which is the last part of the path parameter described above.
Example request (Do not forget to send a valid header containing your API key): http://<subdomain>.kanbanize.com/index.php/api/kanbanize/get_full_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.
avatars Associative array containing the URLs to the avatars 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://<subdomain>.kanbanize.com/index.php/api/kanbanize/get_board_settings/boardid/2
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', '10 September 2012'.
todate The date before which the activities of interest happened. Accepts the following formats: '2012-05-05', '10 September 2012'.
Optional
page Default is 1
resultsperpage Default is 30
author Default is ALL
eventtype Options : Transitions, Updates, Comments, Blocks. Default is All
textformat Options: "plain" (default) and "html". If the plain text format is used, the HTML tags are stripped from the history details.
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://<subdomain>.kanbanize.com/index.php/api/kanbanize/get_board_activities/boardid/2/fromdate/2012-08-05/todate/now/page/2
http://<subdomain>.kanbanize.com/index.php/api/kanbanize/get_board_activities/boardid/2/fromdate/-1 week/todate/12 Aug/page/3/eventtype/comments
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. #34a97b) 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://domain.com/resource. This option is only supported when parameters are sent in the request body.
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://<subdomain>.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
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://<subdomain>.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.
textformat Options: "plain" (default) and "html". If the plain text format is used, the HTML tags are stripped from the task description.
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://<subdomain>.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.
textformat Options: "plain" (default) and "html". If the plain text format is used, the HTML tags are stripped from the task description.
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://<subdomain>.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://<subdomain>.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 to move the task into. 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.
Optional
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.
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.
*This parameter is not taken into consideration when moving tasks to another board.
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://<subdomain>.kanbanize.com/index.php/api/kanbanize/move_task/boardid/17/taskid/24/column/MyColumn/
http://<subdomain>.kanbanize.com/index.php/api/kanbanize/move_task/boardid/17/taskid/24/column/MainColumn.SubColumn.MyColumn/
http://<subdomain>.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. #34a97b) 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://domain.com/resource. This option is only supported when parameters are sent in the request body.
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://<subdomain>.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://<subdomain>.kanbanize.com/index.php/api/kanbanize/block_task/boardid/2/taskid/1173/event/block/blockreason/Reason text
http://<subdomain>.kanbanize.com/index.php/api/kanbanize/block_task/boardid/2/taskid/1173/event/unblock
back to top

Add subtask / add_subtask

Required
taskparent The ID of the task where the subtask to be created is located.
Optional
title Title of the subtask
assignee Username of the assignee (must be a valid username)
Output
status The ID of the newly created subtask or 0 if an error has occurred.
Example request (Do not forget to send a valid header containing your API key): http://<subdomain>.kanbanize.com/index.php/api/kanbanize/add_subtask/taskparent/254/title/sample subtask title/assignee/myusername
back to top

Edit subtask / edit_subtask

Required
boardid The ID of the board where the subtask to be edited is located. You can see the board ID on the dashboard screen, in the upper right corner of each board.
subtaskid The ID of the subtask
Optional
title Title of the subtask
assignee Username of the assignee (must be a valid username)
complete Options: 1 or 0. If it`s set to 1 the subtask will be marked as finished, otherwise as unfinished.
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://<subdomain>.kanbanize.com/index.php/api/kanbanize/edit_subtask/boardid/68/subtaskid/673/title/new subtask title/complete/1
back to top

Log time / log_time

Required
loggedtime The number of hours you want to add to the task.
taskid The ID of the task or subtask to log time to.
Optional
description Comment about the log time entry.
Output
id The id of the log time event.
historyid The id of the event (for internal use).
taskid The id of the task or subtask that has been updated with a log time event.
author The username of the API user who updated the task.
details Message explaining the log time event.
loggedtime The number of hours that have been logged.
issubtask A boolean parameter that shows whether the task is a subtask or not.
title The title of the task that has been updated.
comment The comment that has been added along with the time log.
origindate Timestamp of the event (no timezone applied ).
entrydate Timestamp of the event (timezone applied ).
Example request (Do not forget to send a valid header containing your API key): http://<subdomain>.kanbanize.com/index.php/api/kanbanize/log_time/taskid/68/time/673
back to top