Learning Studio / agents
Apply operations safely
Use versions and idempotency to avoid lost or duplicated edits.
Apply course edits as operations so validation, version checks, and retries follow the same path as the editor. Read the current course before preparing a change.
Native operations
Section titled “Native operations”Supported operation families include section.add, section.update, section.move, section.remove, block.insert, block.update, block.move, block.remove, block.group, block.ungroup, column.insert, column.remove, course.settings.update, course.blueprint.update, course.design.update, course.rubrics.update, and course.restore.
course.rubrics.update replaces the whole rubric list (0–20 rubrics; null or [] removes it). Each rubric has 2–6 levels with strictly descending points and 1–10 criteria, each with one descriptor per level keyed by level ID and links to live course objectives. Rubric, level and criterion IDs must be unique in the course. Show a rubric with a rubric block ({ rubricId }).
course.design.update sets or clears the optional Backward Design plan (null removes it). It replaces the whole design: the approach (standard, academic or performance), results (outcome, roles and tasks, or transfer goals and understandings), objective links, evidence and dismissed checks. Design IDs must be unique in the course, and task roles and evidence targets must name items in the same design. See Plan a course with backward design.
Send operations rather than writing courses.content directly. Operations pass through shared validation and an atomic commit. Rich text uses TipTap JSON. Give new sections, blocks, column children, content groups, and template copies unique IDs.
block.group wraps adjacent blocks in a new content group within the same container. block.ungroup replaces a content group with its children at the same position; it is refused when the group is hidden or locked. column.insert adds an empty column to a columns block (1–4 columns). column.remove removes an empty column, leaving at least one.
Retry and conflict behavior
Section titled “Retry and conflict behavior”Use an idempotency key of 8–100 characters. If the response is uncertain, retry the same intended write with the same key. Use a new key for different content.
A stale baseVersion returns a conflict. Read the latest course, reconcile your proposal with the newer content, and submit it as a new change with a new key. An older whole-course snapshot must not overwrite newer human edits.
Errors
Section titled “Errors”| Status | Meaning | Next action |
|---|---|---|
| 401 | Missing or invalid user token | Authenticate again. |
| 404 | Course is absent or inaccessible | Check the course ID and caller’s access. |
| 400 | Malformed JSON or invalid request envelope | Correct the request format. |
| 409 | Version conflict | Read the latest course and reconcile the change. |
| 422 | Invalid or locked operations | Read the reason and correct the proposal. |
Restore
Section titled “Restore”Read a saved version’s content before constructing a course.restore operation. Restore creates a new validated change; it doesn’t rewrite history.
Save a checkpoint before a major operation. After applying the change, read the result and inspect it in the app.
Apply course operations with version checks and idempotency
Section titled “Apply course operations with version checks and idempotency”Read the course first to obtain its current version. Submit your operations with that version as baseVersion, an idempotencyKey of 8–100 characters, and an ordered ops array (1–500 operations). The server validates every operation through the same pipeline the editor uses, then commits the change atomically.
A successful commit returns { status: "ok", version }. If the response is uncertain, retry the identical request with the same idempotencyKey; the server replays the original result instead of duplicating the write. When you need a different change, generate a new key.
If the course has moved ahead since your read, the server returns 409 with the current version. Read the latest course, reconcile your operations against the newer content, and submit the revised change with a new idempotencyKey.
Operations can also be validated without saving by sending dryRun: true on the agent API endpoint. The response reports whether the operations are valid and lists the resulting change labels and page count, but no version is consumed and nothing is committed.
