For AI agents: markdown of this page — /docs-content-en/entities/tasks/checklist-actions/move-before.md documentation index — /llms.txt

Move an item before another

POST /v1/tasks/:taskId/checklist/:itemId/move-before

Moves a task checklist item and places it before another item.

Parameters

Parameter Type Required Description
ParametertaskId (path) Typenumber Requiredyes DescriptionTask ID, a positive integer. List: GET /v1/tasks
ParameteritemId (path) Typenumber Requiredyes DescriptionID of the item being moved, a positive integer. List: GET /v1/tasks/:taskId/checklist

Request fields (body)

Field Type Required Description
FieldbeforeItemId Typenumber Requiredyes DescriptionID of the item that the itemId item will be placed before, a positive integer. List: GET /v1/tasks/:taskId/checklist — it returns the ID as a string, such as "276", while this field needs a number

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/tasks/4218/checklist/274/move-before" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"beforeItemId": 276}'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/tasks/4218/checklist/274/move-before" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"beforeItemId": 276}'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/tasks/4218/checklist/274/move-before', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ beforeItemId: 276 }),
})

const { success, data } = await res.json()
console.log('New item position:', data?.checkListItem?.sortIndex)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/tasks/4218/checklist/274/move-before', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ beforeItemId: 276 }),
})

const { success, data } = await res.json()

Response fields

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue if the request succeeded
Fielddata Typeobject DescriptionResult with a single field, checkListItem
Fielddata.checkListItem Typeobject DescriptionThe moved item
Fielddata.checkListItem.id Typenumber DescriptionItem ID
Fielddata.checkListItem.taskId Typenumber DescriptionTask ID
Fielddata.checkListItem.parentId Typenumber DescriptionParent item ID. 0 means a top-level item, which is also the checklist name
Fielddata.checkListItem.title Typestring DescriptionItem text
Fielddata.checkListItem.sortIndex Typenumber DescriptionNew position of the item among items with the same parent. The smaller the value, the higher the item
Fielddata.checkListItem.displaySortIndex Typestring DescriptionDisplay number of the item. An empty string in the response
Fielddata.checkListItem.isComplete Typeboolean DescriptionWhether the item is complete
Fielddata.checkListItem.isImportant Typeboolean DescriptionWhether the item is marked important
Fielddata.checkListItem.completedCount Typenumber DescriptionArrives as 0 even when sub-items are complete. To check whether a sub-item is complete, use its isComplete in the item list
Fielddata.checkListItem.members Typearray DescriptionItem members. An empty array if there are none. For member roles, see Key fields
Fielddata.checkListItem.attachments Typearray | object DescriptionItem attachments. An empty array if there are none. For the object format, see Key fields
Fielddata.checkListItem.createdBy Typenumber DescriptionItem author ID. List: GET /v1/users
Fielddata.checkListItem.userId Typenumber DescriptionID of the employee on whose behalf the call is made. List: GET /v1/users
Fielddata.checkListItem.copiedId Typenumber | null DescriptionID of the source item if the item was created by copying. Otherwise null
Fielddata.checkListItem.nodeId Typestring | null DescriptionInternal node key. null in the response

Response example

JSON 
{
  "success": true,
  "data": {
    "checkListItem": {
      "id": 274,
      "copiedId": null,
      "userId": 1295,
      "createdBy": 1295,
      "parentId": 268,
      "title": "Agree on the date",
      "sortIndex": 0,
      "displaySortIndex": "",
      "isComplete": false,
      "isImportant": false,
      "completedCount": 0,
      "members": [],
      "attachments": [],
      "nodeId": null,
      "taskId": 4218
    }
  }
}

Error response example

422 — no item with the ID from beforeItemId:

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "Move item: action unavailable",
    "b24Code": "0"
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS DescriptiontaskId is not a positive integer. Message taskId must be a positive integer
HTTP400 CodeINVALID_PARAMS DescriptionitemId is not a positive integer. Message itemId must be a positive integer
HTTP400 CodeINVALID_PARAMS DescriptionThe body is not a JSON object, for example an array. Message JSON object body is required
HTTP400 CodeINVALID_PARAMS DescriptionbeforeItemId is missing, passed as a string, or is not a positive integer. Message beforeItemId must be a positive integer
HTTP401 CodeMISSING_API_KEY DescriptionX-Api-Key is not passed
HTTP401 CodeTOKEN_MISSING DescriptionThe key has no Bitrix24 tokens
HTTP403 CodeSCOPE_DENIED DescriptionThe key lacks the task scope
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is in read-only mode. error.details.switchUrl contains the URL of the section where the mode is changed
HTTP415 CodeFST_ERR_CTP_INVALID_MEDIA_TYPE DescriptionA body with a Content-Type the API does not parse, such as application/xml
HTTP422 CodeBITRIX_ERROR DescriptionThe task or the itemId item does not exist, or the employee on whose behalf the call is made cannot see the task. The message is in the Bitrix24 account language; on an English-language account it is Access to task was denied. The API specification declares 404 TASK_NOT_FOUND and 404 NOT_FOUND for this case, but the Bitrix24 accounts we tested return this response instead
HTTP422 CodeBITRIX_ERROR DescriptionNo item with the ID from beforeItemId. The message is in the Bitrix24 account language, for example "Move item: action unavailable"
HTTP422 CodeBITRIX_ERROR DescriptionbeforeItemId is a sub-item of the item being moved. The message is in the Bitrix24 account language, for example "Parent item cannot be a subitem of itself"
HTTP429 CodeRATE_LIMITED DescriptionRequest rate exceeded. The effective cap is in the x-ratelimit-limit header

Full list of common API errors — Errors.

Known specifics

The target item's number changes too. The moved item takes the sortIndex number of the beforeItemId item, and the number of the beforeItemId item increases by one. The response shows only the moved item; the new order of the other items is returned by GET /v1/tasks/:taskId/checklist.

See also