Workspace commands & safe retries

One command envelope, several actions

POST /api/v1/workspace/commands uses the Command schema. Every request supplies action and a UUID commandId, with the fields for that action. A successful command returns 204; reload the workspace to obtain the resulting records.

The broad JSON schema lists fields for multiple actions. An optional schema property can still be required for a particular action. The backend performs additional role, scope, revision and business validation.

Course and learning actions

• save: provide course with its draft ID, current revision and content. Requires organisation-wide author permission.
• publish: provide courseId and the exact revision reviewed by the author. A stale revision conflicts.
• assign: provide courseId and 1–100 userIds within your assignment scope. Optional dueAt is YYYY-MM-DD, interpreted at the end of that date in the company timezone. The latest published course version is selected.
• progress: provide enrolmentId and lessonId for your own accessible enrolment. A quiz also requires answer, the zero-based choice index. A wrong answer returns a validation error and records the attempt; it is not an unprocessed network failure.

Resources and bookmarks

• save_resource: provide resource with an ID, title, summary, category, kind, body and revision. A new resource starts at revision 0. Editing requires the current revision and organisation-wide author permission.
• archive_resource: provide resourceId and the current revision. Requires author permission; archived resources are removed from the active library.
• bookmark_resource: provide resourceId and an explicit bookmarked boolean.
• bookmark_course: provide courseId and an explicit bookmarked boolean. Saving never grants access or creates an enrolment.

Keep a command identifier stable

For a retry of the same command, keep the same commandId and payload. The server stores a scoped command receipt; reusing its identifier with a different payload returns a conflict. Generate a new identifier for a genuinely new action, including a new quiz answer.

Do not generate a fresh commandId every time a network retry fires. Inspect the current record after an ambiguous response and distinguish a failed transport from a recorded business result. There is no universal Idempotency-Key header for all endpoints.

Example bookmark payload

Replace the illustrative IDs with a new command UUID and an accessible published course ID. Send this JSON using the session and CSRF procedure from the authentication guide. The docs page does not execute the request.

{
  "action": "bookmark_course",
  "commandId": "11111111-1111-4111-8111-111111111111",
  "courseId": "22222222-2222-4222-8222-222222222222",
  "bookmarked": true
}