> ## 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.

# Caliper Events

> Choose the event contract for your Timeback integration

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.

```bash theme={null}
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](/beta/build-on-timeback/reference/partner-events) 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](/beta/build-on-timeback/reference/timeback-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](/beta/build-on-timeback/reference/platform-events) for native payloads. Keep event identity stable across an ambiguous retry and reconcile duplicate responses before creating a new event.

## Before launch

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