Forums/API
Api Version 1.2
Kanbanery Support
posted this on March 25, 2011 15:01
Introduction to the Kanbanery API
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.
What is new in version 1.2?
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 or XML 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-ApiTokenHTTP headerThis is the recommended way. For example:
curl -H 'X-Kanbanery-ApiToken: API_TOKEN' https://WORKSPACE.kanbanery.com/SOME_PATH -
Add
api_token=API_TOKENto the parameters you send to the APIFor 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.xml
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 formats and statuses
Kanbanery API supports two response formats: JSON and XML. For every API call you need to specify in which format you want to receive response data. You can do this by appending ".json" or ".xml" to the request URL. If you don't specify any format the API will default to JSON format.
For "create" and "update" requests the response body contains resource data serialized in the requested format.
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 returns403 (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 the requested format (JSON or XML).
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
Managing tasks
Form hash param name: task
Task resources have following properties:
| Name | Type | Required? | Settable | Description |
|---|---|---|---|---|
| title | String | yes | on create and update | Title |
| task_type_id | Integer | yes | on create and update | Task type, ie. "Bug", "Story". Instead of setting this id you can just settask_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". Only for JSON responses. In XML responses node name is "task". |
List all tasks from project board
GET https://WORKSPACE.kanbanery.com/api/v1/projects/PROJECT_ID/tasks.json
List all tasks in column
GET https://WORKSPACE.kanbanery.com/api/v1/columns/COLUMN_ID/tasks.json
List all archived tasks
GET https://WORKSPACE.kanbanery.com/api/v1/projects/PROJECT_ID/archive/tasks.json
List all tasks in icebox
GET https://WORKSPACE.kanbanery.com/api/v1/projects/PROJECT_ID/icebox/tasks.json
Create task on project board
POST https://WORKSPACE.kanbanery.com/api/v1/projects/PROJECT_ID/tasks.json
Create task in icebox
POST https://WORKSPACE.kanbanery.com/api/v1/projects/PROJECT_ID/icebox/tasks.json
Get task
GET https://WORKSPACE.kanbanery.com/api/v1/tasks/TASK_ID.json
Update 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
Delete task
DELETE https://WORKSPACE.kanbanery.com/api/v1/tasks/TASK_ID.json
Archive 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.
Managing task subscriptions
TaskSubscription resources have following 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". Only for JSON responses. In XML responses node name is "task_subscription". |
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.
Create task subscription
POST https://WORKSPACE.kanbanery.com/api/v1/tasks/TASK_ID/subscription.json
Get task subscription (check for existence)
GET https://WORKSPACE.kanbanery.com/api/v1/tasks/TASK_ID/subscription.jsonDelete task subscription
DELETE https://WORKSPACE.kanbanery.com/api/v1/tasks/TASK_ID/subscription.json
Managing columns
Form hash param name: column
Column resources have following 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". Only for JSON responses. In XML responses node name is "column". |
List columns
GET https://WORKSPACE.kanbanery.com/api/v1/projects/PROJECT_ID/columns.json
Create column
POST https://WORKSPACE.kanbanery.com/api/v1/projects/PROJECT_ID/columns.json
Get column
GET https://WORKSPACE.kanbanery.com/api/v1/columns/COLUMN_ID.json
Update column
PUT https://WORKSPACE.kanbanery.com/api/v1/columns/COLUMN_ID.json
Delete 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
Managing task comments
Form hash param name: comment
Comment resources have following 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 |  |
List comments
GET https://WORKSPACE.kanbanery.com/api/v1/tasks/TASK_ID/comments.json
Create comment
POST https://WORKSPACE.kanbanery.com/api/v1/tasks/TASK_ID/comments.json
Get comment
GET https://WORKSPACE.kanbanery.com/api/v1/comments/COMMENT_ID.json
Delete comment
DELETE https://WORKSPACE.kanbanery.com/api/v1/comments/COMMENT_ID.json
Managing subtasks
Form hash param name: subtask
Subtask resources have following 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". Only for JSON responses. In XML responses node name is "subtask". |
List subtasks
GET https://WORKSPACE.kanbanery.com/api/v1/tasks/TASK_ID/subtasks.json
Create subtask
POST https://WORKSPACE.kanbanery.com/api/v1/tasks/TASK_ID/subtasks.json
Get subtask
GET https://WORKSPACE.kanbanery.com/api/v1/subtasks/SUBTASK_ID.json
Update subtask
PUT https://WORKSPACE.kanbanery.com/api/v1/subtasks/SUBTASK_ID.json
Delete subtask
DELETE https://WORKSPACE.kanbanery.com/api/v1/subtasks/SUBTASK_ID.json
Managing issues
Form hash param name: issue
Issue resources have following 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". Only for JSON responses. In XML responses node name is "issue". |
List issues
GET https://WORKSPACE.kanbanery.com/api/v1/tasks/TASK_ID/issues.json
Create issue
POST https://WORKSPACE.kanbanery.com/api/v1/tasks/TASK_ID/issues.json
Get issue
GET https://WORKSPACE.kanbanery.com/api/v1/issues/ISSUE_ID.json
Update issue
PUT https://WORKSPACE.kanbanery.com/api/v1/issues/ISSUE_ID.json
Delete issue
DELETE https://WORKSPACE.kanbanery.com/api/v1/issues/ISSUE_ID.json
Managing Project Memberships
Form hash param name: project_membership
ProjectMembership resources have following properties:
| Name | Type | Required? | Settable | Description |
|---|---|---|---|---|
| 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". Only for JSON responses. In XML responses node name is "project_memberships". |
List project memberships
GET https://WORKSPACE.kanbanery.com/api/v1/project/PROJECT_ID/memberships.json
Create project memberships
POST https://WORKSPACE.kanbanery.com/api/v1/project/PROJECT_ID/memberships.json
Get project membership
GET https://WORKSPACE.kanbanery.com/api/v1/project/PROJECT_ID/memberships/PROJECT_MEMBERSHIP_ID.json
Update project membership
note: Only field permission can be updated.
PUT https://WORKSPACE.kanbanery.com/api/v1/project/PROJECT_ID/memberships/PROJECT_MEMBERSHIP_ID.json
Delete project membership
DELETE https://WORKSPACE.kanbanery.com/api/v1/project/PROJECT_ID/memberships/PROJECT_MEMBERSHIP_ID.json
Reading task types
Form hash param name: task_type
TaskType resources have following 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". Only for JSON responses. In XML responses node name is "task_type". |
List project's task types
GET https://WORKSPACE.kanbanery.com/api/v1/projects/PROJECT_ID/task_types.json
Get task type
GET https://WORKSPACE.kanbanery.com/api/v1/task_types/TASK_TYPE_ID.json
Reading estimates
Form hash param name: estimate
Estimate resources have following 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". Only for JSON responses. In XML responses node name is "estimate". |
List project's estimates
GET https://WORKSPACE.kanbanery.com/api/v1/projects/PROJECT_ID/estimates.json
Get estimate
GET https://WORKSPACE.kanbanery.com/api/v1/estimates/ESTIMATE_ID.json
Reading user information
User resources have following properties:
| Name | Type | Description |
|---|---|---|
| api_token | String | User Token |
| String | User email | |
| first_name | String | User first name |
| last_name | String | User last name |
| gravatar_url | String | 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". Only for JSON responses. In XML responses node name is "user". |
Get current user (the API TOKEN owner) information
GET https://WORKSPACE.kanbanery.com/api/v1/user.json
Get project users information
GET https://WORKSPACE.kanbanery.com/api/v1/projects/PROJECT_ID/users.json
Reading Workspaces and Projects
Workspace resources have following 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". Only for JSON responses. In XML responses node name is "workspace". |
Project resources have following 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". Only for JSON responses. In XML responses node name is "project". |
List Workspaces with Projects
GET https://kanbanery.com/api/v1/user/workspaces.json