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).


Quick recap of concepts in Kantree:


The next api version will use the new names


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


Some calls may return paginated results (notably listing cards on projects). Paginated results will contain the following headers:

Pass the page parameter to get the desired page. You can control how many items per page using per_page.


GET /projects/123/cards?page=2

Listing projects

Get your Champs:

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 beginning.

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 fields

Some fields 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 field.

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 fields:

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

You can also edit fields individually:

POST /cards/{card_id}/attributes/{field_name_or_id}
    "value": "my field value"

When dealing with fields with multiple values, you can use append or pop:

POST /cards/{card_id}/attributes/{field_name_or_id}/append
    "value": "my field value"

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

The format of the value depends on the type of field.

For files fields, there are multiple ways to set the value:

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


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


POST /cards/{card_id}/archive


DELETE /cards/{card_id}/archive

Delete a card

DELETE /cards/{card_id}