LMS course version rollouts

Base path: /api/public/v1/lms/courses/{courseId}

Course publication and active-assignment rollout are separate operations. Publishing creates an immutable release; rollout changes the effective release of an explicit assignment audience while preserving compatible learner state. Reads require lms:read. Publish and rollout Apply require lms:write, a claimed employer account, organization/course authority, and an Idempotency-Key where shown.

Publish

POST /publish requires an Idempotency-Key header:

{
  "expectedDraftRevision": 7,
  "confirmPublish": true
}

The response includes the immutable version and additive agent guidance:

{
  "version": {
    "id": "course-version-id",
    "courseId": "course-id",
    "contentHash": "sha256-content-hash"
  },
  "existingAssignments": {
    "updated": false,
    "reason": "PUBLISHED_VERSIONS_ARE_IMMUTABLE"
  },
  "nextAction": {
    "requiredForExistingAssignments": true,
    "operation": "lms.courses.rollout_preview",
    "courseId": "course-id",
    "courseVersionId": "course-version-id",
    "expectedContentHash": "sha256-content-hash",
    "applyOperation": "lms.courses.rollout",
    "statusOperation": "lms.courses.rollout_status",
    "receiptOperation": "lms.courses.rollout_receipt"
  }
}

Preview rollout impact

POST /rollout-preview is read-only and takes no idempotency key:

{
  "toCourseVersionId": "course-version-id",
  "expectedToContentHash": "sha256-content-hash",
  "jobId": "job-id",
  "assignmentIds": null
}

Provide jobId, a non-empty assignmentIds array, or both. The response reports would-be assignment outcomes and counts. It is live information, not a concurrency fence.

Apply rollout

POST /rollout requires a durable Idempotency-Key and explicit confirmation:

{
  "toCourseVersionId": "course-version-id",
  "expectedToContentHash": "sha256-content-hash",
  "jobId": "job-id",
  "assignmentIds": null,
  "confirmApply": true
}

Apply reclassifies each selected assignment from authoritative current state. Its receipt reports assignment-level outcomes and these counts:

updatedNow
queued
alreadyCurrent
skippedTerminal
blocked
failed

Ordinary learner activity after Preview does not reject the batch. A protected in-progress assessment queues for automatic safe-boundary migration. Submitted attempts keep their original version and scoring rules.

Read status and receipts

GET /rollout?toCourseVersionId=<id>&jobId=<id> returns the newest matching receipt plus pendingQueued. Both filters are optional. GET /rollout/{operationKey} returns the durable receipt for one Apply key plus its live queued count. Poll this record while deferred learners finish protected work.

Idempotency and failures

Replaying the same Apply key with the identical request returns the stored receipt. Reusing it with a different request returns 409 CONFLICT. One assignment’s contention or failure is isolated and does not roll back successful assignments; inspect its typed reason and retry that selected assignment under a fresh key after remediation. Rollout never cancels or recreates assignments, resets unrelated progress, or silently regrades submitted attempts. See Update an assigned LMS course, CLI commands, and MCP tools.

⌘I

Getting started

Connect your agent

Core concepts

Guides

API reference

CLI

MCP server

Annotation platforms

LMS course version rollouts

Publish

Preview rollout impact

Apply rollout

Read status and receipts

Idempotency and failures

​Publish

​Preview rollout impact

​Apply rollout

​Read status and receipts

​Idempotency and failures

Publish

Preview rollout impact

Apply rollout

Read status and receipts

Idempotency and failures