Subjects
Create, rename, archive and delete the subjects that tie a user's work together.
How subjects work
A subject tags the tasks, notes, study sets and schedule elements the key's user owns. A subject has at most 20 teachers, each up to 120 characters. DELETE /subjects/{subjectId} unfiles it from all of those, then deletes it. It leaves timetable elements on schedules the key's user doesn't own untouched, even when those schedules reference the same subject.
Name the subject with subjectId, or with subjectName, which must match one of the user's active subjects ignoring case and accents. A name that matches none returns 400 with details.reason unknown-subject and the user's subjects in details.subjects. Send createSubjectIfMissing: true to create it, which also needs subjects:create. Tasks, study sets and note folders all take subjectName.
Get a subject
Returns one subject the key's user owns.
Required scopes: subjects:view or tasks:view or schedule:view or notes:view or sets:view
AuthorizationBearer <token>subjectId*stringSubject id, scoped to the key's user.
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$uuidOK
application/json- response
data*curl -X GET 'https://workroad.app/api/v1/subjects/497f6eca-6276-4993-bfeb-53cbbbba6f08' \ -H 'Authorization: Bearer $WORKROAD_API_KEY'{ "data": { "id": "5f0c1d2e-3a4b-4c5d-8e6f-7a8b9c0d1e2f", "name": "Chemistry", "teachers": [ "Dr. Curie" ], "period": "Year 12", "archived": false }}List subjects
Returns every subject the user owns. Subjects are few and carry no creation timestamp, so this endpoint is not paginated.
Required scopes: subjects:view or tasks:view or schedule:view or notes:view or sets:view
AuthorizationBearer <token>OK
application/json- response
data*array<>curl -X GET 'https://workroad.app/api/v1/subjects' \ -H 'Authorization: Bearer $WORKROAD_API_KEY'{ "data": [ { "id": "5f0c1d2e-3a4b-4c5d-8e6f-7a8b9c0d1e2f", "name": "Chemistry", "teachers": [ "Dr. Curie" ], "period": "Year 12", "archived": false } ]}Create a subject
Fails on a name already in active use.
Required scopes: subjects: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
name*string1 <= length <= 64teachers?array<>Teacher names, in no particular order.
items <= 20[]period?|Free-text term or year label, e.g. Year 12. null clears it.
Created
application/json- response
data*curl -X POST 'https://workroad.app/api/v1/subjects' \ -H 'Authorization: Bearer $WORKROAD_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "name": "string"}'{ "data": { "id": "5f0c1d2e-3a4b-4c5d-8e6f-7a8b9c0d1e2f", "name": "Chemistry", "teachers": [ "Dr. Curie" ], "period": "Year 12", "archived": false }}Update a subject
Changes only the fields you send. archived and any name, teachers or period change are checked and written together, against the subject's final state. Archiving a subject whose course is over also archives its active study sets, so they leave reviews and practice; restoring the subject restores exactly those. setsArchived and setsRestored count them.
Required scopes: subjects:update
AuthorizationBearer <token>subjectId*stringSubject id, scoped to the key's user.
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$uuidapplication/json- body
Send only the fields to change. An omitted field stays as it is.
name?string1 <= length <= 64teachers?array<>Replaces the full list when sent.
items <= 20period?|Free-text term or year label, e.g. Year 12. null clears it.
archived?booleanArchives or restores the subject. Checked and written together with the other fields, against the subject's final state. Archiving it also archives its active study sets, which takes them out of reviews and practice; restoring it restores exactly those, not a set archived on its own.
OK
application/json- response
data*curl -X PATCH 'https://workroad.app/api/v1/subjects/497f6eca-6276-4993-bfeb-53cbbbba6f08' \ -H 'Authorization: Bearer $WORKROAD_API_KEY' \ -H 'Content-Type: application/json' \ -d '{}'{ "data": { "id": "5f0c1d2e-3a4b-4c5d-8e6f-7a8b9c0d1e2f", "name": "Chemistry", "teachers": [ "Dr. Curie" ], "period": "Year 12", "archived": false, "setsArchived": 0, "setsRestored": 0 }}Delete a subject
Unfiles the subject from every task, note folder, study set and schedule element the key's user owns, then deletes it. Never touches another user's timetable.
Required scopes: subjects:delete
AuthorizationBearer <token>subjectId*stringSubject id, scoped to the key's user.
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$uuidOK
application/json- response
data*curl -X DELETE 'https://workroad.app/api/v1/subjects/497f6eca-6276-4993-bfeb-53cbbbba6f08' \ -H 'Authorization: Bearer $WORKROAD_API_KEY'{ "data": { "id": "5f0c1d2e-3a4b-4c5d-8e6f-7a8b9c0d1e2f", "deleted": true }}