MENU Navbar
cURL JavaScript (our SDK)
  • Introduction
  • Getting started
  • Accessing the API
  • Requests & Responses
  • Authentication
  • Working with Users
  • Working with Boards
  • Working with Tasks
  • Working with Subtasks
  • Working with Comments
  • Working with Attachments
  • Working with Time Trackers
  • Types Reference
  • Objects Reference
  • Definitions
  • Introduction

    Kanban Tool provides an API, which makes it extremely easy for any developer to integrate external systems with our platform - adding their own layer of awesomeness on the top of the Kanban Tool.

    Using the API, you can create your own useful plugins (created exactly to fit your needs), synchronize tasks with other platforms or even code a customized backup solution - anything you want!

    Getting started

    Obtaining your access token

    To interact with the API, you need to have a unique, personal access token, which is used to authenticate yourself within the API.

    To generate your access token, you should:

    1. Click on the My profile tab in the main menu:

      Step 1

    2. Click on the API access link:

      Step 2

    3. Click on the Enable API access button to generate a new token:

      Step 3

    4. Note down your newly generated token - you are going to need it soon:

      Step 4

    Accessing the API

    Using wrappers

    An example using our SDK:

    KT.init(YOUR_DOMAIN, YOUR_TOKEN).then(() => {
      console.log(
        KT.currentUser.get('name')
      );
    });
    
    // -- You can use KT.call to make simple REST API queries: //
    
    KT.call('GET', 'tasks/' + TASK_ID).then((response) => {
      console.log(response);
    });
    

    Instead of executing requests on your own, you can use our SDK library: https://kanbantool.com/assets/kanbantool-sdk.js

    It provides a fluent, modern interface, which allows you to easily communicate with our API, without worrying about the internals. You can learn more about it on the SDK documentation page.

    Using cURL

    An example using cURL:

    $ curl 'https://YOUR_DOMAIN.kanbantool.com/api/v3/users/current.json?access_token=YOUR_TOKEN'
    
    # or (whichever suits you best)
    
    $ curl 'https://YOUR_DOMAIN.kanbantool.com/api/v3/users/current.json' \
        -H 'Authorization: Bearer YOUR_TOKEN'
    

    cURL is a sophisticated library (and a command-line application) which lets you send HTTP requests directly from your command line - it is available out-of-the-box in many Linux distributions.

    If you are familiar with working in the console environment, you should have no trouble using cURL.

    Using your web browser

    An example using a web browser (enter the URL in the address bar):

    https://YOUR_DOMAIN.kanbantool.com/api/v3/users/current.json?access_token=YOUR_TOKEN
    

    Last but not least: you can fully interact with our API directly from your browser! No third-party software or any complex development tools are required.

    Using other tools

    There are also numerous other tools, which simplify the process of fiddling with our API - just to name a few:

    Requests & Responses

    Requests

    The Kanban Tool API is built with REST in mind, providing a simple, human-readable interface.

    Example requests

    DELETE /api/v3/some_action.json

    POST /api/v3/some_action.json

    The _m parameter

    In case you have problem with using RESTful verbs, you can always pass the _m parameter, which defines the method you want to call:

    GET /api/v3/some_action.json?_m=delete

    Responses

    The API supports returning data in json and jsonp formats. The response type is dependent on the extension you pass:

    GET /api/v3/some_action.json?parameter=value

    GET /api/v3/some_action.json?callback=myFunction&parameter=value

    Authentication

    Example code:

    KT.init(YOUR_DOMAIN, YOUR_TOKEN).then(() => {
       // code after a successful authentication 
    });
    
    # Using query parameter:
    
    $ curl 'https://YOUR_DOMAIN.kanbantool.com/api/v3/some_action.json?access_token=YOUR_TOKEN'
    
    # Using header:
    
    $ curl 'https://YOUR_DOMAIN.kanbantool.com/api/v3/some_action.json' \
        -H 'Authorization: Bearer YOUR_TOKEN'
    

    To use our API, you must first obtain your own access token - from now on we're going to assume you already have one.

    You can authenticate in two ways:

    1. By passing your token in the access_token query parameter (?access_token=YOUR_TOKEN),

    2. By passing your token in the Authentication header (Authentication: Bearer YOUR_TOKEN).

    Both ways return exactly the same responses - choice is a matter of preference or tools (some HTTP clients may forbid sending custom headers for example).

    Working with Users

    Fetching users

    This command returns information about given user.

    Request

    GET /api/v3/users/:user_id.json

    Response

    This command returns a user object.

    Errors

    Fetching current user

    Example code:

    // KT.currentUser is loaded automatically upon a call to KT.init(...)
    KT.onInit(() => {
      console.log(KT.currentUser);
    });
    
    KT.init(YOUR_DOMAIN, API_TOKEN);
    
    curl 'https://YOUR_DOMAIN.kanbantool.com/api/v3/users/current.json' \
      -H 'Authorization: ...'
    

    Example response:

    {
      "id": 1000,
      "version": 22,
      "name": "Jon Snow",
      "initials": "JS",
      "timezone": "Winterfell",
    
      /* ... */  
    }
    

    This command returns information about currently authenticated user.

    It is an equivalent of fetching the user, if you already know its id.

    Request

    GET /api/v3/users/current.json

    Response

    This command returns a user object.

    Errors

    This command usually does not fail.

    Working with Boards

    Listing accessible boards

    Example code:

    console.log(
        KT.currentUser.get('boards')
    );
    
    curl 'https://YOUR_DOMAIN.kanbantool.com/api/v3/users/current.json' \
      -H 'Authorization: ...'
    

    Example response:

    {
      /* ... */
    
      "boards": [
        {
          "id": 100000,
          "name": "First Board",
          "folder": null,
          "position": null,
          "last_activity_on": "2018-01-01",
    
          "permissions": [
            "create_tasks",
            "read_tasks",
            "update_tasks",
            "delete_tasks",
            "move_tasks"
          ]
        },
    
        {
          "id": 100001,
    
          /* ... */
        }
    
        /* ... */
      ],
    
      /* ... */
    }
    

    To list all boards user has access to, you should fetch the user and access its boards field.

    Fetching boards

    Example code:

    KT.boards.stub(BOARD_ID).preload().then((board) => {
        console.log(board);
    });
    
    curl 'https://YOUR_DOMAIN.kanbantool.com/api/v3/boards/:board_id/preload.json' \
      -H 'Authorization: ...'
    

    Example response:

    {
      "id": 100000,
      "version": 1,
      "external_id_sequence": 1,
      "account_id": 200000,
      "owner_id": 300000,
      "folder_id": null,
      "board_template_id": "personal_timedriven",
    
      "position": null,
      "name": "First Board",
      "description": "This is my first board.",
    
      "created_at": "2018-01-01T12:00:00.000+01:00",
      "updated_at": "2018-01-01T12:00:00.000+01:00",
      "settings_updated_at": "2018-01-01T12:00:00.000+01:00",
      "last_activity_on": "2018-01-01",
      "deleted_at": null,
    
      "swimlanes": [
        /* ... */
      ],
    
      "workflow_stages": [
        /* ... */
      ],
    
      "card_types": [
       /* ... */
      ],
    
      "collaborators": [
       /* ... */
      ],
    
      "stats": [
        /* ... */
      ],
    
      "card_template": {
        /* ... */
      },
    
      "settings": {
       /* ... */
      }
    }
    

    This command returns overall information about given board.

    Request

    GET /api/v3/boards/:board_id/preload.json

    Response

    This command returns a board object.

    Errors

    Fetching boards' details

    Example code:

    KT.boards.stub(BOARD_ID).load().then((board) => {
        console.log(board);
    });
    
    curl 'https://YOUR_DOMAIN.kanbantool.com/api/v3/boards/:board_id.json' \
      -H 'Authorization: ...'
    

    Example response:

    {
      "id": 100000,
      "version": 1,
      "external_id_sequence": 1,
      "account_id": 200000,
      "owner_id": 300000,
      "folder_id": null,
      "board_template_id": "personal_timedriven",
    
      "position": null,
      "name": "First Board",
      "description": "This is my first board.",
    
      "created_at": "2018-01-01T12:00:00.000+01:00",
      "updated_at": "2018-01-01T12:00:00.000+01:00",
      "settings_updated_at": "2018-01-01T12:00:00.000+01:00",
      "last_activity_on": "2018-01-01",
      "deleted_at": null,
    
      "swimlanes": [
        /* ... */
      ],
    
      "workflow_stages": [
        /* ... */
      ],
    
      "tasks": [
        /* ... */
      ],
    
      "card_types": [
        /* ... */
      ],
    
      "collaborators": [
        /* ... */
      ],
    
      "stats": [
        /* ... */
      ],
    
      "card_template": {
        /* ... */
      },
    
      "settings": {
        /* ... */
      }
    }
    

    This command returns detailed information about given board and its tasks.

    Request

    GET /api/v3/boards/:board_id.json

    Response

    This command returns a board object.

    Errors

    Listing boards' changelogs

    Example code:

    KT.boards.stub(BOARD_ID).load().then((board) => {
        console.log(
            board.get('changelogs')
        );
    });
    
    // -- or -- //
    
    KT.boards.load(BOARD_ID, (board) => {
        console.log(
            board.get('changelogs')
        );
    });
    
    curl 'https://YOUR_DOMAIN.kanbantool.com/api/v3/boards/:board_id/changelog.json' \
      -H 'X-KanbanToolToken: ...'
      -d 'before=100000000'
    

    Example response:

    [
      {
        "id": 10000000,
        "board_id": 100000,
        "board_version": 32,
        "workflow_stage_id": 200000,
        "swimlane_id": 300000,
        "user_id": null,
    
        "what": "cloned",
        "description": "'Do something' has recurred",
    
        "changed_object_id": 200000,
        "changed_object_type": "Task",
        "changed_object_version": 5,
    
        "created_at": "2018-01-01T12:00:00.000+01:00",
    
        "data": {
          "task_id": 200000,
          "task_name": "Do something",
          "task_external_id": "",
    
          "workflow_stage_id": 200000,
          "workflow_stage_name": "In progress",
    
          "swimlane_id": 300000,
          "swimlane_name": "Team A"
        },
      },
    
      {
        /* ... */
      },
    
      /* ... */
    ]
    

    This command returns a list of all the changelogs from given board.

    Request

    GET /api/v3/boards/:board_id/changelog.json

    Parameters

    This command accepts a JSON object with following fields:

    Parameter Type Required Description
    before integer Yes When present, returns only changelogs matching id <= :before.
    limit integer No Maximum number of items to return.

    Response

    This command returns a list of changelog objects.

    Errors

    Working with Tasks

    Listing board's tasks

    Example code:

    KT.boards.stub(BOARD_ID).load().then((board) => {
      console.log(
        board.tasks()
      );
    });
    
    // -- or -- //
    
    KT.boards.load(BOARD_ID, () => {
      console.log(
        KT.tasks.where({
            board_id: BOARD_ID,
        })
      );
    });
    
    curl 'https://YOUR_DOMAIN.kanbantool.com/api/v3/boards/:board_id.json' \
      -H 'Authorization: ...'
    

    Example response:

    {
      "id": 100000,
    
      /* ... */
    
      "name": "First board",
      "description": "This is my first board.",
    
      /* ... */
    
      "tasks": [
        {
          "id": 500000,
          "board_id": 100000,
          "workflow_stage_id": 200000,
    
          "position": 1,
          "name": "Make Mary a sandwich.",
          "description": null,
    
          "priority": 0,
          "tags": "",
          "recurring_schedule": null,
    
          "created_at": "2018-01-01T12:00:00.000+01:00",
          "updated_at": "2018-01-01T12:00:00.000+01:00",
          "deleted_at": null,
    
          "subtasks": [
            /* ... */
          ],
    
          /* ... */
        },
    
        {
          /* ... */
        },
    
        /* ... */
      ],
    }
    

    To list board's tasks, you should fetch the board's details and access its tasks field. To get archived tasks, you should use the task search endpoint and set the board_id and archived=1 parameters.

    Searching for tasks

    KT.call('GET', 'tasks/search', {
      q: YOUR_QUERY,
    });
    
    curl 'https://YOUR_DOMAIN.kanbantool.com/api/v3/tasks/search.json' \
      -H 'Authorization: ...'
    

    This command allows to search through all the tasks user has access to.

    Request

    GET /api/v3/tasks/search.json

    Parameters

    This command accepts a JSON object with following field:

    Parameter Type Required Description
    q string Yes Query used to filter tasks (see paragraph below for reference). Required, but may be an empty string.
    limit integer No Maximum number of items to return, or number of items per page if given.
    page integer No Page number. If set additional pagination info is returned together with results.
    board_id string No Comma separated list of board IDs to narrow the search to.
    archived integer No Set to 1 to search through archived tasks.

    Query filters

    Filter Example Description
    - any text Does a full-text search (by task names, their descriptions etc.).
    @ @xz Filters by task's assignee's initials.
    id id<=100000 Filters by tasks' ids.
    board_id board_id=100000 Filters by boards' ids.
    timers_total timers_total>2:15 Filters by sum of tasks' timers. 2:15 determines time (2 minutes & 15 seconds in this case).
    custom_field_3 custom_field_3=3735928559 Filters by tasks' custom fields.
    subtasks_count subtasks_count<5 Filters by number of subtasks.
    comments_count coments_count>3 Filters by number of comments.
    attachments_count attachments_count=2 Filters by number of attachments.
    is is=in_progress Filters by lane types. Available options: backlog_inventory, waiting, in_progress or done.
    type type=yellow Filters by card types.

    Response

    This command returns a list of task objects or an object consisting of pagination ({results_count,page,pages_count}) and results (array of task objects) if page parameter is set.

    Errors

    This command usually does not fail.

    Fetching tasks

    Example code:

    KT.tasks.stub(TASK_ID).preload().then((task) => {
      console.log(task);
    });
    
    // -- or -- //
    
    KT.tasks.preload(TASK_ID, (task) => {
      console.log(task);
    });
    
    // -- or -- //
    
    KT.call('GET', 'tasks/' + TASK_ID).then((response) => {
      console.log(response);
    });
    
    
    curl 'https://YOUR_DOMAIN.kanbantool.com/api/v3/tasks/:task_id/preload.json' \
      -H 'Authorization: ...'
    

    Example response:

    {
      "id": 500000,
      "board_id": 100000,
      "workflow_stage_id": 200000,
    
      "position": 1,
      "name": "Make Mary a sandwich.",
      "description": null,
    
      "priority": 0,
      "tags": "",
      "recurring_schedule": null,
    
      "created_at": "2018-01-01T12:00:00.000+01:00",
      "updated_at": "2018-01-01T12:00:00.000+01:00",
      "deleted_at": null,
    
      /* ... */
    },
    

    This command returns overall information about given task.

    Request

    GET /api/v3/tasks/:task_id/preload.json

    Response

    This command returns a task object.

    Errors

    Fetching tasks' details

    Example code:

    KT.tasks.stub(TASK_ID).load().then((task) => {
        console.log(task);
    });
    
    // -- or -- //
    
    KT.call('GET', 'tasks/' + TASK_ID).then((response) => {
      console.log(response);
    });
    
    curl 'https://YOUR_DOMAIN.kanbantool.com/api/v3/tasks/:task_id.json' \
      -H 'Authorization: ...'
    

    Example response:

    {
      "id": 500000,
      "board_id": 100000,
      "workflow_stage_id": 200000,
    
      "position": 1,
      "name": "Make Mary a sandwich.",
      "description": null,
    
      "priority": 0,
      "tags": "",
      "recurring_schedule": null,
    
      "created_at": "2018-01-01T12:00:00.000+01:00",
      "updated_at": "2018-01-01T12:00:00.000+01:00",
      "deleted_at": null,
    
      "search_tags": [
        /* ... */
      ],
    
      "collaborators": [
        /* ... */
      ],
    
      "comments": [
        /* ... */
      ],
    
      "subtasks": [
        /* ... */
      ],
    
      "attachments": [
        /* ... */
      ],
    
      "changelogs": [
        /* ... */
      ],
    
      "time_trackers": [
        /* ... */
      ]
    }
    

    This command returns detailed information about given task.

    Request

    GET /api/v3/tasks/:task_id.json

    Response

    This command returns a task object.

    Errors

    Creating tasks

    Example code:

    const task = KT.tasks.create({
        board_id: 100000,
        name: 'Make Mary a sandwich.'
    });
    
    console.log(task);
    
    curl 'https://YOUR_DOMAIN.kanbantool.com/api/v3/tasks.json' \
      -X 'POST' \
      -H 'Authorization: ...' \
      -d '{"task[board_id]": 100000, "task[name]": "Make Mary a sandwich."}'
    

    Example response:

    {
      "id": 500000,
      "board_id": 100000,
      "workflow_stage_id": 200000,
    
      "position": 1,
      "name": "Make Mary a sandwich.",
      "description": null,
    
      "priority": 0,
      "tags": "",
      "recurring_schedule": null,
    
      "created_at": "2018-01-01T12:00:00.000+01:00",
      "updated_at": "2018-01-01T12:00:00.000+01:00",
      "deleted_at": null,
    
      "search_tags": [
        /* ... */
      ],
    
      "collaborators": [
        /* ... */
      ],
    
      "comments": [
        /* ... */
      ],
    
      "subtasks": [
        /* ... */
      ],
    
      "attachments": [
        /* ... */
      ],
    
      "changelogs": [
        /* ... */
      ],
    
      "time_trackers": [
        /* ... */
      ]
    }
    

    This command creates a new task.

    Request

    POST /api/v3/tasks.json

    Parameters

    This command accepts task's data wrapped in a task array, e.g.: task[name]. The required parameters are task[name] and task[board_id].

    Unless specified with task[workflow_stage_id], task[swimlane_id] and task[card_type_id], new tasks will be created in the top-left cell using the default card type.

    Response

    This command returns a task object.

    Errors

    Additional options

    Parameter Description
    task[task_attachment_ids] Array of IDs of previously uploaded attachments which should be attached to this task.
    task[subtask_ids] Array of IDs of previously created subtasks which should be attached to this task.
    assert_has_unique_external_id If set, verifies that task with given external_id does not already exist on this board.

    Updating tasks

    Example code:

    const task = KT.tasks.stub(TASK_ID);
    
    task.set('name', 'Make Jenny a sandwich.');
    
    task.save().then(() => {
       console.log('Task has been updated.');
    });
    
    // -- you can also update many options at once: -- //
    
    task.save({
        name: 'Make Jenny a sandwich.',
        description: 'And do it now!',
    });
    
    // -- or use plain KT.call: -- //
    
    KT.call('PATCH', 'tasks/' + TASK_ID, {
      'task[name]': 'Make Jenny a sandwich.',
    }).then((response) => {
      console.log('Task has been updated.');
      console.log(response.task);
    });
    
    curl 'https://YOUR_DOMAIN.kanbantool.com/api/v3/tasks/:task_id.json' \
      -X 'PATCH' \
      -H 'Authorization: ...' \
      -d 'task[name]=Make Jenny a sandwich.'
      -d 'task[description]=And do it now!'
    

    Example response:

    {
      "id": 500000,
      "board_id": 100000,
      "workflow_stage_id": 200000,
    
      "position": 1,
      "name": "Make Jenny a sandwich.",
      "description": null,
    
      /* ... */
    
      "created_at": "2018-01-01T12:00:00.000+01:00",
      "updated_at": "2018-01-01T12:00:00.000+01:00",
      "deleted_at": null,
    
      /* ... */
    }
    

    This commands updates a task.

    Request

    PATCH /api/v3/tasks/:task_id.json

    Parameters

    This command accepts task's data wrapped in a task array, e.g.: task[name].

    Response

    This command returns a task object.

    Errors

    Archiving tasks

    Example code:

    KT.tasks
        .groupUpdate([TASK_ID], { _action: 'archive' })
        .then(() => {
            console.log('Task has been archived.');
        });
    
    curl 'https://YOUR_DOMAIN.kanbantool.com/api/v3/tasks/:task_id.json' \
      -X 'PATCH' \
      -H 'Authorization: ...' \
      -d '_action=archive'
    

    Example response:

    {
      "id": 500000,
      "board_id": 100000,
      "workflow_stage_id": 200000,
    
      "position": 1,
      "name": "Make Jenny a sandwich.",
      "description": null,
    
      /* ... */
    
      "created_at": "2018-01-01T12:00:00.000+01:00",
      "updated_at": "2018-01-01T12:00:00.000+01:00",
      "deleted_at": null,
    
      /* ... */
    }
    

    This command archives a task.

    Request

    PATCH /api/v3/tasks/:task_id.json

    Parameters

    This command accepts a JSON object with following field:

    Parameter Type Required Value
    _action string Yes archive

    Response

    This command returns a task object.

    Errors

    Unarchiving tasks

    Example code:

    KT.tasks
        .groupUpdate([TASK_ID], { _action: 'unarchive' })
        .then(() => {
            console.log('Task has been unarchived.');
        });
    
    curl 'https://YOUR_DOMAIN.kanbantool.com/api/v3/tasks/:task_id.json' \
      -X 'PATCH' \
      -H 'Authorization: ...' \
      -d '_action=unarchive'
    

    Example response:

    {
      "id": 500000,
      "board_id": 100000,
      "workflow_stage_id": 200000,
    
      "position": 1,
      "name": "Make Jenny a sandwich.",
      "description": null,
    
      /* ... */
    
      "created_at": "2018-01-01T12:00:00.000+01:00",
      "updated_at": "2018-01-01T12:00:00.000+01:00",
      "deleted_at": null,
    
      /* ... */
    }
    

    This command unarchives a task.

    Request

    PATCH /api/v3/tasks/:task_id.json

    Parameters

    This command accepts a JSON object with following field:

    Parameter Type Required Value
    _action string Yes unarchive

    Response

    This command returns a task object.

    Errors

    Deleting tasks

    Example code:

    KT.tasks
        .groupUpdate([TASK_ID], { _action: 'delete' })
        .then(() => {
            console.log('Task has been deleted.');
        });
    
    curl 'https://YOUR_DOMAIN.kanbantool.com/api/v3/tasks/:task_id.json' \
      -X 'PATCH' \
      -H 'Authorization: ...' \
      -d '_action=delete'
    

    Example response:

    {
      "id": 500000,
      "board_id": 100000,
      "workflow_stage_id": 200000,
    
      "position": 1,
      "name": "Make Jenny a sandwich.",
      "description": null,
    
      /* ... */
    
      "created_at": "2018-01-01T12:00:00.000+01:00",
      "updated_at": "2018-01-01T12:00:00.000+01:00",
      "deleted_at": "2018-01-01T12:00:00.000+01:00",
    
      /* ... */
    }
    

    This command deletes a task.

    Request

    PATCH /api/v3/tasks/:task_id.json

    Parameters

    This command accepts a JSON object with following field:

    Parameter Type Required Value
    _action string Yes delete

    Response

    This command returns a task object.

    Errors

    Restoring tasks

    Example code:

    KT.tasks
        .groupUpdate([TASK_ID], { _action: 'undelete' })
        .then(() => {
            console.log('Task has been restored.');
        });
    
    curl 'https://YOUR_DOMAIN.kanbantool.com/api/v3/tasks/:task_id.json' \
      -X 'PATCH' \
      -H 'Authorization: ...' \
      -d '_action=undelete'
    

    Example response:

    {
      "id": 500000,
      "board_id": 100000,
      "workflow_stage_id": 200000,
    
      "position": 1,
      "name": "Make Jenny a sandwich.",
      "description": null,
    
      /* ... */
    
      "created_at": "2018-01-01T12:00:00.000+01:00",
      "updated_at": "2018-01-01T12:00:00.000+01:00",
      "deleted_at": null,
    
      /* ... */
    }
    

    This command restores a task.

    Request

    PATCH /api/v3/tasks/:task_id.json

    Parameters

    This command accepts a JSON object with following field:

    Parameter Type Required Value
    _action string Yes undelete

    Response

    This command returns a task object.

    Errors

    Working with Subtasks

    Listing subtasks

    There's no endpoint dedicated only to listing subtasks - you should fetch the task's details and access its subtasks field.

    Creating subtasks

    Example code:

    const task = KT.tasks.stub(TASK_ID);
    
    const subtask = task.subtasks().create({
        name: 'Take out the bread.',
    });
    
    console.log(subtask);
    
    curl 'https://YOUR_DOMAIN.kanbantool.com/api/v3/tasks.json' \
      -X 'POST' \
      -H 'Authorization: ...' \
      -d '{"name": "Take out the bread."}'
    

    Example response:

    {
      "id": 600000,
    
      "task_version": 1,
      "task_id": 500000,
    
      "created_by_id": 900,
      "assigned_user_id": null,
    
      "name": "Take out the bread.",
      "position": 1,
      "is_completed": false,
    
      "created_at": "2018-01-01T12:00:00.000+01:00",
      "updated_at": "2018-01-01T12:00:00.000+01:00",
      "deleted_at": null
    }
    

    This command creates a new subtask.

    Request

    POST /api/v3/subtasks.json

    Parameters

    This command accepts a JSON object with following fields:

    Parameter Type Required Default value
    name string Yes -
    task_id ?integer No null
    assigned_user_id ?integer No null
    is_completed boolean No false

    Response

    This command returns a subtask object.

    Errors

    Updating subtasks

    Example code:

    KT.tasks.load(TASK_ID, (task) => {
      subtask = task.subtasks().get(SUBTASK_ID);
    
      subtask.set('name', 'Buy a bread.');
    
      subtask.save().then(() => {
        console.log('Subtask has been updated.');
      });
    }),
    
    // -- you can also update many options and save at once: -- //
    
    subtask.save({
        name: 'Buy a bread.',
        assigned_user_id: 1000,
    });
    
    
    curl 'https://YOUR_DOMAIN.kanbantool.com/api/v3/subtasks/:subtask_id.json' \
      -X 'PATCH' \
      -H 'Authorization: ...' \
      -d '{"name": "Buy a bread."}'
    

    Example response:

    {
      "id": 600000,
    
      "task_version": 1,
      "task_id": 500000,
    
      "created_by_id": 900,
      "assigned_user_id": null,
    
      "name": "Buy a bread.",
      "position": 1,
      "is_completed": false,
    
      "created_at": "2018-01-01T12:00:00.000+01:00",
      "updated_at": "2018-01-01T12:00:00.000+01:00",
      "deleted_at": null
    }
    

    This command updates a subtask.

    Request

    PATCH /api/v3/subtasks/:subtask_id.json

    Parameters

    This command accepts a JSON object with following fields:

    Parameter Type
    name string
    task_id ?integer
    assigned_user_id ?integer
    is_completed boolean

    Response

    This command returns a subtask object.

    Errors

    Deleting subtasks

    Example code:

    KT.call('DELETE', 'tasks/' + TASK_ID + '/comments/' + COMMENT_ID).then(() => {
      console.log('Comment has been deleted.');
    });
    
    // -- or -- //
    
    KT.tasks.load(TASK_ID, (task) => {
      subtask = task.subtasks().get(SUBTASK_ID);
    
      subtask.destroy().then(() => {
        console.log('Subtask has been deleted.');
      });
    });
    
    curl 'https://YOUR_DOMAIN.kanbantool.com/api/v3/subtasks/:subtask_id.json' \
      -X 'DELETE' \
      -H 'Authorization: ...'
    

    Example response:

    {
      "id": 600000,
    
      "task_version": 1,
      "task_id": 500000,
    
      "created_by_id": 900,
      "assigned_user_id": null,
    
      "name": "Buy a bread.",
      "position": 1,
      "is_completed": false,
    
      "created_at": "2018-01-01T12:00:00.000+01:00",
      "updated_at": "2018-01-01T12:00:00.000+01:00",
      "deleted_at": "2018-01-01T12:00:00.000+01:00"
    }
    

    This command soft-deletes a subtask.

    Request

    DELETE /api/v3/subtasks/:subtask_id.json

    Response

    This command returns a subtask object.

    Errors

    Reordering subtasks

    Example code:

    KT.call('PUT', 'subtasks/reorder', {
      task_id: TASK_ID,
      ids: COMMA_SEPARATED_COMMENT_IDS,
    });
    
    // -- or -- //
    
    KT.tasks.load(TASK_ID, (task) => {
      subtasks = task.subtasks();
    
      subtasks
        .reorder([FIRST_SUBTASK_ID, SECOND_SUBTASK_ID, ...])
        .then(() => {
          console.log('Subtasks have been reordered.');
        });
    });
    
    curl 'https://YOUR_DOMAIN.kanbantool.com/api/v3/subtasks/reorder.json' \
      -X 'PUT' \
      -H 'Authorization: ...' \
      -d '{"task_id": "7000", "ids": "30000,10000,20000"}'
    

    Example response:

    [
      {
        "id": 600000,
    
        "task_version": 1,
        "task_id": 500000,
    
        "created_by_id": 900,
        "assigned_user_id": null,
    
        "name": "Buy bread.",
        "position": 1,
        "is_completed": false,
    
        "created_at": "2018-01-01T12:00:00.000+01:00",
        "updated_at": "2018-01-01T12:00:00.000+01:00",
        "deleted_at": null
      },
    
      {
        /* ... */
      },
    
      /* ... */
    ]
    

    This command reorders all subtasks of given task.

    Request

    PUT /api/v3/subtasks/reorder.json

    Parameters

    This command accepts a JSON object with following fields:

    Parameter Type Required Description
    task_id integer Yes Id of the task in which subtasks should be reordered.
    ids string Yes Comma-separated ids of the subtasks in the new order.

    Response

    This command returns a list of subtask objects.

    Errors

    Working with Comments

    Listing comments

    Example code:

    KT.tasks.stub(TASK_ID).load().then((task) => {
      console.log(
        task.get('comments')
      );
    });
    
    // -- or -- //
    
    KT.call('GET', 'tasks/' + TASK_ID).then((response) => {
      console.log(response.comments);
    });
    
    curl 'https://YOUR_DOMAIN.kanbantool.com/api/v3/tasks/:task_id.json' \
      -H 'Authorization: ...'
    

    Example response:

    {
      "id": 500000,
    
      /* ... */
    
      "comments": [
        {
          "id": 900000,
          "user_id": 4000,
          "commentable_version": 1,
          "content": "Hey, who turned out the lights?",
    
          /* ... */
        },
    
        /* ... */
      ],
    
      /* ... */
    }
    

    To list task's comments, you should fetch the task's details and access its comments field.

    Creating comments

    Example code:

    const task = KT.tasks.stub(TASK_ID);
    
    const comment = task.comments().create({
      content: 'Do not forget about the Order 66.',
    });
    
    console.log(comment);
    
    curl 'https://YOUR_DOMAIN.kanbantool.com/api/v3/tasks/:task_id/comments.json' \
      -X 'POST' \
      -H 'Authorization: ...' \
      -d '{"content": "Do not forget about the Order 66."}'
    

    Example response:

    {
      "comment": {
        "id": 500000,
        "user_id": 100000,
        "commentable_version": 5,
    
        "content": "Do not forget about the Order 66.",
    
        "created_at": "2018-01-01T12:00:00.000+01:00",
        "updated_at": "2018-01-01T12:00:00.000+01:00",
        "deleted_at": null,
    
        "recipients": null,
    
        "attachments": [
          /* ... */      
        ]
      }
    }
    

    This command creates a new comment.

    Request

    POST /api/v3/tasks/:task_id/comments.json

    Parameters

    This command accepts a JSON object with following fields:

    Parameter Type Required Default value
    content string Yes -

    Response

    This command returns a comment object.

    Errors

    Deleting comments

    Example code:

    KT.tasks.load(TASK_ID, (task) => {
      comment = task.comments().get(COMMENT_ID);
    
      comment.destroy().then(() => {
        console.log('Comment has been deleted.');
      });
    });
    
    curl 'https://YOUR_DOMAIN.kanbantool.com/api/v3/tasks/:task_id/comments/:comment_id.json' \
      -X 'DELETE' \
      -H 'Authorization: ...'
    

    Example response:

    {
        "id": 900000,
        "user_id": 4000,
        "commentable_version": 1,
        "content": "Hey, who turned out the lights?",
    
        /* ... */
    }
    

    This command soft-deletes a comment.

    Request

    DELETE /api/v3/tasks/:task_id/comments/:comment_id.json

    Response

    This command returns a comment object.

    Errors

    Working with Attachments

    Listing attachments

    There's no endpoint dedicated only to listing attachments - you should fetch the task's details and access its attachments field.

    Creating attachments

    Example code:

    window.myCallback = (attachments) => {
      const successfullyUploadedAttachments = attachments[0];
      const attachment = successfullyUploadedAttachments[0];
    
      console.log(attachment);
    };
    
    KT.Attachments.upload({
      callback: 'myCallback',
      'attachments[][name]': 'some-file.gif',
      'attachments[][url]': 'https://i.imgur.com/yed5Zfk.gif',
    });
    
    curl 'https://YOUR_DOMAIN.kanbantool.com/api/v3/attachments.json' \
      -X 'POST' \
      -H 'Authorization: ...' \
      -F 'files[]=@fileName.png' \
      -F 'attachable=Board#100000'
    

    Example response:

    [
      [
        {
          "id": 900000000,
          "name": "fileName.png",
          "content_type": "application\/octet-stream",
          "size": 123456,
          "data": null,
          "created_at": "2018-01-01T12:00:00.000+01:00",
          "updated_at": "2018-01-01T12:00:00.000+01:00",
          "url": "\/system\/attachments\/abdef-ghijk\/fileName.png"
        }
      ],
    
      /* ... */
    ]
    

    This method creates an attachment and optionally binds it to given object.

    Request

    POST /api/v3/attachments.json

    Parameters

    This command accepts a JSON object with following fields:

    Parameter Type Required Description
    files[] blob Yes File to upload (like in a regular multipart/form-data form).
    attachable string No String representing attachable to which attachment should be bound. See paragraph below for reference.

    Attachables

    Syntax Example Description
    Board#:board_id Board#100000 Represents a board with given id.
    Task#:task_id Task#200000 Represents a task with given id.

    Response

    This command returns an array of attachment objects.

    First array item contains attachments which were uploaded successfully.

    Second array item contains attachments which failed to upload.

    Third array item contains all the above attachments.

    Errors

    Detaching attachments

    Example code:

    KT.tasks.load(TASK_ID, (task) => {
      attachment = task.attachments().get(ATTACHMENT_ID);
      attachment.detach(task);
    });
    
    curl 'https://YOUR_DOMAIN.kanbantool.com/api/v3/attachments/:attachment_id/detach.json' \
      -X 'DELETE' \
      -H 'Authorization: ...'
    

    This command detaches given attachment from specified object.

    Request

    DELETE /api/v3/attachments/:attachment_id/detach.json

    Parameters

    This command accepts a JSON object with following fields:

    Parameter Type Required Description
    attachable string No String representing attachable from which attachment should be detached. See paragraph on Creating attachments for reference.

    Response

    This command returns no response.

    Errors

    Setting the mode attribute

    Example code:

    KT.tasks.load(TASK_ID, (task) => {
      attachment = task.attachments().get(ATTACHMENT_ID);
      attachment.toggleModeFlag(task, 'PIN');
    });
    
    curl 'https://YOUR_DOMAIN.kanbantool.com/api/v3/attachments/:attachment_id/set_mode.json?mode=0' \
      -H 'Authorization: ...'
    

    This command sets the attachment's mode attribute, which is used by the frontend code to store custom binary flags, currently determining whether attachment is pinned to the card (1), and if it is set as a cover image for a card (2).

    Request

    PATCH /api/v3/attachments/:attachment_id/set_mode.json?mode=:mode&attachable=:attachable

    Parameters

    This command accepts the following parameters:

    Parameter Type Required Description
    attachable string Yes String representing attachable from which mode should be set. See paragraph on Creating attachments for reference.
    mode integer yes Integer describing binary flags set on the attachment: 0 - none, 1 - pinned to the card, 2 - set as card cover, 3 - pinned & cover.

    Response

    This command returns no response.

    Errors

    Working with Time Trackers

    Listing time trackers for current user

    To list user's time trackers, you should fetch the user and access its time_trackers field.

    Creating time trackers

    Example code:

    KT.call('POST', 'time_trackers', {
        board_id: BOARD_ID,
        task_id: TASK_ID,
    }).then(() => {
      console.log('Time tracker has been created.');
    });
    
    curl 'https://YOUR_DOMAIN.kanbantool.com/api/v3/time_trackers.json' \
      -X 'POST' \
      -H 'Authorization: ...' \
      -d '{"board_id": 100000, "task_id": 300000}'
    

    Example response:

    {
      "time_tracker": {
        "id": 700000,
        "user_id": 100000,
        "board_id": 200000,
        "task_id": 300000,
        "position": null,
        "listed": true,
        "seconds_from_resumed_sprint": 0,
        "started_at": "2018-01-01T12:00:00.000+01:00",
        "ended_at": "2018-01-01T12:00:00.000+01:00",
        "highlighted_at": null,
        "enlist_at": null,
        "created_at": "2018-01-01T12:00:00.000+01:00",
        "updated_at": "2018-01-01T12:00:00.000+01:00"
      }
    }
    

    This command creates a new time tracker.

    Request

    POST /api/v3/time_trackers.json

    Parameters

    This command accepts a JSON object with following fields:

    Parameter Type Required Default value
    board_id integer Yes -
    task_id integer Yes -
    position ?integer No 1
    listed boolean No true
    started_at dateTime No current date and time
    ended_at ?dateTime No null
    highlighted_at ?dateTime No null

    Response

    This command returns a time tracker object.

    Errors

    Updating time trackers

    Example code:

    KT.call('PUT', 'time_trackers/' + TIME_TRACKER_ID, {
        started_at: '2018-01-01T13:00:00.000+01:00',
        ended_at: '2018-01-01T13:30:00.000+01:00',
    }).then(() => {
      console.log('Time tracker has been updated.');
    });
    
    curl 'https://YOUR_DOMAIN.kanbantool.com/api/v3/time_trackers/:time_tracker_id.json' \
      -X 'PUT' \
      -H 'Authorization: ...' \
      -d '{"started_at": "2018-01-01T13:00:00.000+01:00", "ended_at": "2018-01-01T13:30:00.000+01:00"}'
    

    Example response:

    {
      "time_tracker": {
        "id": 700000,
        "user_id": 100000,
        "board_id": 200000,
        "task_id": 300000,
        "position": null,
        "listed": true,
        "seconds_from_resumed_sprint": 0,
        "started_at": "2018-01-01T13:00:00.000+01:00",
        "ended_at": "2018-01-01T13:30:00.000+01:00",
        "highlighted_at": null,
        "enlist_at": null,
        "created_at": "2018-01-01T12:00:00.000+01:00",
        "updated_at": "2018-01-01T12:00:00.000+01:00"
      }
    }
    

    This commands updates a time tracker.

    Request

    PUT /api/v3/time_trackers/:time_tracker_id.json

    Parameters

    Parameter Type
    position ?integer
    listed boolean
    started_at ?dateTime
    ended_at ?dateTime
    highlighted_at ?dateTime

    Response

    This command returns a time tracker object.

    Errors

    Deleting time trackers

    Example code:

    KT.call('DELETE', 'time_trackers/' + TIME_TRACKER_ID).then(() => {
      console.log('Time tracker has been deleted.');
    });
    
    curl 'https://YOUR_DOMAIN.kanbantool.com/api/v3/time_trackers/:time_tracker_id.json' \
      -X 'DELETE' \
      -H 'Authorization: ...'
    

    Example response:

    {
      "time_tracker": {
        "id": 700000,
        "user_id": 100000,
        "board_id": 200000,
        "task_id": 300000,
        "position": null,
        "listed": true,
        "seconds_from_resumed_sprint": 0,
        "started_at": "2018-01-01T12:00:00.000+01:00",
        "ended_at": "2018-01-01T12:00:00.000+01:00",
        "highlighted_at": null,
        "enlist_at": null,
        "created_at": "2018-01-01T12:00:00.000+01:00",
        "updated_at": "2018-01-01T12:00:00.000+01:00"
      }
    }
    

    This commands deletes a time tracker.

    Request

    DELETE /api/v3/time_trackers/:time_tracker_id.json

    Response

    This command returns a time tracker object.

    Errors

    Types Reference

    Our API utilizes following types:

    Type Description Example
    boolean true or false true
    date date in Y-m-d format 2018-02-20
    dateTime date in c format 2018-02-20T09:18:15.000+01:0
    float a floating-point number with . used as the separator 123.45
    integer a 32-bit signed integer 12345678
    string an UTF-8 string of variadic length Hello World!

    Objects Reference

    Field availability

    For optimization purposes, some commands return only a brief of object's data.

    For example: when requesting /api/v3/users/current.json, you'll receive list of all the boards user has access to, but it will not contain the board's tasks (since that'd yield a pretty huge object).

    To annotate this fact, we've created an Available in column in the objects references' tables, which denotes which fields are available in which commands.

    Board (object)

    Note: If you look for a human-friendly definition of board, you should go to the board's definition.

    Abbreviations used in the Available in column:
    F = fetching
    D = fetching details

    This object defines a single board; it contains both the board's basic data (like its name & position) and its relationships (like tasks or changelogs).

    Field Type Available in Description
    id integer F, D Board's unique identifier.
    version integer F, D Board's version. Counted from 1.
    external_id_sequence ?integer F, D Board's custom id, optional. Can be used to keep track of the board when synchronizing with other platforms.
    board_template_id string F, D If board's been cloned, this field contains id of that base board. Otherwise, this field contains name of the template used to create this board.
    folder_id ?integer F, D Board's folder id, if it belongs to any.
    owner_id integer F, D Id of the user who owns this board.
    position integer F, D Board's position in the list of all the boards. Counted from 1.
    name string F, D Board's name.
    description string F, D Board's description.
    last_activity_on date F, D Date of latest activity on the board.
    settings_updated_at ?dateTime F, D Date & time when board's settings were updated for the last time - if they have been updated.
    created_at dateTime F, D Date & time when board's been created.
    updated_at dateTime F, D Date & time when board's been updated for the last time.
    deleted_at ?dateTime F, D Date & time when board's been deleted - if it's been deleted.
    card_template Board.Settings.CardTemplateField[] F, D Data of the card template which belongs to this board. A shortcut for board.settings.card_template.
    card_types CardType[] F, D List of all the card types which belong to this board.
    swimlanes Swimlane[] F, D List of all the swimlanes which belong to this board.
    workflow_stages WorkflowStage[] F, D List of all the workflow stages which belong to this board.
    tasks Task[] D List of all the tasks which belong to this board.
    settings Board.Settings F, D Data of the board's settings.
    stats Board.Statistic[] F, D List of all the board's statistics.
    collaborators Collaborator[] F, D List of all the board's collaborators.
    changelogs Changelog[] D List of all the changelogs which belong to this board.

    Board.Statistic (nested object)

    This object defines a single board's statistic.

    It is a read-only, automatically generated object for each of the board's swimlanes and workflow stages.

    Field Type Description
    swimlane_id integer Statistic's swimlane's id.
    workflow_stage_id integer Statistic's workflow stage's id.
    visible_tasks integer Number of visible tasks in above swimlane & workflow stage's pair.
    archived_tasks integer Number of archived tasks in above swimlane & workflow stage's pair.

    Board.Settings (nested object)

    This object defines settings for a single board - it is a part of the board object, but has been created a section of it's own because of its complexity.

    The board settings define:

    Field Type Description
    card_template Board.Settings.CardTemplateField[] Defines settings of the board's tasks' card template.
    powerups Board.Settings.PowerUp[] Defines settings of the board's power-ups.

    Board.Settings.CardTemplateField (nested object)

    This object can be thought of as a schema for each task. It describes a single field present in each of the board's tasks - defines whether that field it's required, what's its default value and so on.

    By the default, this object contains following properties, but - depending on the specific field - there can be more of them:

    Property Type Description
    enabled boolean If equal to true, field is enabled.
    position integer Position of the field in the board's settings. Counted from 1.

    Additional properties for the external_id field

    The external_id field contains these additional properties:

    Property Type Description
    show_on_card boolean If equal to true, the external id is visible on the task's card.
    editable boolean If equal to true, the external id can be modified by users (from the interface). If equal to false, it can be modified only be the API.
    auto_generate boolean If equal to true, the external id field is generated automatically (in an auto increment fashion). If equal to false, you must fill the external id's value manually when creating a task.
    sequential boolean If equal to true, the external id field is forced to be a unique, sequential value throughout all the boards. If equal to false, this field is not validated and it's uniqueness is not enforced in any way.

    Additional properties for the size_estimate field

    The size_estimate field contains these additional properties:

    Property Type Description
    show_on_card boolean If equal to true, the size estimate field is visible on the task's card.
    default string Defines the default value for the size estimate field.
    values string Describes all the possible size estimates. It's for user information only - it's not parsed anywhere in the system.

    Additional properties for the custom_field_N fields

    The custom_field_N fields (custom_field_1, custom_field_2 and so on) contain these additional properties:

    Property Type Description
    label string Custom field's label (e.g. Difficulty points).
    type string Custom field's type, one of: text, link, number, select, date, user.
    width string Custom field's percentage width when rendering; one of: 25, 50, 75, 100.
    options string When this field represents a custom dropdown (select type), this field contains comma-separated list of possible values.
    multiple string When this field represents a dropdown (select or user type), this field determines whether one can choose many values or only one.
    multiline string When this field represents a text (text type), this field determines whether one can write multi-line text inside.

    Board.Settings.PowerUp (nested object)

    This is the base for all the power-ups' settings - each power-up can put any configuration data it requires in this object:

    Property Type Description
    enabled boolean If equal to true, power-up is enabled.

    Since it's power-up-dependent and highly internal, we're not going to cover those settings - if you need to do anything more than just enabling / disabling power-ups, you're on your own.

    Card Type (object)

    This object defines the overall look of of task's card type - it determines e.g. the task's background color.

    Field Type Description
    id integer Card type's unique identifier.
    board_id integer Id of the board to which this card type belongs to.
    name string Card type's label; unique to the board.
    color_ref string Card type's color. See table below for reference.
    is_default boolean If equal to true, all future tasks created at given board will be set this card type by the default
    is_disabled boolean If equal to true, card type is marked as disabled.
    position integer Position of the card type in the board's card type list. Counted from 1.
    color_attrs CardType.ColorAttrs Object describing card type's color.

    CardType.color_ref (field)

    color_ref CSS equivalent Preview
    turquoise #00BCD4
    light_blue #03A9F4
    blue #2196F3
    navy #3F51B5
    violet #673AB7
    fuchsia #9C27B0
    pink #E91E63
    strong_red #D83535
    red #f44336
    carrot #FF5722
    orange #FF9800
    sand #FFC107
    yellow #FFEB3B
    lemon #CDDC39
    green_light #8BC34A
    green #4CAF50
    green_dark #388E3C
    brown #795548
    black #262626
    gray_dark #595959
    gray_medium #9E9E9E
    white #E8E8E8

    CardType.ColorAttrs (nested object)

    Field Type Description
    rgb string A hex value representing the color, prepended with a hash (e.g. #123456).
    position integer Position of the color on the colors' list. Counted from 1.
    default boolean If equal to true, color is marked as the default one. By the default the yellow color is marked as such.

    Changelog (object)

    This object defines a single change made on a given object (a task or a subtask).

    Field Type Description
    id integer Changelog's unique identifier.
    board_id integer Id of the board on which change has been made.
    board_version integer Version of the board at the time of the change.
    swimlane_id integer Id of the swimlane to which this changelog refers to.
    workflow_stage_id integer Id of the workflow stage to which this changelog refers to.
    user_id integer Id of the user who made this change.
    changed_object_type ?string Changed object's type (e.g. Task). May not be present when context is obvious (e.g. when fetching just the task's changelogs).
    changed_object_id integer Changed object's identifier (e.g. modified task's identifier).
    changed_object_version integer Changed object's version at the time of the change.
    what string Change's type (e.g. created). See table below for reference.
    description string Change's description (e.g. XX added task 'yy' to the board).
    data ?object Additional data about the deleted object, optional. See table below for reference.
    created_at dateTime Date & time when this change was created.

    Changelog.what (field)

    This field determines type of change that has been made. It contains one of these values:

    - deleted

    Meaning: task changed_object_id has been deleted.

    Value of the data field: none.

    - comment_deleted

    Meaning: comment changed_object_id has been deleted.

    Value of the data field:

    Field Type Description
    comment_id integer Id of the deleted comment.
    comment_content string Contents of that comment.
    task_id integer Id of the task to which the comment belongs to.
    task_external_id string External id of that task.
    task_name string Name of that task.
    swimlane_id integer Same as changelog.swimlane_id.
    swimlane_name string Name of that swimlane.
    workflow_stage_id integer Same as changelog.workflow_stage_id.
    workflow_stage_name string Name of that workflow stage.
    user_id integer Same as changelog.user_id.
    user_initials string Initials of that user.

    - subtask_checked, subtask_unchecked

    Meaning: subtask changed_object_id has been checked or unchecked.

    Value of the data field:

    Field Type Description
    subtask_id integer Id of the (un)checked subtask.
    subtask_name string Name of that subtask.
    task_id integer Id of the task to which the subtask belongs to.
    task_external_id string External id of that task.
    task_name string Name of that task.
    swimlane_id integer Same as changelog.swimlane_id.
    swimlane_name string Name of that swimlane.
    workflow_stage_id integer Same as changelog.workflow_stage_id.
    workflow_stage_name string Name of that workflow stage.
    user_id integer Same as changelog.user_id.
    user_initials string Initials of that user.

    Collaborator (object)

    This object contains data of user who modified another object.

    You can receive this object as a part of a board or task.

    Field Type Description
    id integer User's id.
    name string User's full name (e.g. Foo Bar).
    initials string User's initials (e.g. FB).
    active boolean If equal to true, user's account is still active.

    Comment (object)

    This object defines a single comment.

    By the design, all comments can be only bound to tasks.

    Field Type Description
    id integer Comment's unique identifier.
    user_id integer Id of the user who created this comment.
    commentable_version integer Version of the object, to which comment is bound, at the time of creating the comment. If the comment's bound to a task for example, this field contains that task's version. Counted from 1.
    content string Comment's message. Markdown formatting is supported.
    recipients ?string[] Comment's recipients, if any - e.g.: ['Foo Bar <123>', 'Asdf Asdf <312>'].
    created_at dateTime Date & time when comment was created.
    updated_at dateTime Date & time when comment was updated for the last time.
    deleted_at ?dateTime Date & time when comment was deleted - if it's been deleted.
    attachments Comment.Attachment[] Comment's attachments.

    Comment.Attachment (nested object)

    Field Type Description
    id integer Attachment's unique identifier.
    name string Attachment's file name (e.g. final-diagram-final-final-2018.png).
    content_type string Attachment's MIME type (e.g. image/jpeg).
    size integer Attachment's size, in bytes (e.g. 123321).
    url string Attachment's URL, relative to the account's domain (e.g. /system/attachments/sn9837gvn592/dskj123409fg.jpg).
    created_at dateTime Date & time when attachment was created.
    updated_at dateTime Date & time when attachment was updated for the last time.

    Subtask (object)

    Note: If you look for a human-friendly definition of subtask, you should go to the task's definition.

    This object defines a single subtask.

    Field Type Description
    id integer Subtask's unique identifier.
    task_id integer Id of the task to which this subtask belongs to.
    task_version integer Version of that task.
    created_by_id integer Id of user who created this subtask.
    assigned_user_id ?integer Id of user to whom the subtask has been assigned.
    position integer Subtask's position on the task's subtasks list. Counted from 1.
    name string Subtask's name.
    is_completed boolean If equal to true, subtask has been marked as completed.
    created_at dateTime Date & time when subtask was created.
    updated_at dateTime Date & time when subtask was updated for the last time.
    deleted_at ?dateTime Date & time when subtask was deleted - if it's been deleted.

    Task (object)

    Note: If you look for a human-friendly definition of task, you should go to the task's definition.

    Abbreviations used in the Available in column:
    L = listing
    F = fetching
    D = fetching details

    This object defines a single task; it contains both the basic task's data (like its name & priority) and its relationships (like subtasks or changelogs).

    Field Type Available in Description
    id integer L, F, D Task's unique identifier.
    version integer L, F, D Task's version. It's automatically incrementing counter, counted from 1.
    external_id ?integer L, F, D Task's custom identifier; optional. Can be used to keep track of the task when synchronizing with other platforms.
    external_link ?string L, F, D Task's custom URL; optional. Functions as above.
    board_id integer L, F, D Id of the board to which this task belongs to.
    board_version integer L, F, D Version of the board when this task was created.
    swimlane_id integer L, F, D Id of the swimlane this task belongs to.
    workflow_stage_id integer L, F, D Id of the workflow stage this task belongs to.
    card_type_id integer L, F, D Id of the card type this task belongs to.
    card_color string L, F, D Task's card's background color name (e.g. yellow).
    card_color_in_rgb string L, F, D Task's card's background color value (e.g. #ffeB3b).
    card_color_invert boolean L, F, D If equal to true, task's card's foreground (text) color should be white (instead of the default black one), for it to be readable.
    created_by_id integer L, F, D Id of the user who created this task.
    assigned_user_id ?integer L, F, D Id of user to which this task has been assigned; optional.
    position integer L, F, D Position of the task in the swimlane & board window. See board definition.
    name string L, F, D Task's name.
    description ?string L, F, D Task's description; optional. HTML tags are supported.
    priority integer L, F, D Task's priority; one of: -1 (low), 0 (normal) or 1 (high).
    tags string L, F, D Comma-separated list of tags associated with task, e.g. bug,chrome,something-else.
    search_tags string[] L, F, D Read-only list of tags / keywords related to this task, e.g. ['Some Task', 'yellow']. It's generated automatically basing on the task's contents.
    time_estimate ?integer L, F, D Task's time estimate, measured in number of seconds; optional.
    size_estimate string L, F, D Task's difficulty as measured by a number; optional. Typically: 0.1 = relatively easy, 1.0 = moderately difficult, 5.0 = 5 times harder than an average task.
    size_estimate_description string L, F, D Read-only description of the task's difficulty, e.g.: small and relatively easy.
    due_date ?date L, F, D Date to which the task is due; optional.
    postponed_until ?date L, F, D Date to which the task has been postponed; optional.
    created_at dateTime L, F, D Date & time when task was created.
    updated_at dateTime L, F, D Date & time when task was updated for the last time.
    archived_at ?dateTime L, F, D Date & time when task was archived - if it's been archived.
    deleted_at ?dateTime L, F, D Date & time when task was deleted - if it's been deleted.
    comments Comment[] F, D List of all the task's comments.
    comments_count integer L, F, D Number of the task's comments.
    timers_total ?integer L, F, D Total number of seconds logged from the finished timers. Equal to null if no time has been logged yet.
    timers_total_updated_at ?dateTime L, F, D Date & time when any of the task's timers was updated for the last time. Equal to null if no timer-related changes have been ever made.
    timers_active_count integer L, F, D Number of currently active (running) timers.
    timers_listed_count integer L, F, D Total number of timers associated with this task (but not necessarily running right now).
    subtasks Subtask[] L, F, D List of all the task's subtasks (checklist points).
    subtasks_count integer L, F, D Number of all the subtasks.
    subtasks_completed_count integer L, F, D Number of all the completed subtasks.
    attachments Attachment[] F, D List of all the task's attachments.
    attachments_count integer L, F, D Number of all the task's attachments.
    time_trackers TimeTracker[] F, D List of all the task's time trackers.
    collaborators Collaborator[] F, D List of all the task's collaborators.
    changelogs Changelog[] F, D List of all the task's changelogs.
    block_reason ?string L, F, D If the Card block power-up is active, this field describes reason for blocking this task. Equal to null if task has not been blocked.
    recurring_schedule ?Task.RecurringSchedule L, F, D If the Recurring tasks power-up is active, this field describes the recurring schedule data related to this task.
    custom_field_N ?string L, F, D Task's custom fields; can contain arbitrary data related to e.g. synchronizing the tasks.

    Task.RecurringSchedule (nested object)

    This section describes recurring schedule for a task when the Recurring tasks power-up is active.

    task.recurring_schedule contains a string in form: [dateTime] + [JSON object], where:

    Example recurring_schedule value:

    2018-03-06T05:00Z{"type":"d","h":"6","m":"0","multi":"1","start":"2018-03-06","tz":"Warsaw","ts":1520249122}
    

    Daily recurring schedule

    Example: daily, on 12:30, every 3 days starting from 2018-01-01.

    Object:

    type  = d
    h     = 12
    m     = 30
    multi = 3
    start = 2018-01-01
    tz    = Warsaw
    

    Tasks can be scheduled to be created daily, at given hour and minute.

    Field Type Description
    type string Describes the schedule's type. Equal to d when dealing with daily recurring schedule.
    h integer Hour at which schedule's tasks should be created.
    m integer Minute at which schedule's tasks should be created.
    multi integer Tasks will be created every multi day(s) starting from given start date (e.g. value 3 means that schedule will be applied every 3 days).
    start date Tasks will be created every multi day(s) starting from given start date (e.g. value 2018-01-01 means that schedule will begin to be applied from 2018-01-01).
    tz string Timezone, e.g.: Warsaw.

    Weekly recurring schedule

    Example: weekly, on 12:30, at every Monday and Friday.

    Object:

    type = w
    h    = 12
    m    = 30
    wd_0 = 0
    wd_1 = 1
    wd_2 = 0
    wd_3 = 0
    wd_4 = 0
    wd_5 = 1
    wd_6 = 0
    tz   = Warsaw
    

    Tasks can be scheduled to be created weekly, at each given day of week, hour and minute.

    Field Type Description
    type string Describes the schedule's type. Equal to w when dealing with weekly recurring schedule.
    h integer Hour at which schedule's tasks should be created.
    m integer Minute at which schedule's tasks should be created.
    wd_0 integer If equal to 1, schedule is enabled for Sundays - equal to 0 otherwise.
    wd_1 integer If equal to 1, schedule is enabled for Mondays - equal to 0 otherwise.
    wd_2 integer If equal to 1, schedule is enabled for Tuesdays - equal to 0 otherwise.
    wd_3 integer If equal to 1, schedule is enabled for Wednesdays - equal to 0 otherwise.
    wd_4 integer If equal to 1, schedule is enabled for Thursdays - equal to 0 otherwise.
    wd_5 integer If equal to 1, schedule is enabled for Fridays - equal to 0 otherwise.
    wd_6 integer If equal to 1, schedule is enabled for Saturdays - equal to 0 otherwise.
    tz string Timezone, e.g.: Warsaw.

    Monthly recurring schedule

    Example: monthly, on 12:30, at every first, fifth and tenth day of each month.

    Object:

    type = m
    h    = 12
    m    = 30
    days = 1,5,10
    tz   = Warsaw
    

    Tasks can be scheduled to be created monthly, at each given day of month, hour and minute.

    Field Type Description
    type string Describes the schedule's type. Equal to m when dealing with monthly recurring schedule.
    h integer Hour at which schedule's tasks should be created.
    m integer Minute at which schedule's tasks should be created.
    days string Comma-separated days at which tasks should be created. E.g. 1,5,10 for first, fifth and tenth day of each month.
    tz string Timezone, e.g.: Warsaw.

    Custom recurring schedule

    Example: custom, on 12:30, at 2018-01-01, 2018-02-03, 2018-09-12.

    Object:

    type = c
    h    = 12
    m    = 30
    days = 2018-01-01,2018-02-03,2018-09-12
    tz   = Warsaw
    
    Field Type Description
    type string Describes the schedule's type. Equal to c when dealing with custom recurring schedule.
    h integer Hour at which schedule's tasks should be created.
    m integer Minute at which schedule's tasks should be created.
    dates string Comma-separated dates at which tasks should be created. E.g. 2018-01-01,2018-02-03,2018-09-12 etc.
    tz string Timezone, e.g.: Warsaw.

    User (object)

    This object defines a single user.

    Field Type Description
    id integer User's unique identifier.
    version integer User's version. Counted from 1.
    name string User's full name (e.g. Jon Snow).
    initials string User's initials (e.g. JS).
    timezone string User's timezone. See here for reference.
    locale string User's locale. It's a simple, two-letter representation of the language, e.g. en or pl.
    is_project_manager boolean If equal to true, user is a project manager.
    is_account_admin boolean If equal to true, user is an administrator of that account.
    is_account_owner boolean If equal to true, user is an owner of the account to which it's linked.
    is_suspended boolean If equal to true, user is suspended.
    last_login_at dateTime Date & time when user's logged in for the last time.
    last_activity_on date Date of user's latest activity.
    created_at dateTime Date & time when user's been created.
    updated_at dateTime Date & time when user's been modified for the last time.
    account Account Account to which user's bound.
    boards Board[] List of user's boards.
    time_trackers TimeTracker[] List of user's time trackers.

    Roles / permissions

    Users can be assigned permissions, namely:

    Project manager

    Project managers can create new boards, share them and invite others. They can only manage the boards they have created and cannot see or access other boards, unless they have been shared with them. They can invite new users, but cannot access the People tab to modify their details.

    Account administrator

    Administrators can create, access and manage all dashboard items within given account. They cannot access the Account settings tab.

    Account owner

    Account owners can do everything with and within their account. This includes: viewing billing details, invoices and terminating the account.

    Workflow Stage (object)

    Note: If you look for a human-friendly definition of workflow stage, you should go to the workflow stage's definition.

    This object defines a workflow stage.

    Workflow stage can be fetched as a part of a board object.

    Field Type Description
    id integer Workflow stage's unique identifier.
    board_id integer Id of the board to which this workflow stage belongs to.
    board_version integer Version of the board at the time of workflow stage's creation.
    parent_id ?integer Id of the workflow stage's parent - used to construct a hierarchy of workflow stages.
    lft integer Used to construct a hierarchy of workflow stages (https://www.sitepoint.com/hierarchical-data-database-2).
    rgt integer Used to construct a hierarchy of workflow stages (https://www.sitepoint.com/hierarchical-data-database-2).
    position integer Position of the workflow stage on the board.
    name string Workflow stage's name (To do, In progress etc.).
    description ?string Workflow stage's description, optional.
    wip_limit ?integer Maximum number of the WIP indicator value which can be put in this workflow stage. Equal to null if no limit should be imposed.
    wip_limit_type ?string Type of indicator for the WIP limit. See below for reference..
    lane_type_id ?integer Type of workflow stage's line. One of: 1 (Backlog / Inventory), 2 (Queue / Waiting), 3 (In Progress), 4 (Done) or null.
    lane_type ?string (read-only) If lane_type_id is set, this field contains a string representation of the lane_type_id value. One of: backlog_inventory, waiting, in_progress, done or null.
    lane_width integer Number of cards per each row of the lane (e.g. value of 2 means that when rendering this workflow stage, two cards should be placed next to each other, the next two should be in a new row etc.).
    archive_enabled boolean If equal to true, tasks being in this stage can be archived. Usually set to true for final stages (like Done).

    WorkflowStage.wip_limit_type (field)

    The wip_limit_type accepts null or one of these values:

    wip_limit_type Description
    tasks_count Number of tasks bound to this workflow stage.
    tasks_size Sum of tasks' difficulty points.
    time_estimate Sum of tasks' estimated hours.
    assignments Number of tasks per user.

    Definitions

    Since some concepts used when talking about kanban boards are not necessarily obvious, we've prepared a few descriptions accompanied with screenshots to help you understand our tool better.

    Board (definition)

    Note: If you look for a programmer-friendly definition of board, you should go to the board's object reference.

    Board is a fundamental piece of the Kanban Tool - this is where all the magic happens.

    Board consists of:

    An example board can look like:

    Board

    You can see here:

    Swimlane (definition)

    Note: If you look for a programmer-friendly definition of swimlane, you should go to the swimlane's object reference.

    Swimlanes are used to group tasks vertically - for example to easily distribute work against many teams:

    Swimlane

    Each board has its own set of swimlanes, which can be altered in any way you like.

    Task (definition)

    Note: If you look for a programmer-friendly definition of task, you should go to the task's object reference.

    Task is a note, which belongs to a certain board, swimlane and a workflow stage.

    Task is also defined by its:

    Task

    Additionally, each task can contain from zero to a lots of subtasks - the task presented above has 4 of them.

    Workflow Stage (definition)

    Note: If you look for a programmer-friendly definition of workflow stage, you should go to the workflow stage's object reference.

    Workflow stage determines the status of your task - it can be In progress, Done and so on:

    Workflow stage

    Each board has its own set of workflow stages, which can be altered in any way you like.

    Moreover - workflow stages can be 'stacked' on top of each other, creating a hierarchy:

    Workflow stage hierarchy