## Restore folder

`POST /v1/folders/:id/restore`

Restores a folder from the Bitrix24 trash together with everything deleted along with it. If the parent folder is also in the trash, the method restores it too, along with all folders above it.

## Parameters

| Parameter | Type | Required | Description |
|----------|-----|:-----:|----------|
| `id` (path) | number | yes | Folder ID. List: `GET /v1/folders?parentId=X`. Folders in the trash do not appear in the list — save the `id` before deleting |

No request body.

## Examples

### curl — personal key

```bash
curl -X POST "https://vibecode.bitrix24.com/v1/folders/10741/restore" \
  -H "X-Api-Key: YOUR_API_KEY"
```

### curl — OAuth application

```bash
curl -X POST "https://vibecode.bitrix24.com/v1/folders/10741/restore" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"
```

### JavaScript — personal key

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/folders/10741/restore', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})
const body = await res.json()
if (!body.success) throw new Error(body.error.code)
console.log('Restored by this call:', body.meta.restored, 'name:', body.data.name)
```

### JavaScript — OAuth application

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/folders/10741/restore', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})
const body = await res.json()
if (!body.success) throw new Error(body.error.code)
console.log('Restored by this call:', body.meta.restored, 'name:', body.data.name)
```

## Response fields

| Field | Type | Description |
|------|-----|----------|
| `success` | boolean | `true` on success |
| `data` | object | The folder after the call. For all fields, see [Folder fields](/docs/entities/folders/fields) |
| `data.name` | string | Current folder name. If it changed during restoration, the previous name is returned in `meta.renamedFrom` |
| `data.deletedType` | number | Deletion status: `0` — the folder is not in the trash |
| `data.deletedAt` | string \| null | Time of the last deletion (ISO 8601). Restoration does not clear the field |
| `data.deletedBy` | number \| null | ID of the user who deleted the folder. Restoration does not clear the field. List: `GET /v1/users` |
| `meta.restored` | boolean | `true` — the folder was restored by this call. `false` — the folder was not in the trash, and the call changed nothing |
| `meta.renamedFrom` | string \| null | Folder name before restoration, if it changed because of a name collision. `null` — the name is unchanged |

## Response example

```json
{
  "success": true,
  "data": {
    "id": 10741,
    "name": "Reports",
    "code": null,
    "storageId": 1379,
    "type": "folder",
    "realObjectId": 10741,
    "parentId": 10739,
    "deletedType": 0,
    "createdAt": "2026-10-15T18:25:16.000Z",
    "updatedAt": "2026-10-15T18:27:36.000Z",
    "deletedAt": "2026-10-15T18:27:34.000Z",
    "createdBy": 1295,
    "updatedBy": 1295,
    "deletedBy": 1295,
    "detailUrl": "https://<portal>.bitrix24.com/company/personal/user/1295/disk/path/Documents/Reports"
  },
  "meta": {
    "restored": true,
    "renamedFrom": null
  }
}
```

## Error response example

404 — the folder does not exist, including after permanent deletion:

```json
{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "Could not find entity with id '999999999'."
  }
}
```

## Errors

| HTTP | Code | Description |
|------|-----|----------|
| 400 | `INVALID_ID` | `id` is not a positive integer |
| 401 | `TOKEN_MISSING` | The key's portal has no authorization tokens |
| 403 | `SCOPE_DENIED` | The key lacks the `disk` scope |
| 403 | `WRITE_BLOCKED_READONLY_KEY` | The key is in read-only mode, and restoration changes portal data |
| 403 | `BITRIX_ACCESS_DENIED` | The key owner has no permissions for the folder in Bitrix24 |
| 404 | `ENTITY_NOT_FOUND` | No folder with this `id`, including after [permanent deletion](/docs/entities/folders/purge) |
| 422 | `DISK_RESTORE_REFUSED` | Bitrix24 did not confirm the restoration. Re-read the folder via [`GET /v1/folders/:id`](/docs/entities/folders/get) |
| 422 | `BITRIX_ERROR` | Bitrix24 refused the restoration; the reason is in `message` |
| 429 | `RATE_LIMITED` | Request rate limit exceeded — wait 1-2 seconds and retry |
| 502 | `DISK_OUTCOME_UNKNOWN` | The connection to Bitrix24 dropped after the restore request was sent. The outcome is unknown and the request was not retried — re-read the folder before calling the method again |
| 502 | `BITRIX_UNAVAILABLE` | Bitrix24 was unavailable while the folder was being read; the restore request was not sent |

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

## Known specifics

**Sibling objects stay in the trash.** If you restore a nested folder while its parent folder is in the trash, only that folder, its contents, and the folders above it come back. The rest of the parent folders' contents stays in the trash — restore it with separate calls.

**Batch calls.** Restoration is not available in [`POST /v1/batch`](/docs/batch) — call it as a separate request.

## See also

- [Delete folder](/docs/entities/folders/delete)
- [Permanently delete folder](/docs/entities/folders/purge)
- [Get a folder](/docs/entities/folders/get)
- [Public link to a folder](/docs/entities/folders/public-link)
- [Folders](/docs/entities/folders)