Kanboard Python API Client

1.1.8 · active · verified Thu Apr 16

The `kanboard` library is a Python client for interacting with the Kanboard API (version 1.1.8). It provides both synchronous and asynchronous access to all Kanboard API methods, dynamically mapping Python calls to JSON-RPC procedures. The library is actively maintained with regular releases and requires Python 3.9 or higher.

Common errors

```
kanboard.ClientError: HTTP Error 403: Forbidden
```
cause This typically indicates an authorization issue. The user or API token used does not have the necessary permissions to perform the requested action. For 'jsonrpc' user, this could mean accessing 'My...' methods.

fix Ensure the API token or user credentials have the required permissions in Kanboard. For 'jsonrpc' user, remember it cannot access 'My...' procedures. Verify the API token is correct and active. Check Kanboard's server logs for more details on the 403 error.
```
kanboard.ClientError: HTTP Error 401: Not Authorized
```
cause Incorrect username or API token/password provided for authentication.

fix Double-check the `username` and `password` (or `API_TOKEN`) passed to `kanboard.Client`. Ensure they match an active Kanboard user or a valid API token. For users with 2FA, API keys must be used.
```
TypeError: Call takes no positional arguments but 1 positional argument was given
```
cause Kanboard client API methods expect named arguments only.

fix Refactor your API calls to use keyword arguments instead of positional arguments (e.g., `kb.create_project(name='My Project')` instead of `kb.create_project('My Project')`).

Warnings

breaking Support for Python 3.7 and 3.8 was dropped in version 1.1.7. Users on older Python versions will need to upgrade to Python 3.9+ or use an older version of the library.
Fix: Upgrade your Python environment to 3.9 or higher. If unable to upgrade, pin the `kanboard` library version to `<1.1.7` (e.g., `pip install kanboard==1.1.6`).
gotcha All Kanboard API methods, when called via the Python client, require named arguments. Positional arguments will not work.
Fix: Always pass arguments to API methods using their keyword names (e.g., `kb.create_project(name='My Project')` instead of `kb.create_project('My Project')`).
gotcha For asynchronous API calls, you must append `_async` to the method name (e.g., `kb.create_project_async`).
Fix: When using `async/await` syntax, ensure method names are suffixed with `_async` for asynchronous execution.
gotcha Kanboard instances configured with a custom authentication header require specifying the `auth_header` parameter during client initialization.
Fix: If your Kanboard `config.php` defines `API_AUTHENTICATION_HEADER`, pass `auth_header='X-Your-Custom-Header'` to the `kanboard.Client` constructor.

Install

pip install kanboard Install with pip

Imports

Client
```
from kanboard import Client
```
ClientError
```
from kanboard import ClientError
```
Used for catching API-specific errors.

Quickstart

This quickstart demonstrates how to initialize the Kanboard client and create a new project. It uses environment variables for the API URL, username, and token for secure credential management. It also includes basic error handling and a check to prevent duplicate project creation.

import os
import kanboard

KANBOARD_URL = os.environ.get('KANBOARD_API_URL', 'http://localhost/jsonrpc.php')
KANBOARD_USERNAME = os.environ.get('KANBOARD_API_USERNAME', 'jsonrpc') # Use 'jsonrpc' for application token
KANBOARD_API_TOKEN = os.environ.get('KANBOARD_API_TOKEN', 'your_api_token') # Or user password/personal access token

try:
    # Initialize the client, using 'jsonrpc' user and an API token
    with kanboard.Client(KANBOARD_URL, KANBOARD_USERNAME, KANBOARD_API_TOKEN) as kb:
        # Kanboard API calls expect named arguments
        # Check if project 'My Test Project' already exists to avoid creation error
        projects = kb.get_all_projects()
        project_exists = any(p.get('name') == 'My Test Project' for p in projects)

        if not project_exists:
            project_id = kb.create_project(name="My Test Project")
            print(f"Project 'My Test Project' created with ID: {project_id}")
        else:
            print("Project 'My Test Project' already exists.")

        # Example of getting current user information (requires user credentials, not 'jsonrpc' token)
        # If KANBOARD_USERNAME is an actual user, you could call:
        # me = kb.get_me()
        # print(f"Connected as: {me.get('username')}")

except kanboard.ClientError as e:
    print(f"An API or network error occurred: {e}")
except Exception as e:
    print(f"An unexpected error occurred: {e}")

view raw JSON →