@vellumai/assistant 0.11.3 → 0.11.4-dev.202608190019.b94dbf2

package/openapi.yaml

@@ -3,7 +3,7 @@
 openapi: 3.1.0
 info:
   title: Vellum Assistant API
-  version: 0.11.3
+  version: 0.11.4
   description: Auto-generated OpenAPI specification for the Vellum Assistant runtime HTTP server.
 servers:
   - url: http://127.0.0.1:7821
@@ -4017,8 +4017,8 @@ paths:
       summary: Get available channels
       description:
         Return the channels this assistant can surface to clients, with display metadata (label, icon, verification
-        capability, setup copy). Today this is a fixed base list plus `email` when an inbox is registered; will become
-        plugin/skill-driven in future.
+        capability, setup copy). A fixed base list plus `email` when an inbox is registered, plus the channels installed
+        plugins bring by declaring ingress routes. Each carries a `source` saying which of those it is.
       tags:
         - channels
       responses:
@@ -4036,16 +4036,9 @@ paths:
                       properties:
                         id:
                           type: string
-                          enum:
-                            - telegram
-                            - phone
-                            - vellum
-                            - whatsapp
-                            - slack
-                            - email
-                            - platform
-                            - a2a
-                            - discord
+                        source:
+                          type: string
+                          description: "`default` for a channel the assistant ships, `plugin:<name>` for one an installed plugin brings"
                         label:
                           type: string
                         subtitle:
@@ -4067,13 +4060,16 @@ paths:
                           additionalProperties: false
                       required:
                         - id
+                        - source
                         - label
                         - subtitle
                         - icon
                         - supportsVerification
                         - setupMessages
                       additionalProperties: false
-                    description: Available channels in display order
+                    description:
+                      "Available channels in display order: the ones the assistant ships, then the ones installed plugins bring
+                      by declaring ingress routes. `source` distinguishes them."
                 required:
                   - channels
                 additionalProperties: false
@@ -4358,6 +4354,7 @@ paths:
                             - platform
                             - a2a
                             - discord
+                            - plugin
                         ready:
                           type: boolean
                         setupStatus:
@@ -4448,6 +4445,7 @@ paths:
                     - platform
                     - a2a
                     - discord
+                    - plugin
                 includeRemote:
                   description: Include remote checks (default true)
                   type: boolean
@@ -4478,6 +4476,7 @@ paths:
                             - platform
                             - a2a
                             - discord
+                            - plugin
                         ready:
                           type: boolean
                         setupStatus:
@@ -4827,6 +4826,7 @@ paths:
                     - gemini
                     - fireworks
                     - openrouter
+                    - chatgpt
                     - vellum
                     - together
                     - vercel-ai-gateway
@@ -6582,6 +6582,7 @@ paths:
               - platform
               - a2a
               - discord
+              - plugin
           description:
             Filter by origin channel. When provided, only conversations with this exact origin_channel value are
             returned. Omit to include all channels.
@@ -6593,8 +6594,34 @@ paths:
           description:
             Filter to a single group, so each sidebar section can load independently of the paginated list. Pass
             "system:all" for conversations in no group, "system:pinned" for the Pinned section, or a custom group id. A
-            group-scoped request is ordered by the user's arrangement (display order, then recency) and never has pinned
-            rows appended to it. Omit to span every group.
+            group-scoped request is recency-ordered like every list read (COALESCE(last_message_at, updated_at)
+            descending) and never has pinned rows appended to it. Omit to span every group.
+        - name: needsAttention
+          in: query
+          required: false
+          schema:
+            type: string
+            enum:
+              - "true"
+          description:
+            'Pass "true" to return only conversations whose latest assistant message the user has not seen: the same
+            predicate behind the unread count and the section index, so a client that keeps no complete conversation
+            list can ask for exactly the rows its attention surfaces need. Composes with every other filter. Any value
+            other than "true" is rejected. Omit to span every conversation.'
+        - name: foregroundOnly
+          in: query
+          required: false
+          schema:
+            type: string
+            enum:
+              - "true"
+          description:
+            Pass "true" to return only user-facing foreground conversations, dropping the automated background and
+            scheduled runs the standard listing admits when they are filed in a custom group (a surfaced run stays).
+            This is the same predicate the unread count and the section index apply, so a client can ask for the newest
+            conversation a user can open in one row instead of paging past runs it would skip. Composes with every other
+            filter; a foreground-only first page never has pinned rows appended to it. Any value other than "true" is
+            rejected. Omit to keep every visible row.
       responses:
         "200":
           description: Successful response
@@ -6718,6 +6745,7 @@ paths:
                                 - platform
                                 - a2a
                                 - discord
+                                - plugin
                             - type: "null"
                         assistantAttention:
                           type: object
@@ -6951,7 +6979,9 @@ paths:
     get:
       operationId: conversations_by_id_get
       summary: Get conversation detail
-      description: Retrieve a single conversation with full metadata.
+      description:
+        Retrieve a single conversation with full metadata. Rows the listing hides by type (legacy private rows) are
+        not found here either.
       tags:
         - conversations
       parameters:
@@ -7081,6 +7111,7 @@ paths:
                               - platform
                               - a2a
                               - discord
+                              - plugin
                           - type: "null"
                       assistantAttention:
                         type: object
@@ -8294,6 +8325,7 @@ paths:
                               - platform
                               - a2a
                               - discord
+                              - plugin
                           - type: "null"
                       assistantAttention:
                         type: object
@@ -9379,6 +9411,107 @@ paths:
                   - query
                   - results
                 additionalProperties: false
+  /v1/conversations/sections:
+    get:
+      operationId: conversations_sections_get
+      summary: Sidebar section index
+      description:
+        "One row per renderable sidebar section (Pinned, each non-empty custom group, each origin channel with
+        unassigned conversations, Chats) with total and unread counts and no conversation rows. Lets a client know which
+        sections exist, and what their badges say, without fetching any conversation list. Totals follow the standard
+        listing visibility; unread applies the same rules as GET /v1/conversations/unread-count scoped to the section.
+        Chats is always present, even at zero: it is the leftover bucket and renders regardless."
+      tags:
+        - conversations
+      responses:
+        "200":
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  sections:
+                    type: array
+                    items:
+                      oneOf:
+                        - type: object
+                          properties:
+                            kind:
+                              type: string
+                              const: pinned
+                            total:
+                              type: number
+                            unread:
+                              type: number
+                          required:
+                            - kind
+                            - total
+                            - unread
+                          additionalProperties: false
+                        - type: object
+                          properties:
+                            kind:
+                              type: string
+                              const: group
+                            groupId:
+                              type: string
+                            name:
+                              type: string
+                            icon:
+                              anyOf:
+                                - type: string
+                                - type: "null"
+                            sortPosition:
+                              type: number
+                            total:
+                              type: number
+                            unread:
+                              type: number
+                          required:
+                            - kind
+                            - groupId
+                            - name
+                            - icon
+                            - sortPosition
+                            - total
+                            - unread
+                          additionalProperties: false
+                        - type: object
+                          properties:
+                            kind:
+                              type: string
+                              const: channel
+                            channelId:
+                              type: string
+                            total:
+                              type: number
+                            unread:
+                              type: number
+                          required:
+                            - kind
+                            - channelId
+                            - total
+                            - unread
+                          additionalProperties: false
+                        - type: object
+                          properties:
+                            kind:
+                              type: string
+                              const: chats
+                            total:
+                              type: number
+                            unread:
+                              type: number
+                          required:
+                            - kind
+                            - total
+                            - unread
+                          additionalProperties: false
+                      type: object
+                required:
+                  - sections
+                additionalProperties: false
   /v1/conversations/seen:
     post:
       operationId: conversations_seen_post
@@ -10801,11 +10934,6 @@ paths:
                     type: number
                   updatedAt:
                     type: number
-                  workspacePath:
-                    anyOf:
-                      - type: string
-                      - type: "null"
-                    description: Workspace-relative file this document is bound to, or null
                 required:
                   - success
                   - surfaceId
@@ -10815,7 +10943,6 @@ paths:
                   - wordCount
                   - createdAt
                   - updatedAt
-                  - workspacePath
                 additionalProperties: false
   /v1/documents/{id}/comments:
     get:
@@ -11233,74 +11360,6 @@ paths:
               schema:
                 type: string
                 format: binary
-  /v1/documents/for-workspace-file:
-    post:
-      operationId: documents_forworkspacefile_post
-      summary: Get or create the document for a workspace markdown file
-      description:
-        "Return the document bound to a workspace markdown file, creating it on first open. The file is the source
-        of truth at open time: stored content that has drifted from the file is refreshed from disk before the document
-        is returned."
-      tags:
-        - documents
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              type: object
-              properties:
-                path:
-                  type: string
-                  description: Workspace-relative path to a .md/.markdown file
-                conversationId:
-                  type: string
-                  description: Conversation the document is opened from
-              required:
-                - path
-                - conversationId
-      responses:
-        "200":
-          description: Successful response
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  success:
-                    type: boolean
-                  surfaceId:
-                    type: string
-                  conversationId:
-                    type: string
-                  title:
-                    type: string
-                  content:
-                    type: string
-                  wordCount:
-                    type: number
-                  createdAt:
-                    type: number
-                  updatedAt:
-                    type: number
-                  workspacePath:
-                    anyOf:
-                      - type: string
-                      - type: "null"
-                    description: Workspace-relative file this document is bound to, or null
-                required:
-                  - success
-                  - surfaceId
-                  - conversationId
-                  - title
-                  - content
-                  - wordCount
-                  - createdAt
-                  - updatedAt
-                  - workspacePath
-                additionalProperties: false
-        "422":
-          description: Path is not a markdown file
   /v1/domain/register:
     post:
       operationId: domain_register_post
@@ -14832,7 +14891,7 @@ paths:
             type: string
           description:
             "Filter by provider. One of: anthropic, openai, gemini, ollama, fireworks, together, openrouter,
-            vercel-ai-gateway, litellm, openai-compatible, minimax, atlascloud, baseten, poolside, vellum"
+            vercel-ai-gateway, litellm, openai-compatible, minimax, atlascloud, baseten, poolside, vellum, chatgpt"
       responses:
         "200":
           description: Successful response
@@ -21962,6 +22021,7 @@ paths:
                     - platform
                     - a2a
                     - discord
+                    - plugin
                     - scheduler
                     - watcher
                 sourceContextId:
@@ -24335,8 +24395,9 @@ paths:
         non-conflicting edits from both sides forward and resolving conflicting hunks toward the local edit (`ours`) or
         the target (`theirs`), or writing git conflict markers into the file and reporting them in
         `conflicts`/`binaryConflicts` for the assistant to resolve (`assistant`). A merge strategy whose install-time
-        baseline cannot be reconstructed returns 409. Mirrors the CLI''s `assistant plugins upgrade <name> [--strategy
-        <s>]`.'
+        baseline cannot be reconstructed returns 409. Pass `marketplaceOnly` to refuse the untrusted direct path
+        outright (409), which is what the unattended auto-update sweep does. Mirrors the CLI''s `assistant plugins
+        upgrade <name> [--strategy <s>]`.'
       tags:
         - plugins
       parameters:
@@ -24366,6 +24427,13 @@ paths:
                     - theirs
                     - overwrite
                     - assistant
+                marketplaceOnly:
+                  description:
+                    Refuse the upgrade (409) when the marketplace does not claim this plugin, instead of advancing it to
+                    whatever its recorded GitHub ref now resolves to. Set by unattended callers such as the automatic
+                    update sweep, for which running code no curator reviewed is never an acceptable outcome. Defaults to
+                    false.
+                  type: boolean
       responses:
         "200":
           description: Successful response
@@ -24465,8 +24533,9 @@ paths:
           description: No copy of the plugin is installed, or its source resolves to nothing.
         "409":
           description:
-            The install has neither a marketplace entry nor a recorded GitHub source to advance to, or a merge strategy
-            was requested whose install-time baseline cannot be reconstructed.
+            The install has neither a marketplace entry nor a recorded GitHub source to advance to, a `marketplaceOnly`
+            upgrade was requested for an install the marketplace does not claim, or a merge strategy was requested whose
+            install-time baseline cannot be reconstructed.
         "503":
           description: The plugin source (GitHub) was temporarily unavailable; the upgrade is retryable.
   /v1/plugins/{name}/versions:
@@ -25663,6 +25732,20 @@ paths:
                           description:
                             User enable/disable override on a plugin-sourced schedule; null when the declaration's own enabled value
                             applies. Always null for user-created schedules.
+                        disarmReason:
+                          anyOf:
+                            - type: string
+                              enum:
+                                - user_disabled
+                                - plugin_removed
+                                - plugin_disabled
+                                - declaration_removed
+                                - declaration_disabled
+                            - type: "null"
+                          description:
+                            "Why a plugin-sourced schedule is off: the user turned it off, the plugin is gone, the plugin is disabled,
+                            the declaration is gone, or the plugin's own files turned it off. Null whenever the schedule
+                            is on, and always null for user-created schedules."
                         isOneShot:
                           type: boolean
                         isDeferred:
@@ -25699,6 +25782,7 @@ paths:
                         - workflowName
                         - sourceKey
                         - userEnabled
+                        - disarmReason
                         - isOneShot
                         - isDeferred
                       additionalProperties: false
@@ -25896,6 +25980,20 @@ paths:
                         description:
                           User enable/disable override on a plugin-sourced schedule; null when the declaration's own enabled value
                           applies. Always null for user-created schedules.
+                      disarmReason:
+                        anyOf:
+                          - type: string
+                            enum:
+                              - user_disabled
+                              - plugin_removed
+                              - plugin_disabled
+                              - declaration_removed
+                              - declaration_disabled
+                          - type: "null"
+                        description:
+                          "Why a plugin-sourced schedule is off: the user turned it off, the plugin is gone, the plugin is disabled,
+                          the declaration is gone, or the plugin's own files turned it off. Null whenever the schedule
+                          is on, and always null for user-created schedules."
                       isOneShot:
                         type: boolean
                       isDeferred:
@@ -25932,6 +26030,7 @@ paths:
                       - workflowName
                       - sourceKey
                       - userEnabled
+                      - disarmReason
                       - isOneShot
                       - isDeferred
                     additionalProperties: false
@@ -26081,6 +26180,20 @@ paths:
                           description:
                             User enable/disable override on a plugin-sourced schedule; null when the declaration's own enabled value
                             applies. Always null for user-created schedules.
+                        disarmReason:
+                          anyOf:
+                            - type: string
+                              enum:
+                                - user_disabled
+                                - plugin_removed
+                                - plugin_disabled
+                                - declaration_removed
+                                - declaration_disabled
+                            - type: "null"
+                          description:
+                            "Why a plugin-sourced schedule is off: the user turned it off, the plugin is gone, the plugin is disabled,
+                            the declaration is gone, or the plugin's own files turned it off. Null whenever the schedule
+                            is on, and always null for user-created schedules."
                         isOneShot:
                           type: boolean
                         isDeferred:
@@ -26117,6 +26230,7 @@ paths:
                         - workflowName
                         - sourceKey
                         - userEnabled
+                        - disarmReason
                         - isOneShot
                         - isDeferred
                       additionalProperties: false
@@ -26263,6 +26377,20 @@ paths:
                         description:
                           User enable/disable override on a plugin-sourced schedule; null when the declaration's own enabled value
                           applies. Always null for user-created schedules.
+                      disarmReason:
+                        anyOf:
+                          - type: string
+                            enum:
+                              - user_disabled
+                              - plugin_removed
+                              - plugin_disabled
+                              - declaration_removed
+                              - declaration_disabled
+                          - type: "null"
+                        description:
+                          "Why a plugin-sourced schedule is off: the user turned it off, the plugin is gone, the plugin is disabled,
+                          the declaration is gone, or the plugin's own files turned it off. Null whenever the schedule
+                          is on, and always null for user-created schedules."
                       isOneShot:
                         type: boolean
                       isDeferred:
@@ -26299,6 +26427,7 @@ paths:
                       - workflowName
                       - sourceKey
                       - userEnabled
+                      - disarmReason
                       - isOneShot
                       - isDeferred
                     additionalProperties: false
@@ -26505,6 +26634,20 @@ paths:
                           description:
                             User enable/disable override on a plugin-sourced schedule; null when the declaration's own enabled value
                             applies. Always null for user-created schedules.
+                        disarmReason:
+                          anyOf:
+                            - type: string
+                              enum:
+                                - user_disabled
+                                - plugin_removed
+                                - plugin_disabled
+                                - declaration_removed
+                                - declaration_disabled
+                            - type: "null"
+                          description:
+                            "Why a plugin-sourced schedule is off: the user turned it off, the plugin is gone, the plugin is disabled,
+                            the declaration is gone, or the plugin's own files turned it off. Null whenever the schedule
+                            is on, and always null for user-created schedules."
                         isOneShot:
                           type: boolean
                         isDeferred:
@@ -26541,6 +26684,7 @@ paths:
                         - workflowName
                         - sourceKey
                         - userEnabled
+                        - disarmReason
                         - isOneShot
                         - isDeferred
                       additionalProperties: false
@@ -26690,6 +26834,20 @@ paths:
                           description:
                             User enable/disable override on a plugin-sourced schedule; null when the declaration's own enabled value
                             applies. Always null for user-created schedules.
+                        disarmReason:
+                          anyOf:
+                            - type: string
+                              enum:
+                                - user_disabled
+                                - plugin_removed
+                                - plugin_disabled
+                                - declaration_removed
+                                - declaration_disabled
+                            - type: "null"
+                          description:
+                            "Why a plugin-sourced schedule is off: the user turned it off, the plugin is gone, the plugin is disabled,
+                            the declaration is gone, or the plugin's own files turned it off. Null whenever the schedule
+                            is on, and always null for user-created schedules."
                         isOneShot:
                           type: boolean
                         isDeferred:
@@ -26726,6 +26884,7 @@ paths:
                         - workflowName
                         - sourceKey
                         - userEnabled
+                        - disarmReason
                         - isOneShot
                         - isDeferred
                       additionalProperties: false
@@ -26877,6 +27036,20 @@ paths:
                           description:
                             User enable/disable override on a plugin-sourced schedule; null when the declaration's own enabled value
                             applies. Always null for user-created schedules.
+                        disarmReason:
+                          anyOf:
+                            - type: string
+                              enum:
+                                - user_disabled
+                                - plugin_removed
+                                - plugin_disabled
+                                - declaration_removed
+                                - declaration_disabled
+                            - type: "null"
+                          description:
+                            "Why a plugin-sourced schedule is off: the user turned it off, the plugin is gone, the plugin is disabled,
+                            the declaration is gone, or the plugin's own files turned it off. Null whenever the schedule
+                            is on, and always null for user-created schedules."
                         isOneShot:
                           type: boolean
                         isDeferred:
@@ -26913,6 +27086,7 @@ paths:
                         - workflowName
                         - sourceKey
                         - userEnabled
+                        - disarmReason
                         - isOneShot
                         - isDeferred
                       additionalProperties: false
@@ -27199,6 +27373,20 @@ paths:
                           description:
                             User enable/disable override on a plugin-sourced schedule; null when the declaration's own enabled value
                             applies. Always null for user-created schedules.
+                        disarmReason:
+                          anyOf:
+                            - type: string
+                              enum:
+                                - user_disabled
+                                - plugin_removed
+                                - plugin_disabled
+                                - declaration_removed
+                                - declaration_disabled
+                            - type: "null"
+                          description:
+                            "Why a plugin-sourced schedule is off: the user turned it off, the plugin is gone, the plugin is disabled,
+                            the declaration is gone, or the plugin's own files turned it off. Null whenever the schedule
+                            is on, and always null for user-created schedules."
                         isOneShot:
                           type: boolean
                         isDeferred:
@@ -27235,6 +27423,7 @@ paths:
                         - workflowName
                         - sourceKey
                         - userEnabled
+                        - disarmReason
                         - isOneShot
                         - isDeferred
                       additionalProperties: false
@@ -33912,23 +34101,7 @@ components:
       additionalProperties: {}
     LLMProvider:
       type: string
-      enum:
-        - anthropic
-        - openai
-        - gemini
-        - ollama
-        - fireworks
-        - openrouter
-        - vercel-ai-gateway
-        - openai-compatible
-        - minimax
-        - atlascloud
-        - together
-        - litellm
-        - baseten
-        - poolside
-        - vellum
-        - chatgpt
+      minLength: 1
     ProfilePatchEntry:
       type: object
       properties:
@@ -34309,6 +34482,7 @@ components:
         - baseten
         - poolside
         - vellum
+        - chatgpt
     Auth:
       oneOf:
         - type: object
@@ -34526,6 +34700,7 @@ components:
                     - gemini
                     - fireworks
                     - openrouter
+                    - chatgpt
                     - vellum
                     - together
                     - vercel-ai-gateway
@@ -34903,6 +35078,7 @@ components:
                 - gemini
                 - fireworks
                 - openrouter
+                - chatgpt
                 - vellum
                 - together
                 - vercel-ai-gateway