Welcome, Guest Login

Support Center

API Version 1.3

Last Updated: Jan 22, 2015 03:53PM CET

What is this API?

We've created the Kanbanery API to allow you to easily integrate your systems and applications with Kanbanery. With this API you can manage your resources like a project's tasks, columns, task comments/subtasks/issues and more.

How does it work?

The Kanbanery API is implemented as a REST interface for the resources mentioned above. If you're not familiar with REST see more information about REST.

Basically, to get or update something in your project(s) you'll make an HTTP request with some data and receive JSON data in the response. Different API calls use different HTTP verbs like GET, POST, PUT and DELETE.

Before you start implementing your integration with Kanbanery you can get familiar with our API and its responses by using the curl command in your shell:

curl -H 'X-Kanbanery-ApiToken: API_TOKEN' https://WORKSPACE.kanbanery.com/api/v1/SOME_PATH curl -H 'X-Kanbanery-ApiToken: API_TOKEN' -X PUT -d OBJECT[ATTRIBUTE]=VALUE https://WORKSPACE.kanbanery.com/api/v1/SOME_PATH curl -H 'X-Kanbanery-ApiToken: API_TOKEN' -X DELETE https://WORKSPACE.kanbanery.com/api/v1/SOME_PATH 

If your library or client system allows you to send only GET and POST requests you can simulate PUT and DELETE requests by making POST request with an additional _method parameter. For example:

curl -H 'X-Kanbanery-ApiToken: API_TOKEN' -X POST -d _method=put -d OBJECT[ATTRIBUTE]=VALUE https://WORKSPACE.kanbanery.com/api/v1/SOME_PATH 

What do I need the API for?

You can do many things with the Kanbanery API. Possibilities are unlimited and here a few ideas for you:

  • You can build a custom Kanbanery client for your favourite smartphone or system platform (or even a desktop GUI app!),
  • Your SCM post-commit hooks can automatically resolve an issue assigned to some task when a commit message matches the issue or even move this task to the next column,
  • Your server monitoring scripts can automatically add a task to remind you about some sysadmin work.

Basics

Authentication

In Kanbanery every user already has their own, unique API token. The token is just a string containing alphanumerical characters. If you use your project's RSS feed for monitoring what's happening in the project you already use this token.

In order to use the Kanbanery API you need to know your API token. You can find it under the "API Token" tab on your user account settings page or you can use basic authentication for retrive user information, where you would find api_token.

Once you know your token you can use it to authenticate your requests. There are 2 ways to do this:

  • Set X-Kanbanery-ApiToken HTTP header

    This is the recommended way. For example:

     curl -H 'X-Kanbanery-ApiToken: API_TOKEN' https://WORKSPACE.kanbanery.com/SOME_PATH 
  • Add api_token=API_TOKEN to the parameters you send to the API

    For example:

     curl https://WORKSPACE.kanbanery.com/SOME_PATH?api_token=API_TOKEN 

Note, when you use our API we identify your user account by this token. In other words, all API activity will be seen as your activity and other project members will see you as the author of any changes.

Basic HTTP Authentication

For example:

 curl -u "email:password" https://kanbanery.com/api/v1/RESOURCE 

Note, this method is not recommended, but it can be used for getting api_token from user resource.

Permissions

As mentioned in the previous section, API calls are made on behalf of one of your project members. This means that the role of this member is being checked when you make API calls. Roles define what you can do and what you cannot do. Currently there are 3 roles in Kanbanery: project viewer (read only user), project member and project manager. You can change a user's role in a specific project on the "Project members" page.

Note that if your paying plan allows you to add one more additional members to the project then you can dedicate this new user account for your API needs. Just set its name to "API", "R2D2", "C3PO" or whatever you want and assign it some nice avatar (at gravatar.com) to distinguish it from "real" users on the board.

URL - Protocol, domain and path

Here is an example of the URL for getting column information:

https://WORKSPACE.kanbanery.com/api/v1/columns/COLUMN_ID.json 

First, the protocol. Kanbanery uses a secure http connection (https) for almost everything to keep your project data safe from sniffing. Thus you should use https protocol for all API calls.

Second, the domain. All API calls should be using your workspace's subdomain in kanbanery.com. In the above example your workspace's domain is WORKSPACE.kanbanery.com. To find it, just open your browser and go to your project's Kanban board - the domain shown in your browser's location bar is the one you should use.

Third, the path. All paths should start with /api/v1, as this is the first and only version of our API for now. When we decide to change the API in future and its release includes non-backwards compatible changes we'll put it at /api/v2. This way, your clients (read: systems and applications integrated with Kanbanery) will still work and you'll have time to update them to use the new API. The rest of the path describes names and identifiers of resources you want to act on.

All resources available in Kanbanery API are described in detail in following sections of this document.

Response format and statuses

Kanbanery API supports one response format: JSON. Specifying the format by appending the ".json" to the request URL is optional.

For "create" and "update" requests the response body contains resource data serialized in JSON.

If the request succeeds the returned status will be 200 (OK), except for requests that create resources, for which the status will be 201 (Created).

If the API token is invalid or is missing the API returns 401 (Unauthorized) HTTP status.

If the role assigned to user accessing the API doesn't allow them to perform the requested action upon the requested resource the API returns 403 (Forbidden) HTTP status.

If you're trying to create or modify any resource and some parameters have invalid values or some required parameters are missing the API returns 422 (Unprocessable entity) HTTP status and error description in JSON.

If a resource removal (DELETE) request fails for some reason the API will return 409 (Conflict) HTTP status.

Request data format

When creating or updating resources through our API you need to specify resource attributes as form-encoded data. These attributes should be put inside a hash map that should be named after resource. For example, to update task title and position the data should look like this:

task[title]=TITLE&task[position]=POSITION 

You can set these attributes with CURL this way:

curl -H 'X-Kanbanery-ApiToken: API_TOKEN' -d task[title]=TITLE -d task[position]=POSITION https://WORKSPACE.kanbanery.com/api/v1/tasks/TASK_ID.json 

User resource

User resource properties

Name Type Description
api_token String User API Token
email String User email
first_name String User first name
last_name String User last name
gravatar_url String URL of user's avatar (at gravatar.com)
created_at DateTime Creation time
updated_at DateTime Last update time
type String Type of this resource, set to "User".

Getting the current user (the API TOKEN owner) information

GET https://WORKSPACE.kanbanery.com/api/v1/user.json 

Getting project users information

GET https://WORKSPACE.kanbanery.com/api/v1/projects/PROJECT_ID/users.json 

Workspace and Project resources

Workspace resource properties

Name Type Description
id Integer Workspace id
name String Workspace name
projects Array Array of Project resources accessible by user
created_at DateTime Creation time
updated_at DateTime Last update time
type String Type of this resource, set to "Workspace".

Project resource properties

Name Type Description
id Integer Project id
name String Project name
url String Full URL to the project
created_at DateTime Creation time
updated_at DateTime Last update time
type String Type of this resource, set to "Project".

Listing workspaces with projects

GET https://kanbanery.com/api/v1/user/workspaces.json

ProjectMembership resource

Form hash param name: project_membership

ProjectMembership resource properties

Name Type Required? Settable Description
email String yes on create  User email
permission String yes on create and update One of permission types: [ manager, member, viewer ]
project_id Integer no   Project id
user_id Integer no   User id
created_at DateTime no   Creation time
updated_at DateTime no   Last update time
type String no   Type of this resource, set to "ProjectMembership".

Listing project memberships

GET https://WORKSPACE.kanbanery.com/api/v1/projects/PROJECT_ID/memberships.json 

Creating a project membership

POST https://WORKSPACE.kanbanery.com/api/v1/projects/PROJECT_ID/memberships.json 

Getting a project membership

GET https://WORKSPACE.kanbanery.com/api/v1/projects/PROJECT_ID/memberships/PROJECT_MEMBERSHIP_ID.json 

Updating a project membership

note: Only field permission can be updated.

PUT https://WORKSPACE.kanbanery.com/api/v1/projects/PROJECT_ID/memberships/PROJECT_MEMBERSHIP_ID.json 

Deleting a project membership

DELETE https://WORKSPACE.kanbanery.com/api/v1/projects/PROJECT_ID/memberships/PROJECT_MEMBERSHIP_ID.json 

TaskType resource

Form hash param name: task_type

TaskType resource properties

Name Type Description
name String Name
color_code Integer Color code
project_id Integer Project to which the task type is assigned
position Integer Position in project's task types list, 1-based
created_at DateTime Creation time
updated_at DateTime Last update time
type String Type of this resource, set to "TaskType".

Listing project's task types

GET https://WORKSPACE.kanbanery.com/api/v1/projects/PROJECT_ID/task_types.json 

Getting a task type

GET https://WORKSPACE.kanbanery.com/api/v1/task_types/TASK_TYPE_ID.json 

Estimate resource

Form hash param name: estimate

Estimate resource properties

Name Type Description
value BigDecimal Numeric value
label String Label to display
project_id Integer Project to which the task type is assigned
created_at DateTime Creation time
updated_at DateTime Last update time
type String Type of this resource, set to "Estimate".

Listing project's estimates

GET https://WORKSPACE.kanbanery.com/api/v1/projects/PROJECT_ID/estimates.json 

Getting an estimate

GET https://WORKSPACE.kanbanery.com/api/v1/estimates/ESTIMATE_ID.json 

Column resource

Form hash param name: column

Column resource properties

Name Type Required? Settable Description
name String yes on create and update Name
project_id Integer no   Project
fixed Boolean no   If column can be moved
capacity Integer no on create and update Capacity (WIP limit)
position Integer no on create and update Position on the board, 1-based
created_at DateTime no   Creation time
updated_at DateTime no   Last update time
type String no   Type of this resource, set to "Column".

Listing a project's columns

GET https://WORKSPACE.kanbanery.com/api/v1/projects/PROJECT_ID/columns.json 

Creating a column

POST https://WORKSPACE.kanbanery.com/api/v1/projects/PROJECT_ID/columns.json 

Getting a column

GET https://WORKSPACE.kanbanery.com/api/v1/columns/COLUMN_ID.json 

Updating a column

PUT https://WORKSPACE.kanbanery.com/api/v1/columns/COLUMN_ID.json 

Deleting column

DELETE https://WORKSPACE.kanbanery.com/api/v1/columns/COLUMN_ID.json 

The column must not contain any tasks (must be empty) in order to be removable. You need to delete all of a column's tasks or move them to another column before you can delete a column. If you want to remove a column and move its tasks to other column at once just settask[column_id] parameter to id of column to which tasks should be sent to. For example:

curl -H 'X-Kanbanery-ApiToken: API_TOKEN' -X DELETE -d task[column_id]=COLUMN_ID https://WORKSPACE.kanbanery.com/api/v1/columns/COLUMN_ID.json 

Task resource

Form hash param name: task

Task resource properties

Name Type Required? Settable Description
title String yes on create and update Title
task_type_id Integer no on create and update Task type, ie. "Bug", "Story". Instead of setting this id you can just set task_type_name to "Bug"
column_id Integer no on update Column
creator_id Integer no   Who created it
description String no on create and update Description
estimate_id Integer no on create and update Estimate
owner_id Integer no   Who is currently assigned to it
position Integer no on create and update Position in column, 1-based
priority Integer no on create and update Priority (0, 1 or 2)
ready_to_pull Boolean no on create and update If task is ready to be pulled
blocked Boolean no   If task is blocked by other task(s)
moved_at DateTime no   When task was moved to current column
created_at DateTime no   Creation time
updated_at DateTime no   Last update time
type String no   Type of this resource, set to "Task".

Listing all tasks from a project board

GET https://WORKSPACE.kanbanery.com/api/v1/projects/PROJECT_ID/tasks.json 

Listing all tasks in a column

GET https://WORKSPACE.kanbanery.com/api/v1/columns/COLUMN_ID/tasks.json 

Listing all archived tasks

GET https://WORKSPACE.kanbanery.com/api/v1/projects/PROJECT_ID/archive/tasks.json 

Listing all tasks in an icebox

GET https://WORKSPACE.kanbanery.com/api/v1/projects/PROJECT_ID/icebox/tasks.json 

Creating a task on a project board

POST https://WORKSPACE.kanbanery.com/api/v1/projects/PROJECT_ID/tasks.json 

Creating a task in an icebox

POST https://WORKSPACE.kanbanery.com/api/v1/projects/PROJECT_ID/icebox/tasks.json 

Getting a task

GET https://WORKSPACE.kanbanery.com/api/v1/tasks/TASK_ID.json 

Updating a task

PUT https://WORKSPACE.kanbanery.com/api/v1/tasks/TASK_ID.json 

You can set additional task[location] attribute to:

  • archive - to move this task to project's archive (if it's in the last column),
  • icebox - to move this task to project's icebox (if it's in the first column),
  • board - to move this task back to project board (if it's in icebox or archive),
  • next_column - to move this task to next column,
  • prev_column - to move this task to previous column

Deleting a task

DELETE https://WORKSPACE.kanbanery.com/api/v1/tasks/TASK_ID.json 

Archiving all "done" (last column) tasks

PUT https://WORKSPACE.kanbanery.com/api/v1/projects/PROJECT_ID/columns/last/tasks.json 

You must set task[location] attribute to archive. Response body of this request contains list of all tasks that have been moved from last column to project's archive.

TaskSearch resource

Form hash param name: task_search

TaskSearch resource properties

Name Type Required? Settable Description
phrase String yes if task_type_id and owner_id are not set on create Search phrase
task_type_id Integer yes if phrase and owner_id are not set on create If set, it narrows the search result to tasks of given task type
owner_id Integer yes if phrase and task_type_id are not set on create If set, it narrows the search result to tasks owned by given user
project_id Integer no   ID of a project to search in
scope String no   A place within the project to search in (can be 'icebox', 'board' or 'archive')
tasks Array of task JSON items no   Found tasks
created_at DateTime no   Creation time
type String no   Type of this resource, set to "TaskSearch".

Searching for a task in an icebox

POST https://WORKSPACE.kanbanery.com/api/v1/projects/PROJECT_ID/icebox/tasks/search.json 

Searching for a task on a board

POST https://WORKSPACE.kanbanery.com/api/v1/projects/PROJECT_ID/board/tasks/search.json 

Searching for a task in an archive

POST https://WORKSPACE.kanbanery.com/api/v1/projects/PROJECT_ID/archive/tasks/search.json 

TaskSubscription resource

TaskSubscription resource properties

Name Type Required? Settable Description
task_id Integer no   The task
user_id Integer no   User subscribed
created_at DateTime no   Creation time
updated_at DateTime no   Last update time
type String no   Type of this resource, set to "TaskSubscription".

None of the above properties are directly settable. When creating a subscription, task_id is taken from the URL and user_id is the id of API_TOKEN owner.

Creating a task subscription

POST https://WORKSPACE.kanbanery.com/api/v1/tasks/TASK_ID/subscription.json 

Getting a task subscription (check for existence)

GET https://WORKSPACE.kanbanery.com/api/v1/tasks/TASK_ID/subscription.json

Deleting a task subscription

DELETE https://WORKSPACE.kanbanery.com/api/v1/tasks/TASK_ID/subscription.json 
 

Comment resource

Form hash param name: comment

Comment resource properties

Name Type Required? Settable Description
body String yes on create Comment text
task_id Integer no   Task
author_id Integer no   Author id
created_at DateTime no   Creation time
updated_at DateTime no   Last update time
type String no    

Listing a task's comments

GET https://WORKSPACE.kanbanery.com/api/v1/tasks/TASK_ID/comments.json 

Creating a comment

POST https://WORKSPACE.kanbanery.com/api/v1/tasks/TASK_ID/comments.json 

Getting a comment

GET https://WORKSPACE.kanbanery.com/api/v1/comments/COMMENT_ID.json 

Deleting a comment

DELETE https://WORKSPACE.kanbanery.com/api/v1/comments/COMMENT_ID.json 

Subtask resource

Form hash param name: subtask

Subtask resource properties

Name Type Required? Settable Description
body String yes on create and update Short description
task_id Integer no   Task
creator_id Integer no   Who created it
completed Boolean no on create and update If it was completed
created_at DateTime no   Creation time
updated_at DateTime no   Last update time
type String no   Type of this resource, set to "Subtask".

Listing a task's subtasks

GET https://WORKSPACE.kanbanery.com/api/v1/tasks/TASK_ID/subtasks.json 

Creating a subtask

POST https://WORKSPACE.kanbanery.com/api/v1/tasks/TASK_ID/subtasks.json 

Getting a subtask

GET https://WORKSPACE.kanbanery.com/api/v1/subtasks/SUBTASK_ID.json 

Updating a subtask

PUT https://WORKSPACE.kanbanery.com/api/v1/subtasks/SUBTASK_ID.json 

Deleting a subtask

DELETE https://WORKSPACE.kanbanery.com/api/v1/subtasks/SUBTASK_ID.json 

Issue resource

Form hash param name: issue

Issue resource properties

Name Type Required? Settable Description
url String yes on create and update URL pointing to the issue in an external bug-tracking system
task_id Integer no   Task
resolved Boolean no on create and update If it was already resolved
created_at DateTime no   Creation time
updated_at DateTime no   Last update time
type String no   Type of this resource, set to "Issue".

Listing a task's issues

GET https://WORKSPACE.kanbanery.com/api/v1/tasks/TASK_ID/issues.json 

Creating an issue

POST https://WORKSPACE.kanbanery.com/api/v1/tasks/TASK_ID/issues.json 

Getting an issue

GET https://WORKSPACE.kanbanery.com/api/v1/issues/ISSUE_ID.json 

Updating an issue

PUT https://WORKSPACE.kanbanery.com/api/v1/issues/ISSUE_ID.json 

Deleting an issue

DELETE https://WORKSPACE.kanbanery.com/api/v1/issues/ISSUE_ID.json 

Blocking resource

Form hash param name: blocking

Blocking resource properties

Name Type Required? Settable Description
blocking_task_id Integer yes if blocking_message is empty on create ID of the task that blocks
blocking_message String yes if blocking_task_id is not set on create Blocking message (present when blocking_task_id is not set)
task_id Integer no   ID of the task that is blocked
created_at DateTime no   Creation time
updated_at DateTime no   Last update time
type String no   Type of this resource, set to "Blocking"

Listing a task's blockings

GET https://WORKSPACE.kanbanery.com/api/v1/tasks/TASK_ID/blockings.json 

Creating a blocking

POST https://WORKSPACE.kanbanery.com/api/v1/tasks/TASK_ID/blockings.json 

Getting a blocking

GET https://WORKSPACE.kanbanery.com/api/v1/blockings/BLOCKING_ID.json 

Deleting a blocking

DELETE https://WORKSPACE.kanbanery.com/api/v1/blockings/BLOCKING_ID.json 

[AddOns][Custom Fields] Project Field resource

Project fields are custom fields assigned to project.
Form hash param name: project_field
 

Project Field resource properties

Name Type Required? Settable Description
title String yes on create and update Title of the project field
field_type String yes on create Type. One of: user/text/date/dropdown
project_id Integer no   Project ID
created_at DateTime no   Creation time
updated_at DateTime no   Last update time
position Integer no   Project Field's position
type String no   Type of this resource, set to "ProjectField"

Listing a project's project fields

GET https://WORKSPACE.kanbanery.com/api/v1/projects/PROJECT_ID/addons/project_fields.json 

Creating a project field

POST https://WORKSPACE.kanbanery.com/api/v1/projects/PROJECT_ID/addons/project_fields.json 

Getting a project field

GET https://WORKSPACE.kanbanery.com/api/v1/addons/project_fields/PROJECT_FIELD_ID.json 

Updating a project field

PUT https://WORKSPACE.kanbanery.com/api/v1/addons/project_fields/PROJECT_FIELD_ID.json 

Deleting a project field

DELETE https://WORKSPACE.kanbanery.com/api/v1/addons/project_fields/PROJECT_FIELD_ID.json 

[AddOns][Custom Fields] Task Field resource

Task fields are values of a project field in a specific task.
Form hash param name: task
_field
 

Task Field resource properties

Name Type Required? Settable Description
value String yes if parent Project Field's type is text or date on create and update Value of the task field
project_field_id Integer yes on create ID of the parent Project Field resource
task_id Integer yes on create ID of the parent Task resource
user_id Integer yes if parent Project Field's type is user on create and update ID of the selected User
value_field_id Integer yes if parent Project Field's type is dropdown on create and update ID of the selected Value Field
created_at DateTime no   Creation time
updated_at DateTime no   Last update time
type String no   Type of this resource, set to "TaskField"

Listing a task's task fields

GET https://WORKSPACE.kanbanery.com/api/v1/tasks/TASK_ID/addons/task_fields.json 

Creating a task field

POST https://WORKSPACE.kanbanery.com/api/v1/tasks/TASK_ID/addons/task_fields.json 

Getting a task field

GET https://WORKSPACE.kanbanery.com/api/v1/addons/task_fields/TASK_FIELD_ID.json 

Updating a task field

PUT https://WORKSPACE.kanbanery.com/api/v1/addons/task_fields/TASK_FIELD_ID.json 

Deleting a task field

DELETE https://WORKSPACE.kanbanery.com/api/v1/addons/task_fields/TASK_FIELD_ID.json 

[AddOns][Custom Fields] Value Field resource

Value fields are dropdown options to choose from dropdown-type project fields.
Form hash param name: value
_field
 

Task Field resource properties

Name Type Required? Settable Description
value String yes if parent Project Field's type is text or date on create and update FIeld's value
project_field_id Integer yes on create ID of the parent Project Field resource
created_at DateTime no   Creation time
updated_at DateTime no   Last update time
position Integer no   Value Field's position
type String no   Type of this resource, set to "ValueField"

Listing a project field's value fields

GET https://WORKSPACE.kanbanery.com/api/v1/addons/project_fields/PROJECT_FIELD_ID/value_fields.json 

Creating a value field

POST https://WORKSPACE.kanbanery.com/api/v1/addons/project_fields/PROJECT_FIELD_ID/value_fields.json 

Getting a value field

GET https://WORKSPACE.kanbanery.com/api/v1/addons/value_fields/VALUE_FIELD_ID.json 

Updating a value field

PUT https://WORKSPACE.kanbanery.com/api/v1/addons/value_fields/VALUE_FIELD_ID.json 

Deleting a value field

DELETE https://WORKSPACE.kanbanery.com/api/v1/addons/value_fields/VALUE_FIELD_ID.json 
​​

Contact Us

https://cdn.desk.com/
false
desk
Loading
seconds ago
a minute ago
minutes ago
an hour ago
hours ago
a day ago
days ago
about
false
Invalid characters found
/customer/en/portal/articles/autocomplete