> ## 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. # Create Events > Receives and processes Caliper events wrapped in an envelope. Events will be validated against the IMS Caliper Analytics specification and stored for further processing and analysis. ## OpenAPI ````yaml /openapi/beyond-ai/caliper-api.yaml post /caliper/event openapi: 3.1.0 info: title: Caliper API version: 1.0.0 description: >- # Documentation ## Overview The Alpha Caliper API is a service that receives, validates, and processes learning events conforming to the [IMS Caliper Analytics® specification](https://www.imsglobal.org/spec/caliper/v1p2). This API enables educational technology platforms to track and analyze student engagement, learning activities, and assessment outcomes. ## Key Features - **Event Validation**: Ensures all submitted events conform to the Caliper Analytics specification - **Event Processing**: Processes and stores valid events for analytics - **Multiple Event Profiles**: Supports various Caliper event profiles ## Getting Started To use this API, you need to: 1. **Familiarize with Caliper**: Understand the [IMS Caliper Analytics specification](https://www.imsglobal.org/spec/caliper/v1p2) 2. **Format Your Events**: Structure your events according to the Caliper data model 3. **Submit Events**: Send events to our API endpoints wrapped in a Caliper envelope --- # Frequently Asked Questions ## Purpose of the API Q: **What is the purpose of the Alpha Caliper API?** A: Receive, validate and store learning events conforming to the [IMS Caliper Analytics® specification](https://www.imsglobal.org/spec/caliper/v1p2). --- ## Out of scope Q: **What is not the (direct) purpose of the Alpha Caliper API?** A: - Generate insights from events. (ETL) - Provide a learning analytics platform. - Provide a learning content management system. - Raw crud apis. --- ## Insights generation Q: **Does Caliper have an ETL layer to extract insights from the events sent?** A: No, caliper is only responsible for storing the events, other services may implement an ETL layer to extract insights from specific events. Caliper acts like a data warehouse, it's purpose is to store events and make them available for reporting and analytics. --- ## Specific Use-cases Q: **Which events should I send?** A: The Alpha Caliper API supports the entire Caliper specification. We also extended the base spec to contain specific events for the Timeback platform. - If you are using the Timeback platform, take a look at the section below for supported use-cases. - If your use-case is not supported, please contact us to discuss how we can extend the spec to support your use-case. - If you want your events to be processed by the Alpha Analytics API (ETL), you need to conform to the TimeBack Profile and it's supported events. --- # Timeback Platform Users ## Guide If you are a user of the timeback platform you may have these questions: - Q: **How do I give XP to my students?** - Q: **How do I record time spent on activities?** - Q: **How do I provided information about total questions, correct answers, etc?** A: Use The **Timeback Profile**, which is a profile that extends the base Caliper specification to support the Timeback platform. It contains the following events: - **TimebackActivityEvent** - used to record student interaction with an activity. - **TimebackTimeSpentEvent** - used to record the time spent on an activity. See the timeback docs for more information: [Timeback Docs](https://caliper.alpha-1edtech.ai/scalar?api=timeback-events-api) --- # Authentication ## Guide Most endpoints require authentication using the `Authorization: Bearer ` header. The token can be obtained with: ``` curl -X POST https://prod-beyond-timeback-api-2-idp.auth.us-east-1.amazoncognito.com/oauth2/token \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "grant_type=client_credentials&client_id=&client_secret=" ``` Use the correct IDP server depending on the environment you're using. IDP Server for this environment: ```text https://prod-beyond-timeback-api-2-idp.auth.us-east-1.amazoncognito.com ``` Reach out to the platform team to get a client/secret pair for your application. servers: - url: https://caliper.alpha-1edtech.ai description: Caliper API security: - OAuth2: [] tags: - name: Events description: >- These are the endpoints to use when submitting and validating Caliper Events - name: Jobs description: These are the endpoints to use when checking the status of background jobs paths: /caliper/event: post: tags: - Events summary: Create Events description: >- Receives and processes Caliper events wrapped in an envelope. Events will be validated against the IMS Caliper Analytics specification and stored for further processing and analysis. requestBody: description: The Caliper envelope containing events to process required: true content: application/json: schema: $ref: '#/components/schemas/Envelope' examples: example1: summary: 1 - Generic Event Example description: Example of a basic Generic event value: sensor: https://alpharead.alpha.school sendTime: dataVersion: http://purl.imsglobal.org/ctx/caliper/v1p2 data: - id: urn:uuid:c51570e4-f8ed-4c18-bb3a-dfe51b2cc594 type: Event actor: https://example.edu/users/554433 action: Created object: >- https://example.edu/terms/201801/courses/7/sections/1/assignments/1 eventTime: '2023-08-15T14:12:00.000Z' example2: summary: 2 - Tool Use Event Example description: Example of a basic Tool Use event value: sensor: https://alpharead.alpha.school sendTime: dataVersion: http://purl.imsglobal.org/ctx/caliper/v1p2 data: - '@context': http://purl.imsglobal.org/ctx/caliper/v1p2 id: urn:uuid:7e10e4f3-a0d8-4430-95bd-783ffae4d916 type: ToolUseEvent profile: ToolUseProfile actor: id: https://example.edu/users/554433 type: Person action: Used object: id: https://example.edu type: SoftwareApplication eventTime: '2016-11-15T10:15:00.000Z' edApp: https://example.edu group: id: https://example.edu/terms/201601/courses/7/sections/1 type: CourseSection extensions: courseNumber: CPS 435-01 academicSession: Fall 2016 example3: summary: 3 - Annotation Event Example description: Example of a basic Annotation event value: sensor: https://alpharead.alpha.school sendTime: dataVersion: http://purl.imsglobal.org/ctx/caliper/v1p2 data: - '@context': http://purl.imsglobal.org/ctx/caliper/v1p2 id: urn:uuid:7e10e4f3-a0d8-4430-95bd-783ffae4d916 type: AnnotationEvent profile: AnnotationProfile actor: id: https://example.edu/users/554433 type: Person action: Highlighted object: id: https://example.edu/terms/201801/courses/7/resources/1 type: DigitalResource generated: id: https://example.edu/users/554433/annotations/1 type: HighlightAnnotation annotator: https://example.edu/users/554433 annotated: https://example.edu/terms/201801/courses/7/resources/1 selection: type: TextPositionSelector start: 412 end: 795 eventTime: '2023-08-01T06:00:00.000Z' edApp: https://example.edu/apps/annotation-tool example4: summary: 4 - Tool Use Generated Metrics description: Example of a basic Tool Use event with generated metrics value: sensor: https://alpharead.alpha.school sendTime: dataVersion: http://purl.imsglobal.org/ctx/caliper/v1p2 data: - id: urn:uuid:c51570e4-f8ed-4c18-bb3a-dfe51b2cc594 type: ToolUseEvent profile: ToolUseProfile actor: id: >- https:/your-app.domain/users/fdeb7d92-b3a4-4b6c-a201-cb590b43bce1 type: Person extensions: email: noemail@student.com action: Used object: id: https:/your-app.domain name: Learning type: SoftwareApplication generated: id: >- https:/your-app.domain/session/adac039d-4ff4-48b9-bfb0-8ec37ac9d1ea type: AggregateMeasureCollection items: - id: >- https:/your-app.domain/session/adac039d-4ff4-48b9-bfb0-8ec37ac9d1ea type: AggregateMeasure metric: Facts Learnt metricValue: 2 - id: >- https:/your-app.domain/session/adac039d-4ff4-48b9-bfb0-8ec37ac9d1ea type: AggregateMeasure metric: Facts Practiced metricValue: 4 - id: >- https:/your-app.domain/session/adac039d-4ff4-48b9-bfb0-8ec37ac9d1ea type: AggregateMeasure metric: Facts Assessed metricValue: 3 session: id: >- https:/your-app.domain/session/adac039d-4ff4-48b9-bfb0-8ec37ac9d1ea type: Session extensions: session_id: adac039d-4ff4-48b9-bfb0-8ec37ac9d1ea eventTime: '2025-03-25T14:12:00.000Z' responses: '200': description: The events were processed successfully content: application/json: schema: type: object properties: status: type: string const: success message: type: string errors: {} required: - status - message '400': description: The request payload is invalid content: application/json: schema: type: object properties: status: type: string const: error message: type: string errors: {} required: - status - message components: schemas: Envelope: type: object properties: sensor: type: string format: uri description: >- The sensor.id that uniquely identifies the Caliper Sensor. Should be in the form of an IRI example: https://example.edu/sensors/1 sendTime: type: string format: date-time description: >- The time the data was sent, formatted as an ISO 8601 date and time in UTC example: '2023-08-15T14:12:00.000Z' dataVersion: type: string const: http://purl.imsglobal.org/ctx/caliper/v1p2 description: >- The data format version. Indicates which version of the Caliper specification governs the form of the entities and events example: http://purl.imsglobal.org/ctx/caliper/v1p2 data: type: array items: anyOf: - $ref: '#/components/schemas/Event' - $ref: '#/components/schemas/Entity' minItems: 1 description: >- The data payload, consisting of an array where items are Caliper Events or Entities example: - id: urn:uuid:c51570e4-f8ed-4c18-bb3a-dfe51b2cc594 type: Event actor: https://example.edu/users/554433 action: Created object: >- https://example.edu/terms/201801/courses/7/sections/1/assignments/1 eventTime: '2023-08-15T14:12:00.000Z' required: - sensor - sendTime - dataVersion - data description: |- # Envelope Represents a package containing events and entity data for ingestion Event: type: object properties: '@context': type: string format: uri default: http://purl.imsglobal.org/ctx/caliper/v1p2 description: The context of the Caliper entity data example: http://purl.imsglobal.org/ctx/caliper/v1p2 id: type: string pattern: ^urn:uuid:(.*)$ description: Unique identifier for this event. Must be a UUID expressed as a URN example: urn:uuid:c51570e4-f8ed-4c18-bb3a-dfe51b2cc594 type: type: string description: >- The type of this event. Must match the term specified in the Caliper information model example: Event actor: type: - string - object description: The agent who initiated the event example: https://example.edu/users/554433 action: type: string description: The action or predicate that binds the actor to the object example: Created object: type: - string - object description: The object of the interaction example: https://example.edu/terms/201801/courses/7/sections/1/assignments/1 eventTime: type: string format: date-time description: ISO 8601 datetime when this event occurred example: '2023-08-15T14:12:00.000Z' profile: allOf: - $ref: '#/components/schemas/AllProfiles' description: The profile that governs interpretation of this event example: AnnotationProfile edApp: type: - string - object description: The application context example: https://example.edu/apps/learning-management generated: type: - string - object description: Entity generated as a result of the interaction example: https://example.edu/users/554433/responses/1 target: type: - string - object description: >- Entity that represents a particular segment or location within the object example: >- https://example.edu/terms/201801/courses/7/sections/1/assignments/1/items/1 referrer: type: - string - object description: Entity that represents the referring context example: https://example.edu/terms/201801/courses/7/sections/1 group: type: - string - object description: >- An Organization that represents the group context. Can be either a URI or an Organization entity object example: id: https://example.edu/terms/201801/courses/7/sections/1 type: Organization extensions: info: other params should follow organization schema membership: type: - string - object description: >- The relationship between the action and the group in terms of roles and status example: https://example.edu/terms/201801/courses/7/sections/1/rosters/1 session: type: - string - object description: The current user Session example: >- https://example.edu/sessions/1f6442a482de72ea6ad134943812bff564a76259 federatedSession: type: - string - object description: >- If the Event occurs within the context of an LTI platform launch, the tool's LtiSession example: https://example.edu/lti-sessions/b533eb02823f31024765305dd3af7b5e extensions: type: object additionalProperties: {} description: Additional attributes not defined by the model example: customField: customValue required: - id - type - actor - action - object - eventTime - profile additionalProperties: false description: |- # Event Represents a Caliper Event that describes learning activities Entity: type: object properties: '@context': type: string format: uri default: http://purl.imsglobal.org/ctx/caliper/v1p2 description: The context of the Caliper entity data example: http://purl.imsglobal.org/ctx/caliper/v1p2 id: type: string format: uri description: >- The unique identifier for this entity. Must be a valid IRI and should be dereferenceable example: https://example.edu/entity/554433 type: type: string description: >- The type of this entity. Must match the term specified in the Caliper information model example: Entity name: type: string description: A word or phrase by which the entity is known example: John Doe description: type: string description: A brief, written representation of the entity example: A student at Example University dateCreated: type: string format: date-time description: ISO 8601 datetime when this entity was created example: '2023-08-15T14:12:00.000Z' dateModified: type: string format: date-time description: ISO 8601 datetime when this entity was last modified example: '2023-08-15T14:12:00.000Z' extensions: type: object additionalProperties: {} description: Additional attributes not defined by the model example: customField: customValue otherIdentifiers: type: array items: type: - string - object required: - id - type additionalProperties: false description: >- # Entity Represents a generic Caliper Entity that participates in learning-related activities. Can be provided in an envelope for context. AllProfiles: type: string enum: - AnnotationProfile - AssessmentProfile - ToolUseProfile - GeneralProfile - FeedbackProfile - MediaProfile - SurveyProfile - ResourceManagementProfile - ForumProfile - AssignableProfile - GradingProfile - ReadingProfile - SessionProfile - SearchProfile - ToolLaunchProfile - TimebackProfile description: >- # Supported Profiles These are the profiles that this API currently supports. See the [specification](https://www.imsglobal.org/spec/caliper/v1p2#profiles-0) for a list of all profiles. securitySchemes: OAuth2: type: oauth2 flows: clientCredentials: scopes: https://purl.imsglobal.org/spec/caliper/v1p1/scope/admin: Admin scope (can call all endpoints) https://purl.imsglobal.org/spec/caliper/v1p1/scope/webhook.create: Webhook create scope (can create and update webhooks) https://purl.imsglobal.org/spec/caliper/v1p1/scope/webhook.readonly: Webhook readonly scope (can read webhooks) https://purl.imsglobal.org/spec/caliper/v1p1/scope/event.create: Event create scope (can create events) tokenUrl: >- https://prod-beyond-timeback-api-2-idp.auth.us-east-1.amazoncognito.com/oauth2/token ````