Courses
Courses are learning objects within Coassemble. Using the API, you can fetch and delete courses as well as get a signed URL for courses for embedding.
Get courses Build and above
Use this endpoint to get all your courses. By default only non-deleted courses are returned; set the deleted query parameter to true to include soft-deleted courses.
Each course in the response includes timeEstimateMinutes, the minutes the author typed on the start screen timeEstimate block. The field is null when that block is absent.
/v1/headless/coursesQuery parameters
| Field | Type | Required | Default | Description | Options |
|---|---|---|---|---|---|
identifier | string | No | — | — | |
clientIdentifier | string | No | — | — | |
length | number | No | 100 | — | |
page | number | No | 0 | — | |
title | string | No | — | — | |
deleted | boolean | No | false | — |
Get course Build and above
Use this endpoint to get a course by ID.
The response includes timeEstimateMinutes, the minutes the author typed on the start screen timeEstimate block. The field is null when that block is absent.
/v1/headless/courses/{id}Path parameters
| Field | Description | Options |
|---|---|---|
id | Course ID | — |
Query parameters
| Field | Type | Required | Default | Description | Options |
|---|---|---|---|---|---|
identifier | string | No | — | — | |
clientIdentifier | string | No | — | — |
Get course content Build and above
Returns normalized course text content, including all translation variants, plus a catalog of media assets with fetchable URLs and metadata. Screens are returned in a standard shape with title, description, asset, assetAltText, and elements (each with question, title, description, cardBack, and answers). Asset processing such as transcription or document parsing is the consumer's responsibility.
/v1/headless/course/content/{id}Path parameters
| Field | Description | Options |
|---|---|---|
id | Course ID | — |
Query parameters
| Field | Type | Required | Default | Description | Options |
|---|---|---|---|---|---|
identifier | string | No | — | — | |
clientIdentifier | string | No | — | — |
Regenerate course card thumbnail Build and above
Fails any stuck thumbnail job and enqueues a fresh capture for Classic, Builder 2, or hosted SCORM. Poll GET /v1/headless/courses/{id} for the JPEG. The response includes id, thumbnail, thumbnailRevision, and queued.
/v1/headless/course/{id}/thumbnailParameter metadata is unavailable for this endpoint, but request examples are still shown.
Migrate Classic courses
Migration converts the draft to Builder 2 and preserves the course, original screen and question identities. It does not publish. A course already in Builder 2 returns already_modern. A blocked course stays unchanged and returns screen-level reasons. An active migration preview is committed: the Classic stash is dropped and the course leaves preview.
POST /v1/headless/course-migrations is the canonical endpoint. Send { courseIds: [123] }. At most 50 course IDs per request; more returns courseIds max=50, asked for N. One unique course, including a repeated id, returns 200 with that course's result. Two or more unique courses return 202 with a batch id. The threshold is one unique course because a 100-screen course finishes in 80-85 ms.
/v1/headless/course-migrationsBody parameters
| Field | Type | Required | Desc | Options |
|---|---|---|---|---|
courseIds | string | integer[] | Yes | — |
POST /v1/headless/course/{id}/migrate calls the same operation for one course and returns the same 200 result. It does not start a separate migration.
/v1/headless/course/{id}/migratePath parameters
| Field | Description | Options |
|---|---|---|
id | — |
Poll GET /v1/headless/course-migrations/{id} only after a 202 response. One unique course has no batch id. Subscribe to migration.progress and migration.completed as an alternative to polling. Those webhooks fire only for 202 batches. Legacy notifyEmail is accepted and ignored. Completion email is not sent.
/v1/headless/course-migrations/{id}Path parameters
| Field | Description | Options |
|---|---|---|
id | — |
Get a signed URL for a course [GET] (Deprecated)
POST /v1/headless/embed/course endpoint instead. See recommended alternative →/v1/headless/course/{action}Path parameters
| Field | Description | Options |
|---|---|---|
action | view (learner) or edit (authoring) | viewedit |
Query parameters
| Field | Type | Required | Default | Description | Options |
|---|---|---|---|---|---|
id | string | No | — | — | |
identifier | string | Yes | — | — | |
clientIdentifier | string | No | — | — | |
flow | string | No | — | aidocumentpresentationpreviewgeneratetransformconvert | |
back | string | No | — | eventhiddennative | |
colorPrimary | string | No | — | — | |
translations | boolean | No | — | — | |
language | string | No | — | — | |
brandVoice | boolean | No | — | — | |
legacy | boolean | No | — | — |
Get a signed URL for a course [POST] (Deprecated)
POST /v1/headless/embed/course endpoint instead. See recommended alternative →Use this endpoint to get a signed URL for a course. This URL can be used to embed the Coassemble interface into your application within an iframe.
/v1/headless/course/urlBody parameters
| Field | Type | Required | Desc | Options |
|---|---|---|---|---|
action | string | Yes | view (learner) or edit (authoring) | viewedit |
id | string | No | Course ID (required when action is view) | — |
identifier | string | Yes | Your stable user identifier | — |
clientIdentifier | string | No | The client this user belongs to | — |
themeId | number | No | Theme ID to render the embed with | — |
name | string | No | Display name for the learner | — |
avatar | string | No | Avatar URL for the learner | — |
options | object | No | — |
Duplicate a course Build and above
Use this endpoint to duplicate an existing course. You can optionally provide an identifier and clientIdentifier to assign the duplicated course to a new client or user within your environment.
/v1/headless/course/{id}/duplicatePath parameters
| Field | Description | Options |
|---|---|---|
id | Source course ID | — |
Body parameters
| Field | Type | Required | Desc | Options |
|---|---|---|---|---|
identifier | string | No | Override identifier on the duplicate | — |
clientIdentifier | string | No | Override client identifier on the duplicate | — |
Migrate a Classic course Build and above
This route is an alias of POST /v1/headless/course-migrations for one course id. It returns the same 200 result and does not create a batch. Migration does not publish the course. These endpoints require API authoring access and only operate on courses in your API key's workspace.
/v1/headless/course/{id}/migratePath parameters
| Field | Description | Options |
|---|---|---|
id | — |
{
"courseId": 123,
"status": "migrated",
"total": 3,
"changed": 3,
"blocked": []
} Check status: migrated means conversion succeeded, already_modern means no conversion was needed, and blocked means the course was left unchanged. For blocked courses, inspect blocked for screen IDs and reasons. An active migration preview is committed rather than rejected: the course leaves preview and stays on Builder 2.
To let authors preview and confirm migration themselves, enable the Course Builder migration option.
Migrate courses in a batch Build and above
Submit course IDs to POST /v1/headless/course-migrations. At most 50 IDs per request. One unique course returns 200 with the final result. Two or more unique courses return 202 with a durable batch id. Duplicate ids in one request count once.
/v1/headless/course-migrationsBody parameters
| Field | Type | Required | Desc | Options |
|---|---|---|---|---|
courseIds | string | integer[] | Yes | — |
{
"courseIds": [
123,
456
]
} The dashboard calls the same operation. A 202 batch keeps running after the request closes. Each course uses the same atomic conversion. One failed course does not undo a successful course. Subscribe to migration.progress and migration.completed instead of polling GET /v1/headless/course-migrations/{id} if you already receive workspace webhooks. Those events fire only for 202 batches, not for the one-course 200 path. notifyEmail is accepted and ignored. Completion email is not sent.
Get migration batch status Build and above
/v1/headless/course-migrations/{id}Path parameters
| Field | Description | Options |
|---|---|---|
id | — |
Use this route only for a 202 batch id, with an API key for the same workspace. Poll while status is pending or processing. Stop when it reaches completed or completed_with_errors. migration.progress and migration.completed carry the same snapshot as this response, so you can skip polling if those webhooks are subscribed.
counts contains total, pending, processing, succeeded, and failed. Inspect items for each course's status, conversion result, blocked screens, or error. Item statuses are pending, processing, migrated, already_modern, blocked, or failed. The batch has no notification field. Completion email is not sent.
Resolve any blocked content or errors, then submit only those course IDs as a new batch to retry. Re-submitting an already migrated course returns already_modern without converting it again.
Delete course Build and above
Use this endpoint to delete an existing course. The course is soft-deleted and can be restored with the restore endpoint.
/v1/headless/course/{id}Path parameters
| Field | Description | Options |
|---|---|---|
id | Course ID | — |
Restore a course Build and above
Use this endpoint to restore a soft-deleted course.
/v1/headless/course/{id}/restorePath parameters
| Field | Description | Options |
|---|---|---|
id | Course ID | — |
Export SCORM Partner
Use this endpoint to export a SCORM package for a course.
/v1/headless/course/scorm/{id}Path parameters
| Field | Description | Options |
|---|---|---|
id | Course ID | — |
Query parameters
| Field | Type | Required | Default | Description | Options |
|---|---|---|---|---|---|
type | string | No | — | dynamicstatic | |
version | string | No | — | 1.22004 |
Generate a course (Deprecated) Build and above
POST /v1/headless/generate/course endpoint instead. See recommended alternative →This legacy route is still available for backwards compatibility and delegates to the new generate controller.
/v1/headless/course/generateBody parameters
| Field | Type | Required | Desc | Options |
|---|---|---|---|---|
prompt | string | Yes | The topic or learning objective to generate a course from | — |
audience | string | Yes | Who the course is for (e.g. "new hires") | — |
familiarity | string | Yes | How familiar the audience is with the topic (e.g. "beginner") | — |
tone | string | Yes | Tone of voice for the generated content (e.g. "professional") | — |
screenCount | number | Yes | Approximate number of screens to generate | — |
identifier | string | Yes | Your stable identifier for the course owner | — |
clientIdentifier | string | No | The client this course belongs to | — |
Publish a course Build and above
Use this endpoint to publish a course programmatically.
/v1/headless/course/{id}/publishPath parameters
| Field | Description | Options |
|---|---|---|
id | Course ID | — |
Revert a course Build and above
Use this endpoint to revert a course to its published version programmatically.
/v1/headless/course/{id}/revertPath parameters
| Field | Description | Options |
|---|---|---|
id | Course ID | — |