@thinkai/tai-api-contract 2.49.0 → 2.51.0-pr.877.bf4a3821

package/openapi/openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.0.3
 info:
   title: ThinkAI API
-  version: 2.49.0
+  version: 2.51.0
   description: >
     Contract surface for the AI Driven SDLC backend used by ThinkAI.
     Workspace-scoped routes use `/workspaces/{workspaceId}/...`.
@@ -1933,13 +1933,9 @@ paths:
       operationId: getAiUsageSpendAggregatedTeams
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
-        - name: rangeId
-          in: query
-          description: Measure time range (maps to weekly bucket count).
-          schema:
-            type: string
-            enum: [4w, 8w, q]
-            default: 4w
+        - $ref: "#/components/parameters/InsightsProductivityRangeId"
+        - $ref: "#/components/parameters/InsightsProductivityFrom"
+        - $ref: "#/components/parameters/InsightsProductivityTo"
         - $ref: "#/components/parameters/InsightsDepartmentFilter"
         - name: team
           in: query
@@ -1988,13 +1984,9 @@ paths:
       operationId: getAiUsageSpendAggregatedContributors
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
-        - name: rangeId
-          in: query
-          description: Measure time range (maps to weekly bucket count).
-          schema:
-            type: string
-            enum: [4w, 8w, q]
-            default: 4w
+        - $ref: "#/components/parameters/InsightsProductivityRangeId"
+        - $ref: "#/components/parameters/InsightsProductivityFrom"
+        - $ref: "#/components/parameters/InsightsProductivityTo"
         - $ref: "#/components/parameters/InsightsDepartmentFilter"
         - name: team
           in: query
@@ -2042,13 +2034,9 @@ paths:
       operationId: getAiUsageSpendContributorToolHeatmap
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
-        - name: rangeId
-          in: query
-          description: Measure time range (maps to weekly bucket count).
-          schema:
-            type: string
-            enum: [4w, 8w, q]
-            default: 4w
+        - $ref: "#/components/parameters/InsightsProductivityRangeId"
+        - $ref: "#/components/parameters/InsightsProductivityFrom"
+        - $ref: "#/components/parameters/InsightsProductivityTo"
         - $ref: "#/components/parameters/InsightsDepartmentFilter"
         - name: team
           in: query
@@ -2096,13 +2084,9 @@ paths:
       operationId: getAiUsageSpendKeyInsights
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
-        - name: rangeId
-          in: query
-          description: Measure time range (maps to weekly bucket count).
-          schema:
-            type: string
-            enum: [4w, 8w, q]
-            default: 4w
+        - $ref: "#/components/parameters/InsightsProductivityRangeId"
+        - $ref: "#/components/parameters/InsightsProductivityFrom"
+        - $ref: "#/components/parameters/InsightsProductivityTo"
         - $ref: "#/components/parameters/InsightsDepartmentFilter"
         - name: team
           in: query
@@ -2145,21 +2129,69 @@ paths:
       summary: AI usage & spend insights — AI-assisted code percentage
       description: >
         Period and weekly AI-assisted code percentage for the Measure **AI-assisted code**
-        card on `/phase-c/c7` and the **AI impact** curve on `/phase-c/c4`. When scoped
-        productivity metrics include `aiAssistedContributionRatioPercent`, values are
-        **measured** from ingest; otherwise the API falls back to token→LOC heuristics and
-        sets `dataQuality` to **estimated**. Clients should not present estimated series as
-        Cursor-measured signal.
+        card on `/phase-c/c7` and the **AI impact** curve on `/phase-c/c4`. When engagement
+        daily rows exist for the scope, values are **measured** from Σ `ai_lines_added` ÷
+        merged-PR lines (`dashboard_metrics`); otherwise the API falls back to token→LOC
+        heuristics and sets `dataQuality` to **estimated**. Clients should not present
+        estimated series as editor-measured signal.
       operationId: getAiUsageSpendAiAssistedCodePercentage
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
-        - name: rangeId
+        - $ref: "#/components/parameters/InsightsProductivityRangeId"
+        - $ref: "#/components/parameters/InsightsProductivityFrom"
+        - $ref: "#/components/parameters/InsightsProductivityTo"
+        - $ref: "#/components/parameters/InsightsDepartmentFilter"
+        - name: team
           in: query
-          description: Measure time range (maps to weekly bucket count).
+          description: Team name filter; send `All teams` to include every team.
           schema:
             type: string
-            enum: [4w, 8w, q]
-            default: 4w
+            default: All teams
+        - name: windowEnd
+          in: query
+          description: ISO timestamp for the end of the last weekly bucket; omit for current week.
+          schema:
+            type: string
+            format: date-time
+      responses:
+        "200":
+          description: AI-assisted code percentage series
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AiUsageSpendAiAssistedCodePercentageDto"
+        "400":
+          description: Invalid query parameters
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [error]
+                properties:
+                  error: { type: string, example: invalid_query }
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace does not exist or malformed workspaceId
+
+  /workspaces/{workspaceId}/insights/ai-usage-spend/provider-engagement-insights:
+    get:
+      tags: [Workspace]
+      summary: AI usage & spend insights — provider engagement cards
+      description: >
+        Provider-specific engagement insight metrics derived from
+        `tai_workspace_ai_tool_engagement_daily` (accepted AI lines, tab completions,
+        suggestion accept rates, Claude Code sessions, etc.). Metrics are
+        **provider- and data-gated**: structurally absent signals render as N/A, not zero.
+        Claude per-user cards require Enterprise Analytics (`insightsPlan` ≠ team).
+      operationId: getAiUsageSpendProviderEngagementInsights
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - $ref: "#/components/parameters/InsightsProductivityRangeId"
+        - $ref: "#/components/parameters/InsightsProductivityFrom"
+        - $ref: "#/components/parameters/InsightsProductivityTo"
         - $ref: "#/components/parameters/InsightsDepartmentFilter"
         - name: team
           in: query
@@ -2173,13 +2205,33 @@ paths:
           schema:
             type: string
             format: date-time
+        - name: memberExternalId
+          in: query
+          description: >
+            When set, aggregate engagement metrics for a single AI-tool member
+            (user detail pages). Mutually exclusive with `scopeTeamId`.
+          schema:
+            type: string
+        - name: scopeTeamId
+          in: query
+          description: >
+            Org-chart team id — aggregate engagement for members mapped to that team
+            (team detail pages). Mutually exclusive with `memberExternalId`.
+          schema:
+            type: string
+        - name: provider
+          in: query
+          description: Optional provider id filter (`cursor`, `claude`) for detail pages.
+          schema:
+            type: string
+            enum: [cursor, claude]
       responses:
         "200":
-          description: AI-assisted code percentage series
+          description: Provider engagement insight cards
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/AiUsageSpendAiAssistedCodePercentageDto"
+                $ref: "#/components/schemas/AiUsageSpendProviderEngagementInsightsDto"
         "400":
           description: Invalid query parameters
           content:
@@ -2210,13 +2262,9 @@ paths:
       operationId: getAiUsageSpendAiToolUsageSpend
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
-        - name: rangeId
-          in: query
-          description: Measure time range (maps to weekly bucket count).
-          schema:
-            type: string
-            enum: [4w, 8w, q]
-            default: 4w
+        - $ref: "#/components/parameters/InsightsProductivityRangeId"
+        - $ref: "#/components/parameters/InsightsProductivityFrom"
+        - $ref: "#/components/parameters/InsightsProductivityTo"
         - $ref: "#/components/parameters/InsightsDepartmentFilter"
         - name: team
           in: query
@@ -2265,13 +2313,9 @@ paths:
       operationId: getAiUsageSpendTeamToolHeatmap
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
-        - name: rangeId
-          in: query
-          description: Measure time range (maps to weekly bucket count).
-          schema:
-            type: string
-            enum: [4w, 8w, q]
-            default: 4w
+        - $ref: "#/components/parameters/InsightsProductivityRangeId"
+        - $ref: "#/components/parameters/InsightsProductivityFrom"
+        - $ref: "#/components/parameters/InsightsProductivityTo"
         - $ref: "#/components/parameters/InsightsDepartmentFilter"
         - name: team
           in: query
@@ -2320,13 +2364,9 @@ paths:
       operationId: getAiUsageSpendRoiProductivitySignal
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
-        - name: rangeId
-          in: query
-          description: Measure time range (maps to weekly bucket count).
-          schema:
-            type: string
-            enum: [4w, 8w, q]
-            default: 4w
+        - $ref: "#/components/parameters/InsightsProductivityRangeId"
+        - $ref: "#/components/parameters/InsightsProductivityFrom"
+        - $ref: "#/components/parameters/InsightsProductivityTo"
         - $ref: "#/components/parameters/InsightsDepartmentFilter"
         - name: team
           in: query
@@ -2376,13 +2416,9 @@ paths:
       operationId: getAiUsageSpendUsageTrends
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
-        - name: rangeId
-          in: query
-          description: Measure time range (maps to weekly bucket count).
-          schema:
-            type: string
-            enum: [4w, 8w, q]
-            default: 4w
+        - $ref: "#/components/parameters/InsightsProductivityRangeId"
+        - $ref: "#/components/parameters/InsightsProductivityFrom"
+        - $ref: "#/components/parameters/InsightsProductivityTo"
         - $ref: "#/components/parameters/InsightsDepartmentFilter"
         - name: team
           in: query
@@ -7768,6 +7804,41 @@ components:
           items:
             $ref: "#/components/schemas/ProductivityInsightsNeedsAttentionItemDto"
 
+    AiUsageSpendGranularity:
+      type: string
+      enum: [day, week]
+      description: >
+        Echo of the resolved time bucket for this response. `day` when the request used an
+        `Nd`/`cr:`/`from`+`to` window; `week` for legacy weekly rangeIds.
+
+    AiUsageSpendRangeId:
+      type: string
+      description: >
+        Daily windows: `7d`, `30d`, `90d`, `180d`, or custom `cr:YYYY-MM-DD:YYYY-MM-DD`.
+        Weekly legacy: `4w`, `8w`, `q` (12 weeks), `12w`, `16w`.
+
+    AiUsageSpendDailyBucketDto:
+      type: object
+      additionalProperties: false
+      required: [date, tokenCount, spendCents, activeUsers]
+      properties:
+        date:
+          type: string
+          format: date
+          description: UTC calendar day (`YYYY-MM-DD`).
+        dayLabel:
+          type: string
+          description: Short label for table headers (e.g. MM/DD).
+        tokenCount:
+          type: integer
+          minimum: 0
+        spendCents:
+          type: integer
+          minimum: 0
+        activeUsers:
+          type: integer
+          minimum: 0
+
     AiUsageSpendAggregatedTeamWeekDto:
       type: object
       additionalProperties: false
@@ -7798,7 +7869,7 @@ components:
     AiUsageSpendAggregatedTeamRowDto:
       type: object
       additionalProperties: false
-      required: [teamId, teamName, headcount, weeks]
+      required: [teamId, teamName, headcount]
       properties:
         teamId:
           type: string
@@ -7809,6 +7880,11 @@ components:
           minimum: 0
         managerLabel:
           type: string
+        days:
+          type: array
+          description: Present in day-mode responses — daily token, spend, and active-user counts.
+          items:
+            $ref: "#/components/schemas/AiUsageSpendDailyBucketDto"
         weeks:
           type: array
           items:
@@ -7848,8 +7924,17 @@ components:
           type: string
           format: uuid
         range:
+          $ref: "#/components/schemas/AiUsageSpendRangeId"
+        granularity:
+          $ref: "#/components/schemas/AiUsageSpendGranularity"
+        from:
+          type: string
+          format: date
+          description: Inclusive start day when `granularity` is `day`.
+        to:
           type: string
-          enum: [4w, 8w, q]
+          format: date
+          description: Inclusive end day when `granularity` is `day`.
         scope:
           $ref: "#/components/schemas/ProductivityInsightsAggregatedTeamsScopeDto"
         generatedAt:
@@ -7865,7 +7950,7 @@ components:
     AiUsageSpendAggregatedContributorRowDto:
       type: object
       additionalProperties: false
-      required: [contributorId, contributorName, weeks]
+      required: [contributorId, contributorName]
       properties:
         contributorId:
           type: string
@@ -7878,6 +7963,11 @@ components:
           type: string
         department:
           type: string
+        days:
+          type: array
+          description: Present in day-mode responses — daily token, spend, and active-user counts.
+          items:
+            $ref: "#/components/schemas/AiUsageSpendDailyBucketDto"
         weeks:
           type: array
           items:
@@ -7892,8 +7982,17 @@ components:
           type: string
           format: uuid
         range:
+          $ref: "#/components/schemas/AiUsageSpendRangeId"
+        granularity:
+          $ref: "#/components/schemas/AiUsageSpendGranularity"
+        from:
           type: string
-          enum: [4w, 8w, q]
+          format: date
+          description: Inclusive start day when `granularity` is `day`.
+        to:
+          type: string
+          format: date
+          description: Inclusive end day when `granularity` is `day`.
         scope:
           $ref: "#/components/schemas/ProductivityInsightsAggregatedTeamsScopeDto"
         generatedAt:
@@ -7920,8 +8019,17 @@ components:
           type: string
           format: uuid
         range:
+          $ref: "#/components/schemas/AiUsageSpendRangeId"
+        granularity:
+          $ref: "#/components/schemas/AiUsageSpendGranularity"
+        from:
+          type: string
+          format: date
+          description: Inclusive start day when `granularity` is `day`.
+        to:
           type: string
-          enum: [4w, 8w, q]
+          format: date
+          description: Inclusive end day when `granularity` is `day`.
         scope:
           $ref: "#/components/schemas/ProductivityInsightsAggregatedTeamsScopeDto"
         generatedAt:
@@ -7956,8 +8064,17 @@ components:
           type: string
           format: uuid
         range:
+          $ref: "#/components/schemas/AiUsageSpendRangeId"
+        granularity:
+          $ref: "#/components/schemas/AiUsageSpendGranularity"
+        from:
+          type: string
+          format: date
+          description: Inclusive start day when `granularity` is `day`.
+        to:
           type: string
-          enum: [4w, 8w, q]
+          format: date
+          description: Inclusive end day when `granularity` is `day`.
         scope:
           $ref: "#/components/schemas/ProductivityInsightsAggregatedTeamsScopeDto"
         generatedAt:
@@ -7985,6 +8102,33 @@ components:
         to proxy tokens when usage rows omit counts; **adoption** — active AI-tool users vs org
         headcount; **unavailable** — no usable signal for the selected scope.
 
+    AiUsageSpendAiAssistedCodeDayDto:
+      type: object
+      additionalProperties: false
+      required:
+        [date, aiAssistedCodePercent, totalLoc, aiLoc, humanLoc, dataQuality]
+      properties:
+        date:
+          type: string
+          format: date
+        dayLabel:
+          type: string
+        aiAssistedCodePercent:
+          type: number
+          minimum: 0
+          maximum: 100
+        totalLoc:
+          type: integer
+          minimum: 0
+        aiLoc:
+          type: integer
+          minimum: 0
+        humanLoc:
+          type: integer
+          minimum: 0
+        dataQuality:
+          $ref: "#/components/schemas/AiAssistedCodeDataQuality"
+
     AiUsageSpendAiAssistedCodeWeekDto:
       type: object
       additionalProperties: false
@@ -8037,14 +8181,22 @@ components:
         - aiLoc
         - humanLoc
         - dataQuality
-        - weeks
       properties:
         workspaceId:
           type: string
           format: uuid
         range:
+          $ref: "#/components/schemas/AiUsageSpendRangeId"
+        granularity:
+          $ref: "#/components/schemas/AiUsageSpendGranularity"
+        from:
+          type: string
+          format: date
+          description: Inclusive start day when `granularity` is `day`.
+        to:
           type: string
-          enum: [4w, 8w, q]
+          format: date
+          description: Inclusive end day when `granularity` is `day`.
         scope:
           $ref: "#/components/schemas/ProductivityInsightsAggregatedTeamsScopeDto"
         generatedAt:
@@ -8089,11 +8241,85 @@ components:
           type: integer
           minimum: 0
           description: Scoped AI-tool spend in cents for the selected period.
+        days:
+          type: array
+          description: Present in day-mode responses — daily AI-assisted code share series.
+          items:
+            $ref: "#/components/schemas/AiUsageSpendAiAssistedCodeDayDto"
         weeks:
           type: array
           items:
             $ref: "#/components/schemas/AiUsageSpendAiAssistedCodeWeekDto"
 
+    ProviderEngagementInsightAvailability:
+      type: string
+      enum: [measured, not_applicable]
+
+    AiUsageSpendProviderEngagementMetricDto:
+      type: object
+      additionalProperties: false
+      required: [id, label, value, displayValue, availability]
+      properties:
+        id:
+          type: string
+        label:
+          type: string
+        value:
+          type: number
+          nullable: true
+        displayValue:
+          type: string
+        availability:
+          $ref: "#/components/schemas/ProviderEngagementInsightAvailability"
+        unit:
+          type: string
+        methodologyNote:
+          type: string
+
+    AiUsageSpendProviderEngagementCardDto:
+      type: object
+      additionalProperties: false
+      required: [providerId, providerName, metrics]
+      properties:
+        providerId:
+          type: string
+        providerName:
+          type: string
+        metrics:
+          type: array
+          items:
+            $ref: "#/components/schemas/AiUsageSpendProviderEngagementMetricDto"
+
+    AiUsageSpendProviderEngagementInsightsDto:
+      type: object
+      additionalProperties: false
+      required: [workspaceId, range, scope, generatedAt, providers]
+      properties:
+        workspaceId:
+          type: string
+          format: uuid
+        range:
+          $ref: "#/components/schemas/AiUsageSpendRangeId"
+        granularity:
+          $ref: "#/components/schemas/AiUsageSpendGranularity"
+        from:
+          type: string
+          format: date
+          description: Inclusive start day when `granularity` is `day`.
+        to:
+          type: string
+          format: date
+          description: Inclusive end day when `granularity` is `day`.
+        scope:
+          $ref: "#/components/schemas/ProductivityInsightsAggregatedTeamsScopeDto"
+        generatedAt:
+          type: string
+          format: date-time
+        providers:
+          type: array
+          items:
+            $ref: "#/components/schemas/AiUsageSpendProviderEngagementCardDto"
+
     AiUsageSpendAiToolUsageSpendProviderItemDto:
       type: object
       additionalProperties: false
@@ -8147,8 +8373,17 @@ components:
           type: string
           format: uuid
         range:
+          $ref: "#/components/schemas/AiUsageSpendRangeId"
+        granularity:
+          $ref: "#/components/schemas/AiUsageSpendGranularity"
+        from:
           type: string
-          enum: [4w, 8w, q]
+          format: date
+          description: Inclusive start day when `granularity` is `day`.
+        to:
+          type: string
+          format: date
+          description: Inclusive end day when `granularity` is `day`.
         scope:
           $ref: "#/components/schemas/ProductivityInsightsAggregatedTeamsScopeDto"
         generatedAt:
@@ -8180,8 +8415,17 @@ components:
           type: string
           format: uuid
         range:
+          $ref: "#/components/schemas/AiUsageSpendRangeId"
+        granularity:
+          $ref: "#/components/schemas/AiUsageSpendGranularity"
+        from:
+          type: string
+          format: date
+          description: Inclusive start day when `granularity` is `day`.
+        to:
           type: string
-          enum: [4w, 8w, q]
+          format: date
+          description: Inclusive end day when `granularity` is `day`.
         scope:
           $ref: "#/components/schemas/ProductivityInsightsAggregatedTeamsScopeDto"
         generatedAt:
@@ -8192,6 +8436,23 @@ components:
           items:
             $ref: "#/components/schemas/AiUsageSpendAggregatedTeamRowDto"
 
+    AiUsageSpendRoiProductivitySignalDayDto:
+      type: object
+      additionalProperties: false
+      required: [date, mergedPrCount, tokenCount]
+      properties:
+        date:
+          type: string
+          format: date
+        dayLabel:
+          type: string
+        mergedPrCount:
+          type: integer
+          minimum: 0
+        tokenCount:
+          type: integer
+          minimum: 0
+
     AiUsageSpendRoiProductivitySignalWeekDto:
       type: object
       additionalProperties: false
@@ -8229,14 +8490,22 @@ components:
         - aiAssistedPrRatio
         - prThroughputDeltaPercent
         - usageDeltaPercent
-        - weeks
       properties:
         workspaceId:
           type: string
           format: uuid
         range:
+          $ref: "#/components/schemas/AiUsageSpendRangeId"
+        granularity:
+          $ref: "#/components/schemas/AiUsageSpendGranularity"
+        from:
+          type: string
+          format: date
+          description: Inclusive start day when `granularity` is `day`.
+        to:
           type: string
-          enum: [4w, 8w, q]
+          format: date
+          description: Inclusive end day when `granularity` is `day`.
         scope:
           $ref: "#/components/schemas/ProductivityInsightsAggregatedTeamsScopeDto"
         generatedAt:
@@ -8265,11 +8534,35 @@ components:
         usageDeltaPercent:
           type: number
           description: Percent change in token usage (recent half vs prior half of range).
+        days:
+          type: array
+          description: Present in day-mode responses — daily merged PR and token counts.
+          items:
+            $ref: "#/components/schemas/AiUsageSpendRoiProductivitySignalDayDto"
         weeks:
           type: array
           items:
             $ref: "#/components/schemas/AiUsageSpendRoiProductivitySignalWeekDto"
 
+    AiUsageSpendUsageTrendsProviderDayDto:
+      type: object
+      additionalProperties: false
+      required: [providerId, providerName, spendCents, tokenCount, activeUsers]
+      properties:
+        providerId:
+          type: string
+        providerName:
+          type: string
+        spendCents:
+          type: integer
+          minimum: 0
+        tokenCount:
+          type: integer
+          minimum: 0
+        activeUsers:
+          type: integer
+          minimum: 0
+
     AiUsageSpendUsageTrendsProviderWeekDto:
       type: object
       additionalProperties: false
@@ -8289,6 +8582,21 @@ components:
           type: integer
           minimum: 0
 
+    AiUsageSpendUsageTrendsDayDto:
+      type: object
+      additionalProperties: false
+      required: [date, providers]
+      properties:
+        date:
+          type: string
+          format: date
+        dayLabel:
+          type: string
+        providers:
+          type: array
+          items:
+            $ref: "#/components/schemas/AiUsageSpendUsageTrendsProviderDayDto"
+
     AiUsageSpendUsageTrendsWeekDto:
       type: object
       additionalProperties: false
@@ -8310,19 +8618,33 @@ components:
     AiUsageSpendUsageTrendsDto:
       type: object
       additionalProperties: false
-      required: [workspaceId, range, scope, generatedAt, weeks]
+      required: [workspaceId, range, scope, generatedAt]
       properties:
         workspaceId:
           type: string
           format: uuid
         range:
+          $ref: "#/components/schemas/AiUsageSpendRangeId"
+        granularity:
+          $ref: "#/components/schemas/AiUsageSpendGranularity"
+        from:
+          type: string
+          format: date
+          description: Inclusive start day when `granularity` is `day`.
+        to:
           type: string
-          enum: [4w, 8w, q]
+          format: date
+          description: Inclusive end day when `granularity` is `day`.
         scope:
           $ref: "#/components/schemas/ProductivityInsightsAggregatedTeamsScopeDto"
         generatedAt:
           type: string
           format: date-time
+        days:
+          type: array
+          description: Present in day-mode responses — per-provider spend and usage by day.
+          items:
+            $ref: "#/components/schemas/AiUsageSpendUsageTrendsDayDto"
         weeks:
           type: array
           items: