Insights to Signals Migration

Move your insight and session reads from the deprecated /insights/1.0 routes to the Signals routes that already serve them.

Note: This guide covers only what changes. See the API Reference for complete endpoint documentation, and Signals Insights for reporting insights.

Before you start

1. Request the Signals read scope for your client: https://timeback-platform.trilogy.com/signals/scope/insights.readonly. It replaces https://purl.imsglobal.org/spec/caliper/v1p2/scope/events.readonly for these reads. A token without it gets 401 from the Signals routes. Ask for it through Getting access.
2. Keep your current calls running while you switch. The old routes keep working with the same parameters and responses until they are removed, and each response carries a Deprecation header. The Signals routes do not send it.

Route mapping

Old route (scope events.readonly)	New route (scope signals/scope/insights.readonly)	What changes
GET /insights/1.0/sessions/{sessionId}	GET /signals/1.0/sessions/{sessionId}/insights	Insight field names and two status codes; see below
GET /insights/1.0/sessions	GET /signals/1.0/sessions	Nothing, unless you use the learning-integrity filters; see below
GET /insights/1.0/users/{userId}	GET /signals/1.0/users/{userId}/insights	Nothing
GET /insights/1.0/users/{userId}/sessions	GET /signals/1.0/users/{userId}/sessions	Nothing
GET /insights/1.0/users/{userId}/overview	GET /signals/1.0/users/{userId}/overview	Nothing
GET /insights/1.0/types	GET /signals/1.0/insights/types	No id, and more types; see below

"Nothing" means the same parameters and the same response body: change the path and the scope.

What changes per route

Session insights

GET /signals/1.0/sessions/{sessionId}/insights takes the same path and query parameters and returns the same session summary and paging. Each entry in insights changes:

Old field	New field
insightType	type
startedAtTime	startedAt
endedAtTime	endedAt
evidence.caliperSessionId	Removed. It is the sessionId you asked for
none	rule, ruleVersion: the rule that produced the insight, Reported for a reported insight

Status codes change for two cases:

• A session outside your organization access returns 200 with no insights and a zero summary, where the old route returned 403.
• An unknown type or insightGroups slug returns 200 with no insights, where the old route returned 400. Check your slugs against GET /signals/1.0/insights/types.

limit and offset must be whole numbers; a fractional value returns 400.

Org sessions

Without the learning-integrity filters, GET /signals/1.0/sessions returns the same page as the old route.

The learning-integrity review listing is not on the Signals route. On the old route, unauthorizedTags, integrityTags and reviewState narrow the list to learning sessions with unauthorized-help tags and add integrityTags, noteCount and review to each session and integrityTagCounts to the page. The Signals route ignores those parameters and returns every matching session, without those fields. If you use this listing, keep calling GET /insights/1.0/sessions for it: the Signals routes have no equivalent today.

enforcement and includeEnforcement match no session and have no effect on the old route. Drop them.

Insight types

GET /signals/1.0/insights/types takes the same category and insightGroups parameters and returns the same entries in the same order, with two differences:

• Entries have no id. Use slug, which is what every insight carries in type.
• The list also includes the v1 catalog types the old route hides, such as SocializingDuringTest and TestIntegrityVerdict. Select by category and read the slugs from the response rather than from a fixed list.

Webhooks

• insight.created, insight.updated and insight.deleted keep their names and payloads. No change is needed.
• proctoring_enforcement.recorded is replaced by action.created. A proctoring action (BlockTest, UnblockTest, EndTest, PreventTestStart) fires action.created; filter on data.type. Add action.created to your subscription. See Action Events.

Checklist

1. Get https://timeback-platform.trilogy.com/signals/scope/insights.readonly on your client.
2. Change each path in the route mapping.
3. For session insights, read type, startedAt and endedAt, and treat an empty 200 as no access or no match.
4. For insight types, key on slug, not id.
5. Keep the learning-integrity review listing on the old route.
6. Subscribe to action.created in place of proctoring_enforcement.recorded.