Platform Event Reference - Timeback Docs (Beta)

This reference applies to POST /caliper/v1p2 on your assigned Platform base URL and the native Caliper contract version 0.1.28. It does not describe the Partner Events API at /events/1.0 or the direct TimebackProfile contract.

Envelope and common fields

Send an envelope with an IRI sensor, UTC millisecond sendTime, dataVersion: "http://purl.imsglobal.org/ctx/caliper/v1p2", and nonempty data. The submission handler validates each item as an event. Although the shared envelope schema includes entity descriptions, do not infer that a standalone entity is accepted by this submission handler. Each native event requires @context with that same context value, a valid UUID URN id, type, eventTime, actor, action, and object. Timestamps must have exactly three fractional digits and end in Z, such as 2026-09-11T15:00:00.000Z. Many entity references accept an IRI or an embedded entity. Embedded entities require an ID and the matching entity type. Use identities assigned to your integration. The parser normalizes UUID URNs for internal use; continue sending the complete urn:uuid: form on the wire.

Native event families

The native event union implements these 12 types. A profile term being defined does not mean every event in that standard profile is implemented.

Family	Event types
Lifecycle and content	`SessionEvent`, `AssessmentEvent`, `AssessmentItemEvent`, `AssignableEvent`, `ViewEvent`
Scoring	`GradeEvent`
Media, navigation, and tools	`MediaEvent`, `NavigationEvent`, `ToolUseEvent`
Aggregated measurements	`ActivityEvent`, `TimeSpentEvent`
Monitoring	`AntiPatternEvent`

The event-specific schema determines its actions, required nested entities, and timing fields. Do not copy a Partner Events API event solely because its type has the same name. For example, native ViewEvent can reference its resource by IRI and does not require the Partner API’s generated attempt.

ActivityEvent

Use action: "Completed". The actor is a Person or IRI, and the object is an AssignableDigitalResource or IRI. The profile is AggregationProfile when supplied; it may be omitted or null. generated is an ActivityMetricsCollection. Each item is an ActivityMetric entity with its own id, metricType, and numeric metricValue. Known metric types are TotalQuestions, CorrectQuestions, XpEarned, MasteredUnits, and Mastered. Additional PascalCase metric terms up to 64 characters pass the schema, but need an agreed consumer interpretation. The schema does not impose a nonnegative constraint or a relationship between question metrics. This is a different wire format from TimebackProfile’s TimebackActivityMetricsCollection and lowercase type/value metric pairs.

TimeSpentEvent

Use action: "SpentTime" with the same actor and resource reference shapes. The profile is AggregationProfile when supplied. generated is a TimeSpentMetricsCollection. Each item is a TimeSpentMetric entity with its own id, metricType, and metricValue in seconds. Native time values must be integers between 0 and 86,400 inclusive. Known time metric types are Active, Inactive, Waste, Unknown, and AntiPattern. Custom PascalCase terms up to 64 characters are accepted. metricSubType, startDate, and endDate are optional. Keep the measured duration and timestamps consistent; schema acceptance does not prove the underlying measurement is correct.

Example native envelope

The following synthetic envelope records one activity and five minutes of active time. Replace example IDs with assigned student, content, and application identities. These two events have been checked against the native 0.1.28 event and envelope schemas.

{
  "sensor": "https://learning.example.com",
  "sendTime": "2026-09-11T15:00:00.000Z",
  "dataVersion": "http://purl.imsglobal.org/ctx/caliper/v1p2",
  "data": [
    {
      "@context": "http://purl.imsglobal.org/ctx/caliper/v1p2",
      "id": "urn:uuid:bd62c8de-7aa3-4c89-868a-a9523d94831f",
      "eventTime": "2026-09-11T15:00:00.000Z",
      "actor": "https://api.example.com/users/student-example",
      "object": "https://learning.example.com/lessons/fractions",
      "edApp": "https://api.example.com/applications/app-example",
      "type": "ActivityEvent",
      "action": "Completed",
      "profile": "AggregationProfile",
      "generated": {
        "id": "https://learning.example.com/metrics/activity-example",
        "type": "ActivityMetricsCollection",
        "items": [
          {
            "id": "https://learning.example.com/metrics/xp-example",
            "type": "ActivityMetric",
            "metricType": "XpEarned",
            "metricValue": 10
          }
        ]
      }
    },
    {
      "@context": "http://purl.imsglobal.org/ctx/caliper/v1p2",
      "id": "urn:uuid:70e919f3-5f1b-4056-82b3-d74d4fc45889",
      "eventTime": "2026-09-11T15:00:00.000Z",
      "actor": "https://api.example.com/users/student-example",
      "object": "https://learning.example.com/lessons/fractions",
      "edApp": "https://api.example.com/applications/app-example",
      "type": "TimeSpentEvent",
      "action": "SpentTime",
      "profile": "AggregationProfile",
      "generated": {
        "id": "https://learning.example.com/metrics/time-example",
        "type": "TimeSpentMetricsCollection",
        "items": [
          {
            "id": "https://learning.example.com/metrics/active-example",
            "type": "TimeSpentMetric",
            "metricType": "Active",
            "metricValue": 300,
            "startDate": "2026-09-11T14:55:00.000Z",
            "endDate": "2026-09-11T15:00:00.000Z"
          }
        ]
      }
    }
  ]
}

AntiPatternEvent

Use Started or Ended. The actor is a Person or IRI. The object is an AntiPattern entity or IRI. When supplied, the profile is MonitoringProfile. An embedded AntiPattern includes an ID, type: "AntiPattern", and antiPatternType, a PascalCase term up to 64 characters. Its start time, end time, and reason are optional. A custom type can pass schema validation without having a configured reporting rule.

Acceptance and compatibility

A 202 response acknowledges queue submission. It does not confirm that a derived insight, XP entry, or callback has completed. Preserve the event ID and payload for transport retries. If a retry reports that the ID already exists, reconcile durable state before sending a new identity. The endpoint also has a separate compatibility parser for selected TimebackProfile activity and time events. Compatibility does not change the native schema. Use the event format assigned to your integration and verify its downstream result.

​Envelope and common fields

​Native event families

​ActivityEvent

​TimeSpentEvent

​Example native envelope

​AntiPatternEvent

​Acceptance and compatibility