kanboard-sdk 1.2.0

Python SDK for the Kanboard JSON-RPC API — typed models, structured exceptions, and complete API coverage

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

Accessor	Methods	Description
client.tasks	14	Task CRUD, search, move, duplicate
client.projects	14	Project CRUD, enable/disable, activity
client.board	1	Full board view (columns → swimlanes → tasks)
client.columns	6	Column management and positioning
client.swimlanes	11	Swimlane management
client.comments	5	Task comments
client.categories	5	Project categories
client.tags	7	Global and project tags
client.subtasks	5	Subtask management
client.users	10	User administration
client.links	7	Link type definitions
client.task_links	5	Internal task-to-task links
client.external_task_links	7	External URL links on tasks
client.groups	5	Group management
client.group_members	5	Group membership
client.actions	6	Automatic action configuration
client.project_files	6	Project file attachments
client.task_files	6	Task file attachments
client.project_metadata	4	Project key-value metadata
client.task_metadata	4	Task key-value metadata
client.project_permissions	9	Project user/group permissions
client.subtask_time_tracking	4	Subtask time tracking
client.me	7	Current user (requires user auth)
client.application	7	Application info (version, colors, roles)

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)

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