@epilot/sdk 2.19.3 → 2.19.5

package/definitions/ai-agents.json

@@ -0,0 +1,2863 @@
+{
+  "openapi": "3.0.0",
+  "info": {
+    "version": "3.0.0",
+    "title": "AI Agents API",
+    "description": "API for configuring and invoking AI agents in epilot platform",
+    "termsOfService": "https://epilot.cloud/agb",
+    "contact": {
+      "name": "Support",
+      "email": "info@epilot.cloud",
+      "url": "https://help.epilot.cloud"
+    }
+  },
+  "security": [
+    {
+      "EpilotAuth": []
+    }
+  ],
+  "servers": [
+    {
+      "url": "https://ai-agents.sls.epilot.io"
+    }
+  ],
+  "tags": [
+    {
+      "name": "Agents Configuration",
+      "description": "Everything about AI Agent configuration"
+    },
+    {
+      "name": "Agent Execution",
+      "description": "Execute AI agents and manage executions"
+    },
+    {
+      "name": "Chat",
+      "description": "Streaming chat with AI agents"
+    },
+    {
+      "name": "Conversations",
+      "description": "Manage conversation history"
+    }
+  ],
+  "paths": {
+    "/v1/agents": {
+      "post": {
+        "tags": [
+          "Agents Configuration"
+        ],
+        "summary": "createAgent",
+        "description": "Creates a new custom agent. System skills cannot be created via this endpoint.",
+        "operationId": "createAgent",
+        "security": [
+          {
+            "EpilotAuth": []
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CreateAgentRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "201": {
+            "description": "Agent Created Successfully",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/AgentDefinition"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Error while creating the agent",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          }
+        }
+      },
+      "get": {
+        "tags": [
+          "Agents Configuration"
+        ],
+        "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": [
+          {
+            "name": "source",
+            "in": "query",
+            "schema": {
+              "$ref": "#/components/schemas/AgentSource"
+            },
+            "description": "Filter by agent source (system = pre-built skills, custom = user-created)"
+          },
+          {
+            "name": "availability",
+            "in": "query",
+            "schema": {
+              "$ref": "#/components/schemas/SkillAvailability"
+            },
+            "description": "Filter by availability context (flows, copilot)"
+          },
+          {
+            "name": "entity_schema",
+            "in": "query",
+            "schema": {
+              "type": "string"
+            },
+            "description": "Filter by allowed entity schema (e.g., \"message\" for email-related skills)"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "List of agents",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ListAgentsResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Error fetching the agent configs",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/agents/{agent_id}": {
+      "get": {
+        "tags": [
+          "Agents Configuration"
+        ],
+        "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": [
+          {
+            "EpilotAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "name": "agent_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "$ref": "#/components/schemas/AgentId"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Agent fetched Successfully",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/AgentDefinition"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Error while creating the agent",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          }
+        }
+      },
+      "put": {
+        "tags": [
+          "Agents Configuration"
+        ],
+        "summary": "updateAgentById",
+        "description": "Updates a custom agent. System skills cannot be updated via this endpoint.",
+        "operationId": "updateAgentById",
+        "security": [
+          {
+            "EpilotAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "name": "agent_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "$ref": "#/components/schemas/AgentId"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/UpdateAgentRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Agent updated Successfully",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/AgentDefinition"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Error while updating the agent",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          }
+        }
+      },
+      "delete": {
+        "tags": [
+          "Agents Configuration"
+        ],
+        "summary": "deleteAgentById",
+        "description": "Deletes a custom agent. System skills cannot be deleted via this endpoint.",
+        "security": [
+          {
+            "EpilotAuth": []
+          }
+        ],
+        "operationId": "deleteAgentById",
+        "parameters": [
+          {
+            "name": "agent_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "$ref": "#/components/schemas/AgentId"
+            }
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "Agent deleted Successfully"
+          },
+          "400": {
+            "description": "Error while deleting the agent",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/agents/{agent_id}/execute": {
+      "post": {
+        "tags": [
+          "Agent Execution"
+        ],
+        "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": [
+          {
+            "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",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ExecutionResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Error while executing the agent",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Agent not found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/agents/{agent_id}/execute/stream": {
+      "post": {
+        "tags": [
+          "Agent Execution"
+        ],
+        "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": [
+          {
+            "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": "SSE stream of execution events",
+            "content": {
+              "text/event-stream": {
+                "schema": {
+                  "$ref": "#/components/schemas/StreamEvent"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Error while executing the agent",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Agent not found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/executions": {
+      "get": {
+        "tags": [
+          "Agent Execution"
+        ],
+        "summary": "listExecutions",
+        "description": "List executions",
+        "operationId": "listExecutions",
+        "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",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/executions/{execution_id}": {
+      "get": {
+        "tags": [
+          "Agent Execution"
+        ],
+        "summary": "getExecution",
+        "description": "Get execution by ID",
+        "operationId": "getExecution",
+        "security": [
+          {
+            "EpilotAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "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": "cancelExecution",
+        "description": "Cancel execution",
+        "operationId": "cancelExecution",
+        "security": [
+          {
+            "EpilotAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "name": "execution_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Execution cancelled",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ExecutionResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Cannot cancel execution (already completed or failed)",
+            "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}/trace": {
+      "get": {
+        "tags": [
+          "Agent Execution"
+        ],
+        "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": [
+          {
+            "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": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          }
+        }
+      },
+      "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": []
+          }
+        ],
+        "parameters": [
+          {
+            "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": "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"
+            }
+          }
+        ],
+        "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": "rejectExecution",
+        "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": "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",
+            "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": "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": [
+          {
+            "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": "listConversations",
+        "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": "getConversation",
+        "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": "deleteConversation",
+        "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": "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": []
+          }
+        ],
+        "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"
+      }
+    },
+    "schemas": {
+      "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"
+      },
+      "CreateAgentRequest": {
+        "type": "object",
+        "required": [
+          "name",
+          "system_prompt",
+          "execution_pattern"
+        ],
+        "properties": {
+          "name": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 100,
+            "example": "Email Reply Generator"
+          },
+          "description": {
+            "type": "string",
+            "maxLength": 1000
+          },
+          "category": {
+            "$ref": "#/components/schemas/SkillCategory"
+          },
+          "icon": {
+            "type": "string",
+            "example": "mail-reply"
+          },
+          "system_prompt": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Core LLM instructions"
+          },
+          "tools": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Tool IDs this agent can use",
+            "example": [
+              "entity.search",
+              "message.draft"
+            ]
+          },
+          "model_config": {
+            "$ref": "#/components/schemas/ModelConfig"
+          },
+          "max_iterations": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 20,
+            "default": 10,
+            "description": "Max ReAct loop iterations"
+          },
+          "execution_pattern": {
+            "$ref": "#/components/schemas/ExecutionPattern"
+          },
+          "execution_mode": {
+            "$ref": "#/components/schemas/ExecutionMode"
+          },
+          "output_schema": {
+            "type": "object",
+            "description": "JSON Schema for expected output"
+          },
+          "input_parameters_schema": {
+            "$ref": "#/components/schemas/InputParametersSchema"
+          }
+        }
+      },
+      "UpdateAgentRequest": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 100
+          },
+          "description": {
+            "type": "string",
+            "maxLength": 1000
+          },
+          "category": {
+            "$ref": "#/components/schemas/SkillCategory"
+          },
+          "icon": {
+            "type": "string"
+          },
+          "system_prompt": {
+            "type": "string",
+            "minLength": 1
+          },
+          "tools": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "model_config": {
+            "$ref": "#/components/schemas/ModelConfig"
+          },
+          "max_iterations": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 20
+          },
+          "execution_pattern": {
+            "$ref": "#/components/schemas/ExecutionPattern"
+          },
+          "execution_mode": {
+            "$ref": "#/components/schemas/ExecutionMode"
+          },
+          "output_schema": {
+            "type": "object"
+          },
+          "input_parameters_schema": {
+            "$ref": "#/components/schemas/InputParametersSchema"
+          }
+        }
+      },
+      "AgentDefinition": {
+        "type": "object",
+        "properties": {
+          "agent_id": {
+            "$ref": "#/components/schemas/AgentId"
+          },
+          "org_id": {
+            "type": "string"
+          },
+          "name": {
+            "type": "string"
+          },
+          "description": {
+            "type": "string"
+          },
+          "category": {
+            "$ref": "#/components/schemas/SkillCategory"
+          },
+          "icon": {
+            "type": "string"
+          },
+          "source": {
+            "$ref": "#/components/schemas/AgentSource"
+          },
+          "availability": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/SkillAvailability"
+            },
+            "description": "Where this agent/skill is available (flows, copilot, or both)",
+            "example": [
+              "flows",
+              "copilot"
+            ]
+          },
+          "allowed_entity_schemas": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Entity schemas this skill is allowed to work with (e.g., [\"message\"] for email skills)",
+            "example": [
+              "message"
+            ]
+          },
+          "system_prompt": {
+            "type": "string"
+          },
+          "tools": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "model_config": {
+            "$ref": "#/components/schemas/ModelConfig"
+          },
+          "max_iterations": {
+            "type": "integer"
+          },
+          "execution_pattern": {
+            "$ref": "#/components/schemas/ExecutionPattern"
+          },
+          "execution_mode": {
+            "$ref": "#/components/schemas/ExecutionMode"
+          },
+          "output_schema": {
+            "type": "object"
+          },
+          "input_parameters_schema": {
+            "$ref": "#/components/schemas/InputParametersSchema"
+          },
+          "version": {
+            "type": "integer"
+          },
+          "created_at": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "updated_at": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "created_by": {
+            "type": "string"
+          }
+        }
+      },
+      "ListAgentsResponse": {
+        "type": "object",
+        "properties": {
+          "agents": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/AgentDefinition"
+            }
+          },
+          "next_cursor": {
+            "type": "string",
+            "nullable": true
+          }
+        }
+      },
+      "ListExecutionsResponse": {
+        "type": "object",
+        "properties": {
+          "executions": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/ExecutionResponse"
+            }
+          },
+          "next_cursor": {
+            "type": "string",
+            "nullable": true
+          }
+        }
+      },
+      "ApproveExecutionRequest": {
+        "type": "object",
+        "properties": {
+          "reason": {
+            "type": "string",
+            "description": "Optional reason for approval"
+          },
+          "approved_action_ids": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "For batch approval - list of action IDs to approve. If not provided, all actions are approved."
+          },
+          "rejected_action_ids": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "For batch approval - list of action IDs to reject. Actions not in approved_action_ids are implicitly rejected."
+          }
+        }
+      },
+      "RejectExecutionRequest": {
+        "type": "object",
+        "required": [
+          "reason"
+        ],
+        "properties": {
+          "reason": {
+            "type": "string",
+            "description": "Reason for rejection"
+          }
+        }
+      },
+      "ExecuteAgentRequest": {
+        "type": "object",
+        "properties": {
+          "input": {
+            "type": "object",
+            "properties": {
+              "entity_id": {
+                "type": "string",
+                "description": "Primary entity ID for context"
+              },
+              "entity_schema": {
+                "type": "string",
+                "description": "Schema of the primary entity (e.g., \"message\", \"contact\")"
+              },
+              "workflow_id": {
+                "type": "string"
+              },
+              "workflow_execution_id": {
+                "type": "string"
+              },
+              "task_id": {
+                "type": "string"
+              },
+              "custom_data": {
+                "type": "object",
+                "additionalProperties": true
+              },
+              "flow_context": {
+                "type": "array",
+                "description": "Array of entities from the flow trigger context (e.g., the message entity when triggered by email receive)",
+                "items": {
+                  "type": "object",
+                  "properties": {
+                    "entity_id": {
+                      "type": "string"
+                    },
+                    "entity_schema": {
+                      "type": "string"
+                    }
+                  },
+                  "required": [
+                    "entity_id",
+                    "entity_schema"
+                  ]
+                }
+              }
+            }
+          },
+          "parameters": {
+            "type": "object",
+            "additionalProperties": true,
+            "description": "Runtime parameters (validated against input_parameters_schema)"
+          },
+          "execution_mode_override": {
+            "$ref": "#/components/schemas/ExecutionMode"
+          },
+          "execution_context": {
+            "$ref": "#/components/schemas/ExecutionContext"
+          },
+          "callback_url": {
+            "type": "string",
+            "format": "uri",
+            "description": "Webhook URL for async completion notification"
+          },
+          "timeout_ms": {
+            "type": "integer",
+            "default": 30000,
+            "maximum": 300000,
+            "description": "Execution timeout in milliseconds"
+          }
+        }
+      },
+      "ExecutionResponse": {
+        "type": "object",
+        "properties": {
+          "execution_id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "agent_id": {
+            "$ref": "#/components/schemas/AgentId"
+          },
+          "agent_source": {
+            "$ref": "#/components/schemas/AgentSource"
+          },
+          "agent_name": {
+            "type": "string",
+            "description": "Human-readable agent name (denormalized for display)"
+          },
+          "execution_context": {
+            "$ref": "#/components/schemas/ExecutionContext"
+          },
+          "org_id": {
+            "type": "string"
+          },
+          "status": {
+            "$ref": "#/components/schemas/ExecutionStatus"
+          },
+          "input": {
+            "type": "object"
+          },
+          "parameters": {
+            "type": "object"
+          },
+          "result": {
+            "type": "object",
+            "nullable": true,
+            "description": "Execution result (when status=completed)",
+            "properties": {
+              "response": {
+                "type": "string",
+                "description": "Text response from the agent"
+              },
+              "structured_output": {
+                "type": "object",
+                "nullable": true,
+                "description": "Parsed structured output (only for direct mode with output_schema)"
+              }
+            }
+          },
+          "error": {
+            "$ref": "#/components/schemas/ExecutionError"
+          },
+          "pending_action": {
+            "$ref": "#/components/schemas/PendingAction"
+          },
+          "metrics": {
+            "$ref": "#/components/schemas/ExecutionMetrics"
+          },
+          "started_at": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "completed_at": {
+            "type": "string",
+            "format": "date-time",
+            "nullable": true
+          },
+          "iterations": {
+            "type": "array",
+            "description": "Slim, labels-only step-progress projection of the ReAct iterations (empty for direct mode). Exposes only index, tool, status, and timestamp — raw thought, action input, and observation are intentionally excluded.",
+            "items": {
+              "$ref": "#/components/schemas/ExecutionIterationProjection"
+            }
+          }
+        }
+      },
+      "ExecutionIterationProjection": {
+        "type": "object",
+        "properties": {
+          "index": {
+            "type": "integer"
+          },
+          "tool": {
+            "type": "string",
+            "nullable": true,
+            "description": "Tool id the iteration invoked, or null for a non-tool step"
+          },
+          "status": {
+            "type": "string",
+            "enum": [
+              "running",
+              "completed"
+            ]
+          },
+          "timestamp": {
+            "type": "string",
+            "format": "date-time"
+          }
+        }
+      },
+      "ExecutionFeedback": {
+        "type": "object",
+        "required": [
+          "rating",
+          "user_id",
+          "submitted_at"
+        ],
+        "properties": {
+          "rating": {
+            "type": "string",
+            "enum": [
+              "up",
+              "down"
+            ]
+          },
+          "comment": {
+            "type": "string"
+          },
+          "user_id": {
+            "type": "string"
+          },
+          "submitted_at": {
+            "type": "string",
+            "format": "date-time"
+          }
+        }
+      },
+      "ExecutionFeedbackResponse": {
+        "type": "object",
+        "required": [
+          "feedback"
+        ],
+        "properties": {
+          "feedback": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/ExecutionFeedback"
+              }
+            ],
+            "nullable": true
+          }
+        }
+      },
+      "PutExecutionFeedbackRequest": {
+        "type": "object",
+        "required": [
+          "rating"
+        ],
+        "properties": {
+          "rating": {
+            "type": "string",
+            "enum": [
+              "up",
+              "down"
+            ]
+          },
+          "comment": {
+            "type": "string"
+          }
+        }
+      },
+      "ExecutionTrace": {
+        "type": "object",
+        "properties": {
+          "execution_id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "iterations": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/ExecutionIteration"
+            }
+          },
+          "total_iterations": {
+            "type": "integer"
+          }
+        }
+      },
+      "ExecutionIteration": {
+        "type": "object",
+        "properties": {
+          "iteration_index": {
+            "type": "integer"
+          },
+          "thought": {
+            "type": "string",
+            "description": "LLM reasoning/thinking"
+          },
+          "action": {
+            "type": "object",
+            "nullable": true,
+            "properties": {
+              "tool": {
+                "type": "string"
+              },
+              "input": {
+                "type": "object"
+              }
+            }
+          },
+          "observation": {
+            "type": "object",
+            "nullable": true,
+            "description": "Tool result"
+          },
+          "timestamp": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "tokens_used": {
+            "type": "integer"
+          },
+          "latency_ms": {
+            "type": "integer"
+          }
+        }
+      },
+      "PendingAction": {
+        "type": "object",
+        "nullable": true,
+        "description": "Action waiting for approval (when status=waiting_approval)",
+        "properties": {
+          "tool": {
+            "type": "string",
+            "description": "Tool ID that requires approval"
+          },
+          "input": {
+            "type": "object",
+            "description": "Tool input parameters"
+          },
+          "description": {
+            "type": "string",
+            "description": "Human-readable description of the action"
+          },
+          "preview": {
+            "$ref": "#/components/schemas/ToolPreview"
+          }
+        }
+      },
+      "ExecutionError": {
+        "type": "object",
+        "nullable": true,
+        "properties": {
+          "code": {
+            "type": "string",
+            "enum": [
+              "TIMEOUT",
+              "MAX_ITERATIONS_EXCEEDED",
+              "TOOL_EXECUTION_FAILED",
+              "LLM_ERROR",
+              "INVALID_OUTPUT",
+              "REJECTED",
+              "INTERNAL_ERROR"
+            ]
+          },
+          "message": {
+            "type": "string"
+          },
+          "details": {
+            "type": "object"
+          }
+        }
+      },
+      "ExecutionMetrics": {
+        "type": "object",
+        "properties": {
+          "total_tokens": {
+            "type": "integer"
+          },
+          "input_tokens": {
+            "type": "integer"
+          },
+          "output_tokens": {
+            "type": "integer"
+          },
+          "total_cost_usd": {
+            "type": "number",
+            "format": "float"
+          },
+          "duration_ms": {
+            "type": "integer"
+          },
+          "iteration_count": {
+            "type": "integer"
+          }
+        }
+      },
+      "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.",
+        "properties": {
+          "action": {
+            "type": "object",
+            "required": [
+              "type",
+              "verb"
+            ],
+            "properties": {
+              "type": {
+                "$ref": "#/components/schemas/PreviewActionType"
+              },
+              "verb": {
+                "type": "string",
+                "description": "Human-readable action verb",
+                "example": "Move Thread"
+              }
+            }
+          },
+          "source": {
+            "$ref": "#/components/schemas/PreviewEntity"
+          },
+          "target": {
+            "$ref": "#/components/schemas/PreviewEntity"
+          },
+          "changes": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/PreviewChange"
+            },
+            "description": "List of changes/modifications being made"
+          },
+          "metadata": {
+            "type": "object",
+            "additionalProperties": {
+              "$ref": "#/components/schemas/PreviewValue"
+            },
+            "description": "Additional context information"
+          },
+          "summary": {
+            "type": "string",
+            "description": "AI reasoning for why this action is recommended",
+            "example": "This email discusses solar panel installation and should be handled by the Service team."
+          }
+        }
+      },
+      "PreviewActionType": {
+        "type": "string",
+        "enum": [
+          "move",
+          "create",
+          "update",
+          "delete",
+          "apply",
+          "send",
+          "link",
+          "unlink",
+          "batch_approval"
+        ],
+        "description": "Type of action being previewed"
+      },
+      "PreviewEntity": {
+        "type": "object",
+        "description": "Entity reference for preview display",
+        "properties": {
+          "type": {
+            "type": "string",
+            "description": "Entity type (e.g., \"inbox\", \"email\", \"contact\", \"label\")",
+            "example": "inbox"
+          },
+          "id": {
+            "type": "string",
+            "description": "Entity ID"
+          },
+          "name": {
+            "type": "string",
+            "description": "Human-readable name for display",
+            "example": "Support Inbox"
+          },
+          "schema": {
+            "type": "string",
+            "description": "Entity schema (for epilot entities)"
+          },
+          "icon": {
+            "type": "string",
+            "description": "Icon hint for UI"
+          },
+          "url": {
+            "type": "string",
+            "description": "Optional URL to view the entity"
+          }
+        }
+      },
+      "PreviewChange": {
+        "type": "object",
+        "description": "A single field change in the preview",
+        "properties": {
+          "field": {
+            "type": "string",
+            "description": "Field identifier"
+          },
+          "label": {
+            "type": "string",
+            "description": "Human-readable field label"
+          },
+          "from": {
+            "$ref": "#/components/schemas/PreviewValue"
+          },
+          "to": {
+            "$ref": "#/components/schemas/PreviewValue"
+          }
+        }
+      },
+      "PreviewValue": {
+        "type": "object",
+        "description": "Typed value for preview display",
+        "required": [
+          "type"
+        ],
+        "properties": {
+          "type": {
+            "type": "string",
+            "enum": [
+              "text",
+              "number",
+              "boolean",
+              "list",
+              "entity",
+              "badge"
+            ],
+            "description": "Value type for proper rendering"
+          },
+          "value": {
+            "description": "The actual value (type depends on \"type\" field)"
+          },
+          "values": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Array of values (for list type)"
+          },
+          "id": {
+            "type": "string",
+            "description": "Entity ID (for entity type)"
+          },
+          "name": {
+            "type": "string",
+            "description": "Display name (for entity type)"
+          },
+          "schema": {
+            "type": "string",
+            "description": "Entity schema (for entity type)"
+          },
+          "color": {
+            "type": "string",
+            "enum": [
+              "success",
+              "warning",
+              "error",
+              "info"
+            ],
+            "description": "Badge color (for badge type)"
+          }
+        }
+      },
+      "ToolDefinition": {
+        "type": "object",
+        "properties": {
+          "tool_id": {
+            "type": "string",
+            "example": "entity.search"
+          },
+          "name": {
+            "type": "string",
+            "example": "Search Entities"
+          },
+          "description": {
+            "type": "string",
+            "description": "Description for LLM to understand tool purpose"
+          },
+          "category": {
+            "type": "string",
+            "enum": [
+              "entity",
+              "message",
+              "taxonomy",
+              "rag",
+              "workflow"
+            ]
+          },
+          "parameters": {
+            "type": "object",
+            "description": "JSON Schema for tool input"
+          },
+          "returns": {
+            "type": "object",
+            "description": "JSON Schema for tool output"
+          },
+          "requires_approval": {
+            "type": "boolean",
+            "default": false,
+            "description": "Whether this tool always requires human approval"
+          },
+          "enabled": {
+            "type": "boolean",
+            "default": true
+          }
+        }
+      },
+      "SkillCategory": {
+        "type": "string",
+        "enum": [
+          "message",
+          "entity",
+          "document",
+          "classification",
+          "custom"
+        ]
+      },
+      "AgentSource": {
+        "type": "string",
+        "enum": [
+          "system",
+          "custom"
+        ],
+        "description": "- system: Pre-built by epilot (system skills)\n- custom: Created by organization\n"
+      },
+      "SkillAvailability": {
+        "type": "string",
+        "enum": [
+          "flows",
+          "copilot",
+          "portals",
+          "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"
+      },
+      "ExecutionContext": {
+        "type": "string",
+        "enum": [
+          "flows",
+          "copilot",
+          "api"
+        ],
+        "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"
+      },
+      "ExecutionPattern": {
+        "type": "string",
+        "enum": [
+          "direct",
+          "react"
+        ],
+        "description": "- direct: Single LLM call, no tools\n- react: Multi-step reasoning with tool use\n"
+      },
+      "ExecutionMode": {
+        "type": "string",
+        "enum": [
+          "automatic",
+          "approval",
+          "draft"
+        ],
+        "description": "- automatic: Execute without human intervention\n- approval: Pause for human approval before tool execution\n- draft: Execute but mark output as draft for review\n"
+      },
+      "ExecutionStatus": {
+        "type": "string",
+        "enum": [
+          "pending",
+          "running",
+          "waiting_approval",
+          "completed",
+          "failed",
+          "cancelled"
+        ]
+      },
+      "ParameterType": {
+        "type": "string",
+        "enum": [
+          "text",
+          "textarea",
+          "number",
+          "boolean",
+          "select",
+          "entity-schema",
+          "entity-attribute",
+          "entity-id",
+          "taxonomy",
+          "taxonomy-classification",
+          "shared-inbox",
+          "label",
+          "matching-criteria"
+        ],
+        "description": "Base types:\n- text: Text input field\n- textarea: Multi-line text input field\n- number: Numeric input field\n- boolean: Toggle switch\n- select: Dropdown selection (requires enum array)\n\nCustom types (domain-specific):\n- entity-schema: Entity schema selector (fetches from Entity API)\n- entity-attribute: Entity attribute selector (requires dependsOn)\n- entity-id: Entity picker (search and select entities)\n- taxonomy: Taxonomy selector (fetches from Taxonomy API)\n- taxonomy-classification: Classification selector (requires dependsOn)\n- shared-inbox: Shared inbox selector (fetches from Email Settings API)\n- matching-criteria: Criteria editor for mapping compared fields between two contexts or entities\n"
+      },
+      "InputParameterDefinition": {
+        "type": "object",
+        "required": [
+          "name",
+          "label",
+          "type"
+        ],
+        "properties": {
+          "name": {
+            "type": "string",
+            "description": "Unique identifier for the parameter (used in API)",
+            "example": "target_schema"
+          },
+          "label": {
+            "type": "string",
+            "description": "Human-readable display label",
+            "example": "Target Schema"
+          },
+          "type": {
+            "$ref": "#/components/schemas/ParameterType"
+          },
+          "description": {
+            "type": "string",
+            "description": "Help text for the parameter"
+          },
+          "default": {
+            "description": "Default value for the parameter"
+          },
+          "multi": {
+            "type": "boolean",
+            "default": false,
+            "description": "Allow multiple selections (value becomes array)"
+          },
+          "dependsOn": {
+            "type": "string",
+            "description": "Parent parameter this depends on (for entity-attribute, taxonomy-classification)"
+          },
+          "visibleWhen": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "array"
+            },
+            "description": "Conditional visibility rules (show when parent has specific values)"
+          },
+          "enum": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Allowed values (required for 'select' type)"
+          },
+          "minimum": {
+            "type": "number",
+            "description": "Minimum value (for number type)"
+          },
+          "maximum": {
+            "type": "number",
+            "description": "Maximum value (for number type)"
+          },
+          "step": {
+            "type": "number",
+            "description": "Step increment (for number type)"
+          },
+          "minLength": {
+            "type": "integer",
+            "description": "Minimum length (for text type)"
+          },
+          "maxLength": {
+            "type": "integer",
+            "description": "Maximum length (for text type)"
+          },
+          "schemaFilter": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Filter to specific schemas (for entity-schema, entity-id)"
+          },
+          "attributeTypeFilter": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Filter to specific attribute types (for entity-attribute)"
+          },
+          "hidden": {
+            "type": "boolean",
+            "default": false,
+            "description": "Whether to hide the parameter from the UI"
+          }
+        }
+      },
+      "InputParametersSchema": {
+        "type": "object",
+        "required": [
+          "type",
+          "parameters"
+        ],
+        "properties": {
+          "type": {
+            "type": "string",
+            "enum": [
+              "object"
+            ],
+            "description": "Always \"object\""
+          },
+          "parameters": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/InputParameterDefinition"
+            },
+            "description": "Array of parameter definitions"
+          },
+          "required": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Array of parameter names that are required"
+          }
+        },
+        "example": {
+          "type": "object",
+          "parameters": [
+            {
+              "name": "target_schema",
+              "label": "Target Schema",
+              "type": "entity-schema",
+              "description": "Entity type to create"
+            },
+            {
+              "name": "confidence_threshold",
+              "label": "Confidence Threshold",
+              "type": "number",
+              "minimum": 0,
+              "maximum": 1,
+              "default": 0.8
+            },
+            {
+              "name": "categories",
+              "label": "Categories",
+              "type": "select",
+              "enum": [
+                "invoice",
+                "contract",
+                "letter"
+              ],
+              "multi": true
+            }
+          ],
+          "required": [
+            "target_schema"
+          ]
+        }
+      },
+      "ModelConfig": {
+        "type": "object",
+        "properties": {
+          "model_id": {
+            "type": "string",
+            "default": "anthropic.claude-3-5-sonnet-20241022-v2:0",
+            "description": "AWS Bedrock model ID"
+          },
+          "temperature": {
+            "type": "number",
+            "minimum": 0,
+            "maximum": 1,
+            "default": 0.7
+          },
+          "max_tokens": {
+            "type": "integer",
+            "default": 4096,
+            "maximum": 8192
+          },
+          "thinking": {
+            "type": "boolean",
+            "default": false,
+            "description": "Enable extended thinking/reasoning for the model"
+          },
+          "thinking_budget": {
+            "type": "integer",
+            "default": 10000,
+            "minimum": 1000,
+            "maximum": 50000,
+            "description": "Token budget for extended thinking (only used when thinking is enabled)"
+          }
+        }
+      },
+      "Error": {
+        "type": "object",
+        "properties": {
+          "error": {
+            "type": "string"
+          },
+          "message": {
+            "type": "string"
+          },
+          "details": {
+            "type": "object"
+          }
+        }
+      },
+      "ChatRequest": {
+        "type": "object",
+        "required": [
+          "agentId",
+          "message"
+        ],
+        "properties": {
+          "agentId": {
+            "type": "string",
+            "description": "Agent ID to chat with"
+          },
+          "message": {
+            "type": "string",
+            "description": "User message"
+          },
+          "conversationId": {
+            "type": "string",
+            "format": "uuid",
+            "description": "Conversation ID for server-side memory. If provided, loads history from DynamoDB."
+          },
+          "clientHistory": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/ChatMessage"
+            },
+            "description": "Client-provided message history (overrides server-side memory)"
+          },
+          "context": {
+            "type": "object",
+            "properties": {
+              "entityId": {
+                "type": "string"
+              },
+              "customData": {
+                "type": "object",
+                "additionalProperties": true
+              }
+            }
+          },
+          "streaming": {
+            "$ref": "#/components/schemas/StreamingOptions"
+          }
+        }
+      },
+      "ChatMessage": {
+        "type": "object",
+        "required": [
+          "role",
+          "content"
+        ],
+        "properties": {
+          "role": {
+            "type": "string",
+            "enum": [
+              "user",
+              "assistant",
+              "tool",
+              "system"
+            ]
+          },
+          "content": {
+            "type": "string"
+          },
+          "tool_calls": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "id": {
+                  "type": "string"
+                },
+                "name": {
+                  "type": "string"
+                },
+                "input": {
+                  "type": "object"
+                },
+                "output": {
+                  "type": "string"
+                }
+              }
+            }
+          }
+        }
+      },
+      "StreamingOptions": {
+        "type": "object",
+        "properties": {
+          "mode": {
+            "type": "string",
+            "enum": [
+              "updates",
+              "messages"
+            ],
+            "default": "updates",
+            "description": "Stream mode - updates for step-based, messages for token-based"
+          },
+          "streamTokens": {
+            "type": "boolean",
+            "default": false,
+            "description": "Enable token-level streaming"
+          },
+          "includeMetadata": {
+            "type": "boolean",
+            "default": false,
+            "description": "Include metadata events"
+          }
+        }
+      },
+      "StreamEvent": {
+        "type": "object",
+        "description": "Server-Sent Event for streaming responses",
+        "properties": {
+          "type": {
+            "type": "string",
+            "enum": [
+              "token",
+              "agent_step",
+              "tool_call",
+              "tool_result",
+              "complete",
+              "error",
+              "metadata",
+              "needs_approval"
+            ]
+          },
+          "content": {
+            "type": "string",
+            "description": "Token content (for token events)"
+          },
+          "index": {
+            "type": "integer",
+            "description": "Token index (for token events)"
+          },
+          "tool": {
+            "type": "string",
+            "description": "Tool name (for tool events)"
+          },
+          "input": {
+            "type": "object",
+            "description": "Tool input (for tool_call events)"
+          },
+          "output": {
+            "type": "string",
+            "description": "Tool output (for tool_result events)"
+          },
+          "callId": {
+            "type": "string",
+            "description": "Tool call ID"
+          },
+          "result": {
+            "$ref": "#/components/schemas/ExecutionResult"
+          },
+          "error": {
+            "type": "object",
+            "properties": {
+              "code": {
+                "type": "string"
+              },
+              "message": {
+                "type": "string"
+              }
+            }
+          },
+          "conversationId": {
+            "type": "string",
+            "format": "uuid",
+            "description": "Conversation ID (included in complete events)"
+          }
+        }
+      },
+      "ExecutionResult": {
+        "type": "object",
+        "properties": {
+          "response": {
+            "type": "string"
+          },
+          "structured_output": {
+            "type": "object"
+          },
+          "status": {
+            "type": "string",
+            "enum": [
+              "completed",
+              "failed",
+              "max_iterations",
+              "rejected"
+            ]
+          },
+          "metrics": {
+            "$ref": "#/components/schemas/ExecutionMetrics"
+          }
+        }
+      },
+      "ConversationItem": {
+        "type": "object",
+        "properties": {
+          "conversation_id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "user_id": {
+            "type": "string"
+          },
+          "agent_id": {
+            "type": "string"
+          },
+          "title": {
+            "type": "string"
+          },
+          "message_count": {
+            "type": "integer"
+          },
+          "last_message": {
+            "type": "string",
+            "description": "Preview of the last message"
+          },
+          "last_message_at": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "context": {
+            "type": "object",
+            "properties": {
+              "entityId": {
+                "type": "string"
+              },
+              "customData": {
+                "type": "object"
+              }
+            }
+          },
+          "created_at": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "updated_at": {
+            "type": "string",
+            "format": "date-time"
+          }
+        }
+      },
+      "MessageItem": {
+        "type": "object",
+        "properties": {
+          "conversation_id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "role": {
+            "type": "string",
+            "enum": [
+              "user",
+              "assistant",
+              "tool",
+              "system"
+            ]
+          },
+          "content": {
+            "type": "string"
+          },
+          "timestamp": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "tool_calls": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "id": {
+                  "type": "string"
+                },
+                "name": {
+                  "type": "string"
+                },
+                "input": {
+                  "type": "object"
+                },
+                "output": {
+                  "type": "string"
+                }
+              }
+            }
+          },
+          "token_count": {
+            "type": "integer"
+          },
+          "trace_id": {
+            "type": "string",
+            "format": "uuid",
+            "description": "Langfuse trace id for the turn (assistant messages only)"
+          },
+          "feedback": {
+            "$ref": "#/components/schemas/MessageFeedback"
+          }
+        }
+      },
+      "MessageFeedback": {
+        "type": "object",
+        "required": [
+          "rating",
+          "user_id",
+          "submitted_at"
+        ],
+        "properties": {
+          "rating": {
+            "type": "string",
+            "enum": [
+              "up",
+              "down"
+            ]
+          },
+          "comment": {
+            "type": "string"
+          },
+          "user_id": {
+            "type": "string"
+          },
+          "submitted_at": {
+            "type": "string",
+            "format": "date-time"
+          }
+        }
+      },
+      "SubmitFeedbackRequest": {
+        "type": "object",
+        "required": [
+          "trace_id",
+          "rating"
+        ],
+        "properties": {
+          "trace_id": {
+            "type": "string",
+            "format": "uuid",
+            "description": "Langfuse trace id of the assistant turn being rated"
+          },
+          "rating": {
+            "type": "string",
+            "enum": [
+              "up",
+              "down"
+            ]
+          },
+          "comment": {
+            "type": "string",
+            "description": "Optional free-text feedback"
+          }
+        }
+      },
+      "ListConversationsResponse": {
+        "type": "object",
+        "properties": {
+          "conversations": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/ConversationItem"
+            }
+          },
+          "next_cursor": {
+            "type": "string",
+            "nullable": true
+          }
+        }
+      },
+      "ConversationWithMessages": {
+        "type": "object",
+        "properties": {
+          "conversation": {
+            "$ref": "#/components/schemas/ConversationItem"
+          },
+          "messages": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/MessageItem"
+            }
+          }
+        }
+      }
+    }
+  }
+}