Learning Studio / agents
Apply operations safely
Use versions and idempotency to avoid lost or duplicated edits.
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, course.settings.update, course.blueprint.update, and course.restore.
Never write courses.content directly. Operations pass through the same pure validation and atomic commit as editor changes. Rich text is TipTap JSON. New sections, blocks, column children, and template copies need unique IDs.
Retry and conflict behavior
Section titled “Retry and conflict behavior”Use an idempotency key of 8–100 characters. Retry the same intended write with the same key when the response is uncertain. Do not reuse that key for different content.
A stale baseVersion returns a conflict. Read the latest course, reconcile your proposal, and submit a new intended change with a new key. Do not overwrite a newer human edit with an old whole-course snapshot.
Errors
Section titled “Errors”- 401: missing or invalid user token; authenticate again.
- 404: course absent or inaccessible to the caller.
- 400: malformed JSON or invalid request envelope.
- 409: version conflict; reread and reconcile.
- 422: invalid operations; inspect the reason and correct the proposal.
Restore
Section titled “Restore”Read a saved version’s content before constructing a course.restore operation. Restoring is a new validated change, not a history rewrite. Checkpoint before a major operation and inspect the UI after applying it.