Forums/API
API Version 1.3
Kanbanery Support
posted this on August 09, 2011 17:17
Table of Contents
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.
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-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.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 |
| 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.jsonProjectMembership resource
Form hash param name: project_membership
ProjectMembership resource 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". |
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.jsonDeleting 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