# Move a task with ordering

`POST /v1/tasks/:taskId/move-stage`

Moves a task to a stage of its workgroup kanban or to a stage of the key owner's My Plan, and optionally places it before or after another task.

## Parameters

| Parameter | Type | Required | Description |
|----------|-----|:-----:|----------|
| `taskId` (path) | number | yes | ID of the task to move. List: [`GET /v1/tasks`](/docs/entities/tasks/list) |

## Request fields (body)

| Field | Type | Required | Description |
|------|-----|:-----:|----------|
| `stageId` | number | yes | ID of the target stage: a stage of the task's group kanban or a My Plan stage. List: [`GET /v1/tasks/stages/:entityId`](/docs/task-stages/list), with the group ID for a group and `0` for My Plan |
| `beforeTaskId` | number | no | ID of the task the moved task is placed before. A task from the same group when moving on the group kanban, or from My Plan when moving on the plan. Not sent together with `afterTaskId` |
| `afterTaskId` | number | no | ID of the task the moved task is placed after. Same conditions as `beforeTaskId`. Not sent together with `beforeTaskId` |

Any other body fields are rejected with `400 INVALID_PARAMS`.

## Examples

### curl — personal key

```bash
curl -X POST "https://vibecode.bitrix24.com/v1/tasks/4127/move-stage" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"stageId": 625, "beforeTaskId": 4125}'
```

### curl — OAuth application

```bash
curl -X POST "https://vibecode.bitrix24.com/v1/tasks/4127/move-stage" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"stageId": 625, "beforeTaskId": 4125}'
```

### JavaScript — personal key

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/tasks/4127/move-stage', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ stageId: 625, beforeTaskId: 4125 }),
})

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

### JavaScript — OAuth application

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/tasks/4127/move-stage', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ stageId: 625, beforeTaskId: 4125 }),
})

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

## Response fields

| Field | Type | Description |
|------|-----|----------|
| `success` | boolean | Always `true` on success |
| `data` | object | Move result |
| `data.taskId` | number | ID of the moved task |
| `data.stageId` | number | ID of the stage the task ended up on |
| `data.moved` | boolean | Always `true`: the move is verified by rereading the task |

## Response example

```json
{
  "success": true,
  "data": {
    "taskId": 4127,
    "stageId": 625,
    "moved": true
  }
}
```

## Error response example

409 — the task is not in the key owner's My Plan, the move was not performed:

```json
{
  "success": false,
  "error": {
    "code": "TASK_NOT_IN_PLAN",
    "message": "The task is not in your My Plan and was not moved"
  }
}
```

## Errors

| HTTP | Code | Description |
|------|-----|----------|
| 400 | `INVALID_PARAMS` | `taskId` or `stageId` is not a positive integer, or the body has other fields: `taskId and stageId must be positive integers` |
| 400 | `INVALID_PARAMS` | Both `beforeTaskId` and `afterTaskId` are sent: `Use either beforeTaskId or afterTaskId` |
| 400 | `INVALID_PARAMS` | The ordering task is the task being moved or is not a positive integer: `The ordering task must be a different positive task id` |
| 400 | `INVALID_PARAMS` | The stage belongs neither to the task's group kanban nor to My Plan: `stageId must belong to the task group or your My Plan` |
| 400 | `INVALID_PARAMS` | Moving on the group kanban, and the ordering task is from another group or does not exist: `Ordering task must belong to the same group` |
| 400 | `INVALID_PARAMS` | Moving on My Plan, and the ordering task is not in it: `Ordering task must belong to your My Plan` |
| 401 | `MISSING_API_KEY` | The `X-Api-Key` header is missing |
| 401 | `TOKEN_MISSING` | The key has no valid Bitrix24 token |
| 403 | `SCOPE_DENIED` | The key has neither the `task` nor the `tasks` scope |
| 403 | `WRITE_BLOCKED_READONLY_KEY` | The key is read-only |
| 403 | `BITRIX_ACCESS_DENIED` | The key's user has no permission for the task or the group kanban |
| 404 | `ENTITY_NOT_FOUND` | No task with this `taskId`: `Task was not found` |
| 409 | `TASK_NOT_IN_PLAN` | Moving on My Plan, and the task is not in the key owner's plan: `The task is not in your My Plan and was not moved` |
| 422 | `BITRIX_ERROR` | Bitrix24 did not confirm the move: `Bitrix24 did not confirm the move; reread the task before retrying` |
| 422 | `BITRIX_ERROR` | After a move on the group kanban, the task is not on the requested stage: `Bitrix24 did not move the task to the requested stage; reread the task before retrying` |
| 422 | `BITRIX_ERROR` | Bitrix24 rejected the move, the reason is in `message` |

Full list of common API errors: [Errors](/docs/errors).

## Known specifics

- **My Plan is independent of the group kanban.** A move on My Plan does not change the task's `stageId` in the group. Read the task's position in the plan by filtering the [task list](/docs/entities/tasks/list) with `filter[stagesId]=<stage ID>`.
- **Tasks are not added to My Plan.** The plan contains only tasks the key owner takes part in, for example as creator or assignee.
- **Group kanban ordering is shared.** All group members see the cards in the same order, so `beforeTaskId` and `afterTaskId` change the board for everyone.
- **Scrum sprint tasks are moved by a different method.** For a sprint board, use [Scrum kanban stages](/docs/scrum/stages).

## See also

- [Tasks: kanban, My Plan and the day plan](/docs/tasks)
- [Task kanban stages](/docs/task-stages)
- [Read the kanban sorting permission](/docs/tasks/stages-can-move)
- [Task list](/docs/entities/tasks/list)
- [Scrum kanban stages](/docs/scrum/stages)