Caliper Events - Timeback Docs (Beta)

Timeback exposes different event contracts. Use the endpoint and credentials assigned to your integration. The Caliper version in dataVersion does not determine the HTTP path.

Contract	Endpoint	Request	Acceptance response
Partner Events API	`POST /events/1.0` on your Timeback API base URL	One supported event, or an envelope with exactly one event	`202` with `{"status":"ok"}`
Platform Caliper API	`POST /caliper/v1p2` on your Platform API base URL	Platform Caliper envelope	`202`
Timeback batch API	`POST /caliper/v2/caliper/event` on its assigned base URL	Batch Caliper envelope	`200`, `jobId: "0"`, and `groups`
Caliper service	`POST /caliper/event` on your Caliper base URL	Caliper 1.2 envelope containing one or more events	`200` with `status`, `message`, and `jobId`

The payload version does not make these endpoints interchangeable. In particular, /caliper/v1p2/events is not the submission path listed above. Use only the endpoint assigned to your integration.

Partner Events API

Send an access token with the https://purl.imsglobal.org/spec/caliper/v1p2/scope/events.write scope. Use HTTPS and send events from a trusted backend.

curl --request POST "$TIMEBACK_API_BASE_URL/events/1.0" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data-binary @event.json

The endpoint accepts GradeEvent, AssessmentEvent, AssessmentItemEvent, AssignableEvent, ViewEvent, and SessionEvent. These have Timeback-specific schemas. It does not accept ActivityEvent, TimeSpentEvent, MediaEvent, or NavigationEvent as partner event types. Use the partner event reference for actions, identifiers, metrics, timing, and complete payloads.

Acceptance and processing

202 means the event passed request validation and was queued. It does not prove that XP, assessment results, or reporting have updated.

Outcome	Meaning	What to do
`400`	Invalid JSON, unsupported event, invalid schema, or invalid reference when reference validation is enabled	Correct the payload before sending it again
`401` or `403`	Authentication or access failed	Check the assigned token and scope
`202`	Event was queued	Verify the expected result through your integration’s result or analytics read API
`500`	Request or queue operation failed	Retry with the same event identity after a bounded delay
`503` on a login event	The session could not be prepared	Honor `Retry-After` and retry the same event

For grade and assessment events, the referenced course must exist and belong to the application identified in the event. That check can occur after acceptance. A missing or mismatched course can prevent downstream writes even after a 202 response. An active enrollment is not a universal prerequisite for recording partner activity. An explicit valid course can receive a grade or assessment event before an enrollment exists. Enrollment and progression rules still affect how activity is used elsewhere.

Identity and retries

Assign each event a urn:uuid: identifier and preserve it, the original eventTime, and the attempt or session identity across transport retries. Use a new event ID for a distinct action. Do not change a submitted event’s meaning while retaining its ID. Deduplication and ordering differ across delivery paths. Do not assume that acceptance means exactly-once processing, or that two HTTP requests finish downstream in event-time order. Keep your own durable send record and make downstream callbacks safe to process more than once.

Direct Caliper integration

The Caliper service requires an envelope with sensor, sendTime, dataVersion, and a nonempty data array. The service’s event-create scope is https://purl.imsglobal.org/spec/caliper/v1p1/scope/event.create. This scope name differs from the Partner Events API scope. For an integration assigned the Timeback metrics profile, see Timeback activity and time events. A standard Caliper event that validates is not a promise of XP or progression support for that event. The Caliper service also exposes POST /caliper/event/validate. This validates without storing or sending events. Use synthetic identities in validation examples; schema validation does not confirm the existence of a student, course, or enrollment.

Platform Caliper API

The Platform endpoint /caliper/v1p2 requires the Caliper v1p2/scope/events.write scope. It validates its own native schemas and a compatibility subset for TimebackProfile metrics. It rejects malformed envelopes and event IDs already present in durable storage. A 202 response acknowledges queuing. Derived results may appear later or require additional processing. Do not substitute the Partner Events API event catalog for the Platform schema. Use the Platform event reference for native payloads. Keep event identity stable across an ambiguous retry and reconcile duplicate responses before creating a new event.

Before launch

Confirm the event contract, base URL, application ID, and credentials for your integration.
Use real assigned student and course IDs in your staging test, with synthetic learning content.
Send one event for each action your app will emit.
Verify the corresponding activity, score, time, or session result.
Repeat a delivery with the same event identity and verify the intended retry behavior.
Confirm which system owns XP and completion decisions. Do not infer those decisions from a Caliper type name.

​Partner Events API

​Acceptance and processing

​Identity and retries

​Direct Caliper integration

​Platform Caliper API

​Before launch