Kanban Tool API v3

https://kanbantool.com/developer/api-v3
Admin
Kanban Tool's API v3 provides developers with a RESTful interface to integrate external systems with...
Tokens:22,691
Snippets:91
Trust Score:9.7
Update:1 year ago
Show doc for...
Tokens:
Raw
### Example Current User Response

Source: https://kanbantool.com/developer/api-v3/index

Provides an example JSON structure for the response when fetching the current user's details via the API.

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

--------------------------------

### Fetch Current User with cURL (Authorization Header - Alternative)

Source: https://kanbantool.com/developer/api-v3/index

Another example using cURL for fetching the current user, emphasizing the Authorization header for authentication.

```bash
# Using Authorization header:

$ curl 'https://YOUR_DOMAIN.kanbantool.com/api/v3/some_action.json' \
    -H 'Authorization: Bearer YOUR_TOKEN'
```

--------------------------------

### Initialize SDK and Get Current User

Source: https://kanbantool.com/developer/api-v3/index

Demonstrates initializing the Kanban Tool SDK with domain and token, then retrieving the current user's name. This is the primary method for integrating the SDK into applications.

```javascript
KT.init(YOUR_DOMAIN, YOUR_TOKEN).then(() => {
  console.log(
    KT.currentUser.get('name')
  );
});
```

--------------------------------

### Create Task

Source: https://kanbantool.com/developer/api-v3/index

Creates a new task within KanbanTool. Provides JavaScript examples for SDK and cURL requests, the API endpoint, required parameters, default behavior for new tasks, and error conditions.

```JavaScript
const task = KT.tasks.create({
    board_id: 100000,
    name: 'Make Mary a sandwich.'
});

console.log(task);
```

```cURL
curl 'https://YOUR_DOMAIN.kanbantool.com/api/v3/tasks.json' \
  -X 'POST' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ...' \
  -d '{"board_id":123, "name": "Make Mary a sandwich."}'
```

```APIDOC
POST /api/v3/tasks.json
  Description: Creates a new task.
  Parameters:
    - task[name]: (Required) The name of the task.
    - task[board_id]: (Required) The ID of the board where the task will be created.
    - task[workflow_stage_id]: Optional. The ID of the workflow stage.
    - task[swimlane_id]: Optional. The ID of the swimlane.
    - task[card_type_id]: Optional. The ID of the card type.
    - task[task_attachment_ids]: Array of IDs of attachments to link.
    - task[subtask_ids]: Array of IDs of subtasks to link.
    - assert_has_unique_external_id: If set, verifies task uniqueness by external_id.
  Default Behavior:
    - New tasks are created in the top-left cell with the default card type unless stage, swimlane, or card type IDs are specified.
  Response:
    - 201 Created: Returns the created task object.
    - 404 Not Found: Returned when an invalid board_id is provided.
    - 422 Unprocessable Entity: Returned when fields are missing or have an invalid format.
```

--------------------------------

### Fetch Current User with cURL (Access Token)

Source: https://kanbantool.com/developer/api-v3/index

An example using cURL to fetch the current user's information by passing the API token as an access_token query parameter. This method is deprecated.

```bash
$ curl 'https://YOUR_DOMAIN.kanbantool.com/api/v3/users/current.json?access_token=YOUR_TOKEN'
```

--------------------------------

### Fetch Task Details

Source: https://kanbantool.com/developer/api-v3/index

Retrieves detailed information for a specific task using the KanbanTool API. Includes JavaScript examples for SDK and generic calls, a cURL request, the API endpoint, response structure, and error conditions. Note that the full task object can be large.

```JavaScript
KT.tasks.stub(TASK_ID).load().then((task) => {
    console.log(task);
});

// -- or -- //

KT.call('GET', 'tasks/' + TASK_ID).then((response) => {
  console.log(response);
});
```

```cURL
curl 'https://YOUR_DOMAIN.kanbantool.com/api/v3/tasks/:task_id.json' \
  -H 'Authorization: Bearer ...'
```

```APIDOC
GET /api/v3/tasks/:task_id.json
  Description: Returns detailed information about a given task.
  Parameters:
    - :task_id: The ID of the task to fetch.
  Response:
    - 200 OK: Returns a task object.
    - 404 Not Found: Returned when given an invalid task_id.
  Example Response Structure:
    {
      "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": []
    }
```

--------------------------------

### Fetch Board Information (Preload)

Source: https://kanbantool.com/developer/api-v3/index

Retrieves general information about a specific board, identified by its ID. This method does not include the board's tasks. It's useful for getting board metadata without a large payload.

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

Description:
  Returns overall information about a given board.

Parameters:
  - :board_id (integer): The unique identifier for the board.

Request Headers:
  - Authorization: Bearer YOUR_API_TOKEN

Response:
  - 200 OK: Returns a board object containing general information.
    Example Response Structure:
    {
      "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": { ... }
    }
  - 404 Not Found: Returned when the provided :board_id is invalid.

Example Usage (JavaScript):
KT.boards.stub(BOARD_ID).preload().then((board) => {
    console.log(board);
});

Example Usage (cURL):
curl 'https://YOUR_DOMAIN.kanbantool.com/api/v3/boards/:board_id/preload.json' \
  -H 'Authorization: Bearer ...'
```

--------------------------------

### Daily Recurring Schedule Configuration

Source: https://kanbantool.com/developer/api-v3/index

Defines a daily recurring schedule for task creation. Tasks are created at a specified hour and minute, recurring every `multi` days starting from a given `start` date. Includes timezone information.

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

--------------------------------

### Update Task

Source: https://kanbantool.com/developer/api-v3/index

Updates an existing task in KanbanTool. Demonstrates JavaScript examples for updating single or multiple fields, a cURL request, the API endpoint, and the response format.

```JavaScript
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
curl 'https://YOUR_DOMAIN.kanbantool.com/api/v3/tasks/:task_id.json' \
  -X 'PATCH' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ...' \
  -d '{"name":"Make Jenny a sandwich.", "description": "And do it now!"}'
```

```APIDOC
PATCH /api/v3/tasks/:task_id.json
  Description: Updates an existing task.
  Parameters:
    - :task_id: The ID of the task to update.
    - Request Body: JSON object containing fields to update (e.g., {"name": "New Name", "description": "New Description"}).
  Response:
    - 200 OK: Returns the updated task object.
    - 404 Not Found: Returned when given an invalid task_id.
    - 422 Unprocessable Entity: Returned when fields have an invalid format.
```

--------------------------------

### Reorder Subtasks

Source: https://kanbantool.com/developer/api-v3/index

Reorders subtasks within a specific task. Supports both direct API calls and SDK methods. Includes cURL example for direct API interaction.

```javascript
KT.call('PUT', 'subtasks/reorder', {
  task_id: TASK_ID,
  ids: COMMA_SEPARATED_COMMENT_IDS,
});
```

```javascript
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
curl 'https://YOUR_DOMAIN.kanbantool.com/api/v3/subtasks/reorder.json' \
  -X 'PUT' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ...' \
  -d '{"task_id": "7000", "ids": "30000,10000,20000"}'
```

--------------------------------

### Update Subtask (JavaScript)

Source: https://kanbantool.com/developer/api-v3/index

Illustrates how to update an existing subtask using the Kanban Tool JavaScript SDK. It shows loading a task, getting a specific subtask, modifying its properties, and saving the changes.

```javascript
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,
});
```

--------------------------------

### SDK Initialization with Callback

Source: https://kanbantool.com/developer/api-v3/index

Provides an alternative way to handle SDK initialization and access user data using an onInit callback, ensuring operations occur after authentication.

```javascript
// KT.currentUser is loaded automatically upon a call to KT.init(...)
KT.onInit(() => {
  console.log(KT.currentUser);
});

KT.init(YOUR_DOMAIN, API_TOKEN);
```

--------------------------------

### Make REST API Queries with SDK

Source: https://kanbantool.com/developer/api-v3/index

Shows how to use the KT.call method to perform simple REST API queries, such as fetching task details. This method abstracts direct HTTP requests.

```javascript
// You can use KT.call to make simple REST API queries: //

KT.call('GET', 'tasks/' + TASK_ID).then((response) => {
  console.log(response);
});
```

--------------------------------

### Delete Subtask (JavaScript)

Source: https://kanbantool.com/developer/api-v3/index

Shows how to delete a subtask using the Kanban Tool JavaScript SDK. It includes examples for both a general KT.call method and a specific subtask destroy method.

```javascript
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.');
  });
});
```

--------------------------------

### Fetch Current User with cURL (Authorization Header)

Source: https://kanbantool.com/developer/api-v3/index

Demonstrates fetching the current user's information using cURL with the recommended Bearer token authentication via the Authorization header.

```bash
$ curl 'https://YOUR_DOMAIN.kanbantool.com/api/v3/users/current.json' \
    -H 'Authorization: Bearer YOUR_TOKEN'
```

--------------------------------

### Kanban Tool API v3 - Tasks

Source: https://kanbantool.com/developer/api-v3/index

Covers the full lifecycle of tasks, including listing, searching, fetching, creating, updating, archiving, unarchiving, deleting, and restoring tasks within boards.

```APIDOC
Tasks:
  GET /boards/{board_id}/tasks
    - Lists all tasks within a specified board.
    - Requires authentication.
    - Parameters:
      - board_id (integer): The ID of the board.
    - Returns a list of Task objects.

  GET /tasks/search?query={search_query}
    - Searches for tasks across the platform based on a query.
    - Requires authentication.
    - Parameters:
      - query (string): The search term.
    - Returns a list of Task objects.

  GET /tasks/{task_id}
    - Fetches details of a specific task.
    - Requires authentication.
    - Parameters:
      - task_id (integer): The ID of the task.
    - Returns a Task object.

  POST /boards/{board_id}/tasks
    - Creates a new task within a specified board.
    - Requires authentication.
    - Parameters:
      - board_id (integer): The ID of the board.
      - task_data (object): Task details (e.g., title, description, status).
    - Returns the created Task object.

  PUT /tasks/{task_id}
    - Updates an existing task.
    - Requires authentication.
    - Parameters:
      - task_id (integer): The ID of the task.
      - task_data (object): Updated task details.
    - Returns the updated Task object.

  POST /tasks/{task_id}/archive
    - Archives a specific task.
    - Requires authentication.
    - Parameters:
      - task_id (integer): The ID of the task.
    - Returns the archived Task object.

  POST /tasks/{task_id}/unarchive
    - Unarchives a specific task.
    - Requires authentication.
    - Parameters:
      - task_id (integer): The ID of the task.
    - Returns the unarchived Task object.

  DELETE /tasks/{task_id}
    - Deletes a specific task permanently.
    - Requires authentication.
    - Parameters:
      - task_id (integer): The ID of the task.
    - Returns a success status.

  POST /tasks/{task_id}/restore
    - Restores a previously archived task.
    - Requires authentication.
    - Parameters:
      - task_id (integer): The ID of the task.
    - Returns the restored Task object.
```

--------------------------------

### Fetch Task Details with JavaScript SDK

Source: https://kanbantool.com/developer/api-v3/index

Demonstrates how to fetch detailed information for a specific task using the Kanban Tool JavaScript SDK. It shows two common methods: using a stubbed task ID and a direct call. Requires the KT SDK and a valid TASK_ID.

```javascript
KT.tasks.stub(TASK_ID).preload().then((task) => {
  console.log(task);
});

// -- or -- //

KT.tasks.preload(TASK_ID, (task) => {
  console.log(task);
});
```

--------------------------------

### Board.Settings Object Structure

Source: https://kanbantool.com/developer/api-v3/index

Defines the top-level settings for a single Kanban board, including card template and power-up configurations.

```APIDOC
Board.Settings:
  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 Object API Documentation

Source: https://kanbantool.com/developer/api-v3/index

Defines a single board, containing basic data like name and position, and relationships like tasks or changelogs. Includes fields such as id, version, name, description, and related objects like card_types, swimlanes, and settings.

```APIDOC
Board (object):
  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).

  Fields:
    id (integer): Board's unique identifier.
    version (integer): Board's version. Counted from 1.
    external_id_sequence (?integer): Board's custom id, optional. Can be used to keep track of the board when synchronizing with other platforms.
    board_template_id (string): 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): Board's folder id, if it belongs to any.
    owner_id (integer): Id of the user who owns this board.
    position (integer): Board's position in the list of all the boards. Counted from 1.
    name (string): Board's name.
    description (string): Board's description.
    last_activity_on (date): Date of latest activity on the board.
    settings_updated_at (?dateTime): Date & time when board's settings were updated for the last time - if they have been updated.
    created_at (dateTime): Date & time when board's been created.
    updated_at (dateTime): Date & time when board's been updated for the last time.
    deleted_at (?dateTime): Date & time when board's been deleted - if it's been deleted.
    card_template (Board.Settings.CardTemplateField[]): Data of the card template which belongs to this board. A shortcut for board.settings.card_template.
    card_types (CardType[]): List of all the card types which belong to this board.
    swimlanes (Swimlane[]): List of all the swimlanes which belong to this board.
    workflow_stages (WorkflowStage[]): List of all the workflow stages which belong to this board.
    tasks (Task[]): List of all the tasks which belong to this board.
    settings (Board.Settings): Data of the board's settings.
    stats (Board.Statistic[]): List of all the board's statistics.
    collaborators (Collaborator[]): List of all the board's collaborators.
    changelogs (Changelog[]): List of all the changelogs which belong to this board.
```

--------------------------------

### API Request Methods

Source: https://kanbantool.com/developer/api-v3/index

Details common HTTP methods used for API requests, including DELETE and POST. It also explains the use of the `_m` parameter as an alternative for specifying request methods.

```APIDOC
DELETE /api/v3/some_action.json

POST /api/v3/some_action.json

# Using the _m parameter for method specification:
GET /api/v3/some_action.json?_m=delete
```

--------------------------------

### Fetch Task Details with cURL

Source: https://kanbantool.com/developer/api-v3/index

Shows how to retrieve detailed information for a specific task using the cURL command-line tool. This method requires authentication via a Bearer token and specifies the API endpoint for preloading task data.

```shell
curl 'https://YOUR_DOMAIN.kanbantool.com/api/v3/tasks/:task_id/preload.json' \
  -H 'Authorization: Bearer ...'
```

--------------------------------

### Fetch Current User via Browser URL

Source: https://kanbantool.com/developer/api-v3/index

Illustrates how to access the current user's information by directly entering the API endpoint URL in a web browser's address bar, including the access token.

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

--------------------------------

### Kanban Tool API v3 - Users

Source: https://kanbantool.com/developer/api-v3/index

Provides endpoints for managing users, including fetching a list of all users and retrieving details for the currently authenticated user.

```APIDOC
Users:
  GET /users
    - Lists all accessible users.
    - Requires authentication.
    - Returns a list of User objects.

  GET /users/me
    - Fetches details of the currently authenticated user.
    - Requires authentication.
    - Returns a User object.
```

--------------------------------

### Kanban Tool API v3 - Object References

Source: https://kanbantool.com/developer/api-v3/index

Details the structure and fields for various objects used within the API, such as Board, Task, User, and Comment.

```APIDOC
Objects Reference:

Board (object):
  id (integer): Unique identifier for the board.
  name (string): Name of the board.
  description (string): Description of the board.
  created_at (datetime): Timestamp when the board was created.
  updated_at (datetime): Timestamp when the board was last updated.
  settings (Board.Settings): Nested object containing board settings.

Board.Settings (nested object):
  swimlanes_enabled (boolean): Whether swimlanes are enabled.
  card_types_enabled (boolean): Whether custom card types are enabled.

Card Type (object):
  id (integer): Unique identifier for the card type.
  name (string): Name of the card type.

Changelog (object):
  id (integer): Unique identifier for the changelog entry.
  timestamp (datetime): Timestamp of the change.
  user (User): User who made the change.
  type (string): Type of change (e.g., 'task_created', 'task_updated').
  details (object): Specific details about the change.

Collaborator (object):
  id (integer): Unique identifier for the collaborator.
  name (string): Name of the collaborator.
  email (string): Email address of the collaborator.

Comment (object):
  id (integer): Unique identifier for the comment.
  task_id (integer): ID of the task the comment belongs to.
  user (User): User who posted the comment.
  content (string): The text content of the comment.
  created_at (datetime): Timestamp when the comment was created.

Subtask (object):
  id (integer): Unique identifier for the subtask.
  task_id (integer): ID of the parent task.
  title (string): Title of the subtask.
  completed (boolean): Status of the subtask.
  created_at (datetime): Timestamp when the subtask was created.

Task (object):
  id (integer): Unique identifier for the task.
  board_id (integer): ID of the board the task belongs to.
  title (string): Title of the task.
  description (string): Detailed description of the task.
  status (string): Current status of the task (e.g., 'Open', 'In Progress').
  priority (string): Priority level of the task.
  due_date (date): Due date for the task.
  created_at (datetime): Timestamp when the task was created.
  updated_at (datetime): Timestamp when the task was last updated.
  recurring_schedule (Task.RecurringSchedule): Nested object for recurring task settings.

Task.RecurringSchedule (nested object):
  frequency (string): Frequency of recurrence (e.g., 'daily', 'weekly').
  interval (integer): Interval for the frequency.
  end_date (date): Date when recurrence stops.

User (object):
  id (integer): Unique identifier for the user.
  name (string): Full name of the user.
  email (string): Email address of the user.
  avatar_url (string): URL to the user's avatar.

Workflow Stage (object):
  id (integer): Unique identifier for the workflow stage.
  name (string): Name of the workflow stage.
  order (integer): Order of the stage in the workflow.
```

--------------------------------

### Kanban Tool API v3 - Boards

Source: https://kanbantool.com/developer/api-v3/index

Enables operations related to boards, such as listing accessible boards, fetching board details, and retrieving board changelogs.

```APIDOC
Boards:
  GET /boards
    - Lists all boards accessible by the authenticated user.
    - Requires authentication.
    - Returns a list of Board objects.

  GET /boards/{board_id}
    - Fetches detailed information about a specific board.
    - Requires authentication.
    - Parameters:
      - board_id (integer): The ID of the board to fetch.
    - Returns a Board object.

  GET /boards/{board_id}/changelog
    - Retrieves the changelog for a specific board.
    - Requires authentication.
    - Parameters:
      - board_id (integer): The ID of the board.
    - Returns a list of Changelog objects.
```

--------------------------------

### API: Type Reference

Source: https://kanbantool.com/developer/api-v3/index

Explains the data types used within the Kanban Tool API, including their format and potential nullability or array structures. This helps in understanding request and response payloads.

```APIDOC
Types Reference

Our API utilizes following types:

| Type     | Description                                                                 |
|----------|-----------------------------------------------------------------------------|
| boolean  | `true` or `false`                                                           |
| date     | date in [`Y-m-d` format](https://php.net/manual/en/function.date.php)        |
| dateTime | date in [`c` format](https://php.net/manual/en/function.date.php)            |
| float    | a floating-point number with `.` used as the separator                      |
| integer  | a 32-bit signed integer                                                     |
| string   | an UTF-8 string of variadic length                                          |

Some fields may also contain a `null` value, which is annotated with the `?` prefix.
For example, `?dateTime` means that the following field may contain a valid `dateTime`
value, a `null`, or may not be present in the request/response at all.

Additionally, some fields may be arrays, which is annotated with the `[]` suffix.
For example, `integer[]` represents an integer array.
```

--------------------------------

### Board.Settings.PowerUp Object

Source: https://kanbantool.com/developer/api-v3/index

The base object for power-up settings, allowing each power-up to define its own configuration. Primarily used for enabling/disabling.

```APIDOC
Board.Settings.PowerUp:
  enabled: boolean
    - If true, the power-up is enabled.
```

--------------------------------

### Kanban Tool API v3 - Time Trackers

Source: https://kanbantool.com/developer/api-v3/index

Provides functionality for managing time tracking entries for the current user, including listing, creating, updating, and deleting time entries.

```APIDOC
Time Trackers:
  GET /time_trackers
    - Lists all time tracking entries for the current user.
    - Requires authentication.
    - Returns a list of Time Tracker objects.

  POST /time_trackers
    - Creates a new time tracking entry.
    - Requires authentication.
    - Parameters:
      - time_tracker_data (object): Details of the time entry (e.g., task_id, start_time, end_time).
    - Returns the created Time Tracker object.

  PUT /time_trackers/{time_tracker_id}
    - Updates an existing time tracking entry.
    - Requires authentication.
    - Parameters:
      - time_tracker_id (integer): The ID of the time tracker.
      - time_tracker_data (object): Updated time entry details.
    - Returns the updated Time Tracker object.

  DELETE /time_trackers/{time_tracker_id}
    - Deletes a specific time tracking entry.
    - Requires authentication.
    - Parameters:
      - time_tracker_id (integer): The ID of the time tracker.
    - Returns a success status.
```

--------------------------------

### Kanban Tool API v3 Authentication and Access

Source: https://kanbantool.com/developer/api-v3/index

Explains how to obtain an API access token for authenticating requests to the Kanban Tool API. The token is personal and should be kept secure.

```APIDOC
API Access Token Generation:
1. Navigate to 'My profile' in the main menu.
2. Click on the 'API access' link.
3. Click the 'Enable API access' button to generate a new token.
4. Securely store the generated token for use in API requests.
```

```cURL
curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" https://kanban.example.com/api/v3/users/me
```

```JavaScript
const token = 'YOUR_ACCESS_TOKEN';
const apiUrl = 'https://kanban.example.com/api/v3';

// Example using fetch API
fetch(`${apiUrl}/users/me`, {
  headers: {
    'Authorization': `Bearer ${token}`
  }
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));
```

--------------------------------

### API Response Formats

Source: https://kanbantool.com/developer/api-v3/index

Explains how the API supports JSON and JSONP response formats, determined by the file extension or query parameters. XML format is not supported for API v3.

```APIDOC
# JSON response (default):
GET /api/v3/some_action.json?parameter=value

# JSONP response:
GET /api/v3/some_action.json?callback=myFunction&parameter=value
```

--------------------------------

### Search Tasks (API)

Source: https://kanbantool.com/developer/api-v3/index

Allows searching across all accessible tasks with various filtering options. Supports full-text search, pagination, and filtering by board ID or archived status.

```APIDOC
GET /api/v3/tasks/search.json

---

**Parameters**:

| Parameter    | Type     | Required | Description                                                                 |
|--------------|----------|----------|-----------------------------------------------------------------------------|
| `q`          | string   | Yes      | Query used to filter tasks. May be an empty string.                         |
| `limit`      | integer  | No       | Maximum number of items to return, or items per page if `page` is given.    |
| `page`       | integer  | No       | Page number for paginated results.                                          |
| `board_id`   | string   | No       | Comma-separated list of board IDs to narrow the search.                     |
| `archived`   | integer  | No       | Set to `1` to search through archived tasks.                                |

---

**Response**:

Returns a list of task objects matching the search criteria.
```

```curl
curl 'https://YOUR_DOMAIN.kanbantool.com/api/v3/tasks/search.json' \
  -H 'Authorization: Bearer ...'
```

--------------------------------

### Create Attachment (JavaScript)

Source: https://kanbantool.com/developer/api-v3/index

Uploads a file and optionally binds it to a Kanban Tool object like a task or board. Requires a callback function to handle the response.

```JavaScript
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',
});
```

--------------------------------

### Kanban Tool API v3 Time Tracker Operations

Source: https://kanbantool.com/developer/api-v3/index

Defines the API endpoints for creating and updating time trackers. Includes request methods, URL paths, parameter details, expected responses, and common error conditions.

```APIDOC
POST /api/v3/time_trackers.json
  - Creates a new time tracker.
  - Request Body Parameters:
    - board_id (integer, Required): The ID of the board.
    - task_id (integer, Required): The ID of the task.
    - position (?integer, Optional): The position of the tracker (defaults to 1).
    - listed (boolean, Optional): Whether the tracker is listed (defaults to true).
    - started_at (dateTime, Optional): The start time of the tracker (defaults to current date and time).
    - ended_at (?dateTime, Optional): The end time of the tracker (defaults to null).
    - highlighted_at (?dateTime, Optional): The highlighted time of the tracker (defaults to null).
  - Response:
    - Returns a time tracker object on success.
  - Errors:
    - 404 Not Found: Invalid board_id or task_id.
    - 422 Unprocessable Entity: Invalid input data (e.g., ended_at in past, wrong date format).

PUT /api/v3/time_trackers/:time_tracker_id.json
  - Updates an existing time tracker.
  - Request Body Parameters:
    - position (?integer, Optional): The position of the tracker.
    - listed (boolean, Optional): Whether the tracker is listed.
    - started_at (?dateTime, Optional): The start time of the tracker.
    - ended_at (?dateTime, Optional): The end time of the tracker.
    - highlighted_at (?dateTime, Optional): The highlighted time of the tracker.
  - Response:
    - Returns the updated time tracker object on success.
  - Errors:
    - 400 Bad Request: No time_tracker parameter in request.
    - 404 Not Found: Invalid time_tracker_id.
    - 422 Unprocessable Entity: Invalid date input (e.g., ended_at in past).
```

--------------------------------

### Kanban Tool API v3 - Attachments

Source: https://kanbantool.com/developer/api-v3/index

Manages attachments for tasks, including listing, creating, detaching, and setting attachment modes.

```APIDOC
Attachments:
  GET /tasks/{task_id}/attachments
    - Lists all attachments for a specific task.
    - Requires authentication.
    - Parameters:
      - task_id (integer): The ID of the task.
    - Returns a list of Attachment objects.

  POST /tasks/{task_id}/attachments
    - Uploads and attaches a file to a task.
    - Requires authentication.
    - Parameters:
      - task_id (integer): The ID of the task.
      - file (file): The file to upload.
    - Returns the created Attachment object.

  DELETE /attachments/{attachment_id}
    - Detaches (removes) an attachment from a task.
    - Requires authentication.
    - Parameters:
      - attachment_id (integer): The ID of the attachment.
    - Returns a success status.

  PUT /attachments/{attachment_id}/mode
    - Sets the mode attribute for an attachment.
    - Requires authentication.
    - Parameters:
      - attachment_id (integer): The ID of the attachment.
      - mode_data (object): Object containing the new mode (e.g., {"mode": "thumbnail"}).
    - Returns the updated Attachment object.
```

--------------------------------

### Create Subtask (JavaScript)

Source: https://kanbantool.com/developer/api-v3/index

Demonstrates how to create a new subtask associated with a specific task using the Kanban Tool JavaScript SDK. It shows stubbing a task and then creating a subtask with a name.

```javascript
const task = KT.tasks.stub(TASK_ID);

const subtask = task.subtasks().create({
    name: 'Take out the bread.',
});

console.log(subtask);
```

--------------------------------

### List Board Tasks (API)

Source: https://kanbantool.com/developer/api-v3/index

Fetches the details of a specific board, which includes a list of all its associated tasks. Unlike previous versions, this API requires fetching the entire board object to access tasks.

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

---

**Description**:

Fetches the details of a specific board, including its tasks. To get archived tasks, use the task search endpoint with `archived=1`.
```

```curl
curl 'https://YOUR_DOMAIN.kanbantool.com/api/v3/boards/:board_id.json' \
  -H 'Authorization: Bearer ...'
```

--------------------------------

### Fetch Board Details (Including Tasks)

Source: https://kanbantool.com/developer/api-v3/index

Retrieves detailed information about a specific board, including all its tasks and subtasks. This can result in a large response payload, so use with caution if tasks are not needed.

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

Description:
  Returns detailed information about a given board and its tasks.
  This command returns the board's tasks and their subtasks.

Parameters:
  - :board_id (integer): The unique identifier for the board.

Request Headers:
  - Authorization: Bearer YOUR_API_TOKEN

Response:
  - 200 OK: Returns a board object containing detailed information and tasks.
    Example Response Structure:
    {
      "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": { ... }
    }
  - 404 Not Found: Returned when the provided :board_id is invalid.

Example Usage (JavaScript):
KT.boards.stub(BOARD_ID).load().then((board) => {
    console.log(board);
});

Example Usage (cURL):
curl 'https://YOUR_DOMAIN.kanbantool.com/api/v3/boards/:board_id.json' \
  -H 'Authorization: Bearer ...'
```

--------------------------------

### Search Tasks (JavaScript)

Source: https://kanbantool.com/developer/api-v3/index

Searches through all tasks the user has access to using the KT JavaScript library. It requires a query string and can optionally filter by board ID or include archived tasks.

```javascript
KT.call('GET', 'tasks/search', {
  q: YOUR_QUERY,
});
```

--------------------------------

### Kanban Tool API v3 - Subtasks

Source: https://kanbantool.com/developer/api-v3/index

Manages subtasks associated with main tasks, including listing, creating, updating, deleting, and reordering subtasks.

```APIDOC
Subtasks:
  GET /tasks/{task_id}/subtasks
    - Lists all subtasks for a given task.
    - Requires authentication.
    - Parameters:
      - task_id (integer): The ID of the parent task.
    - Returns a list of Subtask objects.

  POST /tasks/{task_id}/subtasks
    - Creates a new subtask for a given task.
    - Requires authentication.
    - Parameters:
      - task_id (integer): The ID of the parent task.
      - subtask_data (object): Subtask details (e.g., title).
    - Returns the created Subtask object.

  PUT /subtasks/{subtask_id}
    - Updates an existing subtask.
    - Requires authentication.
    - Parameters:
      - subtask_id (integer): The ID of the subtask.
      - subtask_data (object): Updated subtask details.
    - Returns the updated Subtask object.

  DELETE /subtasks/{subtask_id}
    - Deletes a specific subtask.
    - Requires authentication.
    - Parameters:
      - subtask_id (integer): The ID of the subtask.
    - Returns a success status.

  POST /tasks/{task_id}/subtasks/reorder
    - Reorders subtasks for a given task.
    - Requires authentication.
    - Parameters:
      - task_id (integer): The ID of the parent task.
      - order_data (array): An array of subtask IDs in the desired order.
    - Returns a success status.
```

--------------------------------

### List Board Changelogs (JavaScript)

Source: https://kanbantool.com/developer/api-v3/index

Retrieves the changelog for a specific KanbanTool board using the KT JavaScript library. It demonstrates two common methods for loading board data and accessing its changelogs.

```javascript
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')
    );
});
```

--------------------------------

### List Board Changelogs (API)

Source: https://kanbantool.com/developer/api-v3/index

Fetches a list of changelogs for a given board via the KanbanTool API. Supports filtering by changelog ID using 'before' or 'after' parameters and limiting the number of results.

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

---

**Parameters**:

| Parameter | Type    | Required | Description                                      |
|-----------|---------|----------|--------------------------------------------------|
| `before`  | integer | Yes      | Returns only changelogs matching `id < :before`. |
| `after`   | integer | Yes      | Returns only changelogs matching `id > :after`.  |
| `limit`   | integer | No       | Maximum number of items to return.               |

---

**Response**:

Returns a list of changelog objects.

---

**Errors**:

- `404 Not Found`: If an invalid `board_id` is provided.
```

```curl
curl 'https://YOUR_DOMAIN.kanbantool.com/api/v3/boards/:board_id/changelog.json' \
  -H 'Authorization: Bearer ...' \
  -d 'before=100000000'
```

--------------------------------

### Create Attachment (cURL)

Source: https://kanbantool.com/developer/api-v3/index

Creates an attachment using cURL, uploading a file via multipart/form-data and specifying the attachable object. Requires an Authorization header.

```curl
curl 'https://YOUR_DOMAIN.kanbantool.com/api/v3/attachments.json' \
  -X 'POST' \
  -H 'Authorization: Bearer ...' \
  -F 'files[]=@fileName.png' \
  -F 'attachable=Board#100000'
```
Tokens:
Raw