Plan a study block
Puts study time on the user's calendar, the way the planning copilot does: a title, a future start and end in the user's time zone, and optionally the subject, task or study set it is for. The block can't overlap a lesson (including external calendars, read live) or another block, and can't end after a linked task's due day. Find free time first with getToday or getScheduleWeek.
Required scopes: schedule:create
AuthorizationBearer <token>Idempotency-Key?stringA client-generated key (1 to 255 visible ASCII characters) that makes this POST safe to retry. A retry with the same key and body replays the original response; the same key with a different body returns 409 idempotency_conflict. Stored for 24 hours.
^[\x21-\x7E]{1,255}$1 <= length <= 255application/json- body
title*stringWhat the user studies, 1-120 characters.
1 <= length <= 120startsAt*stringWhen the block starts, in the future. ISO timestamp with Z or an offset, such as 2026-10-21T16:00:00+01:00.
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$date-timeendsAt*stringWhen it ends: 5 minutes to 8 hours after startsAt, on the same day in the user's time zone. ISO timestamp with Z or an offset, such as 2026-10-21T16:00:00+01:00.
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$date-timesubjectId?|The subject studied. Null clears it.
taskId?|The task this block works on. The block must end by the task's due day. Null clears it.
setId?|The study set to practise in the block. Null clears it.
Created
application/json- response
data*curl -X POST 'https://workroad.app/api/v1/study-blocks' \ -H 'Authorization: Bearer $WORKROAD_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "title": "string", "startsAt": "2019-08-24T14:15:22Z", "endsAt": "2019-08-24T14:15:22Z"}'{ "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" }}