Update a card

PATCH /io/card/:cardId

Update a card's fields. This endpoint supports ISO 6902 JSON Patch. Concurrency checks are implemented via a version number that may be specified either in an x-lk-resource-version header or in a json patch test operation against path /version in the body. If no version number is specified, the concurrency check will be skipped.

Operations

Operation	Description
`replace`	Update the field value.
`add`	Add the field value. `replace` and `add` are interchangeable in many cases.
`remove`	Remove the field value.
`test`	Check the field value for a match. This is most commonly used with `version` to handle concurrency issues.

Request Properties

Param	Type	Usage
`title`	string	The card title.
`typeId`	string	The card type.
`assignedUserIds`	string array	Collection of assigned users.
`blockReason`	string	The block reason. This should be specified with the `isBlocked` property operation in the same request.
`customIconId`	string	The custom icon.
`customId`	string	The card header.
`customFields`	object array	Collection of custom fields. Each field has a string `fieldId` and string `value` property.
`description`	string	The card description
`externalLink`	object	External link object with string `label` and string `url` fields.
`index`	integer	The position of the card in the lane starting at 0 as the first position.
`isBlocked`	boolean	The blocked state of the card. Should be specified with the `blockReason` property operation in the same request.
`laneId`	string	The lane id that the card should be moved to.
`parentCardId`	string	The parent card.
`plannedStart`	date	The planned start date in the format YYYY-MM-DD
`plannedFinish`	date	The planned finish date in the format YYYY-MM-DD.
`planningIncrementIds`	string array	Collection of planning increment ids.
`mirrorSourceCardId`	string	The card that is the source for mirroring title, description and customId to this card.
`size`	string	The card size.
`tags`	string array	Collection of tags.
`wipOverrideComment`	string	The WIP override comment. This should be specified with a `laneId` update operation that would violate a WIP limit.
`version`	string	The card version. This can not be set. It is used with a `test` operation to validate that the card was not modified.

Example Request

Updating a single field

1[
2  { "op": "replace", "path": "/title", "value": "updated card title" }
3]

Change two fields at once

1[
2  { "op": "replace", "path": "/description", "value": "updated card description" },
3  { "op": "replace", "path": "/typeId", "value": "944576315" }
4]

All fields that can be updated

01[
02  { "op": "replace", "path": "/title", "value": "Title here" },
03  { "op": "replace", "path": "/typeId", "value": "944576315" },
04  { "op": "add", "path": "/assignedUserIds/1", "value": "583458214" },
05  { "op": "add", "path": "/blockReason", "value": "This card is blocked" },
06  { "op": "replace", "path": "/customIconId", "value": "944576318" },
07  { "op": "replace", "path": "/customId", "value": "The header" },
08  { "op": "add", "path": "/customFields/0", "value": {
09      "fieldId": "945250752",
10      "value": "Custom field value"
11  } },
12  { "op": "replace", "path": "/description", "value": "The description" },
13  { "op": "add", "path": "/externalLink", "value": {
14      "label": "Link label",
15      "url": "https://www.leankit.com"
16  } },
17  { "op": "replace", "path": "/index", "value": 0 },
18  { "op": "replace", "path": "/isBlocked", "value": true },
19  { "op": "replace", "path": "/laneId", "value": "944576328" },
20  { "op": "replace", "path": "/parentCardId", "value": "945265884" },
21  { "op": "replace", "path": "/plannedStart", "value": "2024-01-01" },
22  { "op": "replace", "path": "/plannedFinish", "value": "2024-12-31" },
23  { "op": "remove", "path": "/mirrorSourceCardId", "value": "945265884" },
24  { "op": "replace", "path": "/size", "value": 5 },
25  { "op": "remove", "path": "/tags/0" },
26  { "op": "replace", "path": "/wipOverrideComment", "value": "Override wip" },
27  { "op": "add", "path": "/planningIncrementIds/-", "value": "94114176565" }
28  { "op": "test", "path": "/version", "value": "11" }
29]

Verify the card hasn't changed before updating the custom header id. If the version specified in the test operation does not match the server version a http 428 Unknown response will be returned with the message Optimistic concurrency check failed.

1[
2  { "op": "test", "path": "/version", "value": "8"  },
3  { "op": "replace", "path": "/customId", "value": "new card header"  }
4]

Working With Collections

This example removes the first tag. Positions start at 0.

1[
2  { "op": "remove", "path": "/tags/0" }
3]

This example removes a tag by value. It will remove the tag "red", regardless of where it appears in the tag list.

1[
2  { "op": "remove", "path": "/tags", "value": "red"}
3]

Specifying - as the position adds an item to the end of the collection.

1[
2  { "op": "add", "path": "/tags/-", "value": "end tag" }
3]

Edit the tag in the second position.

1[
2  { "op": "replace", "path": "/tags/1", "value": "edit tag" }
3]

Example Successful Response

200 OK

001{
002    "actualFinish": "2019-12-06T21:25:45Z",
003    "actualStart": "2019-12-06T21:25:45Z",
004    "blockedStatus": {
005        "isBlocked": true,
006        "reason": "The block reason",
007        "date": "2019-12-06T21:07:34Z"
008    },
009    "board": {
010        "id": "944576308",
011        "title": "Sample Board",
012        "version": "65",
013        "isArchived": false
014    },
015    "customIcon": {
016        "id": "944576317",
017        "title": "Date Dependent",
018        "cardColor": "#FFFFFF",
019        "iconColor": "212121",
020        "iconName": "lk_icons_final_01-13",
021        "iconPath": "https://myaccount.leankit.com/customicons/24/212121/lk_icons_final_01-13.png",
022        "policy": ""
023    },
024    "customIconLabel": "Class of Service",
025    "color": "#B8CFDF",
026    "iconPath": null,
027    "createdOn": "2019-12-06T21:07:34Z",
028    "archivedOn": null,
029    "description": "The card description",
030    "plannedFinish": null,
031    "customId": {
032        "value": "Card header text",
033        "prefix": null,
034        "url": null
035    },
036    "externalLinks": [
037        {
038            "label": "The link label",
039            "url": "https://www.leankit.com"
040        }
041    ],
042    "id": "945261794",
043    "index": 2,
044    "lane": {
045        "cardLimit": 0,
046        "description": null,
047        "id": "944576330",
048        "index": 2,
049        "laneClassType": "active",
050        "laneType": "inProcess",
051        "orientation": "vertical",
052        "title": "Under Review",
053        "taskBoard": null,
054        "cardStatus": "started"
055    },
056    "updatedOn": "2019-12-06T22:50:32Z",
057    "movedOn": "2019-12-06T21:37:11Z",
058    "priority": "normal",
059    "size": 1,
060    "plannedStart": null,
061    "tags": [
062        "tagOne",
063        "tagTwo"
064    ],
065    "title": "updated card title",
066    "version": "8",
067    "type": {
068        "id": "944576314",
069        "title": "New Feature",
070        "cardColor": "#B8CFDF"
071    },
072    "taskBoardStats": {
073        "totalCount": 1,
074        "completedCount": 0,
075        "totalSize": 1,
076        "completedSize": 0
077    },
078    "subscriptionId": "945261795",
079    "createdBy": {
080        "id": "478440842",
081        "emailAddress": "user@leankit.com",
082        "fullName": "First Last",
083        "avatar": "https://myaccount.leankit.com/avatar/Show/478440842?s=25"
084    },
085    "updatedBy": {
086        "id": "478440842",
087        "emailAddress": "user@leankit.com",
088        "fullName": "First Last",
089        "avatar": "https://myaccount.leankit.com/avatar/Show/478440842?s=25"
090    },
091    "movedBy": {
092        "id": "478440842",
093        "emailAddress": "user@leankit.com",
094        "fullName": "First Last",
095        "avatar": "https://myaccount.leankit.com/avatar/Show/478440842?s=25"
096    },
097    "archivedBy": null,
098    "assignedUsers": [
099        {
100            "id": "478440842",
101            "emailAddress": "user@leankit.com",
102            "fullName": "First Last",
103            "firstName": "First",
104            "lastName": "Last",
105            "avatar": "https://myaccount.leankit.com/avatar/Show/478440842?s=25"
106        }
107    ],
108    "attachments": [],
109    "comments": [],
110    "parentCards": [
111        {
112            "cardId": "945202295",
113            "boardId": "944576308"
114        }
115    ],
116    "mirrorSourceCardId": "945265884",
117    "customFields": [
118        {
119            "fieldId": "945250752",
120            "type": "text",
121            "label": "Custom Field Label",
122            "value": "This is the field value"
123        }
124    ],
125    "planningIncrements": [
126        {
127          "id": "94114176565",
128          "label": "PI-2",
129          "startDate": "2021-12-01T00:00:00.000Z",
130          "endDate": "2021-12-25T00:00:00.000Z",
131          "series": {
132              "id": "94114169089",
133              "label": "Series 1",
134              "timeZone": "Etc/GMT"
135          },
136          "parent": null
137      }
138    ],
139    "connectedCardStats": {
140        "startedCount": 0,
141        "startedSize": 0,
142        "notStartedCount": 1,
143        "notStartedSize": 1,
144        "completedCount": 0,
145        "completedSize": 0,
146        "blockedCount": 0,
147        "totalCount": 1,
148        "totalSize": 1,
149        "plannedStart": null,
150        "plannedFinish": null,
151        "actualStart": null,
152        "actualFinish": null,
153        "pastDueCount": 0,
154        "projectedLateCount": 0
155    }
156}

Notable Error Responses

Status Code	Error Message	Reason
`428 Unknown`	Optimistic concurrency check failed	A version test operation was sent and failed because the card was modified by another transaction.