kanboard-sdk

Python SDK for the Kanboard JSON-RPC API — typed models, structured exceptions, and complete coverage of all 158 API methods.

Installation

pip install kanboard-sdk

Quick Start

from kanboard import KanboardClient

with KanboardClient(url="https://kanboard.example.com/jsonrpc.php",
                     token="your-api-token") as kb:
    # Create a project
    project_id = kb.projects.create_project(name="My Project")

    # Create a task
    task_id = kb.tasks.create_task(
        title="Implement feature X",
        project_id=project_id,
        color_id="green",
        priority=2,
    )

    # Get all active tasks
    tasks = kb.tasks.get_all_tasks(project_id, status_id=1)
    for task in tasks:
        print(f"#{task.id} [{task.color_id}] {task.title}")

Features

• Complete API coverage — All 158 Kanboard JSON-RPC methods across 24 resource categories
• Typed models — Dataclass response models with from_api() factory methods that handle Kanboard's type inconsistencies
• Structured exceptions — KanboardAuthError, KanboardNotFoundError, KanboardAPIError, etc. with rich context
• Resource-based access — client.tasks, client.projects, client.columns, etc.
• Context manager — KanboardClient supports with statements for clean resource management
• Batch calls — client.batch() for sending multiple JSON-RPC requests in one HTTP round-trip
• Cross-project orchestration — Portfolio management, milestones, dependency analysis, and critical-path computation via kanboard.orchestration
• Minimal dependencies — Only httpx

Resource Categories

Exception Hierarchy

KanboardError (base)
├── KanboardConfigError          # Missing/invalid configuration
├── KanboardConnectionError      # Network/connection failures
├── KanboardAuthError            # HTTP 401/403, invalid credentials
├── KanboardAPIError             # JSON-RPC error responses
│   ├── KanboardNotFoundError    # Resource not found (null response)
│   └── KanboardValidationError  # Invalid parameters
└── KanboardResponseError        # Malformed/unparseable responses

Configuration

KanboardClient accepts URL and token directly, or use KanboardConfig.resolve() for layered config resolution (TOML file → environment variables → explicit args):

from kanboard import KanboardClient, KanboardConfig

# Direct
client = KanboardClient(url="...", token="...")

# From config file / env vars
config = KanboardConfig.resolve()
client = KanboardClient(url=config.url, token=config.token)

Environment Variables

Portfolio Backend (Orchestration)

The orchestration layer (PortfolioManager, DependencyAnalyzer) supports two storage backends. Select via KanboardConfig or the create_backend() factory:

from kanboard import KanboardClient, KanboardConfig, create_backend
from kanboard.orchestration import PortfolioManager

config = KanboardConfig.resolve()  # reads portfolio_backend from env/config file

with KanboardClient(url=config.url, token=config.token) as kb:
    backend = create_backend(config.portfolio_backend, client=kb)
    manager = PortfolioManager(kb, backend)
    tasks = manager.get_portfolio_tasks("My Portfolio")

• "local" (default) — data stored in ~/.config/kanboard/portfolios.json; no plugin required; machine-local only
• "remote" — data stored server-side via the Kanboard Portfolio plugin; shared across all users

CLI Companion

For a full command-line interface built on this SDK, install kanboard-cli:

pip install kanboard-cli

Documentation

• SDK Guide — Full usage guide with examples for every resource
• Configuration — Config file, env vars, and profiles
• API Reference — Complete Kanboard JSON-RPC method signatures

License

MIT