From 873a956b6e8596d35672a85e5054927b44ae7ba7 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 24 Oct 2026 09:56:23 +0000 Subject: [PATCH 1/2] docs: Sync the API reference with platform-client 0.24.0 Co-Authored-By: Claude Sonnet 5 --- docs-mintlify/api-reference/api.yaml | 162 ++++++++++++++++++++-- docs-mintlify/api-reference/changelog.mdx | 17 ++- 2 files changed, 165 insertions(+), 14 deletions(-) diff --git a/docs-mintlify/api-reference/api.yaml b/docs-mintlify/api-reference/api.yaml index 54f9dd16245b3..7452c06814528 100644 --- a/docs-mintlify/api-reference/api.yaml +++ b/docs-mintlify/api-reference/api.yaml @@ -9557,8 +9557,10 @@ components: Notify only when: on each fire the measure is read once, before the agent runs, and the agent runs only when the condition starts to hold, with the crossing facts at the top of its thread; it runs again only after the condition has stopped holding. A `change` or - `anomaly` rule needs `timeDimension` and `granularity`. The creator gets an inbox row - only with `notificationEnabled: true`. Omit to run the agent on every fire. + `anomaly` rule needs `timeDimension` and `granularity`. A request that sends + `notification` must leave a task with a condition notifying someone (`400` otherwise); + one that does not, on the deprecated `notificationEnabled` shape, keeps its earlier + behaviour. Omit to run the agent on every fire. oneOf: - $ref: '#/components/schemas/ScheduledTaskCondition' - type: 'null' @@ -9585,10 +9587,21 @@ components: maxLength: 255 minLength: 1 type: string + notification: + description: >- + Who a finished run notifies, and how. Replaces the stored setting. Picked users and + groups are shared the task, view-only, so they can open the run. An id that is not an + active workspace member or a group answers `400`. Wins over `notificationEnabled` when + both are sent. Omit it, and `notificationEnabled`, to notify nobody. + oneOf: + - $ref: '#/components/schemas/ScheduledTaskNotificationInput' + - type: 'null' notificationEnabled: + deprecated: true description: >- - Notify the creator in Cube's notification inbox when a run finishes, whether it succeeds - or fails. Defaults to `false`. + Deprecated: send `notification` instead. `true` adds the creator to `notification` with + Inbox on; `false` takes the creator off it only when they get Inbox, so a creator who + gets only Email keeps it. oneOf: - type: boolean - type: 'null' @@ -16433,6 +16446,93 @@ components: - items - pageInfo type: object + ScheduledTaskNotification: + properties: + channels: + $ref: '#/components/schemas/ScheduledTaskNotificationChannels' + groupIds: + description: >- + User groups whose members are notified by Inbox and Email, as they are when a run + finishes. + items: + type: integer + maxItems: 200 + type: array + optedOutUserIds: + description: >- + Users who unsubscribed from this task's email. Returned only to the task's creator or an + admin. + oneOf: + - items: + type: integer + type: array + - type: 'null' + slackChannels: + items: + $ref: '#/components/schemas/ScheduledTaskSlackChannel' + maxItems: 50 + type: array + userIds: + description: >- + The users notified by Inbox and Email. The creator is notified only when listed here. A + failed run notifies only the creator. + items: + type: integer + maxItems: 1000 + type: array + required: + - channels + - userIds + - groupIds + - slackChannels + type: object + ScheduledTaskNotificationChannels: + properties: + email: + description: Email, for the picked people. Each email carries an unsubscribe link. + type: boolean + inbox: + description: Cube's notification inbox, for the picked people. + type: boolean + slack: + description: One Slack post to each of `slackChannels`. + type: boolean + required: + - inbox + - email + - slack + type: object + ScheduledTaskNotificationInput: + properties: + channels: + $ref: '#/components/schemas/ScheduledTaskNotificationChannels' + groupIds: + description: >- + User groups whose members are notified by Inbox and Email, as they are when a run + finishes. + items: + type: integer + maxItems: 200 + type: array + slackChannels: + items: + $ref: '#/components/schemas/ScheduledTaskSlackChannel' + maxItems: 50 + type: array + userIds: + description: >- + The users notified by Inbox and Email. The creator is notified only when listed here. A + failed run notifies only the creator. + items: + type: integer + maxItems: 1000 + type: array + required: + - channels + - userIds + - groupIds + - slackChannels + type: object ScheduledTaskResponse: properties: agentId: @@ -16445,8 +16545,10 @@ components: Notify only when: on each fire the measure is read once, before the agent runs, and the agent runs only when the condition starts to hold, with the crossing facts at the top of its thread; it runs again only after the condition has stopped holding. A `change` or - `anomaly` rule needs `timeDimension` and `granularity`. The creator gets an inbox row - only with `notificationEnabled: true`. Null runs the agent on every fire. + `anomaly` rule needs `timeDimension` and `granularity`. A request that sends + `notification` must leave a task with a condition notifying someone (`400` otherwise); + one that does not, on the deprecated `notificationEnabled` shape, keeps its earlier + behaviour. Null runs the agent on every fire. oneOf: - $ref: '#/components/schemas/ScheduledTaskCondition' - type: 'null' @@ -16481,8 +16583,14 @@ components: oneOf: - type: string - type: 'null' + notification: + $ref: '#/components/schemas/ScheduledTaskNotification' + description: Who a finished run notifies, and how. notificationEnabled: - description: Whether a finished run notifies the creator in Cube's notification inbox. + deprecated: true + description: >- + Deprecated: read `notification` instead. Whether a finished run notifies the creator in + Cube's notification inbox. type: boolean prompt: description: >- @@ -16505,6 +16613,7 @@ components: - timezone - isEnabled - notificationEnabled + - notification - userId type: object ScheduledTaskRunResponse: @@ -16537,6 +16646,22 @@ components: - items - pageInfo type: object + ScheduledTaskSlackChannel: + properties: + id: + description: The Slack channel id, e.g. `C0123ABC`. + maxLength: 64 + minLength: 1 + type: string + name: + description: The channel name, without `#`. + maxLength: 255 + minLength: 1 + type: string + required: + - id + - name + type: object SetBranchStagingEnvironmentRequest: properties: branchId: @@ -17667,9 +17792,11 @@ components: Notify only when: on each fire the measure is read once, before the agent runs, and the agent runs only when the condition starts to hold, with the crossing facts at the top of its thread; it runs again only after the condition has stopped holding. A `change` or - `anomaly` rule needs `timeDimension` and `granularity`. The creator gets an inbox row - only with `notificationEnabled: true`. Omit to leave unchanged; null removes it. A - changed condition starts its breach state fresh. + `anomaly` rule needs `timeDimension` and `granularity`. A request that sends + `notification` must leave a task with a condition notifying someone (`400` otherwise); + one that does not, on the deprecated `notificationEnabled` shape, keeps its earlier + behaviour. Omit to leave unchanged; null removes it. A changed condition starts its + breach state fresh. oneOf: - $ref: '#/components/schemas/ScheduledTaskCondition' - type: 'null' @@ -17700,10 +17827,21 @@ components: type: string minLength: 1 - type: 'null' + notification: + description: >- + Who a finished run notifies, and how. Replaces the stored setting. Picked users and + groups are shared the task, view-only, so they can open the run. An id that is not an + active workspace member or a group answers `400`. Wins over `notificationEnabled` when + both are sent. Omit to leave unchanged. Explicit null answers `400`. + oneOf: + - $ref: '#/components/schemas/ScheduledTaskNotificationInput' + - type: 'null' notificationEnabled: + deprecated: true description: >- - Turn the inbox notification for finished runs on or off. Omit to leave unchanged. - Explicit null answers `400`. + Deprecated: send `notification` instead. `true` adds the creator to `notification` with + Inbox on; `false` takes the creator off it only when they get Inbox, so a creator who + gets only Email keeps it. Omit to leave unchanged. Explicit null answers `400`. oneOf: - type: boolean - type: 'null' diff --git a/docs-mintlify/api-reference/changelog.mdx b/docs-mintlify/api-reference/changelog.mdx index 18a30b6864918..52386a33af494 100644 --- a/docs-mintlify/api-reference/changelog.mdx +++ b/docs-mintlify/api-reference/changelog.mdx @@ -7,6 +7,17 @@ rss: true {/* GENERATED FILE — do not edit by hand. */} {/* Run scripts/extract-changelog.mjs against the platform client CHANGELOG.md. */} + + ### Added + + - `notification` on the create and update scheduled task requests (`POST /api/v1/deployments/{deploymentId}/scheduled-tasks` and its update operation) chooses who a finished run notifies: users (`userIds`), user groups (`groupIds`) and Slack channels (`slackChannels`), over Inbox, Email and Slack (`channels`). Picked users and groups are shared the task view-only. An id that is not an active workspace member or a group answers `400`. The scheduled task response returns `notification`, and `optedOutUserIds` for the task's creator or an admin. + + ### Changed + + - `notificationEnabled` on scheduled tasks is deprecated; send and read `notification` instead. When both are sent, `notification` wins. + - A scheduled task request that sends `notification` and sets a condition must notify someone, or it answers `400`. + + ### Changed @@ -44,10 +55,12 @@ rss: true - `GET /api/v1/users/{id}/roles` (`UsersAdminPublicController.getUserRoles`) lists every role a user holds, built-in and custom, whether assigned directly or through a group. Each role carries `direct` and `groupIds`, so you can tell whether `DELETE /api/v1/roles/{roleId}/users/{userId}` will remove it, and the response reports `isAdmin`. Administrator privileges required. New schemas: `UserRolesResponse`, `UserRoleAssignmentResponse`. - `GET /api/v1/roles/{roleId}/users` (`RolesPublicController.getRoleHolders`) lists the users holding a role, directly or through a group, with cursor pagination. It accepts built-in role ids, includes deactivated users, and returns each user's full set of roles, so a combination such as "holds Explorer but not my custom role" is one pass over the pages. Administrator privileges required. New schemas: `RoleHolder`, `RoleHoldersListResponse`. - - `condition` on scheduled tasks (`CreateScheduledTaskInput`, `UpdateScheduledTaskInput`, `ScheduledTaskResponse`): run the agent only when a measure crosses a `threshold`, moves by a `change` percentage, or is flagged as an `anomaly`, instead of on every fire. `ScheduledTaskResponse.lastConditionCheck` reports the latest check. Send `condition: null` on update to remove it. New schemas: `ScheduledTaskCondition`, `ScheduledTaskLastConditionCheck`. + - `condition` on scheduled tasks (`CreateScheduledTaskInput`, `UpdateScheduledTaskInput`, `ScheduledTaskResponse`): run the agent only when a measure crosses a `threshold`, moves by a `change` percentage, or turns `anomaly`-ous, instead of on every fire. `ScheduledTaskResponse.lastConditionCheck` reports the latest check. Send `condition: null` on update to remove it. New schemas: `ScheduledTaskCondition`, `ScheduledTaskLastConditionCheck`. + - `securityContext` on the body of the start-eval-run operation: evaluate under a security context merged over the caller's own. + - `agentResponse`, `agentSql`, `groundTruthSql`, `analysis` and `scoreReasons` on `EvaluationResultResponse`, so a result explains why a question failed or needs review. - `pdf_print` for `notificationFormat` on `CreateNotificationInput` and `UpdateNotificationInput`: deliver the paginated print version of a dashboard. - `in_month`, `not_in_month`, `in_quarter`, `not_in_quarter`, `in_year` and `not_in_year` dashboard filter operators. - - `memory.generateFromChats` on `UserSettingsInput`: let a user turn off background memory from their chats. + - `memory.generateFromChats` on `UserSettingsInput`, and `memoryGenerationEnabled` in the settings response: let a user turn off background memory from their chats. ### Changed From a72595df6847303c9b533b246566f1c66c6723ff Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 24 Oct 2026 09:58:23 +0000 Subject: [PATCH 2/2] docs: Keep existing API changelog entries, add only v0.24.0 Co-Authored-By: Claude Sonnet 5 --- docs-mintlify/api-reference/changelog.mdx | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/docs-mintlify/api-reference/changelog.mdx b/docs-mintlify/api-reference/changelog.mdx index 52386a33af494..a44a584894abb 100644 --- a/docs-mintlify/api-reference/changelog.mdx +++ b/docs-mintlify/api-reference/changelog.mdx @@ -55,12 +55,10 @@ rss: true - `GET /api/v1/users/{id}/roles` (`UsersAdminPublicController.getUserRoles`) lists every role a user holds, built-in and custom, whether assigned directly or through a group. Each role carries `direct` and `groupIds`, so you can tell whether `DELETE /api/v1/roles/{roleId}/users/{userId}` will remove it, and the response reports `isAdmin`. Administrator privileges required. New schemas: `UserRolesResponse`, `UserRoleAssignmentResponse`. - `GET /api/v1/roles/{roleId}/users` (`RolesPublicController.getRoleHolders`) lists the users holding a role, directly or through a group, with cursor pagination. It accepts built-in role ids, includes deactivated users, and returns each user's full set of roles, so a combination such as "holds Explorer but not my custom role" is one pass over the pages. Administrator privileges required. New schemas: `RoleHolder`, `RoleHoldersListResponse`. - - `condition` on scheduled tasks (`CreateScheduledTaskInput`, `UpdateScheduledTaskInput`, `ScheduledTaskResponse`): run the agent only when a measure crosses a `threshold`, moves by a `change` percentage, or turns `anomaly`-ous, instead of on every fire. `ScheduledTaskResponse.lastConditionCheck` reports the latest check. Send `condition: null` on update to remove it. New schemas: `ScheduledTaskCondition`, `ScheduledTaskLastConditionCheck`. - - `securityContext` on the body of the start-eval-run operation: evaluate under a security context merged over the caller's own. - - `agentResponse`, `agentSql`, `groundTruthSql`, `analysis` and `scoreReasons` on `EvaluationResultResponse`, so a result explains why a question failed or needs review. + - `condition` on scheduled tasks (`CreateScheduledTaskInput`, `UpdateScheduledTaskInput`, `ScheduledTaskResponse`): run the agent only when a measure crosses a `threshold`, moves by a `change` percentage, or is flagged as an `anomaly`, instead of on every fire. `ScheduledTaskResponse.lastConditionCheck` reports the latest check. Send `condition: null` on update to remove it. New schemas: `ScheduledTaskCondition`, `ScheduledTaskLastConditionCheck`. - `pdf_print` for `notificationFormat` on `CreateNotificationInput` and `UpdateNotificationInput`: deliver the paginated print version of a dashboard. - `in_month`, `not_in_month`, `in_quarter`, `not_in_quarter`, `in_year` and `not_in_year` dashboard filter operators. - - `memory.generateFromChats` on `UserSettingsInput`, and `memoryGenerationEnabled` in the settings response: let a user turn off background memory from their chats. + - `memory.generateFromChats` on `UserSettingsInput`: let a user turn off background memory from their chats. ### Changed