# Update a study block

Source: https://workroad.app/docs/api/update-study-block

`PATCH https://workroad.app/api/v1/study-blocks/{studyBlockId}`

Moves, renames or relinks a planned block. Fields you leave out keep their value, and the whole block is checked again as if it were new, so a block already in the past can't be edited.

- MCP tool: `updateStudyBlock` on `https://workroad.app/api/mcp`
- Required scopes: schedule:update
- Test mode: `PATCH https://workroad.app/api/test/v1/study-blocks/{studyBlockId}` checks the request and returns the example response without changing anything.

## Path parameters

- `studyBlockId`: string (uuid), required. Study block id, scoped to the key's user.

## Request body

JSON.

- `title`: string, 1-120 characters. What the user studies, 1-120 characters.
- `startsAt`: string (date-time). New start, in the future. ISO timestamp with `Z` or an offset, such as `2026-10-21T16:00:00+01:00`.
- `endsAt`: string (date-time). New end. ISO timestamp with `Z` or an offset, such as `2026-10-21T16:00:00+01:00`.
- `subjectId`: string (uuid) or null. The subject studied. Null clears it.
- `taskId`: string (uuid) or null. The task this block works on. The block must end by the task's due day. Null clears it.
- `setId`: string (uuid) or null. The study set to practise in the block. Null clears it.

## Response

`200` OK

- `data`: object, required
  - `id`: string (uuid), required
  - `title`: string, required
  - `startsAt`: string (date-time), required. Start, in UTC.
  - `endsAt`: string (date-time), required. End, in UTC.
  - `date`: string, required. The day (YYYY-MM-DD) in the user's time zone.
  - `timeZone`: string, required. The time zone the block was planned in.
  - `subjectId`: string or null, required. The subject studied, when set.
  - `taskId`: string or null, required. The task worked on, when set.
  - `setId`: string or null, required. The study set practised, when set.
  - `createdAt`: string (date-time), required. Creation timestamp.
  - `updatedAt`: string (date-time), required. Last update timestamp.

### Example

```json
{
  "data": {
    "id": "5a4b3c2d-1e0f-4a9b-8c7d-6e5f4a3b2c1d",
    "title": "Spanish verbs",
    "startsAt": "2026-02-02T17:00:00.000Z",
    "endsAt": "2026-02-02T17:45:00.000Z",
    "date": "2026-02-02",
    "timeZone": "Europe/London",
    "subjectId": "5f0c1d2e-3a4b-4c5d-8e6f-7a8b9c0d1e2f",
    "taskId": null,
    "setId": "7e6d5c4b-3a2f-4e1d-8c0b-9a8f7e6d5c4b",
    "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` with `details.reason`: `planning-date-invalid` (in the past, shorter than 5 minutes, longer than 8 hours, or across midnight), `planning-clock-change`, or `planning-link-invalid` (a subject, task or set that isn't the user's).
- `401`: Missing, invalid, disabled or expired API key
- `403`: The API key lacks the required scope
- `404`: No study block with that id exists for this key's user.
- `405`: Method not allowed. Use a method from the Allow header.
- `409`: `conflict` with `details.reason`: `planning-conflict` (overlaps a lesson or another block; read `getToday` or `getScheduleWeek` for free times), `planning-after-deadline` (ends after the linked task's due day), `planning-calendar-incomplete` (an external calendar couldn't be read, or the block is beyond next week while one is connected).
- `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