Skip to content
WorkRoad home
REST API

Start a practice session

POST
/practice-sessions

Starts flashcard practice the way the app's Review page does, over every study set the user owns or only some, and answers with the first cards. A normal session serves what is due now (learning and relearning first, then reviews, then new cards within the user's daily new-card limit), taking turns between sets, up to 30 at a time. Answer each card with answerPracticeCard, then call getPracticeSession for more. cram: true walks every term once without touching the schedule. A session lasts 7 days and needs no finishing.

Required scopes: activity:create and sets:view

Authorization

headerAuthorizationBearer <token>

Header Parameters

Idempotency-Key?string

A 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.

Match^[\x21-\x7E]{1,255}$
Length1 <= length <= 255

Request Body

application/json
  1. body
setIds?array<>

Only these study sets, up to 200. Omit to practise every set the user owns.

Itemsitems <= 200
subjectId?string

Only sets filed under this subject. Combines with setIds.

Match^([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)$
Formatuuid
cram?boolean

Walk every term once, due or not, without changing any card's schedule. Defaults to false: a normal session serves only due and new cards and records each answer as an FSRS review.

Response Body

Created

application/json
  1. response
data*
Example Request
curl -X POST 'https://workroad.app/api/v1/practice-sessions' \  -H 'Authorization: Bearer $WORKROAD_API_KEY' \  -H 'Content-Type: application/json' \  -d '{}'
Example Response
{  "data": {    "id": "8b7a6f5e-4d3c-4b2a-9f1e-0d9c8b7a6f5e",    "cram": false,    "setIds": [],    "subjectId": "5f0c1d2e-3a4b-4c5d-8e6f-7a8b9c0d1e2f",    "createdAt": "2026-02-01T12:00:00.000Z",    "expiresAt": "2026-02-08T12:00:00.000Z",    "cards": [      {        "itemId": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b",        "cardId": "3e2d1c0b-9a8f-4e7d-8c6b-5a4f3e2d1c0b",        "termId": "2a1b0c9d-8e7f-4a6b-9c5d-4e3f2a1b0c9d",        "setId": "7e6d5c4b-3a2f-4e1d-8c0b-9a8f7e6d5c4b",        "setName": "Spanish verbs",        "subjectId": "5f0c1d2e-3a4b-4c5d-8e6f-7a8b9c0d1e2f",        "activity": "flashcards",        "term": "tener (yo)",        "definition": "tuve",        "hints": [          "irregular stem tuv-"        ],        "imageUrl": null,        "queue": "review",        "due": "2026-01-15T09:30:00.000Z"      }    ],    "answeredCount": 0,    "finished": false,    "nextDueAt": null,    "undoableItemId": null,    "serverTime": "2026-02-01T12:00:00.000Z"  }}

Get a practice session's next cards GET

Returns the cards still waiting for an answer.

Undo a practice answer POST

Takes back an answer, as the app's undo does: the review is removed from the card's history, the card's schedule goes back to what it was, and the card is queued in the session again under a new itemId.