> ## Documentation Index
> Fetch the complete documentation index at: https://docs.timeback.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Platform Event Reference

> Native event schemas for the Platform Caliper API

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.

```json theme={null}
{
  "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.