API guide

Browse the full API reference in our API browser.

API endpoint

The base URL for all API calls is: https://kantree.io/api/1.0

If you are a Kantree Enterprise customer, you will need to use your own domain (eg: https://acme.kantree.io/api/1.0).

Concepts

Quick recap of concepts in Kantree:

Authorization

At the moment only API key authentification is available. We are working on adding OAuth 2.0.

Obtain a token from https://kantree.io/account#developer.

Authentification should be made using HTTP Basic Authorization and the api key should be used as the username, leaving the password blank.

$ curl -u "my-api-key:" https://kantree.io/api/1.0/me

Listing projects

Get your organizations:

GET /organizations

Get the list of projects in the org.:

GET /organizations/{org_id}/projects

List cards in your project

List all the cards in your project (across all the hierarchy):

 GET /projects/{project_id}/cards

The results are paginated. See the pagination section at the end.

This call can take a few parameters:

Getting a card details

Get a card details:

 GET /cards/{card_id}

Get the stream of a card (comments, activities, logs):

 GET /cards/{card_id}/stream

Get the children of a card:

 GET /cards/{card_id}/children

Creating cards

First you will need to determine the parent of the future card. It can be the top level card (you will find the top_level_card_id property on the project object) or any card in the project.

POST /cards/{parent_id}/children
{
    "title": "my new card title",
    "attributes": {"Due Date": "2018-01-01"},
    "group_id": 111
}

About attributes

Some attributes can have values only from a list of available choices. To list the choices:

GET /cards/{card_id}/attributes/{attr_id}/choices

Which returns a list of tuples in the form of (value, label). Use the value to set the attribute.

Updating a card

To update the card title:

PUT /cards/{card_id}
{
    "title": "new card title"
}

To change the state of the card:

PUT /cards/{card_id}
{
    "state": "completed"
}

Available states: undecided, dropped, accepted, in_progress, waiting, completed, closed.

To update attributes:

POST /cards/{card_id}/attributes
{
    "Description": "my description"
}

Warning: attributes of type “group_type” cannot be modified through this operation. You will need to use the grouping system as explained below. When an attribute is of type “group_type”, it includes a group_type_id property.

Moving cards between groups

Listing available groups

List all available group types:

GET /projects/{project_id}/group-types

To list available groups for a card, you must use its parent’s id:

GET /cards/{parent_id}/groups

Possible parameter:

Moving the card

POST /cards/{card_id}/relocate
{
    "parent_id": 111,
    "group_id": 222,
    "position": 1
}

Parameters:

Adding cards to multiple groups of the same type

If the group type allows it, you can add a card to multiple groups of the same group type.

POST /cards/{card_id}/add-to-group
{
    "group_id": 111
    "position": 1
}

Remove from a group:

POST /cards/{card_id}/remove-from-group
{
    "group_id": 111
}

Remove from all groups of a type:

POST /cards/{card_id}/remove-from-group-type
{
    "type_id": 111
}

Associating a card to a model

To associate:

POST /cards/{card_id}/model
{
    "model_id": 111
}

To deassociate:

POST /cards/{card_id}/model
{
    "model_id": null
}

Removing a card

Archive and restore

Archive:

POST /cards/{card_id}/archive

Restore:

DELETE /cards/{card_id}/archive

Delete a card

DELETE /cards/{card_id}