@epilot/sdk 2.19.3 → 2.19.4

package/definitions/targeting.json

@@ -0,0 +1,2222 @@
+{
+  "openapi": "3.0.3",
+  "info": {
+    "title": "Targeting API",
+    "description": "API for Targeting",
+    "version": "1.1.0"
+  },
+  "tags": [
+    {
+      "name": "Campaign",
+      "description": "Campaign Endpoints"
+    },
+    {
+      "name": "Campaign Recipient",
+      "description": "Campaign Recipient Endpoints"
+    },
+    {
+      "name": "Campaign Delivery",
+      "description": "Campaign Delivery Endpoints"
+    },
+    {
+      "name": "Target",
+      "description": "Target Endpoints"
+    }
+  ],
+  "security": [
+    {
+      "EpilotAuth": []
+    }
+  ],
+  "servers": [
+    {
+      "url": "https://targeting.sls.epilot.io"
+    }
+  ],
+  "paths": {
+    "/v1/campaign/{campaign_id}/status": {
+      "post": {
+        "operationId": "changeCampaignStatus",
+        "summary": "changeCampaignStatus",
+        "description": "Change the status of a campaign to a desired status.\n\nThe status can be one of the following: active, inactive.\n\nStatus transition is accompanied by side effects, e.g., automation execution.\n",
+        "tags": [
+          "Campaign"
+        ],
+        "security": [
+          {
+            "EpilotAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/CampaignIdPathParam"
+          }
+        ],
+        "responses": {
+          "200": {
+            "$ref": "#/components/responses/CampaignResponse"
+          },
+          "400": {
+            "$ref": "#/components/responses/ClientErrorResponse"
+          },
+          "500": {
+            "$ref": "#/components/responses/ServerErrorResponse"
+          }
+        }
+      }
+    },
+    "/v1/campaign/{campaign_id}/job": {
+      "get": {
+        "operationId": "getCampaignJobStatus",
+        "description": "Get the status of a campaign's automation job",
+        "summary": "getCampaignJobStatus",
+        "tags": [
+          "Campaign"
+        ],
+        "security": [
+          {
+            "EpilotAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/CampaignIdPathParam"
+          }
+        ],
+        "responses": {
+          "200": {
+            "$ref": "#/components/responses/JobStatusResponse"
+          },
+          "400": {
+            "$ref": "#/components/responses/ClientErrorResponse"
+          },
+          "500": {
+            "$ref": "#/components/responses/ServerErrorResponse"
+          }
+        }
+      }
+    },
+    "/v1/campaign/{campaign_id}/portals": {
+      "get": {
+        "operationId": "getCampaignPortals",
+        "summary": "getCampaignPortals",
+        "description": "Get the list of portals and its widgets where the campaign is used.\n",
+        "tags": [
+          "Campaign"
+        ],
+        "security": [
+          {
+            "EpilotAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/CampaignIdPathParam"
+          }
+        ],
+        "responses": {
+          "200": {
+            "$ref": "#/components/responses/CampaignPortalsResponse"
+          },
+          "400": {
+            "$ref": "#/components/responses/ClientErrorResponse"
+          },
+          "500": {
+            "$ref": "#/components/responses/ServerErrorResponse"
+          }
+        }
+      }
+    },
+    "/v1/campaign/{campaign_id}/automations:retrigger": {
+      "post": {
+        "operationId": "retriggerCampaignAutomations",
+        "summary": "retriggerCampaignAutomations",
+        "description": "Retrigger automation executions for specific campaign recipients that have failed.\n\nThis endpoint starts new automation executions for the specified recipients\nusing the campaign's associated automation flow. Only recipients with\nautomation_status 'failed' will be processed. Recipients with other statuses\n(success, pending, in_progress, cancelled) will be skipped to prevent\naccidentally retriggering successful or ongoing automations.\n",
+        "tags": [
+          "Campaign Delivery"
+        ],
+        "security": [
+          {
+            "EpilotAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/CampaignIdPathParam"
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/RetriggerAutomationsRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "$ref": "#/components/responses/RetriggerAutomationsResponse"
+          },
+          "400": {
+            "$ref": "#/components/responses/ClientErrorResponse"
+          },
+          "404": {
+            "$ref": "#/components/responses/ServerErrorResponse"
+          },
+          "500": {
+            "$ref": "#/components/responses/ServerErrorResponse"
+          }
+        }
+      }
+    },
+    "/v1/campaign:setup": {
+      "post": {
+        "operationId": "setupCampaign",
+        "summary": "setupCampaign",
+        "description": "Creates a `campaign` entity together with its related entities and configurations in a single call.\nUsed by the campaign wizard UI, but not restricted to it.\n",
+        "tags": [
+          "Campaign"
+        ],
+        "security": [
+          {
+            "EpilotAuth": []
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/SetupCampaignRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "201": {
+            "$ref": "#/components/responses/SetupCampaignResponse"
+          },
+          "400": {
+            "$ref": "#/components/responses/ClientErrorResponse"
+          },
+          "500": {
+            "$ref": "#/components/responses/ServerErrorResponse"
+          }
+        }
+      }
+    },
+    "/v1/campaign:match": {
+      "post": {
+        "operationId": "matchCampaigns",
+        "summary": "matchCampaigns",
+        "description": "Match campaigns based on target entities.\n\nThis endpoint returns the list of campaigns where the provided entities are part of the target.\n",
+        "tags": [
+          "Campaign"
+        ],
+        "security": [
+          {
+            "EpilotAuth": []
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/MatchCampaignParams"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "$ref": "#/components/responses/MatchCampaignsResponse"
+          },
+          "400": {
+            "$ref": "#/components/responses/ClientErrorResponse"
+          },
+          "500": {
+            "$ref": "#/components/responses/ServerErrorResponse"
+          }
+        }
+      }
+    },
+    "/v1/campaign:discover": {
+      "post": {
+        "operationId": "discoverCampaigns",
+        "summary": "discoverCampaigns",
+        "description": "Given an entity, returns the Next Best Actions it should see on the Entity-UI channel.\n\nEnumerates the organization's **active** campaigns that carry a valid Entity-UI Next Best\nAction, live-matches each against the entity using the existing match engine, and returns\nthe matching NBAs priority-sorted (one per campaign).\n\nThis is a pure read: it writes nothing. An entity that matches no campaigns returns an\nempty list, not an error.\n",
+        "tags": [
+          "Campaign"
+        ],
+        "security": [
+          {
+            "EpilotAuth": []
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/DiscoverCampaignsParams"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "$ref": "#/components/responses/DiscoverCampaignsResponse"
+          },
+          "400": {
+            "$ref": "#/components/responses/ClientErrorResponse"
+          },
+          "500": {
+            "$ref": "#/components/responses/ServerErrorResponse"
+          }
+        }
+      }
+    },
+    "/v1/target:match": {
+      "post": {
+        "operationId": "matchTargets",
+        "summary": "matchTargets",
+        "description": "Find targets from the provided list that include the provide entities.\n",
+        "tags": [
+          "Target"
+        ],
+        "security": [
+          {
+            "EpilotAuth": []
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/MatchTargetParams"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "$ref": "#/components/responses/MatchTargetsResponse"
+          },
+          "400": {
+            "$ref": "#/components/responses/ClientErrorResponse"
+          },
+          "500": {
+            "$ref": "#/components/responses/ServerErrorResponse"
+          }
+        }
+      }
+    },
+    "/v1/target/queries": {
+      "post": {
+        "operationId": "getTargetQueries",
+        "summary": "getTargetQueries",
+        "description": "Transform target filters into Lucene queries for the provided target IDs.\nReturns the transformed query string for each target along with any errors encountered.\n",
+        "tags": [
+          "Target"
+        ],
+        "security": [
+          {
+            "EpilotAuth": []
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/GetTargetQueriesParams"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "$ref": "#/components/responses/GetTargetQueriesResponse"
+          },
+          "400": {
+            "$ref": "#/components/responses/ClientErrorResponse"
+          },
+          "500": {
+            "$ref": "#/components/responses/ServerErrorResponse"
+          }
+        }
+      }
+    },
+    "/v1/campaign/{campaign_id}/recipient": {
+      "post": {
+        "operationId": "createRecipient",
+        "summary": "createRecipient",
+        "description": "Creates a new recipient associated with a campaign.",
+        "tags": [
+          "Campaign Recipient"
+        ],
+        "security": [
+          {
+            "EpilotAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/CampaignIdPathParam"
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CreateRecipientPayload"
+              }
+            }
+          }
+        },
+        "responses": {
+          "201": {
+            "$ref": "#/components/responses/RecipientResponse"
+          },
+          "400": {
+            "$ref": "#/components/responses/ClientErrorResponse"
+          },
+          "500": {
+            "$ref": "#/components/responses/ServerErrorResponse"
+          }
+        }
+      }
+    },
+    "/v1/campaign/{campaign_id}/recipient/{recipient_id}": {
+      "patch": {
+        "operationId": "updateRecipient",
+        "summary": "updateRecipient",
+        "description": "Updates a recipient's attributes.",
+        "tags": [
+          "Campaign Recipient"
+        ],
+        "security": [
+          {
+            "EpilotAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/CampaignIdPathParam"
+          },
+          {
+            "$ref": "#/components/parameters/RecipientIdPathParam"
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/UpdateRecipientPayload"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "$ref": "#/components/responses/RecipientResponse"
+          },
+          "400": {
+            "$ref": "#/components/responses/ClientErrorResponse"
+          },
+          "500": {
+            "$ref": "#/components/responses/ServerErrorResponse"
+          }
+        }
+      }
+    },
+    "/v1/campaign/{campaign_id}/recipient/{recipient_id}/portal:status": {
+      "patch": {
+        "operationId": "updateRecipientPortalStatus",
+        "summary": "updateRecipientPortalStatus",
+        "description": "Updates the portal status for a specific campaign recipient.\nThe portal_status_updated_at timestamp is automatically set when the status changes.\n\nStatus transition rules:\n- From 'sent': can change to 'seen', 'dismissed', or 'clicked'\n- From 'seen': can change to 'dismissed' or 'clicked'\n- From 'dismissed' or 'clicked': cannot be changed (final states)\n",
+        "tags": [
+          "Campaign Recipient"
+        ],
+        "security": [
+          {
+            "EpilotAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/CampaignIdPathParam"
+          },
+          {
+            "$ref": "#/components/parameters/RecipientIdPathParam"
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/UpdatePortalStatusRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "$ref": "#/components/responses/RecipientResponse"
+          },
+          "400": {
+            "$ref": "#/components/responses/ClientErrorResponse"
+          },
+          "404": {
+            "$ref": "#/components/responses/ClientErrorResponse"
+          },
+          "409": {
+            "$ref": "#/components/responses/ClientErrorResponse"
+          },
+          "500": {
+            "$ref": "#/components/responses/ServerErrorResponse"
+          }
+        }
+      }
+    },
+    "/v1/campaign/{campaign_id}/recipient/{recipient_id}/entity_ui:status": {
+      "patch": {
+        "operationId": "updateRecipientEntityUiStatus",
+        "summary": "updateRecipientEntityUiStatus",
+        "description": "Records a Next Best Action interaction for a recipient on the Entity-UI channel.\n\nUnlike the portal channel, an NBA recipient is created lazily: the first `seen` creates\nthe recipient record (and requires `entity_schema`). `seen` is idempotent — re-viewing an\nNBA that is already seen/clicked/dismissed is a no-op success and never regresses the status.\n\nStatus transition rules:\n- `seen`: lazily creates the recipient; a no-op success if a status already exists\n- From `seen`: can change to `clicked` or `dismissed`\n- From `clicked`: can change to `dismissed`\n- From `dismissed`: cannot be changed via this operation — use `entity_ui:restore`\n\n`dismissed` and `clicked` require an existing recipient (404 otherwise, since an NBA is\nborn at `seen`) and reject invalid transitions (409).\n\nThe entity_ui_status_updated_at timestamp is automatically set when the status changes.\n",
+        "tags": [
+          "Campaign Recipient"
+        ],
+        "security": [
+          {
+            "EpilotAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/CampaignIdPathParam"
+          },
+          {
+            "$ref": "#/components/parameters/RecipientIdPathParam"
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/UpdateEntityUiStatusRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "$ref": "#/components/responses/RecipientResponse"
+          },
+          "400": {
+            "$ref": "#/components/responses/ClientErrorResponse"
+          },
+          "404": {
+            "$ref": "#/components/responses/ClientErrorResponse"
+          },
+          "409": {
+            "$ref": "#/components/responses/ClientErrorResponse"
+          },
+          "500": {
+            "$ref": "#/components/responses/ServerErrorResponse"
+          }
+        }
+      }
+    },
+    "/v1/campaign/{campaign_id}/recipient/{recipient_id}/entity_ui:restore": {
+      "post": {
+        "operationId": "restoreRecipientEntityUiStatus",
+        "summary": "Undo a dismissal on the Entity-UI (Next Best Action) channel",
+        "description": "Reverses a dismissal so the Next Best Action becomes visible to the entity again. This is\nthe only way out of `dismissed` — `entity_ui:status` cannot leave that state.\n\nThe recipient's status is restored to whatever it was immediately before the dismissal\n(recorded in `entity_ui_status_before_dismiss`), so a `clicked` NBA that was dismissed\nreturns to `clicked` and does not lose its recorded click. Falls back to `seen` when no\nprevious status was recorded.\n\nScoped to the Entity-UI channel only: the recipient's portal and automation state is never\ntouched. Takes no request body — the recipient's current state fully determines the result.\n\nReturns 404 when the recipient has no Entity-UI status at all, and 409 when it has one but\nis not currently `dismissed` (there is nothing to undo).\n",
+        "tags": [
+          "Campaign Recipient"
+        ],
+        "security": [
+          {
+            "EpilotAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/CampaignIdPathParam"
+          },
+          {
+            "$ref": "#/components/parameters/RecipientIdPathParam"
+          }
+        ],
+        "responses": {
+          "200": {
+            "$ref": "#/components/responses/RecipientResponse"
+          },
+          "404": {
+            "$ref": "#/components/responses/ClientErrorResponse"
+          },
+          "409": {
+            "$ref": "#/components/responses/ClientErrorResponse"
+          },
+          "500": {
+            "$ref": "#/components/responses/ServerErrorResponse"
+          }
+        }
+      }
+    },
+    "/v1/campaign/{campaign_id}/recipients": {
+      "get": {
+        "operationId": "getRecipients",
+        "summary": "getRecipients",
+        "description": "Get a paginated list of recipients for a campaign.",
+        "tags": [
+          "Campaign Recipient"
+        ],
+        "security": [
+          {
+            "EpilotAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/CampaignIdPathParam"
+          },
+          {
+            "name": "limit",
+            "in": "query",
+            "description": "Number of items to return",
+            "schema": {
+              "type": "integer",
+              "default": 25
+            }
+          },
+          {
+            "name": "next",
+            "in": "query",
+            "description": "Cursor for pagination",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "q",
+            "in": "query",
+            "description": "Search by recipient title",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "automation_status",
+            "in": "query",
+            "description": "Filter by automation status. Repeat the parameter to match multiple\nstatuses in one request\n(e.g. automation_status=failed&automation_status=cancelled).\n",
+            "style": "form",
+            "explode": true,
+            "schema": {
+              "type": "array",
+              "items": {
+                "$ref": "#/components/schemas/AutomationStatus"
+              }
+            }
+          },
+          {
+            "name": "portal_status",
+            "in": "query",
+            "description": "Filter by portal status",
+            "schema": {
+              "$ref": "#/components/schemas/PortalStatus"
+            }
+          },
+          {
+            "name": "email_status",
+            "in": "query",
+            "description": "Filter by email delivery status (e.g. bounced, delivered). The response total reflects the count for the filtered status.",
+            "schema": {
+              "$ref": "#/components/schemas/EmailStatus"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "$ref": "#/components/responses/RecipientsResponse"
+          },
+          "400": {
+            "$ref": "#/components/responses/ClientErrorResponse"
+          },
+          "500": {
+            "$ref": "#/components/responses/ServerErrorResponse"
+          }
+        }
+      }
+    },
+    "/v1/campaign/{campaign_id}/email-stats": {
+      "get": {
+        "operationId": "getEmailStats",
+        "summary": "getEmailStats",
+        "description": "Aggregate email delivery counts for a campaign, for the KPI summary on the campaign UI.\nCounts cover the email (automation) channel only; `total_emailed` is the number of\nrecipients with a recorded email status. `delivered` is derivable as\n`total_emailed - bounced - complained - failed`.\n",
+        "tags": [
+          "Campaign Recipient"
+        ],
+        "security": [
+          {
+            "EpilotAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/CampaignIdPathParam"
+          }
+        ],
+        "responses": {
+          "200": {
+            "$ref": "#/components/responses/EmailStatsResponse"
+          },
+          "400": {
+            "$ref": "#/components/responses/ClientErrorResponse"
+          },
+          "500": {
+            "$ref": "#/components/responses/ServerErrorResponse"
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "schemas": {
+      "BaseError": {
+        "type": "object",
+        "properties": {
+          "status": {
+            "type": "integer",
+            "example": 404
+          },
+          "message": {
+            "type": "string",
+            "example": "Entity not found"
+          }
+        },
+        "required": [
+          "status",
+          "message"
+        ]
+      },
+      "ServerError": {
+        "$ref": "#/components/schemas/BaseError"
+      },
+      "ClientError": {
+        "oneOf": [
+          {
+            "type": "object",
+            "title": "MessageError",
+            "description": "An error object containing a human-readable message.",
+            "properties": {
+              "message": {
+                "type": "string",
+                "description": "A descriptive error message.",
+                "example": "The provided input was invalid."
+              }
+            },
+            "required": [
+              "message"
+            ],
+            "additionalProperties": false
+          },
+          {
+            "type": "object",
+            "title": "CodeError",
+            "description": "An error object containing a specific machine-readable error code.",
+            "properties": {
+              "code": {
+                "type": "string",
+                "description": "A specific machine-readable error code indicating a known error condition.",
+                "enum": [
+                  "CAMPAIGN_NOT_FOUND",
+                  "CAMPAIGN_HAS_NO_TARGET",
+                  "CAMPAIGN_HAS_NO_DELIVERY_METHOD",
+                  "INVALID_NEXT_BEST_ACTION",
+                  "CAMPAIGN_HAS_JOB_IN_PROGRESS",
+                  "CAMPAIGN_HAS_UNEXPECTED_STATUS",
+                  "JOB_TOKEN_MISSING",
+                  "TARGET_WITHOUT_FILTERS"
+                ],
+                "example": "CAMPAIGN_NOT_FOUND"
+              }
+            },
+            "required": [
+              "code"
+            ],
+            "additionalProperties": false
+          },
+          {
+            "type": "object",
+            "title": "StatusedError",
+            "description": "An error object containing a message and an explicit status, typically from a more generic error handler.",
+            "properties": {
+              "error": {
+                "type": "string",
+                "description": "A descriptive error message.",
+                "example": "An unexpected error occurred during processing."
+              },
+              "status": {
+                "type": "integer",
+                "description": "An explicit status code in the body, often mirroring the HTTP status but provided for programmatic access.",
+                "example": 400
+              }
+            },
+            "required": [
+              "error",
+              "status"
+            ],
+            "additionalProperties": false
+          }
+        ],
+        "description": "Describes the structure of a client error response, which can be one of several types:\n1. `MessageError`: Contains a 'message' field for general descriptive errors.\n2. `CodeError`: Contains a 'code' field for specific, machine-readable error codes.\n3. `StatusedError`: Contains 'error' and 'status' fields.\nThe HTTP status code of the response itself (e.g., 400, 404, 409) will always indicate the overall error category.\n"
+      },
+      "BaseUUID": {
+        "type": "string",
+        "format": "uuid",
+        "example": "b8c01433-5556-4e2b-aad4-6f5348d1df84"
+      },
+      "BaseNanoID": {
+        "type": "string",
+        "example": "xHcOoJCa07eysJ1GaQeSb"
+      },
+      "BaseTags": {
+        "type": "array",
+        "nullable": true,
+        "items": {
+          "type": "string"
+        }
+      },
+      "BaseRelation": {
+        "type": "object",
+        "properties": {
+          "$relation": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "entity_id": {
+                  "$ref": "#/components/schemas/BaseUUID"
+                },
+                "_tags": {
+                  "$ref": "#/components/schemas/BaseTags"
+                }
+              }
+            }
+          }
+        }
+      },
+      "BaseSystemId": {
+        "type": "object",
+        "readOnly": true,
+        "properties": {
+          "_id": {
+            "$ref": "#/components/schemas/BaseUUID"
+          }
+        },
+        "required": [
+          "_id"
+        ]
+      },
+      "BaseEntityOwner": {
+        "description": "The user / organization owning this entity.\n\nNote: Owner implicitly has access to the entity regardless of ACLs.\n",
+        "type": "object",
+        "properties": {
+          "org_id": {
+            "type": "string",
+            "example": "123"
+          },
+          "user_id": {
+            "type": "string",
+            "example": "123"
+          }
+        },
+        "required": [
+          "org_id"
+        ]
+      },
+      "BaseEntityAcl": {
+        "type": "object",
+        "description": "Access control list (ACL) for an entity. Defines sharing access to external orgs or users.",
+        "additionalProperties": true,
+        "readOnly": true,
+        "properties": {
+          "view": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "example": "org:456"
+            }
+          },
+          "edit": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "example": "org:456"
+            }
+          },
+          "delete": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "example": "org:456"
+            }
+          }
+        }
+      },
+      "BaseSystemFields": {
+        "type": "object",
+        "properties": {
+          "_id": {
+            "$ref": "#/components/schemas/BaseUUID"
+          },
+          "_org": {
+            "type": "string",
+            "description": "Organization Id the entity belongs to",
+            "readOnly": true
+          },
+          "_owners": {
+            "type": "array",
+            "readOnly": true,
+            "items": {
+              "$ref": "#/components/schemas/BaseEntityOwner"
+            }
+          },
+          "_schema": {
+            "readOnly": true,
+            "type": "string"
+          },
+          "_title": {
+            "readOnly": true,
+            "type": "string"
+          },
+          "_tags": {
+            "$ref": "#/components/schemas/BaseTags"
+          },
+          "_created_at": {
+            "readOnly": true,
+            "type": "string",
+            "format": "date-time"
+          },
+          "_updated_at": {
+            "readOnly": true,
+            "type": "string",
+            "format": "date-time"
+          },
+          "_acl": {
+            "$ref": "#/components/schemas/BaseEntityAcl"
+          }
+        }
+      },
+      "BaseSystemFieldsRequired": {
+        "type": "object",
+        "required": [
+          "_org",
+          "_owners",
+          "_schema",
+          "_title",
+          "_tags",
+          "_created_at",
+          "_updated_at",
+          "_acl"
+        ]
+      },
+      "CampaignStatus": {
+        "type": "string",
+        "default": "draft",
+        "enum": [
+          "draft",
+          "activating",
+          "active",
+          "inactive"
+        ]
+      },
+      "ExecutionSummaryItem": {
+        "type": "object",
+        "properties": {
+          "execution_id": {
+            "type": "string"
+          },
+          "execution_status": {
+            "type": "string"
+          }
+        }
+      },
+      "JobStatus": {
+        "type": "object",
+        "properties": {
+          "status": {
+            "type": "string",
+            "description": "The status of the automation job",
+            "enum": [
+              "queued",
+              "processing",
+              "finished",
+              "failed",
+              "cancelled",
+              "send_report"
+            ]
+          },
+          "execution_summary": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/ExecutionSummaryItem"
+            }
+          }
+        }
+      },
+      "Campaign": {
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/BaseSystemFields"
+          },
+          {
+            "type": "object",
+            "properties": {
+              "name": {
+                "type": "string"
+              },
+              "goal": {
+                "type": "string"
+              },
+              "status": {
+                "$ref": "#/components/schemas/CampaignStatus"
+              },
+              "start_date": {
+                "type": "string",
+                "format": "date"
+              },
+              "end_date": {
+                "type": "string",
+                "format": "date"
+              },
+              "flow_id": {
+                "type": "string"
+              },
+              "job_id": {
+                "type": "string"
+              },
+              "target": {
+                "$ref": "#/components/schemas/BaseRelation"
+              }
+            }
+          }
+        ]
+      },
+      "Target": {
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/BaseSystemFields"
+          },
+          {
+            "type": "object",
+            "properties": {
+              "name": {
+                "type": "string"
+              },
+              "description": {
+                "type": "string"
+              },
+              "entity_schema": {
+                "type": "string"
+              },
+              "entity_filters": {
+                "type": "object",
+                "additionalProperties": true
+              }
+            }
+          }
+        ]
+      },
+      "MatchCampaignParams": {
+        "type": "object",
+        "properties": {
+          "entity_refs": {
+            "type": "array",
+            "description": "List of entities (e.g. Contacts or Contracts) that should be part of the campaign target.",
+            "items": {
+              "type": "object",
+              "properties": {
+                "entity_id": {
+                  "$ref": "#/components/schemas/BaseUUID"
+                },
+                "entity_schema": {
+                  "type": "string"
+                }
+              },
+              "required": [
+                "entity_id",
+                "entity_schema"
+              ],
+              "additionalProperties": false
+            }
+          },
+          "campaign_ids": {
+            "type": "array",
+            "description": "List of campaign IDs to check.",
+            "items": {
+              "$ref": "#/components/schemas/BaseUUID"
+            },
+            "example": [
+              "b8c01433-5556-4e2b-aad4-6f5348d1df84"
+            ],
+            "minItems": 1,
+            "maxItems": 100,
+            "uniqueItems": true
+          }
+        },
+        "required": [
+          "entity_refs",
+          "campaign_ids"
+        ],
+        "additionalProperties": false
+      },
+      "NextBestAction": {
+        "type": "object",
+        "description": "A Next Best Action configured on a campaign's Entity-UI channel.\nThis is the canonical NBA contract shared by discovery (this API), authoring, and rendering.\nNBA content is single-language in v1; text fields may contain `{{placeholders}}` resolved at render time.\n",
+        "properties": {
+          "category": {
+            "type": "string",
+            "maxLength": 30,
+            "description": "Light category label shown above the title. Free-form text."
+          },
+          "icon": {
+            "type": "object",
+            "description": "Curated icon for the NBA.",
+            "properties": {
+              "name": {
+                "type": "string",
+                "description": "Icon name from \"@epilot360/icons\"."
+              },
+              "color": {
+                "type": "string",
+                "description": "Optional icon color."
+              }
+            },
+            "required": [
+              "name"
+            ]
+          },
+          "title": {
+            "type": "string",
+            "maxLength": 60,
+            "description": "Bold action title. Required. Supports `{{placeholders}}`."
+          },
+          "body": {
+            "type": "string",
+            "maxLength": 140,
+            "description": "Optional description. Supports `{{placeholders}}` (incl. relative dates)."
+          },
+          "priority": {
+            "type": "string",
+            "enum": [
+              "low",
+              "medium",
+              "high"
+            ],
+            "default": "medium",
+            "description": "Display priority. NBAs are shown highest-priority first."
+          },
+          "is_dismissable": {
+            "type": "boolean",
+            "default": true,
+            "description": "Whether the agent can dismiss the NBA."
+          },
+          "cta": {
+            "type": "object",
+            "description": "The NBA's single call-to-action.",
+            "properties": {
+              "type": {
+                "type": "string",
+                "enum": [
+                  "journey",
+                  "workflow",
+                  "flow"
+                ]
+              },
+              "target": {
+                "type": "string",
+                "description": "Journey id, workflow definition id, or flow template id, depending on `type`."
+              },
+              "context_params": {
+                "type": "array",
+                "description": "Journey context parameters (journey CTA only). Maps the journey's declared\ncontext parameters so the journey knows which entity it is about. Discovery\nreturns them verbatim; they are passed to the journey when it launches.\n",
+                "items": {
+                  "type": "object",
+                  "properties": {
+                    "key": {
+                      "type": "string"
+                    },
+                    "value": {
+                      "type": "string"
+                    }
+                  },
+                  "required": [
+                    "key",
+                    "value"
+                  ]
+                }
+              }
+            },
+            "required": [
+              "type",
+              "target"
+            ]
+          }
+        },
+        "required": [
+          "title",
+          "cta"
+        ]
+      },
+      "DiscoverCampaignsParams": {
+        "type": "object",
+        "properties": {
+          "entity_id": {
+            "$ref": "#/components/schemas/BaseUUID"
+          },
+          "entity_schema": {
+            "type": "string",
+            "description": "The schema slug of the entity (e.g. \"contact\" or \"account\")."
+          }
+        },
+        "required": [
+          "entity_id",
+          "entity_schema"
+        ],
+        "additionalProperties": false
+      },
+      "DiscoverResult": {
+        "type": "object",
+        "description": "One discovered Next Best Action, plus this entity's interaction state for it.",
+        "properties": {
+          "campaign_id": {
+            "$ref": "#/components/schemas/BaseUUID"
+          },
+          "nba": {
+            "$ref": "#/components/schemas/NextBestAction"
+          },
+          "status": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/EntityUiStatus"
+              }
+            ],
+            "description": "The recipient's current Entity-UI status for this campaign, present only when a\nrecipient record already exists (i.e. the entity has previously seen, clicked or\ndismissed this NBA). Absent when the entity has not yet interacted with it.\n\nIn `results` this is only ever `seen` or `clicked`; in `dismissed` it is always\n`dismissed`. Lets the client skip a redundant `seen` call for NBAs already seen.\n"
+          },
+          "status_updated_at": {
+            "type": "string",
+            "format": "date-time",
+            "description": "When `status` was last written. Present whenever `status` is. Lets the client show how\nlong ago an NBA was dismissed.\n"
+          }
+        },
+        "required": [
+          "campaign_id",
+          "nba"
+        ]
+      },
+      "MatchTargetParams": {
+        "type": "object",
+        "properties": {
+          "entity_refs": {
+            "type": "array",
+            "description": "List of entities (e.g. Contacts or Contracts) that should be part of the targets.",
+            "items": {
+              "type": "object",
+              "properties": {
+                "entity_id": {
+                  "$ref": "#/components/schemas/BaseUUID"
+                },
+                "entity_schema": {
+                  "type": "string"
+                }
+              },
+              "required": [
+                "entity_id",
+                "entity_schema"
+              ],
+              "additionalProperties": false
+            }
+          },
+          "target_ids": {
+            "type": "array",
+            "description": "List of target IDs to check.",
+            "items": {
+              "$ref": "#/components/schemas/BaseUUID"
+            },
+            "example": [
+              "b8c01433-5556-4e2b-aad4-6f5348d1df84"
+            ],
+            "minItems": 1,
+            "maxItems": 100,
+            "uniqueItems": true
+          }
+        },
+        "required": [
+          "entity_refs",
+          "target_ids"
+        ],
+        "additionalProperties": false
+      },
+      "GetTargetQueriesParams": {
+        "type": "object",
+        "properties": {
+          "target_ids": {
+            "type": "array",
+            "description": "List of target IDs to transform into queries.",
+            "items": {
+              "$ref": "#/components/schemas/BaseUUID"
+            },
+            "example": [
+              "b8c01433-5556-4e2b-aad4-6f5348d1df84"
+            ],
+            "minItems": 1,
+            "uniqueItems": true
+          }
+        },
+        "required": [
+          "target_ids"
+        ],
+        "additionalProperties": false
+      },
+      "TargetQueryResult": {
+        "type": "object",
+        "properties": {
+          "target_id": {
+            "$ref": "#/components/schemas/BaseUUID"
+          },
+          "query": {
+            "type": "string",
+            "description": "Transformed query string, or null if transformation failed.",
+            "nullable": true
+          },
+          "error": {
+            "type": "string",
+            "description": "Error message if query transformation failed."
+          }
+        },
+        "required": [
+          "target_id",
+          "query"
+        ]
+      },
+      "AutomationStatus": {
+        "type": "string",
+        "enum": [
+          "pending",
+          "in_progress",
+          "success",
+          "failed",
+          "cancelled"
+        ]
+      },
+      "PortalStatus": {
+        "type": "string",
+        "enum": [
+          "sent",
+          "seen",
+          "dismissed",
+          "clicked"
+        ]
+      },
+      "EntityUiStatus": {
+        "type": "string",
+        "description": "Lifecycle status of a Next Best Action on the Entity-UI channel. Unlike the portal\nchannel there is no `sent` state: an NBA recipient is born at `seen`, the moment the\naction is first rendered to an agent.\n",
+        "enum": [
+          "seen",
+          "dismissed",
+          "clicked"
+        ]
+      },
+      "EmailStatus": {
+        "type": "string",
+        "description": "Delivery status of the email a campaign's automation sends to a recipient. Set to `sent`\nonce the automation hands the email off, then updated asynchronously as SES notifications\narrive (`bounced` / `complained`; an SES Reject maps to `bounced`). `failed` is a send-time\nfailure (the automation execution could not send at all), distinct from an asynchronous\nbounce. `delivered` is reserved for when Delivery events are published.\n",
+        "enum": [
+          "sent",
+          "delivered",
+          "bounced",
+          "complained",
+          "failed"
+        ]
+      },
+      "EmailBounceType": {
+        "type": "string",
+        "description": "SES bounce classification: `permanent` (hard) or `transient` (soft).",
+        "enum": [
+          "permanent",
+          "transient"
+        ]
+      },
+      "Recipient": {
+        "type": "object",
+        "properties": {
+          "entity_id": {
+            "$ref": "#/components/schemas/BaseUUID"
+          },
+          "entity_schema": {
+            "type": "string"
+          },
+          "title": {
+            "type": "string"
+          },
+          "automation_status": {
+            "$ref": "#/components/schemas/AutomationStatus"
+          },
+          "automation_execution_id": {
+            "type": "string"
+          },
+          "portal_status": {
+            "$ref": "#/components/schemas/PortalStatus"
+          },
+          "portal_status_updated_at": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "portal_state": {
+            "type": "object",
+            "additionalProperties": true
+          },
+          "entity_ui_status": {
+            "$ref": "#/components/schemas/EntityUiStatus"
+          },
+          "entity_ui_status_updated_at": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "entity_ui_status_before_dismiss": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/EntityUiStatus"
+              }
+            ],
+            "description": "The Entity-UI status the recipient held immediately before it was dismissed, so\n`entity_ui:restore` can put it back without losing a recorded click.\n\nServer-managed — never send this from a client; it is ignored on write. Meaningful\n**only while** `entity_ui_status` is `dismissed`: a restore intentionally leaves the\nvalue behind rather than clearing it, so a stale value after a restore is expected and\nmust not be read.\n"
+          },
+          "message_entity_id": {
+            "type": "string",
+            "description": "The message entity id of the email sent to this recipient by the campaign's automation\n(not the SES/provider message id), used to correlate SES delivery notifications back to\nthe recipient. Server-managed.\n"
+          },
+          "email_status": {
+            "$ref": "#/components/schemas/EmailStatus"
+          },
+          "email_status_updated_at": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "email_bounce_type": {
+            "$ref": "#/components/schemas/EmailBounceType"
+          },
+          "email_bounce_subtype": {
+            "type": "string",
+            "description": "SES bounce sub-type (e.g. `General`, `NoEmail`, `MailboxFull`)."
+          },
+          "email_complaint_type": {
+            "type": "string",
+            "description": "SES complaint feedback type (e.g. `abuse`, `fraud`), set for complaints."
+          },
+          "email_bounce_reason": {
+            "type": "string",
+            "description": "Human-readable failure reason — the SES bounce `diagnosticCode`, the complaint\nfeedback type, or a send-time error message.\n"
+          },
+          "email_send_error": {
+            "type": "object",
+            "additionalProperties": true,
+            "description": "The raw SES notification (or send error) kept verbatim for a detail view."
+          },
+          "email_unsubscribed_at": {
+            "type": "string",
+            "format": "date-time",
+            "description": "When the contact unsubscribed from email marketing (opted out). Server-managed."
+          },
+          "updated_at": {
+            "type": "string",
+            "format": "date-time"
+          }
+        }
+      },
+      "BaseRecipientPayload": {
+        "type": "object",
+        "properties": {
+          "entity_id": {
+            "$ref": "#/components/schemas/BaseUUID"
+          },
+          "entity_schema": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "entity_id",
+          "entity_schema"
+        ]
+      },
+      "AutomationRecipientPayload": {
+        "type": "object",
+        "properties": {
+          "automation_status": {
+            "$ref": "#/components/schemas/AutomationStatus"
+          },
+          "automation_execution_id": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "automation_status",
+          "automation_execution_id"
+        ]
+      },
+      "PortalRecipientPayload": {
+        "type": "object",
+        "properties": {
+          "portal_status": {
+            "$ref": "#/components/schemas/PortalStatus"
+          },
+          "portal_state": {
+            "type": "object",
+            "additionalProperties": true
+          }
+        },
+        "required": [
+          "portal_status"
+        ]
+      },
+      "CreateRecipientPayload": {
+        "oneOf": [
+          {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/BaseRecipientPayload"
+              },
+              {
+                "$ref": "#/components/schemas/AutomationRecipientPayload"
+              }
+            ]
+          },
+          {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/BaseRecipientPayload"
+              },
+              {
+                "$ref": "#/components/schemas/PortalRecipientPayload"
+              }
+            ]
+          },
+          {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/BaseRecipientPayload"
+              },
+              {
+                "$ref": "#/components/schemas/AutomationRecipientPayload"
+              },
+              {
+                "$ref": "#/components/schemas/PortalRecipientPayload"
+              }
+            ]
+          }
+        ]
+      },
+      "UpdateRecipientPayload": {
+        "type": "object",
+        "properties": {
+          "automation_status": {
+            "$ref": "#/components/schemas/AutomationStatus"
+          },
+          "automation_execution_id": {
+            "type": "string"
+          },
+          "portal_status": {
+            "$ref": "#/components/schemas/PortalStatus"
+          },
+          "portal_state": {
+            "type": "object",
+            "additionalProperties": true
+          }
+        }
+      },
+      "RetriggerAutomationsRequest": {
+        "type": "object",
+        "properties": {
+          "recipient_ids": {
+            "type": "array",
+            "description": "List of recipient IDs to retrigger automations for",
+            "items": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        },
+        "required": [
+          "recipient_ids"
+        ]
+      },
+      "RetriggerAutomationsResult": {
+        "type": "object",
+        "properties": {
+          "recipient_id": {
+            "type": "string",
+            "format": "uuid",
+            "description": "The ID of the recipient"
+          },
+          "result": {
+            "type": "string",
+            "description": "The result of the retriggering operation",
+            "enum": [
+              "success",
+              "failure",
+              "not_found",
+              "invalid_status"
+            ]
+          },
+          "execution_id": {
+            "type": "string",
+            "description": "The ID of the new automation execution (if successful)"
+          },
+          "error": {
+            "type": "string",
+            "description": "The error message if the operation failed"
+          }
+        },
+        "required": [
+          "recipient_id",
+          "result"
+        ]
+      },
+      "UpdatePortalStatusRequest": {
+        "type": "object",
+        "properties": {
+          "status": {
+            "$ref": "#/components/schemas/PortalStatus"
+          }
+        },
+        "required": [
+          "status"
+        ]
+      },
+      "UpdateEntityUiStatusRequest": {
+        "type": "object",
+        "properties": {
+          "status": {
+            "$ref": "#/components/schemas/EntityUiStatus"
+          },
+          "entity_schema": {
+            "type": "string",
+            "description": "Schema slug of the recipient entity (e.g. \"contact\"). Required when recording the\nfirst `seen`, which lazily creates the recipient record; ignored on later transitions.\n"
+          }
+        },
+        "required": [
+          "status"
+        ],
+        "additionalProperties": false
+      },
+      "SetupCampaignRequest": {
+        "description": "Discriminated by `type`. Each campaign variant has its own request shape;\nnew variants are added by introducing a new schema and extending the `oneOf` list.\n",
+        "oneOf": [
+          {
+            "$ref": "#/components/schemas/SetupTariffChangeCampaignRequest"
+          }
+        ],
+        "discriminator": {
+          "propertyName": "type",
+          "mapping": {
+            "tariff_change": "#/components/schemas/SetupTariffChangeCampaignRequest"
+          }
+        }
+      },
+      "SetupTariffChangeCampaignRequest": {
+        "type": "object",
+        "properties": {
+          "type": {
+            "type": "string",
+            "enum": [
+              "tariff_change"
+            ]
+          },
+          "product_recommendation": {
+            "type": "object",
+            "properties": {
+              "name": {
+                "type": "string",
+                "description": "Optional name of the product recommendation. Defaults to the campaign name."
+              },
+              "source_product_id": {
+                "allOf": [
+                  {
+                    "$ref": "#/components/schemas/BaseUUID"
+                  }
+                ],
+                "description": "Optional source product entity ID for the recommendation."
+              },
+              "source_price_id": {
+                "allOf": [
+                  {
+                    "$ref": "#/components/schemas/BaseUUID"
+                  }
+                ],
+                "description": "Optional source price entity ID for the recommendation."
+              },
+              "offers": {
+                "type": "array",
+                "description": "Offer blocks for the product_recommendation entity.",
+                "items": {
+                  "type": "object",
+                  "properties": {
+                    "target_id": {
+                      "$ref": "#/components/schemas/BaseUUID",
+                      "description": "Optional per-offer target entity ID."
+                    },
+                    "items": {
+                      "type": "array",
+                      "description": "Product/price pairs within this offer.",
+                      "items": {
+                        "type": "object",
+                        "properties": {
+                          "product_id": {
+                            "$ref": "#/components/schemas/BaseUUID"
+                          },
+                          "price_id": {
+                            "$ref": "#/components/schemas/BaseUUID"
+                          },
+                          "highlight_config": {
+                            "type": "object",
+                            "description": "Opaque per-item highlight/comparison config persisted as-is on the entity.",
+                            "additionalProperties": true
+                          }
+                        },
+                        "required": [
+                          "product_id",
+                          "price_id"
+                        ],
+                        "additionalProperties": false
+                      }
+                    }
+                  },
+                  "required": [
+                    "items"
+                  ],
+                  "additionalProperties": false
+                }
+              }
+            },
+            "additionalProperties": false
+          },
+          "campaign": {
+            "type": "object",
+            "properties": {
+              "name": {
+                "type": "string"
+              },
+              "goal": {
+                "type": "string"
+              },
+              "target_ids": {
+                "type": "array",
+                "description": "List of target entity IDs to attach to the campaign. Today only a single\nentry is supported (campaign.target is has_one) but the array shape is kept\nfor forward-compatibility — only `target_ids[0]` is used.\n",
+                "items": {
+                  "$ref": "#/components/schemas/BaseUUID"
+                }
+              }
+            },
+            "required": [
+              "name",
+              "target_ids"
+            ],
+            "additionalProperties": false
+          },
+          "journey": {
+            "type": "object",
+            "description": "Optional journey configuration selected in the wizard. Only sent by the\nconsumer once a journey has been chosen.\n",
+            "properties": {
+              "journey_id": {
+                "$ref": "#/components/schemas/BaseUUID"
+              }
+            },
+            "required": [
+              "journey_id"
+            ],
+            "additionalProperties": false
+          },
+          "channels": {
+            "type": "object",
+            "description": "Optional delivery channel configuration. Each channel is only sent by the\nconsumer once it has been enabled and fully configured in the wizard.\n",
+            "properties": {
+              "portal_widget": {
+                "type": "object",
+                "description": "Portal widget placement for the product recommendation block. Only sent by\nthe consumer once both a portal and a block have been selected.\n",
+                "properties": {
+                  "portal_id": {
+                    "$ref": "#/components/schemas/BaseUUID"
+                  },
+                  "block_id": {
+                    "$ref": "#/components/schemas/BaseUUID"
+                  }
+                },
+                "required": [
+                  "portal_id",
+                  "block_id"
+                ],
+                "additionalProperties": false
+              },
+              "email": {
+                "type": "object",
+                "description": "Email campaign delivery. An automation flow (legacy) and/or an email\ntemplate can be provided to send the campaign emails. The selection is\npersisted as the campaign's `flow_id`. If `automation_id` is provided it is\nused as-is; otherwise a flow is created from `template_id`. Only sent by the\nconsumer once one has been selected.\n",
+                "properties": {
+                  "automation_id": {
+                    "$ref": "#/components/schemas/BaseUUID"
+                  },
+                  "template_id": {
+                    "$ref": "#/components/schemas/BaseUUID"
+                  }
+                },
+                "minProperties": 1,
+                "additionalProperties": false
+              }
+            },
+            "additionalProperties": false
+          }
+        },
+        "required": [
+          "type",
+          "product_recommendation",
+          "campaign"
+        ],
+        "additionalProperties": false
+      },
+      "SetupTariffChangeCampaignResponse": {
+        "type": "object",
+        "properties": {
+          "type": {
+            "type": "string",
+            "enum": [
+              "tariff_change"
+            ]
+          },
+          "product_recommendation_id": {
+            "$ref": "#/components/schemas/BaseUUID"
+          },
+          "campaign_id": {
+            "$ref": "#/components/schemas/BaseUUID"
+          },
+          "journey_id": {
+            "$ref": "#/components/schemas/BaseUUID"
+          },
+          "portal_widget_id": {
+            "$ref": "#/components/schemas/BaseUUID"
+          }
+        },
+        "required": [
+          "type",
+          "product_recommendation_id",
+          "campaign_id"
+        ],
+        "additionalProperties": false
+      }
+    },
+    "securitySchemes": {
+      "EpilotAuth": {
+        "type": "http",
+        "scheme": "bearer",
+        "description": "Authorization header with epilot OAuth2 bearer token",
+        "bearerFormat": "JWT"
+      }
+    },
+    "parameters": {
+      "CampaignIdPathParam": {
+        "name": "campaign_id",
+        "description": "The campaign ID",
+        "in": "path",
+        "required": true,
+        "schema": {
+          "$ref": "#/components/schemas/BaseUUID"
+        }
+      },
+      "RecipientIdPathParam": {
+        "name": "recipient_id",
+        "description": "The entity ID of the recipient",
+        "in": "path",
+        "required": true,
+        "schema": {
+          "$ref": "#/components/schemas/BaseUUID"
+        }
+      }
+    },
+    "responses": {
+      "ClientErrorResponse": {
+        "description": "Any error based on client data errors",
+        "content": {
+          "application/json": {
+            "schema": {
+              "$ref": "#/components/schemas/ClientError"
+            }
+          }
+        }
+      },
+      "ServerErrorResponse": {
+        "description": "Any error based on the server-side",
+        "content": {
+          "application/json": {
+            "schema": {
+              "$ref": "#/components/schemas/ServerError"
+            }
+          }
+        }
+      },
+      "CampaignResponse": {
+        "description": "Campaign entity response",
+        "content": {
+          "application/json": {
+            "schema": {
+              "type": "object",
+              "properties": {
+                "campaign": {
+                  "$ref": "#/components/schemas/Campaign"
+                }
+              }
+            }
+          }
+        }
+      },
+      "JobStatusResponse": {
+        "description": "Campaign job status response",
+        "content": {
+          "application/json": {
+            "schema": {
+              "$ref": "#/components/schemas/JobStatus"
+            }
+          }
+        }
+      },
+      "RecipientResponse": {
+        "description": "Recipient response",
+        "content": {
+          "application/json": {
+            "schema": {
+              "$ref": "#/components/schemas/Recipient"
+            }
+          }
+        }
+      },
+      "RecipientsResponse": {
+        "description": "List of campaign recipients",
+        "content": {
+          "application/json": {
+            "schema": {
+              "type": "object",
+              "properties": {
+                "results": {
+                  "type": "array",
+                  "items": {
+                    "$ref": "#/components/schemas/Recipient"
+                  }
+                },
+                "next": {
+                  "type": "string",
+                  "nullable": true,
+                  "description": "Cursor for next page of results"
+                },
+                "total": {
+                  "type": "integer",
+                  "description": "Total number of recipients"
+                }
+              }
+            }
+          }
+        }
+      },
+      "EmailStatsResponse": {
+        "description": "Aggregate email delivery counts for a campaign.",
+        "content": {
+          "application/json": {
+            "schema": {
+              "type": "object",
+              "required": [
+                "total_emailed",
+                "sent",
+                "delivered",
+                "bounced",
+                "bounced_hard",
+                "bounced_soft",
+                "complained",
+                "failed",
+                "unsubscribed"
+              ],
+              "properties": {
+                "total_emailed": {
+                  "type": "integer",
+                  "description": "Recipients with a recorded email status (the KPI denominator)."
+                },
+                "sent": {
+                  "type": "integer"
+                },
+                "delivered": {
+                  "type": "integer",
+                  "description": "Currently always 0 (Delivery events are not published yet)."
+                },
+                "bounced": {
+                  "type": "integer"
+                },
+                "bounced_hard": {
+                  "type": "integer",
+                  "description": "Bounces classified permanent (bounced_hard + bounced_soft = bounced)."
+                },
+                "bounced_soft": {
+                  "type": "integer",
+                  "description": "Bounces classified transient."
+                },
+                "complained": {
+                  "type": "integer"
+                },
+                "failed": {
+                  "type": "integer"
+                },
+                "unsubscribed": {
+                  "type": "integer",
+                  "description": "Recipients who opted out of email marketing."
+                }
+              }
+            }
+          }
+        }
+      },
+      "MatchCampaignsResponse": {
+        "description": "List of campaigns where the target entities match the given entities.",
+        "content": {
+          "application/json": {
+            "schema": {
+              "type": "object",
+              "properties": {
+                "hits": {
+                  "type": "number",
+                  "description": "Number of matching campaigns."
+                },
+                "results": {
+                  "type": "array",
+                  "description": "List of matching campaigns.",
+                  "items": {
+                    "type": "object",
+                    "properties": {
+                      "campaign": {
+                        "$ref": "#/components/schemas/Campaign"
+                      }
+                    },
+                    "required": [
+                      "campaign"
+                    ]
+                  }
+                }
+              }
+            }
+          }
+        }
+      },
+      "DiscoverCampaignsResponse": {
+        "description": "The Next Best Actions the entity should see on the Entity-UI channel, priority-sorted.",
+        "content": {
+          "application/json": {
+            "schema": {
+              "type": "object",
+              "properties": {
+                "hits": {
+                  "type": "number",
+                  "description": "Number of matching NBAs. Counts `results` only — dismissed ones are excluded."
+                },
+                "results": {
+                  "type": "array",
+                  "description": "Matching NBAs, sorted by priority (desc); one entry per campaign.",
+                  "items": {
+                    "$ref": "#/components/schemas/DiscoverResult"
+                  }
+                },
+                "dismissed": {
+                  "type": "array",
+                  "description": "NBAs this entity has dismissed that would otherwise be in `results` — same shape,\nalso priority-sorted. Returned so the client can show the agent what it hid and\noffer to restore it, without a second round-trip.\n\nOnly currently-relevant dismissals appear: each one is matched against its\ncampaign's target exactly like a visible NBA, so a dismissal is dropped once the\ncampaign ends or the entity stops matching. Capped, so this is not a complete\ndismissal history.\n",
+                  "items": {
+                    "$ref": "#/components/schemas/DiscoverResult"
+                  }
+                }
+              },
+              "required": [
+                "hits",
+                "results",
+                "dismissed"
+              ]
+            }
+          }
+        }
+      },
+      "MatchTargetsResponse": {
+        "description": "List of targets where the given entities are found.",
+        "content": {
+          "application/json": {
+            "schema": {
+              "type": "object",
+              "properties": {
+                "hits": {
+                  "type": "number",
+                  "description": "Number of matching targets."
+                },
+                "results": {
+                  "type": "array",
+                  "description": "List of matching targets.",
+                  "items": {
+                    "type": "object",
+                    "properties": {
+                      "target": {
+                        "$ref": "#/components/schemas/Target"
+                      }
+                    },
+                    "required": [
+                      "target"
+                    ]
+                  }
+                }
+              }
+            }
+          }
+        }
+      },
+      "GetTargetQueriesResponse": {
+        "description": "List of transformed target queries.",
+        "content": {
+          "application/json": {
+            "schema": {
+              "type": "object",
+              "properties": {
+                "results": {
+                  "type": "array",
+                  "description": "List of target query results.",
+                  "items": {
+                    "$ref": "#/components/schemas/TargetQueryResult"
+                  }
+                }
+              },
+              "required": [
+                "results"
+              ]
+            }
+          }
+        }
+      },
+      "CampaignPortalsResponse": {
+        "description": "List of portals and its widgets where the campaign is used",
+        "content": {
+          "application/json": {
+            "schema": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "portal": {
+                    "type": "object",
+                    "properties": {
+                      "origin": {
+                        "type": "string",
+                        "description": "The origin of the portal"
+                      },
+                      "domain": {
+                        "type": "string",
+                        "description": "The domain of the portal"
+                      },
+                      "name": {
+                        "type": "string",
+                        "description": "The name of the portal"
+                      }
+                    }
+                  },
+                  "widgets": {
+                    "type": "array",
+                    "items": {
+                      "type": "object",
+                      "properties": {
+                        "id": {
+                          "type": "string",
+                          "description": "The ID of the widget"
+                        },
+                        "headline": {
+                          "type": "object",
+                          "properties": {
+                            "en": {
+                              "type": "string",
+                              "description": "The headline in English"
+                            },
+                            "de": {
+                              "type": "string",
+                              "description": "The headline in German"
+                            }
+                          }
+                        }
+                      },
+                      "required": [
+                        "id"
+                      ]
+                    }
+                  }
+                },
+                "required": [
+                  "portal",
+                  "widgets"
+                ]
+              }
+            }
+          }
+        }
+      },
+      "SetupCampaignResponse": {
+        "description": "Discriminated by `type`, mirroring the request. Each campaign variant has its\nown response shape; new variants extend the `oneOf` list alongside the request.\n",
+        "content": {
+          "application/json": {
+            "schema": {
+              "oneOf": [
+                {
+                  "$ref": "#/components/schemas/SetupTariffChangeCampaignResponse"
+                }
+              ],
+              "discriminator": {
+                "propertyName": "type",
+                "mapping": {
+                  "tariff_change": "#/components/schemas/SetupTariffChangeCampaignResponse"
+                }
+              }
+            }
+          }
+        }
+      },
+      "RetriggerAutomationsResponse": {
+        "description": "Response to a request to retrigger automations for campaign recipients",
+        "content": {
+          "application/json": {
+            "schema": {
+              "type": "object",
+              "properties": {
+                "message": {
+                  "type": "string",
+                  "description": "A confirmation message indicating the request was received and processed"
+                },
+                "results": {
+                  "type": "array",
+                  "description": "List of retriggering results",
+                  "items": {
+                    "$ref": "#/components/schemas/RetriggerAutomationsResult"
+                  }
+                }
+              },
+              "required": [
+                "message",
+                "results"
+              ]
+            }
+          }
+        }
+      }
+    }
+  }
+}