# API Documentation

> Complete API documentation

## Getting Started

### Introduction

# Getting Started with TimeBack Platform

The TimeBack Platform is a **unified platform** that enables learning apps to provide **coaching insights**, **seamless authentication**, and **unified progress tracking** without building this infrastructure themselves.

## Introduction

Welcome to the **TimeBack Platform documentation**.

We have a mission: to enable learning app developers to launch sophisticated educational experiences with **minimal backend complexity** and **no specialized learning science infrastructure**.

The TimeBack Platform is being built to provide comprehensive learning infrastructure including **curriculum management and sequencing**, **content publishing and distribution**, **learning algorithms**, **student authentication**, **behavior analytics**, and **AI-powered coaching**. This documentation focuses on the **initial integration levels** available now, with additional capabilities being added over time.

Whether you're building a new learning app or integrating an existing one, our documentation will guide you through each integration level—from basic app catalog listing to deep analytics integration.

## Integration Levels

TimeBack offers **progressive integration**—start with app catalog registration, then add deeper capabilities as needed.

| Level                           | Capability                                       | What You Get                                                                                                                                                                                                                                                                                                                                                                                                          |
| ------------------------------- | ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Level 0: Registration**       | App catalog listing + automatic session tracking | Students discover your app in TimeBack's catalog. When launched from TimeBack App, we automatically track session time, detect time waste, and provide coaching insights—**no implementation required**. If we have student credentials on file, we can auto-login students with minimal work on your side. If your app is linked from another TimeBack app, auto-login and session attribution happen automatically. |
| **Level 1: Student Onboarding** | Roster management                                | Programmatically create and manage students, users, and agent relationships (parents, guardians) in TimeBack's roster via API.                                                                                                                                                                                                                                                                                        |
| **Level 2: LTI Launch**         | Seamless authentication                          | Students auto-login to your app via LTI 1.3—no credentials needed, no login screens. Improves user experience by eliminating authentication friction.                                                                                                                                                                                                                                                                 |
| **Level 3: Caliper Events**     | Deep analytics + unified reporting               | Send structured learning events (questions, answers, mastery) to get richer coaching insights and unified progress analytics across the TimeBack ecosystem. Powers cross-app intelligence and detailed behavior analysis.                                                                                                                                                                                             |

**Important:** All automatic tracking and insights require students to use the **TimeBack App** (Electron-based desktop container). TimeBack App handles screen recording permissions, launches your app in an embedded browser, and captures session data automatically.

**Future capabilities:** TimeBack will offer additional integration levels for curriculum management, content distribution, and built-in learning algorithms. These capabilities are in development and will be documented as they become available.

## Getting Started

To start using the TimeBack Platform:

1. **Register your app** by submitting a [registration request](https://docs.platform.timeback.com/public-level-0-registration.txt)
2. **Get your credentials** (Client ID + Client Secret + authorized scopes) from the TimeBack team
3. **Onboard students** programmatically via the [roster API](https://docs.platform.timeback.com/public-level-1-student-onboarding.txt) — students must exist in TimeBack to receive insights
4. **Implement LTI 1.3 launch** to enable seamless student authentication
5. **Send Caliper events** to unlock coaching insights and progress tracking

Our documentation includes detailed guides, complete code examples, and references to help you integrate TimeBack into your learning app quickly and effectively.

### 1EdTech Standards

TimeBack is built on [1EdTech standards](https://www.1edtech.org/specifications) to maximize interoperability:

- OneRoster: Student roster management for creating and managing users
- LTI 1.3: Industry-standard launch protocol used by learning management systems
- Caliper Analytics: Standardized learning event vocabulary

---

## LLM-Friendly Docs

We provide this exact same documentation in LLM-friendly format for usage with any AI:

- **Navigation index** (links with descriptions): https://docs.platform.timeback.com/llms.txt
- **Full documentation** (all content in one file): https://docs.platform.timeback.com/llms-full.txt

## Next Steps

### [Level 0: Register Your App](https://docs.platform.timeback.com/public-level-0-registration.txt)

Submit your app details to get listed in TimeBack's app catalog. This is the required first step for all integrations.

### [Level 1: Student Onboarding](https://docs.platform.timeback.com/public-level-1-student-onboarding.txt)

Programmatically create and manage students, users, and agent relationships in TimeBack's roster.

### [Level 2: Implement LTI Launch](https://docs.platform.timeback.com/public-level-2-lti-launch.txt)

Add seamless authentication so students can access your app without managing separate credentials.

### [Level 3: Send Caliper Events](https://docs.platform.timeback.com/public-level-3-caliper.txt)

Send structured learning activity events to unlock coaching insights and unified analytics.


### Authentication

# Authentication: How to Connect

Step-by-step guide for authenticating with TimeBack Platform APIs using OAuth 2.0 client credentials.

## Authentication Model

TimeBack Platform uses OAuth 2.0 client credentials for server-to-server authentication. This is the only authentication method currently supported; user-based authentication may be added in the future.

## Environments

TimeBack provides two environments for development and production:

### Staging

- **Base URL**: `https://platform.dev.timeback.com`
- **LTI Issuer**: `https://staging.timeback.com`
- **LTI JWKS URL**: `https://platform.dev.timeback.com/.well-known/jwks.json`

Use staging for all development and testing. This environment is separate from production data.

### Production

- **Base URL**: `https://platform.timeback.com`
- **LTI Issuer**: `https://timeback.com`
- **LTI JWKS URL**: `https://platform.timeback.com/.well-known/jwks.json`

Request production credentials only when your integration is tested and ready to launch.

## Step 1: Request Credentials

Contact [timeback@trilogy.com](mailto:timeback@trilogy.com) to request OAuth client credentials.

**Provide in your request:**

- App name and description
- Environment (staging or production)
- Which platform APIs you need access to
- Intended use case

**You will receive:**

- Client ID
- Client Secret
- List of authorized scopes

## Step 2: Exchange Credentials for Access Token

Make a POST request to the token endpoint:

```bash
curl -X POST https://platform.timeback.com/auth/1.0/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -u "<CLIENT_ID>:<CLIENT_SECRET>" \
  -d "grant_type=client_credentials&scope=<SCOPES>"
```

Replace `<CLIENT_ID>`, `<CLIENT_SECRET>`, and `<SCOPES>` with your credentials.

**Response:**

```json
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 3600,
  "token_type": "Bearer",
  "scope": "https://purl.imsglobal.org/spec/caliper/v1p2/scope/events.write"
}
```

## Step 3: Use the Access Token

Include the access token in all API requests:

```bash
curl -X POST https://platform.timeback.com/events/1.0/ \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -d '{
    "@context": "http://purl.imsglobal.org/ctx/caliper/v1p2",
    "type": "SessionEvent",
    "actor": "urn:uuid:student-id",
    "action": "Started",
    "eventTime": "2025-12-15T10:00:00Z",
    "edApp": "urn:uuid:your-app-id"
  }'
```

## Token Management

### Caching Tokens

Tokens expire after 1 hour. Cache the token and reuse it for multiple requests:

```typescript
let accessToken: string | null = null;
let tokenExpiresAt: number | null = null;

async function getValidToken(): Promise<string> {
  const now = Date.now();

  // Return cached token if still valid
  if (accessToken && tokenExpiresAt && now < tokenExpiresAt) {
    return accessToken;
  }

  // Fetch new token
  const response = await fetch('https://platform.timeback.com/auth/1.0/token', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
      Authorization: `Basic ${Buffer.from(`${clientId}:${clientSecret}`).toString('base64')}`,
    },
    body: new URLSearchParams({
      grant_type: 'client_credentials',
      scope: scopes.join(' '),
    }),
  });

  const tokenData = await response.json();
  accessToken = tokenData.access_token;

  // Cache with 10% safety buffer (54 minutes for 1-hour tokens)
  const expirationBuffer = (tokenData.expires_in || 3600) * 0.9;
  tokenExpiresAt = now + expirationBuffer * 1000;

  return accessToken;
}
```

### Handling Token Expiry

If an API call returns `401 Unauthorized`, refresh your token and retry once:

```typescript
const token = await getValidToken();
const response = await fetch(url, {
  headers: { Authorization: `Bearer ${token}` },
  // ... rest of request
});

// Token expired mid-request - refresh and retry
if (response.status === 401) {
  const newToken = await getValidToken(); // Forces refresh
  return await fetch(url, {
    headers: { Authorization: `Bearer ${newToken}` },
    // ... rest of request
  });
}
```

## Scopes

Scopes control what your credentials can access. TimeBack uses 1EdTech standard scope URIs:

| Scope                                                             | Capability                   |
| ----------------------------------------------------------------- | ---------------------------- |
| `https://purl.imsglobal.org/spec/or/v1p2/scope/roster.createput`  | Create/update roster data    |
| `https://purl.imsglobal.org/spec/or/v1p2/scope/roster.readonly`   | Read student roster data     |
| `https://purl.imsglobal.org/spec/caliper/v1p2/scope/events.write` | Send Caliper learning events |

Request only the scopes your app needs. Scopes are assigned during credential setup and cannot be changed without contacting the TimeBack team.

## Common Pitfalls

### Not caching tokens

```typescript
// ❌ Bad: Fetch new token for every request
async function sendEvent(event) {
  const token = await fetchNewToken(); // Wastes time, hits rate limits
  await sendEventWithToken(token, event);
}

// ✅ Good: Cache and reuse tokens
async function sendEvent(event) {
  const token = await getValidToken(); // Returns cached if still valid
  await sendEventWithToken(token, event);
}
```

### Not handling 401 responses

```typescript
// ❌ Bad: No retry on token expiry
const response = await fetch(url, { headers: { Authorization: `Bearer ${token}` } });
// Fails permanently if token expired

// ✅ Good: Refresh and retry
if (response.status === 401) {
  const newToken = await refreshToken();
  return await fetch(url, { headers: { Authorization: `Bearer ${newToken}` } });
}
```

---

## Related Docs

### [Level 1: Student Onboarding](https://docs.platform.timeback.com/public-level-1-student-onboarding.txt)

Use your authenticated credentials to manage students and users in TimeBack's roster.

### [Level 2: LTI Launch](https://docs.platform.timeback.com/public-level-2-lti-launch.txt)

Implement seamless student authentication via LTI 1.3.

### [Level 3: Send Caliper Events](https://docs.platform.timeback.com/public-level-3-caliper.txt)

Use your authenticated credentials to send learning activity events to TimeBack Platform.


## Integration

### Level 0: Registration

# Level 0: Register Your App

Get your app listed in TimeBack's catalog so students can discover and launch it.

## What Registration Provides

Registering your app makes it discoverable in TimeBack's app catalog. Once registered, students can launch your app from TimeBack App, which automatically tracks session time, detects waste time, and provides coaching insights, without any implementation required from you.

## Submission Process

1. **Prepare your app information** using the fields below
2. **Email your registration request** to [timeback@trilogy.com](mailto:timeback@trilogy.com)
3. **Receive confirmation** within 1 business day

Include "TimeBack Registration: [Your App Name]" in your email subject line.

## Required Information

| Field             | Description                                     | Example                                                                                        |
| ----------------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| **Name**          | Your app's display name                         | TrashCat                                                                                       |
| **Description**   | One-sentence description (displayed in catalog) | An endless runner game that builds multiplication fact fluency through rapid-fire math drills. |
| **Logo URL**      | Square image, max 512px                         | `https://trashcat.learnwith.ai/images/logo.png`                                                |
| **Landing URL**   | Where students land when launching your app     | `https://trashcat.learnwith.ai/`                                                               |
| **Organizations** | Which schools/groups can access your app        | Alpha, Learn & Earn, SuperBuilders                                                             |

### Organizations

Select which organizations your app should be available for. Current options:

- Alpha
- Learn & Earn
- Alpha Anywhere
- Texas Sports Academy
- SuperBuilders

If you need your app available for a specific school or organization not listed, mention it in your request.

## Optional Information

Including these fields improves discoverability and provides better context for students and educators:

| Field                | Description                                 | Example                                                                                                |
| -------------------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| **Full Description** | Detailed description (2-3 paragraphs)       | TrashCat uses spaced repetition and adaptive difficulty to build automaticity with basic math facts... |
| **Publisher Name**   | Your company or organization name           | LearnWith.AI                                                                                           |
| **Subjects**         | Academic subjects covered (comma-separated) | Mathematics                                                                                            |
| **Grade Range**      | Supported grades in K-12 format             | 3, 4, 5, 6                                                                                             |
| **Language Support** | Supported languages (comma-separated)       | English, Spanish                                                                                       |

**Note on LTI:** If you plan to implement LTI 1.3 for seamless authentication, you can include LTI-specific fields in the same registration email. See [Level 2: LTI Launch](https://docs.platform.timeback.com/public-level-2-lti-launch.txt) for required LTI fields and implementation details. You can either:

- Submit everything in one email (requires LTI endpoint ready first)
- Register first, implement LTI later, then send update email

The quickest path is to implement LTI before registering and submit once, but both approaches work.

## After Submission

After you submit your registration request:

1. We'll review your submission within 1 business day
2. We'll notify you when your app is live in the catalog
3. Your app will appear for the selected organizations

**Optional:** If you plan to implement Level 3 (Caliper events), you can request OAuth client credentials in the same email. See [Authentication Guide](https://docs.platform.timeback.com/public-authentication.txt) for more information.

## What Happens Next

Once registered, students in the selected organizations can:

- Discover your app in TimeBack's catalog
- Launch your app from TimeBack App
- Have their session time automatically tracked

TimeBack App will handle session tracking, time monitoring, and waste detection automatically. No additional implementation required from you.

**To manage students programmatically**, proceed to [Level 1: Student Onboarding](https://docs.platform.timeback.com/public-level-1-student-onboarding.txt).

**To enable seamless auto-login**, proceed to [Level 2: LTI Launch](https://docs.platform.timeback.com/public-level-2-lti-launch.txt).

**To send learning events for deeper insights**, proceed to [Level 3: Caliper Events](https://docs.platform.timeback.com/public-level-3-caliper.txt).

---

## Related Docs

### [Introduction](https://docs.platform.timeback.com/public-introduction.txt)

Overview of TimeBack Platform and integration levels. Start here if you're new to the platform.

### [Level 1: Student Onboarding](https://docs.platform.timeback.com/public-level-1-student-onboarding.txt)

Programmatically create and manage students, users, and agent relationships in TimeBack's roster.

### [Level 2: LTI Launch](https://docs.platform.timeback.com/public-level-2-lti-launch.txt)

Implement LTI 1.3 to enable seamless student authentication and eliminate login friction.


### Level 1: Student Onboarding

# Level 1: Student Onboarding

Programmatically create and manage students, users, and their relationships (parents, guardians) in TimeBack's roster.

## What Student Onboarding Provides

Student onboarding enables your learning app to:

- Create and update student records in TimeBack's roster
- Manage user accounts with roles and profiles
- Link students to agents (parents, guardians, relatives)
- Query agent relationships for a user

This is foundational for apps that need to manage student data programmatically rather than relying solely on LTI authentication or manual registration.

## Prerequisites

Before implementing student onboarding:

1. **Register your app** (see [Level 0: Registration](https://docs.platform.timeback.com/public-level-0-registration.txt))
2. **Request OAuth credentials** with the `roster.createput` scope (see [Authentication Guide](https://docs.platform.timeback.com/public-authentication.txt))

## Implementation Guide

### Step 1: Obtain Access Token

Request an access token with roster write permissions:

```typescript
const response = await fetch('https://platform.timeback.com/auth/1.0/token', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
    Authorization: `Basic ${Buffer.from(`${clientId}:${clientSecret}`).toString('base64')}`,
  },
  body: new URLSearchParams({
    grant_type: 'client_credentials',
    scope: 'https://purl.imsglobal.org/spec/or/v1p2/scope/roster.createput',
  }),
});

const { access_token } = await response.json();
```

### Step 2: Create or Update a Student

Use the `upsertStudent` endpoint to create a new student or update an existing one:

```
PUT https://platform.timeback.com/rostering/1.0/students
```

**Example request:**

```typescript
const studentData = {
  student: {
    sourcedId: 'student-uuid-here', // Your unique identifier for this student
    status: 'active',
    username: 'john.doe',
    enabledUser: 'true',
    givenName: 'John',
    familyName: 'Doe',
    middleName: null,
    email: 'john.doe@example.com',
    phone: null,
    grades: ['5'],
    primaryOrg: {
      sourcedId: 'organization-uuid', // The school/org this student belongs to
      type: 'org',
    },
  },
};

const response = await fetch('https://platform.timeback.com/rostering/1.0/students', {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${accessToken}`,
  },
  body: JSON.stringify(studentData),
});

// Returns 200 OK on success
```

**Required fields:**

| Field         | Type     | Description                                     |
| ------------- | -------- | ----------------------------------------------- |
| `sourcedId`   | string   | Unique identifier for the student               |
| `status`      | string   | `active`, `inactive`, or `tobedeleted`          |
| `username`    | string   | Login username                                  |
| `enabledUser` | string   | `"true"` or `"false"` (as strings)              |
| `givenName`   | string   | Student's first name                            |
| `familyName`  | string   | Student's last name                             |
| `primaryOrg`  | object   | Reference to the student's primary organization |
| `grades`      | string[] | Array of grade levels (e.g., `["5", "6"]`)      |

### Step 3: Create or Update a User

For non-student users (teachers, parents, administrators), use the `upsertUser` endpoint:

```
PUT https://platform.timeback.com/rostering/1.0/users/{sourcedId}
```

**Example request:**

```typescript
const userData = {
  user: {
    sourcedId: 'user-uuid-here',
    status: 'active',
    enabledUser: 'true',
    givenName: 'Jane',
    familyName: 'Smith',
    email: 'jane.smith@example.com',
    grades: [],
    primaryOrg: {
      sourcedId: 'organization-uuid',
      type: 'org',
    },
    roles: [
      {
        roleType: 'primary',
        role: 'parent',
        org: {
          sourcedId: 'organization-uuid',
          type: 'org',
        },
      },
    ],
  },
};

const response = await fetch(`https://platform.timeback.com/rostering/1.0/users/${userData.user.sourcedId}`, {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${accessToken}`,
  },
  body: JSON.stringify(userData),
});

// Returns 201 Created on success
```

**Available roles:**

- `student`, `teacher`, `parent`, `guardian`, `relative`
- `aide`, `counselor`, `principal`, `proctor`
- `districtAdministrator`, `siteAdministrator`, `systemAdministrator`

### Step 4: Link a Student to an Agent

Create relationships between students and their agents (parents, guardians):

```
PUT https://platform.timeback.com/rostering/1.0/students/{sourcedId}/agents/{agentId}
```

**Example request:**

```typescript
const agentData = {
  user: {
    sourcedId: 'parent-user-uuid', // The agent's user ID
    type: 'user',
  },
  relationshipType: 'parent', // free-form string describing the relationship
};

const response = await fetch(
  `https://platform.timeback.com/rostering/1.0/students/${studentId}/agents/${agentRelationshipId}`,
  {
    method: 'PUT',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${accessToken}`,
    },
    body: JSON.stringify(agentData),
  },
);

// Returns 201 Created on success
```

**Relationship type:**

The `relationshipType` is a free-form string. Use any value that describes the relationship in your system.

### Step 5: Query User Agents

Retrieve all agents associated with a user:

```
GET https://platform.timeback.com/rostering/1.0/users/{sourcedId}/agents
```

**Example request:**

```typescript
const response = await fetch(`https://platform.timeback.com/rostering/1.0/users/${userId}/agents`, {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${accessToken}`,
  },
});

const data = await response.json();
// Returns: { agents: [{ user: { sourcedId, type }, relationshipType }] }
```

### Step 6: Remove an Agent Relationship

Delete an agent relationship when it's no longer valid:

```
DELETE https://platform.timeback.com/rostering/1.0/students/{sourcedId}/agents/{agentId}
```

**Example request:**

```typescript
const response = await fetch(
  `https://platform.timeback.com/rostering/1.0/students/${studentId}/agents/${agentRelationshipId}`,
  {
    method: 'DELETE',
    headers: {
      Authorization: `Bearer ${accessToken}`,
    },
  },
);

// Returns 204 No Content on success
```

## Required Scopes

| Operation            | Required Scope                                                   |
| -------------------- | ---------------------------------------------------------------- |
| `upsertStudent`      | `https://purl.imsglobal.org/spec/or/v1p2/scope/roster.createput` |
| `upsertUser`         | `https://purl.imsglobal.org/spec/or/v1p2/scope/roster.createput` |
| `upsertStudentAgent` | `https://purl.imsglobal.org/spec/or/v1p2/scope/roster.createput` |
| `deleteStudentAgent` | `https://purl.imsglobal.org/spec/or/v1p2/scope/roster.createput` |
| `getUserAgents`      | `https://purl.imsglobal.org/spec/or/v1p2/scope/roster.readonly`  |

## Common Pitfalls

### Not matching sourcedId in path and body

```typescript
// ❌ Bad: Path and body sourcedId don't match
await fetch('/rostering/1.0/users/user-123', {
  body: JSON.stringify({ user: { sourcedId: 'user-456', ... } }),
});

// ✅ Good: Path and body sourcedId match
await fetch('/rostering/1.0/users/user-123', {
  body: JSON.stringify({ user: { sourcedId: 'user-123', ... } }),
});
```

### Using boolean instead of string for enabledUser

```typescript
// ❌ Bad: Boolean value
{
  enabledUser: true;
}

// ✅ Good: String value
{
  enabledUser: 'true';
}
```

### Missing required organization reference

```typescript
// ❌ Bad: Missing primaryOrg
{ student: { sourcedId: '...', givenName: 'John', ... } }

// ✅ Good: Include primaryOrg
{
  student: {
    sourcedId: '...',
    givenName: 'John',
    primaryOrg: { sourcedId: 'org-uuid', type: 'org' },
    ...
  }
}
```

---

## Related Docs

### [Level 0: Registration](https://docs.platform.timeback.com/public-level-0-registration.txt)

Register your app first to get OAuth credentials for API access.

### [Level 2: LTI Launch](https://docs.platform.timeback.com/public-level-2-lti-launch.txt)

Implement seamless authentication so students can access your app without credentials.

### [Level 3: Caliper Events](https://docs.platform.timeback.com/public-level-3-caliper.txt)

Send learning activity events to unlock coaching insights and unified analytics.

### [Authentication](https://docs.platform.timeback.com/public-authentication.txt)

Detailed guide on obtaining and managing OAuth access tokens.


### Level 2: LTI Launch

# Level 2: LTI Launch

Implement seamless student authentication using LTI 1.3 so students can launch your app without login screens or credentials.

## What LTI Provides

LTI 1.3 (Learning Tools Interoperability) is a [1EdTech standard](https://www.imsglobal.org/spec/lti/v1p3) that enables TimeBack to authenticate students into your app automatically. When a student clicks your app in TimeBack's catalog, they're signed in and redirected to your app's landing page—no username, no password, no friction.

## How LTI Launch Works

The launch flow:

1. Student clicks your app in TimeBack App
2. TimeBack generates a signed OIDC ID token containing verified student identity
3. TimeBack POSTs the token to your LTI launch endpoint (form submission from frontend)
4. Your endpoint verifies the token signature using TimeBack's public keys
5. Your endpoint provisions a user account if this is the student's first launch
6. Your endpoint authenticates the student (set cookies, session, JWT, etc.)
7. Your endpoint redirects (302) to your app's landing page
8. Student lands in your app, fully authenticated

The ID token is a signed JWT. By verifying its signature against TimeBack's public keys (JWKS), you confirm the request is authentic and the student identity is verified.

## Implementation Guide

### Step 1: Create the LTI Launch Endpoint

Your endpoint receives a form-urlencoded POST request with an `id_token` field.

**Endpoint requirements:**

- Accepts `POST` requests
- Accepts `application/x-www-form-urlencoded` content type
- Extracts `id_token` from form body
- Returns `302 Redirect` response

**Example endpoint (Express):**

```typescript
app.post('/lti/1.3/launch', async (req, res) => {
  const { id_token } = req.body;

  // Verify token, provision user, authenticate
  const redirectUrl = await handleLtiLaunch(id_token);

  res.redirect(302, redirectUrl);
});
```

### Step 2: Verify the ID Token

Use TimeBack's public keys to verify the token signature:

```typescript
import { createRemoteJWKSet, jwtVerify } from 'jose';

async function verifyLtiToken(idToken: string) {
  const JWKS = createRemoteJWKSet(new URL('https://platform.timeback.com/.well-known/jwks.json'));

  const verified = await jwtVerify(idToken, JWKS, {
    issuer: 'https://timeback.com',
    audience: 'your-app-audience', // Provided during registration
  });

  return verified.payload;
}
```

**Token validation:**

- Verify signature using JWKS
- Verify `iss` (issuer) matches TimeBack
- Verify `aud` (audience) matches your app's audience identifier
- Verify `exp` (expiration) is in the future

### Step 3: Extract User Identity

The verified token payload contains student information:

```typescript
interface LtiTokenPayload {
  // Standard OIDC claims
  sub: string; // Platform user ID
  email: string;
  name: string;
  given_name: string;
  family_name: string;

  // LTI 1.3 claims
  'https://purl.imsglobal.org/spec/lti/claim/message_type': 'LtiResourceLinkRequest';
  'https://purl.imsglobal.org/spec/lti/claim/version': '1.3.0';
  'https://purl.imsglobal.org/spec/lti/claim/target_link_uri': string;

  // TimeBack-specific claims
  'https://timeback.com/lti/claim/application_id': string;
  'https://timeback.com/lti/claim/tool_id': string;
}

function extractUserIdentity(payload: LtiTokenPayload) {
  return {
    platformId: payload.sub,
    email: payload.email,
    fullName: payload.name || `${payload.given_name} ${payload.family_name}`,
  };
}
```

**Critical: Store the `sub` field**

Even if you're only implementing Level 2 now, you should store the `sub` value in your database alongside the user record. This is the student's TimeBack platform ID.

Why this matters:

- If you later implement Level 3 (Caliper events), you'll use `sub` as the `actor` field in all events
- This links student activity in your app to their TimeBack profile
- Without it, you cannot send Caliper events—there's no other way to identify which TimeBack user your events refer to
- The `sub` value remains constant across all sessions and never changes

### Step 4: Provision User Account

Check if a user account exists for this email. If not, create one:

```typescript
async function ensureUser(email: string, fullName: string, platformId: string) {
  let user = await database.findUserByEmail(email);

  if (!user) {
    user = await database.createUser({
      email,
      fullName,
      platformId,
    });
  }

  return user;
}
```

### Step 5: Authenticate and Redirect

Set your app's authentication mechanism (cookies, session, JWT, etc.) and redirect to the landing page:

```typescript
async function handleLtiLaunch(idToken: string): Promise<string> {
  // 1. Verify token
  const payload = await verifyLtiToken(idToken);

  // 2. Extract identity
  const { email, fullName, platformId } = extractUserIdentity(payload);

  // 3. Provision user
  const user = await ensureUser(email, fullName, platformId);

  // 4. Authenticate (example: set session cookie)
  const sessionToken = await createSessionToken(user.id);
  setAuthCookie(sessionToken);

  // 5. Redirect to landing page
  const targetUrl = payload['https://purl.imsglobal.org/spec/lti/claim/target_link_uri'];
  return targetUrl || 'https://yourapp.com/';
}
```

**Authentication options:**

- Set session cookies (most common for web apps)
- Generate your own JWT and set as cookie
- Create magic link token and redirect with query param
- Use your existing authentication mechanism

The key requirement: students must be authenticated when they land on your app.

## Updating Your Registration

Once your LTI endpoint is implemented, reply to your original registration email with these fields:

| Field              | Description                                               | Example                                  |
| ------------------ | --------------------------------------------------------- | ---------------------------------------- |
| **LTI Launch URL** | POST endpoint that receives LTI authentication requests   | `https://api.yourapp.com/lti/1.3/launch` |
| **LTI Audience**   | Unique identifier for your app (used in token validation) | `yourapp`                                |
| **Landing URL**    | Where students are redirected after authentication        | `https://yourapp.com/`                   |

**LTI Audience:** This is an arbitrary string you choose. We include it as the `aud` claim in the ID token. Your endpoint verifies that `aud` matches this value, ensuring the token is intended for your app.

## Common Pitfalls

### Not verifying token signature

```typescript
// ❌ Bad: Decode without verification
const payload = JSON.parse(Buffer.from(idToken.split('.')[1], 'base64').toString());
// Anyone can forge this token

// ✅ Good: Verify signature with JWKS
const { payload } = await jwtVerify(idToken, JWKS, { issuer, audience });
```

### Wrong content type for endpoint

```typescript
// ❌ Bad: Expecting JSON
app.post('/lti/launch', express.json(), handler);

// ✅ Good: Form-urlencoded
app.post('/lti/launch', express.urlencoded({ extended: true }), handler);
```

---

## Related Docs

### [Level 0: Registration](https://docs.platform.timeback.com/public-level-0-registration.txt)

Register your app first before implementing LTI. You'll need your app registered to receive the audience identifier.

### [Level 1: Student Onboarding](https://docs.platform.timeback.com/public-level-1-student-onboarding.txt)

Programmatically create and manage students in TimeBack's roster before they launch your app.

### [Level 3: Caliper Events](https://docs.platform.timeback.com/public-level-3-caliper.txt)

After implementing LTI, send learning activity events to unlock coaching insights and unified analytics.


### Level 3: Caliper Events

# Level 3: Caliper Events

Send structured learning activity events to unlock coaching insights and unified analytics across TimeBack's ecosystem.

## What Caliper Provides

[Caliper Analytics](https://www.imsglobal.org/spec/caliper/v1p2) is a 1EdTech standard that defines a structured vocabulary for learning events. By sending Caliper events to TimeBack, you enable:

- Richer coaching insights based on student behavior patterns
- Unified progress tracking across multiple learning apps
- Cross-app intelligence (detecting patterns like assessment avoidance, topic shopping)
- Detailed analytics for educators and administrators

Without Caliper events, TimeBack can only track session time and screen activity. With Caliper, TimeBack understands what students are actually doing—which questions they answer, what they master, when they skip content.

## Prerequisites

Before implementing Caliper:

1. **Obtain student platform IDs**—you'll use these as the `actor` in all events:
   - **Option 1 (Recommended):** Implement Level 2 (LTI) and store the `sub` field from LTI tokens
   - **Option 2 (Without LTI):** Look up platform IDs by email using the roster API (see [Alternative: Roster Lookup](#alternative-roster-lookup) below)
2. **Request OAuth credentials** with the `events.write` scope (see [Authentication Guide](https://docs.platform.timeback.com/public-authentication.txt))

## Progressive Implementation

Implement Caliper events in phases to balance integration effort with analytics value:

**Phase 1: Core Question Events** (highest value)

1. Questions Started (when question displays)
2. Questions Answered (when student submits)
3. Questions Graded (when feedback provided)

These three events power the most valuable coaching insights—accuracy tracking, struggling topic detection, skip pattern analysis.

**Phase 2: Progress Tracking** 4. XP Awarded (when student earns experience points) 5. Mastery Achieved (when student completes curriculum objectives)

These enable unified progress dashboards and cross-app analytics.

**Phase 3: Additional Context** (optional) 6. Curriculum content events (AssignableEvent, ViewEvent) 7. Assessment grouping events (AssessmentEvent)

These provide richer context but aren't required for core coaching functionality.

Start with Phase 1. Add Phase 2 when ready for progress reporting. Phase 3 is optional—add only if your app has explicit lessons or assessments that benefit from structured tracking.

## Event Types Overview

TimeBack uses four primary event types:

| Event Type             | When to Send                                   | What It Powers                                                        |
| ---------------------- | ---------------------------------------------- | --------------------------------------------------------------------- |
| **Questions Started**  | When a question is displayed to the student    | Detects question skip patterns, measures question engagement time     |
| **Questions Answered** | When a student submits an answer               | Tracks accuracy, identifies struggling topics, detects rapid guessing |
| **XP Awarded**         | When a student earns experience points         | Progress tracking, engagement metrics, cross-app XP leaderboards      |
| **Mastery Achieved**   | When a student completes curriculum objectives | Completion tracking, mastery dashboards, prerequisite unlocking       |

Start with questions and answers—these power the most valuable coaching insights. Add XP and mastery when ready.

For complete event schemas and field documentation, see [Caliper Events Reference](https://docs.platform.timeback.com/public-caliper-events-reference.txt).

## How to Send Events

All Caliper events go to a single endpoint:

```
POST https://platform.timeback.com/events/1.0/
```

Include your OAuth access token (see [Authentication Guide](https://docs.platform.timeback.com/public-authentication.txt)):

```typescript
await fetch('https://platform.timeback.com/events/1.0/', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${accessToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(event),
});
```

Send events as bare JSON—one event per POST request:

```json
{
  "@context": "http://purl.imsglobal.org/ctx/caliper/v1p2",
  "id": "urn:uuid:event-unique-id",
  "type": "AssessmentItemEvent",
  "actor": "urn:uuid:student-platform-id",
  "action": "Started",
  "object": {
    "id": "urn:uuid:question-id",
    "type": "AssessmentItem",
    "name": "7 × 8 = ?"
  },
  "eventTime": "2025-12-15T10:30:00.000Z",
  "edApp": "urn:uuid:your-app-id",
  "session": "urn:tag:auto-attach"
}
```

**Required fields** (see [Caliper Events Reference](https://docs.platform.timeback.com/public-caliper-events-reference.txt) for complete documentation):

- `@context`: Always `http://purl.imsglobal.org/ctx/caliper/v1p2`
- `id`: Unique UUID for this event
- `type`: Event type (e.g., `AssessmentItemEvent`, `GradeEvent`)
- `actor`: Student's platform ID (the `sub` from LTI token, formatted as `urn:uuid:{sub}`)
- `action`: What happened (e.g., `Started`, `Completed`, `Graded`)
- `object`: What the action was performed on
- `eventTime`: ISO 8601 timestamp when event occurred
- `edApp`: Your app's identifier
- `session`: Use `urn:tag:auto-attach` for automatic session attribution

## Sending Pattern

Send events as they happen in real-time. For production reliability, use a queue (Redis, SQS, RabbitMQ) to decouple event sending from user-facing operations and guarantee delivery.

## Implementation

Request the Caliper scope when registering or email the TimeBack team:

```
scope: https://purl.imsglobal.org/spec/caliper/v1p2/scope/events.write
```

Fire events when student actions occur:

```typescript
// When question appears
await fetch('https://platform.timeback.com/events/1.0/', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${accessToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    '@context': 'http://purl.imsglobal.org/ctx/caliper/v1p2',
    id: `urn:uuid:${crypto.randomUUID()}`,
    type: 'AssessmentItemEvent',
    actor: `urn:uuid:${user.platformId}`, // From LTI 'sub'
    action: 'Started',
    object: {
      id: `urn:uuid:${question.id}`,
      type: 'AssessmentItem',
      name: question.text,
    },
    eventTime: new Date().toISOString(),
    edApp: 'urn:uuid:yourapp',
    session: 'urn:tag:auto-attach',
  }),
});
```

Success responses return `200 OK` with empty body.

## Alternative: Roster Lookup

If your app accepts students launching outside TimeBack App (direct browser access), you won't have LTI tokens to get platform IDs. You can look up platform IDs by email using the roster API.

**Use case:** Students who access your app directly (not launched from TimeBack App) but you still want to send their learning events to TimeBack.

### Request Roster Scope

Request the roster read scope along with events write scope:

```
scope: https://purl.imsglobal.org/spec/or/v1p2/scope/roster.readonly
scope: https://purl.imsglobal.org/spec/caliper/v1p2/scope/events.write
```

### Look Up Platform ID by Email

```typescript
async function getPlatformId(email: string, accessToken: string): Promise<string | null> {
  const filter = encodeURIComponent(`email='${email}'`);
  const url = `https://platform.timeback.com/rostering/1.0/users?filter=${filter}`;

  const response = await fetch(url, {
    method: 'GET',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${accessToken}`,
    },
  });

  if (!response.ok) {
    return null;
  }

  const data = await response.json();

  if (data.users.length === 0) {
    return null; // User not in TimeBack system
  }

  return data.users[0].sourcedId; // This is the platform ID
}
```

**Important:** Only students who exist in TimeBack's roster will have platform IDs. If lookup returns null, the student isn't in TimeBack's system—don't send Caliper events for them.

## Common Pitfalls

### Not using platform ID as actor

```typescript
// ❌ Bad: Using your internal user ID
actor: `urn:uuid:${user.id}`;

// ✅ Good: Using TimeBack platform ID
actor: `urn:uuid:${user.platformId}`; // From LTI 'sub' or roster lookup
```

### Sending events without authentication

```typescript
// ❌ Bad: No auth token
await fetch(url, { body: JSON.stringify(event) });

// ✅ Good: Include OAuth token
await fetch(url, {
  headers: { Authorization: `Bearer ${accessToken}` },
  body: JSON.stringify(event),
});
```

---

## Related Docs

### [Caliper Events Reference](https://docs.platform.timeback.com/public-caliper-events-reference.txt)

Complete event schemas, field requirements, and examples for all supported event types.

### [Authentication](https://docs.platform.timeback.com/public-authentication.txt)

Obtain OAuth client credentials and access tokens required for sending Caliper events.

### [Level 1: Student Onboarding](https://docs.platform.timeback.com/public-level-1-student-onboarding.txt)

Programmatically create and manage students in TimeBack's roster.

### [Level 2: LTI Launch](https://docs.platform.timeback.com/public-level-2-lti-launch.txt)

Implement LTI first to get student platform IDs, which you'll use as the `actor` in all Caliper events.


## Event Reference

### Caliper Events

# Caliper Events Reference

Complete event schemas, field requirements, and examples for all Caliper events supported by TimeBack Platform.

## Overview

This document provides sample payloads for different types of Caliper events, along with clear guidance on when and how to use each event type.

## Curriculum Content Interaction

### Structured Curriculum Content

When students interact with structured curriculum content (lessons, units, courses, subjects, etc.), learning applications should fire **AssignableEvent** with **Started** and **Completed** actions.

[AssignableEvent Schema](https://www.imsglobal.org/spec/caliper/v1p2#assignableevent)

**Key Requirements:**

- Use **AssignableEvent** with **Started** action when the student begins interaction
- Use **AssignableEvent** with **Completed** action when the student completes the curriculum material
- Started event's **Attempt** should include **startedAtTime**
- Completed event's **Attempt** should include **endedAtTime**

**Key Attributes:**

| Field     | Description                                                                                                                                                         |
| :-------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| actor     | Student's platform ID (from LTI token's `sub`), formatted as `urn:uuid:{platformId}`                                                                                |
| object    | An [AssignableDigitalResource](https://www.imsglobal.org/spec/caliper/v1p2#assignabledigitalresource) with `mediaType: "curriculum/lesson"`                         |
| generated | The [Attempt](https://www.imsglobal.org/spec/caliper/v1p2#attempt) of the student on the lesson. `assignable` should match the lesson. Must include `startedAtTime` |
| edApp     | Your app's identifier, formatted as `urn:uuid:{yourAppId}`                                                                                                          |
| session   | Use `urn:tag:auto-attach` for automatic session attribution                                                                                                         |

**AssignableEvent.Started**

```json
{
  "@context": "http://purl.imsglobal.org/ctx/caliper/v1p2",
  "id": "urn:uuid:event-unique-id",
  "type": "AssignableEvent",
  "actor": "urn:uuid:student-platform-id",
  "action": "Started",
  "object": {
    "id": "https://learningapp.com/lessons/fractions-intro",
    "type": "AssignableDigitalResource",
    "mediaType": "curriculum/lesson",
    "name": "Introduction to Fractions",
    "isPartOf": {
      "id": "https://learningapp.com/units/number-operations",
      "type": "AssignableDigitalResource",
      "mediaType": "curriculum/unit",
      "name": "Basic Number Operations"
    }
  },
  "generated": {
    "id": "urn:uuid:lesson-attempt-id",
    "type": "Attempt",
    "assignee": "urn:uuid:student-platform-id",
    "assignable": "https://learningapp.com/lessons/fractions-intro",
    "startedAtTime": "2024-01-15T09:30:00.000Z"
  },
  "eventTime": "2024-01-15T09:30:00.000Z",
  "edApp": "urn:uuid:your-app-id",
  "session": "urn:tag:auto-attach"
}
```

**AssignableEvent.Completed**

```json
{
  "@context": "http://purl.imsglobal.org/ctx/caliper/v1p2",
  "id": "urn:uuid:event-unique-id",
  "type": "AssignableEvent",
  "actor": "urn:uuid:student-platform-id",
  "action": "Completed",
  "object": "https://learningapp.com/lessons/fractions-intro",
  "generated": {
    "id": "urn:uuid:lesson-attempt-id",
    "type": "Attempt",
    "assignee": "urn:uuid:student-platform-id",
    "assignable": "https://learningapp.com/lessons/fractions-intro",
    "startedAtTime": "2024-01-15T09:30:00.000Z",
    "endedAtTime": "2024-01-15T10:15:00.000Z"
  },
  "eventTime": "2024-01-15T10:15:00.000Z",
  "edApp": "urn:uuid:your-app-id",
  "session": "urn:tag:auto-attach"
}
```

### Learning Resources

When students consume educational content such as textual materials (articles, documents, etc.) or videos, learning applications should fire **ViewEvent** with **Viewed** action.

[ViewEvent Schema](https://www.imsglobal.org/spec/caliper/v1p2#viewevent)

**Key Requirements:**

- Use **ViewEvent** with **Viewed** action when a student views learning resources
- The event includes a generated **Attempt** with timing information

**Key Attributes:**

| Field   | Description                                                 |
| :------ | :---------------------------------------------------------- |
| actor   | Student's platform ID, formatted as `urn:uuid:{platformId}` |
| edApp   | Your app's identifier, formatted as `urn:uuid:{yourAppId}`  |
| session | Use `urn:tag:auto-attach` for automatic session attribution |

**ViewEvent.Viewed**

```json
{
  "@context": "http://purl.imsglobal.org/ctx/caliper/v1p2",
  "id": "urn:uuid:event-unique-id",
  "type": "ViewEvent",
  "actor": "urn:uuid:student-platform-id",
  "action": "Viewed",
  "object": {
    "id": "https://learningapp.com/articles/algebra-introduction",
    "type": "DigitalResource",
    "name": "Introduction to Algebra",
    "mediaType": "text/html",
    "isPartOf": {
      "id": "https://learningapp.com/lessons/fractions-intro",
      "type": "AssignableDigitalResource",
      "mediaType": "curriculum/lesson",
      "name": "Introduction to Fractions"
    }
  },
  "generated": {
    "id": "urn:uuid:resource-attempt-id",
    "type": "Attempt",
    "assignee": "urn:uuid:student-platform-id",
    "assignable": "https://learningapp.com/articles/algebra-introduction",
    "startedAtTime": "2024-01-15T11:00:00.000Z",
    "endedAtTime": "2024-01-15T11:15:00.000Z"
  },
  "eventTime": "2024-01-15T11:15:00.000Z",
  "edApp": "urn:uuid:your-app-id",
  "session": "urn:tag:auto-attach"
}
```

## Assessment Interaction and Results

### Assessments

When students start and submit assessments, learning applications should fire **AssessmentEvent** with **Started** and **Submitted** actions.

[AssessmentEvent Schema](https://www.imsglobal.org/spec/caliper/v1p2#assessmentevent)

**Key Requirements:**

- Use **AssessmentEvent** with **Started** action when student begins assessment
- Use **AssessmentEvent** with **Submitted** action when student submits assessment
- Started event's **Attempt** should include **startedAtTime**
- Submitted event's **Attempt** should include **endedAtTime**

**Key Attributes:**

| Field   | Description                                                 |
| :------ | :---------------------------------------------------------- |
| actor   | Student's platform ID, formatted as `urn:uuid:{platformId}` |
| edApp   | Your app's identifier, formatted as `urn:uuid:{yourAppId}`  |
| session | Use `urn:tag:auto-attach` for automatic session attribution |

**AssessmentEvent.Started**

```json
{
  "@context": "http://purl.imsglobal.org/ctx/caliper/v1p2",
  "id": "urn:uuid:event-unique-id",
  "type": "AssessmentEvent",
  "actor": "urn:uuid:student-platform-id",
  "action": "Started",
  "object": {
    "id": "https://learningapp.com/assessments/fractions-quiz",
    "type": "Assessment",
    "name": "Fractions Quiz",
    "isPartOf": {
      "id": "https://learningapp.com/lessons/fractions-intro",
      "type": "AssignableDigitalResource",
      "mediaType": "curriculum/lesson",
      "name": "Introduction to Fractions"
    }
  },
  "generated": {
    "id": "urn:uuid:assessment-attempt-id",
    "type": "Attempt",
    "assignee": "urn:uuid:student-platform-id",
    "assignable": "https://learningapp.com/assessments/fractions-quiz",
    "startedAtTime": "2024-01-15T10:00:00.000Z"
  },
  "eventTime": "2024-01-15T10:00:00.000Z",
  "edApp": "urn:uuid:your-app-id",
  "session": "urn:tag:auto-attach"
}
```

**AssessmentEvent.Submitted**

```json
{
  "@context": "http://purl.imsglobal.org/ctx/caliper/v1p2",
  "id": "urn:uuid:event-unique-id",
  "type": "AssessmentEvent",
  "actor": "urn:uuid:student-platform-id",
  "action": "Submitted",
  "object": "https://learningapp.com/assessments/fractions-quiz",
  "generated": {
    "id": "urn:uuid:assessment-attempt-id",
    "type": "Attempt",
    "assignee": "urn:uuid:student-platform-id",
    "assignable": "https://learningapp.com/assessments/fractions-quiz",
    "startedAtTime": "2024-01-15T10:00:00.000Z",
    "endedAtTime": "2024-01-15T10:25:00.000Z"
  },
  "eventTime": "2024-01-15T10:25:00.000Z",
  "edApp": "urn:uuid:your-app-id",
  "session": "urn:tag:auto-attach"
}
```

### Questions

When students interact with individual questions within assessments, learning applications should fire **AssessmentItemEvent** with **Started** and **Completed** actions.

[AssessmentItemEvent Schema](https://www.imsglobal.org/spec/caliper/v1p2#assessmentitemevent)

**Key Requirements:**

- Use **AssessmentItemEvent** with **Started** action when the question is shown
- Use **AssessmentItemEvent** with **Completed** action when student answers question
- **Started** event does not include generated field
- **Completed** event includes **Response** with embedded **Attempt** containing timing information

**Key Attributes:**

| Field   | Description                                                 |
| :------ | :---------------------------------------------------------- |
| actor   | Student's platform ID, formatted as `urn:uuid:{platformId}` |
| edApp   | Your app's identifier, formatted as `urn:uuid:{yourAppId}`  |
| session | Use `urn:tag:auto-attach` for automatic session attribution |

**AssessmentItemEvent.Started**

```json
{
  "@context": "http://purl.imsglobal.org/ctx/caliper/v1p2",
  "id": "urn:uuid:event-unique-id",
  "type": "AssessmentItemEvent",
  "actor": "urn:uuid:student-platform-id",
  "action": "Started",
  "object": {
    "id": "https://learningapp.com/questions/fraction-addition-q1",
    "type": "AssessmentItem",
    "name": "Fraction Addition Question 1",
    "isPartOf": {
      "id": "https://learningapp.com/assessments/fractions-quiz",
      "type": "Assessment",
      "name": "Fractions Quiz"
    }
  },
  "eventTime": "2024-01-15T10:05:00.000Z",
  "edApp": "urn:uuid:your-app-id",
  "session": "urn:tag:auto-attach"
}
```

**AssessmentItemEvent.Completed**

```json
{
  "@context": "http://purl.imsglobal.org/ctx/caliper/v1p2",
  "id": "urn:uuid:event-unique-id",
  "type": "AssessmentItemEvent",
  "actor": "urn:uuid:student-platform-id",
  "action": "Completed",
  "object": "https://learningapp.com/questions/fraction-addition-q1",
  "generated": {
    "id": "urn:uuid:response-id",
    "type": "Response",
    "attempt": {
      "id": "urn:uuid:question-attempt-id",
      "type": "Attempt",
      "assignee": "urn:uuid:student-platform-id",
      "assignable": "https://learningapp.com/questions/fraction-addition-q1",
      "startedAtTime": "2024-01-15T10:05:00.000Z",
      "endedAtTime": "2024-01-15T10:07:00.000Z"
    }
  },
  "eventTime": "2024-01-15T10:07:00.000Z",
  "edApp": "urn:uuid:your-app-id",
  "session": "urn:tag:auto-attach"
}
```

### Grading

When the answered question is graded, learning applications should fire **GradeEvent** with **Graded** action.

[GradeEvent Schema](https://www.imsglobal.org/spec/caliper/v1p2#gradeevent)

**Key Requirements:**

- Use **GradeEvent** with **Graded** action when question is graded
- Event includes **Score** with **scoreType** extension linking to the **Attempt**

**Key Attributes:**

| Field     | Description                                                                                                                                                                                                   |
| :-------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| actor     | Student's platform ID, formatted as `urn:uuid:{platformId}`                                                                                                                                                   |
| edApp     | Your app's identifier, formatted as `urn:uuid:{yourAppId}`                                                                                                                                                    |
| generated | A [Score](https://www.imsglobal.org/spec/caliper/v1p2#Score) object. `maxScore` should always be `1`. `scoreGiven` should be `0` for incorrect answer, `1` for correct. `scoreType` must be `QUESTION_RESULT` |
| session   | Use `urn:tag:auto-attach` for automatic session attribution                                                                                                                                                   |

**GradeEvent.Graded**

```json
{
  "@context": "http://purl.imsglobal.org/ctx/caliper/v1p2",
  "id": "urn:uuid:event-unique-id",
  "type": "GradeEvent",
  "actor": "urn:uuid:student-platform-id",
  "action": "Graded",
  "object": "urn:uuid:question-attempt-id",
  "generated": {
    "id": "urn:uuid:score-id",
    "type": "Score",
    "scoreType": "QUESTION_RESULT",
    "attempt": "urn:uuid:question-attempt-id",
    "maxScore": 1,
    "scoreGiven": 1
  },
  "eventTime": "2024-01-15T10:07:30.000Z",
  "edApp": "urn:uuid:your-app-id",
  "session": "urn:tag:auto-attach"
}
```

## Performance Reporting

When learning applications need to report student progress such as curriculum mastery, they should fire **GradeEvent** with **Graded** action. These events use the **Score** entity with different **scoreType** values to differentiate between mastery achievements and XP awards.

### Mastery

When students achieve mastery of curriculum standards or learning objectives, learning applications should fire **GradeEvent** with **Graded** action.

[GradeEvent Schema](https://www.imsglobal.org/spec/caliper/v1p2#gradeevent)

**Key Requirements:**

- Use **GradeEvent** with **Graded** action when reporting curriculum mastery
- **Score** entity must include **scoreType: MASTERY**

**Key Attributes:**

| Field     | Description                                                                                                                              |
| :-------- | :--------------------------------------------------------------------------------------------------------------------------------------- |
| actor     | Student's platform ID, formatted as `urn:uuid:{platformId}`                                                                              |
| edApp     | Your app's identifier, formatted as `urn:uuid:{yourAppId}`                                                                               |
| generated | A [Score](https://www.imsglobal.org/spec/caliper/v1p2#Score) object with `scoreType: "MASTERY"`                                          |
| object    | An [Attempt](https://www.imsglobal.org/spec/caliper/v1p2#attempt) object. Include `assignable` chain to indicate the curriculum mastered |
| session   | Use `urn:tag:auto-attach` for automatic session attribution                                                                              |

**GradeEvent.Graded (Mastery)**

```json
{
  "@context": "http://purl.imsglobal.org/ctx/caliper/v1p2",
  "id": "urn:uuid:event-unique-id",
  "type": "GradeEvent",
  "actor": "urn:uuid:student-platform-id",
  "action": "Graded",
  "object": {
    "id": "urn:uuid:mastery-attempt-id",
    "type": "Attempt",
    "assignee": "https://learningapp.com/users/student-456",
    "assignable": {
      "id": "https://learningapp.com/standards/fractions-basics",
      "type": "AssignableDigitalResource",
      "mediaType": "curriculum/standard",
      "name": "Basic Fractions Understanding",
      "isPartOf": {
        "id": "https://learningapp.com/clusters/number-operations",
        "type": "AssignableDigitalResource",
        "mediaType": "curriculum/cluster",
        "name": "Number Operations",
        "isPartOf": {
          "id": "https://learningapp.com/domains/numbers-operations",
          "type": "AssignableDigitalResource",
          "mediaType": "curriculum/domain",
          "name": "Numbers and Operations",
          "isPartOf": {
            "id": "https://learningapp.com/courses/mathematics-grade-4",
            "type": "AssignableDigitalResource",
            "mediaType": "curriculum/course",
            "name": "Mathematics Grade 4"
          }
        }
      }
    }
  },
  "generated": {
    "id": "urn:uuid:score-id",
    "type": "Score",
    "scoreType": "MASTERY",
    "attempt": "urn:uuid:mastery-attempt-id",
    "maxScore": 100,
    "scoreGiven": 100
  },
  "eventTime": "2024-01-15T14:30:00.000Z",
  "edApp": "urn:uuid:your-app-id",
  "session": "urn:tag:auto-attach"
}
```

### XP

When students are awarded XP, learning applications should fire **GradeEvent** with **Graded** action to report the awarded XP.

[GradeEvent Schema](https://www.imsglobal.org/spec/caliper/v1p2#gradeevent)

**Key Requirements:**

- Use **GradeEvent** with **Graded** action when reporting XP
- **Object** should reference the XP's **Attempt** entity
- **XP** can be optionally linked to a learning resource through the **Attempt** object's **assignable** field

**Key Attributes:**

| Field     | Description                                                                                                                                  |
| :-------- | :------------------------------------------------------------------------------------------------------------------------------------------- |
| actor     | Student's platform ID, formatted as `urn:uuid:{platformId}`                                                                                  |
| edApp     | Your app's identifier, formatted as `urn:uuid:{yourAppId}`                                                                                   |
| generated | A [Score](https://www.imsglobal.org/spec/caliper/v1p2#Score) object with `scoreType: "XP"`                                                   |
| object    | An [Attempt](https://www.imsglobal.org/spec/caliper/v1p2#attempt) object. Can optionally include `assignable` chain for the related resource |
| session   | Use `urn:tag:auto-attach` for automatic session attribution                                                                                  |

**GradeEvent.Graded (XP)**

```json
{
  "@context": "http://purl.imsglobal.org/ctx/caliper/v1p2",
  "id": "urn:uuid:event-unique-id",
  "type": "GradeEvent",
  "actor": "urn:uuid:student-platform-id",
  "action": "Graded",
  "object": {
    "id": "urn:uuid:xp-attempt-id",
    "type": "Attempt",
    "assignee": "urn:uuid:student-platform-id",
    "assignable": {
      "id": "https://learningapp.com/standards/fractions-basics",
      "type": "AssignableDigitalResource",
      "mediaType": "curriculum/lesson",
      "name": "Introduction to Fractions"
    }
  },
  "generated": {
    "id": "urn:uuid:score-xp-id",
    "type": "Score",
    "scoreType": "XP",
    "attempt": "urn:uuid:xp-attempt-id",
    "scoreGiven": 150
  },
  "eventTime": "2024-01-15T14:30:00.000Z",
  "edApp": "urn:uuid:your-app-id",
  "session": "urn:tag:auto-attach"
}
```

---

## Related Docs

### [Level 3: Caliper Events](https://docs.platform.timeback.com/public-level-3-caliper.txt)

Quick start guide for implementing Caliper event integration with TimeBack Platform.

### [Authentication](https://docs.platform.timeback.com/public-authentication.txt)

Obtain OAuth client credentials and access tokens required for sending Caliper events.


## API References

### API Reference

# TimeBack Platform - Auth API

- **OpenAPI Version:** `3.1.1`
- **API Version:** `1.0.0`

RESTful API for authentication and authorization

## Servers

- **URL:** `https://platform.dev.timeback.com`
  - **Description:** integration

## Operations

### Request an access token

- **Method:** `POST`
- **Path:** `/auth/1.0/token`
- **Tags:** Auth

Used to request a new token with the grant\_type "client\_credentials"

#### Request Body

##### Content-Type: application/x-www-form-urlencoded

- **`grant_type` (required)**

  `string`, possible values: `"client_credentials"`

- **`scope`**

  `string` — Space-separated list of scopes

**Example:**

```json
{
  "grant_type": "client_credentials",
  "scope": ""
}
```

#### Responses

##### Status: 200 Token response

###### Content-Type: application/json

- **`access_token` (required)**

  `string`

- **`expires_in` (required)**

  `integer` — Token expiration time in seconds

- **`token_type` (required)**

  `string`, possible values: `"bearer"`

- **`scope`**

  `string` — Space-separated list of granted scopes

**Example:**

```json
{
  "access_token": "",
  "token_type": "bearer",
  "expires_in": 1,
  "scope": ""
}
```

##### Status: 401 Unauthorized

### Submit Caliper event

- **Method:** `POST`
- **Path:** `/events/1.0`
- **Tags:** CaliperAnalytics

Endpoint to submit Caliper Analytics events

#### Request Body

##### Content-Type: application/json

**Example:**

```json
{
  "propertyName*": "anything"
}
```

#### Responses

##### Status: 204 Event successfully processed

##### Status: 400 Bad request

###### Content-Type: application/json

- **`imsx_codeMajor` (required)**

  `string`, possible values: `"success", "processing", "failure", "unsupported"`

- **`imsx_severity` (required)**

  `string`, possible values: `"status", "warning", "error"`

- **`imsx_CodeMinor`**

  `object` — Container for code minor status codes

  - **`imsx_codeMinorField` (required)**

    `array`

    **Items:**

    - **`imsx_codeMinorFieldName` (required)**

      `string`, default: `"TargetEndSystem"`

    - **`imsx_codeMinorFieldValue` (required)**

      `string`, possible values: `"fullsuccess", "invalid_filter_field", "invalid_selection_field", "invaliddata", "unauthorisedrequest", "forbidden", "server_busy", "unknownobject", "internal_server_error"`

- **`imsx_description`**

  `string`

**Example:**

```json
{
  "imsx_codeMajor": "success",
  "imsx_severity": "status",
  "imsx_description": "",
  "imsx_CodeMinor": {
    "imsx_codeMinorField": [
      {
        "imsx_codeMinorFieldName": "TargetEndSystem",
        "imsx_codeMinorFieldValue": "fullsuccess"
      }
    ]
  }
}
```

##### Status: 500 Internal server error

###### Content-Type: application/json

- **`imsx_codeMajor` (required)**

  `string`, possible values: `"success", "processing", "failure", "unsupported"`

- **`imsx_severity` (required)**

  `string`, possible values: `"status", "warning", "error"`

- **`imsx_CodeMinor`**

  `object` — Container for code minor status codes

  - **`imsx_codeMinorField` (required)**

    `array`

    **Items:**

    - **`imsx_codeMinorFieldName` (required)**

      `string`, default: `"TargetEndSystem"`

    - **`imsx_codeMinorFieldValue` (required)**

      `string`, possible values: `"fullsuccess", "invalid_filter_field", "invalid_selection_field", "invaliddata", "unauthorisedrequest", "forbidden", "server_busy", "unknownobject", "internal_server_error"`

- **`imsx_description`**

  `string`

**Example:**

```json
{
  "imsx_codeMajor": "success",
  "imsx_severity": "status",
  "imsx_description": "",
  "imsx_CodeMinor": {
    "imsx_codeMinorField": [
      {
        "imsx_codeMinorFieldName": "TargetEndSystem",
        "imsx_codeMinorFieldValue": "fullsuccess"
      }
    ]
  }
}
```

### JSON Web Key Set

- **Method:** `GET`
- **Path:** `/.well-known/jwks.json`
- **Tags:** ApplicationsManagement

Returns the JSON Web Key Set (JWKS) containing public keys for verifying JWT tokens. Follows RFC 7517 and RFC 8414 standards.

#### Responses

##### Status: 200 Successful operation

###### Content-Type: application/json

- **`keys` (required)**

  `array` — Array of JSON Web Keys

  **Items:**

  - **`alg` (required)**

    `string` — Algorithm

  - **`kid` (required)**

    `string` — Key ID

  - **`kty` (required)**

    `string` — Key Type

  - **`e`**

    `string` — RSA Exponent (base64url)

  - **`n`**

    `string` — RSA Modulus (base64url)

  - **`use`**

    `string` — Public Key Use

**Example:**

```json
{
  "keys": [
    {
      "kty": "RSA",
      "use": "sig",
      "kid": "rsa-key-2024",
      "alg": "RS256",
      "n": "",
      "e": "AQAB"
    }
  ]
}
```

##### Status: 500 Internal server error

###### Content-Type: application/json

- **`imsx_codeMajor` (required)**

  `string`, possible values: `"success", "processing", "failure", "unsupported"` — The code major value (from the corresponding enumerated vocabulary).

- **`imsx_severity` (required)**

  `string`, possible values: `"status", "warning", "error"` — The severity value (from the corresponding enumerated vocabulary).

- **`imsx_CodeMinor`**

  `object` — This is the container for the set of code minor status codes reported in the responses from the Service Provider.

  - **`imsx_codeMinorField` (required)**

    `array` — Each reported code minor status code.

    **Items:**

    - **`imsx_codeMinorFieldName` (required)**

      `string`, default: `"TargetEndSystem"` — This should contain the identity of the system that has produced the code minor status code report. In most cases this will be the target service provider denoted as 'TargetEndSystem'.

    - **`imsx_codeMinorFieldValue` (required)**

      `string`, possible values: `"fullsuccess", "invalid_filter_field", "invalid_selection_field", "invaliddata", "unauthorisedrequest", "forbidden", "server_busy", "unknownobject", "internal_server_error"` — The code minor status code (this is a value from the corresponding enumerated vocabulary).

- **`imsx_description`**

  `string` — A human readable description supplied by the entity creating the status code information.

**Example:**

```json
{
  "imsx_codeMajor": "success",
  "imsx_severity": "status",
  "imsx_description": "",
  "imsx_CodeMinor": {
    "imsx_codeMinorField": [
      {
        "imsx_codeMinorFieldName": "TargetEndSystem",
        "imsx_codeMinorFieldValue": "fullsuccess"
      }
    ]
  }
}
```

### Create a new student

- **Method:** `PUT`
- **Path:** `/rostering/1.0/students`
- **Tags:** StudentsManagement

Creates a new student in the system

#### Request Body

##### Content-Type: application/json

- **`student` (required)**

  `object`

  - **`enabledUser` (required)**

    `string`, possible values: `"true", "false"`

  - **`familyName` (required)**

    `string`

  - **`givenName` (required)**

    `string`

  - **`grades` (required)**

    `array`

    **Items:**

    `string`

  - **`primaryOrg` (required)**

    `object`

    - **`sourcedId` (required)**

      `string`

    - **`type` (required)**

      `string`, possible values: `"org"`

    - **`href`**

      `string`

  - **`sourcedId` (required)**

    `string`

  - **`status` (required)**

    `string`, possible values: `"active", "tobedeleted", "inactive"`

  - **`username` (required)**

    `string | null`

  - **`demographics`**

    `object`

    - **`birthDate`**

      `string | null`, format: `date`

  - **`email`**

    `string`

  - **`identifier`**

    `string | null`

  - **`metadata`**

    `object | null`

  - **`middleName`**

    `string | null`

  - **`password`**

    `string | null`

  - **`phone`**

    `string | null`

  - **`preferredFirstName`**

    `string | null`

  - **`preferredLastName`**

    `string | null`

  - **`preferredMiddleName`**

    `string | null`

  - **`pronouns`**

    `string | null`

  - **`sms`**

    `string | null`

  - **`userMasterIdentifier`**

    `string | null`

**Example:**

```json
{
  "student": {
    "sourcedId": "",
    "status": "active",
    "metadata": null,
    "userMasterIdentifier": null,
    "username": null,
    "enabledUser": "true",
    "givenName": "",
    "familyName": "",
    "middleName": null,
    "preferredFirstName": null,
    "preferredMiddleName": null,
    "preferredLastName": null,
    "pronouns": null,
    "demographics": {
      "birthDate": null
    },
    "primaryOrg": {
      "href": "",
      "sourcedId": "",
      "type": "org"
    },
    "identifier": null,
    "email": "",
    "sms": null,
    "phone": null,
    "grades": [
      ""
    ],
    "password": null
  }
}
```

#### Responses

##### Status: 200 Student created successfully

###### Content-Type: application/json

- **`student` (required)**

  `object` — User information in the OneRoster format

  - **`agents` (required)**

    `array` — Array of agents (parents, guardians) associated with the user

    **Items:**

    - **`href` (required)**

      `string`, format: `uri` — URI reference to the entity

    - **`sourcedId` (required)**

      `string` — Unique identifier of the referenced entity

    - **`type` (required)**

      `string`, possible values: `"academicSession", "category", "class", "course", "demographics", "enrollment", "gradingPeriod", "org", "resource", "user"` — Type of the referenced entity

  - **`dateLastModified` (required)**

    `string`, format: `date-time` — Timestamp of when the user was last modified

  - **`email` (required)**

    `string` — User's email address

  - **`enabledUser` (required)**

    `string`, possible values: `"true", "false"` — This is used to determine whether or not the record is active in the local system.

  - **`familyName` (required)**

    `string` — The family name. Also, known as the last name.

  - **`givenName` (required)**

    `string` — The given name. Also, known as the first name.

  - **`grades` (required)**

    `array` — Array of grade levels associated with the user

    **Items:**

    `string`

  - **`resources` (required)**

    `array` — The identifiers (GUIDs) for the set of resources that are to be made available to the user.

    **Items:**

    - **`href` (required)**

      `string`, format: `uri` — URI reference to the entity

    - **`sourcedId` (required)**

      `string` — Unique identifier of the referenced entity

    - **`type` (required)**

      `string`, possible values: `"academicSession", "category", "class", "course", "demographics", "enrollment", "gradingPeriod", "org", "resource", "user"` — Type of the referenced entity

  - **`roles` (required)**

    `array` — Array of roles assigned to the user

    **Items:**

    - **`org` (required)**

      `object` — Organization associated with the role

      - **`href` (required)**

        `string`, format: `uri` — URI reference to the entity

      - **`sourcedId` (required)**

        `string` — Unique identifier of the referenced entity

      - **`type` (required)**

        `string`, possible values: `"academicSession", "category", "class", "course", "demographics", "enrollment", "gradingPeriod", "org", "resource", "user"` — Type of the referenced entity

    - **`role` (required)**

      `string`, possible values: `"aide", "counselor", "districtAdministrator", "guardian", "parent", "principal", "proctor", "relative", "siteAdministrator", "student", "systemAdministrator", "teacher"` — Role value

    - **`roleType` (required)**

      `string`, possible values: `"primary", "secondary"` — Type of role (primary/secondary)

    - **`beginDate`**

      `string | null` — Date when the role assignment begins

    - **`endDate`**

      `string | null` — Date when the role assignment ends

    - **`userProfile`**

      `string | null` — User profile ID associated with this role

  - **`sourcedId` (required)**

    `string` — Unique identifier for the user

  - **`status` (required)**

    `string`, possible values: `"active", "tobedeleted", "inactive"` — Status of an entity in the system

  - **`userIds` (required)**

    `array` — The set of external user identifiers that should be used for this user.

    **Items:**

    `string`

  - **`userProfiles` (required)**

    `array` — Array of profiles associated with the user in different systems

    **Items:**

    - **`profileId` (required)**

      `string`, format: `uri` — Unique identifier for the profile

    - **`profileType` (required)**

      `string` — Type of profile (e.g., learning platform, assessment system)

    - **`vendorId` (required)**

      `string` — Identifier of the vendor providing this profile

    - **`applicationId`**

      `string | null` — Identifier of the specific application this profile is for

    - **`credentials`**

      `array` — List of credentials associated with this profile

      **Items:**

      - **`identity`**

        `string` — The identity for the profile

      - **`password`**

        `string` — The password for the profile

      - **`username`**

        `string` — The username for the profile

    - **`description`**

      `string | null` — Human-readable description of this profile

  - **`identifier`**

    `string | null` — Additional identifier for the user

  - **`metadata`**

    `object | null` — Additional metadata associated with the user

  - **`middleName`**

    `string | null` — The set of middle names. If more than one middle name is needed separate using a space.

  - **`password`**

    `string | null` — User's password (hashed)

  - **`phone`**

    `string | null` — User's primary phone number

  - **`preferredFirstName`**

    `string | null` — User's preferred first name if different from given name

  - **`preferredLastName`**

    `string | null` — User's preferred last name if different from family name

  - **`preferredMiddleName`**

    `string | null` — User's preferred middle name if different from middle name

  - **`primaryOrg`**

    `object` — ID of the user's primary organization

    - **`href` (required)**

      `string`, format: `uri` — URI reference to the entity

    - **`sourcedId` (required)**

      `string` — Unique identifier of the referenced entity

    - **`type` (required)**

      `string`, possible values: `"academicSession", "category", "class", "course", "demographics", "enrollment", "gradingPeriod", "org", "resource", "user"` — Type of the referenced entity

  - **`sms`**

    `string | null` — User's SMS contact number

  - **`userMasterIdentifier`**

    `string | null` — The master unique identifier for this user. This is NOT the same as the user's interoperability 'sourcedId'.

  - **`username`**

    `string | null` — The user name assigned to the user.

**Example:**

```json
{
  "student": {
    "sourcedId": "",
    "status": "active",
    "dateLastModified": "",
    "metadata": null,
    "userMasterIdentifier": null,
    "username": null,
    "userIds": [
      ""
    ],
    "enabledUser": "true",
    "givenName": "",
    "familyName": "",
    "middleName": null,
    "preferredFirstName": null,
    "preferredMiddleName": null,
    "preferredLastName": null,
    "roles": [
      {
        "roleType": "primary",
        "role": "aide",
        "org": {
          "href": "",
          "sourcedId": "",
          "type": "academicSession"
        },
        "userProfile": null,
        "beginDate": null,
        "endDate": null
      }
    ],
    "userProfiles": [
      {
        "profileId": "",
        "profileType": "",
        "vendorId": "",
        "applicationId": null,
        "description": null,
        "credentials": [
          {
            "username": "",
            "password": "",
            "identity": ""
          }
        ]
      }
    ],
    "primaryOrg": {
      "href": "",
      "sourcedId": "",
      "type": "academicSession"
    },
    "identifier": null,
    "email": "",
    "sms": null,
    "phone": null,
    "agents": [
      {
        "href": "",
        "sourcedId": "",
        "type": "academicSession"
      }
    ],
    "grades": [
      ""
    ],
    "password": null,
    "resources": [
      {
        "href": "",
        "sourcedId": "",
        "type": "academicSession"
      }
    ]
  }
}
```

##### Status: 400 Bad request

###### Content-Type: application/json

- **`imsx_codeMajor` (required)**

  `string`, possible values: `"success", "processing", "failure", "unsupported"` — The code major value (from the corresponding enumerated vocabulary).

- **`imsx_severity` (required)**

  `string`, possible values: `"status", "warning", "error"` — The severity value (from the corresponding enumerated vocabulary).

- **`imsx_CodeMinor`**

  `object` — This is the container for the set of code minor status codes reported in the responses from the Service Provider.

  - **`imsx_codeMinorField` (required)**

    `array` — Each reported code minor status code.

    **Items:**

    - **`imsx_codeMinorFieldName` (required)**

      `string`, default: `"TargetEndSystem"` — This should contain the identity of the system that has produced the code minor status code report. In most cases this will be the target service provider denoted as 'TargetEndSystem'.

    - **`imsx_codeMinorFieldValue` (required)**

      `string`, possible values: `"fullsuccess", "invalid_filter_field", "invalid_selection_field", "invaliddata", "unauthorisedrequest", "forbidden", "server_busy", "unknownobject", "internal_server_error"` — The code minor status code (this is a value from the corresponding enumerated vocabulary).

- **`imsx_description`**

  `string` — A human readable description supplied by the entity creating the status code information.

**Example:**

```json
{
  "imsx_codeMajor": "success",
  "imsx_severity": "status",
  "imsx_description": "",
  "imsx_CodeMinor": {
    "imsx_codeMinorField": [
      {
        "imsx_codeMinorFieldName": "TargetEndSystem",
        "imsx_codeMinorFieldValue": "fullsuccess"
      }
    ]
  }
}
```

##### Status: 500 Internal server error

###### Content-Type: application/json

- **`imsx_codeMajor` (required)**

  `string`, possible values: `"success", "processing", "failure", "unsupported"` — The code major value (from the corresponding enumerated vocabulary).

- **`imsx_severity` (required)**

  `string`, possible values: `"status", "warning", "error"` — The severity value (from the corresponding enumerated vocabulary).

- **`imsx_CodeMinor`**

  `object` — This is the container for the set of code minor status codes reported in the responses from the Service Provider.

  - **`imsx_codeMinorField` (required)**

    `array` — Each reported code minor status code.

    **Items:**

    - **`imsx_codeMinorFieldName` (required)**

      `string`, default: `"TargetEndSystem"` — This should contain the identity of the system that has produced the code minor status code report. In most cases this will be the target service provider denoted as 'TargetEndSystem'.

    - **`imsx_codeMinorFieldValue` (required)**

      `string`, possible values: `"fullsuccess", "invalid_filter_field", "invalid_selection_field", "invaliddata", "unauthorisedrequest", "forbidden", "server_busy", "unknownobject", "internal_server_error"` — The code minor status code (this is a value from the corresponding enumerated vocabulary).

- **`imsx_description`**

  `string` — A human readable description supplied by the entity creating the status code information.

**Example:**

```json
{
  "imsx_codeMajor": "success",
  "imsx_severity": "status",
  "imsx_description": "",
  "imsx_CodeMinor": {
    "imsx_codeMinorField": [
      {
        "imsx_codeMinorFieldName": "TargetEndSystem",
        "imsx_codeMinorFieldValue": "fullsuccess"
      }
    ]
  }
}
```

### Upsert a student agent

- **Method:** `PUT`
- **Path:** `/rostering/1.0/students/{sourcedId}/agents/{agentId}`
- **Tags:** StudentsManagement

Creates or updates an agent relationship for a student (e.g., parent, guardian)

#### Request Body

##### Content-Type: application/json

- **`relationshipType` (required)**

  `string` — Type of agent relationship (e.g., parent, guardian, relative)

- **`user` (required)**

  `object` — A reference to another OneRoster entity

  - **`href` (required)**

    `string`, format: `uri` — URI reference to the entity

  - **`sourcedId` (required)**

    `string` — Unique identifier of the referenced entity

  - **`type` (required)**

    `string`, possible values: `"academicSession", "category", "class", "course", "demographics", "enrollment", "gradingPeriod", "org", "resource", "user"` — Type of the referenced entity

**Example:**

```json
{
  "user": {
    "href": "",
    "sourcedId": "",
    "type": "academicSession"
  },
  "relationshipType": ""
}
```

#### Responses

##### Status: 201 Successfully created or updated

##### Status: 400 Bad request

###### Content-Type: application/json

- **`imsx_codeMajor` (required)**

  `string`, possible values: `"success", "processing", "failure", "unsupported"` — The code major value (from the corresponding enumerated vocabulary).

- **`imsx_severity` (required)**

  `string`, possible values: `"status", "warning", "error"` — The severity value (from the corresponding enumerated vocabulary).

- **`imsx_CodeMinor`**

  `object` — This is the container for the set of code minor status codes reported in the responses from the Service Provider.

  - **`imsx_codeMinorField` (required)**

    `array` — Each reported code minor status code.

    **Items:**

    - **`imsx_codeMinorFieldName` (required)**

      `string`, default: `"TargetEndSystem"` — This should contain the identity of the system that has produced the code minor status code report. In most cases this will be the target service provider denoted as 'TargetEndSystem'.

    - **`imsx_codeMinorFieldValue` (required)**

      `string`, possible values: `"fullsuccess", "invalid_filter_field", "invalid_selection_field", "invaliddata", "unauthorisedrequest", "forbidden", "server_busy", "unknownobject", "internal_server_error"` — The code minor status code (this is a value from the corresponding enumerated vocabulary).

- **`imsx_description`**

  `string` — A human readable description supplied by the entity creating the status code information.

**Example:**

```json
{
  "imsx_codeMajor": "success",
  "imsx_severity": "status",
  "imsx_description": "",
  "imsx_CodeMinor": {
    "imsx_codeMinorField": [
      {
        "imsx_codeMinorFieldName": "TargetEndSystem",
        "imsx_codeMinorFieldValue": "fullsuccess"
      }
    ]
  }
}
```

##### Status: 404 Resource not found

###### Content-Type: application/json

- **`imsx_codeMajor` (required)**

  `string`, possible values: `"success", "processing", "failure", "unsupported"` — The code major value (from the corresponding enumerated vocabulary).

- **`imsx_severity` (required)**

  `string`, possible values: `"status", "warning", "error"` — The severity value (from the corresponding enumerated vocabulary).

- **`imsx_CodeMinor`**

  `object` — This is the container for the set of code minor status codes reported in the responses from the Service Provider.

  - **`imsx_codeMinorField` (required)**

    `array` — Each reported code minor status code.

    **Items:**

    - **`imsx_codeMinorFieldName` (required)**

      `string`, default: `"TargetEndSystem"` — This should contain the identity of the system that has produced the code minor status code report. In most cases this will be the target service provider denoted as 'TargetEndSystem'.

    - **`imsx_codeMinorFieldValue` (required)**

      `string`, possible values: `"fullsuccess", "invalid_filter_field", "invalid_selection_field", "invaliddata", "unauthorisedrequest", "forbidden", "server_busy", "unknownobject", "internal_server_error"` — The code minor status code (this is a value from the corresponding enumerated vocabulary).

- **`imsx_description`**

  `string` — A human readable description supplied by the entity creating the status code information.

**Example:**

```json
{
  "imsx_codeMajor": "success",
  "imsx_severity": "status",
  "imsx_description": "",
  "imsx_CodeMinor": {
    "imsx_codeMinorField": [
      {
        "imsx_codeMinorFieldName": "TargetEndSystem",
        "imsx_codeMinorFieldValue": "fullsuccess"
      }
    ]
  }
}
```

##### Status: 500 Internal server error

###### Content-Type: application/json

- **`imsx_codeMajor` (required)**

  `string`, possible values: `"success", "processing", "failure", "unsupported"` — The code major value (from the corresponding enumerated vocabulary).

- **`imsx_severity` (required)**

  `string`, possible values: `"status", "warning", "error"` — The severity value (from the corresponding enumerated vocabulary).

- **`imsx_CodeMinor`**

  `object` — This is the container for the set of code minor status codes reported in the responses from the Service Provider.

  - **`imsx_codeMinorField` (required)**

    `array` — Each reported code minor status code.

    **Items:**

    - **`imsx_codeMinorFieldName` (required)**

      `string`, default: `"TargetEndSystem"` — This should contain the identity of the system that has produced the code minor status code report. In most cases this will be the target service provider denoted as 'TargetEndSystem'.

    - **`imsx_codeMinorFieldValue` (required)**

      `string`, possible values: `"fullsuccess", "invalid_filter_field", "invalid_selection_field", "invaliddata", "unauthorisedrequest", "forbidden", "server_busy", "unknownobject", "internal_server_error"` — The code minor status code (this is a value from the corresponding enumerated vocabulary).

- **`imsx_description`**

  `string` — A human readable description supplied by the entity creating the status code information.

**Example:**

```json
{
  "imsx_codeMajor": "success",
  "imsx_severity": "status",
  "imsx_description": "",
  "imsx_CodeMinor": {
    "imsx_codeMinorField": [
      {
        "imsx_codeMinorFieldName": "TargetEndSystem",
        "imsx_codeMinorFieldValue": "fullsuccess"
      }
    ]
  }
}
```

### Delete a student agent

- **Method:** `DELETE`
- **Path:** `/rostering/1.0/students/{sourcedId}/agents/{agentId}`
- **Tags:** StudentsManagement

Deletes an agent relationship for a student by agentId

#### Responses

##### Status: 204 Agent relationship deleted successfully

##### Status: 400 Bad request

###### Content-Type: application/json

- **`imsx_codeMajor` (required)**

  `string`, possible values: `"success", "processing", "failure", "unsupported"` — The code major value (from the corresponding enumerated vocabulary).

- **`imsx_severity` (required)**

  `string`, possible values: `"status", "warning", "error"` — The severity value (from the corresponding enumerated vocabulary).

- **`imsx_CodeMinor`**

  `object` — This is the container for the set of code minor status codes reported in the responses from the Service Provider.

  - **`imsx_codeMinorField` (required)**

    `array` — Each reported code minor status code.

    **Items:**

    - **`imsx_codeMinorFieldName` (required)**

      `string`, default: `"TargetEndSystem"` — This should contain the identity of the system that has produced the code minor status code report. In most cases this will be the target service provider denoted as 'TargetEndSystem'.

    - **`imsx_codeMinorFieldValue` (required)**

      `string`, possible values: `"fullsuccess", "invalid_filter_field", "invalid_selection_field", "invaliddata", "unauthorisedrequest", "forbidden", "server_busy", "unknownobject", "internal_server_error"` — The code minor status code (this is a value from the corresponding enumerated vocabulary).

- **`imsx_description`**

  `string` — A human readable description supplied by the entity creating the status code information.

**Example:**

```json
{
  "imsx_codeMajor": "success",
  "imsx_severity": "status",
  "imsx_description": "",
  "imsx_CodeMinor": {
    "imsx_codeMinorField": [
      {
        "imsx_codeMinorFieldName": "TargetEndSystem",
        "imsx_codeMinorFieldValue": "fullsuccess"
      }
    ]
  }
}
```

##### Status: 404 Agent relationship not found

###### Content-Type: application/json

- **`imsx_codeMajor` (required)**

  `string`, possible values: `"success", "processing", "failure", "unsupported"` — The code major value (from the corresponding enumerated vocabulary).

- **`imsx_severity` (required)**

  `string`, possible values: `"status", "warning", "error"` — The severity value (from the corresponding enumerated vocabulary).

- **`imsx_CodeMinor`**

  `object` — This is the container for the set of code minor status codes reported in the responses from the Service Provider.

  - **`imsx_codeMinorField` (required)**

    `array` — Each reported code minor status code.

    **Items:**

    - **`imsx_codeMinorFieldName` (required)**

      `string`, default: `"TargetEndSystem"` — This should contain the identity of the system that has produced the code minor status code report. In most cases this will be the target service provider denoted as 'TargetEndSystem'.

    - **`imsx_codeMinorFieldValue` (required)**

      `string`, possible values: `"fullsuccess", "invalid_filter_field", "invalid_selection_field", "invaliddata", "unauthorisedrequest", "forbidden", "server_busy", "unknownobject", "internal_server_error"` — The code minor status code (this is a value from the corresponding enumerated vocabulary).

- **`imsx_description`**

  `string` — A human readable description supplied by the entity creating the status code information.

**Example:**

```json
{
  "imsx_codeMajor": "success",
  "imsx_severity": "status",
  "imsx_description": "",
  "imsx_CodeMinor": {
    "imsx_codeMinorField": [
      {
        "imsx_codeMinorFieldName": "TargetEndSystem",
        "imsx_codeMinorFieldValue": "fullsuccess"
      }
    ]
  }
}
```

##### Status: 500 Internal server error

###### Content-Type: application/json

- **`imsx_codeMajor` (required)**

  `string`, possible values: `"success", "processing", "failure", "unsupported"` — The code major value (from the corresponding enumerated vocabulary).

- **`imsx_severity` (required)**

  `string`, possible values: `"status", "warning", "error"` — The severity value (from the corresponding enumerated vocabulary).

- **`imsx_CodeMinor`**

  `object` — This is the container for the set of code minor status codes reported in the responses from the Service Provider.

  - **`imsx_codeMinorField` (required)**

    `array` — Each reported code minor status code.

    **Items:**

    - **`imsx_codeMinorFieldName` (required)**

      `string`, default: `"TargetEndSystem"` — This should contain the identity of the system that has produced the code minor status code report. In most cases this will be the target service provider denoted as 'TargetEndSystem'.

    - **`imsx_codeMinorFieldValue` (required)**

      `string`, possible values: `"fullsuccess", "invalid_filter_field", "invalid_selection_field", "invaliddata", "unauthorisedrequest", "forbidden", "server_busy", "unknownobject", "internal_server_error"` — The code minor status code (this is a value from the corresponding enumerated vocabulary).

- **`imsx_description`**

  `string` — A human readable description supplied by the entity creating the status code information.

**Example:**

```json
{
  "imsx_codeMajor": "success",
  "imsx_severity": "status",
  "imsx_description": "",
  "imsx_CodeMinor": {
    "imsx_codeMinorField": [
      {
        "imsx_codeMinorFieldName": "TargetEndSystem",
        "imsx_codeMinorFieldValue": "fullsuccess"
      }
    ]
  }
}
```

### Get all users

- **Method:** `GET`
- **Path:** `/rostering/1.0/users`
- **Tags:** UsersManagement

Returns a list of users with optional filtering by role

#### Responses

##### Status: 200 Successful operation

###### Content-Type: application/json

- **`limit` (required)**

  `integer` — Maximum number of items returned

- **`offset` (required)**

  `integer` — Number of items skipped in the result set

- **`total` (required)**

  `integer` — Total number of items available

- **`users` (required)**

  `array` — Array of user objects

  **Items:**

  - **`agents` (required)**

    `array` — Array of agents (parents, guardians) associated with the user

    **Items:**

    - **`href` (required)**

      `string`, format: `uri` — URI reference to the entity

    - **`sourcedId` (required)**

      `string` — Unique identifier of the referenced entity

    - **`type` (required)**

      `string`, possible values: `"academicSession", "category", "class", "course", "demographics", "enrollment", "gradingPeriod", "org", "resource", "user"` — Type of the referenced entity

  - **`dateLastModified` (required)**

    `string`, format: `date-time` — Timestamp of when the user was last modified

  - **`email` (required)**

    `string` — User's email address

  - **`enabledUser` (required)**

    `string`, possible values: `"true", "false"` — This is used to determine whether or not the record is active in the local system.

  - **`familyName` (required)**

    `string` — The family name. Also, known as the last name.

  - **`givenName` (required)**

    `string` — The given name. Also, known as the first name.

  - **`grades` (required)**

    `array` — Array of grade levels associated with the user

    **Items:**

    `string`

  - **`resources` (required)**

    `array` — The identifiers (GUIDs) for the set of resources that are to be made available to the user.

    **Items:**

    - **`href` (required)**

      `string`, format: `uri` — URI reference to the entity

    - **`sourcedId` (required)**

      `string` — Unique identifier of the referenced entity

    - **`type` (required)**

      `string`, possible values: `"academicSession", "category", "class", "course", "demographics", "enrollment", "gradingPeriod", "org", "resource", "user"` — Type of the referenced entity

  - **`roles` (required)**

    `array` — Array of roles assigned to the user

    **Items:**

    - **`org` (required)**

      `object` — Organization associated with the role

      - **`href` (required)**

        `string`, format: `uri` — URI reference to the entity

      - **`sourcedId` (required)**

        `string` — Unique identifier of the referenced entity

      - **`type` (required)**

        `string`, possible values: `"academicSession", "category", "class", "course", "demographics", "enrollment", "gradingPeriod", "org", "resource", "user"` — Type of the referenced entity

    - **`role` (required)**

      `string`, possible values: `"aide", "counselor", "districtAdministrator", "guardian", "parent", "principal", "proctor", "relative", "siteAdministrator", "student", "systemAdministrator", "teacher"` — Role value

    - **`roleType` (required)**

      `string`, possible values: `"primary", "secondary"` — Type of role (primary/secondary)

    - **`beginDate`**

      `string | null` — Date when the role assignment begins

    - **`endDate`**

      `string | null` — Date when the role assignment ends

    - **`userProfile`**

      `string | null` — User profile ID associated with this role

  - **`sourcedId` (required)**

    `string` — Unique identifier for the user

  - **`status` (required)**

    `string`, possible values: `"active", "tobedeleted", "inactive"` — Status of an entity in the system

  - **`userIds` (required)**

    `array` — The set of external user identifiers that should be used for this user.

    **Items:**

    `string`

  - **`userProfiles` (required)**

    `array` — Array of profiles associated with the user in different systems

    **Items:**

    - **`profileId` (required)**

      `string`, format: `uri` — Unique identifier for the profile

    - **`profileType` (required)**

      `string` — Type of profile (e.g., learning platform, assessment system)

    - **`vendorId` (required)**

      `string` — Identifier of the vendor providing this profile

    - **`applicationId`**

      `string | null` — Identifier of the specific application this profile is for

    - **`credentials`**

      `array` — List of credentials associated with this profile

      **Items:**

      - **`identity`**

        `string` — The identity for the profile

      - **`password`**

        `string` — The password for the profile

      - **`username`**

        `string` — The username for the profile

    - **`description`**

      `string | null` — Human-readable description of this profile

  - **`identifier`**

    `string | null` — Additional identifier for the user

  - **`metadata`**

    `object | null` — Additional metadata associated with the user

  - **`middleName`**

    `string | null` — The set of middle names. If more than one middle name is needed separate using a space.

  - **`password`**

    `string | null` — User's password (hashed)

  - **`phone`**

    `string | null` — User's primary phone number

  - **`preferredFirstName`**

    `string | null` — User's preferred first name if different from given name

  - **`preferredLastName`**

    `string | null` — User's preferred last name if different from family name

  - **`preferredMiddleName`**

    `string | null` — User's preferred middle name if different from middle name

  - **`primaryOrg`**

    `object` — ID of the user's primary organization

    - **`href` (required)**

      `string`, format: `uri` — URI reference to the entity

    - **`sourcedId` (required)**

      `string` — Unique identifier of the referenced entity

    - **`type` (required)**

      `string`, possible values: `"academicSession", "category", "class", "course", "demographics", "enrollment", "gradingPeriod", "org", "resource", "user"` — Type of the referenced entity

  - **`sms`**

    `string | null` — User's SMS contact number

  - **`userMasterIdentifier`**

    `string | null` — The master unique identifier for this user. This is NOT the same as the user's interoperability 'sourcedId'.

  - **`username`**

    `string | null` — The user name assigned to the user.

**Example:**

```json
{
  "users": [
    {
      "sourcedId": "",
      "status": "active",
      "dateLastModified": "",
      "metadata": null,
      "userMasterIdentifier": null,
      "username": null,
      "userIds": [
        ""
      ],
      "enabledUser": "true",
      "givenName": "",
      "familyName": "",
      "middleName": null,
      "preferredFirstName": null,
      "preferredMiddleName": null,
      "preferredLastName": null,
      "roles": [
        {
          "roleType": "primary",
          "role": "aide",
          "org": {
            "href": "",
            "sourcedId": "",
            "type": "academicSession"
          },
          "userProfile": null,
          "beginDate": null,
          "endDate": null
        }
      ],
      "userProfiles": [
        {
          "profileId": "",
          "profileType": "",
          "vendorId": "",
          "applicationId": null,
          "description": null,
          "credentials": [
            {
              "username": "",
              "password": "",
              "identity": ""
            }
          ]
        }
      ],
      "primaryOrg": {
        "href": "",
        "sourcedId": "",
        "type": "academicSession"
      },
      "identifier": null,
      "email": "",
      "sms": null,
      "phone": null,
      "agents": [
        {
          "href": "",
          "sourcedId": "",
          "type": "academicSession"
        }
      ],
      "grades": [
        ""
      ],
      "password": null,
      "resources": [
        {
          "href": "",
          "sourcedId": "",
          "type": "academicSession"
        }
      ]
    }
  ],
  "offset": 1,
  "limit": 1,
  "total": 1
}
```

##### Status: 400 Bad request

###### Content-Type: application/json

- **`imsx_codeMajor` (required)**

  `string`, possible values: `"success", "processing", "failure", "unsupported"` — The code major value (from the corresponding enumerated vocabulary).

- **`imsx_severity` (required)**

  `string`, possible values: `"status", "warning", "error"` — The severity value (from the corresponding enumerated vocabulary).

- **`imsx_CodeMinor`**

  `object` — This is the container for the set of code minor status codes reported in the responses from the Service Provider.

  - **`imsx_codeMinorField` (required)**

    `array` — Each reported code minor status code.

    **Items:**

    - **`imsx_codeMinorFieldName` (required)**

      `string`, default: `"TargetEndSystem"` — This should contain the identity of the system that has produced the code minor status code report. In most cases this will be the target service provider denoted as 'TargetEndSystem'.

    - **`imsx_codeMinorFieldValue` (required)**

      `string`, possible values: `"fullsuccess", "invalid_filter_field", "invalid_selection_field", "invaliddata", "unauthorisedrequest", "forbidden", "server_busy", "unknownobject", "internal_server_error"` — The code minor status code (this is a value from the corresponding enumerated vocabulary).

- **`imsx_description`**

  `string` — A human readable description supplied by the entity creating the status code information.

**Example:**

```json
{
  "imsx_codeMajor": "success",
  "imsx_severity": "status",
  "imsx_description": "",
  "imsx_CodeMinor": {
    "imsx_codeMinorField": [
      {
        "imsx_codeMinorFieldName": "TargetEndSystem",
        "imsx_codeMinorFieldValue": "fullsuccess"
      }
    ]
  }
}
```

##### Status: 500 Internal server error

###### Content-Type: application/json

- **`imsx_codeMajor` (required)**

  `string`, possible values: `"success", "processing", "failure", "unsupported"` — The code major value (from the corresponding enumerated vocabulary).

- **`imsx_severity` (required)**

  `string`, possible values: `"status", "warning", "error"` — The severity value (from the corresponding enumerated vocabulary).

- **`imsx_CodeMinor`**

  `object` — This is the container for the set of code minor status codes reported in the responses from the Service Provider.

  - **`imsx_codeMinorField` (required)**

    `array` — Each reported code minor status code.

    **Items:**

    - **`imsx_codeMinorFieldName` (required)**

      `string`, default: `"TargetEndSystem"` — This should contain the identity of the system that has produced the code minor status code report. In most cases this will be the target service provider denoted as 'TargetEndSystem'.

    - **`imsx_codeMinorFieldValue` (required)**

      `string`, possible values: `"fullsuccess", "invalid_filter_field", "invalid_selection_field", "invaliddata", "unauthorisedrequest", "forbidden", "server_busy", "unknownobject", "internal_server_error"` — The code minor status code (this is a value from the corresponding enumerated vocabulary).

- **`imsx_description`**

  `string` — A human readable description supplied by the entity creating the status code information.

**Example:**

```json
{
  "imsx_codeMajor": "success",
  "imsx_severity": "status",
  "imsx_description": "",
  "imsx_CodeMinor": {
    "imsx_codeMinorField": [
      {
        "imsx_codeMinorFieldName": "TargetEndSystem",
        "imsx_codeMinorFieldValue": "fullsuccess"
      }
    ]
  }
}
```

### Upsert a user

- **Method:** `PUT`
- **Path:** `/rostering/1.0/users/{sourcedId}`
- **Tags:** UsersManagement

Creates or updates a user by their sourcedId

#### Request Body

##### Content-Type: application/json

- **`user` (required)**

  `object`

  - **`email` (required)**

    `string`, format: `email` — User's email address

  - **`enabledUser` (required)**

    `string`, possible values: `"true", "false"` — Whether the user account is enabled

  - **`familyName` (required)**

    `string` — User's last name

  - **`givenName` (required)**

    `string` — User's first name

  - **`grades` (required)**

    `array` — Grade levels for the user

    **Items:**

    `string`

  - **`primaryOrg` (required)**

    `object`

    - **`sourcedId` (required)**

      `string`, format: `uuid` — Organization ID

    - **`type` (required)**

      `string`, possible values: `"org"` — Reference type

    - **`href`**

      `string` — URI reference to the organization

  - **`sourcedId` (required)**

    `string`, format: `uuid` — Unique identifier for the user

  - **`status` (required)**

    `string`, possible values: `"active", "tobedeleted", "inactive"` — Status of the user record

  - **`demographics`**

    `object` — Demographic information for the user

    - **`birthDate`**

      `string | null`, format: `date` — User's birth date

  - **`identifier`**

    `string | null` — Additional identifier for the user

  - **`metadata`**

    `object | null` — Additional metadata for the user

  - **`middleName`**

    `string | null` — User's middle name

  - **`password`**

    `string | null` — User's password

  - **`phone`**

    `string | null` — User's phone number

  - **`preferredFirstName`**

    `string | null` — User's preferred first name

  - **`preferredLastName`**

    `string | null` — User's preferred last name

  - **`preferredMiddleName`**

    `string | null` — User's preferred middle name

  - **`pronouns`**

    `string | null` — User's preferred pronouns

  - **`roles`**

    `array` — Roles to be assigned to the user

    **Items:**

    - **`org` (required)**

      `object`

      - **`sourcedId` (required)**

        `string`, format: `uuid`

      - **`type` (required)**

        `string`, possible values: `"org"`

      - **`href`**

        `string`

    - **`role` (required)**

      `string`, possible values: `"aide", "counselor", "districtAdministrator", "guardian", "parent", "principal", "proctor", "relative", "siteAdministrator", "student", "systemAdministrator", "teacher"`

    - **`roleType` (required)**

      `string`, possible values: `"primary", "secondary"`

  - **`sms`**

    `string | null` — User's SMS number

  - **`userMasterIdentifier`**

    `string | null` — Master identifier for the user

  - **`username`**

    `string | null` — Username for the user

**Example:**

```json
{
  "user": {
    "sourcedId": "",
    "status": "active",
    "metadata": null,
    "userMasterIdentifier": null,
    "username": null,
    "enabledUser": "true",
    "givenName": "",
    "familyName": "",
    "middleName": null,
    "preferredFirstName": null,
    "preferredMiddleName": null,
    "preferredLastName": null,
    "pronouns": null,
    "demographics": {
      "birthDate": null
    },
    "primaryOrg": {
      "href": "",
      "sourcedId": "",
      "type": "org"
    },
    "identifier": null,
    "email": "",
    "sms": null,
    "phone": null,
    "grades": [
      ""
    ],
    "password": null,
    "roles": [
      {
        "roleType": "primary",
        "role": "aide",
        "org": {
          "href": "",
          "sourcedId": "",
          "type": "org"
        }
      }
    ]
  }
}
```

#### Responses

##### Status: 201 Successfully created or updated

##### Status: 400 Bad request

###### Content-Type: application/json

- **`imsx_codeMajor` (required)**

  `string`, possible values: `"success", "processing", "failure", "unsupported"` — The code major value (from the corresponding enumerated vocabulary).

- **`imsx_severity` (required)**

  `string`, possible values: `"status", "warning", "error"` — The severity value (from the corresponding enumerated vocabulary).

- **`imsx_CodeMinor`**

  `object` — This is the container for the set of code minor status codes reported in the responses from the Service Provider.

  - **`imsx_codeMinorField` (required)**

    `array` — Each reported code minor status code.

    **Items:**

    - **`imsx_codeMinorFieldName` (required)**

      `string`, default: `"TargetEndSystem"` — This should contain the identity of the system that has produced the code minor status code report. In most cases this will be the target service provider denoted as 'TargetEndSystem'.

    - **`imsx_codeMinorFieldValue` (required)**

      `string`, possible values: `"fullsuccess", "invalid_filter_field", "invalid_selection_field", "invaliddata", "unauthorisedrequest", "forbidden", "server_busy", "unknownobject", "internal_server_error"` — The code minor status code (this is a value from the corresponding enumerated vocabulary).

- **`imsx_description`**

  `string` — A human readable description supplied by the entity creating the status code information.

**Example:**

```json
{
  "imsx_codeMajor": "success",
  "imsx_severity": "status",
  "imsx_description": "",
  "imsx_CodeMinor": {
    "imsx_codeMinorField": [
      {
        "imsx_codeMinorFieldName": "TargetEndSystem",
        "imsx_codeMinorFieldValue": "fullsuccess"
      }
    ]
  }
}
```

##### Status: 500 Internal server error

###### Content-Type: application/json

- **`imsx_codeMajor` (required)**

  `string`, possible values: `"success", "processing", "failure", "unsupported"` — The code major value (from the corresponding enumerated vocabulary).

- **`imsx_severity` (required)**

  `string`, possible values: `"status", "warning", "error"` — The severity value (from the corresponding enumerated vocabulary).

- **`imsx_CodeMinor`**

  `object` — This is the container for the set of code minor status codes reported in the responses from the Service Provider.

  - **`imsx_codeMinorField` (required)**

    `array` — Each reported code minor status code.

    **Items:**

    - **`imsx_codeMinorFieldName` (required)**

      `string`, default: `"TargetEndSystem"` — This should contain the identity of the system that has produced the code minor status code report. In most cases this will be the target service provider denoted as 'TargetEndSystem'.

    - **`imsx_codeMinorFieldValue` (required)**

      `string`, possible values: `"fullsuccess", "invalid_filter_field", "invalid_selection_field", "invaliddata", "unauthorisedrequest", "forbidden", "server_busy", "unknownobject", "internal_server_error"` — The code minor status code (this is a value from the corresponding enumerated vocabulary).

- **`imsx_description`**

  `string` — A human readable description supplied by the entity creating the status code information.

**Example:**

```json
{
  "imsx_codeMajor": "success",
  "imsx_severity": "status",
  "imsx_description": "",
  "imsx_CodeMinor": {
    "imsx_codeMinorField": [
      {
        "imsx_codeMinorFieldName": "TargetEndSystem",
        "imsx_codeMinorFieldValue": "fullsuccess"
      }
    ]
  }
}
```

### Get agents for a user

- **Method:** `GET`
- **Path:** `/rostering/1.0/users/{sourcedId}/agents`
- **Tags:** UsersManagement

Returns all agents associated with a specific user

#### Responses

##### Status: 200 Successful operation

###### Content-Type: application/json

- **`agents` (required)**

  `array` — Array of agent relationships

  **Items:**

  - **`relationshipType` (required)**

    `string` — Type of agent relationship (e.g., parent, guardian)

  - **`user` (required)**

    `object` — A reference to another OneRoster entity

    - **`href` (required)**

      `string`, format: `uri` — URI reference to the entity

    - **`sourcedId` (required)**

      `string` — Unique identifier of the referenced entity

    - **`type` (required)**

      `string`, possible values: `"academicSession", "category", "class", "course", "demographics", "enrollment", "gradingPeriod", "org", "resource", "user"` — Type of the referenced entity

**Example:**

```json
{
  "agents": [
    {
      "user": {
        "href": "",
        "sourcedId": "",
        "type": "academicSession"
      },
      "relationshipType": ""
    }
  ]
}
```

##### Status: 400 Bad request

###### Content-Type: application/json

- **`imsx_codeMajor` (required)**

  `string`, possible values: `"success", "processing", "failure", "unsupported"` — The code major value (from the corresponding enumerated vocabulary).

- **`imsx_severity` (required)**

  `string`, possible values: `"status", "warning", "error"` — The severity value (from the corresponding enumerated vocabulary).

- **`imsx_CodeMinor`**

  `object` — This is the container for the set of code minor status codes reported in the responses from the Service Provider.

  - **`imsx_codeMinorField` (required)**

    `array` — Each reported code minor status code.

    **Items:**

    - **`imsx_codeMinorFieldName` (required)**

      `string`, default: `"TargetEndSystem"` — This should contain the identity of the system that has produced the code minor status code report. In most cases this will be the target service provider denoted as 'TargetEndSystem'.

    - **`imsx_codeMinorFieldValue` (required)**

      `string`, possible values: `"fullsuccess", "invalid_filter_field", "invalid_selection_field", "invaliddata", "unauthorisedrequest", "forbidden", "server_busy", "unknownobject", "internal_server_error"` — The code minor status code (this is a value from the corresponding enumerated vocabulary).

- **`imsx_description`**

  `string` — A human readable description supplied by the entity creating the status code information.

**Example:**

```json
{
  "imsx_codeMajor": "success",
  "imsx_severity": "status",
  "imsx_description": "",
  "imsx_CodeMinor": {
    "imsx_codeMinorField": [
      {
        "imsx_codeMinorFieldName": "TargetEndSystem",
        "imsx_codeMinorFieldValue": "fullsuccess"
      }
    ]
  }
}
```

##### Status: 404 User not found

###### Content-Type: application/json

- **`imsx_codeMajor` (required)**

  `string`, possible values: `"success", "processing", "failure", "unsupported"` — The code major value (from the corresponding enumerated vocabulary).

- **`imsx_severity` (required)**

  `string`, possible values: `"status", "warning", "error"` — The severity value (from the corresponding enumerated vocabulary).

- **`imsx_CodeMinor`**

  `object` — This is the container for the set of code minor status codes reported in the responses from the Service Provider.

  - **`imsx_codeMinorField` (required)**

    `array` — Each reported code minor status code.

    **Items:**

    - **`imsx_codeMinorFieldName` (required)**

      `string`, default: `"TargetEndSystem"` — This should contain the identity of the system that has produced the code minor status code report. In most cases this will be the target service provider denoted as 'TargetEndSystem'.

    - **`imsx_codeMinorFieldValue` (required)**

      `string`, possible values: `"fullsuccess", "invalid_filter_field", "invalid_selection_field", "invaliddata", "unauthorisedrequest", "forbidden", "server_busy", "unknownobject", "internal_server_error"` — The code minor status code (this is a value from the corresponding enumerated vocabulary).

- **`imsx_description`**

  `string` — A human readable description supplied by the entity creating the status code information.

**Example:**

```json
{
  "imsx_codeMajor": "success",
  "imsx_severity": "status",
  "imsx_description": "",
  "imsx_CodeMinor": {
    "imsx_codeMinorField": [
      {
        "imsx_codeMinorFieldName": "TargetEndSystem",
        "imsx_codeMinorFieldValue": "fullsuccess"
      }
    ]
  }
}
```

##### Status: 500 Internal server error

###### Content-Type: application/json

- **`imsx_codeMajor` (required)**

  `string`, possible values: `"success", "processing", "failure", "unsupported"` — The code major value (from the corresponding enumerated vocabulary).

- **`imsx_severity` (required)**

  `string`, possible values: `"status", "warning", "error"` — The severity value (from the corresponding enumerated vocabulary).

- **`imsx_CodeMinor`**

  `object` — This is the container for the set of code minor status codes reported in the responses from the Service Provider.

  - **`imsx_codeMinorField` (required)**

    `array` — Each reported code minor status code.

    **Items:**

    - **`imsx_codeMinorFieldName` (required)**

      `string`, default: `"TargetEndSystem"` — This should contain the identity of the system that has produced the code minor status code report. In most cases this will be the target service provider denoted as 'TargetEndSystem'.

    - **`imsx_codeMinorFieldValue` (required)**

      `string`, possible values: `"fullsuccess", "invalid_filter_field", "invalid_selection_field", "invaliddata", "unauthorisedrequest", "forbidden", "server_busy", "unknownobject", "internal_server_error"` — The code minor status code (this is a value from the corresponding enumerated vocabulary).

- **`imsx_description`**

  `string` — A human readable description supplied by the entity creating the status code information.

**Example:**

```json
{
  "imsx_codeMajor": "success",
  "imsx_severity": "status",
  "imsx_description": "",
  "imsx_CodeMinor": {
    "imsx_codeMinorField": [
      {
        "imsx_codeMinorFieldName": "TargetEndSystem",
        "imsx_codeMinorFieldValue": "fullsuccess"
      }
    ]
  }
}
```

## Schemas

### TokenRequest

- **Type:**`object`

* **`grant_type` (required)**

  `string`, possible values: `"client_credentials"`

* **`scope`**

  `string` — Space-separated list of scopes

**Example:**

```json
{
  "grant_type": "client_credentials",
  "scope": ""
}
```

### TokenResponse

- **Type:**`object`

* **`access_token` (required)**

  `string`

* **`expires_in` (required)**

  `integer` — Token expiration time in seconds

* **`token_type` (required)**

  `string`, possible values: `"bearer"`

* **`scope`**

  `string` — Space-separated list of granted scopes

**Example:**

```json
{
  "access_token": "",
  "token_type": "bearer",
  "expires_in": 1,
  "scope": ""
}
```

### CleanupDataOutput

- **Type:**`object`

Result of data cleanup operation

- **`entitiesCleared` (required)**

  `array` — List of entity class names that were cleared

  **Items:**

  `string`

- **`message` (required)**

  `string` — Human-readable message about the operation result

- **`success` (required)**

  `boolean` — Whether the cleanup operation was successful

**Example:**

```json
{
  "success": true,
  "message": "",
  "entitiesCleared": [
    ""
  ]
}
```

### ApiError

- **Type:**`object`

API error response

- **`error` (required)**

  `string` — Error type

- **`message` (required)**

  `string` — Error message

**Example:**

```json
{
  "error": "",
  "message": ""
}
```

### Action

- **Type:**`string`

**Example:**

### EntityType

- **Type:**`string`

**Example:**

### EventType

- **Type:**`string`

**Example:**

### LisRole

- **Type:**`string`

**Example:**

### LisStatus

- **Type:**`string`

**Example:**

### Profile

- **Type:**`string`

**Example:**

### SystemIdentifierType

- **Type:**`string`

**Example:**

### Iri

- **Type:**

An IRI can be either:

1. A URI (any valid URI scheme)
2. A URN in the format "urn:uuid:" where UUID is a version 4 UUID

**Example:**

### IsoDateTime

- **Type:**`string`

**Example:**

### Duration

- **Type:**`string`

**Example:**

### Extensions

- **Type:**`object`

**Example:**

```json
{
  "propertyName*": "anything"
}
```

### Entity

- **Type:**`object`

Base type for all Caliper entities

- **`id` (required)**

  `object` — An IRI can be either: 1. A URI (any valid URI scheme) 2. A URN in the format "urn:uuid:\<UUID>" where UUID is a version 4 UUID

- **`type` (required)**

  `string`, possible values: `"Entity", "Agent", "AggregateMeasure", "AggregateMeasureCollection", "Annotation", "Assessment", "AssessmentItem", "AssignableDigitalResource", "Attempt", "AudioObject", "BookmarkAnnotation", "Chapter", "CommentAnnotation", "CourseOffering", "CourseSection", "DigitalResource", "DigitalResourceCollection", "Document", "EpubChapter", "EpubPart", "EpubSubChapter", "EpubVolume", "FillinBlankResponse", "Forum", "ForumThread", "Frame", "FreeResponse", "Group", "HighlightAnnotation", "ImageObject", "LearningObjective", "Link", "Location", "LtiSession", "MarginAnnotation", "MediaLocation", "MediaObject", "Membership", "Message", "MessageThread", "MultipleChoiceResponse", "MultipleResponseResponse", "Organization", "Page", "Person", "Question", "Questionnaire", "QuestionnaireItem", "Rating", "Reading", "ReferenceFrame", "Response", "Result", "Score", "SearchResponse", "Section", "SelectTextResponse", "Session", "SharedAnnotation", "SoftwareApplication", "Survey", "SyllabusItem", "SystemIdentifier", "TagAnnotation", "TextPositionSelector", "Thread", "Tool", "TrueFalseResponse", "VideoObject", "WebLink", "WebPage", "DateTimeQuestion", "MultiselectQuestion", "OpenEndedQuestion", "RatingScaleQuestion", "DateTimeResponse", "MultiselectResponse", "OpenendedResponse", "RatingscaleResponse", "Scale", "LikertScale", "MultiselectScale", "NumericScale", "AntiPattern"`

- **`dateCreated`**

  `string`, format: `date-time`

- **`dateModified`**

  `string`, format: `date-time`

- **`description`**

  `string`

- **`extensions`**

  `object`

- **`name`**

  `string`

- **`otherIdentifiers`**

  `array`

  **Items:**

  **One of:**

  - **`identifier` (required)**

    `string`

  - **`type` (required)**

    `string`, possible values: `"AccountUserName", "EmailAddress", "LisSourcedId", "LtiContextId", "LtiDeploymentId", "LtiPlatformId", "LtiToolId", "LtiUserId", "OneRosterSourcedId", "Other", "SisSourcedId", "SystemId"`

  - **`source`**

    `object`

**Example:**

```json
{
  "id": "",
  "type": "Entity",
  "name": "",
  "description": "",
  "dateCreated": "",
  "dateModified": "",
  "extensions": {
    "propertyName*": "anything"
  },
  "otherIdentifiers": [
    {
      "type": "AccountUserName",
      "identifier": "",
      "source": {
        "type": "SoftwareApplication",
        "name": "",
        "description": "",
        "dateCreated": "",
        "dateModified": "",
        "extensions": {
          "propertyName*": "anything"
        },
        "version": "",
        "host": "",
        "ipAddress": "",
        "userAgent": ""
      }
    }
  ]
}
```

### Agent

- **Type:**

**Example:**

### Person

- **Type:**

**Example:**

### SoftwareApplication

- **Type:**

**Example:**

### Organization

- **Type:**

**Example:**

### Session

- **Type:**

**Example:**

### Membership

- **Type:**

**Example:**

### LtiSession

- **Type:**

**Example:**

### LtiMessageParameter

- **Type:**`object`

* **`aud` (required)**

  `object`

* **`azp` (required)**

  `string`

* **`deployment_id` (required)**

  `string`

* **`exp` (required)**

  `number`

* **`iat` (required)**

  `number`

* **`iss` (required)**

  `string`, format: `url`

* **`message_type` (required)**

  `string`, possible values: `"LtiResourceLinkRequest"`

* **`nonce` (required)**

  `string`

* **`sub` (required)**

  `string`

* **`target_link_uri` (required)**

  `string`, format: `url`

* **`version` (required)**

  `string`, possible values: `"1.3.0"`

* **`email`**

  `string`, format: `email`

* **`family_name`**

  `string`

* **`given_name`**

  `string`

* **`locale`**

  `string`

* **`middle_name`**

  `string`

* **`name`**

  `string`

* **`picture`**

  `string`, format: `url`

**Example:**

```json
{
  "iss": "",
  "sub": "",
  "aud": "",
  "exp": 1,
  "iat": 1,
  "azp": "",
  "nonce": "",
  "name": "",
  "given_name": "",
  "family_name": "",
  "middle_name": "",
  "picture": "",
  "email": "",
  "locale": "",
  "deployment_id": "",
  "message_type": "LtiResourceLinkRequest",
  "version": "1.3.0",
  "target_link_uri": ""
}
```

### Event

- **Type:**`object`

Caliper Event

- **`@context` (required)**

  `string`, possible values: `"http://purl.imsglobal.org/ctx/caliper/v1p2"`

- **`action` (required)**

  `string`, possible values: `"Abandoned", "Accepted", "Activated", "Added", "Archived", "Attached", "Bookmarked", "ChangedResolution", "ChangedSize", "ChangedSpeed", "ChangedVolume", "Classified", "ClosedPopout", "Commented", "Completed", "Copied", "Created", "Deactivated", "Declined", "Deleted", "Described", "DisabledClosedCaptioning", "Disliked", "Downloaded", "EnabledClosedCaptioning", "Ended", "EnteredFullScreen", "ExitedFullScreen", "ForwardedTo", "Graded", "Hid", "Highlighted", "Identified", "JumpedTo", "Launched", "Liked", "Linked", "LoggedIn", "LoggedOut", "MarkedAsRead", "MarkedAsUnread", "Modified", "Muted", "NavigatedTo", "OpenedPopout", "OptedIn", "OptedOut", "Paused", "Posted", "Printed", "Published", "Questioned", "Ranked", "Recommended", "Removed", "Reset", "Restarted", "Restored", "Resumed", "Retrieved", "Returned", "Reviewed", "Rewound", "Saved", "Searched", "Sent", "Shared", "Showed", "Skipped", "Started", "Submitted", "Subscribed", "Tagged", "TimedOut", "Unmuted", "Unpublished", "Unsubscribed", "Uploaded", "Used", "Viewed"`

- **`actor` (required)**

  `object`

- **`eventTime` (required)**

  `string`, format: `date-time`

- **`id` (required)**

  `object` — An IRI can be either: 1. A URI (any valid URI scheme) 2. A URN in the format "urn:uuid:\<UUID>" where UUID is a version 4 UUID

- **`object` (required)**

  `object`

- **`type` (required)**

  `string`, possible values: `"Event", "AnnotationEvent", "AssessmentEvent", "AssessmentItemEvent", "AssignableEvent", "ForumEvent", "GradeEvent", "MediaEvent", "MessageEvent", "NavigationEvent", "ReadingEvent", "ResourceManagementEvent", "SearchEvent", "SessionEvent", "SurveyEvent", "ThreadEvent", "ToolLaunchEvent", "ToolUseEvent", "ViewEvent", "QuestionnaireEvent", "QuestionnaireItemEvent", "SurveyInvitationEvent", "AntiPatternEvent"`

- **`edApp`**

  `object`

- **`extensions`**

  `object`

- **`federatedSession`**

  `object`

- **`generated`**

  `object`

- **`group`**

  `object`

- **`membership`**

  `object`

- **`profile`**

  `string`, possible values: `"GeneralProfile", "AnnotationProfile", "AssessmentProfile", "AssignableProfile", "FeedbackProfile", "ForumProfile", "GradingProfile", "MediaProfile", "ReadingProfile", "ResourceManagementProfile", "SearchProfile", "SessionProfile", "ToolLaunchProfile", "ToolUseProfile", "MonitoringProfile"`

- **`referrer`**

  `object`

- **`session`**

  `object`

- **`target`**

  `object`

**Example:**

```json
{
  "@context": "http://purl.imsglobal.org/ctx/caliper/v1p2",
  "id": "",
  "type": "Event",
  "profile": "GeneralProfile",
  "actor": {
    "id": "",
    "type": "Entity",
    "name": "",
    "description": "",
    "dateCreated": "",
    "dateModified": "",
    "extensions": {
      "propertyName*": "anything"
    },
    "otherIdentifiers": [
      {
        "type": "AccountUserName",
        "identifier": "",
        "source": {
          "type": "SoftwareApplication",
          "name": "",
          "description": "",
          "dateCreated": "",
          "dateModified": "",
          "extensions": {
            "propertyName*": "anything"
          },
          "version": "",
          "host": "",
          "ipAddress": "",
          "userAgent": ""
        }
      }
    ]
  },
  "action": "Abandoned",
  "object": {
    "id": "",
    "type": "Entity",
    "name": "",
    "description": "",
    "dateCreated": "",
    "dateModified": "",
    "extensions": {
      "propertyName*": "anything"
    },
    "otherIdentifiers": [
      {
        "type": "AccountUserName",
        "identifier": "",
        "source": {
          "type": "SoftwareApplication",
          "name": "",
          "description": "",
          "dateCreated": "",
          "dateModified": "",
          "extensions": {
            "propertyName*": "anything"
          },
          "version": "",
          "host": "",
          "ipAddress": "",
          "userAgent": ""
        }
      }
    ]
  },
  "eventTime": "",
  "edApp": {
    "id": "",
    "type": "SoftwareApplication",
    "name": "",
    "description": "",
    "dateCreated": "",
    "dateModified": "",
    "extensions": {
      "propertyName*": "anything"
    },
    "otherIdentifiers": [
      {
        "type": "AccountUserName",
        "identifier": "",
        "source": {
          "type": "SoftwareApplication",
          "name": "",
          "description": "",
          "dateCreated": "",
          "dateModified": "",
          "extensions": {
            "propertyName*": "anything"
          },
          "version": "",
          "host": "",
          "ipAddress": "",
          "userAgent": ""
        }
      }
    ],
    "version": "",
    "host": "",
    "ipAddress": "",
    "userAgent": ""
  },
  "generated": {
    "id": "",
    "type": "Entity",
    "name": "",
    "description": "",
    "dateCreated": "",
    "dateModified": "",
    "extensions": {
      "propertyName*": "anything"
    },
    "otherIdentifiers": [
      {
        "type": "AccountUserName",
        "identifier": "",
        "source": {
          "type": "SoftwareApplication",
          "name": "",
          "description": "",
          "dateCreated": "",
          "dateModified": "",
          "extensions": {
            "propertyName*": "anything"
          },
          "version": "",
          "host": "",
          "ipAddress": "",
          "userAgent": ""
        }
      }
    ]
  },
  "target": {
    "id": "",
    "type": "Entity",
    "name": "",
    "description": "",
    "dateCreated": "",
    "dateModified": "",
    "extensions": {
      "propertyName*": "anything"
    },
    "otherIdentifiers": [
      {
        "type": "AccountUserName",
        "identifier": "",
        "source": {
          "type": "SoftwareApplication",
          "name": "",
          "description": "",
          "dateCreated": "",
          "dateModified": "",
          "extensions": {
            "propertyName*": "anything"
          },
          "version": "",
          "host": "",
          "ipAddress": "",
          "userAgent": ""
        }
      }
    ]
  },
  "referrer": {
    "id": "",
    "type": "Entity",
    "name": "",
    "description": "",
    "dateCreated": "",
    "dateModified": "",
    "extensions": {
      "propertyName*": "anything"
    },
    "otherIdentifiers": [
      {
        "type": "AccountUserName",
        "identifier": "",
        "source": {
          "type": "SoftwareApplication",
          "name": "",
          "description": "",
          "dateCreated": "",
          "dateModified": "",
          "extensions": {
            "propertyName*": "anything"
          },
          "version": "",
          "host": "",
          "ipAddress": "",
          "userAgent": ""
        }
      }
    ]
  },
  "group": {
    "id": "",
    "type": "Organization",
    "name": "",
    "description": "",
    "dateCreated": "",
    "dateModified": "",
    "extensions": {
      "propertyName*": "anything"
    },
    "otherIdentifiers": [
      {
        "type": "AccountUserName",
        "identifier": "",
        "source": {
          "type": "SoftwareApplication",
          "name": "",
          "description": "",
          "dateCreated": "",
          "dateModified": "",
          "extensions": {
            "propertyName*": "anything"
          },
          "version": "",
          "host": "",
          "ipAddress": "",
          "userAgent": ""
        }
      }
    ],
    "members": [
      {
        "id": "",
        "type": "Entity",
        "name": "",
        "description": "",
        "dateCreated": "",
        "dateModified": "",
        "extensions": {
          "propertyName*": "anything"
        },
        "otherIdentifiers": [
          {
            "type": "AccountUserName",
            "identifier": "",
            "source": {
              "type": "SoftwareApplication",
              "name": "",
              "description": "",
              "dateCreated": "",
              "dateModified": "",
              "extensions": {
                "propertyName*": "anything"
              },
              "version": "",
              "host": "",
              "ipAddress": "",
              "userAgent": ""
            }
          }
        ]
      }
    ],
    "subOrganizationOf": "[Circular Reference]"
  },
  "membership": {
    "id": "",
    "type": "Membership",
    "name": "",
    "description": "",
    "dateCreated": "",
    "dateModified": "",
    "extensions": {
      "propertyName*": "anything"
    },
    "otherIdentifiers": [
      {
        "type": "AccountUserName",
        "identifier": "",
        "source": {
          "type": "SoftwareApplication",
          "name": "",
          "description": "",
          "dateCreated": "",
          "dateModified": "",
          "extensions": {
            "propertyName*": "anything"
          },
          "version": "",
          "host": "",
          "ipAddress": "",
          "userAgent": ""
        }
      }
    ],
    "organization": {
      "id": "",
      "type": "Organization",
      "name": "",
      "description": "",
      "dateCreated": "",
      "dateModified": "",
      "extensions": {
        "propertyName*": "anything"
      },
      "otherIdentifiers": [
        {
          "type": "AccountUserName",
          "identifier": "",
          "source": {
            "type": "SoftwareApplication",
            "name": "",
            "description": "",
            "dateCreated": "",
            "dateModified": "",
            "extensions": {
              "propertyName*": "anything"
            },
            "version": "",
            "host": "",
            "ipAddress": "",
            "userAgent": ""
          }
        }
      ],
      "members": [
        {
          "id": "",
          "type": "Entity",
          "name": "",
          "description": "",
          "dateCreated": "",
          "dateModified": "",
          "extensions": {
            "propertyName*": "anything"
          },
          "otherIdentifiers": [
            {
              "type": "AccountUserName",
              "identifier": "",
              "source": {
                "type": "SoftwareApplication",
                "name": "",
                "description": "",
                "dateCreated": "",
                "dateModified": "",
                "extensions": {
                  "propertyName*": "anything"
                },
                "version": "",
                "host": "",
                "ipAddress": "",
                "userAgent": ""
              }
            }
          ]
        }
      ],
      "subOrganizationOf": "[Circular Reference]"
    },
    "member": {
      "id": "",
      "type": "Person",
      "name": "",
      "description": "",
      "dateCreated": "",
      "dateModified": "",
      "extensions": {
        "propertyName*": "anything"
      },
      "otherIdentifiers": [
        {
          "type": "AccountUserName",
          "identifier": "",
          "source": {
            "type": "SoftwareApplication",
            "name": "",
            "description": "",
            "dateCreated": "",
            "dateModified": "",
            "extensions": {
              "propertyName*": "anything"
            },
            "version": "",
            "host": "",
            "ipAddress": "",
            "userAgent": ""
          }
        }
      ]
    },
    "roles": [
      "Administrator"
    ],
    "status": "Active"
  },
  "session": {
    "id": "",
    "type": "Session",
    "name": "",
    "description": "",
    "dateCreated": "",
    "dateModified": "",
    "extensions": {
      "propertyName*": "anything"
    },
    "otherIdentifiers": [
      {
        "type": "AccountUserName",
        "identifier": "",
        "source": {
          "type": "SoftwareApplication",
          "name": "",
          "description": "",
          "dateCreated": "",
          "dateModified": "",
          "extensions": {
            "propertyName*": "anything"
          },
          "version": "",
          "host": "",
          "ipAddress": "",
          "userAgent": ""
        }
      }
    ],
    "user": {
      "id": "",
      "type": "Person",
      "name": "",
      "description": "",
      "dateCreated": "",
      "dateModified": "",
      "extensions": {
        "propertyName*": "anything"
      },
      "otherIdentifiers": [
        {
          "type": "AccountUserName",
          "identifier": "",
          "source": {
            "type": "SoftwareApplication",
            "name": "",
            "description": "",
            "dateCreated": "",
            "dateModified": "",
            "extensions": {
              "propertyName*": "anything"
            },
            "version": "",
            "host": "",
            "ipAddress": "",
            "userAgent": ""
          }
        }
      ]
    },
    "client": {
      "id": "",
      "type": "SoftwareApplication",
      "name": "",
      "description": "",
      "dateCreated": "",
      "dateModified": "",
      "extensions": {
        "propertyName*": "anything"
      },
      "otherIdentifiers": [
        {
          "type": "AccountUserName",
          "identifier": "",
          "source": {
            "type": "SoftwareApplication",
            "name": "",
            "description": "",
            "dateCreated": "",
            "dateModified": "",
            "extensions": {
              "propertyName*": "anything"
            },
            "version": "",
            "host": "",
            "ipAddress": "",
            "userAgent": ""
          }
        }
      ],
      "version": "",
      "host": "",
      "ipAddress": "",
      "userAgent": ""
    },
    "startedAtTime": "",
    "endedAtTime": "",
    "duration": ""
  },
  "federatedSession": {
    "id": "",
    "type": "LtiSession",
    "name": "",
    "description": "",
    "dateCreated": "",
    "dateModified": "",
    "extensions": {
      "propertyName*": "anything"
    },
    "otherIdentifiers": [
      {
        "type": "AccountUserName",
        "identifier": "",
        "source": {
          "type": "SoftwareApplication",
          "name": "",
          "description": "",
          "dateCreated": "",
          "dateModified": "",
          "extensions": {
            "propertyName*": "anything"
          },
          "version": "",
          "host": "",
          "ipAddress": "",
          "userAgent": ""
        }
      }
    ],
    "user": {
      "id": "",
      "type": "Person",
      "name": "",
      "description": "",
      "dateCreated": "",
      "dateModified": "",
      "extensions": {
        "propertyName*": "anything"
      },
      "otherIdentifiers": [
        {
          "type": "AccountUserName",
          "identifier": "",
          "source": {
            "type": "SoftwareApplication",
            "name": "",
            "description": "",
            "dateCreated": "",
            "dateModified": "",
            "extensions": {
              "propertyName*": "anything"
            },
            "version": "",
            "host": "",
            "ipAddress": "",
            "userAgent": ""
          }
        }
      ]
    },
    "client": {
      "id": "",
      "type": "SoftwareApplication",
      "name": "",
      "description": "",
      "dateCreated": "",
      "dateModified": "",
      "extensions": {
        "propertyName*": "anything"
      },
      "otherIdentifiers": [
        {
          "type": "AccountUserName",
          "identifier": "",
          "source": {
            "type": "SoftwareApplication",
            "name": "",
            "description": "",
            "dateCreated": "",
            "dateModified": "",
            "extensions": {
              "propertyName*": "anything"
            },
            "version": "",
            "host": "",
            "ipAddress": "",
            "userAgent": ""
          }
        }
      ],
      "version": "",
      "host": "",
      "ipAddress": "",
      "userAgent": ""
    },
    "startedAtTime": "",
    "endedAtTime": "",
    "duration": "",
    "messageParameters": {
      "iss": "",
      "sub": "",
      "aud": "",
      "exp": 1,
      "iat": 1,
      "azp": "",
      "nonce": "",
      "name": "",
      "given_name": "",
      "family_name": "",
      "...": "[Additional Properties Truncated]"
    }
  },
  "extensions": {
    "propertyName*": "anything"
  }
}
```

### imsxCodeMinorFieldDType

- **Type:**`object`

Container for a single code minor status code

- **`imsx_codeMinorFieldName` (required)**

  `string`, default: `"TargetEndSystem"`

- **`imsx_codeMinorFieldValue` (required)**

  `string`, possible values: `"fullsuccess", "invalid_filter_field", "invalid_selection_field", "invaliddata", "unauthorisedrequest", "forbidden", "server_busy", "unknownobject", "internal_server_error"`

**Example:**

```json
{
  "imsx_codeMinorFieldName": "TargetEndSystem",
  "imsx_codeMinorFieldValue": "fullsuccess"
}
```

### imsxCodeMinorDType

- **Type:**`object`

Container for code minor status codes

- **`imsx_codeMinorField` (required)**

  `array`

  **Items:**

  - **`imsx_codeMinorFieldName` (required)**

    `string`, default: `"TargetEndSystem"`

  - **`imsx_codeMinorFieldValue` (required)**

    `string`, possible values: `"fullsuccess", "invalid_filter_field", "invalid_selection_field", "invaliddata", "unauthorisedrequest", "forbidden", "server_busy", "unknownobject", "internal_server_error"`

**Example:**

```json
{
  "imsx_codeMinorField": [
    {
      "imsx_codeMinorFieldName": "TargetEndSystem",
      "imsx_codeMinorFieldValue": "fullsuccess"
    }
  ]
}
```

### imsxStatusInfoDType

- **Type:**`object`

Container for status code information

- **`imsx_codeMajor` (required)**

  `string`, possible values: `"success", "processing", "failure", "unsupported"`

- **`imsx_severity` (required)**

  `string`, possible values: `"status", "warning", "error"`

- **`imsx_CodeMinor`**

  `object` — Container for code minor status codes

  - **`imsx_codeMinorField` (required)**

    `array`

    **Items:**

    - **`imsx_codeMinorFieldName` (required)**

      `string`, default: `"TargetEndSystem"`

    - **`imsx_codeMinorFieldValue` (required)**

      `string`, possible values: `"fullsuccess", "invalid_filter_field", "invalid_selection_field", "invaliddata", "unauthorisedrequest", "forbidden", "server_busy", "unknownobject", "internal_server_error"`

- **`imsx_description`**

  `string`

**Example:**

```json
{
  "imsx_codeMajor": "success",
  "imsx_severity": "status",
  "imsx_description": "",
  "imsx_CodeMinor": {
    "imsx_codeMinorField": [
      {
        "imsx_codeMinorFieldName": "TargetEndSystem",
        "imsx_codeMinorFieldValue": "fullsuccess"
      }
    ]
  }
}
```

### InsightSlice

- **Type:**`object`

* **`antiPatternDurationSeconds`**

  `number`

* **`qlt`**

  `number`

* **`sliceEndTimestampUTC`**

  `string`, format: `date-time`

* **`sliceStartTimestampUTC`**

  `string`, format: `date-time`

* **`totalDurationSeconds`**

  `number`

**Example:**

```json
{
  "sliceStartTimestampUTC": "",
  "sliceEndTimestampUTC": "",
  "totalDurationSeconds": 1,
  "antiPatternDurationSeconds": 1,
  "qlt": 1
}
```

### PaginatedInsightSliceOutput

- **Type:**`object`

* **`insights`**

  `array`

  **Items:**

  - **`antiPatternDurationSeconds`**

    `number`

  - **`qlt`**

    `number`

  - **`sliceEndTimestampUTC`**

    `string`, format: `date-time`

  - **`sliceStartTimestampUTC`**

    `string`, format: `date-time`

  - **`totalDurationSeconds`**

    `number`

* **`limit`**

  `number` — The maximum number of items returned in this response

* **`offset`**

  `number` — The number of items skipped from the beginning

* **`total`**

  `number` — The total number of available items

**Example:**

```json
{
  "insights": [
    {
      "sliceStartTimestampUTC": "",
      "sliceEndTimestampUTC": "",
      "totalDurationSeconds": 1,
      "antiPatternDurationSeconds": 1,
      "qlt": 1
    }
  ],
  "offset": 1,
  "limit": 1,
  "total": 1
}
```

### SessionInsight

- **Type:**`object`

* **`endTime`**

  `string`, format: `date-time` — End time of the insight period

* **`insightDescription`**

  `string` — Description of the session insight

* **`insightName`**

  `string` — Name of the session insight

* **`startTime`**

  `string`, format: `date-time` — Start time of the insight period

**Example:**

```json
{
  "insightName": "",
  "insightDescription": "",
  "startTime": "",
  "endTime": ""
}
```

### PaginatedSessionInsightOutput

- **Type:**`object`

* **`insights`**

  `array`

  **Items:**

  - **`endTime`**

    `string`, format: `date-time` — End time of the insight period

  - **`insightDescription`**

    `string` — Description of the session insight

  - **`insightName`**

    `string` — Name of the session insight

  - **`startTime`**

    `string`, format: `date-time` — Start time of the insight period

* **`limit`**

  `number` — The maximum number of items returned in this response

* **`offset`**

  `number` — The number of items skipped from the beginning

* **`total`**

  `number` — The total number of available items

**Example:**

```json
{
  "insights": [
    {
      "insightName": "",
      "insightDescription": "",
      "startTime": "",
      "endTime": ""
    }
  ],
  "offset": 1,
  "limit": 1,
  "total": 1
}
```

### SessionEventsSessionSummary

- **Type:**`object`

Summary information about a Caliper session and its primary actor and client

- **`durationInSeconds`**

  `number | null`

- **`edApp`**

  `object | null`

  - **`id`**

    `string`

  - **`name`**

    `string` — Tool name derived from LTI metadata or Caliper entity fallback

- **`endedAtTime`**

  `string`, format: `date-time`

- **`id`**

  `object` — An IRI can be either: 1. A URI (any valid URI scheme) 2. A URN in the format "urn:uuid:\<UUID>" where UUID is a version 4 UUID

- **`startedAtTime`**

  `string`, format: `date-time`

- **`user`**

  `object | null`

  - **`id`**

    `string`

  - **`name`**

    `string` — Display name derived from OneRoster user when available

**Example:**

```json
{
  "id": "",
  "startedAtTime": "",
  "endedAtTime": "",
  "durationInSeconds": null,
  "user": {
    "id": "",
    "name": ""
  },
  "edApp": {
    "id": "",
    "name": ""
  }
}
```

### PaginatedSessionEventsOutput

- **Type:**`object`

* **`events`**

  `array`

  **Items:**

  - **`@context` (required)**

    `string`, possible values: `"http://purl.imsglobal.org/ctx/caliper/v1p2"`

  - **`action` (required)**

    `string`, possible values: `"Abandoned", "Accepted", "Activated", "Added", "Archived", "Attached", "Bookmarked", "ChangedResolution", "ChangedSize", "ChangedSpeed", "ChangedVolume", "Classified", "ClosedPopout", "Commented", "Completed", "Copied", "Created", "Deactivated", "Declined", "Deleted", "Described", "DisabledClosedCaptioning", "Disliked", "Downloaded", "EnabledClosedCaptioning", "Ended", "EnteredFullScreen", "ExitedFullScreen", "ForwardedTo", "Graded", "Hid", "Highlighted", "Identified", "JumpedTo", "Launched", "Liked", "Linked", "LoggedIn", "LoggedOut", "MarkedAsRead", "MarkedAsUnread", "Modified", "Muted", "NavigatedTo", "OpenedPopout", "OptedIn", "OptedOut", "Paused", "Posted", "Printed", "Published", "Questioned", "Ranked", "Recommended", "Removed", "Reset", "Restarted", "Restored", "Resumed", "Retrieved", "Returned", "Reviewed", "Rewound", "Saved", "Searched", "Sent", "Shared", "Showed", "Skipped", "Started", "Submitted", "Subscribed", "Tagged", "TimedOut", "Unmuted", "Unpublished", "Unsubscribed", "Uploaded", "Used", "Viewed"`

  - **`actor` (required)**

    `object`

  - **`eventTime` (required)**

    `string`, format: `date-time`

  - **`id` (required)**

    `object` — An IRI can be either: 1. A URI (any valid URI scheme) 2. A URN in the format "urn:uuid:\<UUID>" where UUID is a version 4 UUID

  - **`object` (required)**

    `object`

  - **`type` (required)**

    `string`, possible values: `"Event", "AnnotationEvent", "AssessmentEvent", "AssessmentItemEvent", "AssignableEvent", "ForumEvent", "GradeEvent", "MediaEvent", "MessageEvent", "NavigationEvent", "ReadingEvent", "ResourceManagementEvent", "SearchEvent", "SessionEvent", "SurveyEvent", "ThreadEvent", "ToolLaunchEvent", "ToolUseEvent", "ViewEvent", "QuestionnaireEvent", "QuestionnaireItemEvent", "SurveyInvitationEvent", "AntiPatternEvent"`

  - **`edApp`**

    `object`

  - **`extensions`**

    `object`

  - **`federatedSession`**

    `object`

  - **`generated`**

    `object`

  - **`group`**

    `object`

  - **`membership`**

    `object`

  - **`profile`**

    `string`, possible values: `"GeneralProfile", "AnnotationProfile", "AssessmentProfile", "AssignableProfile", "FeedbackProfile", "ForumProfile", "GradingProfile", "MediaProfile", "ReadingProfile", "ResourceManagementProfile", "SearchProfile", "SessionProfile", "ToolLaunchProfile", "ToolUseProfile", "MonitoringProfile"`

  - **`referrer`**

    `object`

  - **`session`**

    `object`

  - **`target`**

    `object`

* **`limit`**

  `number` — The maximum number of items returned in this response

* **`nextCursor`**

  `string | null` — Cursor to fetch the next page of results. Null if no more pages.

* **`session`**

  `object` — Summary information about a Caliper session and its primary actor and client

  - **`durationInSeconds`**

    `number | null`

  - **`edApp`**

    `object | null`

    - **`id`**

      `string`

    - **`name`**

      `string` — Tool name derived from LTI metadata or Caliper entity fallback

  - **`endedAtTime`**

    `string`, format: `date-time`

  - **`id`**

    `object` — An IRI can be either: 1. A URI (any valid URI scheme) 2. A URN in the format "urn:uuid:\<UUID>" where UUID is a version 4 UUID

  - **`startedAtTime`**

    `string`, format: `date-time`

  - **`user`**

    `object | null`

    - **`id`**

      `string`

    - **`name`**

      `string` — Display name derived from OneRoster user when available

* **`total`**

  `number` — The total number of available items

**Example:**

```json
{
  "session": {
    "id": "",
    "startedAtTime": "",
    "endedAtTime": "",
    "durationInSeconds": null,
    "user": {
      "id": "",
      "name": ""
    },
    "edApp": {
      "id": "",
      "name": ""
    }
  },
  "events": [
    {
      "@context": "http://purl.imsglobal.org/ctx/caliper/v1p2",
      "id": "",
      "type": "Event",
      "profile": "GeneralProfile",
      "actor": {
        "id": "",
        "type": "Entity",
        "name": "",
        "description": "",
        "dateCreated": "",
        "dateModified": "",
        "extensions": {
          "propertyName*": "anything"
        },
        "otherIdentifiers": [
          {
            "type": "AccountUserName",
            "identifier": "",
            "source": {
              "type": "SoftwareApplication",
              "name": "",
              "description": "",
              "dateCreated": "",
              "dateModified": "",
              "extensions": {
                "propertyName*": "anything"
              },
              "version": "",
              "host": "",
              "ipAddress": "",
              "userAgent": ""
            }
          }
        ]
      },
      "action": "Abandoned",
      "object": {
        "id": "",
        "type": "Entity",
        "name": "",
        "description": "",
        "dateCreated": "",
        "dateModified": "",
        "extensions": {
          "propertyName*": "anything"
        },
        "otherIdentifiers": [
          {
            "type": "AccountUserName",
            "identifier": "",
            "source": {
              "type": "SoftwareApplication",
              "name": "",
              "description": "",
              "dateCreated": "",
              "dateModified": "",
              "extensions": {
                "propertyName*": "anything"
              },
              "version": "",
              "host": "",
              "ipAddress": "",
              "userAgent": ""
            }
          }
        ]
      },
      "eventTime": "",
      "edApp": {
        "id": "",
        "type": "SoftwareApplication",
        "name": "",
        "description": "",
        "dateCreated": "",
        "dateModified": "",
        "extensions": {
          "propertyName*": "anything"
        },
        "otherIdentifiers": [
          {
            "type": "AccountUserName",
            "identifier": "",
            "source": {
              "type": "SoftwareApplication",
              "name": "",
              "description": "",
              "dateCreated": "",
              "dateModified": "",
              "extensions": {
                "propertyName*": "anything"
              },
              "version": "",
              "host": "",
              "ipAddress": "",
              "userAgent": ""
            }
          }
        ],
        "version": "",
        "host": "",
        "ipAddress": "",
        "userAgent": ""
      },
      "generated": {
        "id": "",
        "type": "Entity",
        "name": "",
        "description": "",
        "dateCreated": "",
        "dateModified": "",
        "extensions": {
          "propertyName*": "anything"
        },
        "otherIdentifiers": [
          {
            "type": "AccountUserName",
            "identifier": "",
            "source": {
              "type": "SoftwareApplication",
              "name": "",
              "description": "",
              "dateCreated": "",
              "dateModified": "",
              "extensions": {
                "propertyName*": "anything"
              },
              "version": "",
              "host": "",
              "ipAddress": "",
              "userAgent": ""
            }
          }
        ]
      },
      "target": {
        "id": "",
        "type": "Entity",
        "name": "",
        "description": "",
        "dateCreated": "",
        "dateModified": "",
        "extensions": {
          "propertyName*": "anything"
        },
        "otherIdentifiers": [
          {
            "type": "AccountUserName",
            "identifier": "",
            "source": {
              "type": "SoftwareApplication",
              "name": "",
              "description": "",
              "dateCreated": "",
              "dateModified": "",
              "extensions": {
                "propertyName*": "anything"
              },
              "version": "",
              "host": "",
              "ipAddress": "",
              "userAgent": ""
            }
          }
        ]
      },
      "referrer": {
        "id": "",
        "type": "Entity",
        "name": "",
        "description": "",
        "dateCreated": "",
        "dateModified": "",
        "extensions": {
          "propertyName*": "anything"
        },
        "otherIdentifiers": [
          {
            "type": "AccountUserName",
            "identifier": "",
            "source": {
              "type": "SoftwareApplication",
              "name": "",
              "description": "",
              "dateCreated": "",
              "dateModified": "",
              "extensions": {
                "propertyName*": "anything"
              },
              "version": "",
              "host": "",
              "ipAddress": "",
              "userAgent": ""
            }
          }
        ]
      },
      "group": {
        "id": "",
        "type": "Organization",
        "name": "",
        "description": "",
        "dateCreated": "",
        "dateModified": "",
        "extensions": {
          "propertyName*": "anything"
        },
        "otherIdentifiers": [
          {
            "type": "AccountUserName",
            "identifier": "",
            "source": {
              "type": "SoftwareApplication",
              "name": "",
              "description": "",
              "dateCreated": "",
              "dateModified": "",
              "extensions": {
                "propertyName*": "anything"
              },
              "version": "",
              "host": "",
              "ipAddress": "",
              "userAgent": ""
            }
          }
        ],
        "members": [
          {
            "id": "",
            "type": "Entity",
            "name": "",
            "description": "",
            "dateCreated": "",
            "dateModified": "",
            "extensions": {
              "propertyName*": "anything"
            },
            "otherIdentifiers": [
              {
                "type": "AccountUserName",
                "identifier": "",
                "source": {
                  "type": "SoftwareApplication",
                  "name": "",
                  "description": "",
                  "dateCreated": "",
                  "dateModified": "",
                  "extensions": {
                    "propertyName*": "anything"
                  },
                  "version": "",
                  "host": "",
                  "ipAddress": "",
                  "userAgent": ""
                }
              }
            ]
          }
        ],
        "subOrganizationOf": "[Circular Reference]"
      },
      "membership": {
        "id": "",
        "type": "Membership",
        "name": "",
        "description": "",
        "dateCreated": "",
        "dateModified": "",
        "extensions": {
          "propertyName*": "anything"
        },
        "otherIdentifiers": [
          {
            "type": "AccountUserName",
            "identifier": "",
            "source": {
              "type": "SoftwareApplication",
              "name": "",
              "description": "",
              "dateCreated": "",
              "dateModified": "",
              "extensions": {
                "propertyName*": "anything"
              },
              "version": "",
              "host": "",
              "ipAddress": "",
              "userAgent": ""
            }
          }
        ],
        "organization": {
          "id": "",
          "type": "Organization",
          "name": "",
          "description": "",
          "dateCreated": "",
          "dateModified": "",
          "extensions": {
            "propertyName*": "anything"
          },
          "otherIdentifiers": [
            {
              "type": "AccountUserName",
              "identifier": "",
              "source": {
                "type": "SoftwareApplication",
                "name": "",
                "description": "",
                "dateCreated": "",
                "dateModified": "",
                "extensions": {
                  "propertyName*": "anything"
                },
                "version": "",
                "host": "",
                "ipAddress": "",
                "userAgent": ""
              }
            }
          ],
          "members": [
            {
              "id": "",
              "type": "Entity",
              "name": "",
              "description": "",
              "dateCreated": "",
              "dateModified": "",
              "extensions": {
                "propertyName*": "anything"
              },
              "otherIdentifiers": [
                {
                  "type": "AccountUserName",
                  "identifier": "",
                  "source": {
                    "type": "SoftwareApplication",
                    "name": "",
                    "description": "",
                    "dateCreated": "",
                    "dateModified": "",
                    "extensions": {
                      "propertyName*": "anything"
                    },
                    "version": "",
                    "host": "",
                    "ipAddress": "",
                    "userAgent": ""
                  }
                }
              ]
            }
          ],
          "subOrganizationOf": "[Circular Reference]"
        },
        "member": {
          "id": "",
          "type": "Person",
          "name": "",
          "description": "",
          "dateCreated": "",
          "dateModified": "",
          "extensions": {
            "propertyName*": "anything"
          },
          "otherIdentifiers": [
            {
              "type": "AccountUserName",
              "identifier": "",
              "source": {
                "type": "SoftwareApplication",
                "name": "",
                "description": "",
                "dateCreated": "",
                "dateModified": "",
                "extensions": {
                  "propertyName*": "anything"
                },
                "version": "",
                "host": "",
                "ipAddress": "",
                "userAgent": ""
              }
            }
          ]
        },
        "roles": [
          "Administrator"
        ],
        "status": "Active"
      },
      "session": {
        "id": "",
        "type": "Session",
        "name": "",
        "description": "",
        "dateCreated": "",
        "dateModified": "",
        "extensions": {
          "propertyName*": "anything"
        },
        "otherIdentifiers": [
          {
            "type": "AccountUserName",
            "identifier": "",
            "source": {
              "type": "SoftwareApplication",
              "name": "",
              "description": "",
              "dateCreated": "",
              "dateModified": "",
              "extensions": {
                "propertyName*": "anything"
              },
              "version": "",
              "host": "",
              "ipAddress": "",
              "userAgent": ""
            }
          }
        ],
        "user": {
          "id": "",
          "type": "Person",
          "name": "",
          "description": "",
          "dateCreated": "",
          "dateModified": "",
          "extensions": {
            "propertyName*": "anything"
          },
          "otherIdentifiers": [
            {
              "type": "AccountUserName",
              "identifier": "",
              "source": {
                "type": "SoftwareApplication",
                "name": "",
                "description": "",
                "dateCreated": "",
                "dateModified": "",
                "extensions": {
                  "propertyName*": "anything"
                },
                "version": "",
                "host": "",
                "ipAddress": "",
                "userAgent": ""
              }
            }
          ]
        },
        "client": {
          "id": "",
          "type": "SoftwareApplication",
          "name": "",
          "description": "",
          "dateCreated": "",
          "dateModified": "",
          "extensions": {
            "propertyName*": "anything"
          },
          "otherIdentifiers": [
            {
              "type": "AccountUserName",
              "identifier": "",
              "source": {
                "type": "SoftwareApplication",
                "name": "",
                "description": "",
                "dateCreated": "",
                "dateModified": "",
                "extensions": {
                  "propertyName*": "anything"
                },
                "version": "",
                "host": "",
                "ipAddress": "",
                "userAgent": ""
              }
            }
          ],
          "version": "",
          "host": "",
          "ipAddress": "",
          "userAgent": ""
        },
        "startedAtTime": "",
        "endedAtTime": "",
        "duration": ""
      },
      "federatedSession": {
        "id": "",
        "type": "LtiSession",
        "name": "",
        "description": "",
        "dateCreated": "",
        "dateModified": "",
        "extensions": {
          "propertyName*": "anything"
        },
        "otherIdentifiers": [
          {
            "type": "AccountUserName",
            "identifier": "",
            "source": {
              "type": "SoftwareApplication",
              "name": "",
              "description": "",
              "dateCreated": "",
              "dateModified": "",
              "extensions": {
                "propertyName*": "anything"
              },
              "version": "",
              "host": "",
              "ipAddress": "",
              "userAgent": ""
            }
          }
        ],
        "user": {
          "id": "",
          "type": "Person",
          "name": "",
          "description": "",
          "dateCreated": "",
          "dateModified": "",
          "extensions": {
            "propertyName*": "anything"
          },
          "otherIdentifiers": [
            {
              "type": "AccountUserName",
              "identifier": "",
              "source": {
                "type": "SoftwareApplication",
                "name": "",
                "description": "",
                "dateCreated": "",
                "dateModified": "",
                "extensions": {
                  "propertyName*": "anything"
                },
                "version": "",
                "host": "",
                "ipAddress": "",
                "userAgent": ""
              }
            }
          ]
        },
        "client": {
          "id": "",
          "type": "SoftwareApplication",
          "name": "",
          "description": "",
          "dateCreated": "",
          "dateModified": "",
          "extensions": {
            "propertyName*": "anything"
          },
          "otherIdentifiers": [
            {
              "type": "AccountUserName",
              "identifier": "",
              "source": {
                "type": "SoftwareApplication",
                "name": "",
                "description": "",
                "dateCreated": "",
                "dateModified": "",
                "extensions": {
                  "propertyName*": "anything"
                },
                "version": "",
                "host": "",
                "ipAddress": "",
                "userAgent": ""
              }
            }
          ],
          "version": "",
          "host": "",
          "ipAddress": "",
          "userAgent": ""
        },
        "startedAtTime": "",
        "endedAtTime": "",
        "duration": "",
        "messageParameters": {
          "iss": "",
          "sub": "",
          "aud": "",
          "exp": 1,
          "iat": 1,
          "azp": "",
          "nonce": "",
          "name": "",
          "given_name": "",
          "family_name": "",
          "...": "[Additional Properties Truncated]"
        }
      },
      "extensions": {
        "propertyName*": "anything"
      }
    }
  ],
  "limit": 1,
  "total": 1,
  "nextCursor": null
}
```

### EntityStatus

- **Type:**`string`

Status of an entity in the system

**Example:**

### imsxCodeMinorFieldDType1

- **Type:**`object`

This is the container for a single code minor status code.

- **`imsx_codeMinorFieldName` (required)**

  `string`, default: `"TargetEndSystem"` — This should contain the identity of the system that has produced the code minor status code report. In most cases this will be the target service provider denoted as 'TargetEndSystem'.

- **`imsx_codeMinorFieldValue` (required)**

  `string`, possible values: `"fullsuccess", "invalid_filter_field", "invalid_selection_field", "invaliddata", "unauthorisedrequest", "forbidden", "server_busy", "unknownobject", "internal_server_error"` — The code minor status code (this is a value from the corresponding enumerated vocabulary).

**Example:**

```json
{
  "imsx_codeMinorFieldName": "TargetEndSystem",
  "imsx_codeMinorFieldValue": "fullsuccess"
}
```

### imsxCodeMinorDType1

- **Type:**`object`

This is the container for the set of code minor status codes reported in the responses from the Service Provider.

- **`imsx_codeMinorField` (required)**

  `array` — Each reported code minor status code.

  **Items:**

  - **`imsx_codeMinorFieldName` (required)**

    `string`, default: `"TargetEndSystem"` — This should contain the identity of the system that has produced the code minor status code report. In most cases this will be the target service provider denoted as 'TargetEndSystem'.

  - **`imsx_codeMinorFieldValue` (required)**

    `string`, possible values: `"fullsuccess", "invalid_filter_field", "invalid_selection_field", "invaliddata", "unauthorisedrequest", "forbidden", "server_busy", "unknownobject", "internal_server_error"` — The code minor status code (this is a value from the corresponding enumerated vocabulary).

**Example:**

```json
{
  "imsx_codeMinorField": [
    {
      "imsx_codeMinorFieldName": "TargetEndSystem",
      "imsx_codeMinorFieldValue": "fullsuccess"
    }
  ]
}
```

### imsxStatusInfoDType1

- **Type:**`object`

This is the container for the status code and associated information returned within the HTTP messages received from the Service Provider.

- **`imsx_codeMajor` (required)**

  `string`, possible values: `"success", "processing", "failure", "unsupported"` — The code major value (from the corresponding enumerated vocabulary).

- **`imsx_severity` (required)**

  `string`, possible values: `"status", "warning", "error"` — The severity value (from the corresponding enumerated vocabulary).

- **`imsx_CodeMinor`**

  `object` — This is the container for the set of code minor status codes reported in the responses from the Service Provider.

  - **`imsx_codeMinorField` (required)**

    `array` — Each reported code minor status code.

    **Items:**

    - **`imsx_codeMinorFieldName` (required)**

      `string`, default: `"TargetEndSystem"` — This should contain the identity of the system that has produced the code minor status code report. In most cases this will be the target service provider denoted as 'TargetEndSystem'.

    - **`imsx_codeMinorFieldValue` (required)**

      `string`, possible values: `"fullsuccess", "invalid_filter_field", "invalid_selection_field", "invaliddata", "unauthorisedrequest", "forbidden", "server_busy", "unknownobject", "internal_server_error"` — The code minor status code (this is a value from the corresponding enumerated vocabulary).

- **`imsx_description`**

  `string` — A human readable description supplied by the entity creating the status code information.

**Example:**

```json
{
  "imsx_codeMajor": "success",
  "imsx_severity": "status",
  "imsx_description": "",
  "imsx_CodeMinor": {
    "imsx_codeMinorField": [
      {
        "imsx_codeMinorFieldName": "TargetEndSystem",
        "imsx_codeMinorFieldValue": "fullsuccess"
      }
    ]
  }
}
```

### JWK

- **Type:**`object`

JSON Web Key (RFC 7517)

- **`alg` (required)**

  `string` — Algorithm

- **`kid` (required)**

  `string` — Key ID

- **`kty` (required)**

  `string` — Key Type

- **`e`**

  `string` — RSA Exponent (base64url)

- **`n`**

  `string` — RSA Modulus (base64url)

- **`use`**

  `string` — Public Key Use

**Example:**

```json
{
  "kty": "RSA",
  "use": "sig",
  "kid": "rsa-key-2024",
  "alg": "RS256",
  "n": "",
  "e": "AQAB"
}
```

### JWKS

- **Type:**`object`

JSON Web Key Set (RFC 7517)

- **`keys` (required)**

  `array` — Array of JSON Web Keys

  **Items:**

  - **`alg` (required)**

    `string` — Algorithm

  - **`kid` (required)**

    `string` — Key ID

  - **`kty` (required)**

    `string` — Key Type

  - **`e`**

    `string` — RSA Exponent (base64url)

  - **`n`**

    `string` — RSA Modulus (base64url)

  - **`use`**

    `string` — Public Key Use

**Example:**

```json
{
  "keys": [
    {
      "kty": "RSA",
      "use": "sig",
      "kid": "rsa-key-2024",
      "alg": "RS256",
      "n": "",
      "e": "AQAB"
    }
  ]
}
```

### imsxCodeMinorFieldDType2

- **Type:**`object`

This is the container for a single code minor status code.

- **`imsx_codeMinorFieldName` (required)**

  `string`, default: `"TargetEndSystem"` — This should contain the identity of the system that has produced the code minor status code report. In most cases this will be the target service provider denoted as 'TargetEndSystem'.

- **`imsx_codeMinorFieldValue` (required)**

  `string`, possible values: `"fullsuccess", "invalid_filter_field", "invalid_selection_field", "invaliddata", "unauthorisedrequest", "forbidden", "server_busy", "unknownobject", "internal_server_error"` — The code minor status code (this is a value from the corresponding enumerated vocabulary).

**Example:**

```json
{
  "imsx_codeMinorFieldName": "TargetEndSystem",
  "imsx_codeMinorFieldValue": "fullsuccess"
}
```

### imsxCodeMinorDType2

- **Type:**`object`

This is the container for the set of code minor status codes reported in the responses from the Service Provider.

- **`imsx_codeMinorField` (required)**

  `array` — Each reported code minor status code.

  **Items:**

  - **`imsx_codeMinorFieldName` (required)**

    `string`, default: `"TargetEndSystem"` — This should contain the identity of the system that has produced the code minor status code report. In most cases this will be the target service provider denoted as 'TargetEndSystem'.

  - **`imsx_codeMinorFieldValue` (required)**

    `string`, possible values: `"fullsuccess", "invalid_filter_field", "invalid_selection_field", "invaliddata", "unauthorisedrequest", "forbidden", "server_busy", "unknownobject", "internal_server_error"` — The code minor status code (this is a value from the corresponding enumerated vocabulary).

**Example:**

```json
{
  "imsx_codeMinorField": [
    {
      "imsx_codeMinorFieldName": "TargetEndSystem",
      "imsx_codeMinorFieldValue": "fullsuccess"
    }
  ]
}
```

### imsxStatusInfoDType2

- **Type:**`object`

This is the container for the status code and associated information returned within the HTTP messages received from the Service Provider. For the OneRoster Rostering service this object will only be returned to provide information about a failed request i.e. it will NOT be in the payload for a successful request.

- **`imsx_codeMajor` (required)**

  `string`, possible values: `"success", "processing", "failure", "unsupported"` — The code major value (from the corresponding enumerated vocabulary).

- **`imsx_severity` (required)**

  `string`, possible values: `"status", "warning", "error"` — The severity value (from the corresponding enumerated vocabulary).

- **`imsx_CodeMinor`**

  `object` — This is the container for the set of code minor status codes reported in the responses from the Service Provider.

  - **`imsx_codeMinorField` (required)**

    `array` — Each reported code minor status code.

    **Items:**

    - **`imsx_codeMinorFieldName` (required)**

      `string`, default: `"TargetEndSystem"` — This should contain the identity of the system that has produced the code minor status code report. In most cases this will be the target service provider denoted as 'TargetEndSystem'.

    - **`imsx_codeMinorFieldValue` (required)**

      `string`, possible values: `"fullsuccess", "invalid_filter_field", "invalid_selection_field", "invaliddata", "unauthorisedrequest", "forbidden", "server_busy", "unknownobject", "internal_server_error"` — The code minor status code (this is a value from the corresponding enumerated vocabulary).

- **`imsx_description`**

  `string` — A human readable description supplied by the entity creating the status code information.

**Example:**

```json
{
  "imsx_codeMajor": "success",
  "imsx_severity": "status",
  "imsx_description": "",
  "imsx_CodeMinor": {
    "imsx_codeMinorField": [
      {
        "imsx_codeMinorFieldName": "TargetEndSystem",
        "imsx_codeMinorFieldValue": "fullsuccess"
      }
    ]
  }
}
```

### OneRosterGUIDRef

- **Type:**`object`

A reference to another OneRoster entity

- **`href` (required)**

  `string`, format: `uri` — URI reference to the entity

- **`sourcedId` (required)**

  `string` — Unique identifier of the referenced entity

- **`type` (required)**

  `string`, possible values: `"academicSession", "category", "class", "course", "demographics", "enrollment", "gradingPeriod", "org", "resource", "user"` — Type of the referenced entity

**Example:**

```json
{
  "href": "",
  "sourcedId": "",
  "type": "academicSession"
}
```

### OneRosterStudentInput

- **Type:**`object`

* **`student` (required)**

  `object`

  - **`enabledUser` (required)**

    `string`, possible values: `"true", "false"`

  - **`familyName` (required)**

    `string`

  - **`givenName` (required)**

    `string`

  - **`grades` (required)**

    `array`

    **Items:**

    `string`

  - **`primaryOrg` (required)**

    `object`

    - **`sourcedId` (required)**

      `string`

    - **`type` (required)**

      `string`, possible values: `"org"`

    - **`href`**

      `string`

  - **`sourcedId` (required)**

    `string`

  - **`status` (required)**

    `string`, possible values: `"active", "tobedeleted", "inactive"`

  - **`username` (required)**

    `string | null`

  - **`demographics`**

    `object`

    - **`birthDate`**

      `string | null`, format: `date`

  - **`email`**

    `string`

  - **`identifier`**

    `string | null`

  - **`metadata`**

    `object | null`

  - **`middleName`**

    `string | null`

  - **`password`**

    `string | null`

  - **`phone`**

    `string | null`

  - **`preferredFirstName`**

    `string | null`

  - **`preferredLastName`**

    `string | null`

  - **`preferredMiddleName`**

    `string | null`

  - **`pronouns`**

    `string | null`

  - **`sms`**

    `string | null`

  - **`userMasterIdentifier`**

    `string | null`

**Example:**

```json
{
  "student": {
    "sourcedId": "",
    "status": "active",
    "metadata": null,
    "userMasterIdentifier": null,
    "username": null,
    "enabledUser": "true",
    "givenName": "",
    "familyName": "",
    "middleName": null,
    "preferredFirstName": null,
    "preferredMiddleName": null,
    "preferredLastName": null,
    "pronouns": null,
    "demographics": {
      "birthDate": null
    },
    "primaryOrg": {
      "href": "",
      "sourcedId": "",
      "type": "org"
    },
    "identifier": null,
    "email": "",
    "sms": null,
    "phone": null,
    "grades": [
      ""
    ],
    "password": null
  }
}
```

### OneRosterStudentAgentInput

- **Type:**`object`

Input for creating or updating a student agent relationship

- **`relationshipType` (required)**

  `string` — Type of agent relationship (e.g., parent, guardian, relative)

- **`user` (required)**

  `object` — A reference to another OneRoster entity

  - **`href` (required)**

    `string`, format: `uri` — URI reference to the entity

  - **`sourcedId` (required)**

    `string` — Unique identifier of the referenced entity

  - **`type` (required)**

    `string`, possible values: `"academicSession", "category", "class", "course", "demographics", "enrollment", "gradingPeriod", "org", "resource", "user"` — Type of the referenced entity

**Example:**

```json
{
  "user": {
    "href": "",
    "sourcedId": "",
    "type": "academicSession"
  },
  "relationshipType": ""
}
```

### OneRosterUserRoleOutput

- **Type:**`object`

Role information associated with a user

- **`org` (required)**

  `object` — Organization associated with the role

  - **`href` (required)**

    `string`, format: `uri` — URI reference to the entity

  - **`sourcedId` (required)**

    `string` — Unique identifier of the referenced entity

  - **`type` (required)**

    `string`, possible values: `"academicSession", "category", "class", "course", "demographics", "enrollment", "gradingPeriod", "org", "resource", "user"` — Type of the referenced entity

- **`role` (required)**

  `string`, possible values: `"aide", "counselor", "districtAdministrator", "guardian", "parent", "principal", "proctor", "relative", "siteAdministrator", "student", "systemAdministrator", "teacher"` — Role value

- **`roleType` (required)**

  `string`, possible values: `"primary", "secondary"` — Type of role (primary/secondary)

- **`beginDate`**

  `string | null` — Date when the role assignment begins

- **`endDate`**

  `string | null` — Date when the role assignment ends

- **`userProfile`**

  `string | null` — User profile ID associated with this role

**Example:**

```json
{
  "roleType": "primary",
  "role": "aide",
  "org": {
    "href": "",
    "sourcedId": "",
    "type": "academicSession"
  },
  "userProfile": null,
  "beginDate": null,
  "endDate": null
}
```

### OneRosterUserProfileOutput

- **Type:**`object`

Profile information associated with a user in a specific role

- **`profileId` (required)**

  `string`, format: `uri` — Unique identifier for the profile

- **`profileType` (required)**

  `string` — Type of profile (e.g., learning platform, assessment system)

- **`vendorId` (required)**

  `string` — Identifier of the vendor providing this profile

- **`applicationId`**

  `string | null` — Identifier of the specific application this profile is for

- **`credentials`**

  `array` — List of credentials associated with this profile

  **Items:**

  - **`identity`**

    `string` — The identity for the profile

  - **`password`**

    `string` — The password for the profile

  - **`username`**

    `string` — The username for the profile

- **`description`**

  `string | null` — Human-readable description of this profile

**Example:**

```json
{
  "profileId": "",
  "profileType": "",
  "vendorId": "",
  "applicationId": null,
  "description": null,
  "credentials": [
    {
      "username": "",
      "password": "",
      "identity": ""
    }
  ]
}
```

### OneRosterCredentialOutput

- **Type:**`object`

The container for the information about a User Profile that will provide the user with access to some system, application, tool, etc.

- **`identity`**

  `string` — The identity for the profile

- **`password`**

  `string` — The password for the profile

- **`username`**

  `string` — The username for the profile

**Example:**

```json
{
  "username": "",
  "password": "",
  "identity": ""
}
```

### OneRosterUserOutput

- **Type:**`object`

User information in the OneRoster format

- **`agents` (required)**

  `array` — Array of agents (parents, guardians) associated with the user

  **Items:**

  - **`href` (required)**

    `string`, format: `uri` — URI reference to the entity

  - **`sourcedId` (required)**

    `string` — Unique identifier of the referenced entity

  - **`type` (required)**

    `string`, possible values: `"academicSession", "category", "class", "course", "demographics", "enrollment", "gradingPeriod", "org", "resource", "user"` — Type of the referenced entity

- **`dateLastModified` (required)**

  `string`, format: `date-time` — Timestamp of when the user was last modified

- **`email` (required)**

  `string` — User's email address

- **`enabledUser` (required)**

  `string`, possible values: `"true", "false"` — This is used to determine whether or not the record is active in the local system.

- **`familyName` (required)**

  `string` — The family name. Also, known as the last name.

- **`givenName` (required)**

  `string` — The given name. Also, known as the first name.

- **`grades` (required)**

  `array` — Array of grade levels associated with the user

  **Items:**

  `string`

- **`resources` (required)**

  `array` — The identifiers (GUIDs) for the set of resources that are to be made available to the user.

  **Items:**

  - **`href` (required)**

    `string`, format: `uri` — URI reference to the entity

  - **`sourcedId` (required)**

    `string` — Unique identifier of the referenced entity

  - **`type` (required)**

    `string`, possible values: `"academicSession", "category", "class", "course", "demographics", "enrollment", "gradingPeriod", "org", "resource", "user"` — Type of the referenced entity

- **`roles` (required)**

  `array` — Array of roles assigned to the user

  **Items:**

  - **`org` (required)**

    `object` — Organization associated with the role

    - **`href` (required)**

      `string`, format: `uri` — URI reference to the entity

    - **`sourcedId` (required)**

      `string` — Unique identifier of the referenced entity

    - **`type` (required)**

      `string`, possible values: `"academicSession", "category", "class", "course", "demographics", "enrollment", "gradingPeriod", "org", "resource", "user"` — Type of the referenced entity

  - **`role` (required)**

    `string`, possible values: `"aide", "counselor", "districtAdministrator", "guardian", "parent", "principal", "proctor", "relative", "siteAdministrator", "student", "systemAdministrator", "teacher"` — Role value

  - **`roleType` (required)**

    `string`, possible values: `"primary", "secondary"` — Type of role (primary/secondary)

  - **`beginDate`**

    `string | null` — Date when the role assignment begins

  - **`endDate`**

    `string | null` — Date when the role assignment ends

  - **`userProfile`**

    `string | null` — User profile ID associated with this role

- **`sourcedId` (required)**

  `string` — Unique identifier for the user

- **`status` (required)**

  `string`, possible values: `"active", "tobedeleted", "inactive"` — Status of an entity in the system

- **`userIds` (required)**

  `array` — The set of external user identifiers that should be used for this user.

  **Items:**

  `string`

- **`userProfiles` (required)**

  `array` — Array of profiles associated with the user in different systems

  **Items:**

  - **`profileId` (required)**

    `string`, format: `uri` — Unique identifier for the profile

  - **`profileType` (required)**

    `string` — Type of profile (e.g., learning platform, assessment system)

  - **`vendorId` (required)**

    `string` — Identifier of the vendor providing this profile

  - **`applicationId`**

    `string | null` — Identifier of the specific application this profile is for

  - **`credentials`**

    `array` — List of credentials associated with this profile

    **Items:**

    - **`identity`**

      `string` — The identity for the profile

    - **`password`**

      `string` — The password for the profile

    - **`username`**

      `string` — The username for the profile

  - **`description`**

    `string | null` — Human-readable description of this profile

- **`identifier`**

  `string | null` — Additional identifier for the user

- **`metadata`**

  `object | null` — Additional metadata associated with the user

- **`middleName`**

  `string | null` — The set of middle names. If more than one middle name is needed separate using a space.

- **`password`**

  `string | null` — User's password (hashed)

- **`phone`**

  `string | null` — User's primary phone number

- **`preferredFirstName`**

  `string | null` — User's preferred first name if different from given name

- **`preferredLastName`**

  `string | null` — User's preferred last name if different from family name

- **`preferredMiddleName`**

  `string | null` — User's preferred middle name if different from middle name

- **`primaryOrg`**

  `object` — ID of the user's primary organization

  - **`href` (required)**

    `string`, format: `uri` — URI reference to the entity

  - **`sourcedId` (required)**

    `string` — Unique identifier of the referenced entity

  - **`type` (required)**

    `string`, possible values: `"academicSession", "category", "class", "course", "demographics", "enrollment", "gradingPeriod", "org", "resource", "user"` — Type of the referenced entity

- **`sms`**

  `string | null` — User's SMS contact number

- **`userMasterIdentifier`**

  `string | null` — The master unique identifier for this user. This is NOT the same as the user's interoperability 'sourcedId'.

- **`username`**

  `string | null` — The user name assigned to the user.

**Example:**

```json
{
  "sourcedId": "",
  "status": "active",
  "dateLastModified": "",
  "metadata": null,
  "userMasterIdentifier": null,
  "username": null,
  "userIds": [
    ""
  ],
  "enabledUser": "true",
  "givenName": "",
  "familyName": "",
  "middleName": null,
  "preferredFirstName": null,
  "preferredMiddleName": null,
  "preferredLastName": null,
  "roles": [
    {
      "roleType": "primary",
      "role": "aide",
      "org": {
        "href": "",
        "sourcedId": "",
        "type": "academicSession"
      },
      "userProfile": null,
      "beginDate": null,
      "endDate": null
    }
  ],
  "userProfiles": [
    {
      "profileId": "",
      "profileType": "",
      "vendorId": "",
      "applicationId": null,
      "description": null,
      "credentials": [
        {
          "username": "",
          "password": "",
          "identity": ""
        }
      ]
    }
  ],
  "primaryOrg": {
    "href": "",
    "sourcedId": "",
    "type": "academicSession"
  },
  "identifier": null,
  "email": "",
  "sms": null,
  "phone": null,
  "agents": [
    {
      "href": "",
      "sourcedId": "",
      "type": "academicSession"
    }
  ],
  "grades": [
    ""
  ],
  "password": null,
  "resources": [
    {
      "href": "",
      "sourcedId": "",
      "type": "academicSession"
    }
  ]
}
```

### PaginatedOneRosterUserOutput

- **Type:**`object`

Paginated list of OneRoster users

- **`limit` (required)**

  `integer` — Maximum number of items returned

- **`offset` (required)**

  `integer` — Number of items skipped in the result set

- **`total` (required)**

  `integer` — Total number of items available

- **`users` (required)**

  `array` — Array of user objects

  **Items:**

  - **`agents` (required)**

    `array` — Array of agents (parents, guardians) associated with the user

    **Items:**

    - **`href` (required)**

      `string`, format: `uri` — URI reference to the entity

    - **`sourcedId` (required)**

      `string` — Unique identifier of the referenced entity

    - **`type` (required)**

      `string`, possible values: `"academicSession", "category", "class", "course", "demographics", "enrollment", "gradingPeriod", "org", "resource", "user"` — Type of the referenced entity

  - **`dateLastModified` (required)**

    `string`, format: `date-time` — Timestamp of when the user was last modified

  - **`email` (required)**

    `string` — User's email address

  - **`enabledUser` (required)**

    `string`, possible values: `"true", "false"` — This is used to determine whether or not the record is active in the local system.

  - **`familyName` (required)**

    `string` — The family name. Also, known as the last name.

  - **`givenName` (required)**

    `string` — The given name. Also, known as the first name.

  - **`grades` (required)**

    `array` — Array of grade levels associated with the user

    **Items:**

    `string`

  - **`resources` (required)**

    `array` — The identifiers (GUIDs) for the set of resources that are to be made available to the user.

    **Items:**

    - **`href` (required)**

      `string`, format: `uri` — URI reference to the entity

    - **`sourcedId` (required)**

      `string` — Unique identifier of the referenced entity

    - **`type` (required)**

      `string`, possible values: `"academicSession", "category", "class", "course", "demographics", "enrollment", "gradingPeriod", "org", "resource", "user"` — Type of the referenced entity

  - **`roles` (required)**

    `array` — Array of roles assigned to the user

    **Items:**

    - **`org` (required)**

      `object` — Organization associated with the role

      - **`href` (required)**

        `string`, format: `uri` — URI reference to the entity

      - **`sourcedId` (required)**

        `string` — Unique identifier of the referenced entity

      - **`type` (required)**

        `string`, possible values: `"academicSession", "category", "class", "course", "demographics", "enrollment", "gradingPeriod", "org", "resource", "user"` — Type of the referenced entity

    - **`role` (required)**

      `string`, possible values: `"aide", "counselor", "districtAdministrator", "guardian", "parent", "principal", "proctor", "relative", "siteAdministrator", "student", "systemAdministrator", "teacher"` — Role value

    - **`roleType` (required)**

      `string`, possible values: `"primary", "secondary"` — Type of role (primary/secondary)

    - **`beginDate`**

      `string | null` — Date when the role assignment begins

    - **`endDate`**

      `string | null` — Date when the role assignment ends

    - **`userProfile`**

      `string | null` — User profile ID associated with this role

  - **`sourcedId` (required)**

    `string` — Unique identifier for the user

  - **`status` (required)**

    `string`, possible values: `"active", "tobedeleted", "inactive"` — Status of an entity in the system

  - **`userIds` (required)**

    `array` — The set of external user identifiers that should be used for this user.

    **Items:**

    `string`

  - **`userProfiles` (required)**

    `array` — Array of profiles associated with the user in different systems

    **Items:**

    - **`profileId` (required)**

      `string`, format: `uri` — Unique identifier for the profile

    - **`profileType` (required)**

      `string` — Type of profile (e.g., learning platform, assessment system)

    - **`vendorId` (required)**

      `string` — Identifier of the vendor providing this profile

    - **`applicationId`**

      `string | null` — Identifier of the specific application this profile is for

    - **`credentials`**

      `array` — List of credentials associated with this profile

      **Items:**

      - **`identity`**

        `string` — The identity for the profile

      - **`password`**

        `string` — The password for the profile

      - **`username`**

        `string` — The username for the profile

    - **`description`**

      `string | null` — Human-readable description of this profile

  - **`identifier`**

    `string | null` — Additional identifier for the user

  - **`metadata`**

    `object | null` — Additional metadata associated with the user

  - **`middleName`**

    `string | null` — The set of middle names. If more than one middle name is needed separate using a space.

  - **`password`**

    `string | null` — User's password (hashed)

  - **`phone`**

    `string | null` — User's primary phone number

  - **`preferredFirstName`**

    `string | null` — User's preferred first name if different from given name

  - **`preferredLastName`**

    `string | null` — User's preferred last name if different from family name

  - **`preferredMiddleName`**

    `string | null` — User's preferred middle name if different from middle name

  - **`primaryOrg`**

    `object` — ID of the user's primary organization

    - **`href` (required)**

      `string`, format: `uri` — URI reference to the entity

    - **`sourcedId` (required)**

      `string` — Unique identifier of the referenced entity

    - **`type` (required)**

      `string`, possible values: `"academicSession", "category", "class", "course", "demographics", "enrollment", "gradingPeriod", "org", "resource", "user"` — Type of the referenced entity

  - **`sms`**

    `string | null` — User's SMS contact number

  - **`userMasterIdentifier`**

    `string | null` — The master unique identifier for this user. This is NOT the same as the user's interoperability 'sourcedId'.

  - **`username`**

    `string | null` — The user name assigned to the user.

**Example:**

```json
{
  "users": [
    {
      "sourcedId": "",
      "status": "active",
      "dateLastModified": "",
      "metadata": null,
      "userMasterIdentifier": null,
      "username": null,
      "userIds": [
        ""
      ],
      "enabledUser": "true",
      "givenName": "",
      "familyName": "",
      "middleName": null,
      "preferredFirstName": null,
      "preferredMiddleName": null,
      "preferredLastName": null,
      "roles": [
        {
          "roleType": "primary",
          "role": "aide",
          "org": {
            "href": "",
            "sourcedId": "",
            "type": "academicSession"
          },
          "userProfile": null,
          "beginDate": null,
          "endDate": null
        }
      ],
      "userProfiles": [
        {
          "profileId": "",
          "profileType": "",
          "vendorId": "",
          "applicationId": null,
          "description": null,
          "credentials": [
            {
              "username": "",
              "password": "",
              "identity": ""
            }
          ]
        }
      ],
      "primaryOrg": {
        "href": "",
        "sourcedId": "",
        "type": "academicSession"
      },
      "identifier": null,
      "email": "",
      "sms": null,
      "phone": null,
      "agents": [
        {
          "href": "",
          "sourcedId": "",
          "type": "academicSession"
        }
      ],
      "grades": [
        ""
      ],
      "password": null,
      "resources": [
        {
          "href": "",
          "sourcedId": "",
          "type": "academicSession"
        }
      ]
    }
  ],
  "offset": 1,
  "limit": 1,
  "total": 1
}
```

### OneRosterUserAgentOutput

- **Type:**`object`

An agent relationship for a user

- **`relationshipType` (required)**

  `string` — Type of agent relationship (e.g., parent, guardian)

- **`user` (required)**

  `object` — A reference to another OneRoster entity

  - **`href` (required)**

    `string`, format: `uri` — URI reference to the entity

  - **`sourcedId` (required)**

    `string` — Unique identifier of the referenced entity

  - **`type` (required)**

    `string`, possible values: `"academicSession", "category", "class", "course", "demographics", "enrollment", "gradingPeriod", "org", "resource", "user"` — Type of the referenced entity

**Example:**

```json
{
  "user": {
    "href": "",
    "sourcedId": "",
    "type": "academicSession"
  },
  "relationshipType": ""
}
```

### OneRosterUserAgentsOutput

- **Type:**`object`

List of agents for a specific user

- **`agents` (required)**

  `array` — Array of agent relationships

  **Items:**

  - **`relationshipType` (required)**

    `string` — Type of agent relationship (e.g., parent, guardian)

  - **`user` (required)**

    `object` — A reference to another OneRoster entity

    - **`href` (required)**

      `string`, format: `uri` — URI reference to the entity

    - **`sourcedId` (required)**

      `string` — Unique identifier of the referenced entity

    - **`type` (required)**

      `string`, possible values: `"academicSession", "category", "class", "course", "demographics", "enrollment", "gradingPeriod", "org", "resource", "user"` — Type of the referenced entity

**Example:**

```json
{
  "agents": [
    {
      "user": {
        "href": "",
        "sourcedId": "",
        "type": "academicSession"
      },
      "relationshipType": ""
    }
  ]
}
```

### OneRosterUserInput

- **Type:**`object`

User information to be created or updated

- **`user` (required)**

  `object`

  - **`email` (required)**

    `string`, format: `email` — User's email address

  - **`enabledUser` (required)**

    `string`, possible values: `"true", "false"` — Whether the user account is enabled

  - **`familyName` (required)**

    `string` — User's last name

  - **`givenName` (required)**

    `string` — User's first name

  - **`grades` (required)**

    `array` — Grade levels for the user

    **Items:**

    `string`

  - **`primaryOrg` (required)**

    `object`

    - **`sourcedId` (required)**

      `string`, format: `uuid` — Organization ID

    - **`type` (required)**

      `string`, possible values: `"org"` — Reference type

    - **`href`**

      `string` — URI reference to the organization

  - **`sourcedId` (required)**

    `string`, format: `uuid` — Unique identifier for the user

  - **`status` (required)**

    `string`, possible values: `"active", "tobedeleted", "inactive"` — Status of the user record

  - **`demographics`**

    `object` — Demographic information for the user

    - **`birthDate`**

      `string | null`, format: `date` — User's birth date

  - **`identifier`**

    `string | null` — Additional identifier for the user

  - **`metadata`**

    `object | null` — Additional metadata for the user

  - **`middleName`**

    `string | null` — User's middle name

  - **`password`**

    `string | null` — User's password

  - **`phone`**

    `string | null` — User's phone number

  - **`preferredFirstName`**

    `string | null` — User's preferred first name

  - **`preferredLastName`**

    `string | null` — User's preferred last name

  - **`preferredMiddleName`**

    `string | null` — User's preferred middle name

  - **`pronouns`**

    `string | null` — User's preferred pronouns

  - **`roles`**

    `array` — Roles to be assigned to the user

    **Items:**

    - **`org` (required)**

      `object`

      - **`sourcedId` (required)**

        `string`, format: `uuid`

      - **`type` (required)**

        `string`, possible values: `"org"`

      - **`href`**

        `string`

    - **`role` (required)**

      `string`, possible values: `"aide", "counselor", "districtAdministrator", "guardian", "parent", "principal", "proctor", "relative", "siteAdministrator", "student", "systemAdministrator", "teacher"`

    - **`roleType` (required)**

      `string`, possible values: `"primary", "secondary"`

  - **`sms`**

    `string | null` — User's SMS number

  - **`userMasterIdentifier`**

    `string | null` — Master identifier for the user

  - **`username`**

    `string | null` — Username for the user

**Example:**

```json
{
  "user": {
    "sourcedId": "",
    "status": "active",
    "metadata": null,
    "userMasterIdentifier": null,
    "username": null,
    "enabledUser": "true",
    "givenName": "",
    "familyName": "",
    "middleName": null,
    "preferredFirstName": null,
    "preferredMiddleName": null,
    "preferredLastName": null,
    "pronouns": null,
    "demographics": {
      "birthDate": null
    },
    "primaryOrg": {
      "href": "",
      "sourcedId": "",
      "type": "org"
    },
    "identifier": null,
    "email": "",
    "sms": null,
    "phone": null,
    "grades": [
      ""
    ],
    "password": null,
    "roles": [
      {
        "roleType": "primary",
        "role": "aide",
        "org": {
          "href": "",
          "sourcedId": "",
          "type": "org"
        }
      }
    ]
  }
}
```

### ApiError1

- **Type:**`object`

* **`error` (required)**

  `string` — Error name/type

* **`message` (required)**

  `string` — Human-readable error message

* **`fields`**

  `array` — Validation errors for specific fields

  **Items:**

  - **`field`**

    `string`

  - **`message`**

    `string`

**Example:**

```json
{
  "error": "",
  "message": "",
  "fields": [
    {
      "field": "",
      "message": ""
    }
  ]
}
```

### imsxStatusInfoDType3

- **Type:**`object`

* **`imsx_codeMajor`**

  `string`

* **`imsx_CodeMinor`**

  `object`

* **`imsx_description`**

  `string`

* **`imsx_severity`**

  `string`

**Example:**

```json
{
  "imsx_codeMajor": "",
  "imsx_severity": "",
  "imsx_description": "",
  "imsx_CodeMinor": {}
}
```

### ApiError2

- **Type:**`object`

* **`error` (required)**

  `string` — Error name/type

* **`message` (required)**

  `string` — Human-readable error message

* **`fields`**

  `array` — Validation errors for specific fields

  **Items:**

  - **`field`**

    `string`

  - **`message`**

    `string`

**Example:**

```json
{
  "error": "",
  "message": "",
  "fields": [
    {
      "field": "",
      "message": ""
    }
  ]
}
```

### imsxStatusInfoDType4

- **Type:**`object`

* **`imsx_codeMajor`**

  `string`

* **`imsx_CodeMinor`**

  `object`

* **`imsx_description`**

  `string`

* **`imsx_severity`**

  `string`

**Example:**

```json
{
  "imsx_codeMajor": "",
  "imsx_severity": "",
  "imsx_description": "",
  "imsx_CodeMinor": {}
}
```

### imsxCodeMinorFieldDType3

- **Type:**`object`

This is the container for a single code minor status code.

- **`imsx_codeMinorFieldName` (required)**

  `string`, default: `"TargetEndSystem"` — This should contain the identity of the system that has produced the code minor status code report. In most cases this will be the target service provider denoted as 'TargetEndSystem'.

- **`imsx_codeMinorFieldValue` (required)**

  `string`, possible values: `"fullsuccess", "invalid_filter_field", "invalid_selection_field", "invaliddata", "unauthorisedrequest", "forbidden", "server_busy", "unknownobject", "internal_server_error"` — The code minor status code (this is a value from the corresponding enumerated vocabulary).

**Example:**

```json
{
  "imsx_codeMinorFieldName": "TargetEndSystem",
  "imsx_codeMinorFieldValue": "fullsuccess"
}
```

### imsxCodeMinorDType3

- **Type:**`object`

This is the container for the set of code minor status codes reported in the responses from the Service Provider.

- **`imsx_codeMinorField` (required)**

  `array` — Each reported code minor status code.

  **Items:**

  - **`imsx_codeMinorFieldName` (required)**

    `string`, default: `"TargetEndSystem"` — This should contain the identity of the system that has produced the code minor status code report. In most cases this will be the target service provider denoted as 'TargetEndSystem'.

  - **`imsx_codeMinorFieldValue` (required)**

    `string`, possible values: `"fullsuccess", "invalid_filter_field", "invalid_selection_field", "invaliddata", "unauthorisedrequest", "forbidden", "server_busy", "unknownobject", "internal_server_error"` — The code minor status code (this is a value from the corresponding enumerated vocabulary).

**Example:**

```json
{
  "imsx_codeMinorField": [
    {
      "imsx_codeMinorFieldName": "TargetEndSystem",
      "imsx_codeMinorFieldValue": "fullsuccess"
    }
  ]
}
```

### imsxStatusInfoDType5

- **Type:**`object`

This is the container for the status code and associated information returned within the HTTP messages received from the Service Provider. For the OneRoster Rostering service this object will only be returned to provide information about a failed request i.e. it will NOT be in the payload for a successful request.

- **`imsx_codeMajor` (required)**

  `string`, possible values: `"success", "processing", "failure", "unsupported"` — The code major value (from the corresponding enumerated vocabulary).

- **`imsx_severity` (required)**

  `string`, possible values: `"status", "warning", "error"` — The severity value (from the corresponding enumerated vocabulary).

- **`imsx_CodeMinor`**

  `object` — This is the container for the set of code minor status codes reported in the responses from the Service Provider.

  - **`imsx_codeMinorField` (required)**

    `array` — Each reported code minor status code.

    **Items:**

    - **`imsx_codeMinorFieldName` (required)**

      `string`, default: `"TargetEndSystem"` — This should contain the identity of the system that has produced the code minor status code report. In most cases this will be the target service provider denoted as 'TargetEndSystem'.

    - **`imsx_codeMinorFieldValue` (required)**

      `string`, possible values: `"fullsuccess", "invalid_filter_field", "invalid_selection_field", "invaliddata", "unauthorisedrequest", "forbidden", "server_busy", "unknownobject", "internal_server_error"` — The code minor status code (this is a value from the corresponding enumerated vocabulary).

- **`imsx_description`**

  `string` — A human readable description supplied by the entity creating the status code information.

**Example:**

```json
{
  "imsx_codeMajor": "success",
  "imsx_severity": "status",
  "imsx_description": "",
  "imsx_CodeMinor": {
    "imsx_codeMinorField": [
      {
        "imsx_codeMinorFieldName": "TargetEndSystem",
        "imsx_codeMinorFieldValue": "fullsuccess"
      }
    ]
  }
}
```

### imsxCodeMinorFieldDType4

- **Type:**`object`

This is the container for a single code minor status code.

- **`imsx_codeMinorFieldName` (required)**

  `string`, default: `"TargetEndSystem"` — This should contain the identity of the system that has produced the code minor status code report. In most cases this will be the target service provider denoted as 'TargetEndSystem'.

- **`imsx_codeMinorFieldValue` (required)**

  `string`, possible values: `"fullsuccess", "invaliddata", "unauthorisedrequest", "forbidden", "server_busy", "unknownobject", "internal_server_error"` — The code minor status code (this is a value from the corresponding enumerated vocabulary).

**Example:**

```json
{
  "imsx_codeMinorFieldName": "TargetEndSystem",
  "imsx_codeMinorFieldValue": "fullsuccess"
}
```

### imsxCodeMinorDType4

- **Type:**`object`

This is the container for the set of code minor status codes reported in the responses from the Service Provider.

- **`imsx_codeMinorField` (required)**

  `array` — Each reported code minor status code.

  **Items:**

  - **`imsx_codeMinorFieldName` (required)**

    `string`, default: `"TargetEndSystem"` — This should contain the identity of the system that has produced the code minor status code report. In most cases this will be the target service provider denoted as 'TargetEndSystem'.

  - **`imsx_codeMinorFieldValue` (required)**

    `string`, possible values: `"fullsuccess", "invaliddata", "unauthorisedrequest", "forbidden", "server_busy", "unknownobject", "internal_server_error"` — The code minor status code (this is a value from the corresponding enumerated vocabulary).

**Example:**

```json
{
  "imsx_codeMinorField": [
    {
      "imsx_codeMinorFieldName": "TargetEndSystem",
      "imsx_codeMinorFieldValue": "fullsuccess"
    }
  ]
}
```

### imsxStatusInfoDType6

- **Type:**`object`

This is the container for the status code and associated information returned within the HTTP messages received from the Service Provider.

- **`imsx_codeMajor` (required)**

  `string`, possible values: `"success", "processing", "failure", "unsupported"` — The code major value (from the corresponding enumerated vocabulary).

- **`imsx_severity` (required)**

  `string`, possible values: `"status", "warning", "error"` — The severity value (from the corresponding enumerated vocabulary).

- **`imsx_CodeMinor`**

  `object` — This is the container for the set of code minor status codes reported in the responses from the Service Provider.

  - **`imsx_codeMinorField` (required)**

    `array` — Each reported code minor status code.

    **Items:**

    - **`imsx_codeMinorFieldName` (required)**

      `string`, default: `"TargetEndSystem"` — This should contain the identity of the system that has produced the code minor status code report. In most cases this will be the target service provider denoted as 'TargetEndSystem'.

    - **`imsx_codeMinorFieldValue` (required)**

      `string`, possible values: `"fullsuccess", "invaliddata", "unauthorisedrequest", "forbidden", "server_busy", "unknownobject", "internal_server_error"` — The code minor status code (this is a value from the corresponding enumerated vocabulary).

- **`imsx_description`**

  `string` — A human readable description supplied by the entity creating the status code information.

**Example:**

```json
{
  "imsx_codeMajor": "success",
  "imsx_severity": "status",
  "imsx_description": "",
  "imsx_CodeMinor": {
    "imsx_codeMinorField": [
      {
        "imsx_codeMinorFieldName": "TargetEndSystem",
        "imsx_codeMinorFieldValue": "fullsuccess"
      }
    ]
  }
}
```

### ImsxCodeMinorFieldDType

- **Type:**`object`

This is the container for a single code minor status code

- **`imsx_codeMinorFieldName` (required)**

  `string`, default: `"TargetEndSystem"` — This should contain the identity of the system that has produced the code minor status code report. In most cases this will be the target service provider denoted as 'TargetEndSystem'

- **`imsx_codeMinorFieldValue` (required)**

  `string`, possible values: `"fullsuccess", "invaliddata", "unauthorisedrequest", "forbidden", "server_busy", "unknownobject", "internal_server_error"` — The code minor status code (this is a value from the corresponding enumerated vocabulary)

**Example:**

```json
{
  "imsx_codeMinorFieldName": "TargetEndSystem",
  "imsx_codeMinorFieldValue": "fullsuccess"
}
```

### ImsxCodeMinorDType

- **Type:**`object`

This is the container for the set of code minor status codes reported in the responses from the Service Provider

- **`imsx_codeMinorField` (required)**

  `array` — Each reported code minor status code

  **Items:**

  - **`imsx_codeMinorFieldName` (required)**

    `string`, default: `"TargetEndSystem"` — This should contain the identity of the system that has produced the code minor status code report. In most cases this will be the target service provider denoted as 'TargetEndSystem'

  - **`imsx_codeMinorFieldValue` (required)**

    `string`, possible values: `"fullsuccess", "invaliddata", "unauthorisedrequest", "forbidden", "server_busy", "unknownobject", "internal_server_error"` — The code minor status code (this is a value from the corresponding enumerated vocabulary)

**Example:**

```json
{
  "imsx_codeMinorField": [
    {
      "imsx_codeMinorFieldName": "TargetEndSystem",
      "imsx_codeMinorFieldValue": "fullsuccess"
    }
  ]
}
```

### ImsxStatusInfoDType

- **Type:**`object`

This is the container for the status code and associated information returned within the HTTP messages received from the Service Provider

- **`imsx_codeMajor` (required)**

  `string`, possible values: `"success", "processing", "failure", "unsupported"` — The code major value (from the corresponding enumerated vocabulary)

- **`imsx_severity` (required)**

  `string`, possible values: `"status", "warning", "error"` — The severity value (from the corresponding enumerated vocabulary)

- **`imsx_CodeMinor`**

  `object` — This is the container for the set of code minor status codes reported in the responses from the Service Provider

  - **`imsx_codeMinorField` (required)**

    `array` — Each reported code minor status code

    **Items:**

    - **`imsx_codeMinorFieldName` (required)**

      `string`, default: `"TargetEndSystem"` — This should contain the identity of the system that has produced the code minor status code report. In most cases this will be the target service provider denoted as 'TargetEndSystem'

    - **`imsx_codeMinorFieldValue` (required)**

      `string`, possible values: `"fullsuccess", "invaliddata", "unauthorisedrequest", "forbidden", "server_busy", "unknownobject", "internal_server_error"` — The code minor status code (this is a value from the corresponding enumerated vocabulary)

- **`imsx_description`**

  `string` — A human readable description supplied by the entity creating the status code information

**Example:**

```json
{
  "imsx_codeMajor": "success",
  "imsx_severity": "status",
  "imsx_description": "",
  "imsx_CodeMinor": {
    "imsx_codeMinorField": [
      {
        "imsx_codeMinorFieldName": "TargetEndSystem",
        "imsx_codeMinorFieldValue": "fullsuccess"
      }
    ]
  }
}
```

### ImsxStatusInfoDType1

- **Type:**`object`

This is the container for the status code and associated information returned within the HTTP messages received from the Service Provider

- **`imsx_codeMajor` (required)**

  `string`, possible values: `"success", "processing", "failure", "unsupported"` — The code major value (from the corresponding enumerated vocabulary)

- **`imsx_severity` (required)**

  `string`, possible values: `"status", "warning", "error"` — The severity value (from the corresponding enumerated vocabulary)

- **`imsx_description`**

  `string` — A human readable description supplied by the entity creating the status code information

**Example:**

```json
{
  "imsx_codeMajor": "success",
  "imsx_severity": "status",
  "imsx_description": ""
}
```

### ErrorResponse

- **Type:**`object`

* **`message`**

  `string`

**Example:**

```json
{
  "message": "Error message"
}
```

### InsightType

- **Type:**`string`

Type of insight

**Example:**

### InsightVersion

- **Type:**`string`

Version of the insight

**Example:**

### InsightEvidenceOutput

- **Type:**`object`

Evidence information for the insight

- **`caliperSessionId` (required)**

  `string` — Reference to the CaliperSession for evidence tracking

**Example:**

```json
{
  "caliperSessionId": ""
}
```

### InsightOutput

- **Type:**`object`

Unified insight information

- **`durationInSeconds` (required)**

  `integer` — Duration of the insight in seconds

- **`endedAtTime` (required)**

  `string`, format: `date-time` — Timestamp when the insight period ended

- **`evidence` (required)**

  `object` — Evidence information for the insight

  - **`caliperSessionId` (required)**

    `string` — Reference to the CaliperSession for evidence tracking

- **`id` (required)**

  `string`, format: `uuid` — Unique identifier for the insight

- **`insightType` (required)**

  `string`, possible values: `"AwayFromSeat", "Eating", "EyesOffScreen", "Game", "Idling", "NonLearningContent", "Socializing", "UnauthorizedAppUse", "HelpFromAnotherPerson", "BullyingOrHarassment", "EmbarrassingOrDefaming", "MentalHealthDistress", "PornographyOrSexualContent", "SelfHarmOrSuicide", "SubstanceAbuse", "ViolenceOrAbuse", "WebcamNudity", "Journal", "IgnoringHelp", "SkipAssessment", "AbandonedAssessment", "TopicShopping"` — Type of insight

- **`reason` (required)**

  `string` — Detailed reason or description for the insight

- **`startedAtTime` (required)**

  `string`, format: `date-time` — Timestamp when the insight period started

- **`version` (required)**

  `string`, possible values: `"v1"` — Version of the insight

**Example:**

```json
{
  "id": "",
  "insightType": "AwayFromSeat",
  "reason": "",
  "startedAtTime": "",
  "endedAtTime": "",
  "durationInSeconds": 1,
  "version": "v1",
  "evidence": {
    "caliperSessionId": ""
  }
}
```

### SessionSummaryOutput

- **Type:**`object`

Session summary information

- **`durationInSeconds` (required)**

  `integer` — Total duration of the session in seconds

- **`endedAtTime` (required)**

  `string`, format: `date-time` — Timestamp when the session ended

- **`startedAtTime` (required)**

  `string`, format: `date-time` — Timestamp when the session started

- **`wasteDurationInSeconds` (required)**

  `integer` — Total waste duration of the session in seconds

- **`wastePercentage` (required)**

  `integer` — Percentage of session time that was waste (0-100)

**Example:**

```json
{
  "startedAtTime": "",
  "endedAtTime": "",
  "durationInSeconds": 1,
  "wasteDurationInSeconds": 1,
  "wastePercentage": 1
}
```

### PaginatedInsightsOutput

- **Type:**`object`

Unified paginated insights response with session summary

- **`insights` (required)**

  `array` — Array of insight objects

  **Items:**

  - **`durationInSeconds` (required)**

    `integer` — Duration of the insight in seconds

  - **`endedAtTime` (required)**

    `string`, format: `date-time` — Timestamp when the insight period ended

  - **`evidence` (required)**

    `object` — Evidence information for the insight

    - **`caliperSessionId` (required)**

      `string` — Reference to the CaliperSession for evidence tracking

  - **`id` (required)**

    `string`, format: `uuid` — Unique identifier for the insight

  - **`insightType` (required)**

    `string`, possible values: `"AwayFromSeat", "Eating", "EyesOffScreen", "Game", "Idling", "NonLearningContent", "Socializing", "UnauthorizedAppUse", "HelpFromAnotherPerson", "BullyingOrHarassment", "EmbarrassingOrDefaming", "MentalHealthDistress", "PornographyOrSexualContent", "SelfHarmOrSuicide", "SubstanceAbuse", "ViolenceOrAbuse", "WebcamNudity", "Journal", "IgnoringHelp", "SkipAssessment", "AbandonedAssessment", "TopicShopping"` — Type of insight

  - **`reason` (required)**

    `string` — Detailed reason or description for the insight

  - **`startedAtTime` (required)**

    `string`, format: `date-time` — Timestamp when the insight period started

  - **`version` (required)**

    `string`, possible values: `"v1"` — Version of the insight

- **`limit` (required)**

  `integer` — Maximum number of items returned

- **`offset` (required)**

  `integer` — Number of items skipped in the result set

- **`session` (required)**

  `object` — Session summary information

  - **`durationInSeconds` (required)**

    `integer` — Total duration of the session in seconds

  - **`endedAtTime` (required)**

    `string`, format: `date-time` — Timestamp when the session ended

  - **`startedAtTime` (required)**

    `string`, format: `date-time` — Timestamp when the session started

  - **`wasteDurationInSeconds` (required)**

    `integer` — Total waste duration of the session in seconds

  - **`wastePercentage` (required)**

    `integer` — Percentage of session time that was waste (0-100)

- **`total` (required)**

  `integer` — Total number of items available

**Example:**

```json
{
  "session": {
    "startedAtTime": "",
    "endedAtTime": "",
    "durationInSeconds": 1,
    "wasteDurationInSeconds": 1,
    "wastePercentage": 1
  },
  "insights": [
    {
      "id": "",
      "insightType": "AwayFromSeat",
      "reason": "",
      "startedAtTime": "",
      "endedAtTime": "",
      "durationInSeconds": 1,
      "version": "v1",
      "evidence": {
        "caliperSessionId": ""
      }
    }
  ],
  "offset": 1,
  "limit": 1,
  "total": 1
}
```

### SessionOutput

- **Type:**`object`

Session information

- **`caliperSessionId` (required)**

  `string` — Reference to the CaliperSession for evidence tracking

- **`durationInSeconds` (required)**

  `integer` — Total duration of the session in seconds

- **`endedAtTime` (required)**

  `string`, format: `date-time` — Timestamp when the session ended

- **`id` (required)**

  `string` — Session identifier

- **`startedAtTime` (required)**

  `string`, format: `date-time` — Timestamp when the session started

- **`toolId` (required)**

  `string`, format: `uuid` — Identifier for the LTI tool used in the session

- **`wasteDurationInSeconds` (required)**

  `integer` — Total waste duration of the session in seconds

- **`wastePercentage` (required)**

  `integer` — Percentage of session time that was waste (0-100)

- **`isProctored`**

  `boolean` — Indicates whether this session is considered proctored

- **`proctoredResult`**

  `string` — Result of the proctored session

- **`recordingEndedAtTime`**

  `string | null`, format: `date-time` — Timestamp when the recording ended

- **`recordingS3Key`**

  `string | null` — S3 key for the associated proctoring recording, if any

- **`recordingStartedAtTime`**

  `string | null`, format: `date-time` — Timestamp when the recording started

**Example:**

```json
{
  "id": "",
  "toolId": "",
  "startedAtTime": "",
  "endedAtTime": "",
  "durationInSeconds": 1,
  "wasteDurationInSeconds": 1,
  "wastePercentage": 1,
  "isProctored": true,
  "proctoredResult": "",
  "recordingStartedAtTime": null,
  "recordingEndedAtTime": null,
  "recordingS3Key": null
}
```

### PaginatedSessionsOutput

- **Type:**`object`

Paginated list of sessions

- **`limit` (required)**

  `integer` — Maximum number of items returned

- **`offset` (required)**

  `integer` — Number of items skipped in the result set

- **`sessions` (required)**

  `array` — Array of session objects

  **Items:**

  - **`caliperSessionId` (required)**

    `string` — Reference to the CaliperSession for evidence tracking

  - **`durationInSeconds` (required)**

    `integer` — Total duration of the session in seconds

  - **`endedAtTime` (required)**

    `string`, format: `date-time` — Timestamp when the session ended

  - **`id` (required)**

    `string` — Session identifier

  - **`startedAtTime` (required)**

    `string`, format: `date-time` — Timestamp when the session started

  - **`toolId` (required)**

    `string`, format: `uuid` — Identifier for the LTI tool used in the session

  - **`wasteDurationInSeconds` (required)**

    `integer` — Total waste duration of the session in seconds

  - **`wastePercentage` (required)**

    `integer` — Percentage of session time that was waste (0-100)

  - **`isProctored`**

    `boolean` — Indicates whether this session is considered proctored

  - **`proctoredResult`**

    `string` — Result of the proctored session

  - **`recordingEndedAtTime`**

    `string | null`, format: `date-time` — Timestamp when the recording ended

  - **`recordingS3Key`**

    `string | null` — S3 key for the associated proctoring recording, if any

  - **`recordingStartedAtTime`**

    `string | null`, format: `date-time` — Timestamp when the recording started

- **`total` (required)**

  `integer` — Total number of items available

**Example:**

```json
{
  "sessions": [
    {
      "id": "",
      "toolId": "",
      "startedAtTime": "",
      "endedAtTime": "",
      "durationInSeconds": 1,
      "wasteDurationInSeconds": 1,
      "wastePercentage": 1,
      "isProctored": true,
      "proctoredResult": "",
      "recordingStartedAtTime": null,
      "recordingEndedAtTime": null,
      "recordingS3Key": null
    }
  ],
  "offset": 1,
  "limit": 1,
  "total": 1
}
```

### InsightsOverviewLevel

- **Type:**`string`

**Example:**

### InsightsLevelSegment

- **Type:**`object`

* **`durationInSeconds` (required)**

  `integer`

* **`level` (required)**

  `string`, possible values: `"StudentNotPresent", "EnvironmentalDistractions", "OnDeviceDistractions", "LearningAppBestPractices"`

**Example:**

```json
{
  "level": "StudentNotPresent",
  "durationInSeconds": 0
}
```

### InsightsSubtypeSegment

- **Type:**`object`

* **`durationInSeconds` (required)**

  `integer`

* **`insightType` (required)**

  `string`, possible values: `"AwayFromSeat", "Eating", "EyesOffScreen", "Game", "Idling", "NonLearningContent", "Socializing", "UnauthorizedAppUse", "HelpFromAnotherPerson", "BullyingOrHarassment", "EmbarrassingOrDefaming", "MentalHealthDistress", "PornographyOrSexualContent", "SelfHarmOrSuicide", "SubstanceAbuse", "ViolenceOrAbuse", "WebcamNudity", "Journal", "IgnoringHelp", "SkipAssessment", "AbandonedAssessment", "TopicShopping"` — Type of insight

**Example:**

```json
{
  "insightType": "AwayFromSeat",
  "durationInSeconds": 0
}
```

### InsightsTrendBucket

- **Type:**`object`

* **`endedAtTime` (required)**

  `string`, format: `date-time`

* **`levels` (required)**

  `array`

  **Items:**

  - **`durationInSeconds` (required)**

    `integer`

  - **`level` (required)**

    `string`, possible values: `"StudentNotPresent", "EnvironmentalDistractions", "OnDeviceDistractions", "LearningAppBestPractices"`

* **`startedAtTime` (required)**

  `string`, format: `date-time`

* **`totalDurationInSeconds` (required)**

  `integer`

* **`wasteDurationInSeconds` (required)**

  `integer`

* **`wastePercentage` (required)**

  `integer`

**Example:**

```json
{
  "startedAtTime": "",
  "endedAtTime": "",
  "totalDurationInSeconds": 0,
  "wasteDurationInSeconds": 0,
  "wastePercentage": 0,
  "levels": [
    {
      "level": "StudentNotPresent",
      "durationInSeconds": 0
    }
  ]
}
```

### InsightsLevelBreakdown

- **Type:**`object`

* **`durationInSeconds` (required)**

  `integer`

* **`level` (required)**

  `string`, possible values: `"StudentNotPresent", "EnvironmentalDistractions", "OnDeviceDistractions", "LearningAppBestPractices"`

* **`subtypes` (required)**

  `array`

  **Items:**

  - **`durationInSeconds` (required)**

    `integer`

  - **`insightType` (required)**

    `string`, possible values: `"AwayFromSeat", "Eating", "EyesOffScreen", "Game", "Idling", "NonLearningContent", "Socializing", "UnauthorizedAppUse", "HelpFromAnotherPerson", "BullyingOrHarassment", "EmbarrassingOrDefaming", "MentalHealthDistress", "PornographyOrSexualContent", "SelfHarmOrSuicide", "SubstanceAbuse", "ViolenceOrAbuse", "WebcamNudity", "Journal", "IgnoringHelp", "SkipAssessment", "AbandonedAssessment", "TopicShopping"` — Type of insight

* **`wastePercentage` (required)**

  `integer`

**Example:**

```json
{
  "level": "StudentNotPresent",
  "durationInSeconds": 0,
  "wastePercentage": 0,
  "subtypes": [
    {
      "insightType": "AwayFromSeat",
      "durationInSeconds": 0
    }
  ]
}
```

### InsightsBiggestInsight

- **Type:**`object`

* **`durationInSeconds` (required)**

  `integer`

* **`level` (required)**

  `string`, possible values: `"StudentNotPresent", "EnvironmentalDistractions", "OnDeviceDistractions", "LearningAppBestPractices"`

* **`wastePercentage` (required)**

  `integer`

**Example:**

```json
{
  "level": "StudentNotPresent",
  "durationInSeconds": 0,
  "wastePercentage": 0
}
```

### GetUserInsightsOverviewOutput

- **Type:**`object`

* **`breakdown` (required)**

  `object`

  - **`levels` (required)**

    `array`

    **Items:**

    - **`durationInSeconds` (required)**

      `integer`

    - **`level` (required)**

      `string`, possible values: `"StudentNotPresent", "EnvironmentalDistractions", "OnDeviceDistractions", "LearningAppBestPractices"`

    - **`subtypes` (required)**

      `array`

      **Items:**

      - **`durationInSeconds` (required)**

        `integer`

      - **`insightType` (required)**

        `string`, possible values: `"AwayFromSeat", "Eating", "EyesOffScreen", "Game", "Idling", "NonLearningContent", "Socializing", "UnauthorizedAppUse", "HelpFromAnotherPerson", "BullyingOrHarassment", "EmbarrassingOrDefaming", "MentalHealthDistress", "PornographyOrSexualContent", "SelfHarmOrSuicide", "SubstanceAbuse", "ViolenceOrAbuse", "WebcamNudity", "Journal", "IgnoringHelp", "SkipAssessment", "AbandonedAssessment", "TopicShopping"` — Type of insight

    - **`wastePercentage` (required)**

      `integer`

* **`summary` (required)**

  `object`

  - **`biggestInsight` (required)**

    `object`

  - **`totalDurationInSeconds` (required)**

    `integer`

  - **`totalWasteDurationInSeconds` (required)**

    `integer`

  - **`wastePercentage` (required)**

    `integer`

* **`trend` (required)**

  `object`

  - **`buckets` (required)**

    `array`

    **Items:**

    - **`endedAtTime` (required)**

      `string`, format: `date-time`

    - **`levels` (required)**

      `array`

      **Items:**

      - **`durationInSeconds` (required)**

        `integer`

      - **`level` (required)**

        `string`, possible values: `"StudentNotPresent", "EnvironmentalDistractions", "OnDeviceDistractions", "LearningAppBestPractices"`

    - **`startedAtTime` (required)**

      `string`, format: `date-time`

    - **`totalDurationInSeconds` (required)**

      `integer`

    - **`wasteDurationInSeconds` (required)**

      `integer`

    - **`wastePercentage` (required)**

      `integer`

**Example:**

```json
{
  "summary": {
    "totalDurationInSeconds": 1,
    "totalWasteDurationInSeconds": 1,
    "wastePercentage": 1,
    "biggestInsight": null
  },
  "trend": {
    "buckets": [
      {
        "startedAtTime": "",
        "endedAtTime": "",
        "totalDurationInSeconds": 0,
        "wasteDurationInSeconds": 0,
        "wastePercentage": 0,
        "levels": [
          {
            "level": "StudentNotPresent",
            "durationInSeconds": 0
          }
        ]
      }
    ]
  },
  "breakdown": {
    "levels": [
      {
        "level": "StudentNotPresent",
        "durationInSeconds": 0,
        "wastePercentage": 0,
        "subtypes": [
          {
            "insightType": "AwayFromSeat",
            "durationInSeconds": 0
          }
        ]
      }
    ]
  }
}
```

### ApiError3

- **Type:**`object`

* **`error` (required)**

  `string` — Error name/type

* **`message` (required)**

  `string` — Human-readable error message

* **`fields`**

  `array` — Validation errors for specific fields

  **Items:**

  - **`field`**

    `string`

  - **`message`**

    `string`

**Example:**

```json
{
  "error": "",
  "message": "",
  "fields": [
    {
      "field": "",
      "message": ""
    }
  ]
}
```