@epilot/sdk 2.20.33 → 2.20.35

package/definitions/integration-toolkit.json

@@ -2,7 +2,7 @@
   "openapi": "3.0.3",
   "info": {
     "title": "Integration Toolkit API",
-    "version": "1.33.0",
+    "version": "1.35.0",
     "description": "API for integrating with external systems in a standardised way."
   },
   "tags": [
@@ -49,6 +49,7 @@
     "/v1/erp/tracking/acknowledgement": {
       "post": {
         "operationId": "acknowledgeTracking",
+        "x-epilot-permissions": [],
         "summary": "acknowledgeTracking",
         "description": "Acknowledges an ERP tracking record by removing it from the tracking table, requires public authentication",
         "tags": [
@@ -106,6 +107,11 @@
     "/v1/erp/trigger": {
       "post": {
         "operationId": "triggerErp",
+        "x-epilot-permissions": [
+          {
+            "action": "entity:view"
+          }
+        ],
         "summary": "triggerErp",
         "description": "Triggers the ERP integration process",
         "tags": [
@@ -142,6 +148,7 @@
       "post": {
         "deprecated": true,
         "operationId": "processErpUpdatesEvents",
+        "x-epilot-permissions": [],
         "summary": "processErpUpdatesEvents",
         "description": "Handles updates from ERP systems and tracks them appropriately",
         "tags": [
@@ -227,6 +234,9 @@
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
+          "429": {
+            "$ref": "#/components/responses/ERPUpdatesRetryableResponse"
+          },
           "500": {
             "$ref": "#/components/responses/InternalServerError"
           }
@@ -237,6 +247,7 @@
       "post": {
         "deprecated": true,
         "operationId": "processErpUpdatesEventsV2",
+        "x-epilot-permissions": [],
         "summary": "processErpUpdatesEventsV2",
         "description": "Handles updates from ERP systems using integration_id directly.\nThis is the v2 version that simplifies the API by accepting integration_id\ninstead of app_id and component_id.\n",
         "tags": [
@@ -286,6 +297,9 @@
           "404": {
             "$ref": "#/components/responses/NotFound"
           },
+          "429": {
+            "$ref": "#/components/responses/ERPUpdatesRetryableResponse"
+          },
           "500": {
             "$ref": "#/components/responses/InternalServerError"
           }
@@ -295,6 +309,7 @@
     "/v3/erp/updates/events": {
       "post": {
         "operationId": "processErpUpdatesEventsV3",
+        "x-epilot-permissions": [],
         "summary": "processErpUpdatesEventsV3",
         "description": "Handles updates from ERP systems using integration_id directly.\nThis is the v3 version that removes the unused event_type field and renames object_type to event_name\nto align with the integration UI naming.\n",
         "tags": [
@@ -342,6 +357,9 @@
           "404": {
             "$ref": "#/components/responses/NotFound"
           },
+          "429": {
+            "$ref": "#/components/responses/ERPUpdatesRetryableResponse"
+          },
           "500": {
             "$ref": "#/components/responses/InternalServerError"
           }
@@ -351,6 +369,7 @@
     "/v2/erp/updates/mapping_simulation": {
       "post": {
         "operationId": "simulateMappingV2",
+        "x-epilot-permissions": [],
         "summary": "simulateMappingV2",
         "description": "Test v2.0 mapping configuration by transforming a payload using the provided mapping rules without persisting data.\n\nThis endpoint accepts the same configuration format that is stored in the integration use case resource,\nmaking it easier to test configurations before saving them to a use case.\n\nSee documentation at /docs/MAPPING_V2.md for detailed v2.0 format specification.\n",
         "tags": [
@@ -622,6 +641,7 @@
     "/v1/erp/updates/direct_simulation": {
       "post": {
         "operationId": "simulateDirect",
+        "x-epilot-permissions": [],
         "summary": "simulateDirect",
         "description": "Dry run for direct-mode payloads: validates a `DirectPayload` against a `direct: true`\nuse case configuration and previews the internal entity and meter reading updates the\npipeline would apply — without persisting anything.\n\nUnlike the ingest endpoint, validation does not stop at the first problem: ALL issues\nacross all operations are collected into `errors`, each carrying the index of the\noperation it refers to. When the payload is valid, the response additionally contains\nthe translated update previews plus non-blocking `warnings` (for example unique-id\nfields that are not defined in the target entity schema, or a failed server-side\nunique-id type derivation).\n\nUse this endpoint while designing a direct integration, before sending events to\n`POST /v3/erp/updates/events`. See documentation at /docs/DIRECT_MODE.md.\n",
         "tags": [
@@ -783,6 +803,7 @@
     "/v1/erp/updates/mapping_simulation": {
       "post": {
         "operationId": "simulateMapping",
+        "x-epilot-permissions": [],
         "summary": "simulateMapping",
         "description": "Test mapping configuration by transforming a payload using the provided mapping rules without persisting data.\n\nSupports both v1.0 (object-based) and v2.0 (event-based) mapping formats.\nSee documentation at /docs/MAPPING_V2.md for detailed v2.0 format specification.\n",
         "tags": [
@@ -1116,6 +1137,11 @@
     "/v1/integrations": {
       "get": {
         "operationId": "listIntegrations",
+        "x-epilot-permissions": [
+          {
+            "action": "integration:view"
+          }
+        ],
         "summary": "listIntegrations",
         "description": "Retrieve all integrations for the authenticated organization",
         "tags": [
@@ -1153,6 +1179,11 @@
       },
       "post": {
         "operationId": "createIntegration",
+        "x-epilot-permissions": [
+          {
+            "action": "integration:manage"
+          }
+        ],
         "summary": "createIntegration",
         "description": "Create a new integration configuration",
         "tags": [
@@ -1194,6 +1225,11 @@
     "/v1/integrations/{integrationId}": {
       "get": {
         "operationId": "getIntegration",
+        "x-epilot-permissions": [
+          {
+            "action": "integration:view"
+          }
+        ],
         "summary": "getIntegration",
         "description": "Retrieve a specific integration by its ID",
         "tags": [
@@ -1235,6 +1271,11 @@
       },
       "put": {
         "operationId": "updateIntegration",
+        "x-epilot-permissions": [
+          {
+            "action": "integration:manage"
+          }
+        ],
         "summary": "updateIntegration",
         "description": "Update an existing integration configuration",
         "tags": [
@@ -1289,6 +1330,11 @@
       },
       "delete": {
         "operationId": "deleteIntegration",
+        "x-epilot-permissions": [
+          {
+            "action": "integration:manage"
+          }
+        ],
         "summary": "deleteIntegration",
         "description": "Delete an integration and all its use cases",
         "tags": [
@@ -1337,6 +1383,11 @@
     "/v1/integrations/{integrationId}/events": {
       "post": {
         "operationId": "queryEvents",
+        "x-epilot-permissions": [
+          {
+            "action": "integration:view"
+          }
+        ],
         "summary": "queryEvents",
         "description": "Query events for a specific integration",
         "tags": [
@@ -1386,6 +1437,11 @@
     "/v1/integrations/{integrationId}/events/replay": {
       "post": {
         "operationId": "replayEvents",
+        "x-epilot-permissions": [
+          {
+            "action": "integration:manage"
+          }
+        ],
         "summary": "replayEvents",
         "description": "Replay one or more events for a specific integration. Events will be re-processed with their original payloads but with a new correlation ID for traceability.",
         "tags": [
@@ -1435,6 +1491,11 @@
     "/v1/integrations/{integrationId}/use-cases": {
       "get": {
         "operationId": "listUseCases",
+        "x-epilot-permissions": [
+          {
+            "action": "integration:view"
+          }
+        ],
         "summary": "listUseCases",
         "description": "Retrieve all use cases for a specific integration",
         "tags": [
@@ -1484,6 +1545,11 @@
       },
       "post": {
         "operationId": "createUseCase",
+        "x-epilot-permissions": [
+          {
+            "action": "integration:manage"
+          }
+        ],
         "summary": "createUseCase",
         "description": "Create a new use case for an integration",
         "tags": [
@@ -1540,6 +1606,11 @@
     "/v1/integrations/{integrationId}/use-cases/{useCaseId}": {
       "get": {
         "operationId": "getUseCase",
+        "x-epilot-permissions": [
+          {
+            "action": "integration:view"
+          }
+        ],
         "summary": "getUseCase",
         "description": "Retrieve a specific use case by its ID",
         "tags": [
@@ -1591,6 +1662,11 @@
       },
       "put": {
         "operationId": "updateUseCase",
+        "x-epilot-permissions": [
+          {
+            "action": "integration:manage"
+          }
+        ],
         "summary": "updateUseCase",
         "description": "Update an existing use case configuration",
         "tags": [
@@ -1655,6 +1731,11 @@
       },
       "delete": {
         "operationId": "deleteUseCase",
+        "x-epilot-permissions": [
+          {
+            "action": "integration:manage"
+          }
+        ],
         "summary": "deleteUseCase",
         "description": "Delete a use case from an integration",
         "tags": [
@@ -1713,6 +1794,11 @@
     "/v1/integrations/{integrationId}/use-cases/{useCaseId}/history": {
       "get": {
         "operationId": "listUseCaseHistory",
+        "x-epilot-permissions": [
+          {
+            "action": "integration:view"
+          }
+        ],
         "summary": "listUseCaseHistory",
         "description": "Retrieve historical versions of a use case's configuration.\nHistory entries are returned in reverse chronological order (newest first).\nUse the 'cursor' parameter for pagination to fetch additional entries.\n",
         "tags": [
@@ -1792,6 +1878,11 @@
     "/v1/integrations/{integrationId}/documentation": {
       "get": {
         "operationId": "listDocumentationPages",
+        "x-epilot-permissions": [
+          {
+            "action": "integration:view"
+          }
+        ],
         "summary": "listDocumentationPages",
         "description": "Retrieve all documentation pages of an integration, without their markdown content.\nAn integration has at most one general page plus at most one page per use case.\nThe page id is 'general' for the integration-wide page, otherwise the use case ID.\n",
         "tags": [
@@ -1846,6 +1937,11 @@
     "/v1/integrations/{integrationId}/documentation/{docId}": {
       "get": {
         "operationId": "getDocumentationPage",
+        "x-epilot-permissions": [
+          {
+            "action": "integration:view"
+          }
+        ],
         "summary": "getDocumentationPage",
         "description": "Retrieve a single documentation page including its markdown content",
         "tags": [
@@ -1897,6 +1993,11 @@
       },
       "put": {
         "operationId": "upsertDocumentationPage",
+        "x-epilot-permissions": [
+          {
+            "action": "integration:manage"
+          }
+        ],
         "summary": "upsertDocumentationPage",
         "description": "Create or update the documentation page identified by docId.\nUpsert semantics enforce the invariant of one general page per\nintegration and one page per use case. For use case pages the\nuse case must exist.\n",
         "tags": [
@@ -1964,6 +2065,11 @@
       },
       "delete": {
         "operationId": "deleteDocumentationPage",
+        "x-epilot-permissions": [
+          {
+            "action": "integration:manage"
+          }
+        ],
         "summary": "deleteDocumentationPage",
         "description": "Delete a documentation page",
         "tags": [
@@ -2025,6 +2131,11 @@
     "/v2/integrations": {
       "get": {
         "operationId": "listIntegrationsV2",
+        "x-epilot-permissions": [
+          {
+            "action": "integration:view"
+          }
+        ],
         "summary": "listIntegrationsV2",
         "description": "Retrieve all integrations with embedded use cases for the authenticated organization",
         "tags": [
@@ -2062,6 +2173,11 @@
       },
       "post": {
         "operationId": "createIntegrationV2",
+        "x-epilot-permissions": [
+          {
+            "action": "integration:manage"
+          }
+        ],
         "summary": "createIntegrationV2",
         "description": "Create a new integration with embedded use cases.\n",
         "tags": [
@@ -2103,6 +2219,11 @@
     "/v2/integrations/{integrationId}": {
       "get": {
         "operationId": "getIntegrationV2",
+        "x-epilot-permissions": [
+          {
+            "action": "integration:view"
+          }
+        ],
         "summary": "getIntegrationV2",
         "description": "Retrieve a specific integration with all its embedded use cases",
         "tags": [
@@ -2144,6 +2265,11 @@
       },
       "put": {
         "operationId": "updateIntegrationV2",
+        "x-epilot-permissions": [
+          {
+            "action": "integration:manage"
+          }
+        ],
         "summary": "updateIntegrationV2",
         "description": "Update an existing integration with embedded use cases.\nThe integration must already exist.\nUse cases are updated declaratively:\n- Use cases in the request with matching IDs are updated\n- Use cases in the request without matching IDs are created\n- Existing use cases not in the request are deleted\n",
         "tags": [
@@ -2198,6 +2324,11 @@
       },
       "delete": {
         "operationId": "deleteIntegrationV2",
+        "x-epilot-permissions": [
+          {
+            "action": "integration:manage"
+          }
+        ],
         "summary": "deleteIntegrationV2",
         "description": "Delete an integration and all its use cases",
         "tags": [
@@ -2246,6 +2377,11 @@
     "/v2/integrations/{integrationId}/notifications/history": {
       "get": {
         "operationId": "listNotificationHistory",
+        "x-epilot-permissions": [
+          {
+            "action": "integration:view"
+          }
+        ],
         "summary": "listNotificationHistory",
         "description": "Returns the cursor-paginated, newest-first notification history for an\nintegration (every real notification decision — both fired and suppressed).\nRequires the `integration:view` permission on the integration's organization.\n",
         "tags": [
@@ -2329,6 +2465,11 @@
     "/v2/integrations/{integrationId}/notifications/test": {
       "post": {
         "operationId": "testSendNotification",
+        "x-epilot-permissions": [
+          {
+            "action": "integration:manage"
+          }
+        ],
         "summary": "testSendNotification",
         "description": "Renders and sends ONE representative notification of the requested kind/type to\nthe CALLING USER ONLY (never any other recipient), so an operator can preview how\na notification looks. A test send does NOT write to the notification history.\nRequires the `integration:manage` permission on the integration's organization.\n",
         "tags": [
@@ -2403,6 +2544,11 @@
     "/v2/integrations/{integrationId}/notifications/status": {
       "get": {
         "operationId": "getNotificationStatus",
+        "x-epilot-permissions": [
+          {
+            "action": "integration:view"
+          }
+        ],
         "summary": "getNotificationStatus",
         "description": "Returns the live per-rule alert state and (for 'auto' rules) the current\nhour-of-week baseline band for an integration's notification monitoring.\nReflects the latest 5-minute sweep — near-real-time, not live.\nRequires the `integration:view` permission on the integration's organization.\n",
         "tags": [
@@ -2469,6 +2615,7 @@
     "/v2/integrations/{integrationId}/use-cases/{useCaseId}/secure-proxy-whitelist": {
       "get": {
         "operationId": "getSecureProxyWhitelist",
+        "x-epilot-permissions": [],
         "summary": "getSecureProxyWhitelist",
         "description": "Returns the current allowed_domains, allowed_ips, and vpc_mode for a secure_proxy use case.\nStaff-only — gated by internal-auth issuer AND admin-portal Cognito user pool membership.\nRejects Login-As tokens.\n",
         "tags": [
@@ -2529,6 +2676,7 @@
       },
       "put": {
         "operationId": "updateSecureProxyWhitelist",
+        "x-epilot-permissions": [],
         "summary": "updateSecureProxyWhitelist",
         "description": "Replaces allowed_domains and/or allowed_ips on a secure_proxy use case.\nAt least one of the two fields is required. Validation mirrors the CLI's\n`validateDomainPatterns` / `validateCidrs`. Writes a USECASE_HISTORY row\nwith the admin user's email as `changed_by`.\n\nUpdate semantics per field:\n  - **omitted** — field is not modified; the stored value is preserved.\n  - **non-empty array** — the stored value is replaced with the supplied list.\n  - **empty array (`[]`)** — the list is cleared (stored as `[]`). This is\n    the canonical way to remove all entries. `null` is not accepted.\n\nStaff-only — same auth gates as GET.\n",
         "tags": [
@@ -2601,6 +2749,7 @@
     "/v2/integrations/{integrationId}/use-cases/{useCaseId}/secure-proxy-whitelist/history": {
       "get": {
         "operationId": "listSecureProxyWhitelistHistory",
+        "x-epilot-permissions": [],
         "summary": "listSecureProxyWhitelistHistory",
         "description": "Returns the most recent USECASE_HISTORY entries for a secure_proxy use case,\nin reverse chronological order (newest first). Each entry includes the\nactor email (`changed_by`), the ISO-8601 timestamp (`history_created_at`),\nthe `change_description` (free-text action), and the full `configuration`\nsnapshot — from which UI-08 computes a before/after diff between consecutive\nentries.\n\nStaff-only — gated by internal-auth issuer AND admin-portal Cognito user pool\nmembership. Rejects Login-As tokens (same auth gate as the GET / PUT\nsecure-proxy-whitelist operations).\n\nThin wrapper over the service-layer `listUseCaseHistory` that powers\n`GET /v1/integrations/{integrationId}/use-cases/{useCaseId}/history` — the\nseparate path exists because the /v1 variant is tenant-gated and admin-portal\ninternal-auth tokens do not carry tenant permissions.\n",
         "tags": [
@@ -2690,6 +2839,11 @@
     "/v1/integrations/{integrationId}/app-mapping": {
       "put": {
         "operationId": "setIntegrationAppMapping",
+        "x-epilot-permissions": [
+          {
+            "action": "integration:manage"
+          }
+        ],
         "summary": "setIntegrationAppMapping",
         "description": "Creates or updates a mapping from an app/component to an integration.\nThis allows ERP updates sent via app_id and component_id to be associated\nwith a specific integration configuration.\n",
         "tags": [
@@ -2754,6 +2908,11 @@
       },
       "delete": {
         "operationId": "deleteIntegrationAppMapping",
+        "x-epilot-permissions": [
+          {
+            "action": "integration:manage"
+          }
+        ],
         "summary": "deleteIntegrationAppMapping",
         "description": "Removes a mapping from an app/component to an integration.\n",
         "tags": [
@@ -2815,6 +2974,7 @@
     "/v1/integrations/{integrationId}/monitoring/inbound-events": {
       "post": {
         "operationId": "queryInboundMonitoringEvents",
+        "x-epilot-permissions": [],
         "summary": "queryInboundMonitoringEvents",
         "description": "Query inbound monitoring events for a specific integration.\nReturns detailed information about inbound sync events from ERP systems,\nincluding success rates, error breakdowns, and processing metrics.\n",
         "tags": [
@@ -2865,6 +3025,7 @@
     "/v1/integrations/{integrationId}/monitoring/stats": {
       "post": {
         "operationId": "getMonitoringStats",
+        "x-epilot-permissions": [],
         "summary": "getMonitoringStats",
         "description": "Get aggregated statistics for both inbound and outbound monitoring events for a specific integration.\nReturns summary metrics for inbound (ERP sync) and outbound (webhook delivery) events,\nincluding success/error counts and optional breakdowns.\n",
         "tags": [
@@ -2915,6 +3076,7 @@
     "/v1/integrations/{integrationId}/monitoring/timeseries": {
       "post": {
         "operationId": "getMonitoringTimeSeries",
+        "x-epilot-permissions": [],
         "summary": "getMonitoringTimeSeries",
         "description": "Get time-series aggregated event counts for monitoring charts.\nReturns pre-bucketed counts at configurable intervals for both inbound and outbound events.\nMaximum of 200 buckets per request. Returns 400 if the time range and interval would exceed this limit.\n",
         "tags": [
@@ -2965,6 +3127,7 @@
     "/v1/integrations/{integrationId}/outbound-status": {
       "get": {
         "operationId": "getOutboundStatus",
+        "x-epilot-permissions": [],
         "summary": "getOutboundStatus",
         "description": "Get the status of all outbound use cases for a specific integration.\nReturns conflict information when events or webhooks are disabled but the use case is enabled.\n",
         "tags": [
@@ -3008,6 +3171,7 @@
     "/v1/integrations/entities/{entityId}/sync-status": {
       "get": {
         "operationId": "getEntitySyncStatus",
+        "x-epilot-permissions": [],
         "summary": "getEntitySyncStatus",
         "description": "Get the inbound ERP sync status of an entity: when each integration last\nsynchronized (checked) the entity against the ERP, and when it last\nactually changed it. `last_synced_at` also advances on no-op checks —\nevents that were received and evaluated but changed nothing — which by\ndesign leave no trace on the entity itself (no activity feed entry, no\n`_updated_at` bump). Use it to tell whether an entity is up to date with\nthe ERP. Returns an empty list for entities no inbound use case has\nprocessed. Org-scoped via the caller's token.\n\nDeprecated alias: `GET /v1/entities/{entityId}/sync-status` is still\nserved (rewritten to this path in the API handler) but will be removed —\nmigrate callers to this path.\n",
         "tags": [
@@ -3061,8 +3225,14 @@
     "/v1/integrations/{integrationId}/outbound/messages/poll": {
       "post": {
         "operationId": "pollOutboundMessages",
+        "x-epilot-permissions": [
+          {
+            "action": "integration:consume",
+            "resource": "integration:{integrationId}"
+          }
+        ],
         "summary": "pollOutboundMessages",
-        "description": "Poll outbound messages for an integration's poll-mode use cases.\nTakes a lease on the head-of-line batch of the integration's FIFO stream:\nthe returned messages stay invisible to subsequent polls until they are\nacknowledged or the visibility timeout elapses. POST because taking a\nlease mutates server state — auto-retrying middleware must not burn\nleases. One in-flight batch per stream: while a lease is active (or\nanother poll wins the race), the response is an empty batch\n(`messages: []`), not an error. Requires the `integration:consume` grant.\n",
+        "description": "Poll outbound messages for an integration's poll-mode use cases.\nTakes a lease on the head-of-line batch of the integration's FIFO stream:\nthe returned messages stay invisible to subsequent polls until they are\nacknowledged or the visibility timeout elapses. POST because taking a\nlease mutates server state — auto-retrying middleware must not burn\nleases. One in-flight batch per stream: while a lease is active (or\nanother poll wins the race), the response is an empty batch\n(`messages: []`), not an error. Each message's `payload` is the\nuse case's JSONata transformation of the event when it has one\n(`mapping_version` identifies the transform), otherwise the raw\nevent. Requires the `integration:consume` grant.\n\nOrdering: messages are delivered in stream order, which follows the\nevent time. An event that arrives after the consumer was already handed\nevents with a later event time is not inserted behind them (it would\nnever be delivered); it is appended at the end of the stream and a\n`MSG_LATE_ARRIVAL` warning is recorded. Delivery is at-least-once: a\nmessage whose lease expires is delivered again, and in rare races the\nsame event can be delivered twice under different message ids, so\nconsumers should deduplicate by `event_id`.\n",
         "tags": [
           "integrations"
         ],
@@ -3125,6 +3295,12 @@
     "/v1/integrations/{integrationId}/outbound/messages/ack": {
       "post": {
         "operationId": "ackOutboundMessages",
+        "x-epilot-permissions": [
+          {
+            "action": "integration:consume",
+            "resource": "integration:{integrationId}"
+          }
+        ],
         "summary": "ackOutboundMessages",
         "description": "Acknowledge polled outbound messages. Acks are validated against the\nactive lease and committed as a prefix-contiguous cursor advance:\nmessages must be acknowledged in stream order. Out-of-order acks past\nthe first gap are rejected per id (`out_of_order`), acks with an\noutdated lease token are rejected (`stale_lease`), and unknown ids are\nrejected (`not_found`). Acknowledged messages are never delivered\nagain. Requires the `integration:consume` grant.\n",
         "tags": [
@@ -3189,6 +3365,12 @@
     "/v1/integrations/{integrationId}/outbound/messages/dlq": {
       "get": {
         "operationId": "listOutboundDlqMessages",
+        "x-epilot-permissions": [
+          {
+            "action": "integration:manage",
+            "resource": "integration:{integrationId}"
+          }
+        ],
         "summary": "listOutboundDlqMessages",
         "description": "List an integration's dead-lettered outbound queue messages\n(poison_policy enforcement and operator skips move messages here).\nOperator endpoint — requires the `integration:manage` grant. Message\npayloads are NOT included in listings: entries are keyed by the\nopaque message id and carry delivery metadata only. Paginated via an\nopaque `next_token`.\n",
         "tags": [
@@ -3264,8 +3446,14 @@
     "/v1/integrations/{integrationId}/outbound/messages/dlq/redrive": {
       "post": {
         "operationId": "redriveOutboundDlqMessages",
+        "x-epilot-permissions": [
+          {
+            "action": "integration:manage",
+            "resource": "integration:{integrationId}"
+          }
+        ],
         "summary": "redriveOutboundDlqMessages",
-        "description": "Redrive selected dead-lettered messages back into the live stream.\nOperator endpoint — requires the `integration:manage` grant.\nA redriven message is re-enqueued at the tail with a new id and\nsequence — it is delivered out of its original per-entity order (the\nstream has moved on); this is inherent to redrive and matches SQS DLQ\nsemantics. The redriven copy starts with zero delivery attempts and a\nfresh retention window; the original DLQ entry is removed. Per-id\nresults report `redriven` or `not_found` (unknown ids, or entries\nconcurrently redriven/expired).\n",
+        "description": "Redrive selected dead-lettered messages back into the live stream.\nOperator endpoint — requires the `integration:manage` grant.\nA redriven message is re-enqueued at the tail with a new id and\nsequence — it is delivered out of its original per-entity order (the\nstream has moved on); this is inherent to redrive and matches SQS DLQ\nsemantics. The redriven copy starts with zero delivery attempts and a\nfresh retention window; the original DLQ entry is removed.\nWith `reapply_mapping`, the raw event is re-mapped with the use case's\ncurrent `jsonata_expression`; entries whose mapping failed are always\nre-mapped. Per-id results report `redriven`, `not_found` (unknown ids,\nor entries concurrently redriven/expired) or `mapping_failed` (the\nre-mapping failed again and the entry stays in the DLQ).\n",
         "tags": [
           "integrations"
         ],
@@ -3328,8 +3516,14 @@
     "/v1/integrations/{integrationId}/outbound/messages/unblock": {
       "post": {
         "operationId": "unblockOutboundStream",
+        "x-epilot-permissions": [
+          {
+            "action": "integration:manage",
+            "resource": "integration:{integrationId}"
+          }
+        ],
         "summary": "unblockOutboundStream",
-        "description": "Unblock an integration's outbound stream halted by the `block`\npoison policy: skips (dead-letters) the current blocked head message,\nemitting MSG_DEAD_LETTERED and letting the next message become the\nhead. Operator endpoint — requires the `integration:manage` grant.\nReturns `unblocked: false` as a no-op when the stream is not\ncurrently blocked (or the state moved concurrently) — safe to retry.\n",
+        "description": "Unblock an integration's outbound stream halted by the `block`\npoison policy: skips (dead-letters) the current blocked head message,\nemitting MSG_DEAD_LETTERED and letting the next message become the\nhead. A head blocked because its `jsonata_expression` failed at\nenqueue is skipped the same way (its DLQ reason defaults to\n`mapping_failed`); fix the expression, then redrive the entry to\nre-map it. Operator endpoint — requires the `integration:manage` grant.\nReturns `unblocked: false` as a no-op when the stream is not\ncurrently blocked (or the state moved concurrently) — safe to retry.\n",
         "tags": [
           "integrations"
         ],
@@ -3389,9 +3583,80 @@
         }
       }
     },
+    "/v1/integrations/{integrationId}/outbound/mapping-simulation": {
+      "post": {
+        "operationId": "simulateOutboundMapping",
+        "x-epilot-permissions": [
+          {
+            "action": "integration:view",
+            "resource": "integration:{integrationId}"
+          }
+        ],
+        "summary": "simulateOutboundMapping",
+        "description": "Preview a poll delivery's `jsonata_expression` without saving or\nenqueueing anything. The expression is checked and evaluated exactly\nas at enqueue time: the same length, syntax and binding checks, the\nsame `$env`/`$mapValue`/`$mapKey` bindings resolved server-side from\nthe org's non-secret environment variables and key/value maps, the\nsame evaluation limits, and the same rule that the output must be a\nJSON object.\n\nProvide exactly one input: `payload` (an event to map as-is), or\n`event_id` (with `event_catalog_event`) to load a historical\nevent-catalog event and hydrate it exactly as enqueue does — the\npreview is then exact, and the hydrated event is echoed as `input`.\n\nMapping failures are a `200` with `valid: false` and an `error`;\n`4xx` is reserved for malformed requests. Requires the\n`integration:view` grant.\n",
+        "tags": [
+          "integrations"
+        ],
+        "security": [
+          {
+            "EpilotAuth": []
+          }
+        ],
+        "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/SimulateOutboundMappingRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Simulation outcome (mapping failures included)",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/SimulateOutboundMappingResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          },
+          "500": {
+            "$ref": "#/components/responses/InternalServerError"
+          }
+        }
+      }
+    },
     "/v1/integrations/{integrationId}/monitoring/access-logs": {
       "post": {
         "operationId": "queryAccessLogs",
+        "x-epilot-permissions": [],
         "summary": "queryAccessLogs",
         "description": "Query API access logs for a specific integration's organization.\nReturns access token usage analytics filtered by user_id (access token).\nSupports infinite scroll pagination with cursor-based navigation.\n",
         "tags": [
@@ -3442,6 +3707,7 @@
     "/v1/integrations/{integrationId}/monitoring/outbound-events": {
       "post": {
         "operationId": "queryOutboundMonitoringEvents",
+        "x-epilot-permissions": [],
         "summary": "queryOutboundMonitoringEvents",
         "description": "Query outbound monitoring events for a specific integration.\nReturns detailed information about outbound event deliveries,\nfiltered by event_name (event_catalog_event) linked to the integration's outbound use cases.\n",
         "tags": [
@@ -3492,6 +3758,7 @@
     "/v2/integrations/{integrationId}/monitoring/events": {
       "post": {
         "operationId": "queryMonitoringEventsV2",
+        "x-epilot-permissions": [],
         "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": [
@@ -3542,6 +3809,7 @@
     "/v2/integrations/{integrationId}/monitoring/stats": {
       "post": {
         "operationId": "getMonitoringStatsV2",
+        "x-epilot-permissions": [],
         "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": [
@@ -3592,6 +3860,7 @@
     "/v2/integrations/{integrationId}/monitoring/time-series": {
       "post": {
         "operationId": "getMonitoringTimeSeriesV2",
+        "x-epilot-permissions": [],
         "summary": "getMonitoringTimeSeriesV2",
         "description": "Get time-series aggregated event counts from the unified erp_monitoring_v2 table.\nReturns bucketed counts for chart rendering.\n",
         "tags": [
@@ -3642,6 +3911,7 @@
     "/v2/integrations/{integrationId}/monitoring/events/{eventId}/associated": {
       "get": {
         "operationId": "getAssociatedMonitoringEvents",
+        "x-epilot-permissions": [],
         "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": [
@@ -3688,6 +3958,11 @@
     "/v2/integrations/{integrationId}/monitoring/external-events": {
       "post": {
         "operationId": "ingestExternalMonitoringEvents",
+        "x-epilot-permissions": [
+          {
+            "action": "integration:manage"
+          }
+        ],
         "summary": "ingestExternalMonitoringEvents",
         "description": "Ingest monitoring spans produced by an EXTERNAL system (e.g. an integration\nmiddleware), so the Integration Hub is the central monitoring point and the\ncross-system event trace spans both the external system and epilot's own\nprocessing.\n\nEach span is validated, assigned a server-controlled `EXTERNAL_*` taxonomy code\nderived from its `level` (the client never supplies a code — this marks\nprovenance and prevents spoofing an epilot code), has its `use_case_slug`\nresolved against the integration's configured use cases, and is republished onto\nthe same monitoring event bus as epilot's own spans — so external spans are\nfirst-class to the trace view, stats, alerting and digests.\n\nSpans link to the epilot trace via `correlation_id` (the trace id): the middleware\nmust stamp the same `correlation_id` here and on the event it forwards to the\ninbound endpoint. Invalid spans in a batch are reported per-item and do not fail\nthe whole batch.\n",
         "tags": [
@@ -3748,6 +4023,11 @@
     "/v2/integrations/{integrationId}/monitoring/traces/{correlationId}": {
       "get": {
         "operationId": "getMonitoringTraceByCorrelation",
+        "x-epilot-permissions": [
+          {
+            "action": "integration:view"
+          }
+        ],
         "summary": "getMonitoringTraceByCorrelation",
         "description": "Returns the cross-system event trace for a `correlation_id`: every monitoring\nspan sharing it — external spans (middleware) plus epilot's own processing spans\n— ordered chronologically, with a rolled-up status and the epilot inbound event\n\"head\" attached. This is the correlation-grouped counterpart to\n`…/events/{eventId}/associated` (which groups a single epilot event's fan-out by\nevent_id). Origin is distinguished by the `EXTERNAL_*` code prefix on external\nspans. Freshness is near-real-time (spans land as they are produced/ingested).\n",
         "tags": [
@@ -3804,6 +4084,11 @@
     "/v1/integrations/secure-proxies": {
       "get": {
         "operationId": "listSecureProxies",
+        "x-epilot-permissions": [
+          {
+            "action": "integration:view"
+          }
+        ],
         "summary": "listSecureProxies",
         "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": [
@@ -3848,6 +4133,11 @@
     "/v1/secure-proxy": {
       "post": {
         "operationId": "secureProxy",
+        "x-epilot-permissions": [
+          {
+            "action": "integration:manage"
+          }
+        ],
         "summary": "secureProxy",
         "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": [
@@ -3931,6 +4221,11 @@
     "/v1/managed-call/{slug}/execute": {
       "post": {
         "operationId": "managedCallExecute",
+        "x-epilot-permissions": [
+          {
+            "action": "integration:manage"
+          }
+        ],
         "summary": "managedCallExecute",
         "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": [
@@ -4020,6 +4315,11 @@
     "/v1/integrations/{integrationId}/generate-types-preview": {
       "post": {
         "operationId": "generateTypesPreview",
+        "x-epilot-permissions": [
+          {
+            "action": "integration:manage"
+          }
+        ],
         "summary": "generateTypesPreview",
         "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": [
@@ -4070,6 +4370,11 @@
     "/v1/integrations/{integrationId}/generate-types": {
       "post": {
         "operationId": "generateTypes",
+        "x-epilot-permissions": [
+          {
+            "action": "integration:manage"
+          }
+        ],
         "summary": "generateTypes",
         "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": [
@@ -4130,6 +4435,11 @@
     "/v1/integrations/{integrationId}/commit-types": {
       "post": {
         "operationId": "commitTypes",
+        "x-epilot-permissions": [
+          {
+            "action": "integration:manage"
+          }
+        ],
         "summary": "commitTypes",
         "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": [
@@ -4190,6 +4500,11 @@
     "/v2/erp/imports": {
       "post": {
         "operationId": "createErpImport",
+        "x-epilot-permissions": [
+          {
+            "action": "integration:manage"
+          }
+        ],
         "summary": "createErpImport",
         "description": "Register an already-uploaded file (S3 ref) as a pricing-file import job. Returns the job and a file preview. Nothing runs yet: no use case is chosen and no validation starts here. Optionally rank candidates with POST /v2/erp/imports/{importId}:suggest-use-cases, then start validation with POST /v2/erp/imports/{importId}:validate.\nPass `import_id` to repoint an existing import at a different file instead, keeping its id and its place in the history — allowed while the import has written nothing.",
         "tags": [
@@ -4253,6 +4568,11 @@
       },
       "get": {
         "operationId": "listErpImports",
+        "x-epilot-permissions": [
+          {
+            "action": "integration:manage"
+          }
+        ],
         "summary": "listErpImports",
         "description": "List recent pricing-file import jobs for the org, newest first.\n\nPass `next_cursor` back as `cursor` for the next page. A page can be\nshorter than `limit` and still have more behind it, so stop on\n`next_cursor: null`.\n",
         "tags": [
@@ -4306,6 +4626,11 @@
     "/v2/erp/imports/{importId}": {
       "get": {
         "operationId": "getErpImport",
+        "x-epilot-permissions": [
+          {
+            "action": "integration:manage"
+          }
+        ],
         "summary": "getErpImport",
         "description": "Get a pricing-file import job (status, counts, result links).",
         "tags": [
@@ -4345,6 +4670,11 @@
       },
       "delete": {
         "operationId": "deleteErpImport",
+        "x-epilot-permissions": [
+          {
+            "action": "integration:manage"
+          }
+        ],
         "summary": "deleteErpImport",
         "description": "Remove an import and the file it owns. Allowed from any status: an import whose run is still in flight is stopped by the deletion, and rows it already wrote stay written.",
         "tags": [
@@ -4379,6 +4709,11 @@
     "/v2/erp/imports/{importId}:validate": {
       "post": {
         "operationId": "validateErpImport",
+        "x-epilot-permissions": [
+          {
+            "action": "integration:manage"
+          }
+        ],
         "summary": "validateErpImport",
         "description": "Choose the use case to read this file with, and start the validate phase.\nCallable from PENDING, READY and FAILED — so a wrong choice is corrected by calling this again with a different use case, rather than re-uploading. Each call replaces any previous verdict. Any other status returns 409.",
         "tags": [
@@ -4443,6 +4778,11 @@
     "/v2/erp/imports/{importId}:suggest-use-cases": {
       "post": {
         "operationId": "suggestErpImportUseCases",
+        "x-epilot-permissions": [
+          {
+            "action": "integration:manage"
+          }
+        ],
         "summary": "suggestErpImportUseCases",
         "description": "Rank the org's inbound use cases against this file's columns — the input to the ranked picker (\"matches 6 of your 7 columns\"). Optional: skip this and call `:validate` directly when the use case is already known. Reads only the file's first row, not its data.\nEvery eligible use case is returned, including ones matching nothing: the \"nothing fits, pick anyway\" view needs the full list. Highest match first.\nCSV only — an xlsx import fails with 400 rather than silently returning zero matches, which would look identical to \"we checked and nothing matches\".",
         "tags": [
@@ -4487,6 +4827,11 @@
     "/v2/erp/imports/{importId}:execute": {
       "post": {
         "operationId": "executeErpImport",
+        "x-epilot-permissions": [
+          {
+            "action": "integration:manage"
+          }
+        ],
         "summary": "executeErpImport",
         "description": "Confirm and run the write phase of a validated import. Only a READY job may be executed; any other status returns 409.\nThe verdict is re-checked against live inputs first: if the mapping or an entity schema changed since the check, this returns 409 `VALIDATION_STALE` and leaves the verdict untouched for `:validate` to re-form.",
         "tags": [
@@ -4558,6 +4903,11 @@
     "/v2/erp/imports/{importId}:abort": {
       "post": {
         "operationId": "abortErpImport",
+        "x-epilot-permissions": [
+          {
+            "action": "integration:manage"
+          }
+        ],
         "summary": "abortErpImport",
         "description": "Ask a running import to stop. Valid while the job is VALIDATING or PROCESSING; any other status returns 409.\nThe stop is cooperative: the job passes through CANCELLING and typically reaches CANCELLED within seconds.\nRows already published to the platform are **kept**: this is a stop, not a rollback. Aborting during VALIDATING has published nothing, so it is always clean; aborting during PROCESSING leaves a partial import, and the rows that landed are visible in monitoring under the job's correlation_id.",
         "tags": [
@@ -10057,7 +10407,7 @@
           "enabled",
           "delivery"
         ],
-        "description": "A mapping that delivers an event to an external system by one of three mechanisms — pushed to a webhook (with a JSONata payload transformation), made available on the pull-based poll queue (raw event payload, no transformation), or handed to a file_proxy use case that uploads files to an external document system (a pointer only; the referenced use case owns the payload and the fan-out)",
+        "description": "A mapping that delivers an event to an external system by one of three mechanisms — pushed to a webhook (with a JSONata payload transformation), made available on the pull-based poll queue (the raw event payload, or its JSONata transformation when the mapping carries one), or handed to a file_proxy use case that uploads files to an external document system (a pointer only; the referenced use case owns the payload and the fan-out)",
         "properties": {
           "id": {
             "type": "string",
@@ -10071,7 +10421,7 @@
           },
           "jsonata_expression": {
             "type": "string",
-            "description": "JSONata expression to transform the event payload. Required for webhook delivery, ignored for poll delivery, and rejected for file_proxy delivery — a file_proxy payload is built by the referenced use case's steps, so accepting an expression here would silently do nothing.",
+            "description": "JSONata expression transforming the event payload. Required for webhook delivery (evaluated by the webhook service). Optional for poll delivery: evaluated at enqueue time against the standardized event-catalog event with `$env`/`$mapValue`/`$mapKey` bindings; must return a JSON object; empty = raw event payload is delivered. Rejected for file_proxy delivery.",
             "example": "{ \"id\": entity._id, \"customer\": entity.customer_name }"
           },
           "enabled": {
@@ -10095,7 +10445,7 @@
         }
       },
       "DeliveryConfig": {
-        "description": "Configuration for how the event should be delivered. webhook = push delivery via svc-webhooks (JSONata-transformed payload); poll = pull-based queue delivery where the consumer fetches items via the poll API (raw event payload); file_proxy = one push per event attachment to an external document system, through a file_proxy use case (JSONata-transformed payload carrying the file bytes)",
+        "description": "Configuration for how the event should be delivered. webhook = push delivery via svc-webhooks (JSONata-transformed payload); poll = pull-based queue delivery where the consumer fetches items via the poll API (raw event payload, or its JSONata transformation when the mapping carries a jsonata_expression); file_proxy = one push per event attachment to an external document system, through a file_proxy use case (JSONata-transformed payload carrying the file bytes)",
         "oneOf": [
           {
             "$ref": "#/components/schemas/WebhookDeliveryConfig"
@@ -10150,7 +10500,7 @@
         "required": [
           "type"
         ],
-        "description": "Pull-based queue delivery. Items carry the raw standardized event-catalog payload; no JSONata mapping is applied in poll mode. Consumers fetch and acknowledge items via the poll API.",
+        "description": "Pull-based queue delivery. Consumers fetch and acknowledge items via the poll API. When the mapping carries a `jsonata_expression`, it is evaluated once at enqueue time against the standardized event-catalog event (with `$env`/`$mapValue`/`$mapKey` bindings) and its output — a JSON object — is the delivered payload; without one, items carry the raw standardized event-catalog payload. An item whose expression fails at enqueue is never delivered: when it reaches the head of the stream the poison_policy applies to it at once, without waiting for max_delivery_attempts.",
         "properties": {
           "type": {
             "type": "string",
@@ -10173,7 +10523,7 @@
               "block"
             ],
             "default": "dead_letter",
-            "description": "What happens when an item exhausts max_delivery_attempts: dead_letter routes the exhausted item to the dead-letter queue and advances past it so the stream keeps flowing; block halts the queue at that item until operator/consumer action removes it."
+            "description": "What happens when an item exhausts max_delivery_attempts, or its jsonata_expression failed at enqueue: dead_letter routes the item to the dead-letter queue and advances past it so the stream keeps flowing; block halts the queue at that item until operator/consumer action removes it."
           },
           "max_delivery_attempts": {
             "type": "integer",
@@ -10568,10 +10918,19 @@
             "type": "string",
             "description": "Ordering group — messages sharing a group are strictly ordered,\ndistinct groups are independent. Constant \"0\" in v1.\n"
           },
+          "org_id": {
+            "type": "string",
+            "description": "The epilot org the message belongs to. Always populated — lets one\nconsumer that polls many orgs attribute every message.\n"
+          },
           "payload": {
             "type": "object",
             "additionalProperties": true,
-            "description": "The raw standardized event-catalog event, always inlined as-is"
+            "description": "The mapped output when the use case has a `jsonata_expression`,\notherwise the raw standardized event-catalog event. Always inlined.\n"
+          },
+          "mapping_version": {
+            "type": "string",
+            "description": "Version of the transform that produced the payload — the first 16\nhex characters of sha256 over the trimmed expression. Absent for\nraw payloads.\n",
+            "example": "3f2a9c1b7d4e8f60"
           },
           "enqueued_at": {
             "type": "string",
@@ -10723,7 +11082,15 @@
           },
           "reason": {
             "type": "string",
-            "description": "Why the message was dead-lettered (policy or operator reason)"
+            "description": "Why the message was dead-lettered (policy or operator reason) —\n`max_delivery_attempts_exhausted`, `mapping_failed`, or the\noperator's own reason\n"
+          },
+          "mapping_error": {
+            "type": "string",
+            "description": "Why the message's transform failed, prefixed with the error code\n(e.g. `invalid_output: ...`). Present on entries whose mapping\nfailed — at enqueue, or again on a re-mapping redrive.\n"
+          },
+          "mapping_version": {
+            "type": "string",
+            "description": "Version of the transform that produced (or failed to produce) the payload"
           },
           "expires_at": {
             "type": "string",
@@ -10766,6 +11133,11 @@
               "type": "string"
             },
             "description": "Message ids (msg_…) of the DLQ entries to redrive"
+          },
+          "reapply_mapping": {
+            "type": "boolean",
+            "default": false,
+            "description": "Re-apply the use case's CURRENT `jsonata_expression` to the raw\nevent instead of re-sending the stored payload. Entries whose\nmapping failed are always re-mapped, whatever this says. When the\nuse case no longer has an expression, the raw event is redriven.\n"
           }
         }
       },
@@ -10784,9 +11156,14 @@
             "type": "string",
             "enum": [
               "redriven",
-              "not_found"
+              "not_found",
+              "mapping_failed"
             ],
-            "description": "Outcome — `redriven` re-enqueued at the tail; `not_found` for\nunknown ids or entries concurrently redriven/expired\n"
+            "description": "Outcome — `redriven` re-enqueued at the tail; `not_found` for\nunknown ids or entries concurrently redriven/expired;\n`mapping_failed` when re-mapping failed again (the entry stays in\nthe DLQ with the updated mapping_error and mapping_version)\n"
+          },
+          "mapping_error": {
+            "type": "string",
+            "description": "Why re-mapping failed — present only when status is mapping_failed"
           }
         }
       },
@@ -10832,6 +11209,96 @@
           }
         }
       },
+      "SimulateOutboundMappingRequest": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "jsonata_expression"
+        ],
+        "description": "Exactly one of `payload` or `event_id` is required. `event_id` needs\n`event_catalog_event` to name the event it belongs to.\n",
+        "properties": {
+          "jsonata_expression": {
+            "type": "string",
+            "minLength": 1,
+            "description": "The poll mapping expression to preview",
+            "example": "{ \"contract_number\": contract.contract_number, \"status\": $mapValue($env.erp.statuses, contract.status) }"
+          },
+          "payload": {
+            "type": "object",
+            "additionalProperties": true,
+            "description": "A standardized event-catalog event to map as-is"
+          },
+          "event_id": {
+            "type": "string",
+            "description": "Id of a historical event-catalog event to load, hydrate and map"
+          },
+          "event_catalog_event": {
+            "type": "string",
+            "description": "Event-catalog event name of `event_id` (required with `event_id`)",
+            "example": "contract.updated"
+          }
+        }
+      },
+      "OutboundMappingSimulationError": {
+        "type": "object",
+        "required": [
+          "code",
+          "message"
+        ],
+        "properties": {
+          "code": {
+            "type": "string",
+            "enum": [
+              "syntax_error",
+              "unknown_binding",
+              "evaluation_error",
+              "timeout",
+              "invalid_output",
+              "expression_too_long"
+            ],
+            "description": "`syntax_error` — the expression does not parse; `unknown_binding` —\nit reads a `$` name that is never bound; `evaluation_error` — it\nfailed while evaluating; `timeout` — it exceeded the evaluation\ntime or depth limit; `invalid_output` — it did not return a JSON\nobject; `expression_too_long` — it exceeds 10,000 characters\n"
+          },
+          "message": {
+            "type": "string",
+            "description": "Human-readable explanation"
+          },
+          "position": {
+            "type": "integer",
+            "description": "Character position of the failure in the expression, when known"
+          }
+        }
+      },
+      "SimulateOutboundMappingResponse": {
+        "type": "object",
+        "required": [
+          "valid",
+          "mapping_version"
+        ],
+        "properties": {
+          "valid": {
+            "type": "boolean",
+            "description": "Whether the expression produced a deliverable payload"
+          },
+          "output": {
+            "type": "object",
+            "additionalProperties": true,
+            "description": "The payload a consumer would receive — present when valid"
+          },
+          "error": {
+            "$ref": "#/components/schemas/OutboundMappingSimulationError"
+          },
+          "mapping_version": {
+            "type": "string",
+            "description": "The `mapping_version` messages mapped by this expression carry",
+            "example": "3f2a9c1b7d4e8f60"
+          },
+          "input": {
+            "type": "object",
+            "additionalProperties": true,
+            "description": "The hydrated event the expression ran against — present when `event_id` was used"
+          }
+        }
+      },
       "RelationConfig": {
         "type": "object",
         "required": [
@@ -12113,6 +12580,7 @@
           "MSG_ENQUEUED",
           "MSG_EXPIRED_UNPOLLED",
           "MSG_HEAD_BLOCKED",
+          "MSG_LATE_ARRIVAL",
           "OAUTH2_TOKEN_FAILURE",
           "PAYLOAD_TOO_LARGE",
           "PRUNE_SCOPE_COMPLETED",
@@ -12941,6 +13409,55 @@
           }
         }
       },
+      "ERPUpdatesRetryableResponse": {
+        "description": "Some events could not be processed right now but will succeed on a retry: their\ndeduplication check was throttled, or another request carrying the same\ndeduplication_id is still being processed. Those events have status `error`.\nRetry the whole request after the `Retry-After` interval: events that were\naccepted by this request are recorded and come back as `skipped` on the retry.\n",
+        "headers": {
+          "Retry-After": {
+            "description": "Seconds to wait before retrying the request",
+            "schema": {
+              "type": "integer"
+            }
+          }
+        },
+        "content": {
+          "application/json": {
+            "schema": {
+              "type": "object",
+              "properties": {
+                "results": {
+                  "type": "array",
+                  "items": {
+                    "type": "object",
+                    "required": [
+                      "event_id",
+                      "status"
+                    ],
+                    "properties": {
+                      "event_id": {
+                        "type": "string",
+                        "description": "ID of the processed event"
+                      },
+                      "status": {
+                        "type": "string",
+                        "enum": [
+                          "success",
+                          "error",
+                          "skipped",
+                          "ignored"
+                        ],
+                        "description": "Processing status for the event (skipped indicates duplicate deduplication_id, ignored indicates unconfigured event)"
+                      },
+                      "message": {
+                        "type": "string"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      },
       "TriggerWebhookResponse": {
         "description": "Result of triggering an ERP synchronization event",
         "content": {