Export Lesson

Export a published lesson version as a self-contained ZIP file containing all lesson content, media assets, and widget bundles.

Endpoint


GET /api/lessons/{lessonId}/versions/{versionId}/export-zip

Authentication

This endpoint requires authentication using a Bearer token. See Authentication for complete details on API token format, usage, and error handling.

Path Parameters

Parameter	Type	Required	Description
`lessonId`	string (UUID)	Yes	The unique identifier of the lesson
`versionId`	string (UUID)	Yes	The unique identifier of the published version

Response

Success Response (200 OK)

Returns a ZIP file as a binary download.

Response Headers:

Header	Value
`Content-Type`	`application/zip`
`Content-Disposition`	`attachment; filename="lesson-slug-v1.zip"`
`Content-Length`	Size of the ZIP file in bytes

ZIP File Structure

The exported ZIP contains the following structure:


lesson-slug-v1/
├── lesson.json          # Lesson content with localized media references
├── manifest.json        # Export metadata and file inventory
├── media/
│   ├── {uuid}.jpg       # Media files (images, videos, audio)
│   ├── {uuid}.png
│   └── ...
└── widgets/
    ├── {widget-id}.js   # Widget JavaScript bundles
    ├── {widget-id}.css  # Widget CSS files (if available)
    └── ...

lesson.json

Contains the full lesson content structure. All media references are rewritten from media:{uuid} format to local paths (./media/{uuid}.{ext}).

manifest.json

Contains export metadata and file inventory:


{
  "lessonId": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Introduction to Biology",
  "versionNumber": 1,
  "versionId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "publishedAt": "2025-01-15T10:30:00Z",
  "exportedAt": "2025-01-20T14:45:00Z",
  "formatVersion": "1.0.0",
  "files": {
    "lesson": "./lesson.json",
    "media": [
      {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "localPath": "./media/a1b2c3d4-e5f6-7890-abcd-ef1234567890.jpg",
        "mimeType": "image/jpeg"
      }
    ],
    "widgets": [
      {
        "widgetType": "multiple-choice",
        "localPath": "./widgets/widget-123.js",
        "cssLocalPath": "./widgets/widget-123.css"
      }
    ]
  },
  "failedMedia": [],
  "failedWidgets": [],
  "attributions": [
    {
      "mediaId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "text": "Photo by John Doe",
      "url": "https://unsplash.com/photos/abc123",
      "portfolioUrl": "https://unsplash.com/@johndoe"
    }
  ]
}

Error Responses

400 Bad Request

The path parameters are invalid.


{
  "error": "Bad Request",
  "message": "Invalid lesson ID",
  "code": "BAD_REQUEST",
  "timestamp": "2025-01-20T14:45:00.000Z"
}

401 Unauthorized

Authentication failed. See Authentication Errors for detailed information.


{
  "error": "Authentication Error",
  "message": "User authentication is required",
  "code": "UNAUTHORIZED",
  "timestamp": "2025-01-20T14:45:00.000Z"
}

404 Not Found

The specified lesson or version does not exist, or is not accessible by the authenticated user.


{
  "error": "Not Found",
  "message": "Published version not found",
  "code": "NOT_FOUND",
  "timestamp": "2025-01-20T14:45:00.000Z"
}

422 Unprocessable Entity

The published version content is invalid or empty.


{
  "error": "Invalid Content",
  "message": "Published version content is invalid or empty",
  "code": "INVALID_CONTENT",
  "timestamp": "2025-01-20T14:45:00.000Z"
}

500 Internal Server Error

An unexpected error occurred during export.


{
  "error": "Internal Server Error",
  "message": "An unexpected error occurred while generating export ZIP",
  "code": "INTERNAL_ERROR",
  "timestamp": "2025-01-20T14:45:00.000Z"
}

Example Requests

Download Lesson Export


curl -X GET 'https://your-domain.com/api/lessons/550e8400-e29b-41d4-a716-446655440000/versions/6ba7b810-9dad-11d1-80b4-00c04fd430c8/export-zip' \
  -H 'Authorization: Bearer tapub_xxxxx.tasec_xxxxx' \
  -o lesson-export.zip

Using wget


wget --header='Authorization: Bearer tapub_xxxxx.tasec_xxxxx' \
  'https://your-domain.com/api/lessons/550e8400-e29b-41d4-a716-446655440000/versions/6ba7b810-9dad-11d1-80b4-00c04fd430c8/export-zip' \
  -O lesson-export.zip

Export Manifest

If you need to download assets individually or implement custom export logic, you can use the manifest endpoint:


GET /api/lessons/{lessonId}/versions/{versionId}/export-manifest

This returns a JSON manifest with signed URLs for all assets (valid for 4 hours), allowing you to download files individually.

Notes

Only published lesson versions can be exported
The ZIP file includes all media assets and widget bundles required to play the lesson offline
Media references in lesson.json are automatically rewritten to use local paths
External media (e.g., from Unsplash) is downloaded and included in the ZIP
Attribution information for external media is preserved in manifest.json
Large exports may take several seconds to generate on the server
The failedMedia and failedWidgets arrays in the manifest indicate any assets that could not be downloaded