cmi5 API Reference

cmi5 launch protocol integration for Creatiq. Enables standards-compliant content delivery with xAPI-based tracking, following the cmi5 specification for assignable unit (AU) registration, launch, and session lifecycle management.

Base path: /api/cmi5

Endpoints

POST /api/cmi5/register

Register content for a cmi5 launch.

Description

Creates a cmi5 content registration binding a specific content item to a learner. Uses upsert logic -- if a registration for the same contentId + learnerId pair exists, it updates the updated_at timestamp. The registration starts in initialized status with Normal launch mode.

Request

{
  "contentId": "h5p-content-abc123",
  "learnerId": "user-12345",
  "actorAccount": {
    "homePage": "https://lms.example.com",
    "name": "user-12345"
  }
}

Response (201 Created)

{
  "success": true,
  "data": {
    "id": "uuid",
    "contentId": "h5p-content-abc123",
    "learnerId": "user-12345",
    "actorAccount": {
      "homePage": "https://lms.example.com",
      "name": "user-12345"
    },
    "status": "initialized",
    "sessionId": null,
    "score": null,
    "launchMode": "Normal",
    "createdAt": "2025-01-15T10:00:00.000Z",
    "updatedAt": "2025-01-15T10:00:00.000Z"
  }
}

Errors

GET /api/cmi5/launch/:registrationId

Generate a cmi5 launch URL for a registration.

Description

Generates a cmi5-compliant launch URL for the specified registration. The process:

1. Looks up the registration record.
2. Creates a one-time fetch token (cached in memory, 1-hour TTL).
3. Generates a new sessionId and sets registration status to launched.
4. Builds the launch URL with cmi5 query parameters.

The returned URL contains all parameters required by the cmi5 specification for AU launch.

Path Parameters

Response

{
  "success": true,
  "data": {
    "launchUrl": "https://app.creatiq.com/h5p/play/abc123?endpoint=https%3A%2F%2Fapp.creatiq.com%2Fapi%2Fxapi%2Fstatements&fetch=https%3A%2F%2Fapp.creatiq.com%2Fapi%2Fcmi5%2Ffetch%2F{token}&registration={id}&activityId=https%3A%2F%2Fapp.creatiq.com%2Fh5p%2Fcontent%2Fabc123&actor=%7B%22objectType%22%3A%22Agent%22%2C%22account%22%3A%7B%22homePage%22%3A%22...%22%2C%22name%22%3A%22...%22%7D%7D"
  }
}

Launch URL Query Parameters (cmi5 spec)

Errors

POST /api/cmi5/fetch/:token

Exchange a fetch token for an xAPI auth token (AU fetch endpoint).

Description

Called by the Assignable Unit (AU) during launch to obtain an xAPI authentication token. The fetch token is single-use -- it is deleted from the cache after exchange. Returns a JWT signed with JWT_SECRET containing the registrationId and purpose claim, valid for 1 hour.

Path Parameters

Response

{
  "auth-token": "eyJhbGciOiJIUzI1NiIs..."
}

The returned JWT payload:

{
  "registrationId": "uuid",
  "purpose": "cmi5-xapi-auth",
  "iat": 1705312800,
  "exp": 1705316400
}

Errors

GET /api/cmi5/sessions/:registrationId

Get the session status for a cmi5 registration.

Description

Returns the current session state for a registration, including status, score, and launch mode.

Path Parameters

Response

{
  "success": true,
  "data": {
    "id": "uuid",
    "contentId": "h5p-content-abc123",
    "learnerId": "user-12345",
    "actorAccount": {
      "homePage": "https://lms.example.com",
      "name": "user-12345"
    },
    "status": "completed",
    "sessionId": "uuid",
    "score": {
      "scaled": 0.85,
      "raw": 85,
      "min": 0,
      "max": 100
    },
    "launchMode": "Normal",
    "createdAt": "2025-01-15T10:00:00.000Z",
    "updatedAt": "2025-01-15T11:30:00.000Z"
  }
}

Errors

PUT /api/cmi5/sessions/:registrationId

Update the session status for a cmi5 registration.

Description

Updates the status and optionally the score for a cmi5 session. Used internally by the platform to reflect AU state transitions. If a score is provided, it is merged with any existing score (COALESCE -- does not overwrite with null).

Path Parameters

Request

{
  "status": "completed",
  "score": {
    "scaled": 0.85,
    "raw": 85,
    "min": 0,
    "max": 100
  }
}

Valid Status Values

Response

{
  "success": true,
  "data": {
    "id": "uuid",
    "contentId": "h5p-content-abc123",
    "learnerId": "user-12345",
    "status": "completed",
    "sessionId": "uuid",
    "score": { "scaled": 0.85, "raw": 85, "min": 0, "max": 100 },
    "launchMode": "Normal",
    "createdAt": "2025-01-15T10:00:00.000Z",
    "updatedAt": "2025-01-15T11:30:00.000Z"
  }
}

Errors

Session Lifecycle

initialized --> launched --> completed
                         --> passed
                         --> failed
                         --> abandoned
                         --> terminated
                         --> waived

The typical flow:

1. Register content for a learner (POST /register -- status: initialized).
2. Generate launch URL (GET /launch/:id -- status changes to launched).
3. AU opens in browser, calls fetch endpoint to get xAPI auth token.
4. AU sends xAPI statements to /api/xapi/statements using the auth token.
5. Session terminates with a final status update (PUT /sessions/:id).

cmi5 Verb Constants

Database Table

cmi5_registrations

Unique constraint: (content_id, learner_id).

Indexes: content_id, learner_id.