nextcloud-deck-client

A Python client for the Nextcloud Deck API, with both synchronous and asynchronous clients.

Install

pip install nextcloud-deck-client

Use

from ncdeck import DeckClient

deck = DeckClient("https://cloud.example.com", "username", "app-password", board_id=1)

for stack in deck.get_stacks():
    print(stack.title)
    for card in stack.cards:
        print("   ", card.title)

Async:

from ncdeck import AsyncDeckClient

deck = AsyncDeckClient("https://cloud.example.com", "username", "app-password")
boards = await deck.get_boards()

What it covers

Boards, stacks, cards, labels, comments and attachments. Cards can be created, updated, moved, archived, deleted and patched. The activity feed is exposed so callers can determine when a card was moved. DeckClient (sync) and AsyncDeckClient (async) expose the same methods with the same arguments — pick whichever matches your program and the two are interchangeable.

Two Deck quirks are handled for you:

• move_card() uses the documented update route addressed at the target stack, rather than the /cards/{id}/reorder endpoint, working around Deck issue #6830. The /reorder route makes Deck renumber every card in the target stack and stamp lastModified on all of them; move_card() avoids that, so lastModified stays a reliable signal for every other card in the stack.
• The activity endpoint answers HTTP 304 with an empty body when there is no data; get_deck_activity() returns an empty list rather than failing.

Changing a card without blanking it

Deck's card update endpoint treats every omitted field as a default, so a partial payload silently clears description and duedate. patch_card resends the card's full state with your changes applied:

card = next(c for c in stacks[0].cards if c.title == "Timeliste")
client.patch_card(card, done="2026-08-04T12:00:00+00:00")  # tick it
client.patch_card(card, done=None)  # un-tick it

move_card(card, stack_id, clear_done=True) moves a card and drops its done-tick in one request.

1.0.0 — breaking changes

• board_id moved to the last, optional parameter on every method of both DeckClient and AsyncDeckClient.
• move_card() now takes a Card instead of raw stack/card ids, and requires .source to be populated (fetch the card via get_stacks() first) — it raises ValueError otherwise. It no longer renumbers sibling cards, so several cards in the target stack may end up sharing order: 0.
• fetch_stacks() was removed in favour of get_stacks().

Authentication

Use a Nextcloud app password, not your account password.

Related tools

nextcloud-deck-cli is a set of command-line tools for Nextcloud Deck built on top of this library.

Licence

LGPL-3.0-or-later. See COPYING.LESSER.