# Restore a task from the trash

Source: https://workroad.app/docs/api/restore-task

`POST https://workroad.app/api/v1/tasks/{taskId}/restore`

Brings a trashed task back with the subtasks that went to the trash with it, and returns it. Restoring a subtask whose task is in the trash restores that task too. Needs `tasks:delete`, the scope that trashed it.

- MCP tool: `restoreTask` on `https://workroad.app/api/mcp`
- Required scopes: tasks:delete
- Test mode: `POST https://workroad.app/api/test/v1/tasks/{taskId}/restore` checks the request and returns the example response without changing anything.

## Path parameters

- `taskId`: string (uuid), required. Task id, scoped to the key's user.

## Headers

- `Idempotency-Key`: string, optional, 1-255 visible ASCII characters. Makes the POST safe to retry: a retry with the same key and body replays the first response, and the same key with a different body returns 409 `idempotency_conflict`. Kept for 24 hours. Over MCP it is the `idempotencyKey` argument.

## Response

`200` OK

- `data`: object, required
  - `id`: string (uuid), required
  - `name`: string, required
  - `description`: string or null, required
  - `type`: string, required. Free-form task type from the user's task settings.
  - `subjectId`: string or null, required. Subject id, when set.
  - `dueDate`: string (date-time) or null, required. Due date, when set.
  - `completed`: boolean, required. Public name for the `finished` column.
  - `priority`: one of `"none"`, `"low"`, `"medium"`, `"high"`, required. How urgent the task is: `none`, `low`, `medium` or `high`, from least to most urgent. `none` when unset.
  - `parentId`: string or null, required. The parent task's id for a subtask, `null` for a top-level task.
  - `createdAt`: string (date-time), required. Creation timestamp.
  - `updatedAt`: string (date-time), required. Last update timestamp.

### Example

```json
{
  "data": {
    "id": "4d3c2b1a-0f9e-4d8c-9b7a-6f5e4d3c2b1a",
    "name": "Finish lab report",
    "description": "Include the error analysis.",
    "type": "Generic",
    "subjectId": "5f0c1d2e-3a4b-4c5d-8e6f-7a8b9c0d1e2f",
    "dueDate": "2026-02-10T17:00:00.000Z",
    "completed": false,
    "priority": "high",
    "parentId": null,
    "createdAt": "2026-01-15T09:30:00.000Z",
    "updatedAt": "2026-02-01T12:00:00.000Z"
  }
}
```

## Errors

Every error has the body `{ "error": { "code", "message", "details" } }`.

- `400`: Invalid request body or query
- `401`: Missing, invalid, disabled or expired API key
- `402`: `api_allowance_reached`: this month's API and AI app requests on the free plan are used up. `details` has `limit`, `used`, `resetsAt` and `upgradeUrl`. Nothing ran; WorkRoad Plus has no monthly limit.
- `403`: The API key lacks the required scope
- `404`: No task with that id is in the trash for this key's user.
- `405`: Method not allowed. Use a method from the Allow header.
- `409`: The Idempotency-Key was reused with a different request body, or a request with the same key is still in progress.
- `429`: Rate limit exceeded. Wait for Retry-After before retrying. The rate-limit headers are absent when the key's own limiter rejected the request before the per-endpoint bucket check ran.
- `500`: Internal server error