@iblai/iblai-api 4.316.1-core → 4.317.1-core

package/sdk_schema.yml

@@ -1,7 +1,7 @@
 openapi: 3.0.3
 info:
   title: ibl-data-manager
-  version: 4.316.1-core
+  version: 4.317.1-core
   description: API for iblai
 paths:
   /api/analytics/content/:
@@ -307,19 +307,27 @@ paths:
   /api/analytics/learner/details:
     get:
       operationId: analytics_learner_details_retrieve
-      description: "\n        Retrieve a holistic snapshot of a learner across catalog\
-        \ enrollments, mentor\n        engagement, skills, credentials, and time spent\
+      description: "\n        Retrieve a holistic snapshot of a user across catalog\
+        \ enrollments, agent\n        engagement, skills, credentials, and time spent\
         \ data. The `metrics` query parameter controls\n        which sections are\
-        \ returned and defaults to `courses` when omitted.\n\n        Optional `course_id`\
-        \ / `program_id` / `pathway_id` scope the matching section to a\n        single\
-        \ item (empty list if the learner is not enrolled — never a 404); omitting\
-        \ them\n        returns the full list unchanged. When `course_id` is set,\
-        \ the course block is also\n        enriched with the learner's live edX Progress\
-        \ data under `edx_progress` (completion\n        summary, grade, grade summary)\
-        \ unless `include_edx_progress=false`. The edX call is\n        best-effort:\
-        \ on failure `edx_progress` is null and the DM data is still returned.\n \
-        \       `program_id` / `pathway_id` get scoping only — no edX enrichment.\n\
-        \        "
+        \ returned and defaults to `courses` when omitted. A user can call this\n\
+        \        endpoint for themselves without passing `username`; admins pass `username`\
+        \ to target a\n        user in their scope.\n\n        The `mentors` section\
+        \ lists every agent the user has engaged, sourced from both their\n      \
+        \  sessions and saved agents. Each agent's `interactions` block reports engagement\
+        \ depth\n        (`session_count`, `conversation_count`, human/AI message\
+        \ counts, `avg_messages_per_session`),\n        recency and stickiness (`first_interaction`,\
+        \ `latest_interaction`, `active_days`),\n        affinity (`rating`, `is_starred`),\
+        \ and spend (`cost_usd`, in USD). The user's total\n        agent spend is\
+        \ `user.total_agent_cost_usd`.\n\n        Optional `course_id` / `program_id`\
+        \ / `pathway_id` scope the matching section to a\n        single item (empty\
+        \ list if the user is not enrolled — never a 404); omitting them\n       \
+        \ returns the full list unchanged. When `course_id` is set, the course block\
+        \ is also\n        enriched with the user's live edX Progress data under `edx_progress`\
+        \ (completion\n        summary, grade, grade summary) unless `include_edx_progress=false`.\
+        \ The edX call is\n        best-effort: on failure `edx_progress` is null\
+        \ and the DM data is still returned.\n        `program_id` / `pathway_id`\
+        \ get scoping only — no edX enrichment.\n        "
       parameters:
       - in: query
         name: course_id
@@ -380,6 +388,9 @@ paths:
         name: metrics
         schema:
           type: string
+        description: 'Comma-separated sections to return: courses, programs, pathways,
+          agents, skills, credentials, time_spent. `agents` is an alias for the agent
+          (mentor) section. Defaults to courses when omitted.'
       - in: query
         name: overtime
         schema:
@@ -417,8 +428,6 @@ paths:
         name: username
         schema:
           type: string
-          minLength: 1
-        required: true
       tags:
       - ai-analytics
       security:
@@ -430,15 +439,16 @@ paths:
               schema:
                 $ref: '#/components/schemas/LearnerDetailsResponse'
               examples:
-                LearnerDetails:
+                UserDetails:
                   value:
                     user:
                       user_id: 42
-                      username: learner123
-                      email: learner@example.com
-                      name: Learner Example
+                      username: user123
+                      email: user@example.com
+                      name: Example User
                       date_joined: '2024-01-01T00:00:00Z'
                       last_active: '2024-02-01T12:30:00Z'
+                      total_agent_cost_usd: '14.2000'
                     data:
                       courses:
                       - course_id: course-v1:edX+Demo+2024
@@ -464,9 +474,18 @@ paths:
                         subjects:
                         - Algebra
                         interactions:
-                          total_messages: 12
+                          session_count: 8
+                          conversation_count: 6
+                          message_count_human: 41
+                          message_count_ai: 47
+                          total_messages: 88
+                          avg_messages_per_session: 11.0
+                          first_interaction: '2024-01-05T00:00:00Z'
                           latest_interaction: '2024-02-01T12:30:00Z'
+                          active_days: 5
+                          cost_usd: '1.8300'
                           rating: 4.5
+                          is_starred: true
                       time_spent:
                         courses:
                         - course_id: course-v1:edX+Demo+2024
@@ -476,7 +495,7 @@ paths:
                           time_spent_secs: 9000
                         total_time_spent: 2h 30m
                         total_time_spent_secs: 9000
-                  summary: Learner details
+                  summary: User details
                   description: Example learner detail payload
           description: Learner profile with requested analytics data
         '400':
@@ -942,6 +961,206 @@ paths:
           description: Bad request
         '401':
           description: Unauthorized
+  /api/analytics/user:
+    get:
+      operationId: analytics_user_retrieve
+      description: "\n        Retrieve a holistic snapshot of a user across catalog\
+        \ enrollments, agent\n        engagement, skills, credentials, and time spent\
+        \ data. The `metrics` query parameter controls\n        which sections are\
+        \ returned and defaults to `courses` when omitted. A user can call this\n\
+        \        endpoint for themselves without passing `username`; admins pass `username`\
+        \ to target a\n        user in their scope.\n\n        The `mentors` section\
+        \ lists every agent the user has engaged, sourced from both their\n      \
+        \  sessions and saved agents. Each agent's `interactions` block reports engagement\
+        \ depth\n        (`session_count`, `conversation_count`, human/AI message\
+        \ counts, `avg_messages_per_session`),\n        recency and stickiness (`first_interaction`,\
+        \ `latest_interaction`, `active_days`),\n        affinity (`rating`, `is_starred`),\
+        \ and spend (`cost_usd`, in USD). The user's total\n        agent spend is\
+        \ `user.total_agent_cost_usd`.\n\n        Optional `course_id` / `program_id`\
+        \ / `pathway_id` scope the matching section to a\n        single item (empty\
+        \ list if the user is not enrolled — never a 404); omitting them\n       \
+        \ returns the full list unchanged. When `course_id` is set, the course block\
+        \ is also\n        enriched with the user's live edX Progress data under `edx_progress`\
+        \ (completion\n        summary, grade, grade summary) unless `include_edx_progress=false`.\
+        \ The edX call is\n        best-effort: on failure `edx_progress` is null\
+        \ and the DM data is still returned.\n        `program_id` / `pathway_id`\
+        \ get scoping only — no edX enrichment.\n        "
+      parameters:
+      - in: query
+        name: course_id
+        schema:
+          type: string
+        description: Scope the `courses` and `time_spent` sections to a single course.
+          When set, also enriches the course with live edX progress (see `include_edx_progress`).
+      - in: query
+        name: date_filter
+        schema:
+          enum:
+          - today
+          - 7d
+          - 30d
+          - 90d
+          - all_time
+          - custom
+          type: string
+          default: today
+          minLength: 1
+        description: |-
+          * `today` - Today only
+          * `7d` - Last 7 days
+          * `30d` - Last 30 days
+          * `90d` - Last 90 days
+          * `all_time` - All time
+          * `custom` - Custom date range
+      - in: query
+        name: end_date
+        schema:
+          type: string
+          format: date
+      - in: query
+        name: granularity
+        schema:
+          enum:
+          - day
+          - hour
+          - week
+          - month
+          type: string
+          default: hour
+          minLength: 1
+        description: |-
+          * `day` - day
+          * `hour` - hour
+          * `week` - week
+          * `month` - month
+      - in: query
+        name: include_edx_progress
+        schema:
+          type: boolean
+          default: true
+        description: When `course_id` is set, fold the learner's live edX Progress-page
+          data (completion summary, grade, grade summary) into the course block. Defaults
+          to true; set false to skip the edX round-trip.
+      - in: query
+        name: metrics
+        schema:
+          type: string
+        description: 'Comma-separated sections to return: courses, programs, pathways,
+          agents, skills, credentials, time_spent. `agents` is an alias for the agent
+          (mentor) section. Defaults to courses when omitted.'
+      - in: query
+        name: overtime
+        schema:
+          type: boolean
+          default: false
+        description: 'Include overtime metrics for time_spent data (default: false)'
+      - in: query
+        name: pathway_id
+        schema:
+          type: string
+        description: Scope the `pathways` section to a single pathway.
+      - in: query
+        name: platform_key
+        schema:
+          type: string
+      - in: query
+        name: program_id
+        schema:
+          type: string
+        description: Scope the `programs` section to a single program.
+      - in: query
+        name: start_date
+        schema:
+          type: string
+          format: date
+      - in: query
+        name: usergroup_ids
+        schema:
+          type: array
+          items:
+            type: integer
+          nullable: true
+        description: Optional list of usergroup IDs to filter results
+      - in: query
+        name: username
+        schema:
+          type: string
+      tags:
+      - ai-analytics
+      security:
+      - PlatformApiKeyAuthentication: []
+      responses:
+        '200':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/LearnerDetailsResponse'
+              examples:
+                UserDetails:
+                  value:
+                    user:
+                      user_id: 42
+                      username: user123
+                      email: user@example.com
+                      name: Example User
+                      date_joined: '2024-01-01T00:00:00Z'
+                      last_active: '2024-02-01T12:30:00Z'
+                      total_agent_cost_usd: '14.2000'
+                    data:
+                      courses:
+                      - course_id: course-v1:edX+Demo+2024
+                        name: Demo Course
+                        platform: key_org1
+                        enrollment:
+                          created: '2024-01-05T00:00:00Z'
+                          started: '2024-01-06T00:00:00Z'
+                          ended: null
+                          active: true
+                        completion:
+                          completed: true
+                          completion_percentage: 92.5
+                          passed: true
+                          passed_date: '2024-01-18T00:00:00Z'
+                      mentors:
+                      - mentor_id: b451624c-ef13-4f9f-8cc6-2a0e8c781f12
+                        name: AI Math Tutor
+                        slug: ai-math-tutor
+                        platform_key: key_org1
+                        categories:
+                        - Mathematics
+                        subjects:
+                        - Algebra
+                        interactions:
+                          session_count: 8
+                          conversation_count: 6
+                          message_count_human: 41
+                          message_count_ai: 47
+                          total_messages: 88
+                          avg_messages_per_session: 11.0
+                          first_interaction: '2024-01-05T00:00:00Z'
+                          latest_interaction: '2024-02-01T12:30:00Z'
+                          active_days: 5
+                          cost_usd: '1.8300'
+                          rating: 4.5
+                          is_starred: true
+                      time_spent:
+                        courses:
+                        - course_id: course-v1:edX+Demo+2024
+                          course_name: Demo Course
+                          platform: key_org1
+                          time_spent: 2h 30m
+                          time_spent_secs: 9000
+                        total_time_spent: 2h 30m
+                        total_time_spent_secs: 9000
+                  summary: User details
+                  description: Example learner detail payload
+          description: Learner profile with requested analytics data
+        '400':
+          description: Bad Request - Invalid parameters supplied
+        '404':
+          description: Learner not found
+        '500':
+          description: Unexpected error
   /api/audience/orgs/{org}/active-users/over-time:
     get:
       operationId: audience_orgs_active_users_over_time_retrieve
@@ -48155,12 +48374,30 @@ components:
           type: string
           readOnly: true
           description: The course key
+        status:
+          type: string
+          readOnly: true
+          description: 'Creation status: pending, building, ready, or failed'
+        status_updated_at:
+          type: string
+          format: date-time
+          readOnly: true
+          description: When the status last changed
+        stalled:
+          type: boolean
+          readOnly: true
+          description: True when an in-flight build exceeded the stall timeout
         mentor_config:
           $ref: '#/components/schemas/LtiMentorCourseXBlock'
         platform_key:
           type: string
           writeOnly: true
           description: Platform key the requesting user belongs to
+        async_create:
+          type: boolean
+          default: false
+          description: When True, triggers an async create and reponds with a 202
+            instead of 201
       required:
       - course_key
       - id
@@ -48168,6 +48405,9 @@ components:
       - name
       - org
       - platform_key
+      - stalled
+      - status
+      - status_updated_at
     LtiMentorCourseXBlock:
       type: object
       properties:
@@ -48429,17 +48669,64 @@ components:
     MentorInteractions:
       type: object
       properties:
+        session_count:
+          type: integer
+          description: Total conversations the user has started with this agent, including
+            empty ones.
+        conversation_count:
+          type: integer
+          description: Conversations that had real back-and-forth (at least one user
+            message and one agent reply). Always less than or equal to session_count.
+        message_count_human:
+          type: integer
+          description: Total messages the user sent to this agent across all conversations.
+        message_count_ai:
+          type: integer
+          description: Total replies this agent sent to the user across all conversations.
         total_messages:
           type: integer
+          description: Sum of user and agent messages exchanged with this agent.
+        avg_messages_per_session:
+          type: number
+          format: double
+          description: Average messages per conversation (total_messages / session_count);
+            0 with no conversations.
+        first_interaction:
+          type: string
+          format: date-time
+          nullable: true
+          description: When the user first messaged this agent.
         latest_interaction:
           type: string
           format: date-time
           nullable: true
+          description: When the user most recently interacted with this agent.
+        active_days:
+          type: integer
+          description: Number of distinct calendar days the user exchanged messages
+            with this agent.
+        cost_usd:
+          type: string
+          format: decimal
+          pattern: ^-?\d{0,10}(?:\.\d{0,4})?$
+          nullable: true
+          description: Total amount the user has spent on this agent, in USD.
         rating:
           type: number
           format: double
           nullable: true
-      required:
+          description: Rating the user gave this agent.
+        is_starred:
+          type: boolean
+          default: false
+          description: Whether the user has favorited (starred) this agent.
+      required:
+      - active_days
+      - avg_messages_per_session
+      - conversation_count
+      - message_count_ai
+      - message_count_human
+      - session_count
       - total_messages
     MentorPolicy:
       type: object
@@ -61300,6 +61587,13 @@ components:
         date_joined:
           type: string
           format: date-time
+        total_agent_cost_usd:
+          type: string
+          format: decimal
+          pattern: ^-?\d{0,10}(?:\.\d{0,4})?$
+          nullable: true
+          description: Total amount the user has spent across all agents, in USD.
+            May be slightly higher than the sum of the per-agent cost_usd values.
       required:
       - email
       - name

package/src/core/OpenAPI.ts

@@ -21,7 +21,7 @@ export type OpenAPIConfig = {
 
 export const OpenAPI: OpenAPIConfig = {
     BASE: 'https://base.manager.iblai.app',
-    VERSION: '4.316.1-core',
+    VERSION: '4.317.1-core',
     WITH_CREDENTIALS: false,
     CREDENTIALS: 'include',
     TOKEN: undefined,

package/src/models/LtiMentor.ts

@@ -17,10 +17,26 @@ export type LtiMentor = {
      * The course key
      */
     readonly course_key: string;
+    /**
+     * Creation status: pending, building, ready, or failed
+     */
+    readonly status: string;
+    /**
+     * When the status last changed
+     */
+    readonly status_updated_at: string;
+    /**
+     * True when an in-flight build exceeded the stall timeout
+     */
+    readonly stalled: boolean;
     mentor_config: LtiMentorCourseXBlock;
     /**
      * Platform key the requesting user belongs to
      */
     platform_key: string;
+    /**
+     * When True, triggers an async create and reponds with a 202 instead of 201
+     */
+    async_create?: boolean;
 };
 

package/src/models/MentorInteractions.ts

@@ -3,8 +3,53 @@
 /* tslint:disable */
 /* eslint-disable */
 export type MentorInteractions = {
+    /**
+     * Total conversations the user has started with this agent, including empty ones.
+     */
+    session_count: number;
+    /**
+     * Conversations that had real back-and-forth (at least one user message and one agent reply). Always less than or equal to session_count.
+     */
+    conversation_count: number;
+    /**
+     * Total messages the user sent to this agent across all conversations.
+     */
+    message_count_human: number;
+    /**
+     * Total replies this agent sent to the user across all conversations.
+     */
+    message_count_ai: number;
+    /**
+     * Sum of user and agent messages exchanged with this agent.
+     */
     total_messages: number;
+    /**
+     * Average messages per conversation (total_messages / session_count); 0 with no conversations.
+     */
+    avg_messages_per_session: number;
+    /**
+     * When the user first messaged this agent.
+     */
+    first_interaction?: string | null;
+    /**
+     * When the user most recently interacted with this agent.
+     */
     latest_interaction?: string | null;
+    /**
+     * Number of distinct calendar days the user exchanged messages with this agent.
+     */
+    active_days: number;
+    /**
+     * Total amount the user has spent on this agent, in USD.
+     */
+    cost_usd?: string | null;
+    /**
+     * Rating the user gave this agent.
+     */
     rating?: number | null;
+    /**
+     * Whether the user has favorited (starred) this agent.
+     */
+    is_starred?: boolean;
 };
 

package/src/models/UserInfo.ts

@@ -13,5 +13,9 @@ export type UserInfo = {
     is_active?: boolean;
     last_active?: string;
     date_joined?: string;
+    /**
+     * Total amount the user has spent across all agents, in USD. May be slightly higher than the sum of the per-agent cost_usd values.
+     */
+    total_agent_cost_usd?: string | null;
 };