@epilot/cli 0.1.117 → 0.1.119

package/README.md

@@ -29,7 +29,7 @@ npm install -g @epilot/cli
 
 <!-- usage-help -->
 ```
-epilot v0.1.117 — CLI for epilot APIs
+epilot v0.1.119 — CLI for epilot APIs
 
 USAGE
   epilot <api> <operationId> [params...] [flags]

package/definitions/ai-agents.json

@@ -45,7 +45,7 @@
         "tags": [
           "Agents Configuration"
         ],
-        "summary": "Create Agent definition",
+        "summary": "createAgent",
         "description": "Creates a new custom agent. System skills cannot be created via this endpoint.",
         "operationId": "createAgent",
         "security": [
@@ -90,7 +90,7 @@
         "tags": [
           "Agents Configuration"
         ],
-        "summary": "List all agent configurations",
+        "summary": "listAgents",
         "description": "Lists agents from both system skills and custom agents.\nUse query parameters to filter by source, availability, or entity schema.\n",
         "operationId": "listAgents",
         "parameters": [
@@ -148,7 +148,7 @@
         "tags": [
           "Agents Configuration"
         ],
-        "summary": "Get the agent configuration by ID",
+        "summary": "getAgentById",
         "description": "Retrieves an agent by ID. Supports both:\n- System skill IDs (prefixed): \"skill:email-categorizer\"\n- Custom agent IDs (UUID): \"0336a235-9417-4dd8-894c-fe81285bba75\"\n",
         "operationId": "getAgentById",
         "security": [
@@ -193,7 +193,7 @@
         "tags": [
           "Agents Configuration"
         ],
-        "summary": "Update the agent configuration by ID",
+        "summary": "updateAgentById",
         "description": "Updates a custom agent. System skills cannot be updated via this endpoint.",
         "operationId": "updateAgentById",
         "security": [
@@ -248,7 +248,7 @@
         "tags": [
           "Agents Configuration"
         ],
-        "summary": "Delete the agent configuration by ID",
+        "summary": "deleteAgentById",
         "description": "Deletes a custom agent. System skills cannot be deleted via this endpoint.",
         "security": [
           {
@@ -288,7 +288,7 @@
         "tags": [
           "Agent Execution"
         ],
-        "summary": "Execute an agent",
+        "summary": "executeAgent",
         "description": "Executes an agent (system skill or custom agent).\nSupports both:\n- System skill IDs (prefixed): \"skill:email-categorizer\"\n- Custom agent IDs (UUID): \"0336a235-9417-4dd8-894c-fe81285bba75\"\n",
         "operationId": "executeAgent",
         "security": [
@@ -355,7 +355,7 @@
         "tags": [
           "Agent Execution"
         ],
-        "summary": "Execute an agent with streaming response",
+        "summary": "executeAgentStream",
         "description": "Executes an agent with real-time streaming of tokens and tool events.\nReturns Server-Sent Events (SSE) stream with token-by-token output,\ntool call progress, and completion status.\n\nUnlike the async `/execute` endpoint which returns immediately with\nan execution_id for polling, this endpoint streams all events in real-time.\n\nSupports both:\n- System skill IDs (prefixed): \"skill:email-categorizer\"\n- Custom agent IDs (UUID): \"0336a235-9417-4dd8-894c-fe81285bba75\"\n",
         "operationId": "executeAgentStream",
         "security": [
@@ -422,7 +422,8 @@
         "tags": [
           "Agent Execution"
         ],
-        "summary": "List executions",
+        "summary": "listExecutions",
+        "description": "List executions",
         "operationId": "listExecutions",
         "security": [
           {
@@ -485,7 +486,8 @@
         "tags": [
           "Agent Execution"
         ],
-        "summary": "Get execution by ID",
+        "summary": "getExecution",
+        "description": "Get execution by ID",
         "operationId": "getExecution",
         "security": [
           {
@@ -530,7 +532,8 @@
         "tags": [
           "Agent Execution"
         ],
-        "summary": "Cancel execution",
+        "summary": "cancelExecution",
+        "description": "Cancel execution",
         "operationId": "cancelExecution",
         "security": [
           {
@@ -587,7 +590,7 @@
         "tags": [
           "Agent Execution"
         ],
-        "summary": "Get execution trace/iterations",
+        "summary": "getExecutionTrace",
         "description": "Returns the step-by-step reasoning and tool calls for ReAct mode executions. Returns empty iterations array for direct mode executions.",
         "operationId": "getExecutionTrace",
         "security": [
@@ -759,7 +762,7 @@
         "tags": [
           "Agent Execution"
         ],
-        "summary": "Approve pending action",
+        "summary": "approveExecution",
         "description": "Approves a pending tool action when execution is in waiting_approval status",
         "operationId": "approveExecution",
         "security": [
@@ -826,7 +829,7 @@
         "tags": [
           "Agent Execution"
         ],
-        "summary": "Reject pending action",
+        "summary": "rejectExecution",
         "description": "Rejects a pending tool action when execution is in waiting_approval status",
         "operationId": "rejectExecution",
         "security": [
@@ -894,7 +897,7 @@
         "tags": [
           "Agent Execution"
         ],
-        "summary": "Reconnect to execution stream",
+        "summary": "streamExecution",
         "description": "Reconnects to an execution's event stream after approval. Replays missed events from event log and continues streaming if execution is still running.",
         "operationId": "streamExecution",
         "security": [
@@ -950,7 +953,7 @@
         "tags": [
           "Chat"
         ],
-        "summary": "Streaming chat with AI agent",
+        "summary": "chat",
         "description": "Initiates a streaming chat session with an AI agent. Supports server-side conversation memory via conversationId or client-provided history via clientHistory.",
         "operationId": "chat",
         "security": [
@@ -1007,7 +1010,7 @@
         "tags": [
           "Conversations"
         ],
-        "summary": "List conversations",
+        "summary": "listConversations",
         "description": "Lists conversations for the authenticated user, sorted by most recent.",
         "operationId": "listConversations",
         "security": [
@@ -1071,7 +1074,7 @@
         "tags": [
           "Conversations"
         ],
-        "summary": "Get conversation with messages",
+        "summary": "getConversation",
         "description": "Retrieves a conversation and its message history.",
         "operationId": "getConversation",
         "security": [
@@ -1126,7 +1129,7 @@
         "tags": [
           "Conversations"
         ],
-        "summary": "Delete conversation",
+        "summary": "deleteConversation",
         "description": "Deletes a conversation and all its messages.",
         "operationId": "deleteConversation",
         "security": [
@@ -1167,7 +1170,7 @@
         "tags": [
           "Conversations"
         ],
-        "summary": "Submit feedback for an assistant turn",
+        "summary": "submitConversationFeedback",
         "description": "Records a thumbs up/down (with optional comment) for the assistant turn identified by its Langfuse trace id. The rating is persisted on the message and mirrored to Langfuse as a trace score.\n",
         "operationId": "submitConversationFeedback",
         "security": [
@@ -1505,14 +1508,6 @@
               "type": "string"
             },
             "description": "For batch approval - list of action IDs to reject. Actions not in approved_action_ids are implicitly rejected."
-          },
-          "share_scope": {
-            "type": "string",
-            "enum": [
-              "primary_only",
-              "primary_and_relations"
-            ],
-            "description": "For `partnering.proposeAssignment` approvals. `primary_only` (default) shares only the primary entity; `primary_and_relations` also shares every entity in the proposal's `related_entities` as a child of the primary. Ignored by other tools.\n"
           }
         }
       },
@@ -1887,6 +1882,105 @@
           }
         }
       },
+      "AgentExecutionEventStatus": {
+        "type": "string",
+        "description": "Lifecycle status carried on an agent execution event.\n\nDeliberately narrower than `ExecutionStatus`, which is the stored status of\nthe execution row: `pending` and `running` both surface as `started`, and\n`cancelled` surfaces as `failed`. Consumers must not assume the two\nvocabularies are interchangeable.\n",
+        "enum": [
+          "started",
+          "completed",
+          "failed",
+          "approval_required"
+        ]
+      },
+      "AgentExecutionEvent": {
+        "type": "object",
+        "description": "Detail payload of the `agent-execution-status-update` event, published on\nthe AI Agents event bus with source `ai-agents`.\n\n`execution_context` and `input` are present on every status, so a consumer\ncan tell whether an execution is theirs, and what it belonged to, from the\nterminal event alone — without a secondary lookup.\n",
+        "required": [
+          "executionId",
+          "agentId",
+          "orgId",
+          "execution_status"
+        ],
+        "properties": {
+          "executionId": {
+            "type": "string",
+            "description": "The agent execution this event reports on"
+          },
+          "agentId": {
+            "$ref": "#/components/schemas/AgentId"
+          },
+          "orgId": {
+            "type": "string"
+          },
+          "userId": {
+            "type": "string"
+          },
+          "execution_status": {
+            "$ref": "#/components/schemas/AgentExecutionEventStatus"
+          },
+          "execution_context": {
+            "$ref": "#/components/schemas/ExecutionContext"
+          },
+          "input": {
+            "type": "object",
+            "additionalProperties": true,
+            "description": "The execution input, as supplied by the caller of the execute endpoint"
+          },
+          "output": {
+            "type": "object",
+            "additionalProperties": true,
+            "description": "Present on `completed` — the execution result"
+          },
+          "error": {
+            "type": "object",
+            "description": "Present on `failed`",
+            "properties": {
+              "message": {
+                "type": "string"
+              },
+              "code": {
+                "type": "string"
+              },
+              "stack": {
+                "type": "string"
+              }
+            }
+          },
+          "duration": {
+            "type": "integer",
+            "description": "Wall-clock duration in milliseconds, present on `completed`"
+          },
+          "iterations": {
+            "type": "integer"
+          },
+          "iteration": {
+            "type": "integer"
+          },
+          "message": {
+            "type": "string",
+            "description": "Present on `approval_required` — what is awaiting approval"
+          },
+          "toolCalls": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "name": {
+                  "type": "string"
+                },
+                "args": {
+                  "type": "object",
+                  "additionalProperties": true
+                }
+              }
+            }
+          },
+          "timestamp": {
+            "type": "string",
+            "format": "date-time"
+          }
+        }
+      },
       "ToolPreview": {
         "type": "object",
         "description": "Structured preview data for approval UI. Provides a generic format that any tool can populate.",

package/definitions/customer-portal.json

@@ -884,7 +884,7 @@
     "/v2/portal/consumption": {
       "get": {
         "operationId": "getConsumption",
-        "summary": "Get Consumption",
+        "summary": "getConsumption",
         "description": "Get energy consumption data between a given time period.",
         "tags": [
           "ECP"
@@ -1039,7 +1039,7 @@
     "/v2/portal/visualization:export": {
       "post": {
         "operationId": "prepareVisualizationExport",
-        "summary": "Prepare Visualization Export",
+        "summary": "prepareVisualizationExport",
         "description": "Asks an installed App to prepare a downloadable export of a visualization (consumption chart, dynamic tariff chart, etc.). The export is produced by the third-party App via a configured portal extension hook of type `dataExport` — this endpoint does not generate the file itself, it forwards the request to the configured hook and returns the descriptor the App provides (typically a `download_url`).\n",
         "tags": [
           "ECP"
@@ -1143,7 +1143,7 @@
     "/v2/portal/visualization/metadata": {
       "get": {
         "operationId": "getVisualizationMetadata",
-        "summary": "Get Visualization Metadata",
+        "summary": "getVisualizationMetadata",
         "description": "Returns runtime metadata describing how a visualization (consumption / price / cost chart) should be rendered for a given portal context (meter, contract, etc). Resolves the extension's `visualizationMetadata` hook implicitly from `app_id` + `extensionId` and invokes it. Supplies the response as a structured payload that the portal uses to configure type/aggregation options, supported intervals, and the available data range.\n",
         "tags": [
           "ECP"
@@ -1211,7 +1211,7 @@
     "/v2/portal/costs": {
       "get": {
         "operationId": "getCosts",
-        "summary": "Get Costs",
+        "summary": "getCosts",
         "description": "Get energy cost data between a given time period.",
         "tags": [
           "ECP"
@@ -1385,7 +1385,7 @@
     "/v2/portal/prices": {
       "get": {
         "operationId": "getPrices",
-        "summary": "Get Prices",
+        "summary": "getPrices",
         "description": "Get energy prices data between a given time period.",
         "tags": [
           "ECP"
@@ -3119,6 +3119,10 @@
                         "journey_registration_email": {
                           "type": "string",
                           "description": "The email address registered in the journey's Login & Registration block"
+                        },
+                        "journey_registration_portal_id": {
+                          "type": "string",
+                          "description": "The portal selected on the journey's Login & Registration block, used to target the registration link to that portal"
                         }
                       }
                     }
@@ -6965,6 +6969,56 @@
         }
       }
     },
+    "/v2/portal/user/file/{id}/preview": {
+      "get": {
+        "operationId": "getFilePreview",
+        "summary": "getFilePreview",
+        "description": "resolves an in-portal preview for a file. Returns a Content-Disposition: inline URL for directly-previewable files (PDF, common image formats), or a document-api PDF conversion result for the Office formats it currently supports (docx/xls/xlsx/xlsm) -- NOT doc/csv/pptx, which document-api's conversion does not cover today. Returns { kind: \"unsupported\" } (no url) for anything else, so the caller can fall back to the existing download flow. An optional `download_url` is returned for all kinds — including \"unsupported\" — whenever the file entity exposes one, so the client can render a real anchor for its Download action; it is only a Content-Disposition: attachment URL for private files, and for other access levels it is the plain object URL, which may render inline. The previewability decision is made server-side from the file's own filename/mime_type — never trust a client-supplied kind for anything security-sensitive.",
+        "tags": [
+          "ECP"
+        ],
+        "security": [
+          {
+            "PortalAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "in": "path",
+            "name": "id",
+            "schema": {
+              "$ref": "#/components/schemas/EntityId"
+            },
+            "required": true,
+            "description": "The Id of a file"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "The file preview was resolved (which may still indicate kind \"unsupported\" with no url).",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/FilePreviewResult"
+                }
+              }
+            }
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          },
+          "500": {
+            "$ref": "#/components/responses/InternalServerError"
+          }
+        }
+      }
+    },
     "/v2/portal/user/file/{id}/downloaded": {
       "post": {
         "operationId": "trackFileDownloaded",
@@ -7023,7 +7077,7 @@
     "/v2/portal/user/files/count-by-entity": {
       "get": {
         "operationId": "getFilesCountByEntity",
-        "summary": "getFileCountByEntity",
+        "summary": "getFilesCountByEntity",
         "description": "Fetch file counts for all ECP user related entities",
         "deprecated": true,
         "tags": [
@@ -7911,7 +7965,7 @@
     "/v2/portal/entity/{slug}/{id}/workflows": {
       "get": {
         "operationId": "getEntityWorkflows",
-        "summary": "Get workflows for an entity",
+        "summary": "getEntityWorkflows",
         "description": "Get all workflows associated with an entity (requires access to the entity)",
         "tags": [
           "ECP"
@@ -7980,7 +8034,7 @@
     "/v2/portal/entity/{slug}/{id}/workflows/linearized": {
       "get": {
         "operationId": "getEntityPortalWorkflows",
-        "summary": "Get linearized workflows for an entity",
+        "summary": "getEntityPortalWorkflows",
         "description": "Get all portal-relevant workflows associated with an entity (requires access to the entity),\nlinearized by the Workflows API into a flat, ordered list of portal-visible tasks.\n\nUnlike `getEntityWorkflows`, this endpoint returns a single uniform shape for both legacy\n(V1) workflow executions and graph-based (V2) flow executions — the execution graph is\nalready resolved server-side (active path, task reachability, chronological ordering), so\nclients can render a timeline without any graph traversal logic.\n\nTasks carry the config of both portal audiences (`ecp` and `installer`); clients filter\nper their configured audience, so one response serves every block on a page.\n",
         "tags": [
           "ECP"
@@ -8046,10 +8100,96 @@
         }
       }
     },
+    "/v2/portal/entities/workflows/linearized/batch": {
+      "post": {
+        "operationId": "getEntityPortalWorkflowsBatch",
+        "summary": "getEntityPortalWorkflowsBatch",
+        "description": "Batch variant of `getEntityPortalWorkflows`: returns portal-relevant workflows for\nup to 50 entities — schemas may differ — in a single call, each already linearized\nby the Workflows API into a flat, ordered list of portal-visible tasks.\n\nIntended for portal list views (e.g. an entity list where every card shows its\nworkflow progress). Entities the portal user cannot access are omitted from the\nresponse; an entry with an empty task list means the entity has no portal-relevant\nworkflow.\n",
+        "tags": [
+          "ECP"
+        ],
+        "security": [
+          {
+            "PortalAuth": []
+          }
+        ],
+        "requestBody": {
+          "description": "Entities to load portal workflows for",
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "entities": {
+                    "type": "array",
+                    "items": {
+                      "type": "object",
+                      "properties": {
+                        "id": {
+                          "type": "string",
+                          "description": "ID of the entity"
+                        },
+                        "slug": {
+                          "type": "string",
+                          "description": "Schema slug of the entity",
+                          "example": "order"
+                        }
+                      },
+                      "required": [
+                        "id",
+                        "slug"
+                      ]
+                    },
+                    "minItems": 1,
+                    "maxItems": 50
+                  }
+                },
+                "required": [
+                  "entities"
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "One entry per accessible entity, each with its linearized workflows",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "results": {
+                      "type": "array",
+                      "items": {
+                        "$ref": "#/components/schemas/EntityPortalWorkflows"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/InvalidRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "500": {
+            "$ref": "#/components/responses/InternalServerError"
+          }
+        }
+      }
+    },
     "/v2/portal/metering/reading/photo": {
       "post": {
         "operationId": "uploadMeterReadingPhoto",
-        "summary": "Upload Meter Reading Photo",
+        "summary": "uploadMeterReadingPhoto",
         "description": "Uploads a Meter Reading photo and - if enabled - gives back data extracted from the photo.",
         "tags": [
           "ECP"
@@ -8104,7 +8244,7 @@
     "/v2/portal/metering/reading": {
       "post": {
         "operationId": "createMeterReading",
-        "summary": "Create Meter Reading",
+        "summary": "createMeterReading",
         "description": "Inserts a new meter reading.",
         "tags": [
           "ECP"
@@ -8171,6 +8311,7 @@
     "/v2/portal/metering/reading/allowed-range/{meter_id}": {
       "get": {
         "operationId": "getAllowedMeterReadingRange",
+        "summary": "getAllowedMeterReadingRange",
         "description": "Get allowed reading range for all counters of a meter from the configured\nthird-party plausibility check hook using 'range' mode. This endpoint requires\na plausibility check hook to be configured for the portal.\n",
         "tags": [
           "ECP"
@@ -8272,7 +8413,7 @@
     "/v2/portal/metering/readings": {
       "post": {
         "operationId": "getMeterReadings",
-        "summary": "Get meter readings with optional template resolution",
+        "summary": "getMeterReadings",
         "description": "Fetches meter readings for a counter and optionally resolves Handlebars\ntemplate strings against each reading object using @epilot/variables.\n",
         "tags": [
           "ECP"
@@ -9617,7 +9758,7 @@
     "/v2/portal/campaign/{campaign_id}/entity:status": {
       "put": {
         "operationId": "updateCampaignPortalBlockStatus",
-        "summary": "Update Campaign Portal Block Status",
+        "summary": "updateCampaignPortalBlockStatus",
         "description": "Updates the status of a campaign portal block for multiple recipients.",
         "tags": [
           "ECP"
@@ -10271,7 +10412,7 @@
                     "items": {
                       "$ref": "#/components/schemas/SwappableConfig"
                     },
-                    "description": "Items to swap"
+                    "description": "Optional, opt-in configuration items to additionally swap on top of the always-swapped pages and functional config. Defaults to an empty list (nothing extra swapped). Domain and access/security settings can never be swapped."
                   }
                 }
               }
@@ -11579,6 +11720,10 @@
           "message": {
             "type": "string",
             "description": "Error message"
+          },
+          "reason": {
+            "type": "string",
+            "description": "Machine-readable cause, when the API can name one. `PORTAL_USER_PENDING_ACTIVATION` means the portal user is authenticated but not mapped to a contact yet, so re-authenticating will not help."
           }
         }
       },
@@ -11994,7 +12139,7 @@
           },
           "identity_providers": {
             "type": "array",
-            "description": "SSO identity providers for the portal. When sent on a portal save (PUT/POST),\nthe list is fully synced — incoming providers are upserted and any existing\nproviders not in the list are deleted. Omit the field to leave SSO\nconfiguration unchanged; send an empty array to remove all providers.\n\nEach provider is persisted verbatim — `oidc_config.client_secret` is stored\nas sent. Customers are encouraged to reference an org env secret via\n`{{ env.VAR }}` rather than embed raw values.\n",
+            "description": "SSO identity providers for the portal. When sent on a portal save (PUT/POST),\nthe list is fully synced — incoming providers are upserted and any existing\nproviders not in the list are deleted. Omit the field to leave SSO\nconfiguration unchanged; send an empty array to remove all providers.\n\nSecrets: a provider sent without `oidc_config.client_secret` keeps the\nstored secret for the same slug; an explicit empty string clears it.\n`getPortalConfigV3` returns providers with raw secrets redacted;\n`{{ env.VAR }}` references pass through.\n",
             "items": {
               "$ref": "#/components/schemas/ProviderConfig"
             }
@@ -14369,6 +14514,33 @@
           }
         ]
       },
+      "FilePreviewResult": {
+        "type": "object",
+        "required": [
+          "kind"
+        ],
+        "properties": {
+          "kind": {
+            "type": "string",
+            "description": "What kind of preview (if any) is available. \"pdf\" covers both native PDFs and Office documents that were converted to PDF server-side. \"unsupported\" means no preview is available and the caller should fall back to download.",
+            "enum": [
+              "pdf",
+              "image",
+              "unsupported"
+            ]
+          },
+          "url": {
+            "type": "string",
+            "format": "uri",
+            "description": "A Content-Disposition: inline URL to render in a preview viewer. Present only when kind is \"pdf\" or \"image\". Short-lived — do not cache across dialog opens."
+          },
+          "download_url": {
+            "type": "string",
+            "format": "uri",
+            "description": "Optional download URL for the file, returned for any kind — including \"unsupported\" — whenever the file entity exposes one. It is only a Content-Disposition: attachment URL for files with access_control \"private\", where it is a short-lived signed URL; for any other access level it is the file entity's plain public/CDN object URL, which carries no attachment disposition and may render inline in the browser. Absent when the file entity exposes no usable URL, so clients must handle it being missing."
+          }
+        }
+      },
       "EntityFileCount": {
         "type": "object",
         "required": [
@@ -14868,6 +15040,26 @@
           "is_active"
         ]
       },
+      "EntityPortalWorkflows": {
+        "type": "object",
+        "description": "Linearized portal workflows of a single entity",
+        "properties": {
+          "entity_id": {
+            "type": "string"
+          },
+          "portal_workflows": {
+            "type": "array",
+            "description": "Empty when the entity has no portal-relevant workflow",
+            "items": {
+              "$ref": "#/components/schemas/PortalWorkflow"
+            }
+          }
+        },
+        "required": [
+          "entity_id",
+          "portal_workflows"
+        ]
+      },
       "PortalTaskConfig": {
         "type": "object",
         "description": "Portal-specific (ECP / installer) display config of a workflow task",
@@ -19211,10 +19403,8 @@
       },
       "SwappableConfig": {
         "type": "string",
+        "description": "Optional configuration item that a portal swap can additionally include. The swap always transfers the pages and the functional experience config that keep the portal working. These items are opt-in on top of that and are OFF by default. Domain and access/security settings (domain, cognito_details, auth_settings) can never be swapped and are therefore not part of this enum.",
         "enum": [
-          "all",
-          "domain",
-          "users",
           "email_templates"
         ]
       },

package/definitions/message.json

@@ -585,7 +585,7 @@
       "post": {
         "operationId": "getUnreadCounts",
         "summary": "getUnreadCounts",
-        "description": "Unread counts for several named scopes in one request.\n\nA scope is a name plus the same parameters the thread list already takes (`q`, `inbox_id`),\nso a scope's count and the list beneath it are the same predicate and agree by construction.\nThe server adds only the read-state condition; it does not re-author the caller's view.\n\nThe `organization` scope is the exception and takes no `q`: it reuses the four canonical\ncentral-inbox queries, so its numbers match `getUnread` exactly.\n\nBuckets are not symmetric, across scope types or across actors. Every scope other than\n`organization` returns `unread` alone. The `organization` scope returns all four\n(`unread`, `drafts`, `unassigned`, `spam`) for `actor: organization`, and only `unread` and\n`drafts` for `actor: user` — the agent sidebar has no Spam or Unlinked folder, so those two\nnumbers have nowhere to render and each one costs a cardinality aggregation. This is a\ndeliberate divergence from `getUnread`, which computes all four for both actors.\n\nGated on the `message-unread-counts` flag, evaluated once per request against the calling\norg. With the flag off the response is `{ \"enabled\": false, \"counts\": {} }` and no\nElasticsearch query is issued.\n",
+        "description": "Unread counts for several named scopes in one request.\n\nA scope is a name plus the same parameters the thread list already takes (`q`, `inbox_id`),\nso a scope's count and the list beneath it are the same predicate and agree by construction.\nThe server adds only the read-state condition; it does not re-author the caller's view.\n\nThe `organization` scope is the exception and takes no `q`: it reuses the four canonical\ncentral-inbox queries, so its numbers match `getUnread` exactly.\n\nWhich buckets come back varies by scope type and actor. Every scope other than `organization`\nreturns `unread` alone. An `organization` scope returns all four (`unread`, `drafts`,\n`unassigned`, `spam`) for `actor: organization`, and `unread` and `drafts` only for\n`actor: user`. `getUnread` returns all four for both actors; this endpoint omits the two that\nno per-user surface renders, since each costs an aggregation.\n\nGated on the `message-unread-counts` flag, evaluated once per request against the calling\norg. With the flag off the response is `{ \"enabled\": false, \"counts\": {} }` and no\nElasticsearch query is issued.\n",
         "tags": [
           "Messages"
         ],
@@ -611,7 +611,7 @@
             }
           },
           "400": {
-            "description": "The request names more scopes than the cap allows, repeats a scope name, or omits `q`\non a scope type that requires it. Over-cap requests are refused rather than truncated:\na silently dropped scope renders as a missing badge, which is indistinguishable from\nzero unread.\n"
+            "description": "The request names more scopes than the cap allows, repeats a scope name, or omits both\n`q` and `view` on a scope type that needs a predicate. Over-cap requests are refused rather than truncated:\na silently dropped scope renders as a missing badge, which is indistinguishable from\nzero unread.\n"
           },
           "403": {
             "description": "Forbidden"
@@ -832,7 +832,7 @@
       "post": {
         "operationId": "getAssigneeWorkload",
         "summary": "getAssigneeWorkload",
-        "description": "Return the open-thread workload for a set of user ids.\n\nFor each requested user id, returns the number of *open* threads assigned\ndirectly to that user — matching what the user sees in their central-inbox\nopen view: in inbox, not trashed, not done, and excluding notification-only\nand spam threads.\n\nOnly threads assigned directly to a user are counted; threads assigned to a\ngroup the user belongs to are not. Intended for assignment load-balancing\n(e.g. even-distribution automations) that need a consistent, inbox-aligned\nworkload per user.\n",
+        "description": "Return the open-thread workload for a set of user ids.\n\nFor each requested user id, returns the number of *open* threads assigned\ndirectly to that user \u2014 matching what the user sees in their central-inbox\nopen view: in inbox, not trashed, not done, and excluding notification-only\nand spam threads.\n\nOnly threads assigned directly to a user are counted; threads assigned to a\ngroup the user belongs to are not. Intended for assignment load-balancing\n(e.g. even-distribution automations) that need a consistent, inbox-aligned\nworkload per user.\n",
         "tags": [
           "Threads"
         ],
@@ -2695,6 +2695,117 @@
           }
         }
       },
+      "ThreadView": {
+        "type": "object",
+        "additionalProperties": true,
+        "description": "A central-inbox view, described structurally so the server compiles the query for it. Both the\nthread list and the unread count for a view are compiled from the same description, so the two\ncannot disagree about what the view means.\n\nEvery field is optional and an omitted field adds no condition, so a view narrows the whole\nmailbox rather than being a template with required holes. Unknown fields are ignored.\n",
+        "properties": {
+          "folder": {
+            "type": "string",
+            "enum": [
+              "inbox",
+              "favorite",
+              "sent",
+              "trash",
+              "spam",
+              "unassignable",
+              "draft"
+            ],
+            "description": "Which sidebar folder's membership predicate to apply."
+          },
+          "mailbox": {
+            "type": "string",
+            "enum": [
+              "organization",
+              "agent"
+            ],
+            "description": "Whose mailbox this is. `agent` scopes to threads assigned to the caller or their groups;\n`organization` scopes to the org and is the only mailbox that carries address filtering.\n"
+          },
+          "labels": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Saved-filter labels, ANDed. Matched exactly against the tag rather than against its\ntokens, so a label whose words overlap a folder tag no longer lands in that folder.\n"
+          },
+          "purposes": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Purpose ids on linked entities, ANDed."
+          },
+          "filters": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "enum": [
+                "unread",
+                "resolved",
+                "trash"
+              ]
+            },
+            "description": "State filters, independent of the folder. `resolved` and `trash` reach the Inbox folder\nonly and are mutually exclusive there; `unread` applies anywhere.\n"
+          },
+          "from": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Sender addresses to filter on."
+          },
+          "to": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Recipient addresses to filter on."
+          },
+          "assigned_to": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Assignee user ids."
+          },
+          "include_unassigned": {
+            "type": "boolean",
+            "description": "Whether threads with no assignee join the `assigned_to` set. A separate flag rather than a\nsentinel entry in that list, so `assigned_to` holds user ids and nothing else.\n"
+          },
+          "date_from_days_ago": {
+            "type": "integer",
+            "minimum": 0,
+            "description": "Lower bound of the date range, in days before now. Omitted means the epoch."
+          },
+          "date_to_days_ago": {
+            "type": "integer",
+            "minimum": 0,
+            "description": "Upper bound of the date range, in days before now. Omitted means now."
+          },
+          "email_filter": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Addresses the user selected in the address filter. Absent and empty differ, and the\ndifference is a real UI state: absent is \"not filtering by address\", empty is \"every\naddress deselected\", which matches nothing.\n\nDistinct from the permission restriction, which the server derives and a caller cannot\nauthor.\n"
+          },
+          "text": {
+            "type": "string",
+            "description": "The user's search string, as typed. Expanded across the searched fields server-side and\nnever interpreted as query syntax, so a typed operator or a stray bracket cannot\nre-associate the predicate around it.\n"
+          },
+          "thread_ids": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Restrict the view to these threads. Exists because \"would this thread appear in the view\nthe user is looking at?\" is a real question the inbox asks when a new thread arrives, and\nit is a membership test against the view rather than a different view.\n"
+          },
+          "pinned_by": {
+            "type": "string",
+            "description": "Restrict the view to threads this user pinned. The pinned strip above the list is the same\nview with this one extra condition.\n"
+          }
+        }
+      },
       "UnreadCountScope": {
         "type": "object",
         "required": [
@@ -2714,13 +2825,18 @@
               "shared_inbox",
               "saved_view"
             ],
-            "description": "Decides which buckets come back, and whether `q` is required. `organization` returns all\nfour buckets from the canonical central-inbox queries and takes no `q`. `shared_inbox`\nand `saved_view` return `unread` alone and require the `q` their list uses.\n\nA `shared_inbox` scope additionally requires `actor: organization` and is refused with a\n400 otherwise. A shared inbox is an organization-level construct — selecting one always\nswitches the mailbox to the organization — so it has no per-user read state and the\ncombination would compute a number no surface renders. `saved_view` accepts either actor,\nbecause a view's own configuration names its mailbox.\n"
+            "description": "Decides which buckets come back, and whether `q` is required. `organization` returns all\nfour buckets from the canonical central-inbox queries and takes no `q`. `shared_inbox`\nand `saved_view` return `unread` alone. A `saved_view` scope names its view with `view_id`;\na `shared_inbox` scope needs only its `inbox_id`, since the query follows from the type.\n\nA `shared_inbox` scope additionally requires `actor: organization` and is refused with a\n400 otherwise. A shared inbox is an organization-level construct \u2014 selecting one always\nswitches the mailbox to the organization \u2014 so it has no per-user read state and the\ncombination would compute a number no surface renders. `saved_view` accepts either actor,\nbecause a view's own configuration names its mailbox.\n"
           },
           "q": {
             "type": "string",
-            "description": "The scope's own list predicate, in Lucene syntax, exactly as the caller passes it to\n`threads:search`. Required for `shared_inbox` and `saved_view`, rejected for\n`organization`. The server ANDs the read-state condition onto it and nothing else, which\nis what makes the count and the list agree. Until the predicate definition moves\nserver-side, this is the caller's authored copy.\n",
+            "description": "The scope's query, in Lucene syntax, as passed to `threads:search` for the same scope. The\nserver adds the read-state condition and nothing else, so the count matches that list.\n\nAccepted for `shared_inbox` and `saved_view`; rejected for `organization`.\n\nSuperseded by server-side compilation. It remains accepted for callers whose counts are\nenabled while compilation is not, and is ignored when compilation is enabled. It will be\nremoved once compilation is enabled everywhere counts are.\n",
             "example": "_tags.keyword:inbox AND !_tags.keyword:trash"
           },
+          "view_id": {
+            "type": "string",
+            "description": "The id of the saved view this scope counts. The server reads that view and compiles the same\nquery the thread list runs for it, so the count and the list cannot describe the view\ndifferently.\n\nRequired for `saved_view` scopes unless `q` is supplied instead; rejected for the other two\ntypes. A `shared_inbox` scope needs no predicate field at all, because its query follows from\nthe type and its `inbox_id`. An `organization` scope uses the canonical folder queries.\n\nThe view's own shared-inbox filter is read from the stored view, so `inbox_id` need not be\nsent alongside this.\n\nCompilation is enabled per organization by the `message-unread-unified-predicate` feature\nflag. While it is off, a scope supplying only a `view_id` has no query to run and its name is\nreturned in `omitted` rather than counted. A named view that this organization does not have,\nor whose stored configuration cannot be read, is omitted the same way.\n",
+            "example": "3f34ce73-089c-4d45-a5ee-c161234e41c3"
+          },
           "inbox_id": {
             "description": "Shared inbox ids, resolved to bucket ids the same way `threads:search` resolves them.",
             "oneOf": [
@@ -2751,7 +2867,7 @@
               "organization",
               "user"
             ],
-            "description": "Which read state to count against — the org's or the calling user's. Same meaning as\n`getUnread`'s path parameter, and unrelated to a scope's `type`.\n"
+            "description": "Which read state to count against \u2014 the org's or the calling user's. Same meaning as\n`getUnread`'s path parameter, and unrelated to a scope's `type`.\n"
           },
           "email_filter": {
             "type": "array",
@@ -2760,6 +2876,13 @@
             },
             "description": "Restrict every scope to messages involving these addresses."
           },
+          "user_groups": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "The caller's group ids, as `group_<id>`, with the same meaning and constraints as on\n`threads:search`. Read only when a scope carries a `view`. Entries not matching\n`group_<id>` are dropped. Not an authorization input.\n"
+          },
           "scopes": {
             "type": "array",
             "minItems": 1,
@@ -2791,7 +2914,7 @@
           },
           "omitted": {
             "type": "array",
-            "description": "Names of scopes that were accepted but could not be counted — today, a shared inbox whose\nids matched no bucket in this org. Listed explicitly so a caller can tell an omission apart\nfrom a mis-spelled scope name, both of which are otherwise just a missing key in `counts`.\n",
+            "description": "Names of scopes that were accepted but could not be counted. Each appears here and is\nabsent from `counts`, so an omission is distinguishable from a mis-spelled scope name.\n\nCauses, not distinguishable from this field: a `shared_inbox` scope whose ids matched no\nbucket in the organization; a scope with no query to run because compilation is disabled for\nthe organization and no `q` was supplied; and a `view_id` naming a view this organization\ndoes not have or whose stored configuration cannot be read.\n",
             "items": {
               "type": "string"
             }
@@ -2827,9 +2950,6 @@
       },
       "SearchParamsV2": {
         "type": "object",
-        "required": [
-          "q"
-        ],
         "properties": {
           "inbox_id": {
             "oneOf": [
@@ -2852,10 +2972,25 @@
             ]
           },
           "q": {
-            "description": "Lucene query syntax supported with ElasticSearch",
+            "description": "Lucene query syntax supported with ElasticSearch.\n\nSend this or `view`, not both. At least one is required; a request with neither is refused\nwith a 400. An empty string is accepted and returns no hits.\n",
             "type": "string",
             "example": "subject:\"Request for solar panel price\" AND _tags:INBOX"
           },
+          "view": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/ThreadView"
+              }
+            ],
+            "description": "A view for the server to compile into the query, instead of supplying `q`. When a view is\npresent and compilation is enabled for the calling organization, the compiled query runs and\n`q` is not consulted.\n\nRead by `threads:search` and `threads:searchIds` only. This schema is shared with\n`messages:search`, which compiles no view and ignores the field, so a request there must\nsupply `q`.\n\nCompilation is enabled per organization by the `message-unread-unified-predicate` feature\nflag. While it is off, `q` runs and a request supplying only a view returns no hits.\n"
+          },
+          "user_groups": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "The caller's group ids, as `group_<id>`. Read only when a `view` is compiled, where they\ndetermine the agent mailbox's assignee condition and which shared inboxes, and therefore\nwhich addresses, are reachable. Required for those conditions to be correct, because group\nmembership is not present on the id token this service parses.\n\nEntries not matching `group_<id>` are dropped.\n\nNot an authorization input, and not treated as one: naming groups the caller is not in\nwidens what the response includes, exactly as supplying a broader `q` does. Access control\nis enforced elsewhere.\n"
+          },
           "fields": {
             "$ref": "#/components/schemas/FieldsParam"
           },
@@ -2913,6 +3048,21 @@
       "SearchIDParams": {
         "type": "object",
         "properties": {
+          "view": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/ThreadView"
+              }
+            ],
+            "description": "The view to compile, with the same meaning as on `threads:search`. Present here because\nthis endpoint returns the ordered id set *for that list*: if one compiled its view and the\nother ran an authored `q`, the two would disagree inside a single feature, which is the\ndrift this replaces.\n"
+          },
+          "user_groups": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "The caller's group ids, with the same meaning and caveats as on `threads:search`."
+          },
           "inbox_id": {
             "oneOf": [
               {
@@ -3160,7 +3310,7 @@
           },
           "label_name": {
             "type": "string",
-            "description": "Resolved taxonomy classification display name (e.g. `Verärgert`), when the label is a classification. Absent for free-form tags."
+            "description": "Resolved taxonomy classification display name (e.g. `Ver\u00e4rgert`), when the label is a classification. Absent for free-form tags."
           }
         }
       },
@@ -3183,7 +3333,7 @@
           },
           "label_name": {
             "type": "string",
-            "description": "Resolved taxonomy classification display name (e.g. `Verärgert`), when the label is a classification. Absent for free-form tags."
+            "description": "Resolved taxonomy classification display name (e.g. `Ver\u00e4rgert`), when the label is a classification. Absent for free-form tags."
           }
         }
       },
@@ -3400,7 +3550,7 @@
           "timestamp": {
             "type": "string",
             "description": "Timestamp of the event",
-            "example": "2024-01-01T00:00:00Z"
+            "example": "2024-01-01T00:00:00.000Z"
           },
           "message_id": {
             "type": "string",

package/dist/bin/epilot.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   API_LIST
-} from "../chunk-PKLYEJHD.js";
+} from "../chunk-IKYUAORY.js";
 
 // bin/epilot.ts
 import { runMain } from "citty";
@@ -11,7 +11,7 @@ import { defineCommand } from "citty";
 var main = defineCommand({
   meta: {
     name: "epilot",
-    version: "0.1.117",
+    version: "0.1.119",
     description: "CLI for epilot APIs"
   },
   args: {
@@ -30,8 +30,8 @@ var main = defineCommand({
     auth: () => import("../auth-WMXFMPWE.js").then((m) => m.default),
     profile: () => import("../profile-OZJL5ZPT.js").then((m) => m.default),
     config: () => import("../config-DGZIMLZK.js").then((m) => m.default),
-    completion: () => import("../completion-YY2UW6SA.js").then((m) => m.default),
-    upgrade: () => import("../upgrade-YQ6STVES.js").then((m) => m.default),
+    completion: () => import("../completion-CPMUSY3E.js").then((m) => m.default),
+    upgrade: () => import("../upgrade-LASQG4TZ.js").then((m) => m.default),
     "access-token": () => import("../access-token-WWE6BDJH.js").then((m) => m.default),
     address: () => import("../address-EH3C4CVB.js").then((m) => m.default),
     "address-suggestions": () => import("../address-suggestions-RRSLOBFW.js").then((m) => m.default),
@@ -134,13 +134,13 @@ process.stderr.on("error", (err) => {
   if (err.code === "EPIPE") process.exit(0);
   throw err;
 });
-var VERSION = true ? "0.1.117" : (await null).default.version;
+var VERSION = true ? "0.1.119" : (await null).default.version;
 var reorderedArgv = hoistFlagsAfterSubcommand(process.argv.slice(2));
 process.argv = [process.argv[0], process.argv[1], ...reorderedArgv];
 var args = process.argv.slice(2);
 var completionsIdx = args.indexOf("--_completions");
 if (completionsIdx >= 0) {
-  const { handleCompletions } = await import("../completion-YY2UW6SA.js");
+  const { handleCompletions } = await import("../completion-CPMUSY3E.js");
   handleCompletions(args[completionsIdx + 1], args[completionsIdx + 2]);
   process.exit(0);
 }

package/dist/{chunk-PKLYEJHD.js → chunk-IKYUAORY.js}

@@ -328,7 +328,7 @@ var API_LIST = [
     kebabName: "customer-portal",
     title: "Portal API",
     serverUrl: "https://customer-portal-api.sls.epilot.io",
-    operationCount: 160,
+    operationCount: 162,
     operationIds: [
       "upsertPortal",
       "createUser",
@@ -428,6 +428,7 @@ var API_LIST = [
       "getRegistrationIdentifiers",
       "getAllFiles",
       "getFileById",
+      "getFilePreview",
       "trackFileDownloaded",
       "getFilesCountByEntity",
       "getBillingEvents",
@@ -445,6 +446,7 @@ var API_LIST = [
       "updateWorkflowStepAsDone",
       "getEntityWorkflows",
       "getEntityPortalWorkflows",
+      "getEntityPortalWorkflowsBatch",
       "uploadMeterReadingPhoto",
       "createMeterReading",
       "getAllowedMeterReadingRange",

package/dist/{completion-YY2UW6SA.js → completion-CPMUSY3E.js}

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   API_LIST
-} from "./chunk-PKLYEJHD.js";
+} from "./chunk-IKYUAORY.js";
 import {
   DIM,
   GREEN,

package/dist/{upgrade-YQ6STVES.js → upgrade-LASQG4TZ.js}

@@ -72,7 +72,7 @@ ${GREEN}${BOLD}Upgraded to @epilot/cli@${latest}${RESET}
   }
 });
 var getCurrentVersion = () => {
-  if (true) return "0.1.117";
+  if (true) return "0.1.119";
   try {
     const output = execSync("npm ls -g @epilot/cli --depth=0 --json 2>/dev/null", {
       encoding: "utf-8",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@epilot/cli",
-  "version": "0.1.117",
+  "version": "0.1.119",
   "description": "CLI for epilot APIs",
   "type": "module",
   "bin": {