@epilot/cli 0.1.212 → 0.1.213

package/definitions/ai-agents.json

@@ -26,6 +26,10 @@
       "name": "Agents Configuration",
       "description": "Everything about AI Agent configuration"
     },
+    {
+      "name": "Customer Chat",
+      "description": "Org-scoped configuration for website and portal chat agents"
+    },
     {
       "name": "Agent Execution",
       "description": "Execute AI agents and manage executions"
@@ -37,6 +41,10 @@
     {
       "name": "Conversations",
       "description": "Manage conversation history"
+    },
+    {
+      "name": "Knowledge",
+      "description": "Manage knowledge sources used by custom agents"
     }
   ],
   "paths": {
@@ -45,7 +53,7 @@
         "tags": [
           "Agents Configuration"
         ],
-        "summary": "createAgent",
+        "summary": "Create Agent definition",
         "description": "Creates a new custom agent. System skills cannot be created via this endpoint.",
         "operationId": "createAgent",
         "security": [
@@ -90,7 +98,7 @@
         "tags": [
           "Agents Configuration"
         ],
-        "summary": "listAgents",
+        "summary": "List all agent configurations",
         "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 +156,7 @@
         "tags": [
           "Agents Configuration"
         ],
-        "summary": "getAgentById",
+        "summary": "Get the agent configuration by ID",
         "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 +201,7 @@
         "tags": [
           "Agents Configuration"
         ],
-        "summary": "updateAgentById",
+        "summary": "Update the agent configuration by ID",
         "description": "Updates a custom agent. System skills cannot be updated via this endpoint.",
         "operationId": "updateAgentById",
         "security": [
@@ -241,6 +249,26 @@
                 }
               }
             }
+          },
+          "404": {
+            "description": "Agent not found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "409": {
+            "description": "Agent changed during the update; retry the request",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
           }
         }
       },
@@ -248,7 +276,7 @@
         "tags": [
           "Agents Configuration"
         ],
-        "summary": "deleteAgentById",
+        "summary": "Delete the agent configuration by ID",
         "description": "Deletes a custom agent. System skills cannot be deleted via this endpoint.",
         "security": [
           {
@@ -283,62 +311,32 @@
         }
       }
     },
-    "/v1/agents/{agent_id}/execute": {
-      "post": {
+    "/v1/customer-chat": {
+      "get": {
         "tags": [
-          "Agent Execution"
+          "Customer Chat"
         ],
-        "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",
+        "summary": "List customer chat agents",
+        "description": "Returns the org's website agent (at most one) first, then its portal agents ordered by created_at ascending.",
+        "operationId": "listCustomerChat",
         "security": [
           {
             "EpilotAuth": []
           }
         ],
-        "parameters": [
-          {
-            "name": "agent_id",
-            "in": "path",
-            "required": true,
-            "schema": {
-              "$ref": "#/components/schemas/AgentId"
-            }
-          }
-        ],
-        "requestBody": {
-          "required": false,
-          "content": {
-            "application/json": {
-              "schema": {
-                "$ref": "#/components/schemas/ExecuteAgentRequest"
-              }
-            }
-          }
-        },
         "responses": {
           "200": {
-            "description": "Agent execution initiated or completed",
+            "description": "Customer Chat agents",
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/ExecutionResponse"
+                  "$ref": "#/components/schemas/ListCustomerChatResponse"
                 }
               }
             }
           },
           "400": {
-            "description": "Error while executing the agent",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/Error"
-                }
-              }
-            }
-          },
-          "404": {
-            "description": "Agent not found",
+            "description": "Error listing customer chat",
             "content": {
               "application/json": {
                 "schema": {
@@ -348,54 +346,42 @@
             }
           }
         }
-      }
-    },
-    "/v1/agents/{agent_id}/execute/stream": {
+      },
       "post": {
         "tags": [
-          "Agent Execution"
+          "Customer Chat"
         ],
-        "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",
+        "summary": "Create a customer chat agent with default config",
+        "description": "Mints agent_id (equal to runtime_agent_id) and compiles the runtime AgentRecord. An org can have at most one website agent (409 on a second one) and any number of portal agents.",
+        "operationId": "createCustomerChatAgent",
         "security": [
           {
             "EpilotAuth": []
           }
         ],
-        "parameters": [
-          {
-            "name": "agent_id",
-            "in": "path",
-            "required": true,
-            "schema": {
-              "$ref": "#/components/schemas/AgentId"
-            }
-          }
-        ],
         "requestBody": {
-          "required": false,
+          "required": true,
           "content": {
             "application/json": {
               "schema": {
-                "$ref": "#/components/schemas/ExecuteAgentRequest"
+                "$ref": "#/components/schemas/CreateCustomerChatAgentRequest"
               }
             }
           }
         },
         "responses": {
-          "200": {
-            "description": "SSE stream of execution events",
+          "201": {
+            "description": "Customer Chat agent created",
             "content": {
-              "text/event-stream": {
+              "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/StreamEvent"
+                  "$ref": "#/components/schemas/CustomerChatAgent"
                 }
               }
             }
           },
           "400": {
-            "description": "Error while executing the agent",
+            "description": "Invalid request",
             "content": {
               "application/json": {
                 "schema": {
@@ -404,8 +390,8 @@
               }
             }
           },
-          "404": {
-            "description": "Agent not found",
+          "409": {
+            "description": "The org already has a website agent",
             "content": {
               "application/json": {
                 "schema": {
@@ -417,63 +403,26 @@
         }
       }
     },
-    "/v1/executions": {
+    "/v1/customer-chat/capabilities": {
       "get": {
         "tags": [
-          "Agent Execution"
+          "Customer Chat"
         ],
-        "summary": "listExecutions",
-        "description": "List executions",
-        "operationId": "listExecutions",
+        "summary": "List the capability catalog",
+        "description": "Capabilities admins can enable and the places they are offered on.\nSingle source of truth for Agent Builder; capabilities that are no\nlonger offered are omitted, while already-enabled instances of them\nkeep working.\n",
+        "operationId": "listCustomerChatCapabilities",
         "security": [
           {
             "EpilotAuth": []
           }
         ],
-        "parameters": [
-          {
-            "name": "agent_id",
-            "in": "query",
-            "schema": {
-              "type": "string"
-            },
-            "description": "Filter by agent ID"
-          },
-          {
-            "name": "status",
-            "in": "query",
-            "schema": {
-              "$ref": "#/components/schemas/ExecutionStatus"
-            },
-            "description": "Filter by status"
-          },
-          {
-            "name": "limit",
-            "in": "query",
-            "schema": {
-              "type": "integer",
-              "default": 50
-            },
-            "description": "Maximum number of executions to return"
-          }
-        ],
         "responses": {
           "200": {
-            "description": "List of executions",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/ListExecutionsResponse"
-                }
-              }
-            }
-          },
-          "400": {
-            "description": "Error fetching executions",
+            "description": "Capability catalog",
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/Error"
+                  "$ref": "#/components/schemas/ListCustomerChatCapabilitiesResponse"
                 }
               }
             }
@@ -481,14 +430,13 @@
         }
       }
     },
-    "/v1/executions/{execution_id}": {
+    "/v1/customer-chat/{agent_id}": {
       "get": {
         "tags": [
-          "Agent Execution"
+          "Customer Chat"
         ],
-        "summary": "getExecution",
-        "description": "Get execution by ID",
-        "operationId": "getExecution",
+        "summary": "Get a customer chat agent",
+        "operationId": "getCustomerChatAgent",
         "security": [
           {
             "EpilotAuth": []
@@ -496,28 +444,22 @@
         ],
         "parameters": [
           {
-            "name": "execution_id",
-            "in": "path",
-            "required": true,
-            "schema": {
-              "type": "string",
-              "format": "uuid"
-            }
+            "$ref": "#/components/parameters/CustomerChatAgentIdPath"
           }
         ],
         "responses": {
           "200": {
-            "description": "Execution details",
+            "description": "Customer Chat agent",
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/ExecutionResponse"
+                  "$ref": "#/components/schemas/CustomerChatAgent"
                 }
               }
             }
           },
           "404": {
-            "description": "Execution not found",
+            "description": "Customer Chat agent not found",
             "content": {
               "application/json": {
                 "schema": {
@@ -528,13 +470,12 @@
           }
         }
       },
-      "delete": {
+      "patch": {
         "tags": [
-          "Agent Execution"
+          "Customer Chat"
         ],
-        "summary": "cancelExecution",
-        "description": "Cancel execution",
-        "operationId": "cancelExecution",
+        "summary": "Rename a customer chat agent",
+        "operationId": "renameCustomerChatAgent",
         "security": [
           {
             "EpilotAuth": []
@@ -542,28 +483,35 @@
         ],
         "parameters": [
           {
-            "name": "execution_id",
-            "in": "path",
-            "required": true,
-            "schema": {
-              "type": "string",
-              "format": "uuid"
-            }
+            "$ref": "#/components/parameters/CustomerChatAgentIdPath"
+          },
+          {
+            "$ref": "#/components/parameters/IfMatchUpdatedAt"
           }
         ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/RenameCustomerChatAgentRequest"
+              }
+            }
+          }
+        },
         "responses": {
           "200": {
-            "description": "Execution cancelled",
+            "description": "Customer Chat agent renamed",
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/ExecutionResponse"
+                  "$ref": "#/components/schemas/CustomerChatAgent"
                 }
               }
             }
           },
           "400": {
-            "description": "Cannot cancel execution (already completed or failed)",
+            "description": "Invalid request",
             "content": {
               "application/json": {
                 "schema": {
@@ -573,7 +521,17 @@
             }
           },
           "404": {
-            "description": "Execution not found",
+            "description": "Customer Chat agent not found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "409": {
+            "description": "Stale update",
             "content": {
               "application/json": {
                 "schema": {
@@ -583,16 +541,14 @@
             }
           }
         }
-      }
-    },
-    "/v1/executions/{execution_id}/trace": {
-      "get": {
+      },
+      "delete": {
         "tags": [
-          "Agent Execution"
+          "Customer Chat"
         ],
-        "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",
+        "summary": "Remove a customer chat agent and its runtime projection",
+        "description": "Deletes the place agent. For portal agents, also clears\n`feature_settings.portal_copilot_agent_id` on linked portals (pass\n`portal_id` when known, otherwise the API scans org portal configs)\nbefore deleting, so a single request cannot leave an orphan agent.\n",
+        "operationId": "deleteCustomerChatAgent",
         "security": [
           {
             "EpilotAuth": []
@@ -600,28 +556,38 @@
         ],
         "parameters": [
           {
-            "name": "execution_id",
-            "in": "path",
-            "required": true,
-            "schema": {
-              "type": "string",
-              "format": "uuid"
-            }
+            "$ref": "#/components/parameters/CustomerChatAgentIdPath"
+          },
+          {
+            "$ref": "#/components/parameters/IfMatchUpdatedAt"
           }
         ],
+        "requestBody": {
+          "required": false,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/DeleteCustomerChatAgentRequest"
+              }
+            }
+          }
+        },
         "responses": {
-          "200": {
-            "description": "Execution trace",
+          "204": {
+            "description": "Customer Chat agent deleted"
+          },
+          "404": {
+            "description": "Customer Chat agent not found",
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/ExecutionTrace"
+                  "$ref": "#/components/schemas/Error"
                 }
               }
             }
           },
-          "404": {
-            "description": "Execution not found",
+          "409": {
+            "description": "Stale update",
             "content": {
               "application/json": {
                 "schema": {
@@ -633,14 +599,13 @@
         }
       }
     },
-    "/v1/executions/{execution_id}/feedback": {
-      "get": {
+    "/v1/customer-chat/{agent_id}/config": {
+      "put": {
         "tags": [
-          "Agent Execution"
+          "Customer Chat"
         ],
-        "summary": "Get execution feedback",
-        "description": "Returns the authenticated user's feedback for an execution.",
-        "operationId": "getExecutionFeedback",
+        "summary": "Replace the AgentConfig and compile the runtime AgentRecord",
+        "operationId": "saveCustomerChatConfig",
         "security": [
           {
             "EpilotAuth": []
@@ -648,28 +613,55 @@
         ],
         "parameters": [
           {
-            "name": "execution_id",
-            "in": "path",
-            "required": true,
-            "schema": {
-              "type": "string",
-              "format": "uuid"
-            }
+            "$ref": "#/components/parameters/CustomerChatAgentIdPath"
+          },
+          {
+            "$ref": "#/components/parameters/IfMatchUpdatedAt"
           }
         ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/SaveCustomerChatConfigRequest"
+              }
+            }
+          }
+        },
         "responses": {
           "200": {
-            "description": "Feedback state",
+            "description": "Config saved",
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/ExecutionFeedbackResponse"
+                  "$ref": "#/components/schemas/CustomerChatAgent"
                 }
               }
             }
           },
-          "404": {
-            "description": "Execution not found",
+          "400": {
+            "description": "Invalid config",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Customer Chat agent not found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "409": {
+            "description": "Stale update",
             "content": {
               "application/json": {
                 "schema": {
@@ -678,64 +670,61 @@
               }
             }
           }
-        }
-      },
-      "put": {
-        "tags": [
-          "Agent Execution"
-        ],
-        "summary": "Submit execution feedback",
-        "description": "Upserts thumbs up/down feedback and mirrors it to the execution's Langfuse trace.",
-        "operationId": "putExecutionFeedback",
-        "security": [
-          {
-            "EpilotAuth": []
-          }
+        }
+      }
+    },
+    "/v1/knowledge/sources": {
+      "get": {
+        "tags": [
+          "Knowledge"
         ],
-        "parameters": [
-          {
-            "name": "execution_id",
-            "in": "path",
-            "required": true,
-            "schema": {
-              "type": "string",
-              "format": "uuid"
+        "summary": "List knowledge sources",
+        "operationId": "listKnowledgeSources",
+        "responses": {
+          "200": {
+            "description": "Knowledge sources available to the organization",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ListKnowledgeSourcesResponse"
+                }
+              }
             }
           }
+        }
+      }
+    },
+    "/v1/knowledge/file-uploads": {
+      "post": {
+        "tags": [
+          "Knowledge"
         ],
+        "summary": "Create a knowledge file upload",
+        "description": "Returns a direct S3 upload. The source becomes available after S3 confirms the completed object.",
+        "operationId": "createKnowledgeFileUpload",
         "requestBody": {
           "required": true,
           "content": {
             "application/json": {
               "schema": {
-                "$ref": "#/components/schemas/PutExecutionFeedbackRequest"
+                "$ref": "#/components/schemas/CreateKnowledgeFileUploadRequest"
               }
             }
           }
         },
         "responses": {
-          "200": {
-            "description": "Feedback recorded",
+          "201": {
+            "description": "Upload created",
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/ExecutionFeedbackResponse"
+                  "$ref": "#/components/schemas/CreateKnowledgeFileUploadResponse"
                 }
               }
             }
           },
           "400": {
-            "description": "Invalid feedback",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/Error"
-                }
-              }
-            }
-          },
-          "404": {
-            "description": "Execution not found",
+            "description": "Invalid file metadata",
             "content": {
               "application/json": {
                 "schema": {
@@ -745,7 +734,7 @@
             }
           },
           "409": {
-            "description": "Execution cannot be rated",
+            "description": "Organization knowledge source limit reached",
             "content": {
               "application/json": {
                 "schema": {
@@ -757,52 +746,37 @@
         }
       }
     },
-    "/v1/executions/{execution_id}/approve": {
-      "post": {
-        "tags": [
-          "Agent Execution"
-        ],
-        "summary": "approveExecution",
-        "description": "Approves a pending tool action when execution is in waiting_approval status",
-        "operationId": "approveExecution",
-        "security": [
-          {
-            "EpilotAuth": []
-          }
-        ],
-        "parameters": [
-          {
-            "name": "execution_id",
-            "in": "path",
-            "required": true,
-            "schema": {
-              "type": "string",
-              "format": "uuid"
-            }
+    "/v1/knowledge/sources/{source_id}": {
+      "parameters": [
+        {
+          "name": "source_id",
+          "in": "path",
+          "required": true,
+          "schema": {
+            "type": "string",
+            "format": "uuid"
           }
+        }
+      ],
+      "get": {
+        "tags": [
+          "Knowledge"
         ],
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "schema": {
-                "$ref": "#/components/schemas/ApproveExecutionRequest"
-              }
-            }
-          }
-        },
+        "summary": "Get a knowledge source",
+        "operationId": "getKnowledgeSource",
         "responses": {
           "200": {
-            "description": "Action approved",
+            "description": "Knowledge source",
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/ExecutionResponse"
+                  "$ref": "#/components/schemas/KnowledgeSource"
                 }
               }
             }
           },
-          "400": {
-            "description": "No pending action to approve",
+          "404": {
+            "description": "Knowledge source not found",
             "content": {
               "application/json": {
                 "schema": {
@@ -810,9 +784,21 @@
                 }
               }
             }
+          }
+        }
+      },
+      "delete": {
+        "tags": [
+          "Knowledge"
+        ],
+        "summary": "Delete a knowledge source",
+        "operationId": "deleteKnowledgeSource",
+        "responses": {
+          "204": {
+            "description": "Knowledge source deleted"
           },
-          "404": {
-            "description": "Execution not found",
+          "409": {
+            "description": "Knowledge source is referenced by an agent",
             "content": {
               "application/json": {
                 "schema": {
@@ -824,14 +810,14 @@
         }
       }
     },
-    "/v1/executions/{execution_id}/reject": {
+    "/v1/agents/{agent_id}/execute": {
       "post": {
         "tags": [
           "Agent Execution"
         ],
-        "summary": "rejectExecution",
-        "description": "Rejects a pending tool action when execution is in waiting_approval status",
-        "operationId": "rejectExecution",
+        "summary": "Execute an agent",
+        "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": [
           {
             "EpilotAuth": []
@@ -839,28 +825,37 @@
         ],
         "parameters": [
           {
-            "name": "execution_id",
+            "name": "agent_id",
             "in": "path",
             "required": true,
             "schema": {
-              "type": "string",
-              "format": "uuid"
+              "$ref": "#/components/schemas/AgentId"
             }
           }
         ],
         "requestBody": {
-          "required": true,
+          "required": false,
           "content": {
             "application/json": {
               "schema": {
-                "$ref": "#/components/schemas/RejectExecutionRequest"
+                "$ref": "#/components/schemas/ExecuteAgentRequest"
               }
             }
           }
         },
         "responses": {
           "200": {
-            "description": "Action rejected",
+            "description": "Completed execution (`mode: sync`)",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ExecutionResponse"
+                }
+              }
+            }
+          },
+          "201": {
+            "description": "Execution accepted; poll it by `execution_id`",
             "content": {
               "application/json": {
                 "schema": {
@@ -870,7 +865,7 @@
             }
           },
           "400": {
-            "description": "No pending action to reject",
+            "description": "Error while executing the agent",
             "content": {
               "application/json": {
                 "schema": {
@@ -880,7 +875,7 @@
             }
           },
           "404": {
-            "description": "Execution not found",
+            "description": "Agent not found",
             "content": {
               "application/json": {
                 "schema": {
@@ -888,55 +883,19 @@
                 }
               }
             }
-          }
-        }
-      }
-    },
-    "/v1/executions/{execution_id}/stream": {
-      "get": {
-        "tags": [
-          "Agent Execution"
-        ],
-        "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": [
-          {
-            "EpilotAuth": []
-          }
-        ],
-        "parameters": [
-          {
-            "name": "execution_id",
-            "in": "path",
-            "required": true,
-            "schema": {
-              "type": "string",
-              "format": "uuid"
-            }
           },
-          {
-            "name": "from_sequence",
-            "in": "query",
-            "schema": {
-              "type": "integer"
-            },
-            "description": "Resume from this event sequence number (for reconnection)"
-          }
-        ],
-        "responses": {
-          "200": {
-            "description": "SSE stream of execution events",
+          "422": {
+            "description": "`mode: sync`: the input exceeds the model's context window (`error: INPUT_TOO_LONG`)",
             "content": {
-              "text/event-stream": {
+              "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/StreamEvent"
+                  "$ref": "#/components/schemas/Error"
                 }
               }
             }
           },
-          "404": {
-            "description": "Execution not found",
+          "504": {
+            "description": "`mode: sync`: the model did not answer within the request deadline (`error: TIMEOUT`)",
             "content": {
               "application/json": {
                 "schema": {
@@ -948,32 +907,42 @@
         }
       }
     },
-    "/v1/chat": {
+    "/v1/agents/{agent_id}/execute/stream": {
       "post": {
         "tags": [
-          "Chat"
+          "Agent Execution"
         ],
-        "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",
+        "summary": "Execute an agent with streaming response",
+        "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": [
           {
             "EpilotAuth": []
           }
         ],
+        "parameters": [
+          {
+            "name": "agent_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "$ref": "#/components/schemas/AgentId"
+            }
+          }
+        ],
         "requestBody": {
-          "required": true,
+          "required": false,
           "content": {
             "application/json": {
               "schema": {
-                "$ref": "#/components/schemas/ChatRequest"
+                "$ref": "#/components/schemas/ExecuteAgentRequest"
               }
             }
           }
         },
         "responses": {
           "200": {
-            "description": "SSE stream of chat events",
+            "description": "SSE stream of execution events",
             "content": {
               "text/event-stream": {
                 "schema": {
@@ -983,7 +952,7 @@
             }
           },
           "400": {
-            "description": "Invalid request",
+            "description": "Error while executing the agent",
             "content": {
               "application/json": {
                 "schema": {
@@ -1005,14 +974,14 @@
         }
       }
     },
-    "/v1/conversations": {
+    "/v1/executions": {
       "get": {
         "tags": [
-          "Conversations"
+          "Agent Execution"
         ],
-        "summary": "listConversations",
-        "description": "Lists conversations for the authenticated user, sorted by most recent.",
-        "operationId": "listConversations",
+        "summary": "List executions",
+        "description": "List executions",
+        "operationId": "listExecutions",
         "security": [
           {
             "EpilotAuth": []
@@ -1028,36 +997,36 @@
             "description": "Filter by agent ID"
           },
           {
-            "name": "limit",
+            "name": "status",
             "in": "query",
             "schema": {
-              "type": "integer",
-              "default": 20
+              "$ref": "#/components/schemas/ExecutionStatus"
             },
-            "description": "Maximum number of conversations to return"
+            "description": "Filter by status"
           },
           {
-            "name": "cursor",
+            "name": "limit",
             "in": "query",
             "schema": {
-              "type": "string"
+              "type": "integer",
+              "default": 50
             },
-            "description": "Pagination cursor"
+            "description": "Maximum number of executions to return"
           }
         ],
         "responses": {
           "200": {
-            "description": "List of conversations",
+            "description": "List of executions",
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/ListConversationsResponse"
+                  "$ref": "#/components/schemas/ListExecutionsResponse"
                 }
               }
             }
           },
           "400": {
-            "description": "Error fetching conversations",
+            "description": "Error fetching executions",
             "content": {
               "application/json": {
                 "schema": {
@@ -1069,14 +1038,14 @@
         }
       }
     },
-    "/v1/conversations/{conversation_id}": {
+    "/v1/executions/{execution_id}": {
       "get": {
         "tags": [
-          "Conversations"
+          "Agent Execution"
         ],
-        "summary": "getConversation",
-        "description": "Retrieves a conversation and its message history.",
-        "operationId": "getConversation",
+        "summary": "Get execution by ID",
+        "description": "Get execution by ID",
+        "operationId": "getExecution",
         "security": [
           {
             "EpilotAuth": []
@@ -1084,37 +1053,180 @@
         ],
         "parameters": [
           {
-            "name": "conversation_id",
+            "name": "execution_id",
             "in": "path",
             "required": true,
             "schema": {
               "type": "string",
               "format": "uuid"
             }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Execution details",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ExecutionResponse"
+                }
+              }
+            }
           },
+          "404": {
+            "description": "Execution not found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          }
+        }
+      },
+      "delete": {
+        "tags": [
+          "Agent Execution"
+        ],
+        "summary": "Cancel execution",
+        "description": "Cancel execution",
+        "operationId": "cancelExecution",
+        "security": [
           {
-            "name": "message_limit",
-            "in": "query",
+            "EpilotAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "name": "execution_id",
+            "in": "path",
+            "required": true,
             "schema": {
-              "type": "integer",
-              "default": 100
-            },
-            "description": "Maximum number of messages to return"
+              "type": "string",
+              "format": "uuid"
+            }
           }
         ],
         "responses": {
           "200": {
-            "description": "Conversation with messages",
+            "description": "Execution cancelled",
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/ConversationWithMessages"
+                  "$ref": "#/components/schemas/ExecutionResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Cannot cancel execution (already completed or failed)",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
                 }
               }
             }
           },
           "404": {
-            "description": "Conversation not found",
+            "description": "Execution not found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/executions/{execution_id}/trace": {
+      "get": {
+        "tags": [
+          "Agent Execution"
+        ],
+        "summary": "Get execution trace/iterations",
+        "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": [
+          {
+            "EpilotAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "name": "execution_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Execution trace",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ExecutionTrace"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Execution not found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/executions/{execution_id}/feedback": {
+      "get": {
+        "tags": [
+          "Agent Execution"
+        ],
+        "summary": "Get execution feedback",
+        "description": "Returns the authenticated user's feedback for an execution.",
+        "operationId": "getExecutionFeedback",
+        "security": [
+          {
+            "EpilotAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "name": "execution_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Feedback state",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ExecutionFeedbackResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Execution not found",
             "content": {
               "application/json": {
                 "schema": {
@@ -1125,13 +1237,13 @@
           }
         }
       },
-      "delete": {
+      "put": {
         "tags": [
-          "Conversations"
+          "Agent Execution"
         ],
-        "summary": "deleteConversation",
-        "description": "Deletes a conversation and all its messages.",
-        "operationId": "deleteConversation",
+        "summary": "Submit execution feedback",
+        "description": "Upserts thumbs up/down feedback and mirrors it to the execution's Langfuse trace.",
+        "operationId": "putExecutionFeedback",
         "security": [
           {
             "EpilotAuth": []
@@ -1139,7 +1251,85 @@
         ],
         "parameters": [
           {
-            "name": "conversation_id",
+            "name": "execution_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PutExecutionFeedbackRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Feedback recorded",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ExecutionFeedbackResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Invalid feedback",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Execution not found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "409": {
+            "description": "Execution cannot be rated",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/executions/{execution_id}/approve": {
+      "post": {
+        "tags": [
+          "Agent Execution"
+        ],
+        "summary": "Approve pending action",
+        "description": "Approves a pending tool action when execution is in waiting_approval status",
+        "operationId": "approveExecution",
+        "security": [
+          {
+            "EpilotAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "name": "execution_id",
             "in": "path",
             "required": true,
             "schema": {
@@ -1148,111 +1338,1171 @@
             }
           }
         ],
-        "responses": {
-          "204": {
-            "description": "Conversation deleted"
-          },
-          "404": {
-            "description": "Conversation not found",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/Error"
-                }
-              }
-            }
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ApproveExecutionRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Action approved",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ExecutionResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "No pending action to approve",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Execution not found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/executions/{execution_id}/reject": {
+      "post": {
+        "tags": [
+          "Agent Execution"
+        ],
+        "summary": "Reject pending action",
+        "description": "Rejects a pending tool action when execution is in waiting_approval status",
+        "operationId": "rejectExecution",
+        "security": [
+          {
+            "EpilotAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "name": "execution_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/RejectExecutionRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Action rejected",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ExecutionResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "No pending action to reject",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Execution not found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/executions/{execution_id}/stream": {
+      "get": {
+        "tags": [
+          "Agent Execution"
+        ],
+        "summary": "Reconnect to execution stream",
+        "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": [
+          {
+            "EpilotAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "name": "execution_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          },
+          {
+            "name": "from_sequence",
+            "in": "query",
+            "schema": {
+              "type": "integer"
+            },
+            "description": "Resume from this event sequence number (for reconnection)"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "SSE stream of execution events",
+            "content": {
+              "text/event-stream": {
+                "schema": {
+                  "$ref": "#/components/schemas/StreamEvent"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Execution not found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/chat": {
+      "post": {
+        "tags": [
+          "Chat"
+        ],
+        "summary": "Streaming chat with AI agent",
+        "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": [
+          {
+            "EpilotAuth": []
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ChatRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "SSE stream of chat events",
+            "content": {
+              "text/event-stream": {
+                "schema": {
+                  "$ref": "#/components/schemas/StreamEvent"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Invalid request",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Agent not found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/conversations": {
+      "get": {
+        "tags": [
+          "Conversations"
+        ],
+        "summary": "List conversations",
+        "description": "Lists conversations for the authenticated user, sorted by most recent.",
+        "operationId": "listConversations",
+        "security": [
+          {
+            "EpilotAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "name": "agent_id",
+            "in": "query",
+            "schema": {
+              "type": "string"
+            },
+            "description": "Filter by agent ID"
+          },
+          {
+            "name": "limit",
+            "in": "query",
+            "schema": {
+              "type": "integer",
+              "default": 20
+            },
+            "description": "Maximum number of conversations to return"
+          },
+          {
+            "name": "cursor",
+            "in": "query",
+            "schema": {
+              "type": "string"
+            },
+            "description": "Pagination cursor"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "List of conversations",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ListConversationsResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Error fetching conversations",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/conversations/{conversation_id}": {
+      "get": {
+        "tags": [
+          "Conversations"
+        ],
+        "summary": "Get conversation with messages",
+        "description": "Retrieves a conversation and its message history.",
+        "operationId": "getConversation",
+        "security": [
+          {
+            "EpilotAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "name": "conversation_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          },
+          {
+            "name": "message_limit",
+            "in": "query",
+            "schema": {
+              "type": "integer",
+              "default": 100
+            },
+            "description": "Maximum number of messages to return"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Conversation with messages",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ConversationWithMessages"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Conversation not found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          }
+        }
+      },
+      "delete": {
+        "tags": [
+          "Conversations"
+        ],
+        "summary": "Delete conversation",
+        "description": "Deletes a conversation and all its messages.",
+        "operationId": "deleteConversation",
+        "security": [
+          {
+            "EpilotAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "name": "conversation_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "Conversation deleted"
+          },
+          "404": {
+            "description": "Conversation not found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/conversations/{conversation_id}/feedback": {
+      "post": {
+        "tags": [
+          "Conversations"
+        ],
+        "summary": "Submit feedback for an assistant turn",
+        "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": [
+          {
+            "EpilotAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "name": "conversation_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/SubmitFeedbackRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Feedback recorded",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "feedback": {
+                      "$ref": "#/components/schemas/MessageFeedback"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Invalid request",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Conversation or message not found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "securitySchemes": {
+      "EpilotAuth": {
+        "type": "http",
+        "scheme": "bearer",
+        "description": "Authorization header with epilot OAuth2 bearer token. Supports RFC8725 for JWT validation.",
+        "bearerFormat": "JWT"
+      }
+    },
+    "parameters": {
+      "CustomerChatAgentIdPath": {
+        "name": "agent_id",
+        "in": "path",
+        "required": true,
+        "description": "Customer Chat agent id",
+        "schema": {
+          "type": "string"
+        }
+      },
+      "IfMatchUpdatedAt": {
+        "name": "If-Match",
+        "in": "header",
+        "required": false,
+        "description": "Compare-and-swap token. The agent's current `updated_at`; may be sent as `updated_at` in the body instead.",
+        "schema": {
+          "type": "string"
+        }
+      }
+    },
+    "schemas": {
+      "AgentConfig": {
+        "type": "object",
+        "required": [
+          "capabilities",
+          "knowledgeSources",
+          "escalation",
+          "appearance"
+        ],
+        "properties": {
+          "capabilities": {
+            "description": "Configured capability instances, up to 30 per agent. The same\ncatalog `type` may appear more than once when `label` (name) or\n`guidance` (when to use) differs between siblings.\n",
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/CapabilityInstance"
+            }
+          },
+          "knowledgeSources": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/CustomerChatKnowledgeSource"
+            }
+          },
+          "escalation": {
+            "$ref": "#/components/schemas/EscalationConfig"
+          },
+          "appearance": {
+            "$ref": "#/components/schemas/AppearanceConfig"
+          },
+          "instructions": {
+            "type": "string",
+            "maxLength": 8000,
+            "description": "Admin-editable briefing in the default `appearance.language`. Prefilled with a place default on create; omitted on save keeps the saved value."
+          },
+          "instructionTranslations": {
+            "type": "object",
+            "description": "Briefings for each language in `appearance.languages` other than `appearance.language`. Only present once the agent speaks a second language.",
+            "properties": {
+              "de": {
+                "type": "string",
+                "maxLength": 8000
+              },
+              "en": {
+                "type": "string",
+                "maxLength": 8000
+              }
+            }
+          },
+          "instructionsNeedsReview": {
+            "type": "array",
+            "description": "Languages whose briefing changed in another language and are not checked yet.",
+            "items": {
+              "type": "string",
+              "enum": [
+                "de",
+                "en"
+              ]
+            }
+          }
+        }
+      },
+      "AppearanceConfig": {
+        "type": "object",
+        "required": [
+          "displayName",
+          "greeting",
+          "starters",
+          "language",
+          "formOfAddress"
+        ],
+        "properties": {
+          "displayName": {
+            "type": "string"
+          },
+          "greeting": {
+            "type": "string"
+          },
+          "starters": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "language": {
+            "type": "string",
+            "description": "Default language. The top-level texts are written in it.",
+            "enum": [
+              "de",
+              "en"
+            ]
+          },
+          "formOfAddress": {
+            "type": "string",
+            "enum": [
+              "sie",
+              "du"
+            ]
+          },
+          "languages": {
+            "type": "array",
+            "description": "Languages customers can chat in. Only present with two or more; always includes `language`.",
+            "items": {
+              "type": "string",
+              "enum": [
+                "de",
+                "en"
+              ]
+            }
+          },
+          "translations": {
+            "type": "object",
+            "description": "Texts for each language in `languages` other than `language`.",
+            "properties": {
+              "de": {
+                "$ref": "#/components/schemas/LocalizedAppearance"
+              },
+              "en": {
+                "$ref": "#/components/schemas/LocalizedAppearance"
+              }
+            }
+          },
+          "needsReview": {
+            "type": "object",
+            "description": "Per language, texts that changed in another language and are not checked yet.",
+            "properties": {
+              "de": {
+                "$ref": "#/components/schemas/LocalizedFieldList"
+              },
+              "en": {
+                "$ref": "#/components/schemas/LocalizedFieldList"
+              }
+            }
+          }
+        }
+      },
+      "LocalizedAppearance": {
+        "type": "object",
+        "required": [
+          "displayName",
+          "greeting",
+          "starters"
+        ],
+        "properties": {
+          "displayName": {
+            "type": "string"
+          },
+          "greeting": {
+            "type": "string"
+          },
+          "starters": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          }
+        }
+      },
+      "LocalizedFieldList": {
+        "type": "array",
+        "items": {
+          "type": "string",
+          "enum": [
+            "displayName",
+            "greeting",
+            "starters"
+          ]
+        }
+      },
+      "CapabilityId": {
+        "type": "string",
+        "enum": [
+          "navigate_portal_pages",
+          "search_portal_records",
+          "view_billing",
+          "view_meter_readings",
+          "view_contracts",
+          "search_web",
+          "open_quick_actions",
+          "view_hems_energy"
+        ]
+      },
+      "ActionAutonomy": {
+        "type": "string",
+        "description": "Action capabilities only (`open_quick_actions`): per-capability autonomy.\n`draft` = suggest only (proposal + deep link, nothing opens),\n`approval` = the customer confirms in a card first,\n`automatic` = run immediately. Defaults to `approval` when the\ncapability is enabled without one; unknown values become `approval`;\nvalues above the capability's maximum are clamped down.\n",
+        "enum": [
+          "draft",
+          "approval",
+          "automatic"
+        ]
+      },
+      "CapabilityState": {
+        "type": "object",
+        "required": [
+          "enabled"
+        ],
+        "properties": {
+          "enabled": {
+            "type": "boolean"
+          },
+          "meterTypes": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "ticketType": {
+            "type": "string"
+          },
+          "allowedDomains": {
+            "type": "array",
+            "maxItems": 20,
+            "description": "`search_web` only. Websites web search may use, normalized to\n`host[/path]` (scheme, `www.`, query, fragment and trailing slash\nremoved; host lowercased; duplicates dropped). Empty or missing\nallows any website. When set, only `web_search.search` is granted.\n",
+            "items": {
+              "type": "string"
+            }
+          },
+          "autonomy": {
+            "$ref": "#/components/schemas/ActionAutonomy"
+          },
+          "label": {
+            "type": "string",
+            "maxLength": 100,
+            "description": "Admin label override. Kept on every capability so a disabled row stays listed."
+          },
+          "guidance": {
+            "type": "string",
+            "maxLength": 1000,
+            "description": "Admin guidance. Kept on every capability so a disabled row stays listed; action capabilities also inject it into the prompt."
+          },
+          "blockIds": {
+            "type": "array",
+            "description": "`open_quick_actions` only. Reserved tile allowlist (at most 200);\nempty or missing allows every quick-action tile on the linked portal.\n",
+            "items": {
+              "type": "string"
+            }
+          },
+          "integrationId": {
+            "type": "string",
+            "format": "uuid",
+            "description": "`view_hems_energy` only. Hub integration installation id used by\nHEMS portal tools (`portal.hems.snapshot` via list_devices, and\nwhen searchDeviceDocs is on also get_vendors /\nget_connection_options). Chosen in Agent Builder via the\nintegration picker.\n"
+          },
+          "searchDeviceDocs": {
+            "type": "boolean",
+            "description": "`view_hems_energy` only. When true or omitted, grants device\nonboarding docs tools (`portal.hems.vendors` via get_vendors +\n`portal.hems.onboarding_docs` via get_connection_options) once\nan integrationId is set. Set false to disable. Portal place only.\n"
+          }
+        }
+      },
+      "CapabilityInstance": {
+        "allOf": [
+          {
+            "type": "object",
+            "required": [
+              "type",
+              "enabled"
+            ],
+            "properties": {
+              "type": {
+                "$ref": "#/components/schemas/CapabilityId"
+              },
+              "instanceId": {
+                "type": "string",
+                "minLength": 1,
+                "description": "Stable id for this instance within the agent. Generated when\nomitted; send it back unchanged on later saves.\n"
+              }
+            }
+          },
+          {
+            "$ref": "#/components/schemas/CapabilityState"
+          }
+        ]
+      },
+      "CreateCustomerChatAgentRequest": {
+        "type": "object",
+        "required": [
+          "place"
+        ],
+        "properties": {
+          "place": {
+            "$ref": "#/components/schemas/CustomerChatPlace"
+          },
+          "internal_name": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 100
+          }
+        }
+      },
+      "CustomerChatAgent": {
+        "type": "object",
+        "required": [
+          "org_id",
+          "agent_id",
+          "place",
+          "internal_name",
+          "runtime_agent_id",
+          "config",
+          "created_at",
+          "updated_at"
+        ],
+        "properties": {
+          "org_id": {
+            "type": "string"
+          },
+          "agent_id": {
+            "type": "string",
+            "format": "uuid",
+            "description": "Stable id of the customer chat agent; equal to runtime_agent_id."
+          },
+          "place": {
+            "$ref": "#/components/schemas/CustomerChatPlace"
+          },
+          "internal_name": {
+            "type": "string"
+          },
+          "runtime_agent_id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "config": {
+            "$ref": "#/components/schemas/AgentConfig"
+          },
+          "created_at": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "updated_at": {
+            "type": "string",
+            "format": "date-time"
+          }
+        }
+      },
+      "CustomerChatCasRequest": {
+        "type": "object",
+        "properties": {
+          "updated_at": {
+            "type": "string",
+            "format": "date-time"
+          }
+        }
+      },
+      "DeleteCustomerChatAgentRequest": {
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/CustomerChatCasRequest"
+          },
+          {
+            "type": "object",
+            "properties": {
+              "portal_id": {
+                "type": "string",
+                "format": "uuid",
+                "description": "Portal linked to this agent (`feature_settings.portal_copilot_agent_id`).\nWhen set, only that portal is unlinked. When omitted for a portal agent,\norg portal configs are scanned for matching links.\n"
+              }
+            }
+          }
+        ]
+      },
+      "CustomerChatPlace": {
+        "type": "string",
+        "enum": [
+          "website",
+          "portal"
+        ]
+      },
+      "EscalationConfig": {
+        "type": "object",
+        "required": [
+          "websiteHandover"
+        ],
+        "properties": {
+          "websiteHandover": {
+            "$ref": "#/components/schemas/WebsiteHandover"
+          }
+        }
+      },
+      "CustomerChatKnowledgeSource": {
+        "type": "object",
+        "required": [
+          "id",
+          "type",
+          "title",
+          "targetId"
+        ],
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "type": {
+            "$ref": "#/components/schemas/CustomerChatKnowledgeSourceType"
+          },
+          "title": {
+            "type": "string"
+          },
+          "targetId": {
+            "type": "string"
+          },
+          "detail": {
+            "type": "string"
+          }
+        }
+      },
+      "CustomerChatKnowledgeSourceType": {
+        "type": "string",
+        "enum": [
+          "portal_page",
+          "document",
+          "catalogue",
+          "url"
+        ]
+      },
+      "ListCustomerChatResponse": {
+        "type": "object",
+        "required": [
+          "agents"
+        ],
+        "properties": {
+          "agents": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/CustomerChatAgent"
+            }
+          }
+        }
+      },
+      "CustomerChatCapabilityCatalogEntry": {
+        "type": "object",
+        "required": [
+          "id",
+          "places"
+        ],
+        "properties": {
+          "id": {
+            "$ref": "#/components/schemas/CapabilityId"
+          },
+          "places": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/CustomerChatPlace"
+            }
+          },
+          "singleInstance": {
+            "type": "boolean",
+            "description": "An agent can have this capability at most once. Agents that already\nhave more instances keep them, but cannot add another.\n"
+          },
+          "requiresIntegration": {
+            "type": "boolean",
+            "description": "Only offer this capability when the organization has a matching\nintegration set up.\n"
+          }
+        }
+      },
+      "ListCustomerChatCapabilitiesResponse": {
+        "type": "object",
+        "required": [
+          "capabilities"
+        ],
+        "properties": {
+          "capabilities": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/CustomerChatCapabilityCatalogEntry"
+            }
+          }
+        }
+      },
+      "RenameCustomerChatAgentRequest": {
+        "type": "object",
+        "required": [
+          "internal_name"
+        ],
+        "properties": {
+          "internal_name": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 100
+          },
+          "updated_at": {
+            "type": "string",
+            "format": "date-time"
+          }
+        }
+      },
+      "SaveCustomerChatConfigRequest": {
+        "type": "object",
+        "required": [
+          "config"
+        ],
+        "properties": {
+          "config": {
+            "$ref": "#/components/schemas/AgentConfig"
+          },
+          "updated_at": {
+            "type": "string",
+            "format": "date-time"
+          }
+        }
+      },
+      "WebsiteHandover": {
+        "type": "object",
+        "required": [
+          "kind",
+          "value"
+        ],
+        "properties": {
+          "kind": {
+            "type": "string",
+            "enum": [
+              "phone",
+              "email",
+              "journey",
+              "unset"
+            ]
+          },
+          "value": {
+            "type": "string"
+          },
+          "journeyId": {
+            "type": "string"
+          },
+          "journeyName": {
+            "type": "string"
+          }
+        }
+      },
+      "AgentId": {
+        "type": "string",
+        "description": "Agent identifier. Can be either:\n- System skill ID (prefixed): \"skill:email-categorizer\", \"skill:email-labeler\"\n- Custom agent UUID: \"0336a235-9417-4dd8-894c-fe81285bba75\"\n",
+        "example": "skill:email-categorizer"
+      },
+      "KnowledgeSourceIds": {
+        "type": "array",
+        "description": "Knowledge source IDs available to this agent. An empty array clears the selection.",
+        "uniqueItems": true,
+        "items": {
+          "type": "string",
+          "format": "uuid"
+        }
+      },
+      "KnowledgeSource": {
+        "oneOf": [
+          {
+            "$ref": "#/components/schemas/KnowledgeFileSource"
+          }
+        ],
+        "discriminator": {
+          "propertyName": "type",
+          "mapping": {
+            "file": "#/components/schemas/KnowledgeFileSource"
           }
         }
-      }
-    },
-    "/v1/conversations/{conversation_id}/feedback": {
-      "post": {
-        "tags": [
-          "Conversations"
+      },
+      "KnowledgeFileSource": {
+        "type": "object",
+        "required": [
+          "type",
+          "source_id",
+          "filename",
+          "mime_type",
+          "size_bytes",
+          "ready",
+          "created_at",
+          "updated_at"
         ],
-        "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": [
-          {
-            "EpilotAuth": []
+        "additionalProperties": false,
+        "properties": {
+          "type": {
+            "type": "string",
+            "enum": [
+              "file"
+            ]
+          },
+          "source_id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "filename": {
+            "type": "string"
+          },
+          "mime_type": {
+            "type": "string"
+          },
+          "size_bytes": {
+            "type": "integer",
+            "format": "int64"
+          },
+          "ready": {
+            "type": "boolean",
+            "description": "Whether the source is available for agent retrieval."
+          },
+          "created_at": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "updated_at": {
+            "type": "string",
+            "format": "date-time"
           }
+        }
+      },
+      "CreateKnowledgeFileUploadRequest": {
+        "type": "object",
+        "required": [
+          "filename",
+          "mime_type",
+          "size_bytes"
         ],
-        "parameters": [
-          {
-            "name": "conversation_id",
-            "in": "path",
-            "required": true,
-            "schema": {
-              "type": "string",
-              "format": "uuid"
-            }
+        "additionalProperties": false,
+        "properties": {
+          "filename": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 255
+          },
+          "mime_type": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 255
+          },
+          "size_bytes": {
+            "type": "integer",
+            "format": "int64",
+            "minimum": 1,
+            "maximum": 1000000000
           }
+        }
+      },
+      "CreateKnowledgeFileUploadResponse": {
+        "type": "object",
+        "required": [
+          "source_id",
+          "upload_url",
+          "upload_fields",
+          "expires_at"
         ],
-        "requestBody": {
-          "required": true,
-          "content": {
-            "application/json": {
-              "schema": {
-                "$ref": "#/components/schemas/SubmitFeedbackRequest"
-              }
-            }
-          }
-        },
-        "responses": {
-          "200": {
-            "description": "Feedback recorded",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "type": "object",
-                  "properties": {
-                    "feedback": {
-                      "$ref": "#/components/schemas/MessageFeedback"
-                    }
-                  }
-                }
-              }
-            }
+        "properties": {
+          "source_id": {
+            "type": "string",
+            "format": "uuid"
           },
-          "400": {
-            "description": "Invalid request",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/Error"
-                }
-              }
+          "upload_url": {
+            "type": "string",
+            "format": "uri"
+          },
+          "upload_fields": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "string"
             }
           },
-          "404": {
-            "description": "Conversation or message not found",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/Error"
-                }
-              }
+          "expires_at": {
+            "type": "string",
+            "format": "date-time"
+          }
+        }
+      },
+      "ListKnowledgeSourcesResponse": {
+        "type": "object",
+        "required": [
+          "sources"
+        ],
+        "properties": {
+          "sources": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/KnowledgeSource"
             }
           }
         }
-      }
-    }
-  },
-  "components": {
-    "securitySchemes": {
-      "EpilotAuth": {
-        "type": "http",
-        "scheme": "bearer",
-        "description": "Authorization header with epilot OAuth2 bearer token. Supports RFC8725 for JWT validation.",
-        "bearerFormat": "JWT"
-      }
-    },
-    "schemas": {
-      "AgentId": {
+      },
+      "AgentDomain": {
         "type": "string",
-        "description": "Agent identifier. Can be either:\n- System skill ID (prefixed): \"skill:email-categorizer\", \"skill:email-labeler\"\n- Custom agent UUID: \"0336a235-9417-4dd8-894c-fe81285bba75\"\n",
-        "example": "skill:email-categorizer"
+        "description": "Business domain selected in the agent builder.",
+        "enum": [
+          "customer_service",
+          "sales",
+          "billing",
+          "metering_grid",
+          "other"
+        ]
       },
       "CreateAgentRequest": {
         "type": "object",
@@ -1262,6 +2512,17 @@
           "execution_pattern"
         ],
         "properties": {
+          "domain": {
+            "$ref": "#/components/schemas/AgentDomain"
+          },
+          "availability": {
+            "type": "array",
+            "minItems": 1,
+            "uniqueItems": true,
+            "items": {
+              "$ref": "#/components/schemas/SkillAvailability"
+            }
+          },
           "name": {
             "type": "string",
             "minLength": 1,
@@ -1317,12 +2578,26 @@
           },
           "input_parameters_schema": {
             "$ref": "#/components/schemas/InputParametersSchema"
+          },
+          "knowledge_source_ids": {
+            "$ref": "#/components/schemas/KnowledgeSourceIds"
           }
         }
       },
       "UpdateAgentRequest": {
         "type": "object",
         "properties": {
+          "domain": {
+            "$ref": "#/components/schemas/AgentDomain"
+          },
+          "availability": {
+            "type": "array",
+            "minItems": 1,
+            "uniqueItems": true,
+            "items": {
+              "$ref": "#/components/schemas/SkillAvailability"
+            }
+          },
           "name": {
             "type": "string",
             "minLength": 1,
@@ -1367,12 +2642,18 @@
           },
           "input_parameters_schema": {
             "$ref": "#/components/schemas/InputParametersSchema"
+          },
+          "knowledge_source_ids": {
+            "$ref": "#/components/schemas/KnowledgeSourceIds"
           }
         }
       },
       "AgentDefinition": {
         "type": "object",
         "properties": {
+          "domain": {
+            "$ref": "#/components/schemas/AgentDomain"
+          },
           "agent_id": {
             "$ref": "#/components/schemas/AgentId"
           },
@@ -1442,6 +2723,9 @@
           "input_parameters_schema": {
             "$ref": "#/components/schemas/InputParametersSchema"
           },
+          "knowledge_source_ids": {
+            "$ref": "#/components/schemas/KnowledgeSourceIds"
+          },
           "version": {
             "type": "integer"
           },
@@ -1526,9 +2810,24 @@
       "ExecuteAgentRequest": {
         "type": "object",
         "properties": {
+          "mode": {
+            "type": "string",
+            "enum": [
+              "auto",
+              "stream",
+              "async",
+              "sync"
+            ],
+            "default": "auto",
+            "description": "`sync` runs the skill inside the request and answers 200 with the completed execution, or 422/504/500\nwith the failed execution's id in `details.execution_id`. Only for direct, tool-less, automatic skills;\nthe model call is cut off after 27 seconds.\n"
+          },
           "input": {
             "type": "object",
             "properties": {
+              "message": {
+                "type": "string",
+                "description": "Free-text instruction or query for the agent"
+              },
               "entity_id": {
                 "type": "string",
                 "description": "Primary entity ID for context"
@@ -1568,6 +2867,38 @@
                     "entity_schema"
                   ]
                 }
+              },
+              "attachment": {
+                "type": "object",
+                "description": "The file the agent should look at, referenced by S3 object. Only accepted by skills\nthat declare attachment support (currently direct-mode document skills). The object is\nread by the execution Lambda and passed to the model as an image or document content\nblock; images must be JPEG, PNG, GIF or WebP, documents PDF, DOCX, DOC, XLSX, XLS,\nCSV, TXT, HTML or Markdown. Callers are expected to downscale images and cap document\npages before referencing them.\n",
+                "required": [
+                  "s3ref",
+                  "mime_type"
+                ],
+                "properties": {
+                  "s3ref": {
+                    "type": "object",
+                    "required": [
+                      "bucket",
+                      "key"
+                    ],
+                    "properties": {
+                      "bucket": {
+                        "type": "string"
+                      },
+                      "key": {
+                        "type": "string"
+                      }
+                    }
+                  },
+                  "mime_type": {
+                    "type": "string",
+                    "description": "Mime type of the object, decides whether it is sent as an image or a document block."
+                  },
+                  "filename": {
+                    "type": "string"
+                  }
+                }
               }
             }
           },
@@ -1884,9 +3215,10 @@
       },
       "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",
+        "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\n`queued` is non-terminal: the execution is waiting for executor capacity and will\nbe followed by `started`, and it can be published more than once if a throttled\nexecution is put back on the queue. Consumers must not treat it as an outcome.\n",
         "enum": [
           "started",
+          "queued",
           "completed",
           "failed",
           "approval_required"
@@ -1981,6 +3313,93 @@
           }
         }
       },
+      "KnowledgeSourceRegisteredEvent": {
+        "description": "Detail payload of the `knowledge-source-registered` event, published on\nthe AI Agents event bus with source `ai-agents` after the source record\nexists in DynamoDB. Consumers must process `sourceId` idempotently.\n",
+        "oneOf": [
+          {
+            "$ref": "#/components/schemas/KnowledgeFileSourceRegisteredEvent"
+          }
+        ],
+        "discriminator": {
+          "propertyName": "type",
+          "mapping": {
+            "file": "#/components/schemas/KnowledgeFileSourceRegisteredEvent"
+          }
+        }
+      },
+      "KnowledgeFileSourceRegisteredEvent": {
+        "type": "object",
+        "required": [
+          "orgId",
+          "sourceId",
+          "type",
+          "bucket",
+          "key"
+        ],
+        "properties": {
+          "orgId": {
+            "type": "string"
+          },
+          "sourceId": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "type": {
+            "type": "string",
+            "enum": [
+              "file"
+            ]
+          },
+          "bucket": {
+            "type": "string"
+          },
+          "key": {
+            "type": "string"
+          }
+        }
+      },
+      "KnowledgeSourceDeletedEvent": {
+        "type": "object",
+        "description": "Published when a knowledge source is deleted.",
+        "required": [
+          "orgId",
+          "sourceId",
+          "type"
+        ],
+        "properties": {
+          "orgId": {
+            "type": "string"
+          },
+          "sourceId": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "type": {
+            "type": "string",
+            "enum": [
+              "file"
+            ]
+          }
+        }
+      },
+      "KnowledgeSourceProcessingCompletedEvent": {
+        "type": "object",
+        "description": "Published by a knowledge processing pipeline after all derived data for\nthe source has been stored and is available for agent retrieval. The\nevent uses source `knowledge-processing` and detail type\n`knowledge-source-processing-completed` on the AI Agents event bus.\n",
+        "required": [
+          "orgId",
+          "sourceId"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "orgId": {
+            "type": "string"
+          },
+          "sourceId": {
+            "type": "string",
+            "format": "uuid"
+          }
+        }
+      },
       "ToolPreview": {
         "type": "object",
         "description": "Structured preview data for approval UI. Provides a generic format that any tool can populate.",
@@ -2217,18 +3636,20 @@
           "flows",
           "copilot",
           "portals",
+          "website",
           "all"
         ],
-        "description": "Where the skill/agent is available:\n- flows: Available in workflow automations\n- copilot: Available as a sub-agent in copilot\n- portals: Available in end-user self-service portals\n- all: Available everywhere\n"
+        "description": "Where the skill/agent is available:\n- flows: Available in workflow automations\n- copilot: Available as a sub-agent in copilot\n- portals: Available in end-user self-service portals\n- website: Website chat, explicitly selected; currently supports anonymous execution\n- all: Available on the existing non-website surfaces; website requires explicit selection\n"
       },
       "ExecutionContext": {
         "type": "string",
         "enum": [
           "flows",
           "copilot",
-          "api"
+          "api",
+          "sharing"
         ],
-        "description": "Where the execution was triggered from:\n- flows: Triggered from workflow automation\n- copilot: Triggered from copilot assistant\n- api: Direct API call\n"
+        "description": "Where the execution was triggered from:\n- flows: Triggered from workflow automation\n- copilot: Triggered from copilot assistant\n- api: Direct API call\n- sharing: Triggered by sharing-api auto-sharing rules\n"
       },
       "ExecutionPattern": {
         "type": "string",
@@ -2251,6 +3672,7 @@
         "type": "string",
         "enum": [
           "pending",
+          "queued",
           "running",
           "waiting_approval",
           "completed",
@@ -2520,6 +3942,10 @@
           },
           "streaming": {
             "$ref": "#/components/schemas/StreamingOptions"
+          },
+          "preview_demo": {
+            "type": "boolean",
+            "description": "Agent Builder place-agent preview: when true, portal tools return\nsynthetic demo fixtures instead of calling customer-portal-api,\nand execution mode is forced to draft.\n"
           }
         }
       },