Importing data

Data must be provided in tabular form (spreadsheet). We support the following formats: XLSX, CSV, ODS.

Import data into an existing workspace

First upload your file:

$ curl -u "API_KEY:" https://kantree.io/api/1.0/importers/spreadsheet/discover -F file=@your_file.xlsx

Note down the file_id from the response.

Now import this file into your project:

$ curl -u "API_KEY:" https://kantree.io/api/1.0/importers/spreadsheet/import -H "Content-type: application/json" -d '
{
    "discover_file_id": FILE_ID_FROM_FIRST_API_CALL,
    "project_id": PROJECT_ID,
    "mapping": {
        # ... see Mapping your data section
    },
}
'

The following additional parameters are available:

• update_field: the field from the mapping to use to match existing card. If provided, cards matching the field value will be updated.
• update_only: a boolean indicating whether to ignore lines that do not match an existing card.
• options: additional options:
  • ignore_header: boolean indicating whether to ignore first row

Create a new workspace from a spreadsheet

Creating a workspace is similar to importing data to an existing one. API calls are the same but instead of providing a project_id to the second call, you must provide a title and any other parameters used by the create_project api call.

Example:

$ curl -u "API_KEY:" https://kantree.io/api/1.0/importers/spreadsheet/import -H "Content-type: application/json" -d '
{
    "discover_file_id": FILE_ID_FROM_FIRST_API_CALL
    "title": "My new workspace",
    "mapping": {
        # ... see Mapping your data section
    }
}
'

Mapping your data

The mapping indicates how to handle the data from your file. Each column in your spreadsheet is assigned a number. You can see this in the response to the api call used to upload the file. A list of “fields” is provided.

You can then tell kantree what to do with each field. If a field is not mentionned, it will be ignored. A field mapping to the card title must be provided.

Example:

{
    "0": {"type": "title"},
    "1": {"type": "attribute", "attr_type": "text", "name": "My text field"},
    "2": {"type": "context", "name": "My context name"}
}

The possible mapping types are:

• title: map to the title
• attribute: map to an attribute. additional options:
  • attr_type: the type of the attribute
  • name: the name of the attribute.
• context: map to a context. additional options:
  • name: name of the context
• model: map to the name of a card model available in this project
• comment: add a new comment on the card
• children: add a new child card of the card, you can add multiple child cards at once with line breaks
• ref: map to the card ref. Can only be read to update current cards, cannot be edited.

If you are matching existing attributes/contexts, their name (and type) must match.

To see the available attribute types: GET /attribute-types

To list all fields in your project: GET /projects/PROJECT_ID/attributes.
Using “jq” to facilitate reading: $ curl -u "API_KEY:" https://kantree.io/api/1.0/projects/PROJECT_ID/attributes | jq '.[] | .name,.type'

Full example

Imagine a CSV file as follow:

title,description,due date,assignees,labels,lists
hello world,a lengthy description,2023-01-01,@username,"label1,label2",todo

Let’s import it in an existing project:

$ curl -u "API_KEY:" https://kantree.io/api/1.0/importers/spreadsheet/discover -F file=@data.csv
$ curl -u "API_KEY:" https://kantree.io/api/1.0/importers/spreadsheet/import -H "Content-type: application/json" -d '
{
    "discover_file_id": FILE_ID_FROM_FIRST_API_CALL,
    "project_id": PROJECT_ID,
    "mapping": {
        "0": {"type": "title"},
        "1": {"type": "attribute", "attr_type": "content", "name": "Description"},
        "2": {"type": "attribute", "attr_type": "date", "name": "Due date"},
        "3": {"type": "attribute", "attr_type": "group_type", "name": "Labels"},
        "4": {"type": "context", "name": "Lists"}
    },
    "options": {
        "ignore_header": true
    }
}
'