@epilot/cli 0.1.10 → 0.1.12

package/definitions/erp-integration.json

@@ -2,7 +2,7 @@
   "openapi": "3.0.3",
   "info": {
     "title": "ERP Integration API",
-    "version": "0.46.0",
+    "version": "0.58.0",
     "description": "API for integrating with ERP systems, handling tracking acknowledgments, triggering ERP processes, and processing ERP updates."
   },
   "tags": [
@@ -21,6 +21,14 @@
     {
       "name": "monitoring",
       "description": "Monitoring and analytics endpoints"
+    },
+    {
+      "name": "managed-call",
+      "description": "Managed call endpoints for synchronous external API calls"
+    },
+    {
+      "name": "proxy",
+      "description": "Secure proxy endpoints"
     }
   ],
   "servers": [
@@ -2248,944 +2256,2282 @@
           }
         }
       }
-    }
-  },
-  "components": {
-    "securitySchemes": {
-      "EpilotAuth": {
-        "type": "http",
-        "scheme": "bearer",
-        "description": "Authorization header with epilot OAuth2 bearer token",
-        "bearerFormat": "JWT"
-      }
     },
-    "schemas": {
-      "ErrorResponseBase": {
-        "type": "object",
-        "properties": {
-          "code": {
-            "type": "string",
-            "description": "Computer-readable error code"
-          },
-          "message": {
-            "type": "string",
-            "description": "Error message"
+    "/v2/integrations/{integrationId}/monitoring/events": {
+      "post": {
+        "operationId": "queryMonitoringEventsV2",
+        "summary": "queryMonitoringEventsV2",
+        "description": "Query monitoring events from the unified erp_monitoring_v2 table.\nReturns all event types (inbound, outbound, file_proxy, etc.) in a single list.\nReplaces the separate v1 inbound-events and outbound-events endpoints.\n",
+        "tags": [
+          "monitoring",
+          "integrations"
+        ],
+        "parameters": [
+          {
+            "name": "integrationId",
+            "in": "path",
+            "required": true,
+            "description": "The integration ID",
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
           }
-        }
-      },
-      "ErpEvent": {
-        "type": "object",
-        "required": [
-          "event_type",
-          "object_type",
-          "timestamp",
-          "format",
-          "payload"
         ],
-        "properties": {
-          "event_type": {
-            "type": "string",
-            "enum": [
-              "CREATE",
-              "UPDATE",
-              "DELETE"
-            ],
-            "description": "Type of event (create, update, delete)"
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/QueryMonitoringEventsV2Request"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "$ref": "#/components/responses/QueryMonitoringEventsV2Response"
           },
-          "object_type": {
-            "type": "string",
-            "description": "Type of the object being updated (business_partner, contract_account, etc.). Corresponds to \"Event Name\" from the integration UI."
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
           },
-          "timestamp": {
-            "type": "string",
-            "format": "date-time",
-            "description": "Timestamp when the event occurred"
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
           },
-          "format": {
-            "type": "string",
-            "enum": [
-              "json",
-              "xml"
-            ],
-            "default": "json",
-            "description": "Format of the payload data"
+          "404": {
+            "$ref": "#/components/responses/NotFound"
           },
-          "payload": {
-            "oneOf": [
-              {
-                "type": "string",
-                "minLength": 2,
-                "description": "The serialized object data payload (JSON, XML, etc.) as a string"
-              },
-              {
-                "type": "object",
-                "minProperties": 1,
-                "description": "Direct JSON object (will be automatically serialized)",
-                "additionalProperties": true
+          "500": {
+            "$ref": "#/components/responses/InternalServerError"
+          }
+        }
+      }
+    },
+    "/v2/integrations/{integrationId}/monitoring/stats": {
+      "post": {
+        "operationId": "getMonitoringStatsV2",
+        "summary": "getMonitoringStatsV2",
+        "description": "Get aggregated statistics from the unified erp_monitoring_v2 table.\nReturns combined metrics for all event types with optional breakdowns.\n",
+        "tags": [
+          "monitoring",
+          "integrations"
+        ],
+        "parameters": [
+          {
+            "name": "integrationId",
+            "in": "path",
+            "required": true,
+            "description": "The integration ID",
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/GetMonitoringStatsV2Request"
               }
-            ],
-            "description": "The object data payload - can be either a serialized string or a direct JSON object"
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "$ref": "#/components/responses/GetMonitoringStatsV2Response"
           },
-          "deduplication_id": {
-            "type": "string",
-            "pattern": "^[a-zA-Z0-9_-]+$",
-            "minLength": 1,
-            "maxLength": 255,
-            "description": "Optional unique identifier for idempotency - prevents duplicate processing of the same event within 24 hours in context of the same integration. Must contain only alphanumeric characters, hyphens, and underscores.\n",
-            "example": "evt-2025-05-01-12345-create-bp"
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          },
+          "500": {
+            "$ref": "#/components/responses/InternalServerError"
           }
         }
-      },
-      "ErpUpdatesEventsV2Request": {
-        "type": "object",
-        "required": [
-          "integration_id",
-          "events"
+      }
+    },
+    "/v2/integrations/{integrationId}/monitoring/time-series": {
+      "post": {
+        "operationId": "getMonitoringTimeSeriesV2",
+        "summary": "getMonitoringTimeSeriesV2",
+        "description": "Get time-series aggregated event counts from the unified erp_monitoring_v2 table.\nReturns bucketed counts for chart rendering.\n",
+        "tags": [
+          "monitoring",
+          "integrations"
         ],
-        "properties": {
-          "integration_id": {
-            "type": "string",
-            "format": "uuid",
-            "description": "UUID that identifies the integration configuration to use"
+        "parameters": [
+          {
+            "name": "integrationId",
+            "in": "path",
+            "required": true,
+            "description": "The integration ID",
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/GetMonitoringTimeSeriesV2Request"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "$ref": "#/components/responses/GetMonitoringTimeSeriesV2Response"
           },
-          "correlation_id": {
-            "type": "string",
-            "description": "Optional ID that identifies the specific request for debugging purposes"
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
           },
-          "events": {
-            "type": "array",
-            "description": "List of ERP events to process",
-            "items": {
-              "$ref": "#/components/schemas/ErpEvent"
-            }
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          },
+          "500": {
+            "$ref": "#/components/responses/InternalServerError"
           }
         }
-      },
-      "ErpEventV3": {
-        "type": "object",
-        "required": [
-          "timestamp",
-          "format",
-          "payload"
+      }
+    },
+    "/v2/integrations/{integrationId}/monitoring/events/{eventId}/associated": {
+      "get": {
+        "operationId": "getAssociatedMonitoringEvents",
+        "summary": "getAssociatedMonitoringEvents",
+        "description": "Returns all monitoring events sharing the same event_id, ordered chronologically.\nAlso includes the original inbound event payload from erp_incoming_events if available.\nUsed to display a full event trace/timeline.\n",
+        "tags": [
+          "monitoring",
+          "integrations"
         ],
-        "anyOf": [
+        "parameters": [
           {
-            "required": [
-              "event_name"
-            ]
+            "name": "integrationId",
+            "in": "path",
+            "required": true,
+            "description": "The integration ID",
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
           },
           {
-            "required": [
-              "use_case_slug"
-            ]
+            "name": "eventId",
+            "in": "path",
+            "required": true,
+            "description": "The event ID to get associated events for",
+            "schema": {
+              "type": "string"
+            }
           }
         ],
-        "properties": {
-          "event_name": {
-            "type": "string",
-            "description": "Event name from integration mapping (e.g., business_partner, contract_account). Required when use_case_slug is not provided.\n"
+        "responses": {
+          "200": {
+            "$ref": "#/components/responses/GetAssociatedMonitoringEventsResponse"
           },
-          "timestamp": {
-            "type": "string",
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "500": {
+            "$ref": "#/components/responses/InternalServerError"
+          }
+        }
+      }
+    },
+    "/v1/integrations/secure-proxies": {
+      "get": {
+        "operationId": "listSecureProxies",
+        "summary": "List all secure proxy use cases",
+        "description": "Lists all secure_proxy use cases across all integrations for the authenticated organization.\nReturns minimal data suitable for dropdowns and selection UIs.\n",
+        "tags": [
+          "integrations"
+        ],
+        "security": [
+          {
+            "EpilotAuth": []
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Successfully retrieved secure proxy use cases",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "required": [
+                    "secure_proxies"
+                  ],
+                  "properties": {
+                    "secure_proxies": {
+                      "type": "array",
+                      "items": {
+                        "$ref": "#/components/schemas/SecureProxySummary"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "500": {
+            "$ref": "#/components/responses/InternalServerError"
+          }
+        }
+      }
+    },
+    "/v1/secure-proxy": {
+      "post": {
+        "operationId": "secureProxy",
+        "summary": "Proxy HTTP request through secure VPC",
+        "description": "Routes an HTTP request through a VPC with either static IP egress or VPN secure link access.\nThe VPC mode is determined by the referenced secure_proxy use case configuration.\nFor secure_link mode, the target URL must match the use case's allowed_domains whitelist.\n",
+        "tags": [
+          "proxy"
+        ],
+        "security": [
+          {
+            "EpilotAuth": []
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/SecureProxyRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Proxied response from the target URL",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/SecureProxyResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "description": "Forbidden - insufficient permissions or target domain not whitelisted",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponseBase"
+                }
+              }
+            }
+          },
+          "502": {
+            "description": "Upstream error from the proxied target",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponseBase"
+                }
+              }
+            }
+          },
+          "503": {
+            "description": "VPC proxy not available for the requested mode",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponseBase"
+                }
+              }
+            }
+          },
+          "504": {
+            "description": "Upstream timeout",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponseBase"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/managed-call/{slug}/execute": {
+      "post": {
+        "operationId": "managedCallExecute",
+        "summary": "Execute a managed call operation",
+        "description": "Execute a managed call operation synchronously. The slug in the path acts as the RPC method name.\nCalls an external partner API with JSONata mapping on both request and response.\n",
+        "tags": [
+          "managed-call"
+        ],
+        "security": [
+          {
+            "EpilotAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "name": "slug",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "pattern": "^[a-z0-9][a-z0-9_-]*$"
+            },
+            "description": "Use case slug (acts as the RPC method name)"
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ManagedCallExecuteRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Managed call executed successfully.\nThe response body is the JSONata-mapped result (or raw external API response if no mapping).\nIf inbound routing is configured, check X-Inbound-Event-Id header for tracking.\n",
+            "headers": {
+              "X-Inbound-Event-Id": {
+                "description": "Event ID for tracking inbound pipeline processing (only present when inbound routing is configured)",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ManagedCallExecuteResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Bad request (e.g., invalid URL blocked by SSRF protection)",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ManagedCallErrorResponse"
+                }
+              }
+            }
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          },
+          "500": {
+            "$ref": "#/components/responses/InternalServerError"
+          },
+          "502": {
+            "description": "External API error (upstream service returned an error)",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ManagedCallErrorResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/integrations/{integrationId}/generate-types-preview": {
+      "post": {
+        "operationId": "generateTypesPreview",
+        "summary": "Preview scaffolded types for a connector integration",
+        "description": "Analyses the JSONata mappings of all managed-call use cases in the integration and returns scaffolded type descriptors. The frontend uses these to show the type editor modal where developers fill in leaf types.\n",
+        "tags": [
+          "integrations"
+        ],
+        "security": [
+          {
+            "EpilotAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "name": "integrationId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Scaffolded type preview",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GenerateTypesPreviewResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          },
+          "500": {
+            "$ref": "#/components/responses/InternalServerError"
+          }
+        }
+      }
+    },
+    "/v1/integrations/{integrationId}/generate-types": {
+      "post": {
+        "operationId": "generateTypes",
+        "summary": "Generate a TypeScript npm package for a connector integration",
+        "description": "Generates a complete TypeScript npm package with typed interfaces for all managed-call use cases. This is a stateless operation that does not persist any changes. Use the commit-types endpoint to lock configurations after review.\n",
+        "tags": [
+          "integrations"
+        ],
+        "security": [
+          {
+            "EpilotAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "name": "integrationId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/GenerateTypesRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Generated package",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GenerateTypesResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          },
+          "500": {
+            "$ref": "#/components/responses/InternalServerError"
+          }
+        }
+      }
+    },
+    "/v1/integrations/{integrationId}/commit-types": {
+      "post": {
+        "operationId": "commitTypes",
+        "summary": "Commit generated types and lock use case configurations",
+        "description": "Commits the generated types by locking use case configurations and updating version tracking. Should be called after the user reviews and downloads the generated package.\n",
+        "tags": [
+          "integrations"
+        ],
+        "security": [
+          {
+            "EpilotAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "name": "integrationId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CommitTypesRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Types committed successfully",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/CommitTypesResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          },
+          "500": {
+            "$ref": "#/components/responses/InternalServerError"
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "securitySchemes": {
+      "EpilotAuth": {
+        "type": "http",
+        "scheme": "bearer",
+        "description": "Authorization header with epilot OAuth2 bearer token",
+        "bearerFormat": "JWT"
+      }
+    },
+    "schemas": {
+      "ErrorResponseBase": {
+        "type": "object",
+        "properties": {
+          "code": {
+            "type": "string",
+            "description": "Computer-readable error code"
+          },
+          "message": {
+            "type": "string",
+            "description": "Error message"
+          }
+        }
+      },
+      "ErpEvent": {
+        "type": "object",
+        "required": [
+          "event_type",
+          "object_type",
+          "timestamp",
+          "format",
+          "payload"
+        ],
+        "properties": {
+          "event_type": {
+            "type": "string",
+            "enum": [
+              "CREATE",
+              "UPDATE",
+              "DELETE"
+            ],
+            "description": "Type of event (create, update, delete)"
+          },
+          "object_type": {
+            "type": "string",
+            "description": "Type of the object being updated (business_partner, contract_account, etc.). Corresponds to \"Event Name\" from the integration UI."
+          },
+          "timestamp": {
+            "type": "string",
+            "format": "date-time",
+            "description": "Timestamp when the event occurred"
+          },
+          "format": {
+            "type": "string",
+            "enum": [
+              "json",
+              "xml"
+            ],
+            "default": "json",
+            "description": "Format of the payload data"
+          },
+          "payload": {
+            "oneOf": [
+              {
+                "type": "string",
+                "minLength": 2,
+                "description": "The serialized object data payload (JSON, XML, etc.) as a string"
+              },
+              {
+                "type": "object",
+                "minProperties": 1,
+                "description": "Direct JSON object (will be automatically serialized)",
+                "additionalProperties": true
+              }
+            ],
+            "description": "The object data payload - can be either a serialized string or a direct JSON object"
+          },
+          "deduplication_id": {
+            "type": "string",
+            "pattern": "^[a-zA-Z0-9_-]+$",
+            "minLength": 1,
+            "maxLength": 255,
+            "description": "Optional unique identifier for idempotency - prevents duplicate processing of the same event within 24 hours in context of the same integration. Must contain only alphanumeric characters, hyphens, and underscores.\n",
+            "example": "evt-2025-05-01-12345-create-bp"
+          }
+        }
+      },
+      "ErpUpdatesEventsV2Request": {
+        "type": "object",
+        "required": [
+          "integration_id",
+          "events"
+        ],
+        "properties": {
+          "integration_id": {
+            "type": "string",
+            "format": "uuid",
+            "description": "UUID that identifies the integration configuration to use"
+          },
+          "correlation_id": {
+            "type": "string",
+            "description": "Optional ID that identifies the specific request for debugging purposes"
+          },
+          "events": {
+            "type": "array",
+            "description": "List of ERP events to process",
+            "items": {
+              "$ref": "#/components/schemas/ErpEvent"
+            }
+          }
+        }
+      },
+      "ErpEventV3": {
+        "type": "object",
+        "required": [
+          "timestamp",
+          "format",
+          "payload"
+        ],
+        "anyOf": [
+          {
+            "required": [
+              "event_name"
+            ]
+          },
+          {
+            "required": [
+              "use_case_slug"
+            ]
+          }
+        ],
+        "properties": {
+          "event_name": {
+            "type": "string",
+            "description": "Event name from integration mapping (e.g., business_partner, contract_account). Required when use_case_slug is not provided.\n",
+            "example": "business_partner"
+          },
+          "timestamp": {
+            "type": "string",
+            "format": "date-time",
+            "description": "Timestamp when the event occurred",
+            "example": "2025-05-01T08:30:00Z"
+          },
+          "format": {
+            "type": "string",
+            "enum": [
+              "json",
+              "xml"
+            ],
+            "default": "json",
+            "description": "Format of the payload data",
+            "example": "json"
+          },
+          "payload": {
+            "oneOf": [
+              {
+                "type": "string",
+                "minLength": 2,
+                "description": "The serialized object data payload (JSON, XML, etc.) as a string"
+              },
+              {
+                "type": "object",
+                "minProperties": 1,
+                "description": "Direct JSON object (will be automatically serialized)",
+                "additionalProperties": true
+              }
+            ],
+            "description": "The object data payload - can be either a serialized string or a direct JSON object",
+            "example": "{\"id\":\"BP10001\",\"name\":\"Acme Corporation\",\"type\":\"organization\",\"tax_id\":\"DE123456789\",\"status\":\"active\"}"
+          },
+          "use_case_slug": {
+            "type": "string",
+            "pattern": "^[a-z0-9][a-z0-9_-]*$",
+            "minLength": 1,
+            "maxLength": 255,
+            "description": "Recommended. Use case slug for routing this event to the correct use case configuration. If provided, takes precedence over event_name for use case lookup. Preferred over event_name-based routing as slugs are portable across environments.\n",
+            "example": "business_partner"
+          },
+          "deduplication_id": {
+            "type": "string",
+            "pattern": "^[a-zA-Z0-9_-]+$",
+            "minLength": 1,
+            "maxLength": 255,
+            "description": "Optional unique identifier for idempotency - prevents duplicate processing of the same event within 24 hours in context of the same integration. Must contain only alphanumeric characters, hyphens, and underscores.\n",
+            "example": "evt-2025-05-01-12345-bp"
+          }
+        }
+      },
+      "ErpUpdatesEventsV3Request": {
+        "type": "object",
+        "required": [
+          "integration_id",
+          "events"
+        ],
+        "properties": {
+          "integration_id": {
+            "type": "string",
+            "format": "uuid",
+            "description": "UUID that identifies the integration configuration to use"
+          },
+          "correlation_id": {
+            "type": "string",
+            "description": "Optional ID that identifies the specific request for debugging purposes"
+          },
+          "events": {
+            "type": "array",
+            "description": "List of ERP events to process",
+            "items": {
+              "$ref": "#/components/schemas/ErpEventV3"
+            }
+          }
+        }
+      },
+      "TriggerErpActionRequest": {
+        "type": "object",
+        "required": [
+          "execution_id",
+          "org_id",
+          "webhook_id",
+          "flow_id",
+          "created_at",
+          "action_id",
+          "flow_action_id",
+          "flow_name",
+          "activity_id",
+          "entity_id"
+        ],
+        "properties": {
+          "execution_id": {
+            "type": "string",
+            "description": "Unique identifier of the current automation execution"
+          },
+          "org_id": {
+            "type": "string",
+            "description": "Identifier of the organization where the automation is executed"
+          },
+          "webhook_id": {
+            "type": "string",
+            "description": "Identifier of the self-service webhook configuration"
+          },
+          "flow_id": {
+            "type": "string",
+            "description": "Identifier of the automation flow that triggered the action"
+          },
+          "created_at": {
+            "type": "string",
             "format": "date-time",
-            "description": "Timestamp when the event occurred"
+            "description": "ISO-8601 timestamp when the webhook event was created"
+          },
+          "action_id": {
+            "type": "string",
+            "description": "Identifier of the automation action being executed"
+          },
+          "flow_action_id": {
+            "type": "string",
+            "description": "Identifier of the specific automation flow action instance"
+          },
+          "flow_name": {
+            "type": "string",
+            "description": "Human readable name of the automation flow"
+          },
+          "activity_id": {
+            "type": "string",
+            "description": "Identifier of the entity activity related to this trigger"
+          },
+          "entity_id": {
+            "type": "string",
+            "description": "Identifier of the entity referenced by the activity"
+          }
+        }
+      },
+      "TriggerWebhookResp": {
+        "type": "object",
+        "properties": {
+          "status_code": {
+            "type": "string"
+          },
+          "message": {
+            "type": "string"
+          },
+          "body": {
+            "type": "object"
+          },
+          "code": {
+            "type": "string"
+          },
+          "status": {
+            "type": "string",
+            "enum": [
+              "succeeded",
+              "failed"
+            ]
+          },
+          "start_date": {
+            "type": "string"
+          },
+          "end_date": {
+            "type": "string"
+          },
+          "event_id": {
+            "type": "string"
+          }
+        }
+      },
+      "IntegrationEditableFields": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 255,
+            "description": "Integration name"
+          },
+          "description": {
+            "type": "string",
+            "maxLength": 1000,
+            "description": "Optional description of the integration"
+          },
+          "access_token_ids": {
+            "type": "array",
+            "description": "List of access token IDs associated with this integration",
+            "items": {
+              "type": "string"
+            }
+          },
+          "app_ids": {
+            "type": "array",
+            "description": "List of app IDs associated with this integration",
+            "items": {
+              "type": "string"
+            }
+          },
+          "environment_config": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/EnvironmentFieldConfig"
+            },
+            "description": "Configuration defining environment variables needed by this integration. Values are stored in the Environments API."
+          },
+          "settings": {
+            "$ref": "#/components/schemas/IntegrationSettings"
+          },
+          "integration_type": {
+            "type": "string",
+            "enum": [
+              "erp",
+              "connector"
+            ],
+            "default": "erp",
+            "description": "Type of integration. \"erp\" is the ERP integration with inbound/outbound use cases. \"connector\" is for complex proxy integrations with external APIs.\n"
+          },
+          "connector_config": {
+            "$ref": "#/components/schemas/ConnectorConfig"
+          },
+          "protected": {
+            "type": "boolean",
+            "description": "If true, integration is displayed in read-only mode in the UI to discourage changes"
+          },
+          "_manifest": {
+            "type": "array",
+            "description": "The manifest IDs associated with this integration",
+            "items": {
+              "type": "string"
+            }
+          }
+        }
+      },
+      "ConnectorConfig": {
+        "type": "object",
+        "description": "Shared configuration for connector-type integrations",
+        "properties": {
+          "base_url": {
+            "type": "string",
+            "description": "Base URL for the partner API"
+          },
+          "auth": {
+            "$ref": "#/components/schemas/ManagedCallAuth"
+          },
+          "types_versions": {
+            "type": "array",
+            "description": "History of generated type package versions",
+            "items": {
+              "type": "object",
+              "required": [
+                "version",
+                "package_name",
+                "generated_at",
+                "generated_by",
+                "status"
+              ],
+              "properties": {
+                "version": {
+                  "type": "string"
+                },
+                "package_name": {
+                  "type": "string"
+                },
+                "generated_at": {
+                  "type": "string",
+                  "format": "date-time"
+                },
+                "generated_by": {
+                  "type": "string"
+                },
+                "status": {
+                  "type": "string",
+                  "enum": [
+                    "active",
+                    "deprecated"
+                  ]
+                }
+              }
+            }
+          },
+          "latest_types_version": {
+            "type": "string",
+            "description": "Latest active types package version"
+          },
+          "latest_types_package_name": {
+            "type": "string",
+            "description": "Latest active types package name"
+          }
+        }
+      },
+      "ManagedCallAuth": {
+        "type": "object",
+        "description": "Authentication configuration for managed call requests",
+        "properties": {
+          "type": {
+            "type": "string",
+            "enum": [
+              "oauth2_client_credentials",
+              "api_key",
+              "bearer"
+            ],
+            "description": "Authentication type"
+          },
+          "token_url": {
+            "type": "string",
+            "description": "OAuth2 token URL. Can be plain text or {{env.key}} reference."
+          },
+          "client_id": {
+            "type": "string",
+            "description": "OAuth2 client ID. Can be plain text or {{env.key}} reference."
+          },
+          "client_secret": {
+            "type": "string",
+            "description": "OAuth2 client secret. Must be an {{env.key}} reference (secret)."
+          },
+          "scope": {
+            "type": "string",
+            "description": "OAuth2 scope"
+          },
+          "audience": {
+            "type": "string",
+            "description": "OAuth2 audience parameter (e.g. for Auth0, Azure AD). Can be plain text or {{env.key}} reference."
+          },
+          "resource": {
+            "type": "string",
+            "description": "OAuth2 resource parameter (e.g. for Azure AD). Can be plain text or {{env.key}} reference."
+          },
+          "body_params": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "string"
+            },
+            "description": "Additional key-value pairs for the OAuth2 token request body. Values can be {{env.key}} references."
+          },
+          "headers": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "string"
+            },
+            "description": "Additional headers for the OAuth2 token request. Values can be {{env.key}} references."
+          },
+          "query_params": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "string"
+            },
+            "description": "Additional query parameters for the OAuth2 token URL. Values can be {{env.key}} references."
+          },
+          "api_key_header": {
+            "type": "string",
+            "description": "Header name for API key auth (default X-API-Key)"
+          },
+          "api_key": {
+            "type": "string",
+            "description": "API key value. Must be an {{env.key}} reference (secret)."
+          },
+          "token": {
+            "type": "string",
+            "description": "Bearer token value. Must be an {{env.key}} reference (secret)."
+          }
+        }
+      },
+      "Integration": {
+        "allOf": [
+          {
+            "type": "object",
+            "required": [
+              "id",
+              "orgId",
+              "name",
+              "created_at",
+              "updated_at"
+            ],
+            "properties": {
+              "id": {
+                "type": "string",
+                "format": "uuid",
+                "readOnly": true,
+                "description": "Unique identifier for the integration"
+              },
+              "orgId": {
+                "type": "string",
+                "readOnly": true,
+                "description": "Organization ID"
+              },
+              "created_at": {
+                "type": "string",
+                "format": "date-time",
+                "readOnly": true,
+                "description": "ISO-8601 timestamp when the integration was created"
+              },
+              "updated_at": {
+                "type": "string",
+                "format": "date-time",
+                "readOnly": true,
+                "description": "ISO-8601 timestamp when the integration was last updated"
+              }
+            }
+          },
+          {
+            "$ref": "#/components/schemas/IntegrationEditableFields"
+          }
+        ]
+      },
+      "CreateIntegrationRequest": {
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/IntegrationEditableFields"
+          },
+          {
+            "type": "object",
+            "required": [
+              "name"
+            ]
+          }
+        ]
+      },
+      "UpdateIntegrationRequest": {
+        "$ref": "#/components/schemas/IntegrationEditableFields"
+      },
+      "EnvironmentFieldConfig": {
+        "type": "object",
+        "required": [
+          "key",
+          "label",
+          "type"
+        ],
+        "properties": {
+          "key": {
+            "type": "string",
+            "description": "Environment variable key, used to look up the value in the Environments API.",
+            "pattern": "^[a-z0-9][a-z0-9_.\\-]{0,127}$"
           },
-          "format": {
+          "label": {
+            "type": "string",
+            "description": "Display label for the field in the UI",
+            "minLength": 1,
+            "maxLength": 255
+          },
+          "type": {
             "type": "string",
             "enum": [
-              "json",
-              "xml"
+              "String",
+              "SecretString"
             ],
-            "default": "json",
-            "description": "Format of the payload data"
+            "description": "Whether the value is a plain string or an encrypted secret"
           },
-          "payload": {
-            "oneOf": [
-              {
-                "type": "string",
-                "minLength": 2,
-                "description": "The serialized object data payload (JSON, XML, etc.) as a string"
-              },
-              {
-                "type": "object",
-                "minProperties": 1,
-                "description": "Direct JSON object (will be automatically serialized)",
-                "additionalProperties": true
-              }
-            ],
-            "description": "The object data payload - can be either a serialized string or a direct JSON object"
+          "description": {
+            "type": "string",
+            "description": "Help text shown below the field",
+            "maxLength": 1000
           },
-          "use_case_slug": {
+          "required": {
+            "type": "boolean",
+            "default": false,
+            "description": "Whether this field must be filled before the integration can be used"
+          },
+          "order": {
+            "type": "integer",
+            "minimum": 0,
+            "description": "Sort order for display and drag-to-reorder"
+          }
+        }
+      },
+      "IntegrationSettings": {
+        "type": "object",
+        "description": "Settings for the integration",
+        "properties": {
+          "autoRefresh": {
+            "$ref": "#/components/schemas/AutoRefreshSettings"
+          }
+        }
+      },
+      "AutoRefreshSettings": {
+        "type": "object",
+        "description": "Auto-refresh settings for keeping integration data fresh",
+        "properties": {
+          "enabled": {
+            "type": "boolean",
+            "default": false,
+            "description": "Whether auto-refresh is enabled"
+          },
+          "freshnessThresholdMinutes": {
+            "type": "integer",
+            "minimum": 1,
+            "description": "Maximum age (in minutes) of data before it is considered stale and eligible for refresh"
+          }
+        }
+      },
+      "SetIntegrationAppMappingRequest": {
+        "type": "object",
+        "required": [
+          "app_id",
+          "component_id"
+        ],
+        "properties": {
+          "app_id": {
             "type": "string",
-            "pattern": "^[a-z0-9][a-z0-9_-]*$",
-            "minLength": 1,
-            "maxLength": 255,
-            "description": "Recommended. Use case slug for routing this event to the correct use case configuration. If provided, takes precedence over event_name for use case lookup. Preferred over event_name-based routing as slugs are portable across environments.\n"
+            "format": "uuid",
+            "description": "UUID of the integration app instance"
           },
-          "deduplication_id": {
+          "component_id": {
             "type": "string",
-            "pattern": "^[a-zA-Z0-9_-]+$",
-            "minLength": 1,
-            "maxLength": 255,
-            "description": "Optional unique identifier for idempotency - prevents duplicate processing of the same event within 24 hours in context of the same integration. Must contain only alphanumeric characters, hyphens, and underscores.\n",
-            "example": "evt-2025-05-01-12345-bp"
+            "format": "uuid",
+            "description": "UUID of the integration app component instance"
+          },
+          "overwrite": {
+            "type": "boolean",
+            "default": false,
+            "description": "If true, overwrites existing mapping. If false and mapping exists, returns 409 Conflict."
           }
         }
       },
-      "ErpUpdatesEventsV3Request": {
+      "DeleteIntegrationAppMappingRequest": {
         "type": "object",
         "required": [
-          "integration_id",
-          "events"
+          "app_id",
+          "component_id"
+        ],
+        "properties": {
+          "app_id": {
+            "type": "string",
+            "format": "uuid",
+            "description": "UUID of the integration app instance"
+          },
+          "component_id": {
+            "type": "string",
+            "format": "uuid",
+            "description": "UUID of the integration app component instance"
+          }
+        }
+      },
+      "IntegrationAppMapping": {
+        "type": "object",
+        "required": [
+          "integration_id"
         ],
         "properties": {
           "integration_id": {
             "type": "string",
             "format": "uuid",
-            "description": "UUID that identifies the integration configuration to use"
+            "description": "The integration ID this app/component is mapped to"
+          }
+        }
+      },
+      "IntegrationWithUseCases": {
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/Integration"
+          },
+          {
+            "type": "object",
+            "description": "Integration with embedded use cases for atomic CRUD operations",
+            "required": [
+              "use_cases"
+            ],
+            "properties": {
+              "use_cases": {
+                "type": "array",
+                "description": "All use cases belonging to this integration",
+                "items": {
+                  "$ref": "#/components/schemas/UseCase"
+                }
+              }
+            }
+          }
+        ]
+      },
+      "UpsertIntegrationWithUseCasesRequest": {
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/IntegrationEditableFields"
+          },
+          {
+            "type": "object",
+            "description": "Request to create or update an integration with embedded use cases (upsert).\nThis is a declarative operation - the request represents the desired state.\n",
+            "required": [
+              "name"
+            ],
+            "properties": {
+              "use_cases": {
+                "type": "array",
+                "description": "Full list of use cases (declarative). This replaces ALL existing use cases.\n- Use cases with an `id` field matching an existing use case will be updated\n- Use cases without an `id` or with a non-matching `id` will be created\n- Existing use cases not in this list will be deleted\n",
+                "items": {
+                  "$ref": "#/components/schemas/EmbeddedUseCaseRequest"
+                }
+              }
+            }
+          }
+        ]
+      },
+      "InboundIntegrationEventConfiguration": {
+        "type": "object",
+        "description": "Configuration for inbound use cases (ERP to epilot)",
+        "properties": {
+          "entities": {
+            "type": "array",
+            "description": "Array of entity configurations for this event",
+            "items": {
+              "$ref": "#/components/schemas/IntegrationEntity"
+            }
+          },
+          "meter_readings": {
+            "type": "array",
+            "description": "Array of meter reading configurations for this event",
+            "items": {
+              "$ref": "#/components/schemas/IntegrationMeterReading"
+            }
+          }
+        }
+      },
+      "OutboundIntegrationEventConfiguration": {
+        "type": "object",
+        "required": [
+          "event_catalog_event",
+          "mappings"
+        ],
+        "description": "Configuration for outbound use cases. Defines the event that triggers the flow and the webhook mappings.",
+        "properties": {
+          "event_catalog_event": {
+            "type": "string",
+            "description": "The Event Catalog event name that triggers this outbound flow",
+            "example": "contract.created"
+          },
+          "mappings": {
+            "type": "array",
+            "minItems": 1,
+            "items": {
+              "$ref": "#/components/schemas/OutboundMapping"
+            },
+            "description": "List of mappings that transform and deliver the event"
+          }
+        }
+      },
+      "IntegrationEntity": {
+        "type": "object",
+        "required": [
+          "entity_schema",
+          "unique_ids",
+          "fields"
+        ],
+        "properties": {
+          "entity_schema": {
+            "type": "string",
+            "description": "Target entity schema (e.g., 'contact', 'contract')"
+          },
+          "unique_ids": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Array of attribute names that uniquely identify this entity.\nThe _type hint for repeatable fields (e.g., email, phone) should be specified\non the corresponding field definition in the fields array.\n"
+          },
+          "jsonataExpression": {
+            "type": "string",
+            "description": "Optional JSONata expression to pre-process the event data before field mapping"
+          },
+          "enabled": {
+            "oneOf": [
+              {
+                "type": "boolean"
+              },
+              {
+                "type": "string"
+              }
+            ],
+            "description": "Controls whether this entity mapping should be processed. Can be a boolean or a JSONata expression (string) that evaluates to a boolean."
           },
-          "correlation_id": {
+          "mode": {
             "type": "string",
-            "description": "Optional ID that identifies the specific request for debugging purposes"
+            "enum": [
+              "upsert",
+              "delete",
+              "purge",
+              "upsert-prune-scope-purge",
+              "upsert-prune-scope-delete"
+            ],
+            "default": "upsert",
+            "description": "Operation mode for entity mapping:\n- 'upsert': Create or update the entity (default)\n- 'delete': Soft delete the entity (marks as deleted)\n- 'purge': Hard delete the entity (permanent removal)\n- 'upsert-prune-scope-purge': Upsert entities from array, then purge entities in scope that weren't upserted\n- 'upsert-prune-scope-delete': Upsert entities from array, then soft delete entities in scope that weren't upserted\n"
           },
-          "events": {
+          "scope": {
+            "$ref": "#/components/schemas/PruneScopeConfig"
+          },
+          "fields": {
             "type": "array",
-            "description": "List of ERP events to process",
+            "description": "Field mapping definitions",
             "items": {
-              "$ref": "#/components/schemas/ErpEventV3"
+              "$ref": "#/components/schemas/IntegrationEntityField"
             }
           }
         }
       },
-      "TriggerErpActionRequest": {
+      "IntegrationMeterReading": {
         "type": "object",
         "required": [
-          "execution_id",
-          "org_id",
-          "webhook_id",
-          "flow_id",
-          "created_at",
-          "action_id",
-          "flow_action_id",
-          "flow_name",
-          "activity_id",
-          "entity_id"
+          "meter",
+          "fields"
         ],
         "properties": {
-          "execution_id": {
+          "jsonataExpression": {
             "type": "string",
-            "description": "Unique identifier of the current automation execution"
+            "description": "Optional JSONata expression to extract meter reading items from the event data.\nIf not provided, the entire payload is used as the reading data.\nUseful when you need to extract an array of readings from a nested structure (e.g., \"$.readings\").\n"
           },
-          "org_id": {
+          "reading_matching": {
             "type": "string",
-            "description": "Identifier of the organization where the automation is executed"
+            "enum": [
+              "external_id",
+              "strict-date"
+            ],
+            "default": "external_id",
+            "description": "Strategy for matching incoming readings against existing readings.\n- 'external_id': Match readings by external_id attribute (default behavior)\n- 'strict-date': Match by meter_id + counter_id + direction + date (German timezone).\n  Useful when readings originate from ECP and are echoed back by the ERP with truncated timestamps.\n"
           },
-          "webhook_id": {
+          "mode": {
             "type": "string",
-            "description": "Identifier of the self-service webhook configuration"
+            "enum": [
+              "upsert",
+              "delete",
+              "upsert-prune-scope"
+            ],
+            "default": "upsert",
+            "description": "Operation mode for meter reading mapping:\n- 'upsert': Create or update meter readings (default)\n- 'delete': Delete the meter reading\n- 'upsert-prune-scope': Upsert readings from array, then delete all other readings for the same meter+counter that weren't upserted\n"
           },
-          "flow_id": {
-            "type": "string",
-            "description": "Identifier of the automation flow that triggered the action"
+          "scope": {
+            "$ref": "#/components/schemas/MeterReadingPruneScopeConfig"
           },
-          "created_at": {
-            "type": "string",
-            "format": "date-time",
-            "description": "ISO-8601 timestamp when the webhook event was created"
+          "meter": {
+            "$ref": "#/components/schemas/MeterUniqueIdsConfig"
           },
-          "action_id": {
-            "type": "string",
-            "description": "Identifier of the automation action being executed"
+          "meter_counter": {
+            "$ref": "#/components/schemas/MeterUniqueIdsConfig"
           },
-          "flow_action_id": {
+          "fields": {
+            "type": "array",
+            "description": "Field mapping definitions for meter reading attributes",
+            "items": {
+              "$ref": "#/components/schemas/IntegrationEntityField"
+            }
+          }
+        }
+      },
+      "PruneScopeConfig": {
+        "type": "object",
+        "description": "Scope configuration for upsert-prune-scope modes.\nDefines how to find entities that should be pruned if not in the upsert payload.\nThe scope is resolved against the original event payload (not individual array items).\n",
+        "required": [
+          "scope_mode"
+        ],
+        "properties": {
+          "scope_mode": {
             "type": "string",
-            "description": "Identifier of the specific automation flow action instance"
+            "enum": [
+              "relations",
+              "query"
+            ],
+            "description": "Scope mode for finding entities to prune:\n- 'relations': Find scope by looking at all entities related to a specific entity (both direct and reverse relations)\n- 'query': Find scope entities directly via query parameters\n"
           },
-          "flow_name": {
+          "schema": {
             "type": "string",
-            "description": "Human readable name of the automation flow"
+            "description": "For 'relations' mode: The schema of the entity to find (e.g., 'billing_account').\nNot used for 'query' mode.\n"
           },
-          "activity_id": {
-            "type": "string",
-            "description": "Identifier of the entity activity related to this trigger"
+          "unique_ids": {
+            "type": "array",
+            "description": "For 'relations' mode: How to identify the scope entity from the payload.\nNot used for 'query' mode.\n",
+            "items": {
+              "$ref": "#/components/schemas/RelationUniqueIdField"
+            }
           },
-          "entity_id": {
+          "query": {
+            "type": "array",
+            "description": "For 'query' mode: Direct query parameters to find scope entities.\nNot used for 'relations' or 'reverse-relations' modes.\n",
+            "items": {
+              "$ref": "#/components/schemas/RelationUniqueIdField"
+            }
+          }
+        }
+      },
+      "MeterReadingPruneScopeConfig": {
+        "type": "object",
+        "description": "Scope configuration for meter reading upsert-prune-scope mode.\nThe scope is all readings for the same meter + counter.\n",
+        "properties": {
+          "source": {
             "type": "string",
-            "description": "Identifier of the entity referenced by the activity"
+            "description": "Optional source filter. When set, only readings with this source\nare eligible for pruning (e.g., 'ERP' to only prune ERP-synced readings).\n"
           }
         }
       },
-      "TriggerWebhookResp": {
+      "MeterUniqueIdsConfig": {
         "type": "object",
+        "required": [
+          "unique_ids"
+        ],
         "properties": {
-          "status_code": {
-            "type": "string"
+          "unique_ids": {
+            "type": "array",
+            "minItems": 1,
+            "description": "Array of unique identifier field mappings",
+            "items": {
+              "$ref": "#/components/schemas/RelationUniqueIdField"
+            }
+          }
+        }
+      },
+      "IntegrationEntityField": {
+        "type": "object",
+        "required": [
+          "attribute"
+        ],
+        "properties": {
+          "attribute": {
+            "type": "string",
+            "description": "Target attribute name"
           },
-          "message": {
-            "type": "string"
+          "field": {
+            "type": "string",
+            "description": "Source field name or JSONPath expression (if starts with $)"
           },
-          "body": {
-            "type": "object"
+          "jsonataExpression": {
+            "type": "string",
+            "description": "JSONata expression for transformation"
           },
-          "code": {
-            "type": "string"
+          "constant": {
+            "description": "Constant value to assign (any type)"
           },
-          "status": {
-            "type": "string",
-            "enum": [
-              "succeeded",
-              "failed"
-            ]
+          "_type": {
+            "$ref": "#/components/schemas/RepeatableFieldType"
           },
-          "start_date": {
-            "type": "string"
+          "enabled": {
+            "oneOf": [
+              {
+                "type": "boolean"
+              },
+              {
+                "type": "string"
+              }
+            ],
+            "description": "Controls whether this field mapping should be processed. Can be a boolean or a JSONata expression (string) that evaluates to a boolean. Defaults to true if omitted."
           },
-          "end_date": {
-            "type": "string"
+          "relations": {
+            "$ref": "#/components/schemas/RelationConfig"
           },
-          "event_id": {
-            "type": "string"
+          "relation_refs": {
+            "$ref": "#/components/schemas/RelationRefsConfig"
+          },
+          "file_proxy_url": {
+            "$ref": "#/components/schemas/FileProxyUrlConfig"
           }
         }
       },
-      "IntegrationEditableFields": {
-        "type": "object",
-        "properties": {
-          "name": {
-            "type": "string",
-            "minLength": 1,
-            "maxLength": 255,
-            "description": "Integration name"
-          },
-          "description": {
-            "type": "string",
-            "maxLength": 1000,
-            "description": "Optional description of the integration"
+      "FileProxyUrlParam": {
+        "description": "Parameter for file proxy URL. Exactly one of field, constant, or jsonataExpression must be set.",
+        "oneOf": [
+          {
+            "type": "object",
+            "required": [
+              "field"
+            ],
+            "properties": {
+              "field": {
+                "type": "string",
+                "description": "Source field name or JSONPath expression (if starts with $)"
+              }
+            }
           },
-          "access_token_ids": {
-            "type": "array",
-            "description": "List of access token IDs associated with this integration",
-            "items": {
-              "type": "string"
+          {
+            "type": "object",
+            "required": [
+              "constant"
+            ],
+            "properties": {
+              "constant": {
+                "description": "Constant value (any type, stringified for URL)"
+              }
             }
           },
-          "app_ids": {
-            "type": "array",
-            "description": "List of app IDs associated with this integration",
-            "items": {
-              "type": "string"
+          {
+            "type": "object",
+            "required": [
+              "jsonataExpression"
+            ],
+            "properties": {
+              "jsonataExpression": {
+                "type": "string",
+                "description": "JSONata expression for transformation"
+              }
             }
-          },
-          "environment_config": {
-            "type": "array",
-            "items": {
-              "$ref": "#/components/schemas/EnvironmentFieldConfig"
-            },
-            "description": "Configuration defining environment variables needed by this integration. Values are stored in the Environments API."
-          },
-          "settings": {
-            "$ref": "#/components/schemas/IntegrationSettings"
           }
+        ]
+      },
+      "FileProxyUrlParams": {
+        "type": "object",
+        "description": "Custom query parameters. Keys become URL param names, values resolved from payload.",
+        "additionalProperties": {
+          "$ref": "#/components/schemas/FileProxyUrlParam"
         }
       },
-      "Integration": {
-        "allOf": [
+      "FileProxyUrlConfig": {
+        "description": "Auto-constructs a file proxy download URL. orgId and integrationId are injected from context. Exactly one of use_case_id or use_case_slug must be provided. Using use_case_slug is recommended as it is portable across environments.\n",
+        "oneOf": [
           {
             "type": "object",
             "required": [
-              "id",
-              "orgId",
-              "name",
-              "created_at",
-              "updated_at"
+              "use_case_slug"
             ],
             "properties": {
-              "id": {
-                "type": "string",
-                "format": "uuid",
-                "readOnly": true,
-                "description": "Unique identifier for the integration"
-              },
-              "orgId": {
-                "type": "string",
-                "readOnly": true,
-                "description": "Organization ID"
-              },
-              "created_at": {
+              "use_case_slug": {
                 "type": "string",
-                "format": "date-time",
-                "readOnly": true,
-                "description": "ISO-8601 timestamp when the integration was created"
+                "pattern": "^[a-z0-9][a-z0-9_-]*$",
+                "description": "Recommended. Slug of the file_proxy use case. Maps to useCaseSlug query parameter. Portable across environments.\n"
               },
-              "updated_at": {
-                "type": "string",
-                "format": "date-time",
-                "readOnly": true,
-                "description": "ISO-8601 timestamp when the integration was last updated"
+              "params": {
+                "$ref": "#/components/schemas/FileProxyUrlParams"
               }
             }
           },
-          {
-            "$ref": "#/components/schemas/IntegrationEditableFields"
-          }
-        ]
-      },
-      "CreateIntegrationRequest": {
-        "allOf": [
-          {
-            "$ref": "#/components/schemas/IntegrationEditableFields"
-          },
           {
             "type": "object",
             "required": [
-              "name"
-            ]
+              "use_case_id"
+            ],
+            "properties": {
+              "use_case_id": {
+                "type": "string",
+                "description": "Legacy. UUID of the file_proxy use case. Maps to useCaseId query parameter. Prefer use_case_slug for portable configuration.\n"
+              },
+              "params": {
+                "$ref": "#/components/schemas/FileProxyUrlParams"
+              }
+            }
           }
         ]
       },
-      "UpdateIntegrationRequest": {
-        "$ref": "#/components/schemas/IntegrationEditableFields"
-      },
-      "EnvironmentFieldConfig": {
-        "type": "object",
-        "required": [
-          "key",
-          "label",
-          "type"
-        ],
-        "properties": {
-          "key": {
-            "type": "string",
-            "description": "Environment variable key, used to look up the value in the Environments API.",
-            "pattern": "^[a-z0-9][a-z0-9_.\\-]{0,127}$"
-          },
-          "label": {
-            "type": "string",
-            "description": "Display label for the field in the UI",
-            "minLength": 1,
-            "maxLength": 255
+      "EmbeddedUseCaseRequest": {
+        "oneOf": [
+          {
+            "$ref": "#/components/schemas/EmbeddedInboundUseCaseRequest"
           },
-          "type": {
-            "type": "string",
-            "enum": [
-              "String",
-              "SecretString"
-            ],
-            "description": "Whether the value is a plain string or an encrypted secret"
+          {
+            "$ref": "#/components/schemas/EmbeddedOutboundUseCaseRequest"
           },
-          "description": {
-            "type": "string",
-            "description": "Help text shown below the field",
-            "maxLength": 1000
+          {
+            "$ref": "#/components/schemas/EmbeddedFileProxyUseCaseRequest"
           },
-          "required": {
-            "type": "boolean",
-            "default": false,
-            "description": "Whether this field must be filled before the integration can be used"
+          {
+            "$ref": "#/components/schemas/EmbeddedManagedCallUseCaseRequest"
           },
-          "order": {
-            "type": "integer",
-            "minimum": 0,
-            "description": "Sort order for display and drag-to-reorder"
-          }
-        }
-      },
-      "IntegrationSettings": {
-        "type": "object",
-        "description": "Settings for the integration",
-        "properties": {
-          "autoRefresh": {
-            "$ref": "#/components/schemas/AutoRefreshSettings"
+          {
+            "$ref": "#/components/schemas/EmbeddedSecureProxyUseCaseRequest"
           }
-        }
-      },
-      "AutoRefreshSettings": {
-        "type": "object",
-        "description": "Auto-refresh settings for keeping integration data fresh",
-        "properties": {
-          "enabled": {
-            "type": "boolean",
-            "default": false,
-            "description": "Whether auto-refresh is enabled"
-          },
-          "freshnessThresholdMinutes": {
-            "type": "integer",
-            "minimum": 1,
-            "description": "Maximum age (in minutes) of data before it is considered stale and eligible for refresh"
+        ],
+        "discriminator": {
+          "propertyName": "type",
+          "mapping": {
+            "inbound": "#/components/schemas/EmbeddedInboundUseCaseRequest",
+            "outbound": "#/components/schemas/EmbeddedOutboundUseCaseRequest",
+            "file_proxy": "#/components/schemas/EmbeddedFileProxyUseCaseRequest",
+            "managed_call": "#/components/schemas/EmbeddedManagedCallUseCaseRequest",
+            "secure_proxy": "#/components/schemas/EmbeddedSecureProxyUseCaseRequest"
           }
         }
       },
-      "SetIntegrationAppMappingRequest": {
+      "EmbeddedUseCaseRequestBase": {
         "type": "object",
         "required": [
-          "app_id",
-          "component_id"
+          "name",
+          "type",
+          "enabled"
         ],
         "properties": {
-          "app_id": {
+          "id": {
             "type": "string",
             "format": "uuid",
-            "description": "UUID of the integration app instance"
+            "description": "Optional use case ID for update matching.\n- If provided and matches an existing use case, that use case is updated\n- If provided but no match, a new use case with this ID is created\n- If omitted, a new use case with auto-generated ID is created\n"
           },
-          "component_id": {
+          "name": {
             "type": "string",
-            "format": "uuid",
-            "description": "UUID of the integration app component instance"
+            "minLength": 1,
+            "maxLength": 255,
+            "description": "Use case name"
           },
-          "overwrite": {
+          "slug": {
+            "type": "string",
+            "pattern": "^[a-z0-9][a-z0-9_-]*$",
+            "minLength": 1,
+            "maxLength": 255,
+            "description": "URL-safe identifier for the use case. Recommended for portable cross-environment referencing. Must be unique per integration. Immutable after creation.\n"
+          },
+          "enabled": {
             "type": "boolean",
-            "default": false,
-            "description": "If true, overwrites existing mapping. If false and mapping exists, returns 409 Conflict."
+            "description": "Whether the use case is enabled"
+          },
+          "change_description": {
+            "type": "string",
+            "maxLength": 2000,
+            "description": "Optional description of this change (like a commit message)"
           }
         }
       },
-      "DeleteIntegrationAppMappingRequest": {
-        "type": "object",
-        "required": [
-          "app_id",
-          "component_id"
-        ],
-        "properties": {
-          "app_id": {
-            "type": "string",
-            "format": "uuid",
-            "description": "UUID of the integration app instance"
+      "EmbeddedInboundUseCaseRequest": {
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/EmbeddedUseCaseRequestBase"
           },
-          "component_id": {
-            "type": "string",
-            "format": "uuid",
-            "description": "UUID of the integration app component instance"
+          {
+            "type": "object",
+            "required": [
+              "type"
+            ],
+            "properties": {
+              "type": {
+                "type": "string",
+                "enum": [
+                  "inbound"
+                ],
+                "description": "Use case type"
+              },
+              "configuration": {
+                "$ref": "#/components/schemas/InboundIntegrationEventConfiguration"
+              }
+            }
           }
-        }
+        ]
       },
-      "IntegrationAppMapping": {
-        "type": "object",
-        "required": [
-          "integration_id"
-        ],
-        "properties": {
-          "integration_id": {
-            "type": "string",
-            "format": "uuid",
-            "description": "The integration ID this app/component is mapped to"
+      "EmbeddedOutboundUseCaseRequest": {
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/EmbeddedUseCaseRequestBase"
+          },
+          {
+            "type": "object",
+            "required": [
+              "type"
+            ],
+            "properties": {
+              "type": {
+                "type": "string",
+                "enum": [
+                  "outbound"
+                ],
+                "description": "Use case type"
+              },
+              "configuration": {
+                "$ref": "#/components/schemas/OutboundIntegrationEventConfiguration"
+              }
+            }
           }
-        }
+        ]
       },
-      "IntegrationWithUseCases": {
+      "EmbeddedFileProxyUseCaseRequest": {
         "allOf": [
           {
-            "$ref": "#/components/schemas/Integration"
+            "$ref": "#/components/schemas/EmbeddedUseCaseRequestBase"
           },
           {
             "type": "object",
-            "description": "Integration with embedded use cases for atomic CRUD operations",
             "required": [
-              "use_cases"
+              "type"
             ],
             "properties": {
-              "use_cases": {
-                "type": "array",
-                "description": "All use cases belonging to this integration",
-                "items": {
-                  "$ref": "#/components/schemas/UseCase"
-                }
+              "type": {
+                "type": "string",
+                "enum": [
+                  "file_proxy"
+                ],
+                "description": "Use case type"
+              },
+              "configuration": {
+                "$ref": "#/components/schemas/FileProxyUseCaseConfiguration"
               }
             }
           }
         ]
       },
-      "UpsertIntegrationWithUseCasesRequest": {
+      "EmbeddedManagedCallUseCaseRequest": {
         "allOf": [
           {
-            "$ref": "#/components/schemas/IntegrationEditableFields"
+            "$ref": "#/components/schemas/EmbeddedUseCaseRequestBase"
           },
           {
             "type": "object",
-            "description": "Request to create or update an integration with embedded use cases (upsert).\nThis is a declarative operation - the request represents the desired state.\n",
             "required": [
-              "name"
+              "type"
             ],
             "properties": {
-              "use_cases": {
-                "type": "array",
-                "description": "Full list of use cases (declarative). This replaces ALL existing use cases.\n- Use cases with an `id` field matching an existing use case will be updated\n- Use cases without an `id` or with a non-matching `id` will be created\n- Existing use cases not in this list will be deleted\n",
-                "items": {
-                  "$ref": "#/components/schemas/EmbeddedUseCaseRequest"
-                }
+              "type": {
+                "type": "string",
+                "enum": [
+                  "managed_call"
+                ],
+                "description": "Use case type for managed API calls"
+              },
+              "configuration": {
+                "$ref": "#/components/schemas/ManagedCallOperationConfig"
               }
             }
           }
         ]
       },
-      "InboundIntegrationEventConfiguration": {
-        "type": "object",
-        "description": "Configuration for inbound use cases (ERP to epilot)",
-        "properties": {
-          "entities": {
-            "type": "array",
-            "description": "Array of entity configurations for this event",
-            "items": {
-              "$ref": "#/components/schemas/IntegrationEntity"
-            }
+      "EmbeddedSecureProxyUseCaseRequest": {
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/EmbeddedUseCaseRequestBase"
           },
-          "meter_readings": {
-            "type": "array",
-            "description": "Array of meter reading configurations for this event",
-            "items": {
-              "$ref": "#/components/schemas/IntegrationMeterReading"
+          {
+            "type": "object",
+            "required": [
+              "type"
+            ],
+            "properties": {
+              "type": {
+                "type": "string",
+                "enum": [
+                  "secure_proxy"
+                ],
+                "description": "Use case type"
+              },
+              "configuration": {
+                "$ref": "#/components/schemas/SecureProxyUseCaseConfiguration"
+              }
             }
           }
-        }
+        ]
       },
-      "OutboundIntegrationEventConfiguration": {
+      "UseCaseBase": {
         "type": "object",
         "required": [
-          "event_catalog_event",
-          "mappings"
+          "id",
+          "integrationId",
+          "name",
+          "type",
+          "enabled",
+          "created_at",
+          "updated_at"
         ],
-        "description": "Configuration for outbound use cases. Defines the event that triggers the flow and the webhook mappings.",
         "properties": {
-          "event_catalog_event": {
+          "id": {
             "type": "string",
-            "description": "The Event Catalog event name that triggers this outbound flow",
-            "example": "contract.created"
+            "format": "uuid",
+            "description": "Unique identifier for the use case"
           },
-          "mappings": {
-            "type": "array",
-            "minItems": 1,
-            "items": {
-              "$ref": "#/components/schemas/OutboundMapping"
-            },
-            "description": "List of mappings that transform and deliver the event"
-          }
-        }
-      },
-      "IntegrationEntity": {
-        "type": "object",
-        "required": [
-          "entity_schema",
-          "unique_ids",
-          "fields"
-        ],
-        "properties": {
-          "entity_schema": {
+          "integrationId": {
             "type": "string",
-            "description": "Target entity schema (e.g., 'contact', 'contract')"
+            "format": "uuid",
+            "description": "Parent integration ID"
           },
-          "unique_ids": {
-            "type": "array",
-            "items": {
-              "type": "string"
-            },
-            "description": "Array of attribute names that uniquely identify this entity.\nThe _type hint for repeatable fields (e.g., email, phone) should be specified\non the corresponding field definition in the fields array.\n"
+          "name": {
+            "type": "string",
+            "description": "Use case name"
           },
-          "jsonataExpression": {
+          "slug": {
             "type": "string",
-            "description": "Optional JSONata expression to pre-process the event data before field mapping"
+            "pattern": "^[a-z0-9][a-z0-9_-]*$",
+            "minLength": 1,
+            "maxLength": 255,
+            "description": "URL-safe identifier for the use case. Recommended for portable cross-environment referencing. Unique per integration. Immutable after creation. Lowercase alphanumeric, hyphens, and underscores only.\n"
           },
-          "enabled": {
-            "oneOf": [
-              {
-                "type": "boolean"
-              },
-              {
-                "type": "string"
-              }
+          "type": {
+            "type": "string",
+            "enum": [
+              "inbound",
+              "outbound",
+              "file_proxy",
+              "managed_call",
+              "secure_proxy"
             ],
-            "description": "Controls whether this entity mapping should be processed. Can be a boolean or a JSONata expression (string) that evaluates to a boolean."
+            "description": "Use case type"
           },
-          "mode": {
+          "enabled": {
+            "type": "boolean"
+          },
+          "change_description": {
             "type": "string",
-            "enum": [
-              "upsert",
-              "delete",
-              "purge",
-              "upsert-prune-scope-purge",
-              "upsert-prune-scope-delete"
+            "maxLength": 2000,
+            "description": "Description of the last change made to this use case"
+          },
+          "created_at": {
+            "type": "string",
+            "format": "date-time",
+            "description": "ISO-8601 timestamp when the use case was created"
+          },
+          "updated_at": {
+            "type": "string",
+            "format": "date-time",
+            "description": "ISO-8601 timestamp when the use case was last updated"
+          }
+        }
+      },
+      "InboundUseCase": {
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/UseCaseBase"
+          },
+          {
+            "type": "object",
+            "required": [
+              "type"
             ],
-            "default": "upsert",
-            "description": "Operation mode for entity mapping:\n- 'upsert': Create or update the entity (default)\n- 'delete': Soft delete the entity (marks as deleted)\n- 'purge': Hard delete the entity (permanent removal)\n- 'upsert-prune-scope-purge': Upsert entities from array, then purge entities in scope that weren't upserted\n- 'upsert-prune-scope-delete': Upsert entities from array, then soft delete entities in scope that weren't upserted\n"
+            "properties": {
+              "type": {
+                "type": "string",
+                "enum": [
+                  "inbound"
+                ],
+                "description": "Use case type"
+              },
+              "configuration": {
+                "$ref": "#/components/schemas/InboundIntegrationEventConfiguration"
+              }
+            }
+          }
+        ]
+      },
+      "OutboundUseCase": {
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/UseCaseBase"
           },
-          "scope": {
-            "$ref": "#/components/schemas/PruneScopeConfig"
+          {
+            "type": "object",
+            "required": [
+              "type"
+            ],
+            "properties": {
+              "type": {
+                "type": "string",
+                "enum": [
+                  "outbound"
+                ],
+                "description": "Use case type"
+              },
+              "configuration": {
+                "$ref": "#/components/schemas/OutboundIntegrationEventConfiguration"
+              }
+            }
+          }
+        ]
+      },
+      "FileProxyUseCase": {
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/UseCaseBase"
           },
-          "fields": {
-            "type": "array",
-            "description": "Field mapping definitions",
-            "items": {
-              "$ref": "#/components/schemas/IntegrationEntityField"
+          {
+            "type": "object",
+            "required": [
+              "type"
+            ],
+            "properties": {
+              "type": {
+                "type": "string",
+                "enum": [
+                  "file_proxy"
+                ],
+                "description": "Use case type"
+              },
+              "configuration": {
+                "$ref": "#/components/schemas/FileProxyUseCaseConfiguration"
+              }
             }
           }
-        }
+        ]
       },
-      "IntegrationMeterReading": {
-        "type": "object",
-        "required": [
-          "meter",
-          "fields"
-        ],
-        "properties": {
-          "jsonataExpression": {
-            "type": "string",
-            "description": "Optional JSONata expression to extract meter reading items from the event data.\nIf not provided, the entire payload is used as the reading data.\nUseful when you need to extract an array of readings from a nested structure (e.g., \"$.readings\").\n"
+      "ManagedCallUseCase": {
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/UseCaseBase"
           },
-          "reading_matching": {
-            "type": "string",
-            "enum": [
-              "external_id",
-              "strict-date"
+          {
+            "type": "object",
+            "required": [
+              "type"
             ],
-            "default": "external_id",
-            "description": "Strategy for matching incoming readings against existing readings.\n- 'external_id': Match readings by external_id attribute (default behavior)\n- 'strict-date': Match by meter_id + counter_id + direction + date (German timezone).\n  Useful when readings originate from ECP and are echoed back by the ERP with truncated timestamps.\n"
+            "properties": {
+              "type": {
+                "type": "string",
+                "enum": [
+                  "managed_call"
+                ],
+                "description": "Use case type for managed API calls"
+              },
+              "configuration": {
+                "$ref": "#/components/schemas/ManagedCallOperationConfig"
+              },
+              "type_annotations": {
+                "$ref": "#/components/schemas/TypeAnnotations"
+              },
+              "types_locked": {
+                "type": "boolean",
+                "description": "Whether types have been generated for this use case"
+              }
+            }
+          }
+        ]
+      },
+      "SecureProxyUseCase": {
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/UseCaseBase"
           },
-          "mode": {
-            "type": "string",
-            "enum": [
-              "upsert",
-              "delete",
-              "upsert-prune-scope"
+          {
+            "type": "object",
+            "required": [
+              "type"
             ],
-            "default": "upsert",
-            "description": "Operation mode for meter reading mapping:\n- 'upsert': Create or update meter readings (default)\n- 'delete': Delete the meter reading\n- 'upsert-prune-scope': Upsert readings from array, then delete all other readings for the same meter+counter that weren't upserted\n"
+            "properties": {
+              "type": {
+                "type": "string",
+                "enum": [
+                  "secure_proxy"
+                ],
+                "description": "Use case type"
+              },
+              "configuration": {
+                "$ref": "#/components/schemas/SecureProxyUseCaseConfiguration"
+              }
+            }
+          }
+        ]
+      },
+      "UseCase": {
+        "oneOf": [
+          {
+            "$ref": "#/components/schemas/InboundUseCase"
           },
-          "scope": {
-            "$ref": "#/components/schemas/MeterReadingPruneScopeConfig"
+          {
+            "$ref": "#/components/schemas/OutboundUseCase"
           },
-          "meter": {
-            "$ref": "#/components/schemas/MeterUniqueIdsConfig"
+          {
+            "$ref": "#/components/schemas/FileProxyUseCase"
           },
-          "meter_counter": {
-            "$ref": "#/components/schemas/MeterUniqueIdsConfig"
+          {
+            "$ref": "#/components/schemas/ManagedCallUseCase"
           },
-          "fields": {
-            "type": "array",
-            "description": "Field mapping definitions for meter reading attributes",
-            "items": {
-              "$ref": "#/components/schemas/IntegrationEntityField"
-            }
+          {
+            "$ref": "#/components/schemas/SecureProxyUseCase"
+          }
+        ],
+        "discriminator": {
+          "propertyName": "type",
+          "mapping": {
+            "inbound": "#/components/schemas/InboundUseCase",
+            "outbound": "#/components/schemas/OutboundUseCase",
+            "file_proxy": "#/components/schemas/FileProxyUseCase",
+            "managed_call": "#/components/schemas/ManagedCallUseCase",
+            "secure_proxy": "#/components/schemas/SecureProxyUseCase"
           }
         }
       },
-      "PruneScopeConfig": {
-        "type": "object",
-        "description": "Scope configuration for upsert-prune-scope modes.\nDefines how to find entities that should be pruned if not in the upsert payload.\nThe scope is resolved against the original event payload (not individual array items).\n",
-        "required": [
-          "scope_mode"
-        ],
-        "properties": {
-          "scope_mode": {
-            "type": "string",
-            "enum": [
-              "relations",
-              "query"
-            ],
-            "description": "Scope mode for finding entities to prune:\n- 'relations': Find scope by looking at all entities related to a specific entity (both direct and reverse relations)\n- 'query': Find scope entities directly via query parameters\n"
+      "CreateUseCaseRequest": {
+        "oneOf": [
+          {
+            "$ref": "#/components/schemas/CreateInboundUseCaseRequest"
           },
-          "schema": {
-            "type": "string",
-            "description": "For 'relations' mode: The schema of the entity to find (e.g., 'billing_account').\nNot used for 'query' mode.\n"
+          {
+            "$ref": "#/components/schemas/CreateOutboundUseCaseRequest"
           },
-          "unique_ids": {
-            "type": "array",
-            "description": "For 'relations' mode: How to identify the scope entity from the payload.\nNot used for 'query' mode.\n",
-            "items": {
-              "$ref": "#/components/schemas/RelationUniqueIdField"
-            }
+          {
+            "$ref": "#/components/schemas/CreateFileProxyUseCaseRequest"
           },
-          "query": {
-            "type": "array",
-            "description": "For 'query' mode: Direct query parameters to find scope entities.\nNot used for 'relations' or 'reverse-relations' modes.\n",
-            "items": {
-              "$ref": "#/components/schemas/RelationUniqueIdField"
-            }
-          }
-        }
-      },
-      "MeterReadingPruneScopeConfig": {
-        "type": "object",
-        "description": "Scope configuration for meter reading upsert-prune-scope mode.\nThe scope is all readings for the same meter + counter.\n",
-        "properties": {
-          "source": {
-            "type": "string",
-            "description": "Optional source filter. When set, only readings with this source\nare eligible for pruning (e.g., 'ERP' to only prune ERP-synced readings).\n"
+          {
+            "$ref": "#/components/schemas/CreateManagedCallUseCaseRequest"
+          },
+          {
+            "$ref": "#/components/schemas/CreateSecureProxyUseCaseRequest"
           }
-        }
-      },
-      "MeterUniqueIdsConfig": {
-        "type": "object",
-        "required": [
-          "unique_ids"
         ],
-        "properties": {
-          "unique_ids": {
-            "type": "array",
-            "minItems": 1,
-            "description": "Array of unique identifier field mappings",
-            "items": {
-              "$ref": "#/components/schemas/RelationUniqueIdField"
-            }
+        "discriminator": {
+          "propertyName": "type",
+          "mapping": {
+            "inbound": "#/components/schemas/CreateInboundUseCaseRequest",
+            "outbound": "#/components/schemas/CreateOutboundUseCaseRequest",
+            "file_proxy": "#/components/schemas/CreateFileProxyUseCaseRequest",
+            "managed_call": "#/components/schemas/CreateManagedCallUseCaseRequest",
+            "secure_proxy": "#/components/schemas/CreateSecureProxyUseCaseRequest"
           }
         }
       },
-      "IntegrationEntityField": {
+      "CreateUseCaseRequestBase": {
         "type": "object",
         "required": [
-          "attribute"
+          "name",
+          "type",
+          "enabled"
         ],
         "properties": {
-          "attribute": {
-            "type": "string",
-            "description": "Target attribute name"
-          },
-          "field": {
+          "name": {
             "type": "string",
-            "description": "Source field name or JSONPath expression (if starts with $)"
+            "minLength": 1,
+            "maxLength": 255,
+            "description": "Use case name"
           },
-          "jsonataExpression": {
+          "slug": {
             "type": "string",
-            "description": "JSONata expression for transformation"
-          },
-          "constant": {
-            "description": "Constant value to assign (any type)"
-          },
-          "_type": {
-            "$ref": "#/components/schemas/RepeatableFieldType"
+            "pattern": "^[a-z0-9][a-z0-9_-]*$",
+            "minLength": 1,
+            "maxLength": 255,
+            "description": "URL-safe identifier for the use case. Recommended for portable cross-environment referencing. Must be unique per integration. Immutable after creation. Lowercase alphanumeric, hyphens, and underscores only.\n"
           },
           "enabled": {
-            "oneOf": [
-              {
-                "type": "boolean"
+            "type": "boolean",
+            "description": "Whether the use case is enabled"
+          }
+        }
+      },
+      "CreateInboundUseCaseRequest": {
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/CreateUseCaseRequestBase"
+          },
+          {
+            "type": "object",
+            "required": [
+              "type"
+            ],
+            "properties": {
+              "type": {
+                "type": "string",
+                "enum": [
+                  "inbound"
+                ],
+                "description": "Use case type"
               },
-              {
-                "type": "string"
+              "configuration": {
+                "$ref": "#/components/schemas/InboundIntegrationEventConfiguration"
               }
-            ],
-            "description": "Controls whether this field mapping should be processed. Can be a boolean or a JSONata expression (string) that evaluates to a boolean. Defaults to true if omitted."
-          },
-          "relations": {
-            "$ref": "#/components/schemas/RelationConfig"
-          },
-          "relation_refs": {
-            "$ref": "#/components/schemas/RelationRefsConfig"
-          },
-          "file_proxy_url": {
-            "$ref": "#/components/schemas/FileProxyUrlConfig"
+            }
           }
-        }
+        ]
       },
-      "FileProxyUrlParam": {
-        "description": "Parameter for file proxy URL. Exactly one of field, constant, or jsonataExpression must be set.",
-        "oneOf": [
+      "CreateOutboundUseCaseRequest": {
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/CreateUseCaseRequestBase"
+          },
           {
             "type": "object",
             "required": [
-              "field"
+              "type"
             ],
             "properties": {
-              "field": {
+              "type": {
                 "type": "string",
-                "description": "Source field name or JSONPath expression (if starts with $)"
+                "enum": [
+                  "outbound"
+                ],
+                "description": "Use case type"
+              },
+              "configuration": {
+                "$ref": "#/components/schemas/OutboundIntegrationEventConfiguration"
               }
             }
-          },
+          }
+        ]
+      },
+      "CreateFileProxyUseCaseRequest": {
+        "allOf": [
           {
-            "type": "object",
-            "required": [
-              "constant"
-            ],
-            "properties": {
-              "constant": {
-                "description": "Constant value (any type, stringified for URL)"
-              }
-            }
+            "$ref": "#/components/schemas/CreateUseCaseRequestBase"
           },
           {
             "type": "object",
             "required": [
-              "jsonataExpression"
+              "type"
             ],
             "properties": {
-              "jsonataExpression": {
+              "type": {
                 "type": "string",
-                "description": "JSONata expression for transformation"
+                "enum": [
+                  "file_proxy"
+                ],
+                "description": "Use case type"
+              },
+              "configuration": {
+                "$ref": "#/components/schemas/FileProxyUseCaseConfiguration"
               }
             }
           }
         ]
       },
-      "FileProxyUrlParams": {
-        "type": "object",
-        "description": "Custom query parameters. Keys become URL param names, values resolved from payload.",
-        "additionalProperties": {
-          "$ref": "#/components/schemas/FileProxyUrlParam"
-        }
-      },
-      "FileProxyUrlConfig": {
-        "description": "Auto-constructs a file proxy download URL. orgId and integrationId are injected from context. Exactly one of use_case_id or use_case_slug must be provided. Using use_case_slug is recommended as it is portable across environments.\n",
-        "oneOf": [
+      "CreateManagedCallUseCaseRequest": {
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/CreateUseCaseRequestBase"
+          },
           {
             "type": "object",
             "required": [
-              "use_case_slug"
+              "type"
             ],
             "properties": {
-              "use_case_slug": {
+              "type": {
                 "type": "string",
-                "pattern": "^[a-z0-9][a-z0-9_-]*$",
-                "description": "Recommended. Slug of the file_proxy use case. Maps to useCaseSlug query parameter. Portable across environments.\n"
+                "enum": [
+                  "managed_call"
+                ],
+                "description": "Use case type for managed API calls"
               },
-              "params": {
-                "$ref": "#/components/schemas/FileProxyUrlParams"
+              "configuration": {
+                "$ref": "#/components/schemas/ManagedCallOperationConfig"
               }
             }
+          }
+        ]
+      },
+      "CreateSecureProxyUseCaseRequest": {
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/CreateUseCaseRequestBase"
           },
           {
             "type": "object",
             "required": [
-              "use_case_id"
+              "type"
             ],
             "properties": {
-              "use_case_id": {
+              "type": {
                 "type": "string",
-                "description": "Legacy. UUID of the file_proxy use case. Maps to useCaseId query parameter. Prefer use_case_slug for portable configuration.\n"
+                "enum": [
+                  "secure_proxy"
+                ],
+                "description": "Use case type"
               },
-              "params": {
-                "$ref": "#/components/schemas/FileProxyUrlParams"
+              "configuration": {
+                "$ref": "#/components/schemas/SecureProxyUseCaseConfiguration"
               }
             }
           }
         ]
       },
-      "EmbeddedUseCaseRequest": {
+      "UpdateUseCaseRequest": {
         "oneOf": [
           {
-            "$ref": "#/components/schemas/EmbeddedInboundUseCaseRequest"
+            "$ref": "#/components/schemas/UpdateInboundUseCaseRequest"
           },
           {
-            "$ref": "#/components/schemas/EmbeddedOutboundUseCaseRequest"
+            "$ref": "#/components/schemas/UpdateOutboundUseCaseRequest"
+          },
+          {
+            "$ref": "#/components/schemas/UpdateFileProxyUseCaseRequest"
+          },
+          {
+            "$ref": "#/components/schemas/UpdateManagedCallUseCaseRequest"
+          },
+          {
+            "$ref": "#/components/schemas/UpdateSecureProxyUseCaseRequest"
           }
         ],
         "discriminator": {
           "propertyName": "type",
           "mapping": {
-            "inbound": "#/components/schemas/EmbeddedInboundUseCaseRequest",
-            "outbound": "#/components/schemas/EmbeddedOutboundUseCaseRequest"
+            "inbound": "#/components/schemas/UpdateInboundUseCaseRequest",
+            "outbound": "#/components/schemas/UpdateOutboundUseCaseRequest",
+            "file_proxy": "#/components/schemas/UpdateFileProxyUseCaseRequest",
+            "managed_call": "#/components/schemas/UpdateManagedCallUseCaseRequest",
+            "secure_proxy": "#/components/schemas/UpdateSecureProxyUseCaseRequest"
           }
         }
       },
-      "EmbeddedUseCaseRequestBase": {
+      "UpdateUseCaseRequestBase": {
         "type": "object",
-        "required": [
-          "name",
-          "type",
-          "enabled"
-        ],
         "properties": {
-          "id": {
-            "type": "string",
-            "format": "uuid",
-            "description": "Optional use case ID for update matching.\n- If provided and matches an existing use case, that use case is updated\n- If provided but no match, a new use case with this ID is created\n- If omitted, a new use case with auto-generated ID is created\n"
-          },
           "name": {
             "type": "string",
             "minLength": 1,
@@ -3197,7 +4543,7 @@
             "pattern": "^[a-z0-9][a-z0-9_-]*$",
             "minLength": 1,
             "maxLength": 255,
-            "description": "URL-safe identifier for the use case. Recommended for portable cross-environment referencing. Must be unique per integration. Immutable after creation.\n"
+            "description": "URL-safe identifier for the use case. Recommended for portable cross-environment referencing. Can only be set once on use cases that don't have a slug yet. Immutable after being set.\n"
           },
           "enabled": {
             "type": "boolean",
@@ -3210,16 +4556,13 @@
           }
         }
       },
-      "EmbeddedInboundUseCaseRequest": {
+      "UpdateInboundUseCaseRequest": {
         "allOf": [
           {
-            "$ref": "#/components/schemas/EmbeddedUseCaseRequestBase"
+            "$ref": "#/components/schemas/UpdateUseCaseRequestBase"
           },
           {
             "type": "object",
-            "required": [
-              "type"
-            ],
             "properties": {
               "type": {
                 "type": "string",
@@ -3235,16 +4578,13 @@
           }
         ]
       },
-      "EmbeddedOutboundUseCaseRequest": {
+      "UpdateOutboundUseCaseRequest": {
         "allOf": [
           {
-            "$ref": "#/components/schemas/EmbeddedUseCaseRequestBase"
+            "$ref": "#/components/schemas/UpdateUseCaseRequestBase"
           },
           {
             "type": "object",
-            "required": [
-              "type"
-            ],
             "properties": {
               "type": {
                 "type": "string",
@@ -3260,216 +4600,170 @@
           }
         ]
       },
-      "UseCaseBase": {
-        "type": "object",
-        "required": [
-          "id",
-          "integrationId",
-          "name",
-          "type",
-          "enabled",
-          "created_at",
-          "updated_at"
-        ],
-        "properties": {
-          "id": {
-            "type": "string",
-            "format": "uuid",
-            "description": "Unique identifier for the use case"
-          },
-          "integrationId": {
-            "type": "string",
-            "format": "uuid",
-            "description": "Parent integration ID"
-          },
-          "name": {
-            "type": "string",
-            "description": "Use case name"
-          },
-          "slug": {
-            "type": "string",
-            "pattern": "^[a-z0-9][a-z0-9_-]*$",
-            "minLength": 1,
-            "maxLength": 255,
-            "description": "URL-safe identifier for the use case. Recommended for portable cross-environment referencing. Unique per integration. Immutable after creation. Lowercase alphanumeric, hyphens, and underscores only.\n"
-          },
-          "type": {
-            "type": "string",
-            "enum": [
-              "inbound",
-              "outbound",
-              "file_proxy"
-            ],
-            "description": "Use case type"
-          },
-          "enabled": {
-            "type": "boolean"
-          },
-          "change_description": {
-            "type": "string",
-            "maxLength": 2000,
-            "description": "Description of the last change made to this use case"
-          },
-          "created_at": {
-            "type": "string",
-            "format": "date-time",
-            "description": "ISO-8601 timestamp when the use case was created"
-          },
-          "updated_at": {
-            "type": "string",
-            "format": "date-time",
-            "description": "ISO-8601 timestamp when the use case was last updated"
-          }
-        }
-      },
-      "InboundUseCase": {
+      "UpdateFileProxyUseCaseRequest": {
         "allOf": [
           {
-            "$ref": "#/components/schemas/UseCaseBase"
+            "$ref": "#/components/schemas/UpdateUseCaseRequestBase"
           },
           {
             "type": "object",
-            "required": [
-              "type"
-            ],
             "properties": {
               "type": {
                 "type": "string",
                 "enum": [
-                  "inbound"
+                  "file_proxy"
                 ],
                 "description": "Use case type"
               },
               "configuration": {
-                "$ref": "#/components/schemas/InboundIntegrationEventConfiguration"
+                "$ref": "#/components/schemas/FileProxyUseCaseConfiguration"
               }
             }
           }
         ]
       },
-      "OutboundUseCase": {
+      "UpdateManagedCallUseCaseRequest": {
         "allOf": [
           {
-            "$ref": "#/components/schemas/UseCaseBase"
+            "$ref": "#/components/schemas/UpdateUseCaseRequestBase"
           },
           {
             "type": "object",
-            "required": [
-              "type"
-            ],
             "properties": {
               "type": {
                 "type": "string",
                 "enum": [
-                  "outbound"
+                  "managed_call"
                 ],
-                "description": "Use case type"
+                "description": "Use case type for managed API calls"
               },
               "configuration": {
-                "$ref": "#/components/schemas/OutboundIntegrationEventConfiguration"
+                "$ref": "#/components/schemas/ManagedCallOperationConfig"
+              },
+              "type_annotations": {
+                "$ref": "#/components/schemas/TypeAnnotations"
               }
             }
           }
         ]
       },
-      "FileProxyUseCase": {
+      "UpdateSecureProxyUseCaseRequest": {
         "allOf": [
           {
-            "$ref": "#/components/schemas/UseCaseBase"
+            "$ref": "#/components/schemas/UpdateUseCaseRequestBase"
           },
           {
             "type": "object",
-            "required": [
-              "type"
-            ],
             "properties": {
               "type": {
                 "type": "string",
                 "enum": [
-                  "file_proxy"
+                  "secure_proxy"
                 ],
                 "description": "Use case type"
               },
               "configuration": {
-                "$ref": "#/components/schemas/FileProxyUseCaseConfiguration"
+                "$ref": "#/components/schemas/SecureProxyUseCaseConfiguration"
               }
             }
           }
         ]
       },
-      "UseCase": {
+      "UseCaseHistoryEntry": {
         "oneOf": [
           {
-            "$ref": "#/components/schemas/InboundUseCase"
+            "$ref": "#/components/schemas/InboundUseCaseHistoryEntry"
           },
           {
-            "$ref": "#/components/schemas/OutboundUseCase"
+            "$ref": "#/components/schemas/OutboundUseCaseHistoryEntry"
           },
           {
-            "$ref": "#/components/schemas/FileProxyUseCase"
-          }
-        ],
-        "discriminator": {
-          "propertyName": "type",
-          "mapping": {
-            "inbound": "#/components/schemas/InboundUseCase",
-            "outbound": "#/components/schemas/OutboundUseCase",
-            "file_proxy": "#/components/schemas/FileProxyUseCase"
-          }
-        }
-      },
-      "CreateUseCaseRequest": {
-        "oneOf": [
-          {
-            "$ref": "#/components/schemas/CreateInboundUseCaseRequest"
+            "$ref": "#/components/schemas/FileProxyUseCaseHistoryEntry"
           },
           {
-            "$ref": "#/components/schemas/CreateOutboundUseCaseRequest"
+            "$ref": "#/components/schemas/ManagedCallUseCaseHistoryEntry"
           },
           {
-            "$ref": "#/components/schemas/CreateFileProxyUseCaseRequest"
+            "$ref": "#/components/schemas/SecureProxyUseCaseHistoryEntry"
           }
         ],
         "discriminator": {
           "propertyName": "type",
           "mapping": {
-            "inbound": "#/components/schemas/CreateInboundUseCaseRequest",
-            "outbound": "#/components/schemas/CreateOutboundUseCaseRequest",
-            "file_proxy": "#/components/schemas/CreateFileProxyUseCaseRequest"
+            "inbound": "#/components/schemas/InboundUseCaseHistoryEntry",
+            "outbound": "#/components/schemas/OutboundUseCaseHistoryEntry",
+            "file_proxy": "#/components/schemas/FileProxyUseCaseHistoryEntry",
+            "managed_call": "#/components/schemas/ManagedCallUseCaseHistoryEntry",
+            "secure_proxy": "#/components/schemas/SecureProxyUseCaseHistoryEntry"
           }
         }
       },
-      "CreateUseCaseRequestBase": {
+      "UseCaseHistoryEntryBase": {
         "type": "object",
         "required": [
+          "id",
+          "useCaseId",
+          "integrationId",
           "name",
           "type",
-          "enabled"
+          "enabled",
+          "created_at",
+          "updated_at",
+          "history_created_at"
         ],
         "properties": {
+          "id": {
+            "type": "string",
+            "format": "uuid",
+            "description": "Unique identifier for this history entry"
+          },
+          "useCaseId": {
+            "type": "string",
+            "format": "uuid",
+            "description": "Reference to the parent use case"
+          },
+          "integrationId": {
+            "type": "string",
+            "format": "uuid",
+            "description": "Parent integration ID"
+          },
           "name": {
             "type": "string",
-            "minLength": 1,
-            "maxLength": 255,
-            "description": "Use case name"
+            "description": "Use case name at this point in history"
           },
           "slug": {
             "type": "string",
-            "pattern": "^[a-z0-9][a-z0-9_-]*$",
-            "minLength": 1,
-            "maxLength": 255,
-            "description": "URL-safe identifier for the use case. Recommended for portable cross-environment referencing. Must be unique per integration. Immutable after creation. Lowercase alphanumeric, hyphens, and underscores only.\n"
+            "description": "Use case slug at this point in history"
           },
           "enabled": {
             "type": "boolean",
-            "description": "Whether the use case is enabled"
+            "description": "Whether the use case was enabled at this point in history"
+          },
+          "change_description": {
+            "type": "string",
+            "description": "Description of the change that was made at this point in history"
+          },
+          "created_at": {
+            "type": "string",
+            "format": "date-time",
+            "description": "ISO-8601 timestamp when the use case was originally created"
+          },
+          "updated_at": {
+            "type": "string",
+            "format": "date-time",
+            "description": "ISO-8601 timestamp of this historical snapshot (before the update)"
+          },
+          "history_created_at": {
+            "type": "string",
+            "format": "date-time",
+            "description": "ISO-8601 timestamp when this history entry was created"
           }
         }
       },
-      "CreateInboundUseCaseRequest": {
+      "InboundUseCaseHistoryEntry": {
         "allOf": [
           {
-            "$ref": "#/components/schemas/CreateUseCaseRequestBase"
+            "$ref": "#/components/schemas/UseCaseHistoryEntryBase"
           },
           {
             "type": "object",
@@ -3491,10 +4785,10 @@
           }
         ]
       },
-      "CreateOutboundUseCaseRequest": {
+      "OutboundUseCaseHistoryEntry": {
         "allOf": [
           {
-            "$ref": "#/components/schemas/CreateUseCaseRequestBase"
+            "$ref": "#/components/schemas/UseCaseHistoryEntryBase"
           },
           {
             "type": "object",
@@ -3516,10 +4810,10 @@
           }
         ]
       },
-      "CreateFileProxyUseCaseRequest": {
+      "FileProxyUseCaseHistoryEntry": {
         "allOf": [
           {
-            "$ref": "#/components/schemas/CreateUseCaseRequestBase"
+            "$ref": "#/components/schemas/UseCaseHistoryEntryBase"
           },
           {
             "type": "object",
@@ -3541,277 +4835,611 @@
           }
         ]
       },
-      "UpdateUseCaseRequest": {
-        "oneOf": [
+      "ManagedCallUseCaseHistoryEntry": {
+        "allOf": [
           {
-            "$ref": "#/components/schemas/UpdateInboundUseCaseRequest"
+            "$ref": "#/components/schemas/UseCaseHistoryEntryBase"
           },
           {
-            "$ref": "#/components/schemas/UpdateOutboundUseCaseRequest"
+            "type": "object",
+            "required": [
+              "type"
+            ],
+            "properties": {
+              "type": {
+                "type": "string",
+                "enum": [
+                  "managed_call"
+                ],
+                "description": "Use case type for managed API calls"
+              },
+              "configuration": {
+                "$ref": "#/components/schemas/ManagedCallOperationConfig"
+              },
+              "type_annotations": {
+                "$ref": "#/components/schemas/TypeAnnotations"
+              },
+              "types_locked": {
+                "type": "boolean",
+                "description": "Whether types have been generated for this use case"
+              }
+            }
+          }
+        ]
+      },
+      "SecureProxyUseCaseHistoryEntry": {
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/UseCaseHistoryEntryBase"
+          },
+          {
+            "type": "object",
+            "required": [
+              "type"
+            ],
+            "properties": {
+              "type": {
+                "type": "string",
+                "enum": [
+                  "secure_proxy"
+                ],
+                "description": "Use case type"
+              },
+              "configuration": {
+                "$ref": "#/components/schemas/SecureProxyUseCaseConfiguration"
+              }
+            }
+          }
+        ]
+      },
+      "SecureProxyUseCaseConfiguration": {
+        "type": "object",
+        "required": [
+          "vpc_mode"
+        ],
+        "description": "Configuration for secure_proxy use cases. Defines how to route requests through a secure VPC.\n",
+        "properties": {
+          "vpc_mode": {
+            "type": "string",
+            "enum": [
+              "static_ip",
+              "secure_link"
+            ],
+            "readOnly": true,
+            "description": "VPC routing mode. Read-only after creation.\n- static_ip: Routes through a VPC with static outbound IP (NAT Gateway) for IP-allowlisted external APIs.\n- secure_link: Routes through a VPN VPC for accessing private customer networks.\n"
+          },
+          "allowed_domains": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "readOnly": true,
+            "description": "Domain whitelist for secure_link mode. Admin-only — can only be modified directly in DynamoDB via admin script.\nSupports exact match (e.g., \"api.wemag.com\") and wildcard prefix (e.g., \"*.wemag.com\").\n"
+          },
+          "allowed_ips": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "readOnly": true,
+            "description": "IP allowlist (CIDR notation) for secure_link mode. Admin-only — can only be modified directly in DynamoDB via admin script.\nRequired for secure_link mode. All DNS-resolved IPs must match at least one range.\nExample: [\"10.0.1.0/24\", \"192.168.1.0/24\"]\n"
+          }
+        }
+      },
+      "SecureProxySummary": {
+        "type": "object",
+        "required": [
+          "id",
+          "name",
+          "enabled",
+          "vpc_mode",
+          "integration_id",
+          "integration_name"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "name": {
+            "type": "string"
+          },
+          "slug": {
+            "type": "string"
+          },
+          "enabled": {
+            "type": "boolean"
+          },
+          "vpc_mode": {
+            "type": "string",
+            "enum": [
+              "static_ip",
+              "secure_link"
+            ]
+          },
+          "allowed_domains": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "allowed_ips": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "integration_id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "integration_name": {
+            "type": "string"
+          }
+        }
+      },
+      "SecureProxyRequest": {
+        "type": "object",
+        "required": [
+          "url",
+          "method",
+          "integration_id"
+        ],
+        "properties": {
+          "integration_id": {
+            "type": "string",
+            "format": "uuid",
+            "description": "Integration ID that owns the secure_proxy use case"
+          },
+          "use_case_id": {
+            "type": "string",
+            "format": "uuid",
+            "description": "Use case ID (provide either use_case_id or use_case_slug)"
+          },
+          "use_case_slug": {
+            "type": "string",
+            "description": "Use case slug (provide either use_case_id or use_case_slug)"
+          },
+          "url": {
+            "type": "string",
+            "format": "uri",
+            "description": "Target URL to proxy the request to"
+          },
+          "method": {
+            "type": "string",
+            "enum": [
+              "GET",
+              "POST",
+              "PUT",
+              "PATCH",
+              "DELETE"
+            ],
+            "description": "HTTP method"
+          },
+          "headers": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "string"
+            },
+            "description": "Request headers to forward"
+          },
+          "body": {
+            "description": "Request body (string or JSON)"
+          },
+          "response_type": {
+            "type": "string",
+            "enum": [
+              "json",
+              "binary"
+            ],
+            "default": "json",
+            "description": "Expected response type"
+          }
+        }
+      },
+      "SecureProxyResponse": {
+        "type": "object",
+        "properties": {
+          "status_code": {
+            "type": "integer",
+            "description": "HTTP status code from the upstream response"
+          },
+          "headers": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "string"
+            },
+            "description": "Response headers from upstream"
+          },
+          "body": {
+            "description": "Response body from upstream"
+          }
+        }
+      },
+      "ManagedCallOperationConfig": {
+        "type": "object",
+        "required": [
+          "operation"
+        ],
+        "description": "Configuration for managed_call use cases. Defines a single API operation with JSONata mapping.",
+        "properties": {
+          "operation": {
+            "$ref": "#/components/schemas/ManagedCallOperation"
+          },
+          "request_mapping": {
+            "type": "string",
+            "description": "JSONata expression for outbound body transformation"
+          },
+          "response_mapping": {
+            "type": "string",
+            "description": "JSONata expression for inbound response transformation"
+          },
+          "inbound_use_case_slug": {
+            "type": "string",
+            "description": "Slug of the inbound use case to route responses to for async entity processing.\nWhen set, the managed call response is queued to the inbound pipeline and processed\nusing the referenced inbound use case's mapping configuration.\n"
+          }
+        }
+      },
+      "ManagedCallOperation": {
+        "type": "object",
+        "required": [
+          "method",
+          "path"
+        ],
+        "description": "HTTP operation configuration for managed calls",
+        "properties": {
+          "method": {
+            "type": "string",
+            "enum": [
+              "GET",
+              "POST",
+              "PUT",
+              "PATCH",
+              "DELETE"
+            ]
+          },
+          "path": {
+            "type": "string",
+            "description": "URL path template with {{variable}} interpolation"
+          },
+          "headers": {
+            "type": "object",
+            "description": "Custom HTTP headers for the request. Values support {{variable}} interpolation from the request payload and {{env.VAR}} references for environment variables.",
+            "additionalProperties": {
+              "type": "string"
+            }
           },
-          {
-            "$ref": "#/components/schemas/UpdateFileProxyUseCaseRequest"
-          }
-        ],
-        "discriminator": {
-          "propertyName": "type",
-          "mapping": {
-            "inbound": "#/components/schemas/UpdateInboundUseCaseRequest",
-            "outbound": "#/components/schemas/UpdateOutboundUseCaseRequest",
-            "file_proxy": "#/components/schemas/UpdateFileProxyUseCaseRequest"
+          "query_params": {
+            "type": "object",
+            "description": "Query parameters for the request. Values support {{variable}} interpolation from the request payload.",
+            "additionalProperties": {
+              "type": "string"
+            }
           }
         }
       },
-      "UpdateUseCaseRequestBase": {
+      "ManagedCallExecuteRequest": {
         "type": "object",
+        "required": [
+          "integration_id"
+        ],
         "properties": {
-          "name": {
-            "type": "string",
-            "minLength": 1,
-            "maxLength": 255,
-            "description": "Use case name"
-          },
-          "slug": {
+          "integration_id": {
             "type": "string",
-            "pattern": "^[a-z0-9][a-z0-9_-]*$",
-            "minLength": 1,
-            "maxLength": 255,
-            "description": "URL-safe identifier for the use case. Recommended for portable cross-environment referencing. Can only be set once on use cases that don't have a slug yet. Immutable after being set.\n"
+            "format": "uuid",
+            "description": "Integration ID"
           },
-          "enabled": {
-            "type": "boolean",
-            "description": "Whether the use case is enabled"
+          "payload": {
+            "type": "object",
+            "additionalProperties": true,
+            "description": "Request payload for the managed call operation"
           },
-          "change_description": {
+          "correlation_id": {
             "type": "string",
-            "maxLength": 2000,
-            "description": "Optional description of this change (like a commit message)"
+            "description": "Correlation ID for tracing related events (auto-generated if not provided)"
           }
         }
       },
-      "UpdateInboundUseCaseRequest": {
-        "allOf": [
-          {
-            "$ref": "#/components/schemas/UpdateUseCaseRequestBase"
-          },
-          {
+      "ManagedCallExecuteResponse": {
+        "description": "The response from a managed call execution.\nOn success, returns the JSONata-mapped response data directly (no wrapper).\nThe shape is entirely defined by your response_mapping JSONata expression.\nIf no response_mapping is configured, returns the raw external API response.\nCheck the X-Inbound-Event-Id header for inbound pipeline tracking when inbound routing is configured.\n",
+        "additionalProperties": true
+      },
+      "ManagedCallErrorResponse": {
+        "type": "object",
+        "required": [
+          "error"
+        ],
+        "properties": {
+          "error": {
             "type": "object",
+            "required": [
+              "code",
+              "message"
+            ],
             "properties": {
-              "type": {
+              "code": {
                 "type": "string",
-                "enum": [
-                  "inbound"
-                ],
-                "description": "Use case type"
+                "description": "Error code (e.g., EXTERNAL_API_ERROR, SSRF_BLOCKED, MANAGED_CALL_EXECUTION_ERROR)"
               },
-              "configuration": {
-                "$ref": "#/components/schemas/InboundIntegrationEventConfiguration"
+              "message": {
+                "type": "string",
+                "description": "Human-readable error message"
+              },
+              "details": {
+                "type": "object",
+                "additionalProperties": true,
+                "description": "Additional error details (e.g., status code and body for external API errors)"
               }
             }
           }
-        ]
+        }
       },
-      "UpdateOutboundUseCaseRequest": {
-        "allOf": [
-          {
-            "$ref": "#/components/schemas/UpdateUseCaseRequestBase"
+      "TypeAnnotations": {
+        "type": "object",
+        "description": "Developer-provided type annotations for a use case's request and response fields",
+        "properties": {
+          "request": {
+            "type": "object",
+            "description": "Type annotations for request fields, keyed by dot-path (e.g., \"vendors[].id\" -> \"string\")",
+            "additionalProperties": {
+              "type": "string"
+            }
           },
-          {
+          "response": {
             "type": "object",
-            "properties": {
-              "type": {
-                "type": "string",
-                "enum": [
-                  "outbound"
-                ],
-                "description": "Use case type"
-              },
-              "configuration": {
-                "$ref": "#/components/schemas/OutboundIntegrationEventConfiguration"
-              }
+            "description": "Type annotations for response fields",
+            "additionalProperties": {
+              "type": "string"
             }
           }
-        ]
+        }
       },
-      "UpdateFileProxyUseCaseRequest": {
-        "allOf": [
-          {
-            "$ref": "#/components/schemas/UpdateUseCaseRequestBase"
+      "TypeDescriptor": {
+        "type": "object",
+        "description": "Describes the inferred type shape of a JSONata expression",
+        "required": [
+          "kind"
+        ],
+        "properties": {
+          "kind": {
+            "type": "string",
+            "enum": [
+              "object",
+              "array",
+              "string",
+              "number",
+              "boolean",
+              "null",
+              "unknown",
+              "union"
+            ]
           },
-          {
+          "properties": {
             "type": "object",
-            "properties": {
-              "type": {
-                "type": "string",
-                "enum": [
-                  "file_proxy"
-                ],
-                "description": "Use case type"
-              },
-              "configuration": {
-                "$ref": "#/components/schemas/FileProxyUseCaseConfiguration"
+            "description": "For kind=object, the properties and their type descriptors",
+            "additionalProperties": {
+              "$ref": "#/components/schemas/TypeDescriptor"
+            }
+          },
+          "items": {
+            "description": "For kind=array, the type of array items",
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/TypeDescriptor"
               }
+            ]
+          },
+          "source": {
+            "type": "string",
+            "description": "For kind=unknown, the JSONata path that produced this value"
+          },
+          "variants": {
+            "type": "array",
+            "description": "For kind=union, the variant types",
+            "items": {
+              "$ref": "#/components/schemas/TypeDescriptor"
             }
           }
-        ]
+        }
       },
-      "UseCaseHistoryEntry": {
-        "oneOf": [
-          {
-            "$ref": "#/components/schemas/InboundUseCaseHistoryEntry"
+      "UseCaseTypePreview": {
+        "type": "object",
+        "description": "Scaffolded type descriptors for a single use case",
+        "required": [
+          "slug",
+          "request_shape",
+          "response_shape"
+        ],
+        "properties": {
+          "slug": {
+            "type": "string"
           },
-          {
-            "$ref": "#/components/schemas/OutboundUseCaseHistoryEntry"
+          "name": {
+            "type": "string"
           },
-          {
-            "$ref": "#/components/schemas/FileProxyUseCaseHistoryEntry"
-          }
-        ],
-        "discriminator": {
-          "propertyName": "type",
-          "mapping": {
-            "inbound": "#/components/schemas/InboundUseCaseHistoryEntry",
-            "outbound": "#/components/schemas/OutboundUseCaseHistoryEntry",
-            "file_proxy": "#/components/schemas/FileProxyUseCaseHistoryEntry"
+          "request_shape": {
+            "$ref": "#/components/schemas/TypeDescriptor"
+          },
+          "response_shape": {
+            "$ref": "#/components/schemas/TypeDescriptor"
+          },
+          "existing_annotations": {
+            "$ref": "#/components/schemas/TypeAnnotations"
           }
         }
       },
-      "UseCaseHistoryEntryBase": {
+      "GenerateTypesPreviewResponse": {
         "type": "object",
         "required": [
-          "id",
-          "useCaseId",
-          "integrationId",
-          "name",
-          "type",
-          "enabled",
-          "created_at",
-          "updated_at",
-          "history_created_at"
+          "use_cases"
         ],
         "properties": {
-          "id": {
-            "type": "string",
-            "format": "uuid",
-            "description": "Unique identifier for this history entry"
+          "integration_name": {
+            "type": "string"
           },
-          "useCaseId": {
-            "type": "string",
-            "format": "uuid",
-            "description": "Reference to the parent use case"
+          "use_cases": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/UseCaseTypePreview"
+            }
           },
-          "integrationId": {
+          "previous_version": {
             "type": "string",
-            "format": "uuid",
-            "description": "Parent integration ID"
+            "description": "Previously generated version, if any"
           },
-          "name": {
+          "suggested_version": {
             "type": "string",
-            "description": "Use case name at this point in history"
+            "description": "Suggested next version based on detected changes"
           },
-          "slug": {
+          "suggested_bump": {
             "type": "string",
-            "description": "Use case slug at this point in history"
-          },
-          "enabled": {
-            "type": "boolean",
-            "description": "Whether the use case was enabled at this point in history"
+            "enum": [
+              "major",
+              "minor"
+            ]
           },
-          "change_description": {
+          "detected_changes": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": [
+                "slug",
+                "field",
+                "type",
+                "description"
+              ],
+              "properties": {
+                "slug": {
+                  "type": "string"
+                },
+                "field": {
+                  "type": "string"
+                },
+                "type": {
+                  "type": "string",
+                  "enum": [
+                    "breaking",
+                    "non-breaking"
+                  ]
+                },
+                "description": {
+                  "type": "string"
+                }
+              }
+            }
+          }
+        }
+      },
+      "GenerateTypesRequest": {
+        "type": "object",
+        "required": [
+          "package_name",
+          "version"
+        ],
+        "properties": {
+          "package_name": {
             "type": "string",
-            "description": "Description of the change that was made at this point in history"
+            "description": "npm package name",
+            "example": "@epilot/hems-cleverpv"
           },
-          "created_at": {
+          "version": {
             "type": "string",
-            "format": "date-time",
-            "description": "ISO-8601 timestamp when the use case was originally created"
+            "description": "Package version",
+            "example": "1.0.0"
           },
-          "updated_at": {
+          "description": {
+            "type": "string"
+          },
+          "domain_package": {
             "type": "string",
-            "format": "date-time",
-            "description": "ISO-8601 timestamp of this historical snapshot (before the update)"
+            "description": "Domain standard package to extend",
+            "example": "@epilot/hems"
           },
-          "history_created_at": {
+          "domain_map_name": {
             "type": "string",
-            "format": "date-time",
-            "description": "ISO-8601 timestamp when this history entry was created"
+            "description": "Name of the domain UseCaseMap to extend",
+            "example": "HemsUseCaseMap"
+          },
+          "annotations": {
+            "type": "object",
+            "description": "Type annotations per use case slug",
+            "additionalProperties": {
+              "$ref": "#/components/schemas/TypeAnnotations"
+            }
           }
         }
       },
-      "InboundUseCaseHistoryEntry": {
-        "allOf": [
-          {
-            "$ref": "#/components/schemas/UseCaseHistoryEntryBase"
-          },
-          {
-            "type": "object",
-            "required": [
-              "type"
-            ],
-            "properties": {
-              "type": {
-                "type": "string",
-                "enum": [
-                  "inbound"
-                ],
-                "description": "Use case type"
-              },
-              "configuration": {
-                "$ref": "#/components/schemas/InboundIntegrationEventConfiguration"
-              }
+      "GenerateTypesResponse": {
+        "type": "object",
+        "required": [
+          "package_name",
+          "version",
+          "files"
+        ],
+        "properties": {
+          "package_name": {
+            "type": "string"
+          },
+          "version": {
+            "type": "string"
+          },
+          "files": {
+            "type": "object",
+            "description": "Generated file contents keyed by file path",
+            "additionalProperties": {
+              "type": "string"
+            }
+          },
+          "warnings": {
+            "type": "array",
+            "items": {
+              "type": "string"
             }
           }
-        ]
+        }
       },
-      "OutboundUseCaseHistoryEntry": {
-        "allOf": [
-          {
-            "$ref": "#/components/schemas/UseCaseHistoryEntryBase"
+      "CommitTypesRequest": {
+        "type": "object",
+        "required": [
+          "package_name",
+          "version"
+        ],
+        "properties": {
+          "package_name": {
+            "type": "string",
+            "description": "npm package name",
+            "example": "@epilot/hems-cleverpv"
           },
-          {
+          "version": {
+            "type": "string",
+            "description": "Package version",
+            "example": "1.0.0"
+          },
+          "annotations": {
             "type": "object",
-            "required": [
-              "type"
-            ],
-            "properties": {
-              "type": {
-                "type": "string",
-                "enum": [
-                  "outbound"
-                ],
-                "description": "Use case type"
-              },
-              "configuration": {
-                "$ref": "#/components/schemas/OutboundIntegrationEventConfiguration"
-              }
+            "description": "Type annotations per use case slug",
+            "additionalProperties": {
+              "$ref": "#/components/schemas/TypeAnnotations"
             }
           }
-        ]
+        }
       },
-      "FileProxyUseCaseHistoryEntry": {
-        "allOf": [
-          {
-            "$ref": "#/components/schemas/UseCaseHistoryEntryBase"
+      "CommitTypesResponse": {
+        "type": "object",
+        "required": [
+          "committed"
+        ],
+        "properties": {
+          "committed": {
+            "type": "boolean"
           },
-          {
-            "type": "object",
-            "required": [
-              "type"
-            ],
-            "properties": {
-              "type": {
-                "type": "string",
-                "enum": [
-                  "file_proxy"
-                ],
-                "description": "Use case type"
-              },
-              "configuration": {
-                "$ref": "#/components/schemas/FileProxyUseCaseConfiguration"
-              }
+          "warnings": {
+            "type": "array",
+            "items": {
+              "type": "string"
             }
           }
-        ]
+        }
       },
       "FileProxyUseCaseConfiguration": {
         "type": "object",
@@ -3821,11 +5449,13 @@
         ],
         "description": "Configuration for file_proxy use cases. Defines how to authenticate and fetch files from external document systems.\n\nThe file proxy download URL always requires `orgId`, `integrationId`, and either `useCaseSlug` (recommended) or `useCaseId` (legacy UUID) as query parameters.\nThe `orgId` is included in the signed URL to establish organization context without requiring authentication.\nAdditional use-case-specific parameters are declared in the `params` array.\n",
         "properties": {
-          "requires_vpc": {
-            "type": "boolean",
-            "readOnly": true,
-            "description": "Whether requests require VPC routing for IP allowlisting. Read-only after creation — can only be modified directly in DynamoDB.",
-            "default": false
+          "secure_proxy": {
+            "description": "Optional secure proxy attachment for routing all outbound file proxy requests.\nOnly `use_case_slug` is supported and the referenced secure_proxy use case\nmust belong to the same integration.\n",
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/FileProxySecureProxyAttachment"
+              }
+            ]
           },
           "auth": {
             "$ref": "#/components/schemas/FileProxyAuth"
@@ -3850,6 +5480,19 @@
           }
         }
       },
+      "FileProxySecureProxyAttachment": {
+        "type": "object",
+        "required": [
+          "use_case_slug"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "use_case_slug": {
+            "type": "string",
+            "description": "Slug of the secure_proxy use case in the same integration."
+          }
+        }
+      },
       "FileProxyAuth": {
         "type": "object",
         "required": [
@@ -4336,7 +5979,6 @@
       "OutboundMapping": {
         "type": "object",
         "required": [
-          "id",
           "name",
           "jsonata_expression",
           "enabled",
@@ -5426,48 +7068,222 @@
           },
           "event_id": {
             "type": "string",
-            "description": "Unique event identifier"
+            "description": "Unique event identifier"
+          },
+          "correlation_id": {
+            "type": "string",
+            "nullable": true,
+            "description": "Correlation ID for tracing related events"
+          },
+          "integration_id": {
+            "type": "string",
+            "nullable": true,
+            "description": "Integration ID"
+          },
+          "use_case_id": {
+            "type": "string",
+            "nullable": true,
+            "description": "Use case ID"
+          },
+          "event_type": {
+            "type": "string",
+            "enum": [
+              "CREATE",
+              "UPDATE",
+              "DELETE",
+              "TRIGGER"
+            ],
+            "description": "Type of event (optional for V3 events)"
+          },
+          "object_type": {
+            "type": "string",
+            "description": "Type of object being synced (e.g., 'contract', 'meter')"
+          },
+          "sync_type": {
+            "type": "string",
+            "enum": [
+              "entity",
+              "meter_reading",
+              "webhook",
+              "api_deprecation"
+            ],
+            "description": "Type of sync operation"
+          },
+          "status": {
+            "type": "string",
+            "enum": [
+              "success",
+              "error",
+              "skipped",
+              "warning"
+            ],
+            "description": "Processing status"
+          },
+          "error_code": {
+            "type": "string",
+            "nullable": true,
+            "description": "Error code (when status=error)"
+          },
+          "error_message": {
+            "type": "string",
+            "nullable": true,
+            "description": "Error message (when status=error)"
+          },
+          "error_category": {
+            "type": "string",
+            "nullable": true,
+            "enum": [
+              "validation",
+              "configuration",
+              "downstream_api",
+              "timeout",
+              "system"
+            ],
+            "description": "Error category (when status=error)"
+          },
+          "processing_duration_ms": {
+            "type": "integer",
+            "nullable": true,
+            "description": "Processing duration in milliseconds"
+          },
+          "received_at": {
+            "type": "string",
+            "format": "date-time",
+            "description": "When the event was received"
+          },
+          "completed_at": {
+            "type": "string",
+            "format": "date-time",
+            "description": "When processing completed"
+          }
+        }
+      },
+      "QueryMonitoringEventsV2Request": {
+        "type": "object",
+        "properties": {
+          "use_case_id": {
+            "type": "string",
+            "description": "Filter by use case ID (UUID). Empty string matches \"General\" events."
+          },
+          "use_case_type": {
+            "type": "string",
+            "enum": [
+              "inbound",
+              "outbound",
+              "file_proxy",
+              "managed_call",
+              "secure_proxy"
+            ],
+            "description": "Filter by use case type (replaces direction)"
+          },
+          "level": {
+            "type": "string",
+            "enum": [
+              "success",
+              "error",
+              "skipped",
+              "warning"
+            ],
+            "description": "Filter by event level"
+          },
+          "code": {
+            "type": "string",
+            "description": "Filter by taxonomy code (e.g. OAUTH2_TOKEN_FAILURE, HTTP_502)"
+          },
+          "event_id": {
+            "type": "string",
+            "description": "Filter by trigger/inbound event ID"
+          },
+          "correlation_id": {
+            "type": "string",
+            "description": "Filter by correlation ID for tracing"
+          },
+          "from_date": {
+            "type": "string",
+            "format": "date-time",
+            "description": "Filter events from this date (inclusive)",
+            "example": "2025-01-01T00:00:00Z"
+          },
+          "to_date": {
+            "type": "string",
+            "format": "date-time",
+            "description": "Filter events until this date (inclusive)",
+            "example": "2025-01-31T23:59:59Z"
+          },
+          "limit": {
+            "type": "integer",
+            "description": "Maximum number of results to return",
+            "example": 50,
+            "default": 50,
+            "minimum": 1,
+            "maximum": 100
+          },
+          "cursor": {
+            "type": "object",
+            "description": "Cursor for pagination (from previous response's next_cursor)",
+            "properties": {
+              "created_at": {
+                "type": "string",
+                "format": "date-time"
+              },
+              "id": {
+                "type": "string",
+                "format": "uuid"
+              }
+            }
+          }
+        }
+      },
+      "MonitoringEventV2": {
+        "type": "object",
+        "required": [
+          "id",
+          "org_id",
+          "integration_id",
+          "event_id",
+          "use_case_type",
+          "level",
+          "created_at"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "format": "uuid",
+            "description": "Unique monitoring event ID"
           },
-          "correlation_id": {
+          "org_id": {
             "type": "string",
-            "nullable": true,
-            "description": "Correlation ID for tracing related events"
+            "description": "Organization ID"
           },
           "integration_id": {
             "type": "string",
-            "nullable": true,
             "description": "Integration ID"
           },
-          "use_case_id": {
+          "event_id": {
             "type": "string",
-            "nullable": true,
-            "description": "Use case ID"
+            "description": "Trigger/inbound event ID (groups related monitoring events)"
           },
-          "event_type": {
+          "correlation_id": {
             "type": "string",
-            "enum": [
-              "CREATE",
-              "UPDATE",
-              "DELETE",
-              "TRIGGER"
-            ],
-            "description": "Type of event (optional for V3 events)"
+            "description": "Correlation ID for tracing. Empty when unavailable."
           },
-          "object_type": {
+          "use_case_id": {
             "type": "string",
-            "description": "Type of object being synced (e.g., 'contract', 'meter')"
+            "description": "Use case ID. Empty for system-level events (\"General\")."
           },
-          "sync_type": {
+          "use_case_type": {
             "type": "string",
             "enum": [
-              "entity",
-              "meter_reading",
-              "webhook",
-              "api_deprecation"
+              "inbound",
+              "outbound",
+              "file_proxy",
+              "managed_call",
+              "secure_proxy",
+              ""
             ],
-            "description": "Type of sync operation"
+            "description": "Use case type. Empty for system-level events."
           },
-          "status": {
+          "level": {
             "type": "string",
             "enum": [
               "success",
@@ -5475,44 +7291,198 @@
               "skipped",
               "warning"
             ],
-            "description": "Processing status"
+            "description": "Event outcome level"
           },
-          "error_code": {
+          "code": {
             "type": "string",
-            "nullable": true,
-            "description": "Error code (when status=error)"
+            "description": "Taxonomy code (e.g. OAUTH2_TOKEN_FAILURE, HTTP_502). Empty for success."
           },
-          "error_message": {
+          "message": {
             "type": "string",
+            "description": "Human-readable message. Empty when not applicable."
+          },
+          "detail": {
+            "type": "object",
             "nullable": true,
-            "description": "Error message (when status=error)"
+            "additionalProperties": true,
+            "description": "Event-specific JSON data. Structure determined by `code`."
           },
-          "error_category": {
+          "created_at": {
+            "type": "string",
+            "format": "date-time",
+            "description": "When the monitoring event was created"
+          }
+        }
+      },
+      "GetMonitoringStatsV2Request": {
+        "type": "object",
+        "properties": {
+          "from_date": {
+            "type": "string",
+            "format": "date-time",
+            "description": "Start of the time range",
+            "example": "2025-01-01T00:00:00Z"
+          },
+          "to_date": {
+            "type": "string",
+            "format": "date-time",
+            "description": "End of the time range",
+            "example": "2025-01-31T23:59:59Z"
+          },
+          "use_case_type": {
             "type": "string",
-            "nullable": true,
             "enum": [
-              "validation",
-              "configuration",
-              "downstream_api",
-              "timeout",
-              "system"
+              "inbound",
+              "outbound",
+              "file_proxy",
+              "managed_call",
+              "secure_proxy"
             ],
-            "description": "Error category (when status=error)"
+            "description": "Filter stats by use case type"
           },
-          "processing_duration_ms": {
+          "group_by": {
+            "type": "string",
+            "enum": [
+              "use_case_id",
+              "use_case_type",
+              "level",
+              "code",
+              "date"
+            ],
+            "description": "Field to group the breakdown by"
+          }
+        }
+      },
+      "MonitoringStatsV2": {
+        "type": "object",
+        "required": [
+          "total_events",
+          "success_count",
+          "error_count",
+          "warning_count",
+          "skipped_count"
+        ],
+        "properties": {
+          "total_events": {
+            "type": "integer",
+            "description": "Total number of events in the period"
+          },
+          "success_count": {
+            "type": "integer",
+            "description": "Number of successful events"
+          },
+          "error_count": {
+            "type": "integer",
+            "description": "Number of error events"
+          },
+          "warning_count": {
+            "type": "integer",
+            "description": "Number of warning events"
+          },
+          "skipped_count": {
+            "type": "integer",
+            "description": "Number of skipped events"
+          },
+          "ack_timeout_count": {
             "type": "integer",
+            "description": "Number of ACK_TIMEOUT events (acknowledgement timed out)"
+          },
+          "success_rate": {
+            "type": "number",
+            "format": "float",
+            "description": "Success rate as percentage (0-100)"
+          },
+          "last_error_at": {
+            "type": "string",
+            "format": "date-time",
             "nullable": true,
-            "description": "Processing duration in milliseconds"
+            "description": "Timestamp of the most recent error"
           },
-          "received_at": {
+          "breakdown": {
+            "type": "array",
+            "description": "Statistics breakdown by requested group_by field",
+            "items": {
+              "type": "object",
+              "additionalProperties": true
+            }
+          }
+        }
+      },
+      "GetMonitoringTimeSeriesV2Request": {
+        "type": "object",
+        "required": [
+          "from_date",
+          "interval"
+        ],
+        "properties": {
+          "from_date": {
             "type": "string",
             "format": "date-time",
-            "description": "When the event was received"
+            "description": "Start of the time range (required)",
+            "example": "2025-01-01T00:00:00Z"
           },
-          "completed_at": {
+          "to_date": {
             "type": "string",
             "format": "date-time",
-            "description": "When processing completed"
+            "description": "End of the time range (defaults to now)",
+            "example": "2025-01-31T23:59:59Z"
+          },
+          "interval": {
+            "type": "string",
+            "enum": [
+              "5m",
+              "10m",
+              "30m",
+              "1h",
+              "3h",
+              "1d"
+            ],
+            "description": "Time bucket interval"
+          },
+          "use_case_type": {
+            "type": "string",
+            "enum": [
+              "inbound",
+              "outbound",
+              "file_proxy",
+              "managed_call",
+              "secure_proxy"
+            ],
+            "description": "Filter by use case type"
+          }
+        }
+      },
+      "TimeSeriesBucketV2": {
+        "type": "object",
+        "required": [
+          "timestamp",
+          "total_count"
+        ],
+        "properties": {
+          "timestamp": {
+            "type": "string",
+            "format": "date-time",
+            "description": "Bucket start timestamp"
+          },
+          "success_count": {
+            "type": "integer",
+            "description": "Number of successful events in the bucket"
+          },
+          "error_count": {
+            "type": "integer",
+            "description": "Number of error events in the bucket"
+          },
+          "warning_count": {
+            "type": "integer",
+            "description": "Number of warning events in the bucket"
+          },
+          "skipped_count": {
+            "type": "integer",
+            "description": "Number of skipped events in the bucket"
+          },
+          "total_count": {
+            "type": "integer",
+            "description": "Total events in the bucket"
           }
         }
       }
@@ -5548,6 +7518,16 @@
           }
         }
       },
+      "Forbidden": {
+        "description": "Forbidden - insufficient permissions",
+        "content": {
+          "application/json": {
+            "schema": {
+              "$ref": "#/components/schemas/ErrorResponseBase"
+            }
+          }
+        }
+      },
       "InternalServerError": {
         "description": "Internal Server Error",
         "content": {
@@ -5839,6 +7819,117 @@
             }
           }
         }
+      },
+      "QueryMonitoringEventsV2Response": {
+        "description": "Monitoring events queried successfully",
+        "content": {
+          "application/json": {
+            "schema": {
+              "type": "object",
+              "properties": {
+                "data": {
+                  "type": "array",
+                  "items": {
+                    "$ref": "#/components/schemas/MonitoringEventV2"
+                  },
+                  "description": "List of monitoring events"
+                },
+                "next_cursor": {
+                  "type": "object",
+                  "nullable": true,
+                  "description": "Cursor to fetch the next page. Null if no more results.",
+                  "properties": {
+                    "created_at": {
+                      "type": "string",
+                      "format": "date-time"
+                    },
+                    "id": {
+                      "type": "string",
+                      "format": "uuid"
+                    }
+                  }
+                },
+                "has_more": {
+                  "type": "boolean",
+                  "description": "Indicates if more results are available"
+                }
+              }
+            }
+          }
+        }
+      },
+      "GetMonitoringStatsV2Response": {
+        "description": "Monitoring statistics retrieved successfully",
+        "content": {
+          "application/json": {
+            "schema": {
+              "$ref": "#/components/schemas/MonitoringStatsV2"
+            }
+          }
+        }
+      },
+      "GetMonitoringTimeSeriesV2Response": {
+        "description": "Time-series data retrieved successfully",
+        "content": {
+          "application/json": {
+            "schema": {
+              "type": "object",
+              "properties": {
+                "interval": {
+                  "type": "string",
+                  "enum": [
+                    "5m",
+                    "10m",
+                    "30m",
+                    "1h",
+                    "3h",
+                    "1d"
+                  ],
+                  "description": "The bucket interval"
+                },
+                "from_date": {
+                  "type": "string",
+                  "format": "date-time"
+                },
+                "to_date": {
+                  "type": "string",
+                  "format": "date-time"
+                },
+                "buckets": {
+                  "type": "array",
+                  "items": {
+                    "$ref": "#/components/schemas/TimeSeriesBucketV2"
+                  }
+                }
+              }
+            }
+          }
+        }
+      },
+      "GetAssociatedMonitoringEventsResponse": {
+        "description": "Associated monitoring events for the given event_id",
+        "content": {
+          "application/json": {
+            "schema": {
+              "type": "object",
+              "properties": {
+                "monitoring_events": {
+                  "type": "array",
+                  "items": {
+                    "$ref": "#/components/schemas/MonitoringEventV2"
+                  },
+                  "description": "All monitoring events sharing this event_id, ordered by created_at ASC"
+                },
+                "inbound_event": {
+                  "type": "object",
+                  "nullable": true,
+                  "additionalProperties": true,
+                  "description": "The original inbound event payload from erp_incoming_events, if available"
+                }
+              }
+            }
+          }
+        }
       }
     }
   }