Prerequisites

August 7, 2025 · View on GitHub

The REST API provides access for authenticated users to their data inside the Deck app. To get a better understanding of Decks data models and their relations, please have a look at the data structure documentation.

Prerequisites

All requests require a OCS-APIRequest HTTP header to be set to true and a Content-Type of application/json. This does not apply to the endpoint for uploading attachments, which consumes multipart/form-data.
The API is located at https://nextcloud.local/index.php/apps/deck/api/v1.0
All request parameters are required, unless otherwise specified

Naming

Board is the project like grouping of tasks that can be shared to different users and groups
Stack is the grouping of cards which is rendered in vertical columns in the UI
Card is the representation of a single task
Labels are defined on a board level and can be assigned to any number of cards

Global responses

400 Bad request

In case the request is invalid, e.g. because a parameter is missing or an invalid value has been transmitted, a 400 error will be returned:

{
  "status": 400,
  "message": "title must be provided"
}

403 Permission denied

In any case a user doesn't have access to a requested entity, a 403 error will be returned:

{
    "status": 403,
    "message": "Permission denied"
}

Formats

Date

Datetime values in request data need to be provided in ISO-8601. Example: 2020-01-20T09:52:43+00:00

Headers

If-Modified-Since

Some index endpoints support limiting the result set to entries that have been changed since the given time. The supported date formats are:

IMF-fixdate: Sun, 03 Aug 2019 10:34:12 GMT
(obsolete) RFC 850: Sunday, 03-Aug-19 10:34:12 GMT
(obsolete) ANSI C asctime(): Sun Aug 3 10:34:12 2019

It is highly recommended to only use the IMF-fixdate format. Note that according to RFC2616 all HTTP date/time stamps MUST be represented in Greenwich Mean Time (GMT), without exception.

Example curl request:

curl -u admin:admin -X GET \
    'http://localhost:8000/index.php/apps/deck/api/v1.0/boards/2/stacks' \
    -H "OCS-APIRequest: true" \
    -H "If-Modified-Since: Mon, 05 Nov 2018 09:28:00 GMT"

ETag

An ETag header is returned in order to determine if further child elements have been updated for the following endpoints:

Fetch all user board GET /api/v1.0/boards
Fetch a single board GET /api/v1.0/boards/{boardId}
Fetch all stacks of a board GET /api/v1.0/boards/{boardId}/stacks
Fetch a single stacks of a board GET /api/v1.0/boards/{boardId}/stacks/{stackId}
Fetch a single card of a board GET /api/v1.0/boards/{boardId}/stacks/{stackId}/cards/{cardId}
Fetch attachments of a card GET /api/v1.0/boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments

If a If-None-Match header is provided and the requested element has not changed a 304 Not Modified response will be returned.

Changes of child elements will propagate to their parents and also cause an update of the ETag which will be useful for determining if a sync is necessary on any client integration side. As an example, if a label is added to a card, the ETag of all related entities (the card, stack and board) will change.

If available the ETag will also be part of JSON response objects as shown below for a card:

{
  "id": 81,
  "ETag": "bdb10fa2d2aeda092a2b6b469454dc90",
  "title": "Test card"
}

Changelog

API version 1.0

Deck >=1.0.0: The maximum length of the card title has been extended from 100 to 255 characters
Deck >=1.0.0: The API will now return a 400 Bad request response if the length limitation of a board, stack or card title is exceeded

API version 1.1

This API version has become available with Deck 1.3.0.

The maximum length of the card title has been extended from 100 to 255 characters
The API will now return a 400 Bad request response if the length limitation of a board, stack or card title is exceeded
The attachments API endpoints will return other attachment types than deck_file
- Prior to Deck version v1.3.0 (API v1.0), attachments were stored within deck. For this type of attachments deck_file was used as the default type of attachments
- Starting with Deck version 1.3.0 (API v1.1) files are stored within the users regular Nextcloud files and the type file has been introduced for that

API version 1.2 (unreleased)

Endpoints for the new import functionality have been added:
The done property was added to cards

Endpoints

Boards

GET /boards - Get a list of boards

Headers

The board list endpoint supports setting an If-Modified-Since header to limit the results to entities that are changed after the provided time.

Request parameters

Parameter	Type	Description
details	Bool	Optional Enhance boards with details about labels, stacks and users

Parameter	Type	Description
title	String	The title of the new board, maximum length is limited to 100 characters
color	String	The hexadecimal color of the new board (e.g. FF0000)

Parameter	Type	Description
title	String	The title of the board, maximum length is limited to 100 characters
color	String	The hexadecimal color of the board (e.g. FF0000)
archived	Bool	Whether or not this board should be archived.

Parameter	Type	Description
boardId	Integer	The id of the board the card belongs to
stackId	Integer	The id of the stack the card belongs to
cardId	Integer	The id of the card

Parameter	Type	Description
type	Integer	Type of the participant
participant	String	The uid of the participant
permissionEdit	Bool	Setting if the participant has edit permissions
permissionShare	Bool	Setting if the participant has sharing permissions
permissionManage	Bool	Setting if the participant has management permissions

Parameter	Type	Description
withCards	Bool	Setting if the cards should be copied (Default: false)
withAssignments	Bool	Setting if the card assignments should be cloned (Default: false)
withLabels	Bool	Setting if the card labels should be cloned (Default: false)
withDueDate	Bool	Setting if the card due dates should be cloned (Default: false)
moveCardsToLeftStack	Bool	Setting if all cards should be moved to the most left column (useful for To-Do / Doing / Done boards) (Default: false)
restoreArchivedCards	Bool	Setting if the archived cards should be unarchived (Default: false)

Parameter	Type	Description
boardId	Integer	The id of the board the stack belongs to
stackId	Integer	The id of the stack

Parameter	Type	Description
title	String	The title of the new stack, maximum length is limited to 100 characters
order	Integer	Order for sorting the stacks

Parameter	Type	Description
title	String	The title of the stack, maximum length is limited to 100 characters
order	Integer	Order for sorting the stacks

Parameter	Type	Description
title	String	The title of the card, maximum length is limited to 255 characters
type	String	Type of the card (for later use) use 'plain' for now
order	Integer	Order for sorting the stacks
description	String	(optional) The markdown description of the card
duedate	timestamp	(optional) The duedate of the card or null

Parameter	Type	Description
order	Integer	The position in the stack where the card should be moved to
stackId	Integer	The id of the stack where the card should be moved to

Parameter	Type	Description
boardId	Integer	The id of the board the label belongs to
labelId	Integer	The id of the label

Parameter	Type	Description
boardId	Integer	The id of the board the attachment belongs to
stackId	Integer	The id of the stack the attachment belongs to
cardId	Integer	The id of the card the attachment belongs to
attachmentId	Integer	The id of the attachment

Parameter	Type	Description
type	String	The type of the attachement. Use `file` or `deck_file`.
file	Binary	File data to add as an attachment together with the `filename` parameter according to RFC 7578.

Parameter	Type	Description
type	String	The type of the attachement. For now only `deck_file` is supported as an attachment type.
file	Binary	File data to add as an attachment together with the `filename` parameter according to RFC 7578.

Parameter	Type	Description
system	string	The allowed name of system to import from
config	Object	The config object (JSON)
data	Object	The data object to import (JSON)

Config key	Description
calendar	Determines if the calendar/tasks integration through the CalDAV backend is enabled for the user (boolean)
cardDetailsInModal	Determines if the bigger view is used (boolean)
cardIdBadge	Determines if the ID badges are displayed on cards (boolean)
groupLimit	Determines if creating new boards is limited to certain groups of the instance. The resulting output is an array of group objects with the id and the displayname (Admin only)

Parameter	Type	Description
id	Integer	The id of the board
key	String	The config key to set, prefixed with `board:{boardId}:` for board specific settings
value	String	The value that should be stored for the config key

Key	Value
notify-due	`off`, `assigned` or `all`
calendar	Boolean
cardDetailsInModal	Boolean
cardIdBadge	Boolean

Parameter	Type	Description
boardId	Integer	The id of the opened board
token	String	The session token from the /sessions/create response