Assignments

An assignment (asg_…) is work set in one subject: for a class or team, or for named learners. It is what a teacher or a manager sets in the console's Assignments page, and the API sets it the same way. Reading needs assignments:read; setting, changing and deleting need assignments:write. See the Assignments reference for every field.

Setting work#

POST /v1/assignments names the subject (subjectId), a title, and who it is for:

• unitId: a class or team, and with it everyone in the units below it who holds a learner's place;
• or personIds: up to 500 named learners. Each must hold a learner's place in your organization (400 invalid_request otherwise).

{
  "subjectId": "sub_4hd8...",
  "title": "Handle price objections",
  "unitId": "unit_8f2k...",
  "instructions": "Two practice calls before Friday.",
  "dueAt": "2026-11-06T17:00:00Z",
  "minutes": 20,
  "focus": { "id": "price-objections" },
  "target": 70
}

What it can ask for depends on the subject, as in the console:

• focus: one of the subject's topics, question sets or scenarios, by id. Without one, any session in the subject counts.
• difficulty (easy, medium or hard): only where the subject has levels. A session at that level or harder counts.
• target: a score from 1 to 100, where a score fits the subject (role-plays, and tutors that give a score).
• minutes: how many minutes of counting sessions it asks for (1 to 240). Without it, one counting session is enough.
• dueAt: when it is due. A date already gone is refused (with a day and a half of slack for time zones).

Something the subject doesn't offer is refused with 400 invalid_request. Work is never set on a unit that is switched off, or where homework is switched off (409 conflict, with details.reason). Send an Idempotency-Key so a retry never sets the same work twice.

Following it#

Each learner's state moves on its own:

GET /v1/assignments lists the work set in your organization, newest first, with how many learners are at each state (counts). Filter it by subjectId, unitId or personId. GET /v1/assignments/{id} adds every learner and where they are. Learners are named by id (usr_…); their names are read with people:read.

Changing and withdrawing it#

PATCH /v1/assignments/{id} changes the title, the instructions, the due date or the minutes; null clears the instructions, the due date or the minutes. Who it is for and what counts towards it stay as set. To change those, delete it and set it again.

DELETE /v1/assignments/{id} withdraws the work: it and every learner's state on it go. Sessions, results and reports stay.

Who may set what#

An API key acts as an admin of your organization: it sets work for any class, team or learner there. In the console, a leader sets work only for the units they lead and the learners in them, and changes or deletes only work they set or work on their units. Owners and admins manage all of it.

Events#

Reading them through GET /v1/events needs assignments:read as well as events:read.