create-course-draft

Files (2)

• SKILL.md
• create-course-draft.js

SKILL.md (first lines)

# Create Course Draft

This is an **Action** skill — a single, unambiguous API call. It is deterministic and narrowly scoped.

## Endpoint

`POST /incoming/v2/content/course/create`

## When to use

- Creating a new course (courseGroup, microCourse, article, SCORM/xAPI) from a JSON payload.
- Staging AI-generated course outlines as drafts in the TI platform.

## Agent instructions

1. Gather required fields: `title`, `kind` (courseGroup, microCourse, article, video, shareableContentObject, xApiObject).
2. For courseGroup kind, optionally include nested `sections` → `lessons` → `topics`. For microCourse/video, topics may sit at the course top level (no sections).
3. **Every topic MUST include a `type`** (`text`, `video`, `embed`, `pdfViewer`, `quiz`, etc.). This is the field name the API expects — not `contentType`. A topic without `type` makes the server reject the whole request with a generic `"A processing error occurred"`. For ordinary HTML body content in a lesson, use `"text"`.
   - **Do NOT use `type: "article"` (or other standalone-only types) for a topic embedded in a lesson.** `article` is only for a standalone `kind:"article"` course (where the plugin builds the single topic for you). The API accepts an embedded `article` topic but the learner view then 404s and the editor cannot open it — and there is no delete action, so the course must be rebuilt. The script now blocks this locally.
   - **Every lesson needs an `openType`** (`studentsOnly`, `open`, or `emailCaptureOpen`). It is required by the API; the script defaults a missing `openType` to `studentsOnly` and rejects invalid values (omitting it against the raw API produces a generic `"A processing error occurred"`).
4. For **video content**, do NOT paste a Wistia/YouTube embed or URL into `body` — see [Video content](#video-content) below. Use `videoAsset` or `videoUrl`.
5. Run `create-course-draft.js --dry-run --file=course.json` first to validate (the script now fails locally with a precise message if a topic is missing/has an invalid `type`, or if a video's source is in the wrong field).
6. Then run without `--dry-run` to create.
7. The API returns course IDs. For SCORM/video uploads, a `backgroundJob` may be returned — poll with `GET /jobs/{id}`.

## Limits

- Max **100 courses** per request (`courseAttributes` array length).
- Max **25 child entities** per course (sections + lessons + topics combined). This mirrors the server's hard cap (`APICreateCourses` rejects >25). For a larger course, create the shell here and attach the remaining structure with `update-course-content` (up to 100 items per call).
- **`slug` is not settable on create.** TI auto-generates the slug from the `title`; a supplied `slug` is rejected with a generic HTTP 400. The script drops any `slug` (with a warning) so it never fails the request. To change a slug, set it afterward with `update-course-content`.

## Run the script

```bash
node "${CLAUDE_PLUGIN_ROOT:+$CLAUDE_PLUGIN_ROOT/skills/actions/create-course-draft/}create-course-draft.js" --dry-run --file=course.json
node "${CLAUDE_PLUGIN_ROOT:+$CLAUDE_PLUGIN_ROOT/skills/actions/create-course-draft/}create-course-draft.js" --file=course.json
node "${CLAUDE_PLUGIN_ROOT:+$CLAUDE_PLUGIN_ROOT/skills/actions/create-course-draft/}create-course-draft.js" --json='{"title":"My Course","kind":"courseGroup"}'
```

## Payload shapes

Single course:
```json
{ "title": "Intro to APIs", "kind": "courseGroup", "description": "..." }
```

With nested structure (note the required `type` on every topic):
```json
{
  "title": "Intro to APIs",
  "kind": "courseGroup",
  "sections": [
    {
      "title": "Getting Started",
      "lessons": [
        {
          "title": "What is an API?",
          "openType": "studentsOnly",
          "topics": [
            { "title": "Overview", "type": "text", "body": "<p>An API is...</p>" }
          ]
        }
      ]
    }
  ]
}
```

Micro course (topics at the top level, still need `type`):
```json
{
  "title": "Quick Tips",
  "kind": "microCourse",
  "topics": [
    { "title": "Tip 1", "type": "text", "body": "<p>...</p>" }
  ]
}
```

## Video content

A video is **never** set via HTML/embed markup in `body`. The API rejects that
for a `video` course (generic `"A processing error occurred"`) and **silently
drops** it for a `video` topic — the create "succeeds" but the page is empty.
Instead use these dedicated fields (mutually exclusive):

| Field | Use it for | Example |
|-------|------------|---------|
| `videoAsset` | An **existing** video: a Wistia **`hashed_id`** or a Synthesia **UUID**. No upload. | `"ie20dfp60t"` |
| `videoUrl` | A direct video **file** URL (`.mp4`, `.mov`, …) — the server uploads it to **Wistia** via a background job. (No Synthesia equivalent; `videoUrl` is always a Wistia ingest.) | `"https://cdn.example.com/clip.mp4"` |
| `assetType` | `"wistia"` (default) or `"synthesia"`. Pair with `videoAsset`; omit with `videoUrl` (auto-set to `wistia`). | `"wistia"` |

**Synthesia** works exactly like Wistia but is **reference-only**: pass the
Synthesia asset UUID as `videoAsset` and set `"assetType": "synthesia"`
explicitly — it is **required** for Synthesia (only Wistia defaults it), and
there is no `videoUrl` upload path for Synthesia.
```json
{ "title": "Welcome Video", "kind": "video", "videoAsset": "550e8400-e29b-41d4-a716-446655440000", "assetType": "synthesia" }
```

> **A "Wistia URL" is not a `videoUrl`.** A link the user pastes such as
> `https://acme.wistia.com/medias/ie20dfp60t` or
> `https://fast.wistia.net/embed/iframe/ie20dfp60t` is a *page/embed* URL, not a
> file. Extract the hashed id (the token after `/medias/` or `/embed/iframe/` —
> here `ie20dfp60t`) and pass it as `videoAsset`. `videoUrl` is only for a
> directly downloadable video file.

Where the fields go depends on the kind:

- **Standalone `kind:"video"` course** — put the field on the **course object**. The API creates the single underlying page for you.
```json
{ "title": "Welcome Video", "kind": "video", "videoAsset": "ie20dfp60t", "assetType": "wistia" }
```
- **A `type:"video"` topic** inside a courseGroup/microCourse — put the field on the **topic**.
```json
{
  "title": "Course with a Video",
  "kind": "microCourse",
  "topics": [

From thoughtindustries/ti-admin-plugin, MIT.

More from thoughtindustries/ti-admin-plugin