Report an insight, or move its start and end

​

Upsert for trusted reporters. The caller generates the insight id (a UUID), so a retry updates the same insight, and one id is always one insight. Reporting requires the caller's tenant to hold signals:report_insight:all on urn:platform. Call with the client's own token: a person's token, or one delegated to a person, is refused. 403 when the caller holds no grant, uses a person's token, or another client reported the id; 409 when the call changes type, version or tbSessionId.

OAuth scopes
  • https://timeback-platform.trilogy.com/signals/scope/insights.write

Path Parameters

  • insightId
    Type: stringFormat: uuid
    required

    Reporter-generated signals insight id

Body·

required
application/json

An insight a trusted reporter judged. The caller generates the insight id, so a retry updates the same insight. startedAt, endedAt, reason and severity can change under an existing id; type, version and tbSessionId cannot. A field left out of a later call keeps its stored value.

  • startedAt
    Type: stringFormat: date-time
    required

    the date-time notation as defined by RFC 3339, section 5.6, for example, 2017-07-21T17:32:28Z

  • tbSessionId
    Type: string
    required

    The session the insight happened in. The student comes from the session.

  • type
    Type: string
    required

    A registered insight type, for example PhoneUse. Types the platform judges itself are refused.

  • version
    Type: string
    required

    The type's registered version, for example v1.

  • endedAt
    Type: stringFormat: date-time

    Not before startedAt. Defaults to startedAt on the first call; a later call sets or extends it.

  • reason
    Type: string
    min length:  
    1
    max length:  
    5000

    Short, parent-safe description. Defaults to Reported by consumer.

  • severity
    Type: "red" or "orange"enum

    red reaches the school safety officer; orange is stored and counted but hidden.

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for put/signals/1.0/insights/{insightId}
curl https://platform.dev.timeback.com/signals/1.0/insights/123e4567-e89b-12d3-a456-426614174000 \
  --request PUT \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "type": "",
  "version": "",
  "tbSessionId": "",
  "startedAt": "",
  "endedAt": "",
  "reason": "",
  "severity": "red"
}'

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "type": "string",
  "version": "string",
  "tbSessionId": "string",
  "startedAt": "2026-10-29T14:38:22.771Z",
  "endedAt": "2026-10-29T14:38:22.771Z",
  "reason": null,
  "severity": "red",
  "rolloutState": "SHADOW",
  "outcome": "raised",
  "dateCreated": "2026-10-29T14:38:22.771Z",
  "dateLastModified": "2026-10-29T14:38:22.771Z"
}

The reported insight as stored

Previous
List Insight Groups
Next
Submit or replace insight feedback, or invalidate the insight