You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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.
(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:
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:
A 403 response might be returned if the users ability to create new boards has been disabled by the administrator. For checking this before, see the canCreateBoards value in the Nextcloud capabilties.
GET /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments/{attachmentId} - Get the attachment file
Request parameters
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
Response
200 Success
POST /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments - Upload an attachment
Request parameters
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
Request data
Parameter
Type
Description
type
String
The type of the attachement
file
Binary
File data to add as an attachment
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
Response
200 Success
PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments/{attachmentId} - Update an attachment
Request parameters
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
Request data
Parameter
Type
Description
type
String
The type of the attachement
file
Binary
File data to add as an attachment
For now only deck_file is supported as an attachment type.
Response
200 Success
DELETE /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments/{attachmentId} - Delete an attachment
Request parameters
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
Response
200 Success
PUT /boards/{boardId}/stacks/{stackId}/cards/{cardId}/attachments/{attachmentId}/restore - Resore a deleted attachment
Request parameters
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
Response
200 Success
GET /boards/import/getSystems - Import a board
Request parameters
Parameter
Type
Description
system
Integer
The system name. Example: trello
Response
Make a request to see the json schema of system
{
}
GET /boards/import/config/system/{schema} - Import a board
Request parameters
Response
[
"trello"
]
POST /boards/import - Import a board
Request parameters
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)
Response
200 Success
OCS API
The following endpoints are available through the Nextcloud OCS endpoint, which is available at /ocs/v2.php/apps/deck/api/v1.0/.
This has the benefit that both the web UI as well as external integrations can use the same API.
Config
Deck stores user and app configuration values globally and per board. The GET endpoint allows to fetch the current global configuration while board settings will be exposed through the board element on the regular API endpoints.
GET /api/v1.0/config - Fetch app configuration values
Response
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)
In case a comment is marked as a reply to another comment object, the parent comment will be added as replyTo entry to the response. Only the next parent node is added, nested replies are not exposed directly.
[
{
"id": 175,
"objectId": 12,
"message": "This is a comment with a mention to @alice",
"actorId": "admin",
"actorType": "users",
"actorDisplayName": "Administrator",
"creationDateTime": "2020-03-10T10:23:07+00:00",
"mentions": [
{
"mentionId": "alice",
"mentionType": "user",
"mentionDisplayName": "alice"
}
],
"replyTo": {
"id": 175,
"objectId": 12,
"message": "This is a comment with a mention to @alice",
"actorId": "admin",
"actorType": "users",
"actorDisplayName": "Administrator",
"creationDateTime": "2020-03-10T10:23:07+00:00",
"mentions": [
{
"mentionId": "alice",
"mentionType": "user",
"mentionDisplayName": "alice"
}
]
}
}
]
POST /cards/{cardId}/comments - Create a new comment
Request parameters
Parameter
Type
Description
cardId
Integer
The id of the card
message
String
The message of the comment, maximum length is limited to 1000 characters
parentId
Integer
(optional) The start offset used for pagination, defaults to null
Mentions will be parsed by the server. The server will return a list of mentions in the response to this request as shown below.
curl -X POST 'https://admin:admin@nextcloud/ocs/v2.php/apps/deck/api/v1.0/cards/12/comments' \
-H 'Accept: application/json' -H 'OCS-APIRequest: true'
-H 'Content-Type: application/json;charset=utf-8'
--data '{"message":"My message to @bob","parentId":null}'
Response
A list of comments will be provided under the ocs.data key. If no or no more comments are available the list will be empty.