{"openapi":"3.0.3","info":{"title":"Optima Campaign API","version":"0.1","description":"Optima Campaign is a separately licensed campaign-orchestration suite built\non top of the Optima CDP. This API (default port\n2600) manages Campaign resources — segments; campaigns and offers; NBA\ndecisioning; message templates and sending; and journeys. Customer data (profiles, events,\nsignals, consents) is never stored here: member reads and count previews\nare live proxies of the CDP's `/cdp/api/v1/profiles` API using the suite's\nservice API key, so CDP privacy enforcement (consent, PII levels, purpose\ngates, erasure) always applies.\n\n**Authentication**: same scheme as the CDP, against the same shared\naccounts, API keys and roles, and the same session\nstore:\n- `X-APIKey` header — machine-to-machine API key auth (SHA-512 hashed, role-based route permissions)\n- `Authorization: Bearer <token>` header — operator session issued by the CDP's `/cdp/auth/login`\n\n**Delegated requests**: an application flagged `delegation_enforces_user_roles`\n(set on the CDP's `PUT /applications/{id}/instance-flags`, which also sets\n`delegation_allowed`, needed for the flag to take effect) never acts as itself on this API or on the NBA API.\nEach request must carry `X-On-Behalf-Of: <user email>`; the call is allowed\nonly when the application's own roles AND the roles that user holds in the\nresolved tenant both allow the route, and in-handler role gates (such as\napproval rights) judge the user. Refusals are 403: `X-On-Behalf-Of-App`\npresent (\"this application may only act on behalf of users\"), no\n`X-On-Behalf-Of` (\"this application must act on behalf of a user\"),\ndelegation not allowed (\"application is not permitted to act on behalf of\nusers\"), an inactive user (\"delegated user is not active\"), a user with no\nrole in the tenant (\"delegated user has no role in this tenant\"); a value\nthat is not a bare email address is 400. Every CDP call made for the\nrequest then carries the user. Other applications ignore `X-On-Behalf-Of`\nhere, as before.\n\nBuilt-in roles: `campaign_editor` (authoring\nCRUD — campaigns, journeys, segments, templates, documents, offer\ncatalogs, code pools, responses — but GET only on channels, systems,\ndestinations, audiences and contact governance, plus\nPOST on the NBA API; formerly `marketer`), `campaign_admin`\n(the same plus channel providers, external systems, activation, contact\ngovernance and approval rights), `campaign_approver`, `engineer` and\n`admin` (full); read-only: `campaign_viewer` (GET across the suite plus\nthe named read-only pre-flight POSTs), `analytics_editor` (formerly\n`analyst`), `analytics_viewer` and `auditor`. Area roles —\n`audience_editor` (segments), `content_editor` / `content_viewer`\n(templates, documents), `contact_policy_editor` (fatigue, response\npolicies, silent hours, control groups), `activation_editor`\n(destinations, audiences), `integration_editor` / `integration_viewer`\n(channel providers, external systems) — reach only their own prefixes.\nRoles stack: a user or key may hold several per tenant.\n\n**Required headers**: Every request must include `X-Request-ID` (a\nclient-generated unique ID for tracing).\n\n**Feature licence**: this\nwhole API requires the calling tenant's account to hold the **campaign**\npackage. Three surfaces inside it are separate add-ons:\n`/offer-catalogs/*` and the NBA API need **decision**; `/destinations/*`\nand `/audiences/*` need **activation** (both require campaign);\n`/segments/suggest`, `/templates/generate`, `/campaigns/{id}/journeys/draft`,\n`/campaigns/{id}/predict` and `/campaigns/{id}/insights` need **ai**.\nWithin the package, every route family also carries its own feature key\n(`journeys`, `templates`, `delivery`, `fatigue`, `control_groups`,\n`code_pools`, `attribution`, `silent_hours`, `languages`, `split_tests`,\n`preflight`, `external_systems`, `documents`, `approvals`,\n`response_policies`, the `assist_*` keys): a licence always grants the\nwhole package, but a tenant's `settings.disabled_features` may deny one\nkey, and then just that family answers the 403. A resource's\n`/revisions` routes (list, read, restore) carry its family's key as well\nas `approvals`, and refuse exactly as its PUT does.\nThe on-site pull channels (`web_banner`, `web_personalization`,\n`mobile_inapp`) belong to the **edge** package: any save naming one of\nthem as its channel (campaign, provider, fatigue policy, send, template\nvariant) is refused with the same 403 unless Edge is licensed.\n\nAn unlicensed call answers **403** with\n`data.reason = \"feature_not_licensed\"` and `data.package` naming what would\ngrant it and `data.package_licensed` (boolean) saying whether the account\nalready holds that package (true: the feature was excluded or switched off;\nfalse: the package is missing). An account with no stored licence has every package, so this\nchanges nothing until a licence is written.\n\n**Before the first licence snapshot loads** (process just started, or its\ncontrol-plane poll has never succeeded), every licence-gated route on\nboth the Campaign and NBA services — which is effectively\nevery route in this document and the NBA decide operations below — answers\n**503** instead of evaluating the licence at all, rather than risk waving\nevery tenant through as fully licensed. A later poll failure keeps serving\nfrom the last-good snapshot; only \"never loaded\" refuses. Endpoint-level\n503 entries call this out only where it might otherwise be mistaken for a\ndifferent unavailability (e.g. the send queue or a downstream store).\n"},"servers":[{"url":"http://localhost:2600","description":"Local development server"}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-APIKey"},"BearerAuth":{"type":"http","scheme":"bearer","description":"Opaque session token obtained from the CDP's POST /cdp/auth/login."}},"parameters":{"PurposeHeader":{"name":"X-Purpose","in":"header","required":false,"description":"Declared processing purpose, forwarded verbatim to the CDP on\nmember/count reads so the CDP's privacy gates evaluate the true\npurpose of the read. Mandatory when the CDP runs in strict privacy mode.\n","schema":{"type":"string"},"example":"campaign_targeting"},"SegmentId":{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Segment id."},"CampaignId":{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Campaign id."},"ControlEntityType":{"name":"entity_type","in":"path","required":true,"schema":{"type":"string"},"description":"The entity type whose global control group this is. The holdout is scoped per entity type because \"who is held out from marketing\" is a property of the customer base, not of a campaign.\n"},"OfferId":{"name":"offerId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Offer id (scoped to its campaign)."},"CatalogId":{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Offer catalogue id."},"ResponseWindowDays":{"name":"days","in":"query","schema":{"type":"integer","minimum":1,"maximum":365,"default":30},"description":"Window size, counting back from now. Above 365 is REJECTED rather than clamped, so nobody reports a year's worth of answers as two.\n"},"ResponseOfferId":{"name":"offer_id","in":"query","schema":{"type":"string"},"description":"Narrows to one offer."},"ResponseAction":{"name":"action","in":"query","schema":{"type":"string","enum":["presented","accepted","postponed","rejected","realized","decisioned"]},"description":"Which answer to list. Omitted lists all five response actions (never the message axis). `decisioned` lists DECISIONS instead — the rows a response can be reported against.\n"},"ResponseSource":{"name":"response_source","in":"query","schema":{"type":"string","enum":["api","edge","console"]},"description":"Which surface reported the answer. `console` is a response a human generated from the campaign console while testing response rules — a real touch that suppresses exactly like a customer's own answer. Rows written before this attribute existed carry no value and match no filter.\n"},"ResponsePage":{"name":"page","in":"query","schema":{"type":"integer","minimum":0,"default":0},"description":"0-based page index."},"ResponseSize":{"name":"size","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Page size. The CDP caps it at 100."},"TemplateId":{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Message template id."},"JourneyId":{"name":"journeyId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Journey id (scoped to its campaign)."},"JourneyIdTop":{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Journey id."},"NodeId":{"name":"nodeId","in":"path","required":true,"schema":{"type":"string"},"description":"Graph node id, as authored — not a uuid. It is scoped to the graph VERSION being addressed, so a node id valid on version 7 may not exist on version 8.\n"},"RunId":{"name":"runId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Journey run id (scoped to its journey)."},"RevisionNumber":{"name":"revision","in":"path","required":true,"schema":{"type":"integer","minimum":1},"description":"Revision number, 1-based per object."},"RevisionActor":{"name":"actor","in":"query","required":false,"schema":{"type":"string"},"description":"Exact match on the recorded caller identity (a user's email, or an application's api_key_hash).\n"},"RevisionAction":{"name":"action","in":"query","required":false,"schema":{"type":"string","enum":["create","update","delete","activate","pause","restore","archive","unarchive","request_approval","approve","reject","stop","approval_reset","reopen"]}},"RevisionFrom":{"name":"from","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Inclusive lower bound (RFC3339). An unparseable value is a 400 rather than an ignored filter - silently dropping it would return the whole history while looking like a narrow search.\n"},"RevisionTo":{"name":"to","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"Inclusive upper bound (RFC3339)."},"RevisionIncludeSnapshot":{"name":"include_snapshot","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Load each row's full post-change configuration. Off by default: a page of journey-graph snapshots dwarfs the changelog that displays it.\n"}},"responses":{"AIRateLimited":{"description":"The caller's AI assist budget for this minute is spent (instance setting ai_requests_per_minute, default 30). The budget is counted per tenant and caller and shared with the CDP's assist endpoints (segment translate, profile summary, AI explain, script assist, image generation, LLM provider test). Retry after the number of seconds in Retry-After.","headers":{"Retry-After":{"description":"Seconds until the next one-minute window.","schema":{"type":"integer","minimum":1,"maximum":60}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}}},"schemas":{"PreflightBasis":{"type":"string","description":"How a stage's numbers were obtained. Mandatory on every stage: a UI that renders an estimate as if it were a count is the failure this field exists to prevent.\n\n`exact` — a real count over the whole population, or a configuration fact identical for every profile. `sampled` — extrapolated from the stride sample; carries `passing_low`/`passing_high`. `assumed` — a declared assumption nobody measured (journey projections only). `unavailable` — the read behind the stage failed; the stages below continued from the population above it. `skipped` — the gate was not checked at all, which is NOT the same claim as \"nobody was dropped\".\n","enum":["exact","sampled","assumed","unavailable","skipped"]},"PreflightStage":{"type":"object","description":"One rung of the delivery gate ladder, counted over a population.","properties":{"gate":{"type":"string","description":"`audience`, then the delivery ladder's own gate names: `template`, `offer`, `profile`, `channel`, `provider`, `fatigue`, `cap`, `consent`, `device`, `contact`, `suppression`, `control_group`, `render`, `outbound`.\n"},"reason":{"type":"string","description":"The machine-readable drop code for the profiles this stage removed — the delivery path's own vocabulary (`consent_denied`, `no_contact`, `suppressed`, `fatigue`, `cap`, `control_group`, `render_failed`, `template_budget`, `code_pool_empty`, `code_pool_missing`, `outbound_off`, `not_dispatchable`).\n"},"basis":{"$ref":"#/components/schemas/PreflightBasis"},"entering":{"type":"integer","format":"int64"},"passing":{"type":"integer","format":"int64"},"dropped":{"type":"integer","format":"int64"},"pass_rate":{"type":"number","description":"The CONDITIONAL rate — of those who reached this stage, the share that survived it."},"sample_entering":{"type":"integer"},"sample_passing":{"type":"integer"},"passing_low":{"type":"integer","format":"int64","description":"Lower bound of the 95% Wilson interval on `passing` (sampled stages)."},"passing_high":{"type":"integer","format":"int64"},"exact_rate":{"type":"number","description":"The gate's MARGINAL pass rate over the whole audience, from one composed CDP count. Corroboration for a bulk-countable gate, never a substitute for the sampled conditional rate above.\n"},"correlated":{"type":"boolean","description":"The exact marginal rate fell outside the sampled conditional rate's interval. This is a FINDING, not an error: the gate is entangled with one above it, so the marginal rate does not apply to the population actually arriving here.\n"},"note":{"type":"string"},"error":{"type":"string","description":"Present when basis is `unavailable`."}},"required":["gate","basis","entering","passing","dropped"]},"PreflightReachReport":{"type":"object","properties":{"shape":{"type":"string","enum":["funnel","decision_distribution"]},"campaign_id":{"type":"string"},"campaign_type":{"type":"string"},"entity_type":{"type":"string"},"channel":{"type":"string"},"purpose":{"type":"string","description":"The X-Purpose the CDP reads behind this report were made under."},"computed_at":{"type":"string","format":"date-time"},"sample":{"type":"object","description":"How the sample was drawn. `page_stride` skips pages at a stride derived from the exact count — a naive prefix would correlate with creation time and bias every sampled stage toward the oldest profiles. `hash_mod` is the preferred draw — the CDP keeps one profile in N by a hash of the id, which is one query and a uniform sample, so the confidence intervals below are honest; `page_stride` is the fallback for a CDP that does not offer it, and is cluster sampling. `census` means the population was smaller than the request and was read whole. `errors` counts profiles whose ladder walk hit a failed read; those are EXCLUDED from every stage rather than counted as drops. `truncated` means the sample was cut short — the `preflight_sample_budget_sec` wall-clock ran out, or the caller disconnected — so `evaluated` is below `drawn` and the stages were computed from the profiles that finished; a warning says so. A spent budget never fails the request: a smaller sample, honestly labelled, beats losing a funnel that was already computed.\n","properties":{"method":{"type":"string","enum":["hash_mod","page_stride","census","none"]},"requested":{"type":"integer"},"drawn":{"type":"integer"},"evaluated":{"type":"integer"},"errors":{"type":"integer"},"page_size":{"type":"integer","format":"int64"},"stride":{"type":"integer","format":"int64"},"truncated":{"type":"boolean"},"walk_ms":{"type":"integer","format":"int64","description":"Wall clock the sampled walk spent, including its bulk prefetches."},"reads_per_profile":{"type":"number","description":"CDP round trips per evaluated profile, excluding the bulk prefetches. A DIAGNOSTIC, not a finding: around 2 means the walk is bounded by CDP latency (a larger sample needs a larger budget); 4 or more means the bulk ledger prefetches are not reaching the CDP, which no budget fixes.\n"}}},"stages":{"type":"array","items":{"$ref":"#/components/schemas/PreflightStage"}},"reached":{"type":"integer","format":"int64","description":"The population surviving the whole ladder."},"audience_estimate":{"type":"integer","format":"int64","description":"Exact number of profiles the campaign's audience matches (the funnel's first gate). Batch campaign types (one_off_batch, recurring_batch) only, absent for the others; 0 is a real empty audience.\n"},"audience_cap":{"type":"integer","description":"The operator-configured audience cap: the most profiles one batch run may match before it fails and pauses the campaign. 0 = unlimited. Compare with audience_estimate before activating a one-off batch campaign. Batch campaign types (one_off_batch, recurring_batch) only, absent for the others.\n"},"top_drops":{"type":"array","description":"The biggest losses, largest first — \"why not the rest\", in three lines.","items":{"type":"object","properties":{"gate":{"type":"string"},"reason":{"type":"string"},"dropped":{"type":"integer","format":"int64"},"share":{"type":"number"},"basis":{"$ref":"#/components/schemas/PreflightBasis"}}}},"decisions":{"type":"object","description":"Present only when shape is `decision_distribution` (inbound_offer campaigns).","properties":{"winning_offers":{"type":"array","items":{"type":"object","properties":{"offer_id":{"type":"string"},"name":{"type":"string"},"count":{"type":"integer"},"share":{"type":"number"}}}},"exclusions":{"type":"array","description":"Exclusion reasons across every candidate offer of every sampled profile.","items":{"type":"object","properties":{"reason":{"type":"string"},"count":{"type":"integer"},"share":{"type":"number"}}}},"empty_decisions":{"type":"integer","description":"Sampled profiles for which NOTHING was eligible. The number that matters: an inbound-offer campaign returning an empty decision to most callers is misconfigured.\n"},"empty_share":{"type":"number"}}},"warnings":{"type":"array","items":{"type":"string"}},"cached":{"type":"boolean","description":"The body came from the short-TTL result cache rather than a fresh run."}},"required":["shape","campaign_id","computed_at","sample","reached"]},"PreflightGateResultBase":{"type":"object","description":"One rung of the delivery ladder as it was evaluated for a single profile — the same gate vocabulary the funnel's stages use.\n","properties":{"gate":{"type":"string"},"status":{"type":"string","enum":["passed","failed","skipped","error"],"description":"`skipped` means the gate does not apply to this send, or the caller asked for it to be reported without being enforced. `error` means the gate's own read failed — distinct from a gate that evaluated to \"no\".\n"},"reason":{"type":"string","description":"Machine-readable drop code (the delivery path's own vocabulary)."},"detail":{"type":"string"}},"required":["gate","status"]},"PreflightGateResult":{"description":"A gate result whose `evidence` shape is fixed per `gate`. A gate that recorded no evidence omits the key.\n","oneOf":[{"$ref":"#/components/schemas/PreflightGateTemplate"},{"$ref":"#/components/schemas/PreflightGateOffer"},{"$ref":"#/components/schemas/PreflightGateProfile"},{"$ref":"#/components/schemas/PreflightGateChannel"},{"$ref":"#/components/schemas/PreflightGateProvider"},{"$ref":"#/components/schemas/PreflightGateSilentHours"},{"$ref":"#/components/schemas/PreflightGateFatigue"},{"$ref":"#/components/schemas/PreflightGateCap"},{"$ref":"#/components/schemas/PreflightGateResponse"},{"$ref":"#/components/schemas/PreflightGateConsent"},{"$ref":"#/components/schemas/PreflightGateDevice"},{"$ref":"#/components/schemas/PreflightGateContact"},{"$ref":"#/components/schemas/PreflightGateSuppression"},{"$ref":"#/components/schemas/PreflightGateControlGroup"},{"$ref":"#/components/schemas/PreflightGateRender"},{"$ref":"#/components/schemas/PreflightGateCoupon"},{"$ref":"#/components/schemas/PreflightGateAttachments"},{"$ref":"#/components/schemas/PreflightGateOutbound"},{"$ref":"#/components/schemas/PreflightGateRateLimit"},{"$ref":"#/components/schemas/PreflightGateCampaignStopped"}],"discriminator":{"propertyName":"gate","mapping":{"template":"#/components/schemas/PreflightGateTemplate","offer":"#/components/schemas/PreflightGateOffer","profile":"#/components/schemas/PreflightGateProfile","channel":"#/components/schemas/PreflightGateChannel","provider":"#/components/schemas/PreflightGateProvider","silent_hours":"#/components/schemas/PreflightGateSilentHours","fatigue":"#/components/schemas/PreflightGateFatigue","cap":"#/components/schemas/PreflightGateCap","response":"#/components/schemas/PreflightGateResponse","consent":"#/components/schemas/PreflightGateConsent","device":"#/components/schemas/PreflightGateDevice","contact":"#/components/schemas/PreflightGateContact","suppression":"#/components/schemas/PreflightGateSuppression","control_group":"#/components/schemas/PreflightGateControlGroup","render":"#/components/schemas/PreflightGateRender","coupon":"#/components/schemas/PreflightGateCoupon","attachments":"#/components/schemas/PreflightGateAttachments","outbound":"#/components/schemas/PreflightGateOutbound","rate_limit":"#/components/schemas/PreflightGateRateLimit","campaign_stopped":"#/components/schemas/PreflightGateCampaignStopped"}}},"PreflightGateTemplate":{"allOf":[{"$ref":"#/components/schemas/PreflightGateResultBase"},{"type":"object","properties":{"evidence":{"type":"object","description":"`template`+`onsite` when it passed; `variant` (the missing one) when it failed.","properties":{"template":{"type":"string"},"onsite":{"type":"boolean"},"variant":{"type":"string"}}}}}]},"PreflightGateOffer":{"allOf":[{"$ref":"#/components/schemas/PreflightGateResultBase"},{"type":"object","properties":{"evidence":{"type":"object","properties":{"offer_id":{"type":"string"},"offer_name":{"type":"string"}}}}}]},"PreflightGateProfile":{"allOf":[{"$ref":"#/components/schemas/PreflightGateResultBase"},{"type":"object","properties":{"evidence":{"type":"object","properties":{"entity_type":{"type":"string"},"person_key":{"type":"string"},"members":{"type":"integer"}}}}}]},"PreflightGateChannel":{"allOf":[{"$ref":"#/components/schemas/PreflightGateResultBase"},{"type":"object","properties":{"evidence":{"type":"object","properties":{"channel":{"type":"string"},"auto":{"type":"boolean"},"signal_prefix":{"type":"string"}}}}}]},"PreflightGateProvider":{"allOf":[{"$ref":"#/components/schemas/PreflightGateResultBase"},{"type":"object","properties":{"evidence":{"type":"object","properties":{"provider_id":{"type":"string"},"provider_name":{"type":"string"},"provider_type":{"type":"string"}}}}}]},"PreflightGateSilentHours":{"allOf":[{"$ref":"#/components/schemas/PreflightGateResultBase"},{"type":"object","properties":{"evidence":{"type":"object","properties":{"level":{"type":"string","enum":["node","campaign","channel","general"]},"timezone":{"type":"string"},"timezone_source":{"type":"string"},"next_open":{"type":"string","format":"date-time"},"expired":{"type":"boolean"}}}}}]},"PreflightGateFatigue":{"allOf":[{"$ref":"#/components/schemas/PreflightGateResultBase"},{"type":"object","properties":{"evidence":{"type":"object","description":"The blocking policy on a failure; the campaign type on a pass.","properties":{"policy":{"type":"string"},"max_touches":{"type":"integer"},"window_days":{"type":"integer"},"campaign_type":{"type":"string"}}}}}]},"PreflightGateCap":{"allOf":[{"$ref":"#/components/schemas/PreflightGateResultBase"},{"type":"object","properties":{"evidence":{"type":"object","properties":{"max_per_profile":{"type":"integer"},"max_per_channel":{"type":"integer"},"window_days":{"type":"integer"}}}}}]},"PreflightGateResponse":{"allOf":[{"$ref":"#/components/schemas/PreflightGateResultBase"},{"type":"object","properties":{"evidence":{"type":"object","description":"The matched rule and its count on a failure; `rule_count` on a pass.","properties":{"action":{"type":"string"},"count":{"type":"integer"},"min":{"type":"integer"},"window_days":{"type":"integer"},"rule_count":{"type":"integer"}}}}}]},"PreflightGateConsent":{"allOf":[{"$ref":"#/components/schemas/PreflightGateResultBase"},{"type":"object","properties":{"evidence":{"type":"object","properties":{"purpose":{"type":"string"},"basis":{"type":"string"},"enforced":{"type":"boolean","description":"Present (false) only when the gate was reported and not enforced (the seed send)."}}}}}]},"PreflightGateDevice":{"allOf":[{"$ref":"#/components/schemas/PreflightGateResultBase"},{"type":"object","properties":{"evidence":{"type":"object","properties":{"platform":{"type":"string","enum":["web","mobile"]},"device_identifier_key":{"type":"string"}}}}}]},"PreflightGateContact":{"allOf":[{"$ref":"#/components/schemas/PreflightGateResultBase"},{"type":"object","properties":{"evidence":{"type":"object","properties":{"kind":{"type":"string"},"identifier_keys":{"type":"array","items":{"type":"string"}},"contact_attribute":{"type":"string"},"overridden":{"type":"boolean"},"contact_profile_id":{"type":"string","description":"The person member whose contact was borrowed."}}}}}]},"PreflightGateSuppression":{"allOf":[{"$ref":"#/components/schemas/PreflightGateResultBase"},{"type":"object","properties":{"evidence":{"type":"object","properties":{"channel":{"type":"string"},"purpose":{"type":"string"}}}}}]},"PreflightGateControlGroup":{"allOf":[{"$ref":"#/components/schemas/PreflightGateResultBase"},{"type":"object","properties":{"evidence":{"type":"object","properties":{"exempt":{"type":"boolean"},"global_mode":{"type":"string"},"global_percent":{"type":"number"},"global_seed":{"type":"string"},"group":{"type":"string"},"campaign_percent":{"type":"number"},"campaign_seed":{"type":"string"}}}}}]},"PreflightGateRender":{"allOf":[{"$ref":"#/components/schemas/PreflightGateResultBase"},{"type":"object","properties":{"evidence":{"type":"object","properties":{"variant":{"type":"string"},"language":{"type":"string"}}}}}]},"PreflightGateCoupon":{"allOf":[{"$ref":"#/components/schemas/PreflightGateResultBase"},{"type":"object","description":"Records no evidence; the pool and its state are in `detail`."}]},"PreflightGateAttachments":{"allOf":[{"$ref":"#/components/schemas/PreflightGateResultBase"},{"type":"object","properties":{"evidence":{"type":"object","description":"`count`+`bytes` for resolved content attachments (`count` alone when skipped, `item_id` alone when an attachment is unresolved); `kind: document` with its template, bytes and protection for a generated document.","properties":{"kind":{"type":"string","enum":["document"]},"count":{"type":"integer"},"item_id":{"type":"string","description":"The content item an unresolved attachment pointed at."},"bytes":{"type":"integer"},"document_template_id":{"type":"string"},"password_protected":{"type":"boolean"}}}}}]},"PreflightGateOutbound":{"allOf":[{"$ref":"#/components/schemas/PreflightGateResultBase"},{"type":"object","properties":{"evidence":{"type":"object","properties":{"mode":{"type":"string"}}}}}]},"PreflightGateRateLimit":{"allOf":[{"$ref":"#/components/schemas/PreflightGateResultBase"},{"type":"object","properties":{"evidence":{"type":"object","properties":{"limit":{"type":"string","example":"10/minute"}}}}}]},"PreflightGateCampaignStopped":{"allOf":[{"$ref":"#/components/schemas/PreflightGateResultBase"},{"type":"object","properties":{"evidence":{"type":"object","properties":{"campaign_id":{"type":"string"},"stop_reason":{"type":"object","nullable":true,"additionalProperties":true},"queued_at":{"type":"string","format":"date-time"},"stopped_at":{"type":"string","format":"date-time"}}}}}]},"PreflightResolution":{"type":"object","description":"The trace that produced the message: everything the send path resolved before rendering anything.\n","properties":{"template":{"type":"string"},"channel":{"type":"string"},"channel_source":{"type":"string","enum":["campaign","request","auto"],"description":"`auto` means the send-time optimizer picked it from THIS profile's affinity signals, so another profile may render a different variant entirely.\n"},"variant":{"type":"string","description":"The template variant key the copy came from — not always the channel, since an operator-declared channel borrows a built-in variant.\n"},"provider_id":{"type":"string"},"provider_name":{"type":"string"},"provider_type":{"type":"string"},"offer_id":{"type":"string"},"offer_name":{"type":"string"},"consent_purpose":{"type":"string","description":"The purpose the send path would check, with any `{channel}` placeholder already expanded against the resolved channel.\n"},"language":{"type":"string","description":"The language whose template mutation actually rendered, as the ladder resolved it (campaign pin → profile attribute → default). Absent = the base/default copy.\n"},"onsite":{"type":"boolean","description":"An edge-served pull channel: nothing is rendered here, because Optima Edge renders at visit time in its own template language.\n"}},"required":["channel","variant"]},"PreflightContextGap":{"type":"object","description":"One template placeholder that resolved to nothing.","properties":{"path":{"type":"string","example":".Profile.Attributes.first_name"},"reason":{"type":"string","enum":["missing","empty"],"description":"`missing` — the key is not on the profile at all, usually because the attribute is not collected for this entity type. `empty` — it is collected and this person has no value.\n"},"fields":{"type":"array","description":"The variant fields that read the path (subject, body_html, …).","items":{"type":"string"}},"rate":{"type":"number","description":"The share of the sampled audience with the same gap. Present only on a population run — and it is the number that changes what the marketer writes.\n"},"affected":{"type":"integer"}},"required":["path","reason","fields"]},"PreflightRenderReport":{"type":"object","properties":{"campaign_id":{"type":"string"},"profile_id":{"type":"string"},"computed_at":{"type":"string","format":"date-time"},"resolution":{"$ref":"#/components/schemas/PreflightResolution"},"rendered":{"type":"object","additionalProperties":{"type":"string"},"description":"The variant's rendered fields — or, for an onsite channel, the UN-rendered variant, which is exactly what the entitlement carries.\n"},"data":{"type":"object","additionalProperties":true,"description":"The `{{.Data.*}}` an onsite entitlement freezes for the edge."},"context_gaps":{"type":"array","items":{"$ref":"#/components/schemas/PreflightContextGap"}},"gates":{"type":"array","description":"The ladder as it was walked, so a proof that could not be produced says which gate stopped it.\n","items":{"$ref":"#/components/schemas/PreflightGateResult"}},"sample":{"type":"object","description":"Present only on a population gap-rate run.","properties":{"method":{"type":"string"},"requested":{"type":"integer"},"drawn":{"type":"integer"},"evaluated":{"type":"integer"},"errors":{"type":"integer"}}},"warnings":{"type":"array","items":{"type":"string"}}},"required":["campaign_id","profile_id","computed_at","resolution","context_gaps","gates"]},"PreflightTraceReport":{"type":"object","properties":{"campaign_id":{"type":"string"},"profile_id":{"type":"string"},"computed_at":{"type":"string","format":"date-time"},"resolution":{"$ref":"#/components/schemas/PreflightResolution"},"outcome":{"type":"string","enum":["send","drop","retry","held_out","entitlement","sink","deferred"],"description":"The ladder's verdict. `held_out` is a control-group holdout, which is terminal but NOT a failure. `retry` means a read behind a gate failed and nothing was decided.\n"},"would_send":{"type":"boolean","description":"The single-word answer, for a console that wants one."},"reason":{"type":"string"},"code":{"type":"string"},"gates":{"type":"array","items":{"$ref":"#/components/schemas/PreflightGateResult"}},"warnings":{"type":"array","description":"Non-terminal findings: the send would go out, with these. Today only `attachment_pii` while `attachment_pii_enforce` is off.\n","items":{"type":"object","properties":{"gate":{"type":"string","example":"attachments"},"code":{"type":"string","example":"attachment_pii"},"detail":{"type":"string"},"item_id":{"type":"string","format":"uuid"}},"required":["gate","code","detail"]}},"halted_at":{"type":"string","description":"The gate that stopped the walk DESPITE `continue_after_failure` — a structural failure whose unresolved artifact the gates below would have had to judge.\n"},"halted_because":{"type":"string"},"rendered":{"type":"object","additionalProperties":{"type":"string"},"description":"The message this profile would receive, when the walk got that far."},"contact":{"type":"string","description":"The destination the send would resolve to. Present only when the caller may read it — the CDP's own PII and purpose gates already decided that when they answered the profile read.\n"}},"required":["campaign_id","profile_id","computed_at","outcome","would_send","gates"]},"PreflightTestSend":{"type":"object","description":"One row of the seed-send audit trail. Deliberately NOT a `campaign_touch`: a proof sent to an internal address never reached a customer, and recording it in the ledger would spend a real profile's contact budget.\n","properties":{"id":{"type":"string"},"campaign_id":{"type":"string"},"node_id":{"type":"string"},"requested_by":{"type":"string","description":"The session email for a user, the api-key hash for a machine caller."},"profile_id":{"type":"string"},"destination":{"type":"string","description":"The `to` override — never the profile's own contact."},"channel":{"type":"string"},"provider_id":{"type":"string"},"provider_message_id":{"type":"string"},"body_hash":{"type":"string","description":"sha256 over the rendered variant. The body itself is never stored: it is personalized customer data, and the only audit question it has to answer is answered by the hash.\n"},"outcome":{"type":"string","enum":["sent","suppressed","failed"],"description":"`suppressed` is a sandbox (`outbound_mode=sink`): rendered and recorded, transmitted to nobody.\n"},"error":{"type":"string"},"created_at":{"type":"string","format":"date-time"}},"required":["id","campaign_id","requested_by","profile_id","destination","channel","outcome","created_at"]},"PreflightTestSendResult":{"type":"object","properties":{"campaign_id":{"type":"string"},"profile_id":{"type":"string"},"to":{"type":"string"},"computed_at":{"type":"string","format":"date-time"},"resolution":{"$ref":"#/components/schemas/PreflightResolution"},"outcome":{"type":"string","enum":["sent","suppressed","failed"]},"transmitted":{"type":"boolean","description":"The fact that matters — did a provider actually accept it."},"provider_message_id":{"type":"string"},"error":{"type":"string"},"gates":{"type":"array","items":{"$ref":"#/components/schemas/PreflightGateResult"}},"rendered":{"type":"object","additionalProperties":{"type":"string"}},"recorded":{"$ref":"#/components/schemas/PreflightTestSend"},"warnings":{"type":"array","description":"Includes the consent notice — the proof went out, but the campaign would not reach this person.\n","items":{"type":"string"}}},"required":["campaign_id","profile_id","to","computed_at","outcome","transmitted","gates"]},"PreflightPathNode":{"type":"object","description":"One node's place in a journey projection.","properties":{"node_id":{"type":"string"},"node_type":{"type":"string"},"node_name":{"type":"string"},"fraction":{"type":"number","description":"Share of the ENTRY population that reaches this node."},"reaching":{"type":"integer","format":"int64","description":"That fraction applied to the entry population."},"basis":{"$ref":"#/components/schemas/PreflightBasis"},"note":{"type":"string","description":"Where the number came from — the assumption, the historical window, the exact count. For a split it also says the exactness is in EXPECTATION.\n"},"arrives_after":{"type":"string","description":"Accumulated wait from entry to this node (Go duration). A 30-day wait means the projection describes a population arriving over 30 days, not tomorrow.\n"},"unreachable":{"type":"boolean","description":"The projection never reaches this node in this graph version — a data property the DAG validator cannot see, because the SHAPE is fine.\n"},"delivery":{"allOf":[{"$ref":"#/components/schemas/PreflightReachReport"}],"description":"The send node's own delivery funnel, scaled onto the projected sub-population. Rates are unchanged (they are properties of the profiles); only the counts move.\n"}},"required":["node_id","node_type","fraction","reaching","basis"]},"PreflightJourneyReachReport":{"type":"object","properties":{"journey_id":{"type":"string"},"campaign_id":{"type":"string"},"version":{"type":"integer","description":"The PINNED graph version the projection walked."},"entity_type":{"type":"string"},"purpose":{"type":"string"},"computed_at":{"type":"string","format":"date-time"},"entry":{"type":"object","description":"The entry population and its provenance.","properties":{"trigger":{"type":"string","enum":["event","segment_entry","schedule","immediate","planned","api"]},"count":{"type":"integer","format":"int64"},"basis":{"$ref":"#/components/schemas/PreflightBasis"},"rate":{"type":"boolean","description":"The population arrives OVER a window rather than standing still — an event trigger counts profiles per N days, which is a FLOW, not a stock. Conflating the two is the mistake this field exists to prevent.\n"},"window_days":{"type":"integer"},"note":{"type":"string"},"error":{"type":"string"}},"required":["trigger","count","basis"]},"path":{"type":"array","description":"Every node the projection reaches, in graph order.","items":{"$ref":"#/components/schemas/PreflightPathNode"}},"send_nodes":{"type":"array","description":"The send nodes, each with its delivery funnel.","items":{"$ref":"#/components/schemas/PreflightPathNode"}},"unreachable":{"type":"array","description":"Send nodes the projection never reaches.","items":{"$ref":"#/components/schemas/PreflightPathNode"}},"warnings":{"type":"array","items":{"type":"string"}}},"required":["journey_id","version","computed_at","entry","path"]},"JourneySimulationStep":{"type":"object","description":"One node's simulated execution.","properties":{"node_id":{"type":"string"},"node_type":{"type":"string"},"node_name":{"type":"string"},"at":{"type":"string","format":"date-time","description":"The SIMULATED clock when this node ran, advanced by every wait — what makes a 14-day journey inspectable in one request.\n"},"branch":{"type":"string"},"outcome":{"type":"string"},"assumed":{"type":"boolean","description":"Nobody measured this outcome — a pinned or defaulted goal, a split arm chosen by weight, an unfired webhook's assumed success branch. A UI MUST render these differently from evaluated steps.\n"},"detail":{"type":"string"},"wait_for":{"type":"string"},"stale_profile":{"type":"boolean","description":"This condition was evaluated by the CDP against STORED data after an earlier profile node's writes were only simulated. Reaching those writes would need a second, client-side filter evaluator — exactly the reimplementation this design forbids — so the fact is reported instead.\n"},"error":{"type":"string"},"send":{"type":"object","description":"The send node's gate ladder and rendered message.","properties":{"outcome":{"type":"string"},"reason":{"type":"string"},"code":{"type":"string"},"channel":{"type":"string"},"gates":{"type":"array","items":{"$ref":"#/components/schemas/PreflightGateResult"}},"rendered":{"type":"object","additionalProperties":{"type":"string"}},"contact":{"type":"string"},"offer_id":{"type":"string"}}},"webhook":{"type":"object","description":"The action node's RENDERED request. Credential-bearing headers are redacted even though an inline node stores them in the graph in clear text.\n","properties":{"mode":{"type":"string","enum":["inline","system"]},"method":{"type":"string"},"url":{"type":"string"},"headers":{"type":"object","additionalProperties":{"type":"string"}},"body":{"type":"string"},"executed":{"type":"boolean"},"status":{"type":"integer"},"response":{"type":"string"}}},"profile_diff":{"type":"object","description":"The profile node's computed writes — returned, never applied.","properties":{"mode":{"type":"string","enum":["event","attribute"]},"event_type":{"type":"string"},"attributes":{"type":"object","additionalProperties":true},"error":{"type":"string"}}},"decision":{"type":"object","additionalProperties":true,"description":"The decide node's winner, as it lands in run state."},"branches":{"type":"array","description":"The parallel fan-out's sibling branches. A simulation that flattened a fan-out would silently drop branches.\n","items":{"type":"object","properties":{"from_node_id":{"type":"string"},"status":{"type":"string"},"reason":{"type":"string"},"steps":{"type":"array","items":{"$ref":"#/components/schemas/JourneySimulationStep"}}}}}},"required":["node_id","node_type","at"]},"JourneySimulation":{"type":"object","properties":{"journey_id":{"type":"string"},"version":{"type":"integer"},"profile_id":{"type":"string"},"computed_at":{"type":"string","format":"date-time"},"started_at":{"type":"string","format":"date-time"},"ends_at":{"type":"string","format":"date-time","description":"The simulated clock after the last wait."},"steps":{"type":"array","items":{"$ref":"#/components/schemas/JourneySimulationStep"}},"status":{"type":"string","enum":["completed","exited","failed","truncated"]},"reason":{"type":"string"},"state":{"type":"object","additionalProperties":true,"description":"The run state the walk produced."},"warnings":{"type":"array","items":{"type":"string"}}},"required":["journey_id","version","profile_id","computed_at","started_at","ends_at","status","state"]},"JourneyNodeRenderReport":{"type":"object","properties":{"journey_id":{"type":"string"},"node_id":{"type":"string"},"node_name":{"type":"string"},"version":{"type":"integer"},"profile_id":{"type":"string"},"computed_at":{"type":"string","format":"date-time"},"resolution":{"$ref":"#/components/schemas/PreflightResolution"},"rendered":{"type":"object","additionalProperties":{"type":"string"}},"data":{"type":"object","additionalProperties":true,"description":"The frozen {{.Data.*}} for an onsite channel."},"state":{"type":"object","additionalProperties":true,"description":"The run state the render used."},"state_source":{"type":"string","enum":["empty","supplied","simulated"],"description":"Where that state came from. `empty` is what a FRESH ENTRANT sees — a real check, and the default.\n"},"context_gaps":{"type":"array","items":{"$ref":"#/components/schemas/PreflightContextGap"}},"gates":{"type":"array","items":{"$ref":"#/components/schemas/PreflightGateResult"}},"simulation":{"allOf":[{"$ref":"#/components/schemas/JourneySimulation"}],"description":"The walk that produced the state (simulate_from_entry only)."},"warnings":{"type":"array","items":{"type":"string"}}},"required":["journey_id","node_id","version","profile_id","computed_at","resolution","state","state_source","context_gaps","gates"]},"OnsitePreflightEntitlement":{"type":"object","properties":{"journey_id":{"type":"string"},"campaign_id":{"type":"string"},"node_id":{"type":"string"},"profile_id":{"type":"string"},"computed_at":{"type":"string","format":"date-time"},"resolution":{"$ref":"#/components/schemas/PreflightResolution"},"written":{"type":"boolean","description":"Whether the entitlement row was actually inserted."},"token":{"type":"string","description":"The entitlement's serve handle — what the SDK echoes back."},"expires_at":{"type":"string","format":"date-time"},"content":{"type":"object","additionalProperties":{"type":"string"},"description":"The UN-rendered variant. Optima Edge renders it at visit time in its own template language, not this one.\n"},"data":{"type":"object","additionalProperties":true},"gates":{"type":"array","items":{"$ref":"#/components/schemas/PreflightGateResult"}},"reason":{"type":"string","description":"Why no entitlement was written (a refused gate — no tracked device, or the profile's own consent for the purpose is not granted).\n"},"recorded":{"$ref":"#/components/schemas/PreflightTestSend"},"warnings":{"type":"array","items":{"type":"string"}}},"required":["campaign_id","profile_id","computed_at","written","gates"]},"ReencryptResult":{"type":"object","properties":{"total":{"type":"integer"},"reencrypted":{"type":"integer"},"already_current":{"type":"integer"},"failed":{"type":"array","items":{"type":"string"},"description":"Ids whose blob opened under neither key or could not be stored."}}},"GenericResponse":{"type":"object","description":"Standard response envelope used by all endpoints (same contract as the CDP API).","properties":{"status":{"type":"string","example":"ok"},"message":{"type":"string","example":"segment created"},"data":{"description":"Endpoint-specific payload; absent on success-with-no-body responses."},"warnings":{"type":"array","description":"Non-fatal degradations (e.g. LLM metadata suggestion or member-count preview unavailable on /segments/suggest). The request succeeded.\n","items":{"type":"string"}},"trace":{"type":"string","description":"Stack trace, only present when the server runs in debug mode."},"page":{"$ref":"#/components/schemas/PageMeta"}},"required":["status","message"]},"CredentialsRequiredResponse":{"type":"object","description":"Returned with 409 `credentials_required` when an update changes where a stored credential would be sent (host, URL, type, protocol, network…) without re-supplying it. Re-send the request with the credential, or clear the stored one explicitly. `fields` names the destination parts that changed (DTO field names); `credentials` (instance settings only) names the secret settings to re-enter.\n","properties":{"status":{"type":"string","example":"error"},"message":{"type":"string","example":"credentials must be re-entered when the destination changes"},"data":{"type":"object","properties":{"code":{"type":"string","enum":["credentials_required"]},"fields":{"type":"array","items":{"type":"string"},"example":["base_url"]},"credentials":{"type":"array","items":{"type":"string"},"example":["smtp_pass"]}},"required":["code","fields"]}},"required":["status","message","data"]},"PageMeta":{"type":"object","description":"Pagination metadata returned alongside every list response.","properties":{"page":{"type":"integer","format":"int64"},"size":{"type":"integer","format":"int64"},"total":{"type":"integer","format":"int64"}},"required":["page","size","total"]},"QueryBuilderFilter":{"type":"object","description":"A react-querybuilder filter tree, identical to the JSON accepted by the\nCDP's `GET /profiles?filter=`. Leaf rules reference fields via the CDP\ngrammar (`profile.<attr>`, `identifier.<key>`, `event.<type>.count`,\n`consent.<purpose>`, `computed.<name>`, ...). The Campaign API\nvalidates structure (combinator, operators, namespaces) at save time;\nthe CDP re-validates against live schemas on every execution.\n\nSignal-cohort membership is a rule here —\n`{field: \"cohort.<name>\", operator: \"=\", value: true}` (or `false` to\nexclude) — which replaced the segment's old `cohort_name` field: a rule\ncan be negated and nested under any combinator, whereas the field could\nonly AND one cohort onto the whole filter. Existing values were folded\nin automatically.\n","properties":{"combinator":{"type":"string","enum":["and","or"]},"not":{"type":"boolean"},"rules":{"type":"array","items":{"type":"object","description":"A leaf rule (field/operator/value) or a nested group (combinator/rules)."}}},"required":["combinator","rules"],"example":{"combinator":"and","rules":[{"field":"profile.age","operator":">","value":30},{"field":"consent.marketing","operator":"=","value":true}]}},"Segment":{"type":"object","description":"A persisted, named audience owned by the Campaign suite.","properties":{"id":{"type":"string","format":"uuid"},"entity_type":{"type":"string","example":"customer"},"name":{"type":"string","example":"High-Value Customers"},"description":{"type":"string"},"filter":{"$ref":"#/components/schemas/QueryBuilderFilter"},"is_active":{"type":"boolean"},"folder":{"type":"string","description":"Materialized folder path; \"\" is the root. Folders are implicit — they exist because a segment names them, there is no folder CRUD.\n","example":"Lifecycle/Winback"},"tags":{"type":"array","description":"Free-form labels for cross-cutting discovery. Never null.","items":{"type":"string"},"example":["vip","q3"]},"usage":{"allOf":[{"$ref":"#/components/schemas/SegmentUsage"}],"description":"What references this segment. Present on LIST reads only — the single read is on the hot path of every send and every decide and does not pay for a count nobody asked it for."},"created_by":{"type":"string","description":"Authenticated caller identity (email or API-key hash) captured at create time."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","entity_type","name","filter","is_active","folder","tags"]},"SegmentRequest":{"type":"object","description":"Create/update body for a segment.","properties":{"entity_type":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"filter":{"$ref":"#/components/schemas/QueryBuilderFilter"},"is_active":{"type":"boolean","default":true},"folder":{"type":"string","description":"Normalised server-side: segments are trimmed, empty segments dropped, depth capped at 12 and length at 512 characters.\n","example":"Lifecycle/Winback"},"tags":{"type":"array","description":"Normalised server-side: trimmed, empties dropped, de-duplicated case-insensitively (first spelling wins), max 32 tags of 64 characters. The list is the full desired state, not a patch — omitting it on update clears the segment's tags.\n","items":{"type":"string"}}},"required":["entity_type","name","filter"]},"OrganizeFacets":{"type":"object","description":"Distinct folder paths and tags in use across one organisable resource. Returned by both /segments/facets and /campaigns/facets — the two browsers share one folder/tag component set, so the payload has one shape.\n","properties":{"folders":{"type":"array","items":{"type":"string"},"description":"Non-empty folder paths only; the root is not a facet."},"tags":{"type":"array","items":{"type":"string"}}},"required":["folders","tags"]},"SegmentUsage":{"type":"object","description":"The things that point at a segment, counted separately because they are different relationships with different consequences. Journey entry triggers can also name a segment, but they live inside a graph JSON snapshot rather than a column and are NOT counted here — a zero total means nothing in these three tables refers to it, not that nothing anywhere does.","properties":{"campaigns":{"type":"integer","format":"int64","description":"Campaigns whose audience is this segment."},"offers":{"type":"integer","format":"int64","description":"Offers gating eligibility on this segment."},"audience_syncs":{"type":"integer","format":"int64","description":"Optima Activation syncs mirroring it to an ad platform."}},"required":["campaigns","offers","audience_syncs"]},"SuggestSegmentRequest":{"type":"object","properties":{"entity_type":{"type":"string"},"description":{"type":"string","description":"Natural-language audience description.","example":"customers over 30 who purchased in the last 90 days"}},"required":["entity_type","description"]},"SuggestSegmentResponse":{"type":"object","description":"An unsaved AI-drafted segment. The filter is produced by the CDP's NL→filter translation (validated against live schemas there, and structurally re-validated here); name/description are proposed by the Campaign LLM; member_count is a live preview. Nothing is persisted — saving is an explicit POST /segments after human review.\n","properties":{"entity_type":{"type":"string"},"filter":{"$ref":"#/components/schemas/QueryBuilderFilter"},"name":{"type":"string","description":"Proposed segment name (absent when LLM metadata generation failed — see warnings)."},"description":{"type":"string"},"member_count":{"type":"integer","format":"int64","description":"Live member-count preview (absent when the preview failed — see warnings)."}},"required":["entity_type","filter"]},"FrequencyCap":{"type":"object","description":"Touch limit for a profile within ONE campaign. On a campaign it is the default cap; on a campaign-owned offer it overrides (narrows) the campaign's for that offer only.\n\nThe two limits are NESTED, not alternatives — both counts are scoped to the campaign and the per-channel one narrows further: `max_per_profile` is the campaign's total across every channel, and `max_per_channel` is the most any SINGLE channel may contribute. Either may be omitted (unlimited); with both set, both must pass — \"3 a week from this campaign, no more than 1 of them by SMS\". At least one is required, and a `max_per_channel` above `max_per_profile` is rejected because it could never apply.\n\nCaps are counted from `campaign_touch` events in the CDP: one action per message flow — `decisioned` for inbound_offer campaigns (handing the offer out is the touch), `queued` for every other type (one per outbound message attempt). Engagement echoes (opened/clicked) and sent/delivered/bounced never consume the cap, and neither do control-group holdouts or sends withheld before transmission (a `failed` touch whose reason is `fatigue`, `outbound_off`, `cap`, `silent_hours_expired`, `response_suppressed`, `campaign_stopped`, `code_pool_empty`, `code_pool_missing` or `template_budget`) — both are subtracted, because nothing reached the customer.\n\n`campaign_stopped` is the newest of those: the campaign reached a stop condition (see `stop_conditions`) after this send was queued, so delivery dropped it permanently rather than transmitting.\n\n`max_per_channel` needs a known channel, so it is enforced by the batch dispatcher, journey send nodes, decide-to-send and delivery. An NBA decide runs BEFORE the channel is resolved and therefore checks only the total.\n\nThe cap is checked TWICE: at queue time (where it also produces the `frequency_capped` decide exclusion and drives a journey send node's defer/skip/exit) and again immediately before transmission, because a send can sit through rate-limit deferrals and NAK backoff while the campaign queues more to the same profile. The delivery-time check excludes the send's own `queued` touch, so it never counts the message it is deciding about.\n","properties":{"max_per_profile":{"type":"integer","minimum":1,"description":"The campaign's total across every channel. Omit for unlimited."},"max_per_channel":{"type":"integer","minimum":1,"description":"The most any one channel may contribute to that total. Omit for unlimited. Not enforced where the channel is unknown (NBA decide).\n"},"window_days":{"type":"integer","minimum":1},"scope":{"type":"string","enum":["campaign","channel"],"deprecated":true,"description":"DEPRECATED. The legacy enum, whose two values were never alternatives — \"channel\" still counted within the campaign, so it was a per-channel sub-limit and no total could coexist with it. Still ACCEPTED on write and folded into the two limits above (`channel` becomes `max_per_channel` with no total); never returned.\n"}},"required":["window_days"]},"ResponseRule":{"type":"object","description":"Suppresses an offer once a profile has responded to it often enough. A rule matches when the profile has at least `min` `campaign_touch` events of `action` for THIS offer within the trailing `window_days`; ANY matching rule suppresses the offer (rules are never combined/ANDed). Counting is profile-scoped and offer-scoped but CAMPAIGN-BLIND — the same offer pinned to two campaigns shares one suppression history — so a rejection recorded under one campaign suppresses the offer everywhere, including catalogue decides.\n\nThere is deliberately only ONE window and no separate cool-off: without a stored per-decision row, \"suppressed until the newest matching response + N days\" would need a timestamp the exact-count fallback path (heavy profiles) does not have, so the rule would behave differently depending on how busy the profile is. What is lost is only distinguishing clustered rejections from spread-out ones.\n","properties":{"action":{"type":"string","enum":["presented","accepted","postponed","rejected","realized"]},"min":{"type":"integer","minimum":1,"description":"The count at which the rule matches."},"window_days":{"type":"integer","minimum":0,"description":"Trailing window in days. 0 means ALL TIME — how \"realized >= 1 ⇒ never offer this again\" is expressed.\n"}},"required":["action","min","window_days"]},"Campaign":{"type":"object","description":"The top-level activation container.","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","example":"summer-upsell"},"type":{"type":"string","enum":["one_off_batch","recurring_batch","journey_based","inbound_offer"]},"entity_type":{"type":"string","example":"customer"},"description":{"type":"string"},"segment_id":{"type":"string","format":"uuid","description":"Target audience; absent for pure inbound_offer campaigns."},"audience_filter":{"type":"object","description":"The campaign's OWN querybuilder conditions (react-querybuilder JSON group). The batch audience is `segment_id`'s current filter AND these conditions; either may stand alone. The segment stays a live reference — editing it still moves this campaign's audience. Absent = no conditions of its own.\n"},"catalog_id":{"type":"string","format":"uuid","description":"The campaign's DEFAULT offer source: the shared offer catalogue its decides rank over when the caller names none. A /decide body's `catalog_id` and a journey decide node's own `catalog_id` override it; absent = the campaign's own offers. Only the deciding types (inbound_offer, journey_based) may carry one.\n"},"offer_tags":{"type":"array","items":{"type":"string"},"description":"AND-filter over the default catalogue's offers (an offer must carry all of them). Applies only to `catalog_id` — a decide that brings its own catalogue brings its own tags.\n"},"status":{"type":"string","enum":["draft","active","paused","archived","completed","stopped"],"description":"`stopped` is machine-set: a stop condition was met and the campaign stopped itself, exiting every in-flight journey run. It cannot be activated directly (409); `POST /campaigns/{id}/reopen` moves it (or a `completed` one-off) back to `draft` to edit and activate again. It can also be archived. See stop_conditions.\n"},"archived_from":{"type":"string","enum":["draft","paused","completed","stopped"],"description":"The status this campaign was archived out of; present only while archived. `/unarchive` restores exactly this rather than guessing — a completed one-off must come back completed, or it becomes activatable again.\n"},"schedule_cron":{"type":"string","description":"Cron expression (recurring_batch campaigns). Required to activate one, but may be empty on a draft. Five fields; when both day of month and day of week are restricted a day matching either fires; an expression that never occurs (30 February) is refused.\n"},"schedule_timezone":{"type":"string","description":"IANA zone schedule_cron is evaluated in, stamped at save time. Empty = the dispatcher's historical local zone.\n","example":"Europe/Bratislava"},"frequency_cap":{"$ref":"#/components/schemas/FrequencyCap"},"message_template":{"type":"string","description":"message_templates.name a batch dispatch sends. Required (with channel) to activate one_off_batch/recurring_batch campaigns.\n"},"channel":{"type":"string","enum":["auto","email","sms","rcs","whatsapp","viber","push","webhook","web_banner","web_personalization","mobile_inapp"],"description":"Channel a batch dispatch sends over. \"auto\" defers the choice to send time — delivery picks the highest channel_affinity_* signal among the channels the template has a variant for AND that have an active provider (never an onsite channel), the same option a journey send node offers. Operator-declared channels take part too: they are scored on `channel_affinity_<name>` like any other, judged against the variant they borrow, and sit last in the no-signal fallback order. A pinned provider_id resolves an \"auto\" campaign to that provider's channel instead. Activation requires the template to carry a variant for at least one of email, sms, rcs, whatsapp, viber, push, webhook.\n"},"provider_id":{"type":"string","format":"uuid","description":"Channel provider instance this campaign's sends use; absent = the channel's default provider. Must serve the campaign's channel (validated at save and activation).\n"},"provider_params":{"type":"object","additionalProperties":{"type":"string"},"description":"Provider parameters carried on every send (webhook payload templates render them as {{.Params.name}}). Values are Go templates over the send context, so a parameter may be personalized; they sit UNDER the message template's own params. A journey campaign REFUSES both (400): its sends are configured per send node, which carries its own provider and parameters, and nothing on the journey path reads a campaign's.\n"},"contact_attribute":{"type":"string","description":"Profile attribute batch sends resolve the destination from instead of identifier keys; empty = identifier default. Email- and phone-addressed channels only (not push/webhook). Must be declared in the CDP contact-attribute registry (`/cdp/api/v1/privacy/contact-attributes`) with the channel's kind — either kind for `auto` or no channel yet — or the save (and activation, which re-checks it together with every active journey's send nodes, and journey activation) answers 400 with `data.code = contact_attribute_undeclared` (`data.attribute`, `data.contact_kinds`); 503 when the registry cannot be read. Also the default for decide-to-send calls that omit contact_attribute.\n"},"channel_signal_prefix":{"type":"string","description":"Which signal FAMILY resolves `channel: \"auto\"` — the delivery service takes the argmax over `<prefix><channel>` signals. Empty = `channel_affinity_`, the family the suite's own signal templates produce. A prefix rather than a signal name because \"which channel\" is answered by one value PER channel. Must end in `_`; rejected on any channel but \"auto\", where it would silently do nothing.\n"},"consent_purpose":{"type":"string","description":"Consent purpose re-checked live before EVERY send of this campaign (an offer's own consent_purpose overrides it). Whether a missing consent row blocks depends on the purpose's lawful_basis in the CDP catalog (opt-in for consent, opt-out for legitimate_interest). May carry a \"{channel}\" placeholder (e.g. \"marketing_{channel}\"), expanded against the send's RESOLVED channel — closing the channel:\"auto\" gap; at decide time the offer is excluded only when every possible expansion is denied, and activation validates that every expansion exists in the CDP purpose catalogue. The sentinel \"none\" is an explicit opt-out — DEPRECATED: prefer a real purpose with lawful_basis=legitimate_interest; \"none\" keeps working for existing campaigns. Required (purpose or \"none\") to activate one_off_batch/recurring_batch campaigns.\n"},"language":{"type":"string","description":"The campaign's language pin (\"\" / absent = resolve per profile from the tenant vocabulary's entity attribute). See CampaignRequest.language for the save/degrade semantics.\n"},"silent_hours":{"$ref":"#/components/schemas/SilentHoursSpec","description":"The campaign's do-not-send override (absent = inherit the tenant configuration; {\"disabled\": true} = opt out). Read live by the delivery gate on every deferral hop.\n"},"folder":{"type":"string","description":"Materialized folder path; \"\" is the root.","example":"Lifecycle/Winback"},"tags":{"type":"array","items":{"type":"string"},"description":"Free-form labels; always present, [] when none."},"control_group":{"type":"string","enum":["none","global","campaign"],"description":"Which control group this campaign's incremental lift is measured against: `none` (nothing of its own), `global` (the entity's global control group — no extra customers withheld), `campaign` (an ADDITIONAL automatic holdout of control_percent).\n\nIt does NOT decide whether the entity's global holdout applies — that binds every campaign; `control_exempt` is the only way out.\n"},"control_percent":{"type":"number","format":"double","minimum":0,"maximum":100,"description":"This campaign's own holdout size; control_group=campaign only."},"control_seed":{"type":"string","description":"Minted by the server on first use and preserved across edits — a change of control_percent is monotone, so a live experiment survives it.\n"},"control_exempt":{"type":"boolean","description":"Releases the campaign from the GLOBAL holdout entirely, for messaging that must reach every customer. A separate flag rather than a fourth control_group value so \"measure nothing\" and \"contact everyone\" can never be confused. Requires control_group=none.\n"},"goal":{"$ref":"#/components/schemas/CampaignGoal"},"response_rules":{"type":"array","items":{"$ref":"#/components/schemas/ResponseRule"},"description":"The DEFAULT suppression rules for offers of this campaign that declare none of their own (an offer's own rules are never merged with these — one or the other). At most 10. [] / absent = no default.\n"},"stop_conditions":{"type":"array","items":{"$ref":"#/components/schemas/StopCondition"},"description":"KPI thresholds that stop this campaign when ANY of them is met (it stays `stopped` until reopened). Absent/[] = the feature is off.\n"},"stop_state":{"$ref":"#/components/schemas/CampaignStopState"},"stopped_at":{"type":"string","format":"date-time","description":"When the last automatic stop fired; absent if the campaign was never stopped. Kept as history after a reopen (compare with `reopened_at`), so it is not by itself proof the campaign is stopped now — read `status`.\n"},"reopened_at":{"type":"string","format":"date-time","description":"When the campaign was last reopened (`POST /campaigns/{id}/reopen`); absent if it never was. Work and stop-condition counts before this moment belong to the previous launch.\n"},"stop_reason":{"$ref":"#/components/schemas/CampaignStopReason"},"created_by":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"approval_requested_by":{"type":"string","description":"Who opened the currently-open approval request; empty when none is open. A parallel dimension, not a status — a campaign can carry a standing approval (approved_by set) AND an open re-request at the same time, which is how \"approved, awaiting re-review after an edit\" is represented.\n"},"approval_requested_at":{"type":"string","format":"date-time"},"approved_by":{"type":"string","description":"Who holds the campaign's standing approval; empty when the campaign has never been approved. Cleared by a rejection, and by any change to the content it signed off: a campaign PUT that changes a field other than name/description/folder/tags, an offer or journey create/update/delete/rearm (journey activate/deactivate does not), a create/update/delete of a message template the campaign sends (as message_template or from a journey send node), and a revision restore of any of these. The edit and the reset commit in one transaction (a failed reset saves nothing). Each reset is recorded in the changelog with action `approval_reset`; status never changes.\n"},"approved_by_type":{"type":"string","enum":["user","application","root"],"description":"The kind of identity approved_by names — user, application (a service API key), or root. Empty when approved_by is empty (never approved).\n"},"approved_at":{"type":"string","format":"date-time"},"approval_rejected_by":{"type":"string","description":"Who recorded the most recent rejection; empty if no rejection is on record. A rejection stays recorded until a new decision (another approve or reject) replaces it — it is not cleared by opening a fresh approval request.\n"},"approval_rejected_at":{"type":"string","format":"date-time"},"approval_reason":{"type":"string","description":"The reason text given with the most recent rejection."},"prediction":{"allOf":[{"$ref":"#/components/schemas/Prediction"}],"description":"The advisory AI performance prediction most recently written by POST .../predict. Absent until one has been generated; never a gate on anything.\n"}},"required":["id","name","type","entity_type","status","folder","tags"]},"CampaignRequest":{"type":"object","description":"Create/update body for a campaign. Status is not settable here — lifecycle moves through POST /campaigns/{id}/activate and /pause; new campaigns start as draft. A referenced segment must exist and match the campaign's entity type.\n","properties":{"name":{"type":"string"},"type":{"type":"string","enum":["one_off_batch","recurring_batch","journey_based","inbound_offer"]},"entity_type":{"type":"string"},"description":{"type":"string"},"segment_id":{"type":"string","format":"uuid"},"audience_filter":{"type":"object","description":"The campaign's own querybuilder conditions, ANDed with the segment's filter (or standing alone with no segment_id). Structurally validated at save like a segment filter; an EMPTY group is rejected because \"no rules\" reads as \"match everything\". Omit the field to clear stored conditions. A batch campaign needs a segment_id, an audience_filter, or both to ACTIVATE.\n"},"catalog_id":{"type":"string","format":"uuid","description":"Default offer source: the shared catalogue this campaign's decides rank over when the caller names none — the offer source a caller-driven inbound_offer campaign otherwise had no way to configure. Must exist and match the campaign's entity type; an INACTIVE catalogue is accepted (parking a pool is reversible, and the decide answers an empty decision for one). Refused for one_off_batch/recurring_batch, which never decide. Omit to clear.\n"},"offer_tags":{"type":"array","items":{"type":"string"},"description":"AND-filter over the default catalogue's offers; requires catalog_id. Normalised like every tag surface (trimmed, case-insensitively deduped).\n"},"schedule_cron":{"type":"string","description":"Cron expression for recurring_batch campaigns. Five fields; when both day of month and day of week are restricted a day matching either fires; an expression that never occurs (30 February) is refused. A wall time repeated by a clock change fires once, at its first instant; a wall time skipped by one does not fire that day. Validated at save time WHEN PRESENT, but its absence is not a save-time error: a cron-less recurring campaign is a legal draft (the console edits type and schedule on separate screens, so a type switch passes through that state). Required to ACTIVATE a recurring_batch campaign, like segment/template/channel/consent_purpose.\n"},"schedule_timezone":{"type":"string","description":"IANA zone schedule_cron is evaluated in (validated at save). Empty defaults to the configuring user's profile timezone for session callers, else stays empty = the dispatcher's historical local zone.\n","example":"Europe/Bratislava"},"frequency_cap":{"$ref":"#/components/schemas/FrequencyCap"},"message_template":{"type":"string"},"channel":{"type":"string","enum":["auto","email","sms","rcs","whatsapp","viber","push","webhook","web_banner","web_personalization","mobile_inapp"],"description":"\"auto\" resolves the channel per profile at send time (see the Campaign schema); a channel-scoped frequency cap degrades to campaign scope for it, since the concrete channel isn't known when the cap is checked.\n"},"provider_id":{"type":"string","format":"uuid","description":"Pin a channel provider instance (must exist and serve `channel`); empty = the channel's default provider.\n"},"provider_params":{"type":"object","additionalProperties":{"type":"string"},"description":"A journey campaign REFUSES both (400): its sends are configured per send node, which carries its own provider and parameters, and nothing on the journey path reads a campaign's.\n"},"contact_attribute":{"type":"string","description":"Resolve batch-send destinations from this profile attribute instead of identifier keys — email- and phone-addressed channels only, i.e. not push/webhook (400 otherwise; re-checked at activation). Must be declared in the CDP contact-attribute registry with the channel's kind (400 `contact_attribute_undeclared` otherwise, 503 when the registry cannot be read).\n"},"channel_signal_prefix":{"type":"string","description":"Which signal FAMILY resolves `channel: \"auto\"` — the delivery service takes the argmax over `<prefix><channel>` signals. Empty = `channel_affinity_`, the family the suite's own signal templates produce. A prefix rather than a signal name because \"which channel\" is answered by one value PER channel. Must end in `_`; rejected on any channel but \"auto\", where it would silently do nothing.\n"},"consent_purpose":{"type":"string","description":"Consent purpose gating every send of this campaign (offer-level consent_purpose overrides). \"none\" = explicit opt-out (DEPRECATED — prefer a real purpose with lawful_basis=legitimate_interest); required to activate batch campaigns.\n"},"language":{"type":"string","description":"Pins every send of this campaign to one language mutation, skipping per-profile attribute resolution — \"this journey is the German winback\". Must exist in the tenant vocabulary at save (the stored value is grandfathered, so a language deleted from the vocabulary never blocks a resave); at send time a deleted pin degrades softly to the default copy. Omitted/\"\" = resolve per profile.\n"},"silent_hours":{"$ref":"#/components/schemas/SilentHoursSpec","description":"Overrides the tenant's do-not-send configuration for this campaign's sends, wholesale: absent/null = inherit, {\"disabled\": true} = opt out (the OTP-shaped case), else a full spec validated with the same rules as PUT /silent-hours. Enforced by delivery immediately before transmission and re-read on every deferral hop, so an edit reaches already-queued sends.\n"},"folder":{"type":"string","description":"Materialized folder path (\"Lifecycle/Winback\"); \"\" is the root. Folders are implicit — they exist because a campaign names them — and are normalised server-side (segments trimmed, empties dropped, max depth 12 / 512 characters). The list is the full desired state, not a patch: omitting it on update moves the campaign to the root.\n","example":"Lifecycle/Winback"},"tags":{"type":"array","description":"Normalised server-side: trimmed, empties dropped, de-duplicated case-insensitively (first spelling wins), max 32 tags of 64 characters. The list is the full desired state, not a patch — omitting it on update clears the campaign's tags.\n","items":{"type":"string"}},"control_group":{"type":"string","enum":["none","global","campaign"],"description":"Which control group this campaign's lift is measured against. Defaults to `none`. `campaign` requires control_percent above 0. See the Campaign schema for the full semantics.\n"},"control_percent":{"type":"number","format":"double","minimum":0,"maximum":100},"control_seed":{"type":"string","description":"Normally omitted — the server mints one on first use and keeps it across edits so a live experiment is never re-drawn.\n"},"control_exempt":{"type":"boolean","description":"Releases the campaign from the global holdout. Requires control_group=none.\n"},"goal":{"$ref":"#/components/schemas/CampaignGoal"},"response_rules":{"type":"array","items":{"$ref":"#/components/schemas/ResponseRule"},"description":"Default suppression rules for offers that declare none of their own; see the Campaign schema. At most 10.\n"},"stop_conditions":{"type":"array","maxItems":8,"items":{"$ref":"#/components/schemas/StopCondition"},"description":"KPI thresholds that stop this campaign when any of them is met (it stays `stopped` until reopened). The list is the full desired state, not a patch — omitting it or sending [] clears every condition.\n\nStopping also EXITS every in-flight journey run of the campaign: profiles currently mid-journey are dropped and will neither resume nor receive further messages. A console that offers this setting must say so before the marketer saves.\n\nValidated all-or-nothing; a malformed list answers 422 with `data.issues` of `{index, message}` pairs indexed to the offending condition. `stop_state`, `stopped_at` and `stop_reason` are runtime bookkeeping and are NOT settable here — an edit never clears them (a reopen resets `stop_state` and keeps `stopped_at` / `stop_reason` as the record of the last stop).\n"}},"required":["name","type","entity_type"]},"StopCondition":{"type":"object","description":"One automatic-stop rule. `type` selects which of the other fields apply; all four types share `op` and `value`. There is deliberately no `=` operator: a counter sampled once a minute steps past an exact value between checks.\n","properties":{"type":{"type":"string","enum":["touch_count","conversion_count","metric","rate"],"description":"`touch_count` — the campaign's own campaign_touch count for one action, over its lifetime. `conversion_count` — profiles that performed the goal event within the attribution window of their OWN touch (control-group members excluded). `metric` — the STORED last_value of an Analyze > Metrics KPI (tenant-global by design; never triggers a recompute, so staleness is that metric's own check interval). `rate` — a ratio of two touch-action counts, guarded by min_denominator.\n"},"op":{"type":"string","enum":[">=","<=",">","<"],"description":"`<` and `<=` are rejected at save time for `touch_count` and `conversion_count`: both count a lifetime total that only grows and starts at 0, so a \"less than\" condition on either would be met on the very first check and stop the campaign before it sends anything. Use `>` or `>=` for those two types; `metric` and `rate` keep all four operators. A condition stored before this rule existed is evaluated as SKIPPED, never met.\n"},"value":{"type":"number","format":"double","description":"The threshold. Must be greater than zero.","example":1000},"action":{"type":"string","description":"The counted touch action (touch_count only). Any campaign_touch action except `control_group`, which records profiles the campaign chose NOT to contact.\n","example":"clicked"},"goal":{"$ref":"#/components/schemas/CampaignGoal","description":"The conversion definition (conversion_count only). Same shape as the campaign's lift goal and the same rules, EXCEPT that engagement-flavoured events are permitted here: the lift report rejects them because a control group can never open or click, and a stop KPI has no control group.\n"},"metric_id":{"type":"string","format":"uuid","description":"The Analyze > Metrics KPI (metric only). Existence is checked against the CDP at save time; a CDP that cannot answer lets the save through with a warning rather than blocking it, but a metric the CDP positively reports as missing is rejected.\n"},"numerator":{"type":"string","description":"The counted touch action on top of the ratio (rate only).","example":"opened"},"denominator":{"type":"string","description":"The counted touch action underneath the ratio (rate only).","example":"sent"},"min_denominator":{"type":"integer","minimum":1,"description":"REQUIRED for `rate`: the sample size below which the ratio is not trusted. Without it, \"open rate under 2%\" fires on the first unopened send of a campaign that has barely started. Below the floor the condition is SKIPPED, never met.\n","example":500}},"required":["type","op","value"]},"CampaignStopState":{"type":"object","description":"The stop evaluator's most recent snapshot, written on every check — the campaign's live KPI progress (\"812 of 1,000 clicks\"). Read-only.\n","properties":{"evaluated_at":{"type":"string","format":"date-time"},"error":{"type":"string","description":"A failure that affected the whole evaluation (the touch aggregate, most often). The campaign KEEPS RUNNING: a condition that cannot be evaluated is never met.\n"},"conditions":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer","description":"Position in stop_conditions."},"type":{"type":"string"},"label":{"type":"string","example":"clicked touches >= 1000"},"op":{"type":"string"},"threshold":{"type":"number","format":"double"},"current":{"type":"number","format":"double"},"met":{"type":"boolean"},"skipped":{"type":"string","description":"Why this condition could not be evaluated (sample below min_denominator, metric never computed, read failed). A skipped condition is never met.\n"},"denominator":{"type":"integer","description":"The rate's observed sample size."},"min_denominator":{"type":"integer"}}}}}},"CampaignStopReason":{"type":"object","description":"Which condition fired, at what value, when, for the last automatic stop. Read-only; absent if the campaign was never stopped, and kept as history after a reopen (read `status` for the current state).\n","properties":{"index":{"type":"integer"},"type":{"type":"string"},"label":{"type":"string"},"op":{"type":"string"},"threshold":{"type":"number","format":"double"},"current":{"type":"number","format":"double"},"action":{"type":"string"},"metric_id":{"type":"string"},"numerator":{"type":"string"},"denominator":{"type":"string"},"stopped_at":{"type":"string","format":"date-time"},"exited_runs":{"type":"integer","description":"How many in-flight journey runs the stop terminated."}}},"Offer":{"type":"object","description":"An NBA decision candidate within a campaign.","properties":{"id":{"type":"string","format":"uuid"},"campaign_id":{"type":"string","format":"uuid","description":"Owning campaign. Exactly one of campaign_id/catalog_id is set for an offer's whole life."},"catalog_id":{"type":"string","format":"uuid","description":"Owning shared offer catalogue (see /offer-catalogs). Empty for campaign-owned offers."},"name":{"type":"string","example":"gold-upgrade"},"entity_type":{"type":"string"},"eligibility_segment_id":{"type":"string","format":"uuid","description":"Profile must be a live member of this segment to be eligible."},"eligibility_filter":{"type":"object","description":"Inline segment: a react-querybuilder tree in the same grammar saved segments use, evaluated at decide time through the same single-profile CDP probe. Absent = no inline gate; when several eligibility gates are set they are conjunctive. An offer excluded here reports reason not_matching_eligibility_filter.\n","example":{"combinator":"and","rules":[{"field":"profile.country","operator":"=","value":"SK"}]}},"eligibility_expr":{"type":"string","description":"expr-lang boolean expression over `attributes.*`, `signals.*`, `context.*` and `profile_id`. Errors at decide time fail closed (the offer is excluded with reason eligibility_expr_error). Save enforces static limits (400): predicate functions (all, any, map, filter, …) nest at most 2 deep and a literal range a..b spans fewer than 1000 elements (dynamic ranges are bounded by the runtime budget). A decide-time run over its execution budget (1 048 576 steps / 500 ms) excludes the offer with reason expr_budget.\n","example":"signals.purchase_propensity > 0.5 && attributes.country == \"SK\""},"score_signal":{"type":"string","description":"CDP signal name whose current value ranks this offer (missing value scores 0). For a CATALOGUE-owned offer, leaving BOTH score fields empty inherits the catalogue's default scoring; setting either one overrides the catalogue's pair wholesale.\n","example":"purchase_propensity"},"score_expr":{"type":"string","description":"expr-lang NUMERIC expression over `attributes.*`, `signals.*`, `context.*` and `profile_id`; when set it overrides score_signal. Compiled at save time (400 on a broken formula); a runtime error scores 0 with a decision warning — the offer still competes, it is never excluded for a scoring error, EXCEPT a run over its execution budget (1 048 576 steps / 500 ms), which excludes it with reason expr_budget. Save enforces the same static limits as eligibility_expr (400).\n","example":"signals.purchase_propensity * 2 + (attributes.tier == \"gold\" ? 10 : 0)"},"priority":{"type":"integer","description":"Manual tie-break; higher wins at equal score."},"consent_purpose":{"type":"string","description":"CDP consent purpose re-checked live at every decide; empty = no consent gate. Interpretation of a missing consent row follows the purpose's lawful_basis in the CDP catalog. Supports the \"{channel}\" placeholder (see the campaign-level consent_purpose).\n"},"payload":{"type":"object","description":"Offer content (SKU, copy, discount, ...), merged into template data downstream."},"frequency_cap":{"$ref":"#/components/schemas/FrequencyCap"},"response_rules":{"type":"array","items":{"$ref":"#/components/schemas/ResponseRule"},"description":"Suppresses THIS offer once the profile has responded to it often enough. Checked at decide (exclusion reason `response_suppressed`) and again by the delivery gate immediately before send. [] / absent = fall back to the owning campaign's response_rules as a default; at most 10.\n"},"tags":{"type":"array","items":{"type":"string"},"description":"Free-form labels; a decide node's offer_tags filter matches offers carrying ALL requested tags."},"is_active":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","name","entity_type","priority","payload","is_active"]},"OfferRequest":{"type":"object","description":"Create/update body for an offer. entity_type defaults to the parent campaign's. eligibility_expr is compiled at save time so a broken expression is rejected here with a 400, and eligibility_filter is structurally validated by the same rule a saved segment's filter goes through (a tree with no rules is stored as no filter at all).\n","properties":{"name":{"type":"string"},"entity_type":{"type":"string"},"eligibility_segment_id":{"type":"string","format":"uuid"},"eligibility_filter":{"type":"object"},"eligibility_expr":{"type":"string"},"score_signal":{"type":"string"},"score_expr":{"type":"string","description":"expr-lang numeric formula overriding score_signal; compiled at save time (400 on error, or when it breaks the static limits — see Offer.eligibility_expr)."},"priority":{"type":"integer","default":0},"consent_purpose":{"type":"string"},"payload":{"type":"object","default":{}},"frequency_cap":{"$ref":"#/components/schemas/FrequencyCap"},"response_rules":{"type":"array","items":{"$ref":"#/components/schemas/ResponseRule"},"description":"Suppresses this offer once the profile has responded to it often enough; see the Offer schema. At most 10.\n"},"tags":{"type":"array","items":{"type":"string"},"description":"Free-form labels (trimmed, case-insensitively deduped, max 32 × 64 chars)."},"is_active":{"type":"boolean","default":true}},"required":["name"]},"OfferCatalog":{"type":"object","description":"An entity-scoped, campaign-independent offer pool any campaign's decide can rank over (a decide node or /decide body names it via catalog_id). A catalogue is a container, not a policy — offers carry their own eligibility, consent purpose and frequency cap; a catalogue-owned offer's cap is GLOBAL (counted across every campaign).\n","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","example":"winback-ladder"},"entity_type":{"type":"string"},"description":{"type":"string"},"default_payload":{"type":"object","additionalProperties":true,"description":"The payload SHAPE offers in this catalogue are authored from: keys are the fields such an offer is expected to fill, values the defaults a new offer opens with (\"\" = \"just a field name\"). A template for authoring only — it seeds a NEW offer's payload in the console and is never merged into a stored offer at save or decide time, so changing it leaves existing offers untouched. {} = none.\n","example":{"sku":"","discount_pct":0}},"score_signal":{"type":"string","description":"The catalogue's DEFAULT ranking signal, inherited by every offer in it that defines no scoring of its own. \"\" = no default.\n"},"score_expr":{"type":"string","description":"The catalogue's DEFAULT ranking formula (expr-lang over attributes/signals/context), overriding score_signal in the same way an offer's does. Compiled at save time — a broken default would fail at decide for every offer inheriting it.\n"},"is_active":{"type":"boolean","description":"An inactive catalogue yields empty decisions (never failed runs)."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","name","entity_type","default_payload","score_signal","score_expr","is_active"]},"OfferCatalogRequest":{"type":"object","description":"Create/update body for an offer catalogue. entity_type is required at create and IMMUTABLE afterwards (409 on change) — live journey graphs were validated against it.\n","properties":{"name":{"type":"string"},"entity_type":{"type":"string"},"description":{"type":"string"},"default_payload":{"type":"object","additionalProperties":true,"description":"Payload template for offers authored in this catalogue (see OfferCatalog.default_payload). Must be a JSON object — anything else is a 400. OMITTED on update keeps what is stored (a client that predates the field cannot wipe it); an explicit {} clears it.\n"},"score_signal":{"type":"string","description":"Catalogue default ranking signal (see OfferCatalog.score_signal). OMITTED keeps what is stored; an explicit \"\" clears it.\n"},"score_expr":{"type":"string","description":"Catalogue default ranking formula; must compile and respect the expression static limits (400 otherwise — see Offer.eligibility_expr). OMITTED keeps what is stored (not re-checked); an explicit \"\" clears it.\n"},"is_active":{"type":"boolean","default":true}},"required":["name"]},"CatalogUsageResponse":{"type":"object","description":"What references the catalogue — the pre-delete answer: LIVE journeys naming it in a decide node, and campaigns whose DEFAULT offer source it is (campaigns.catalog_id). Either one refuses the delete with a 409 naming them. Pinned graph snapshots are deliberately not counted (they never expire and would make a catalogue permanently undeletable); a run pinned to an old snapshot naming a deleted catalogue gets an empty decision at decide time.\n","properties":{"catalog_id":{"type":"string","format":"uuid"},"journeys":{"type":"array","items":{"type":"object","properties":{"journey_id":{"type":"string","format":"uuid"},"journey_name":{"type":"string"},"campaign_id":{"type":"string","format":"uuid"},"campaign_name":{"type":"string"}}}},"campaigns":{"type":"array","description":"Campaigns that default to this catalogue (all statuses — the FK holds regardless).","items":{"type":"object","properties":{"campaign_id":{"type":"string","format":"uuid"},"campaign_name":{"type":"string"},"campaign_type":{"type":"string"}}}}}},"CatalogOfferStatsResponse":{"type":"object","description":"The cross-campaign campaign_touch funnel for ONE catalogue offer — \"how did this offer perform, regardless of which campaign asked\". by_campaign breaks the same funnel down per DECIDING campaign (keyed by campaign_id; a deleted campaign still appears under its id).\nCounted by `offer_id`. Every touch of a catalogue-owned offer ALSO carries `catalog_id` — the pool it came from, stamped by whichever process wrote the touch (decide, decide-to-send, a journey send node, delivery, the receipt consumer, the onsite consumer and pruner) — so the whole POOL can be aggregated in one analytics query without enumerating its offers first. A campaign-owned offer's touches omit the attribute entirely rather than carrying an empty one.\n","properties":{"catalog_id":{"type":"string","format":"uuid"},"offer_id":{"type":"string","format":"uuid"},"window_days":{"type":"integer"},"funnel":{"type":"array","items":{"type":"object","properties":{"action":{"type":"string"},"count":{"type":"integer"},"rate":{"type":"number","nullable":true,"description":"Fraction of this step's base within the same breakdown: queued, sent and failed are relative to queued (failed touches are drops and exhausted retries, never sent messages), every later step (delivered, bounced, opened, clicked, presented, accepted, postponed, rejected, realized) to sent. Null for decisioned and when the base is 0. Later steps can exceed 1 when opened/clicked count repeat events."}}}},"by_campaign":{"type":"object","additionalProperties":{"type":"array","items":{"type":"object","properties":{"action":{"type":"string"},"count":{"type":"integer"},"rate":{"type":"number","nullable":true,"description":"Fraction of this step's base within the same breakdown: queued, sent and failed are relative to queued (failed touches are drops and exhausted retries, never sent messages), every later step (delivered, bounced, opened, clicked, presented, accepted, postponed, rejected, realized) to sent. Null for decisioned and when the base is 0. Later steps can exceed 1 when opened/clicked count repeat events."}}}}},"by_channel":{"type":"object","additionalProperties":{"type":"array","items":{"type":"object","properties":{"action":{"type":"string"},"count":{"type":"integer"},"rate":{"type":"number","nullable":true,"description":"Fraction of this step's base within the same breakdown: queued, sent and failed are relative to queued (failed touches are drops and exhausted retries, never sent messages), every later step (delivered, bounced, opened, clicked, presented, accepted, postponed, rejected, realized) to sent. Null for decisioned and when the base is 0. Later steps can exceed 1 when opened/clicked count repeat events."}}}}},"held_out":{"type":"integer"},"truncated":{"type":"boolean","description":"True when the CDP analytics row limit cut an aggregate behind this response (the funnel or, with ?interval=, the timeline), so the counts are lower bounds. Absent when complete."}}},"DecideRequest":{"type":"object","description":"One NBA decide call. test_mode runs the full pipeline on a campaign of any status without logging decisioned touches or marking the burst dedup — a dry run for the GUI test panel.\n","properties":{"profile_id":{"type":"string","format":"uuid"},"context":{"type":"object","description":"Caller-supplied situational values available to eligibility expressions as `context.*`.","example":{"channel":"web","page":"checkout"}},"top_n":{"type":"integer","minimum":1,"maximum":50,"default":1},"test_mode":{"type":"boolean","default":false},"catalog_id":{"type":"string","format":"uuid","description":"Rank over this shared offer catalogue instead of the campaign's own offers. The campaign in the path stays required — it supplies the entity type, the campaign-level cap, the fatigue class and the campaign_id stamped on every touch. A missing, inactive or entity-mismatched catalogue yields an EMPTY decision with a warning, never an error.\nOmitted, the campaign's own `catalog_id` (its configured default offer source) applies; with neither, the campaign's own offers are ranked.\n"},"offer_tags":{"type":"array","items":{"type":"string"},"description":"AND-filter within the catalogue (offers carrying ALL these tags). Ignored without catalog_id — a request that names its own catalogue does NOT inherit the campaign's offer_tags.\n"}},"required":["profile_id"]},"CatalogDecideRequest":{"type":"object","description":"One catalogue-only NBA decide call (the catalogue id is in the path; there is no campaign anywhere in the flow). test_mode runs the full pipeline — including on an inactive catalogue — without logging decisioned touches or marking the burst dedup.\n","properties":{"profile_id":{"type":"string","format":"uuid"},"context":{"type":"object","description":"Caller-supplied situational values available to eligibility expressions as `context.*`.","example":{"channel":"web","page":"checkout"}},"top_n":{"type":"integer","minimum":1,"maximum":50,"default":1},"test_mode":{"type":"boolean","default":false},"offer_tags":{"type":"array","items":{"type":"string"},"description":"AND-filter within the catalogue (offers carrying ALL these tags)."},"channel":{"type":"string","description":"The channel the caller intends to serve the winning offer through — native or operator-declared (onsite pull channels are refused: they are entitled through a campaign, not a catalogue decide). It drives `{channel}` consent-purpose expansion, channel-scoped fatigue policies and the offer cap's per-channel limit, and is stamped on the decisioned touches. Omitted: offers whose consent purpose carries `{channel}` are excluded fail-closed (consent_denied) and channel-scoped checks skip. Onsite channels are deliberately not accepted — a catalogue-only decide hands the offer to the caller, it does not create an onsite entitlement.\n"}},"required":["profile_id"]},"Decision":{"type":"object","description":"The ranked decide result. Every returned offer already had a `decisioned` campaign_touch event logged (unless test_mode), so an immediate second decide respects the frequency cap. Exactly one of campaign_id/catalog_id is present — campaign decides (including campaign catalogue decides) carry campaign_id, catalogue-only decides carry catalog_id.\n","properties":{"campaign_id":{"type":"string","format":"uuid"},"catalog_id":{"type":"string","format":"uuid","description":"Set on catalogue-only decides (POST /nba/api/v1/offer-catalogs/{id}/decide)."},"profile_id":{"type":"string","format":"uuid"},"test_mode":{"type":"boolean"},"offers":{"type":"array","items":{"type":"object","properties":{"offer":{"$ref":"#/components/schemas/Offer"},"score":{"type":"number","description":"The offer's score_expr result when set, else the current value of its score_signal (0 when unset/missing/errored).\n"},"nba_id":{"type":"string","description":"A 26-character opaque id minted for THIS hand-out of this offer to this profile (Crockford-base32 ULID; not a token and not a stored row — possession is the capability). Hand it to whatever channel presents the offer; report what the customer did with it via `POST /campaign/api/v1/responses` or `POST /edge/v1/nba/responses`. Empty on a `test_mode` decide — a test decide writes no touch, so an id nobody could respond against would be a trap — and on a control-group holdout, which mints nothing by construction.\n"}}}},"excluded":{"type":"array","items":{"type":"object","properties":{"offer_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"reason":{"type":"string","enum":["not_in_eligibility_segment","not_matching_eligibility_filter","eligibility_expr_false","eligibility_expr_error","expr_budget","consent_denied","frequency_capped","burst_dedup","fatigue","control_group","ranked_below_top_n","response_suppressed","response_policy"]},"detail":{"type":"string","description":"For `response_suppressed`, names the matching rule's action, count and window (\"3 rejected responses in the last 90 days (limit 3)\"; window_days 0 reads \"recorded\" with no window).\n`response_policy` is the CROSS-OFFER counterpart: it appears on EVERY candidate at once (the whole decide is stopped, not one offer), and its detail additionally names the policy responsible — \"3 rejected responses in the last 14 days (limit 2, policy \\\"Cool off\\\")\".\n`expr_budget`: an eligibility or score expression exceeded its execution budget (1 048 576 steps / 500 ms); the detail names which expression.\n"}}}},"warnings":{"type":"array","items":{"type":"string"}}},"required":["profile_id","offers","excluded"]},"TemplateVariants":{"type":"object","description":"Per-channel message definitions. Field values are Go text/template strings rendered over `{Profile: {ID, Attributes, Signals}, Offer: {ID, Name, Payload}, Run: {State}}` — `email.body_html` uses html/template, so customer attribute values are HTML-escaped. Helper functions: `default` (fallback for missing values), `upper`, `lower`, `json` (safe interpolation into webhook JSON bodies), `date` (format a date-like value with a Go reference layout — `{{date \"02.01.2006\" .Profile.Attributes.birth_date}}`; unparseable values are a render ERROR, not empty output), and `{{file \"<item_id>\" \"<variant>\"}}` — resolves at render time to the opaque sealed public URL (`/edge/v1/files/<sealed>/<filename>`) of a PUBLIC content item's published variant, on any channel. A ref that cannot resolve (item missing/not public/archived, variant not in the approved surface, public file links not configured for the instance) FAILS the render — and therefore the send, as `render_failed` — with the reason in the message; the literal tag is never shipped. Missing context keys render as empty strings. Every string is parse-validated at save time.\nmobile_inapp variants are EITHER a form message (`body` required; `title`, `image_url`, `cta_label` + `cta_url`, `data` optional) OR `body_html` — raw HTML/CSS/JS in the Edge personalization language, at most 256 KB; any form field next to `body_html` is a 400. `placement` is `overlay` (default — drawn over the app in an SDK frame chosen by `position` top|bottom|center, default bottom, and `style` card|bar|modal, default card) or `inline` (drawn inside the app's `OptimaSlot` named by `slot`, then required). Style and position must agree: a `modal` takes position `center` or none, and a `bar` takes `top` or `bottom`; any other pairing is a 400.\n","properties":{"email":{"type":"object","description":"Requires subject plus at least one of body_html/body_text.","properties":{"subject":{"type":"string","example":"Hi {{default \"there\" .Profile.Attributes.first_name}}!"},"body_html":{"type":"string"},"body_text":{"type":"string"},"from_name":{"type":"string","example":"{{.Offer.Data.brand}}","description":"Optional. Overrides the provider's sender name (config `from_name`, see ChannelProvider). Rendered in the same pass as subject, then sanitized (control runes → space, collapsed whitespace, trimmed, capped at 128 runes on a rune boundary) at send. Literal (non-`{{…}}`) text containing `@` is rejected at save (400, plain message — the same template-save error as any other variant validation failure); a rendered value containing `@` is dropped at send and falls back to the provider's from_name. Empty/absent = the provider's from_name, or no display name at all (today's bare-address behaviour).\n"},"to_name":{"type":"string","example":"{{.Profile.Attributes.first_name}} {{.Profile.Attributes.last_name}}","description":"Optional. Recipient display name. Sanitized and capped at 128 runes at send like from_name, but has no `@` rule — it is the recipient's own name, shown only to them. A render that yields an empty name (e.g. the profile has no name attributes) degrades to the bare address, never `To: \" \" <jane@…>`.\n"},"reply_to":{"type":"string","example":"{{.Offer.Data.support_email}}","description":"Optional. Overrides the provider's Reply-To address. A literal value with no template actions must be exactly one bare address (mail.ParseAddress with no display name) or save rejects it (400, plain message). A templated value is checked at send; if the rendered value is not a single bare address it falls back to the provider's reply_to (and reply_to_name — see below). Reply-To always resolves as an (address, name) PAIR: the name comes from the same rung — template or provider — as the address, never mixed.\n"},"reply_to_name":{"type":"string","example":"Acme Support","description":"Optional. Display name for this variant's `reply_to`; requires a non-empty `reply_to` on the SAME variant, or save rejects it (400, plain message) — a template name is never paired with the provider's Reply-To address. Literal text containing `@` is rejected at save (400, plain message); a rendered value containing `@` is dropped at send (the address still applies, unnamed).\n"}}},"sms":{"type":"object","properties":{"body":{"type":"string"}},"required":["body"]},"rcs":{"type":"object","description":"RCS Business Messaging. body alone sends a text message; setting card_title or media_url promotes it to a rich card on providers that support one (Infobip). The Twilio provider folds card_title/card_description into the message text.\n","properties":{"body":{"type":"string"},"media_url":{"type":"string","description":"https URL of an image/video"},"card_title":{"type":"string"},"card_description":{"type":"string"}},"required":["body"]},"whatsapp":{"type":"object","description":"WhatsApp. At least one of template_name or body is required. Business-initiated messages MUST use an approved template (template_name = the Meta template name, or the Twilio Content SID \"HX...\" on the twilio provider); a bare body is only delivered inside the 24h customer-service window. template_params renders to either a JSON array (`[\"Ada\", \"42\"]`) or a pipe-separated list (`Ada|42`) and fills the template's positional variables in order. template_language/template_params require template_name.\n","properties":{"body":{"type":"string"},"template_name":{"type":"string","example":"order_update"},"template_language":{"type":"string","example":"en_US"},"template_params":{"type":"string","example":"[\"{{.Profile.Attributes.first_name}}\", \"42\"]"},"media_url":{"type":"string","description":"header image for a template send; standalone image otherwise"}}},"viber":{"type":"object","description":"Viber Business Messages. image_url switches to an image message with body as the caption; button_text requires button_url.\n","properties":{"body":{"type":"string"},"image_url":{"type":"string"},"button_text":{"type":"string"},"button_url":{"type":"string"}},"required":["body"]},"push":{"type":"object","description":"Mobile push (FCM v1 / APNs). title and body are the alert; everything else is the optional rich block, and what a device does with it differs per platform: `image_url` (absolute http(s)) is native on Android — on iOS the payload only sets `mutable-content` and carries the URL as a custom key, so the app needs a Notification Service Extension to show it; `deep_link` is not opened by either OS — it rides in the data payload (FCM data / APNs custom key) and the APP routes it on tap; `buttons` (JSON array of `{id, label, deep_link}`, max 4) is likewise data — iOS action buttons come from the UNNotificationCategory named by `category`, which is registered in the app, and Android actions are built by an app that renders from data; `data` is a FLAT JSON object of STRING values (FCM's data payload is a string map) and may not use the reserved keys aps, deep_link, image_url, buttons, notification, google, gcm; `badge` is a non-negative integer (0 CLEARS the badge), `ttl_hours` a positive integer (FCM android.ttl / APNs apns-expiration), `priority` one of high/normal (FCM android.priority HIGH/NORMAL / APNs apns-priority 10/5). `collapse_key` (printable ASCII, <= 64 bytes after render) makes a newer push replace an older one with the same key — FCM `android.collapse_key` and APNs `apns-collapse-id`; `thread_id` groups iOS notifications (`aps.thread-id`). A variant with only title and body produces exactly the payload it did before the rich block existed.\n","properties":{"title":{"type":"string"},"body":{"type":"string"},"image_url":{"type":"string","description":"absolute http(s) URL the device downloads"},"deep_link":{"type":"string","example":"myapp://orders/{{.Profile.Attributes.order_id}}"},"data":{"type":"string","description":"flat JSON object of string values","example":"{\"order_id\": \"{{.Profile.Attributes.order_id}}\"}"},"buttons":{"type":"string","description":"JSON array of {id, label, deep_link}, max 4","example":"[{\"id\": \"track\", \"label\": \"Track order\", \"deep_link\": \"myapp://track\"}]"},"category":{"type":"string","description":"iOS UNNotificationCategory identifier registered in the app","example":"ORDER_UPDATE"},"sound":{"type":"string","example":"default"},"badge":{"type":"string","description":"non-negative integer; 0 clears the badge","example":"1"},"ttl_hours":{"type":"string","example":"24"},"priority":{"type":"string","enum":["high","normal"]},"collapse_key":{"type":"string","maxLength":64,"description":"newer pushes with the same key replace older ones (FCM collapse_key + APNs apns-collapse-id); printable ASCII, max 64 bytes after render","example":"order-{{.Profile.Attributes.order_id}}"},"thread_id":{"type":"string","description":"iOS notification grouping (aps.thread-id)","example":"orders"}},"required":["title","body"]},"webhook":{"type":"object","description":"JSON body POSTed to the `_webhook_url` given in the send data, HMAC-SHA256 signed (X-Optima-Signature). Use the `json` helper to interpolate values safely.\n","properties":{"body":{"type":"string","example":"{\"name\": {{json .Profile.Attributes.first_name}}}"}},"required":["body"]}}},"MessageTemplate":{"type":"object","description":"A reusable message template from the template library.","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","example":"welcome-email"},"entity_type":{"type":"string","example":"customer"},"description":{"type":"string"},"variants":{"$ref":"#/components/schemas/TemplateVariants"},"channels":{"type":"array","items":{"type":"string"},"description":"The OPERATOR-DECLARED channels this template was authored for. The copy itself lives under the variant schema each of them borrows (several declared channels can share one), so this records intent, not storage: it reopens the console on the channel the author picked and makes `?channel=<declared>` an exact match. Empty = authored against the built-in variant.\n"},"params":{"type":"object","additionalProperties":{"type":"string"},"description":"Declared-parameter VALUES this template supplies to an http provider (the webhook channel, an in-house gateway, an operator-declared channel). The provider owns the request — URL, method, auth, headers and a payload template rendering `{{.Params.name}}` — so on such a channel the template's job is the parameters, not a body. Values are Go templates over the send context, so a parameter can be personalized. Precedence, narrowest wins: provider defaults < these < the send node's / campaign's own `params`.\n"},"design":{"$ref":"#/components/schemas/TemplateDesign"},"attachments":{"$ref":"#/components/schemas/TemplateAttachments"},"track_clicks":{"type":"boolean","nullable":true,"description":"Email-tracking tri-state. `null`/absent = inherit the instance setting `email_click_tracking`; `true`/`false` pins this template either way. When effective, every eligible link in the rendered email `body_html` is rewritten to a sealed tracking redirect (`/edge/v1/c/{token}`) and clicks log a `campaign_touch action=clicked` with the target `url` attribute. Email channel only; on a PUT the field is a plain value — omitting it resets the override to inherit.\n"},"track_opens":{"type":"boolean","nullable":true,"description":"Email-tracking tri-state for the open pixel: `null`/absent = inherit `email_open_tracking`; `true`/`false` pins this template. When effective, rendered email HTML gets a 1×1 tracking image (`/edge/v1/o/{token}`) and fetches log a `campaign_touch action=opened`. Same PUT semantics as `track_clicks`.\n"},"design_stale":{"type":"array","items":{"type":"string"},"description":"Computed on the single-template read only. Variant keys whose stored `design[v].compiled_sha256` no longer matches `sha256(variants[v].body_html)` — i.e. some writer (an API script, the AI copy generator, a configuration rollback) changed the HTML without the design following. The console resolves it by asking the marketer — keep the HTML (drop the design) or reopen the design (recompile on save) — never by guessing. Absent when nothing is stale.\n"},"variants_i18n":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/TemplateVariants"},"description":"Per-language mutations: language value → a variants document validated with exactly the base column's rules. The base `variants` ARE the mandatory default-language mutation; a mutation substitutes one whole (language, channel) cell and a missing cell falls back to the base variant — fields are never merged across languages. A mutation may only override channel variants the base carries. `{}` = no mutations.\n"},"design_i18n":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/TemplateDesign"},"description":"Per-language visual-builder designs: language value → a design document with the base `design` column's exact contract (server-stamped `compiled_sha256` against that LANGUAGE's mutation, never an input to rendering). `{}` = none.\n"},"design_stale_i18n":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Computed on the single-template read only: language → the variant keys whose `design_i18n` stamp no longer matches the mutation's current `body_html`. Absent when nothing is stale.\n"},"is_active":{"type":"boolean"},"created_by":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","name","entity_type","variants","is_active"]},"TemplateDesign":{"type":"object","description":"The visual-builder design document, keyed by variant (only `email` today). The design is what the EDITOR reopens — MJML is not reversible from compiled HTML — and it is never an input to rendering: `variants[v].body_html` stays the only thing the send path, previews and the pre-flight proof read. Compilation happens in the browser (mjml-browser); the server validates shape and size only (instance setting `template_design_max_bytes`, default 512 KB) and never compiles MJML. `{}` = no visual design (HTML-mode variants lose nothing and stay supported forever).\n","additionalProperties":{"type":"object","properties":{"format":{"type":"string","enum":["mjml"],"description":"The design language."},"source":{"type":"string","description":"The design document itself (MJML markup)."},"compiled_sha256":{"type":"string","description":"STAMPED BY THE SERVER on every write as `sha256(variants[v].body_html)`; any client-supplied value is overwritten. The staleness anchor for `design_stale`.\n"},"builder":{"type":"string","example":"grapesjs-mjml@1.0.8","description":"The builder/component-set version that produced the source."}},"required":["format","source"]}},"DocumentTemplate":{"type":"object","description":"A frame + flow PDF document definition (Feature B). `layout` is the engine's JSON: `style` (page size A4/letter, base font size, palette, brand TTF content items — the embedded Noto Sans answers where no font is named), `frame` (`first_page` / `continuation_page`, each with full-bleed `background` artwork — a designed PDF page or PNG/JPEG — and absolutely-positioned mm `fields`), `content_box` (the mm rectangle the flow lives in) and `blocks` (heading / paragraph / kv_table / table-with-`rows_from` / image / spacer / divider / columns; overflow breaks the page, stamps the continuation frame and repeats table headers). Every text field is a Go template over the same send context message copy uses.\n\nA `columns` block places content side by side: `cols` is a list of `{width, blocks}` (width in mm; 0 shares whatever the fixed columns and `gap` leave, split evenly among the 0-width columns — the same convention table columns use) and `gap` is the mm between adjacent columns (default 5). The JSON key is `cols`, not `columns`, because `columns` is already the table-column list on the same block. 2 to 6 columns; a column needs at least one block; columns CANNOT nest. A columns block must fit on ONE page — if a column overflows, the render fails naming the block rather than letting the columns break onto different pages and destroy the alignment the block exists to create.\n","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string"},"entity_type":{"type":"string"},"layout":{"type":"object"},"password_template":{"type":"string","description":"Renders per recipient into the AES-256 user password (`date` helper available for birthdate-derived passwords). Empty = unprotected; set-but-renders-empty FAILS the operation (`document_password_empty`). Passwords are never stored. Honest limit: a birthdate-derived password is low-entropy — bank-statement-grade protection, not cryptographic secrecy.\n"},"public_filename":{"type":"string","description":"Exposed-filename template of the sealed public link a generated document is served under ({yyyy} {yy} {mm} {dd} + literals; empty = \"document.pdf\").\n"},"is_active":{"type":"boolean"},"created_by":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","name","entity_type","layout","is_active"]},"DocumentRequest":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"entity_type":{"type":"string"},"layout":{"type":"object"},"password_template":{"type":"string"},"public_filename":{"type":"string"},"is_active":{"type":"boolean","default":true}},"required":["name","entity_type","layout"]},"DocumentPreviewRequest":{"type":"object","properties":{"layout":{"type":"object"},"password_template":{"type":"string"},"profile_id":{"type":"string","format":"uuid","description":"Preview against a REAL profile: read live from the CDP under the request's X-Purpose, exactly as /documents/{id}/render does. REPLACES `attributes`/`signals` when both are sent — merging would let a hand-typed value stand in for one the real profile lacks, which is the failure this mode exists to reveal. Unknown profile = 404."},"attributes":{"type":"object","description":"Hand-written profile attributes, for previewing a template before any matching profile exists. Ignored when `profile_id` is set."},"signals":{"type":"object","description":"Hand-written signals. Ignored when `profile_id` is set."},"payload":{"type":"object"},"state":{"type":"object","description":"Exposed as {{.Run.State.*}} — the document's own body (invoice lines, statement rows). Always hand-written: there is no profile for it to come from, so `profile_id` does not affect it."},"params":{"type":"object","additionalProperties":{"type":"string"}}},"required":["layout"]},"DocumentRenderRequest":{"type":"object","properties":{"profile_id":{"type":"string","format":"uuid"},"values":{"type":"object","description":"Raw values exposed as {{.Run.State.*}} — arrays feed table blocks."},"params":{"type":"object","additionalProperties":{"type":"string"}}}},"TemplateAttachments":{"type":"array","description":"Content-Manager file refs the EMAIL channel attaches to every send of this template (other channels link files in the body instead, with `{{file}}`). The Content Manager is the ONLY attachment source: a template references an item and one variant of its published (approved) surface; there are no ad-hoc per-template uploads. Validated at save — the item must exist with the variant in its frozen `published_variants` pin map, the caller's `pii_access_level` must cover the item's `pii_level` (403 otherwise), and the count/total-declared-size caps apply (instance settings `campaign_attachment_max_count`, default 5, and `campaign_attachment_max_mb`, default 10) — and re-resolved live at send time, so an item unpublished after the save fails the send (`attachment_unresolved`) rather than shipping unapproved bytes. At send time every attached content item, and every content item a document's layout uses, is also held to the Campaign service application's `pii_access_level`. While the instance setting `attachment_pii_enforce` is off (the default), an item above it only produces an `attachment_pii` warning: in the pre-flight trace's `warnings`, the test send's `warnings`, and a reach-report count. The send still goes out. With the setting on, the send fails (`attachment_pii`). `kind: document` references a document template (validated: exists and active, AND every content item its own stored layout references — backgrounds, images, fonts — must carry a PII level the caller's `pii_access_level` covers, 403 otherwise): the PDF is GENERATED per recipient at send time — on email it travels as a true attachment; on every other channel the FIRST document ref becomes an opaque sealed download link the body references as `{{.Document.URL}}`. Every generated document is stored (ledger + object) and expires after `campaign_document_ttl_days`. A set-but-empty-rendering password template fails the send (`document_password_empty`). A document that prints a profile attribute the CDP withheld from the service application fails the send (`document_redacted_data`) instead of rendering a blank. Templates and layouts can test for that with `{{redacted \"<attribute>\"}}` (true when withheld), e.g. `{{if redacted \"first_name\"}}customer{{else}}{{.Profile.Attributes.first_name}}{{end}}`. In message bodies a withheld attribute still renders empty. Empty = no attachments.\n","items":{"type":"object","properties":{"kind":{"type":"string","enum":["content","document"]},"item_id":{"type":"string","format":"uuid","description":"The content item (`kind: content`)."},"variant":{"type":"string","description":"A variant name present in the item's published pin map."},"document_id":{"type":"string","description":"The document template to generate (`kind: document`)."},"filename":{"type":"string","description":"Optional exposed-filename override; defaults to the pinned rendition's upload filename. Plain filenames only (no path separators, quotes or control characters, max 128 chars).\n"}},"required":["kind"]}},"TemplateRequest":{"type":"object","description":"Create/update body for a message template. Rejected with 400 when any variant fails validation (unknown channel/field, missing required field, template parse error).\n`variants` may be EMPTY when `params` are supplied: on a channel whose http provider carries a payload template the provider owns the whole request and the template's job is the declared parameters that payload interpolates. A template with neither copy nor parameters is a 400. Whether such a template may be SENT on a given channel is decided where the provider is known — campaign activation, journey validation, direct send and the delivery ladder all waive the variant requirement exactly where the channel's active http provider owns the payload.\n","properties":{"name":{"type":"string"},"entity_type":{"type":"string"},"description":{"type":"string"},"variants":{"$ref":"#/components/schemas/TemplateVariants"},"channels":{"type":"array","items":{"type":"string"},"description":"Operator-declared channels only. A name this tenant has not declared is a 400, and so is a BUILT-IN channel name — that is already recorded as the variant key, and storing it twice would let the two disagree. If the CDP's channel registry cannot be read the save is a **503**, not a 400: the name may well be declared, and blaming the author for an upstream failure sends them looking for a declaration they already made.\n"},"params":{"type":"object","additionalProperties":{"type":"string"},"description":"Declared-parameter VALUES this template supplies to an http provider (the webhook channel, an in-house gateway, an operator-declared channel). The provider owns the request — URL, method, auth, headers and a payload template rendering `{{.Params.name}}` — so on such a channel the template's job is the parameters, not a body. Values are Go templates over the send context, so a parameter can be personalized. Precedence, narrowest wins: provider defaults < these < the send node's / campaign's own `params`.\n"},"design":{"$ref":"#/components/schemas/TemplateDesign","description":"OMITTING this field on an update carries the stored design forward UNCHANGED — hash included — which is what lets a design-unaware writer edit `body_html` without deleting the canvas (the mismatch surfaces as `design_stale` on the next read). An explicit `{}` (or `null`) deletes the design — the visual→HTML conversion, which keeps the compiled `body_html`.\n"},"attachments":{"$ref":"#/components/schemas/TemplateAttachments","description":"FULL REPLACE on update (unlike `design`): absent or empty means the template carries no attachments. 400 on a ref that fails validation, 403 when an item's PII level exceeds the caller's access level.\n"},"variants_i18n":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/TemplateVariants"},"description":"Per-language mutations. Every cell is validated with the base `variants` rules; each language must exist in the tenant vocabulary (`/campaign/api/v1/languages`) and must not be the default (the base variants ARE the default's copy) — except languages the stored row already carries, which are GRANDFATHERED so a language deleted from the vocabulary never blocks a resave (soft deletion). A mutation may only override channel variants the base carries. PRESERVE-ON-OMIT like `design`: omitting the field on an update carries the stored mutations forward unchanged; an explicit `{}` clears them.\n"},"design_i18n":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/TemplateDesign"},"description":"Per-language visual designs, stamped server-side against each language's own mutation. Same preserve-on-omit semantics as `design`/`variants_i18n`.\n"},"track_clicks":{"type":"boolean","nullable":true,"description":"Email-tracking tri-state: `null`/absent = inherit the instance setting `email_click_tracking`, `true`/`false` pins this template. Plain value on update (unlike `design`) — omitting it resets the override to inherit.\n"},"track_opens":{"type":"boolean","nullable":true,"description":"Open-pixel tri-state: `null`/absent = inherit `email_open_tracking`, `true`/`false` pins this template. Same update semantics as `track_clicks`.\n"},"is_active":{"type":"boolean","default":true}},"required":["name","entity_type"]},"RenderTemplateRequest":{"type":"object","description":"Preview one channel variant. With profile_id set, the profile's live attributes/signals are fetched via the CDP (X-Purpose forwarded); otherwise the sample maps are used as-is.\n","properties":{"channel":{"type":"string","description":"Native or operator-declared; a declared channel renders the built-in variant it borrows.\n"},"profile_id":{"type":"string","format":"uuid"},"attributes":{"type":"object","description":"Sample Profile.Attributes (ignored when profile_id is set)."},"signals":{"type":"object","description":"Sample Profile.Signals (ignored when profile_id is set)."},"payload":{"type":"object","description":"Sample Offer.Payload."},"state":{"type":"object","description":"Sample Run.State."},"language":{"type":"string","description":"Renders that language's mutation cell when the template carries one for the channel, and falls back to the base variants otherwise — the exact send-time cell rule. The response's `data.language` reports which copy actually rendered (\"\" = the base/default). When omitted and `profile_id` is set, the profile's preferred language is used, as a send would; with neither, the default copy.\n"}},"required":["channel"]},"TemplatePreviewRequest":{"type":"object","description":"Preview UNSAVED template text over a sample (or live) send context. `fields` maps field name → ad-hoc template source. With `profile_id` set, the profile's live attributes/signals are fetched via the CDP (X-Purpose forwarded) and the sample attributes/signals are ignored. The remaining maps fill the payload-template roots available to http providers (`.Params`, `.Content`, `.Contact`) and the preference links (`.Unsubscribe.URL` / `.Unsubscribe.OneClickURL`).\n","properties":{"channel":{"type":"string","description":"Optional. Routes field escaping exactly as delivery would (html/template for email body_html); a declared channel renders as the variant it borrows. Omit for single-value inputs (plain text/template). Onsite channels are refused with 422.\n"},"fields":{"type":"object","additionalProperties":{"type":"string"},"minProperties":1,"maxProperties":64,"description":"Field name → template source. At least one entry and at most 64 — each field is a separate render under its own time and output budget; more is a 400.\n"},"profile_id":{"type":"string","format":"uuid"},"attributes":{"type":"object","description":"Sample Profile.Attributes."},"signals":{"type":"object","description":"Sample Profile.Signals."},"payload":{"type":"object","description":"Sample Offer.Payload."},"state":{"type":"object","description":"Sample Run.State."},"params":{"type":"object","additionalProperties":{"type":"string"},"description":"Sample .Params (http-provider payload templates)."},"content":{"type":"object","additionalProperties":{"type":"string"},"description":"Sample .Content (already-rendered variant fields)."},"contact":{"type":"string","description":"Sample .Contact (resolved destination)."},"unsubscribe":{"type":"object","properties":{"url":{"type":"string"},"one_click_url":{"type":"string"}}}},"required":["fields"]},"GenerateCopyRequest":{"type":"object","description":"Ask the LLM for message-copy drafts. Drafts are parse-validated against the channel's variant schema and returned unsaved — template creation stays an explicit call.\n\nThe onsite channels (web_banner, web_personalization, mobile_inapp) are drafted in the Optima Edge personalization language (`.Attributes.x`), since they render at serve time, and cover the message only: the banner's `slot`, a personalization's CSS selectors and a CTA's URL are operator knowledge and are never drafted. web_banner and web_personalization return `body_html`, mobile_inapp `title` + `body`.\n\nEmail is the only channel with more than one authoring surface, so it takes a `format` naming which one — see that field.\n","properties":{"channel":{"type":"string","enum":["email","sms","rcs","whatsapp","viber","push","webhook","web_banner","web_personalization","mobile_inapp"]},"brief":{"type":"string","description":"What the message should say/achieve.","example":"Win back customers who abandoned a cart this week; 15% code SAVE15."},"tone":{"type":"string","example":"playful"},"format":{"type":"string","enum":["text","html","mjml"],"default":"text","description":"The email body LANGUAGE to draft in — which is the same thing as which editor the author has open. `text` returns `subject` + `body_text`, `html` returns `subject` + a complete self-contained HTML email under `body_html`, and `mjml` returns `subject` + an MJML document under **`body_mjml`**.\n\n`body_mjml` is deliberately NOT a variant field: it is a DESIGN (the console reopens its visual canvas on it and the browser compiles `body_html` from it at save time — see MessageTemplate `design`), so nothing on the send path may read it. It is still validated through the same `html/template` parse its compiled output will face, plus a structural check that it is an MJML document.\n\nEmail only — any other value than `text` on another channel is a 400, since those channels have exactly one authoring surface.\n"},"placeholders":{"type":"array","description":"Template paths the copy may use verbatim inside {{ }}, in the dialect the channel renders in (`.Profile.Attributes.x` for delivery channels, `.Attributes.x` for onsite ones).\n","items":{"type":"string"},"example":[".Profile.Attributes.first_name",".Offer.Payload.code"]},"count":{"type":"integer","minimum":1,"maximum":5,"default":2}},"required":["channel","brief"]},"SendOfferRequest":{"type":"object","description":"Explicit dispatch of an already-decisioned offer. The template name resolves in order: this body's `template`, the offer payload's \"template\" key, the campaign's message_template.\n","properties":{"profile_id":{"type":"string","format":"uuid"},"channel":{"type":"string","description":"Native, operator-declared, or an onsite pull channel — the deliverable set is native ∪ the CDP's delivery_channels registry, which OpenAPI cannot enumerate.\n"},"template":{"type":"string"},"contact_attribute":{"type":"string","description":"Resolve the destination (email address / phone number) from this profile attribute instead of the channel's identifier keys. Must be declared in the CDP contact-attribute registry with the channel's kind (400 `contact_attribute_undeclared` otherwise). Email- and phone-addressed channels only, i.e. not push/webhook (400 otherwise); no identifier fallback: a missing/empty attribute fails the send with a `failed` touch naming the attribute.\n"},"data":{"type":"object","description":"Extra render context (Run.State). Webhook sends may read the destination from `_webhook_url` here (used when the webhook provider has no URL of its own).\n"},"provider":{"type":"string","format":"uuid","description":"Channel provider instance for this send; empty falls back to the campaign's provider_id (when its channel matches), then the channel's default provider. Must serve `channel` and be active (400 otherwise).\n"},"params":{"type":"object","additionalProperties":{"type":"string"},"description":"Provider parameters merged over the campaign's provider_params (webhook payload templates render them as {{.Params.name}}).\n"}},"required":["profile_id","channel"]},"OnsiteDelivery":{"type":"object","description":"One onsite pull-channel content entitlement: written by delivery instead of a provider call, served by Optima Edge when the profile's device next shows up. Holds NO customer data — content is the un-rendered template variant, data the campaign-frozen {{.Data.*}} values, and hold_filter the querybuilder tree pinned at deliver time and re-evaluated live on every serve.\n","properties":{"id":{"type":"string","format":"uuid"},"token":{"type":"string","description":"Unguessable serve/report handle the SDK echoes back."},"profile_id":{"type":"string"},"campaign_id":{"type":"string","format":"uuid"},"journey_id":{"type":"string","format":"uuid"},"journey_run_id":{"type":"string","format":"uuid"},"offer_id":{"type":"string","format":"uuid"},"catalog_id":{"type":"string","format":"uuid","description":"The shared offer catalogue offer_id belongs to; empty for a campaign-owned offer. Carried so the feedback touches written from this row attribute the same pool the `decisioned` touch did.\n"},"channel":{"type":"string","enum":["web_banner","web_personalization","mobile_inapp"]},"node_id":{"type":"string","description":"Journey send node that produced the entitlement ('' for batch/decide flows)."},"origin":{"type":"string","enum":["campaign","preflight"],"description":"`campaign` is a real delivery; `preflight` is an operator's proof. A preflight row is served and its interaction state tracked identically, but it writes NO campaign_touch — a tester viewing their own proof must not move a live campaign's numbers.\n"},"purpose":{"type":"string"},"consent_purpose":{"type":"string","description":"Resolved ({channel}-expanded) purpose re-checked live at serve."},"content":{"type":"object","description":"Un-rendered template variant (fields, targeting globs, display block)."},"data":{"type":"object","description":"Campaign-frozen values exposed to the template as {{.Data.*}}."},"hold_filter":{"type":"object","nullable":true,"description":"Pinned querybuilder tree; null serves unconditionally for the TTL."},"state":{"type":"string","enum":["active","delivered","clicked","dismissed","expired"],"description":"Customer-interaction state only — consent and the hold condition are evaluated fresh on every serve, never stored.\n"},"impressions":{"type":"integer"},"max_impressions":{"type":"integer"},"stop_on_click":{"type":"boolean"},"delivered_at":{"type":"string","format":"date-time","nullable":true},"expires_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"ControlGroupSettings":{"type":"object","description":"One entity type's GLOBAL control group — the profiles held out from every campaign for that entity type.\n","properties":{"entity_type":{"type":"string"},"mode":{"type":"string","enum":["off","rule","auto"],"description":"`rule` = membership is the filter below (TRUE ⇒ in control); `auto` = membership is a deterministic bucket under `percent`.\n"},"filter":{"type":"object","description":"querybuilder tree; `rule` mode only."},"percent":{"type":"number","format":"double","minimum":0,"maximum":100,"description":"Holdout size (two decimals); `auto` mode only."},"seed":{"type":"string","description":"Rotating this re-draws the holdout from scratch and invalidates every prior lift number for the entity type.\n"},"description":{"type":"string"},"updated_at":{"type":"string","format":"date-time"},"updated_by":{"type":"string"}}},"ControlGroupSettingsRequest":{"type":"object","required":["mode"],"properties":{"mode":{"type":"string","enum":["off","rule","auto"]},"filter":{"type":"object"},"percent":{"type":"number","format":"double","minimum":0,"maximum":100},"seed":{"type":"string"},"description":{"type":"string"},"rotate_seed":{"type":"boolean","description":"Mint a fresh seed, re-drawing the holdout. An explicit opt-in rather than a side effect of editing, because it invalidates every prior measurement.\n"}}},"CampaignGoal":{"type":"object","description":"A campaign's success definition for the lift report — an OUTCOME the control group can also exhibit.\n\nDeliverability, opens and clicks are deliberately NOT goal types: a control group receives nothing, so lift against them is 100% by construction. They stay on the engagement funnel as campaign performance.\n","required":["type","window_days"],"properties":{"type":{"type":"string","enum":["event"],"description":"Only `event` is supported. `attribute` and `signal` outcomes are conceptually valid but have no exact evaluation route yet.\n"},"event_type":{"type":"string"},"filter":{"type":"object","description":"Narrows which events of that type count — \"a purchase over 50\" rather than any purchase. A querybuilder tree in the analytics ROW-NATIVE grammar, whose fields are the goal event type's OWN attribute keys, so it is tied to `event_type` and must be reset when that changes. Applied identically to both arms: filtering only the treated arm would compare different outcomes and manufacture lift out of nothing.\n"},"window_days":{"type":"integer","minimum":1,"maximum":365,"description":"The attribution window, measured from each profile's OWN touch. Without it both cohorts are compared over their entire lifetimes and every difference is baseline noise.\n"}}},"LiftCohort":{"type":"object","properties":{"profiles":{"type":"integer","description":"Distinct profiles in the arm."},"converted":{"type":"integer","description":"How many met the goal inside the window."},"rate":{"type":"number","format":"double"}}},"LiftResult":{"type":"object","description":"The incremental-lift report for one campaign.","properties":{"status":{"type":"string","enum":["ok","not_enough_data","goal_not_configured","no_control_group"]},"measured_against":{"type":"string","enum":["global_rule","global_auto","campaign_auto"],"description":"Which control cohort this campaign is compared against."},"goal":{"$ref":"#/components/schemas/CampaignGoal"},"window_days":{"type":"integer"},"period_days":{"type":"integer"},"control":{"$ref":"#/components/schemas/LiftCohort"},"treated":{"$ref":"#/components/schemas/LiftCohort"},"absolute_lift":{"type":"number","format":"double","description":"Treated rate minus control rate, as a proportion (0.004 = +0.4pp)."},"relative_lift":{"type":"number","format":"double","description":"Omitted when the control rate is zero, where the ratio is undefined."},"ci_low":{"type":"number","format":"double"},"ci_high":{"type":"number","format":"double","description":"95% confidence interval on the absolute lift (unpooled SE)."},"p_value":{"type":"number","format":"double","description":"Two-tailed two-proportion z-test (pooled SE)."},"significant":{"type":"boolean","description":"p_value below 0.05. Never true below the 100-profile-per-arm floor — without this guard a 2pp swing on 400 profiles reads as a win.\n"},"incremental_conversions":{"type":"number","format":"double","description":"absolute_lift × treated size — the conversions the campaign caused."},"notes":{"type":"array","items":{"type":"string"}}}},"AttributionModelCredit":{"type":"object","properties":{"conversions":{"type":"number","format":"double"},"value":{"type":"number","format":"double"}}},"AttributionRow":{"type":"object","description":"One campaign × channel cell of the attribution matrix.","properties":{"campaign_id":{"type":"string"},"campaign_name":{"type":"string","description":"Resolved once per distinct campaign_id. Empty when the lookup failed or the campaign has since been deleted — the row is kept regardless, because the touches still carry real credit and omitting the row would move that credit into thin air.\n"},"channel":{"type":"string"},"touches":{"type":"integer","format":"int64","description":"Raw creditable touch count in the window, independent of model."},"models":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/AttributionModelCredit"},"description":"Keyed by the requested model names (`models` on the request)."}}},"AttributionResult":{"type":"object","description":"The multi-touch attribution matrix: which touches get credit for a conversion, under one or more rule-based models computed side by side from one ordered touch list per profile.\n","properties":{"conversion_event":{"type":"string"},"days":{"type":"integer"},"lookback_days":{"type":"integer"},"models":{"type":"array","items":{"type":"string"},"description":"The requested models, in REQUEST order — rows are sorted by the first one's credited conversions descending.\n"},"credit_actions":{"type":"array","items":{"type":"string"}},"rows":{"type":"array","items":{"$ref":"#/components/schemas/AttributionRow"}},"unattributed":{"allOf":[{"$ref":"#/components/schemas/AttributionModelCredit"}],"description":"Conversions whose profile had no creditable touch inside the lookback window — the number that keeps the report honest. Never hidden.\n"},"total_conversions":{"type":"integer","format":"int64"},"total_value":{"type":"number","format":"double"},"conversions_truncated":{"type":"boolean","description":"The conversion aggregate hit its row cap; the report is a lower bound."},"touches_truncated":{"type":"boolean","description":"The touch aggregate hit its row cap; the report is a lower bound."},"notes":{"type":"array","items":{"type":"string"},"description":"Always includes the standing note distinguishing attribution from lift; truncation flags each append their own note naming the cap.\n"}}},"OfferResponses":{"type":"object","description":"The per-offer response matrix for one owner (a campaign or an offer catalogue), read from the campaign_touch ledger — the suite keeps no bespoke contact-history store.\n","properties":{"campaign_id":{"type":"string","format":"uuid","description":"Set on the campaign route only."},"catalog_id":{"type":"string","format":"uuid","description":"Set on the catalogue route only."},"window_days":{"type":"integer"},"actions":{"type":"array","items":{"type":"string"},"description":"The response axis in funnel order — the column order to render, served rather than duplicated client-side.\n","example":["presented","accepted","postponed","rejected","realized"]},"offers":{"type":"array","items":{"$ref":"#/components/schemas/OfferResponseRow"}},"totals":{"type":"object","additionalProperties":{"type":"integer","format":"int64"},"description":"Column sums across the listed offers, plus `decisioned`. An action with no rows anywhere is absent.\n"},"truncated":{"type":"boolean","description":"The aggregate hit the 10 000-row analytics limit and the counts under-report. Offers x 6 actions x 3 sources is far below it, but a silently truncated count looks correct.\n"}}},"OfferResponseRow":{"type":"object","description":"One offer's row of the matrix.","properties":{"offer_id":{"type":"string"},"name":{"type":"string","description":"Resolved at read time; empty for a deleted offer."},"deleted":{"type":"boolean","description":"The store no longer knows this offer. Its responses still happened and still count toward a response rule, so the row survives with its raw id rather than being dropped.\n"},"decisioned":{"type":"integer","format":"int64","description":"Hand-outs in the window — the response-rate denominator. NOT one of the counts: a decision is not an answer.\n"},"counts":{"type":"object","additionalProperties":{"type":"integer","format":"int64"},"description":"The five response actions. An action with no rows is ABSENT, not a zero — absent means \"none\", never \"the query could not tell you\", and a console rendering zeros for both loses that distinction.\n","example":{"presented":1240,"accepted":312,"rejected":410}},"test_counts":{"type":"object","additionalProperties":{"type":"integer","format":"int64"},"description":"The `response_source = console` subset OF counts (not in addition to it), so a console can show or subtract its own test responses without a second round trip.\n","example":{"accepted":2}}}},"OfferResponseEvents":{"type":"object","description":"One page of the individual answers behind a matrix cell.","properties":{"events":{"type":"array","items":{"$ref":"#/components/schemas/OfferResponseEvent"}},"page":{"type":"integer","format":"int64"},"size":{"type":"integer","format":"int64"},"total":{"type":"integer","format":"int64","description":"Exact match count for the filter, across all pages."}}},"OfferResponseEvent":{"type":"object","description":"One campaign_touch row. Every field is a touch attribute; one the row never carried — or one the privacy gates withheld — comes back empty rather than filled in with something plausible.\n","properties":{"timestamp":{"type":"string","format":"date-time"},"profile_id":{"type":"string","format":"uuid"},"offer_id":{"type":"string"},"offer_name":{"type":"string"},"action":{"type":"string"},"nba_id":{"type":"string","description":"The decision this answer was reported against. Empty on rows from flows with no decide.\n"},"reason":{"type":"string"},"reference_id":{"type":"string","description":"The reporting system's own handle (an order id)."},"response_value":{"type":"number","description":"The outcome's monetary value. Absent when not reported — an explicit 0 is a real fact (\"realized, worth nothing\") and is returned as 0.\n"},"response_source":{"type":"string","enum":["api","edge","console"],"description":"Empty on rows written before this attribute existed."},"campaign_id":{"type":"string"},"journey_id":{"type":"string"}}},"CampaignDelivery":{"type":"object","description":"A one-off campaign's delivery rollup from the campaign_touch ledger, present on GET /campaigns/{id} for type one_off_batch outside draft (absent when the CDP read fails). `completed` means the run published; this says what became of the sends. failed = provider failures + bounces; pending = queued sends (control-group holdouts excluded) with no sent/failed outcome yet. Channels without receipts never report delivered.","properties":{"sent":{"type":"integer","format":"int64"},"delivered":{"type":"integer","format":"int64"},"failed":{"type":"integer","format":"int64"},"pending":{"type":"integer","format":"int64"}},"required":["sent","delivered","failed","pending"]},"BatchRun":{"type":"object","description":"One execution of a batch campaign.","properties":{"id":{"type":"string","format":"uuid"},"campaign_id":{"type":"string","format":"uuid"},"scheduled_for":{"type":"string","format":"date-time"},"started_at":{"type":"string","format":"date-time"},"finished_at":{"type":"string","format":"date-time","description":"Absent while running."},"status":{"type":"string","enum":["running","completed","failed"]},"profiles_matched":{"type":"integer"},"sends_published":{"type":"integer"},"duplicate_persons":{"type":"integer","description":"Audience members skipped because another member of the same person was already reached."},"error":{"type":"string","description":"Absent when the run did not fail."},"attempts":{"type":"integer","description":"Retry claims of a failed run (0 = first execution); absent at 0."},"resume_cursor":{"type":"string","readOnly":true,"description":"Checkpoint - the audience cursor of the next page to read; a retry resumes there. Absent before the first checkpoint."},"audience_pages":{"type":"integer","readOnly":true,"description":"Audience pages finished so far (with the checkpoint); absent at 0."}},"required":["id","campaign_id","scheduled_for","started_at","status","profiles_matched","sends_published","duplicate_persons"]},"CampaignStats":{"type":"object","description":"campaign_touch funnel for one campaign, aggregated by the CDP's analytics engine over the requested window.\n","properties":{"campaign_id":{"type":"string","format":"uuid"},"window_days":{"type":"integer"},"truncated":{"type":"boolean","description":"True when the CDP analytics row limit cut an aggregate behind this response (the funnel or, with ?interval=, the timeline), so the counts are lower bounds. Absent when complete."},"held_out":{"type":"integer","format":"int64","description":"Profiles deliberately not contacted (control_group touches). It sits BESIDE the funnel, never inside it: a holdout is not a funnel stage, and rendering it as one would read as a drop-off.\n"},"funnel":{"type":"array","description":"Fixed action order; absent actions count 0. Both campaign_touch axes appear, message first (decisioned…clicked) then the customer's decision about the offer (presented…realized, reported against the decision's NBA ID — see §\"NBA response collection\"), so one contact reads top to bottom from hand-out to outcome.\n","items":{"type":"object","properties":{"action":{"type":"string","enum":["decisioned","queued","sent","delivered","failed","bounced","opened","clicked","presented","accepted","postponed","rejected","realized"]},"count":{"type":"integer","format":"int64"},"rate":{"type":"number","nullable":true,"description":"count as a fraction (4 decimals) of this funnel's `sent` count; null when nothing was sent. May exceed 1 for steps counted before sending (decisioned, queued).\n"}}}},"by_channel":{"type":"object","description":"The same funnel per delivery channel (email/sms/rcs/whatsapp/ viber/push/webhook). Touches without a channel attribute (decisioned, campaign-level queued) count in `funnel` only.\n","additionalProperties":{"type":"array","items":{"type":"object","properties":{"action":{"type":"string"},"count":{"type":"integer","format":"int64"},"rate":{"type":"number","nullable":true,"description":"Fraction of this step's base within the same breakdown: queued, sent and failed are relative to queued (failed touches are drops and exhausted retries, never sent messages), every later step (delivered, bounced, opened, clicked, presented, accepted, postponed, rejected, realized) to sent. Null for decisioned and when the base is 0. Later steps can exceed 1 when opened/clicked count repeat events."}}}}},"by_provider":{"type":"object","description":"The same funnel per resolved channel-provider instance, keyed by provider_id. Touches without a provider_id (decisioned, campaign-level queued with no pinned provider) count in `funnel` only. Keys are ids so a since-deleted provider still appears; resolve names from the channels catalog.\n","additionalProperties":{"type":"array","items":{"type":"object","properties":{"action":{"type":"string"},"count":{"type":"integer","format":"int64"},"rate":{"type":"number","nullable":true,"description":"Fraction of this step's base within the same breakdown: queued, sent and failed are relative to queued (failed touches are drops and exhausted retries, never sent messages), every later step (delivered, bounced, opened, clicked, presented, accepted, postponed, rejected, realized) to sent. Null for decisioned and when the base is 0. Later steps can exceed 1 when opened/clicked count repeat events."}}}}},"timeline":{"type":"array","description":"Present only when `?interval=` was requested: the same funnel bucketed over time, oldest first. Buckets are cut in the viewer's calendar, not UTC.\n","items":{"$ref":"#/components/schemas/StatsBucket"}}},"required":["campaign_id","window_days","funnel"]},"SegmentMember":{"type":"object","description":"One profile from the CDP, passed through verbatim — this endpoint proxies `GET /cdp/api/v1/profiles` under the caller's purpose. The authoritative shape is `ProfileObject` in the CDP spec (`oapi3.yml`); only the always-present keys are restated here, deliberately, so the two specs cannot drift into disagreeing about the rest.\n","additionalProperties":true,"properties":{"id":{"type":"string","format":"uuid"},"entity_type":{"type":"string"},"identifiers":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"}}}},"attributes":{"type":"object","description":"Present only when `include_attributes=true` was requested."}},"required":["id","entity_type"]},"ControlGroupPreview":{"type":"object","description":"What a control-group setting WOULD hold out, without storing anything.\n","properties":{"entity_type":{"type":"string"},"mode":{"type":"string","enum":["off","auto","rule"]},"total_profiles":{"type":"integer","format":"int64"},"held_out":{"type":"integer","format":"int64"},"targetable":{"type":"integer","format":"int64"},"exact":{"type":"boolean","description":"True in `rule` mode, which counts real matches. In `auto` mode the figure is an expectation over a uniform assignment — saying so keeps the console honest.\n"}},"required":["entity_type","mode","total_profiles","held_out","targetable","exact"]},"PredictionResponse":{"type":"object","description":"The advisory prediction plus the evidence it was drawn from. A store failure still answers 200, with the prediction and a warnings envelope.\n","properties":{"prediction":{"$ref":"#/components/schemas/Prediction"},"evidence":{"type":"object","description":"The measured inputs the model was shown."}},"required":["prediction"]},"InsightSection":{"type":"object","properties":{"key":{"type":"string","enum":["vs_industry","vs_your_campaigns","why","suggestions"]},"title":{"type":"string"},"body_md":{"type":"string"}},"required":["key","title","body_md"]},"GeneratedInsight":{"type":"object","description":"The freshly generated analysis. NOT a CampaignInsight row — row identity lives in the sibling `id`, never on the insight itself.\n","properties":{"verdict":{"type":"string","enum":["strong","healthy","mixed","underperforming"]},"summary":{"type":"string"},"sections":{"type":"array","items":{"$ref":"#/components/schemas/InsightSection"}},"generated_at":{"type":"string","format":"date-time"}},"required":["verdict","summary","sections"]},"InsightResponse":{"type":"object","description":"`id` is present when the insight was persisted; a store failure instead returns 200 with a warnings envelope carrying only insight + evidence.\n","properties":{"insight":{"$ref":"#/components/schemas/GeneratedInsight"},"evidence":{"type":"object","description":"The measured performance the analysis was drawn from."},"id":{"type":"string","format":"uuid"}},"required":["insight"]},"InsightListResponse":{"type":"object","properties":{"insights":{"type":"array","items":{"$ref":"#/components/schemas/CampaignInsight"}}},"required":["insights"]},"SplitDecision":{"type":"object","description":"One winner test's verdict, pinned to the journey version it ran on.","properties":{"journey_id":{"type":"string","format":"uuid"},"journey_version":{"type":"integer"},"node_id":{"type":"string"},"status":{"type":"string","enum":["collecting","decided","inconclusive"]},"started_at":{"type":"string","format":"date-time"},"deadline":{"type":"string","format":"date-time"},"decided_at":{"type":"string","format":"date-time","nullable":true},"winner":{"type":"string","description":"The winning arm; empty while collecting and on an inconclusive verdict."},"stats":{"type":"object","description":"The per-arm statistics snapshot the verdict was taken on."}},"required":["journey_id","journey_version","node_id","status","started_at","deadline"]},"SplitDecideResponse":{"type":"object","properties":{"decision":{"$ref":"#/components/schemas/SplitDecision"},"woken":{"type":"integer","description":"How many held runs were woken to flow through the verdict. A wake failure is reported honestly: the verdict is committed either way, and unwoken runs still flow at their original deadline.\n"}},"required":["decision","woken"]},"RenderedRequest":{"type":"object","description":"The HTTP request a provider or action node would issue.","properties":{"method":{"type":"string"},"url":{"type":"string"},"headers":{"type":"object","additionalProperties":{"type":"string"}},"body":{"type":"string"},"credentials_withheld":{"type":"boolean","description":"True when the provider has credentialed auth (basic, bearer, api_key, oauth2) or an HMAC signing secret but this request's host is not the literal host of its url — the per-send contact URL or a templated host; the X-Optima-Signature header is then left off too. A preview, a journey-node probe or a per-send contact URL request is sent without the credentials; a channel SEND to a provider whose url host is templated is refused as a permanent failure instead (re-save the provider with a literal host).\n"}},"required":["method","url"]},"ProviderPreviewResponse":{"type":"object","description":"The rendered provider request, plus the live response when `execute` was set.\n","properties":{"request":{"$ref":"#/components/schemas/RenderedRequest"},"executed":{"type":"boolean"},"status":{"type":"integer"},"body":{"type":"string"}},"required":["request","executed"]},"WebhookProbeResponse":{"type":"object","description":"What an action node would do. Only `request` is present on a render. A transport failure (DNS, refused, timeout, blocked by the SSRF guard) or a broken success_when expression is the ANSWER, not a server fault, so it rides a 200 in `error`.\n","properties":{"request":{"$ref":"#/components/schemas/RenderedRequest"},"executed":{"type":"boolean"},"status":{"type":"integer"},"duration_ms":{"type":"integer","format":"int64","description":"The round trip — how a timeout gets diagnosed."},"body":{"type":"string"},"success":{"type":"boolean","description":"The `success_when` verdict — which branch the node would take."},"mapped":{"type":"object","description":"What `response_mapping` lifted out of the body."},"mapping_note":{"type":"string","description":"Why `mapped` is empty when the body was not JSON."},"error":{"type":"string"}},"required":["request","executed","success"]},"TemplatePreviewFieldResult":{"type":"object","description":"The outcome for one previewed field. A broken template is the ANSWER, not a request failure: `ok: false` plus the exact parse or execution error.\n","properties":{"ok":{"type":"boolean"},"rendered":{"type":"string"},"error":{"type":"object","properties":{"message":{"type":"string"},"line":{"type":"integer","description":"0 or absent means the error carried no position."}},"required":["message"]},"references":{"type":"array","description":"The personalization paths the template touched.","items":{"type":"object","properties":{"path":{"type":"string"},"defaulted":{"type":"boolean"},"resolved":{"type":"boolean"}},"required":["path","resolved"]}}},"required":["ok"]},"TemplatePreviewResponse":{"type":"object","properties":{"fields":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/TemplatePreviewFieldResult"}},"warnings":{"type":"array","items":{"type":"string"},"description":"Non-blocking notes about the previewed text; absent when there are none. `subject_crlf`: the rendered `subject` contains a line break.\n"}},"required":["fields"]},"RenderTemplateResponse":{"type":"object","properties":{"channel":{"type":"string"},"language":{"type":"string","description":"The language whose mutation actually rendered. Empty means the base/default copy — either none was requested, or the requested one has no cell for this channel and fell back.\n"},"rendered":{"type":"object","description":"Each variant field to its rendered string.","additionalProperties":{"type":"string"}}},"required":["channel","rendered"]},"GenerateCopyResponse":{"type":"object","description":"LLM copy drafts, already parse-validated (drafts that fail validation are dropped). Nothing is persisted.\n","properties":{"channel":{"type":"string"},"variants":{"type":"array","description":"Each draft is a field map matching the requested schema. The keys are the channel's variant fields, except under `format: mjml` where the design comes back as `body_mjml`.\n","items":{"type":"object","additionalProperties":{"type":"string"}}}},"required":["channel","variants"]},"VariantDesign":{"type":"object","description":"A visual-editor design document for one variant. The server never compiles it — compilation happens in the browser and the client submits the compiled `body_html` alongside.\n","properties":{"format":{"type":"string","enum":["mjml"]},"source":{"type":"string","description":"The design document itself (MJML markup for format=mjml)."},"compiled_sha256":{"type":"string","description":"sha256 of the variant's body_html, stamped by the SERVER on every write. On read, a mismatch against the current body_html means the design is stale — some writer changed the HTML without touching it.\n"},"builder":{"type":"string","description":"The builder/component-set version that produced the source.","example":"grapesjs-mjml@1.0.8"}},"required":["format","source"]},"TranslateTemplateResponse":{"type":"object","description":"The translation draft, ready for the editor. Nothing is persisted.","properties":{"channel":{"type":"string"},"variant_key":{"type":"string"},"language":{"type":"string"},"fields":{"type":"object","description":"The complete mutation cell — translated prose plus verbatim carry-overs. For a visual email it deliberately omits `body_html`: the GUI compiles the translated design into it, keeping design and HTML in lockstep.\n","additionalProperties":{"type":"string"}},"design":{"$ref":"#/components/schemas/VariantDesign"},"repair_rounds":{"type":"integer"},"warnings":{"type":"array","items":{"type":"string"}}},"required":["channel","variant_key","language","fields"]},"ChannelVocabularyEntry":{"type":"object","description":"One entry of the effective channel vocabulary — what a channel picker renders.","properties":{"name":{"type":"string"},"label":{"type":"string"},"contact_kind":{"type":"string","enum":["email","phone","token","none"]},"template_variant":{"type":"string","description":"Which message-template variant carries this channel's copy. A native channel is its own variant; a declared one borrows a built-in schema.\n"},"custom":{"type":"boolean"},"is_active":{"type":"boolean"}},"required":["name","label","contact_kind","template_variant","custom","is_active"]},"HolidayCountry":{"type":"object","description":"A compiled public-holiday calendar a silent-hours spec may reference.","properties":{"code":{"type":"string","description":"Lowercase ISO 3166-1 alpha-2."},"name":{"type":"string"}},"required":["code","name"]},"StatsBucket":{"type":"object","description":"One point of the funnel-over-time timeline.","properties":{"bucket":{"type":"string","description":"The bucket's start, granularity per the requested `interval` (day/week/month).\n"},"counts":{"type":"object","description":"Touch action to count within this bucket. Actions with no touches in the bucket are absent rather than zero.\n","additionalProperties":{"type":"integer","format":"int64"}}},"required":["bucket","counts"]},"LanguageDefinition":{"type":"object","description":"One entry of the tenant's language vocabulary. `value` is the raw profile-attribute value that means this language — an arbitrary tenant-defined string, no BCP-47 anywhere. `label` is the display name AND the target the AI translate assist is prompted with.\n","properties":{"value":{"type":"string","example":"esp","maxLength":64},"label":{"type":"string","example":"Spanish","maxLength":128},"default":{"type":"boolean","description":"Exactly one language carries it. The default's template mutation is the template's base `variants` itself, so it is structurally mandatory.\n"}},"required":["value","label"]},"LanguageSettings":{"type":"object","description":"The tenant's language configuration, a singleton per tenant.\n","properties":{"languages":{"type":"array","items":{"$ref":"#/components/schemas/LanguageDefinition"}},"entity_attributes":{"type":"object","additionalProperties":{"type":"string"},"description":"Entity type → the profile attribute carrying the preferred language (e.g. {\"customer\": \"lang\"}). An entity type with no entry resolves every profile to the default language.\n"},"updated_at":{"type":"string","format":"date-time","description":"Absent until the settings are first saved."},"updated_by":{"type":"string"}},"required":["languages"]},"LanguageSettingsRequest":{"type":"object","properties":{"languages":{"type":"array","items":{"$ref":"#/components/schemas/LanguageDefinition"}},"entity_attributes":{"type":"object","additionalProperties":{"type":"string"}}},"required":["languages"]},"SilentHoursWindow":{"type":"object","description":"One weekly silent rule: the listed days with either whole-day silence or a start/end time-of-day pair. start > end wraps past midnight, interpreted PER LISTED DAY (on each listed day the silent time is start→midnight plus midnight→end, so \"weekdays 20:00–08:00\" keeps Monday 06:00 silent without Sunday being listed).\n","properties":{"days":{"type":"array","items":{"type":"string","enum":["mon","tue","wed","thu","fri","sat","sun"]}},"start":{"type":"string","description":"\"HH:MM\", zero-padded. Mutually exclusive with all_day."},"end":{"type":"string","description":"\"HH:MM\", zero-padded. Mutually exclusive with all_day."},"all_day":{"type":"boolean"}},"required":["days"]},"SilentHoursSpec":{"type":"object","description":"A silent-hours document — one shape at every level (tenant general, tenant per-channel, campaign override, journey send-node override). An override replaces the inherited spec wholesale; disabled=true is the explicit opt-out (\"this sends at any hour\"). Enforced by delivery immediately before transmission, never at queue time.\n","properties":{"disabled":{"type":"boolean"},"timezone":{"type":"string","description":"IANA zone the windows are read in. Required unless disabled."},"timezone_attribute":{"type":"string","description":"Optional profile attribute holding the recipient's IANA timezone; a missing/invalid value falls back to `timezone` and never fails a send.\n"},"windows":{"type":"array","items":{"$ref":"#/components/schemas/SilentHoursWindow"}},"holidays":{"type":"object","description":"Public-holiday silence for one country from the compiled registry (see /silent-hours/countries). observed extends silence to observed dates (a weekend holiday moving to Monday where the country does that).\n","properties":{"country":{"type":"string","example":"sk"},"observed":{"type":"boolean"}},"required":["country"]},"max_defer_hours":{"type":"integer","minimum":0,"description":"How long a send may wait for a window to open; 0 = wait forever.\n"},"on_expiry":{"type":"string","enum":["drop","send"],"description":"Past max_defer_hours: drop (default) terminates with a failed touch (reason silent_hours_expired); send transmits despite the window and the sent touch carries reason sent_after_expiry.\n"}}},"SilentHoursSettings":{"type":"object","description":"The tenant's silent-hours configuration, a singleton per tenant: one optional general spec plus optional per-channel specs. A channel with its own entry uses it INSTEAD of general (wholesale, no merging). Keys are the EFFECTIVE channel vocabulary — the native push channels plus this tenant's active operator-declared ones (GET /cdp/api/v1/channels); onsite channels (web_banner/ web_personalization/mobile_inapp) are exempt from silent hours and rejected as keys.\n","properties":{"general":{"$ref":"#/components/schemas/SilentHoursSpec"},"channels":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/SilentHoursSpec"}},"updated_at":{"type":"string","format":"date-time","description":"Absent until the settings are first saved."},"updated_by":{"type":"string"}}},"SilentHoursRequest":{"type":"object","properties":{"general":{"$ref":"#/components/schemas/SilentHoursSpec"},"channels":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/SilentHoursSpec"}}}},"ResponsePolicy":{"type":"object","description":"A CROSS-OFFER response policy: once a profile has answered enough offers, decisioning stops for them entirely.\nAn offer's own `response_rules` ask whether the profile has answered THAT offer enough; a policy asks whether they have answered enough at all. Same rule shape, no offer filter.\nEnforced at the DECIDE only — every candidate offer is excluded with reason `response_policy` and the caller gets an empty decision. A send already queued from an earlier decide is not stopped.\n","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"entity_type":{"type":"string"},"rules":{"type":"array","items":{"$ref":"#/components/schemas/ResponseRule"}},"offer_tags":{"type":"array","description":"Count only responses to offers carrying ALL of these tags; empty = every offer for the entity type. Resolved to offer ids when the policy runs (the ledger records offer_id, never tags), so responses to an offer since deleted or re-tagged stop counting, and when the tags match more than 500 offers only 500 of them count.\n","items":{"type":"string"}},"is_active":{"type":"boolean"},"created_by":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"ResponsePolicyRequest":{"type":"object","required":["name","entity_type","rules"],"description":"Rule bounds are the same ones an offer's `response_rules` obey — a policy is not a second, laxer grammar for the same shape. Validated identically on create, update and revision restore.\n","properties":{"name":{"type":"string"},"entity_type":{"type":"string"},"rules":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/ResponseRule"}},"offer_tags":{"type":"array","items":{"type":"string"}},"is_active":{"type":"boolean","description":"Absent = active."}}},"FatiguePolicy":{"type":"object","description":"Cross-campaign over-communication rule: at most max_touches outbound touches (queued ledger actions) per profile in window_days, across every campaign — optionally narrowed to one channel (absent = all) and/or campaign types (absent = all). Enforced at NBA decide (exclusion reason \"fatigue\"), journey send nodes (defer/skip/exit per node config) and the delivery service's pre-dispatch backstop (drop + failed touch, reason \"fatigue\"). Channel-scoped policies are skipped where the channel isn't known yet (decides, auto-channel sends).\n","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"entity_type":{"type":"string","description":"The target entity type this policy counts touches against. Required for scope=profile; always empty for scope=hierarchy, which governs sends to every entity type instead.\n"},"channel":{"type":"string","description":"Native, operator-declared, or an onsite pull channel — the deliverable set is native ∪ the CDP's delivery_channels registry, which OpenAPI cannot enumerate.\n"},"max_touches":{"type":"integer","minimum":1},"window_days":{"type":"integer","minimum":1},"campaign_types":{"type":"array","items":{"type":"string","enum":["one_off_batch","recurring_batch","journey_based","inbound_offer"]}},"scope":{"type":"string","enum":["profile","hierarchy"],"default":"profile","description":"profile = per-profile counting (default). hierarchy = the policy bounds touches over a whole profile subtree: the target profile is resolved up profile_links to its anchor(s) of anchor_entity_type and the cap applies to the anchor plus all descendants together. Hierarchy policies apply to sends targeting ANY entity type; entity_type must be empty and campaign_types is not supported.\n"},"anchor_entity_type":{"type":"string","description":"Entity type the pool anchors at (required when scope=hierarchy)."},"relation_types":{"type":"array","items":{"type":"string"},"description":"profile_links relation types that form the hierarchy. Empty = every relation type except \"identity\"; listing \"identity\" explicitly opts identity-graph edges in.\n"},"is_active":{"type":"boolean"},"created_by":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","name","max_touches","window_days","is_active"]},"FatiguePolicyRequest":{"type":"object","properties":{"name":{"type":"string"},"entity_type":{"type":"string","description":"The target entity type the policy counts for. REQUIRED when scope is profile (or omitted) and must be EMPTY when scope=hierarchy — both rules are scope-conditional, so they are enforced together with the rest of the scope shape and answer 422, not 400.\n"},"channel":{"type":"string"},"max_touches":{"type":"integer","minimum":1},"window_days":{"type":"integer","minimum":1},"campaign_types":{"type":"array","items":{"type":"string"}},"scope":{"type":"string","enum":["profile","hierarchy"],"default":"profile","description":"profile = per-profile counting (default). hierarchy = the policy bounds touches over a whole profile subtree: the target profile is resolved up profile_links to its anchor(s) of anchor_entity_type and the cap applies to the anchor plus all descendants together. Hierarchy policies apply to sends targeting ANY entity type; entity_type must be empty and campaign_types is not supported.\n"},"anchor_entity_type":{"type":"string","description":"Entity type the pool anchors at (required when scope=hierarchy)."},"relation_types":{"type":"array","items":{"type":"string"},"description":"profile_links relation types that form the hierarchy. Empty = every relation type except \"identity\"; listing \"identity\" explicitly opts identity-graph edges in.\n"},"is_active":{"type":"boolean","default":true}},"required":["name","max_touches","window_days"]},"CodePool":{"type":"object","description":"A named bag of unique coupon codes. `uploaded` pools are seeded from an operator-supplied CSV (POST .../upload); `generated` pools mint codes from `pattern` on demand (POST .../generate). Counts are the pool's live code states — populated on every read, never written directly, since the code lifecycle (claim/issue/redeem at send time) is the only thing that moves a code between states.\n\n**Redemption contract**: closing the loop is not a Campaign API call. The commerce system that accepts the code posts an ordinary CDP event of type `coupon_redeemed` (`POST /cdp/api/v1/events/add`) carrying an attribute `code` = the redeemed string. The journey engine resolves that event to the send which issued the code and logs a `campaign_touch` with `action: \"redeemed\"` under the send's stored purpose — no separate coupon-redemption endpoint exists or is needed.\n","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string"},"kind":{"type":"string","enum":["uploaded","generated"],"default":"uploaded"},"pattern":{"type":"string","description":"Generation pattern for kind=generated (e.g. \"SUMMER-{8}\"): each \"{k}\" is replaced with k crypto-random alphabet characters (2 <= k <= 32, summing to at least 6), literal text restricted to [A-Za-z0-9_-]. Ignored for kind=uploaded.\n"},"single_use":{"type":"boolean","default":true},"low_water":{"type":"integer","format":"int64","description":"Free-code threshold below which the pool is considered low (alerting is a separate concern, not this endpoint's)."},"expires_at":{"type":"string","format":"date-time","nullable":true},"low_notified_at":{"type":"string","format":"date-time","nullable":true},"created_by":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"free":{"type":"integer","format":"int64","description":"Codes never claimed."},"claimed":{"type":"integer","format":"int64","description":"Claimed for an in-flight send","not yet confirmed sent.":null},"issued":{"type":"integer","format":"int64","description":"Claimed and the provider accepted the message."},"redeemed":{"type":"integer","format":"int64","description":"Redeemed by the customer."},"expired":{"type":"integer","format":"int64","description":"Was free when the pool's expires_at passed."}},"required":["id","name","kind","single_use","created_at","updated_at"]},"CodePoolRequest":{"type":"object","description":"Create/update body. `name` is validated against the shared pool-name contract (letters/digits/spaces/underscores/hyphens, starting with a letter or digit, max 64 chars, no quotes or backticks — the name is interpolated into `{{coupon \"name\"}}` template tokens) rather than by a generic string rule, so an invalid name answers 400. `pattern` is required (and validated) only when kind=generated.\n","properties":{"name":{"type":"string","maxLength":64},"description":{"type":"string"},"kind":{"type":"string","enum":["uploaded","generated"],"default":"uploaded"},"pattern":{"type":"string"},"single_use":{"type":"boolean","default":true},"low_water":{"type":"integer","format":"int64","minimum":0,"default":0},"expires_at":{"type":"string","format":"date-time","nullable":true}},"required":["name"]},"GenerateCodesRequest":{"type":"object","properties":{"count":{"type":"integer","minimum":1,"maximum":100000}},"required":["count"]},"FieldChange":{"type":"object","description":"One field-level difference between two configuration snapshots. `from` is absent when the field did not exist before (a create, or a newly-set optional field); `to` is absent when it no longer exists (a delete, or a cleared field). Values are raw JSON of whatever type the field holds, so a tag array or a frequency cap round-trips unchanged. The comparison is deliberately shallow: a nested document (a journey graph, a segment filter, a template's variants) is reported as one changed field carrying both versions.\n","properties":{"field":{"type":"string","example":"consent_purpose"},"from":{},"to":{}},"required":["field"]},"ConfigRevision":{"type":"object","description":"One recorded change to a campaign-suite configuration object (campaign, offer, journey, message template, segment, fatigue policy). Revisions are append-only and outlive the object they describe: a deleted campaign's changelog stays readable, and its final `delete` revision is the only remaining record of what it contained.\n","properties":{"id":{"type":"string","format":"uuid"},"resource_type":{"type":"string","enum":["campaign","offer","offer_catalog","journey","template","segment","fatigue_policy","response_policy","document","code_pool"]},"resource_id":{"type":"string","format":"uuid"},"campaign_id":{"type":"string","format":"uuid","description":"The campaign whose changelog this revision appears in - the object itself for campaigns, the parent for offers and journeys. Absent for templates, segments and fatigue policies, which are shared across campaigns and belong to no single one.\n"},"resource_name":{"type":"string","description":"The object's name AT THE TIME of the change, so the changelog stays readable after a rename and after the object is gone.\n"},"revision":{"type":"integer","minimum":1,"description":"Monotonic per object, starting at 1 for its `create`."},"action":{"type":"string","enum":["create","update","delete","activate","pause","restore"],"description":"`activate`/`pause` are the campaign lifecycle transitions, recorded separately from `update` so \"someone turned this campaign on\" is findable without reading every edit.\n"},"snapshot":{"type":"object","description":"The full post-change configuration, in the same shape the object's GET returns - this is what a restore replays. Omitted from list responses unless `include_snapshot=true`; always present when reading a single revision.\n"},"diff":{"type":"array","items":{"$ref":"#/components/schemas/FieldChange"}},"restored_from":{"type":"integer","description":"On `action=restore`, the revision whose snapshot was replayed."},"actor":{"type":"string","description":"The authenticated caller: a user's email address, or an application's api_key_hash.\n"},"actor_type":{"type":"string","enum":["user","application","root","system"],"description":"`system` = an automatic action (stop condition)."},"created_at":{"type":"string","format":"date-time"}},"required":["id","resource_type","resource_id","resource_name","revision","action","diff","actor","created_at"]},"RestoreResult":{"type":"object","properties":{"restored_from":{"type":"integer","description":"The revision that was replayed."},"resource":{"type":"object","description":"The stored object after the rollback."},"approvals_cleared":{"$ref":"#/components/schemas/ApprovalsCleared"}}},"ApprovalsCleared":{"type":"array","description":"The approved campaigns whose standing approval this change cleared, because it alters what they send (the edited object is one they send through). Always present on these responses; empty when nothing was cleared. Each is recorded as an `approval_reset` revision.\n","items":{"type":"object","required":["id","name"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}}},"Prediction":{"type":"object","description":"Advisory AI performance prediction (never a gate). Stored on the campaign (`prediction` field) and refreshed via POST .../predict.\n","properties":{"open_rate":{"$ref":"#/components/schemas/PredictionRange"},"click_rate":{"$ref":"#/components/schemas/PredictionRange"},"conversion_rate":{"$ref":"#/components/schemas/PredictionRange"},"rationale":{"type":"string"},"confidence":{"type":"string","enum":["low","medium","high"]},"generated_at":{"type":"string","format":"date-time"}}},"PredictionRange":{"type":"object","properties":{"low":{"type":"number","minimum":0,"maximum":1},"high":{"type":"number","minimum":0,"maximum":1}}},"CampaignInsight":{"type":"object","description":"One stored AI performance analysis (advisory, never a gate).","properties":{"id":{"type":"string","format":"uuid"},"campaign_id":{"type":"string","format":"uuid"},"verdict":{"type":"string","enum":["strong","healthy","mixed","underperforming"]},"summary":{"type":"string"},"sections":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","enum":["vs_industry","vs_your_campaigns","why","suggestions"]},"title":{"type":"string"},"body_md":{"type":"string","description":"GitHub-flavored markdown."}}}},"evidence":{"type":"object","description":"The exact bundle the LLM saw."},"model":{"type":"string","description":"Resolved LLM provider label."},"created_by":{"type":"string"},"created_at":{"type":"string","format":"date-time"}}},"JourneyNodeStats":{"type":"object","description":"Per-node drop-off report aggregated from journey runs.","properties":{"journey_id":{"type":"string","format":"uuid"},"version":{"type":"integer"},"nodes":{"type":"array","items":{"type":"object","properties":{"node_id":{"type":"string"},"status":{"type":"string","enum":["running","waiting","completed","exited","failed"]},"count":{"type":"integer","format":"int64"}}}},"totals":{"type":"object","additionalProperties":{"type":"integer","format":"int64"}}}},"ChannelStatus":{"type":"object","description":"One channel's configured provider instances (from campaign_channel_providers) and which of them is the default. The list covers the native channels, the tenant's OPERATOR-DECLARED ones (which need a provider exactly as much — it carries their URL, method, headers, payload template, declared parameters and auth), and any channel that still has providers after its declaration was removed.\n","properties":{"channel":{"type":"string","description":"A native channel (email, sms, rcs, whatsapp, viber, push, webhook) or an operator-declared channel name.\n"},"label":{"type":"string","description":"What a declared channel calls itself. Absent for a native channel, which the console already names.\n"},"custom":{"type":"boolean","description":"True for an operator-declared channel."},"configured":{"type":"boolean","description":"True when at least one active provider exists."},"default_provider_id":{"type":"string","format":"uuid"},"providers":{"type":"array","items":{"$ref":"#/components/schemas/ChannelProvider"}},"detail":{"type":"string","description":"Why unconfigured / caveats."}},"required":["channel","configured","providers"]},"ChannelProvider":{"type":"object","description":"One operator-configured delivery provider instance. Secrets are write-only: reads expose has_credentials, never the values.\n","properties":{"id":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["channel","system"],"default":"channel","description":"`channel` = a delivery provider (consent, suppression, fatigue and the touch ledger all apply). `system` = a registered external HTTP integration a journey action node calls, with no channel semantics at all; systems live behind /systems and never appear in a channel list.\n"},"channel":{"type":"string","description":"A native channel or one this tenant declared — the deliverable set is native ∪ the CDP's delivery_channels registry, which OpenAPI cannot enumerate.\n"},"provider_type":{"type":"string","description":"email: smtp|mailgun|sendgrid|postmark|mailchimp; sms: twilio|infobip|sinch; rcs: twilio|infobip; whatsapp: meta_cloud|twilio; viber: infobip|vonage; push: fcm|apns; webhook: http (see GET /channels/catalog). **`http` is offered on EVERY channel** — a custom integration that DELIVERS that channel (an in-house SMS gateway is channel `sms`, type `http`). Consent (`marketing_sms`), contact resolution (the profile's phone), the suppression hash, channel-scoped fatigue policies, the `sms` template variant and the touch ledger then all treat it as sms, exactly as sms/twilio is treated. The payload template receives the resolved destination as `{{.Contact}}`.\n"},"name":{"type":"string","example":"prod-mailgun"},"is_default":{"type":"boolean","description":"Exactly one default per channel; used when a campaign/journey/send doesn't pin a provider. The first provider of a channel becomes the default automatically; deleting the default promotes the oldest remaining provider.\n"},"is_active":{"type":"boolean"},"config":{"type":"object","description":"Non-secret settings document; schema per provider type in GET /channels/catalog. The webhook http provider additionally carries `url` (Go template), `method`, `headers` (templated values), `payload_template` ({{.Content.body}} = rendered message variant, {{.Params.x}} = caller parameter, plus full {Profile, Offer, Run} personalization; **required** on a channel provider whose method carries a body — anything but GET/HEAD/DELETE — because the provider owns the request and a message template only supplies the parameters it interpolates, so one without a payload could be configured but never sent), `params` ([{name, required, default}]) and `auth` ({type: none|basic|bearer|api_key|oauth2|mtls, ...}; api_key also takes `header` (default X-API-Key) and `prefix`), and `rate_limit` ({requests: N, per: second|minute|hour|day}) which paces calls to the endpoint across every delivery instance. Over the limit a send is DEFERRED — re-queued and retried when the window rolls over — never dropped, and the deferral does not count against the send's failure budget. Absent or 0 requests = unlimited. EVERY provider type accepts `rate_limit` (same shape, validated identically) — not only http. Independently of it, a vendor 429 (Twilio, APNs, FCM, SendGrid, Mailgun, Postmark, Infobip) defers the send for the vendor's Retry-After (1 s when absent) without spending an attempt; after 50 consecutive throttles of one send it falls back to the normal retry ladder. EVERY provider type also accepts `network_id` (a CDP private network, /cdp/api/v1/networks): all of the provider's traffic — SMTP relay, webhook endpoint, SaaS base_url override — then dials through that tunnel, with hostnames resolving on its far side. An unknown or disabled network fails sends permanently; traffic never silently falls back to the default route. EVERY email provider type (smtp, mailgun, sendgrid, postmark, mailchimp) additionally accepts `from_name` (default sender name), `reply_to` (default Reply-To address — one bare address) and `reply_to_name` (display name for `reply_to`; requires `reply_to`) — see GET /channels/catalog for the per-type field list. All three are optional and non-secret. Validated at save (400): `from_name`/`reply_to_name` must not contain `@` and are capped at 128 runes; `reply_to` must be a single bare address (no display name, no CR/LF); `reply_to_name` requires `reply_to`. A message template's own `from_name`/`reply_to`/`reply_to_name` variant fields override these at send time when non-empty and valid (see TemplateVariants.email); Reply-To always resolves as an (address, name) pair from the same rung. None of the three is part of the credential destination — changing them never triggers a 409 `credentials_required`.\n"},"has_credentials":{"type":"boolean"},"receipt_url":{"type":"string","format":"uri","description":"The full public delivery-receipt callback URL to register with the provider, derived from the stored receipt token and the instance's receipt callback address. Empty when receipts are disabled — no token minted, or no Edge endpoint deployed. The raw token is never returned; rotate it via POST /channels/providers/{id}/receipt-token/rotate.\n"},"created_by":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","channel","provider_type","name","is_default","is_active"]},"ChannelProviderRequest":{"type":"object","description":"Create/update body for a channel provider. Credentials is write-only — omit it on update to keep the stored secrets, send a map to replace them. channel/provider_type are immutable after creation; the default moves through POST /channels/providers/{id}/default (or is_default true here).\n","properties":{"channel":{"type":"string","description":"A native channel or one this tenant declared — the deliverable set is native ∪ the CDP's delivery_channels registry, which OpenAPI cannot enumerate.\n"},"provider_type":{"type":"string"},"name":{"type":"string"},"config":{"type":"object"},"credentials":{"type":"object","additionalProperties":{"type":"string"},"description":"Secret fields per provider type (see GET /channels/catalog), e.g. smtp: password; mailgun/infobip: api_key; sendgrid: api_key; mailchimp: api_key; postmark: server_token; twilio: auth_token; sinch: api_token; fcm: service_account_json; apns: key_p8; webhook: password / bearer_token / api_key / client_secret / client_cert_pem / client_key_pem / ca_cert_pem / hmac_secret. AES-256-GCM encrypted at rest.\n"},"is_default":{"type":"boolean"},"is_active":{"type":"boolean","default":true}},"required":["channel","provider_type","name"]},"ExternalSystemRequest":{"type":"object","description":"Create/update body for an external system — a registered HTTP integration journey action nodes call. provider_type is always \"http\", so the request does not carry one, and there is no channel: a system is not a way to reach a customer. Credentials is write-only (omit on update to keep the stored secrets).\n","properties":{"name":{"type":"string","example":"stock-service"},"config":{"type":"object","description":"Same document as a webhook channel provider — `url` (REQUIRED here: a system has no per-send URL fallback), `method`, `headers`, `payload_template`, `params` ([{name, required, default}]), `auth` — plus the system-only fields `required_consent_purpose` (gates every calling node on the profile's live consent; a node may add its own purpose but never lower this one — validated against the CDP purpose catalogue at save, and a `{channel}` family is REFUSED because a system has no channel to expand it against; an unreachable catalogue saves unchecked with a warning), `timeout_sec` (0 = 10, max 60), `rate_limit` ({requests: N, per: second|minute|hour|day}) — shared with every other caller of the same endpoint, and a paced system parks the journey run at the node WITHOUT spending a retry — and `retry` ({attempts: 0-5, backoff_sec: 0-3600}, TRANSPORT failures only — a response is data the graph branches on and is never re-sent).\n"},"credentials":{"type":"object","additionalProperties":{"type":"string"},"description":"password / bearer_token / api_key / client_secret / client_cert_pem / client_key_pem / ca_cert_pem / hmac_secret. AES-256-GCM encrypted at rest. These never enter the journey graph, which is the point of the registry.\n"},"is_active":{"type":"boolean","default":true}},"required":["name"]},"ChannelProviderSpec":{"type":"object","description":"One supported provider type and its field schemas.","properties":{"channel":{"type":"string"},"type":{"type":"string"},"description":{"type":"string"},"receipts":{"type":"object","description":"What this provider reports about a message AFTER accepting it. `message_id` = an accepted send returns the provider's own id, so a later receipt can be correlated with the send. `callback` = `per_message` (the receipt URL rides on each send — the instance's receipt callback address is enough), `account` (the operator registers one webhook in the provider's own console), or absent (no delivery receipts at all). `events` lists the campaign_touch actions the provider can report.\n","properties":{"message_id":{"type":"boolean"},"callback":{"type":"string","enum":["per_message","account"]},"events":{"type":"array","items":{"type":"string","enum":["delivered","failed","bounced","opened","clicked"]}}}},"config_fields":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"required":{"type":"boolean"},"secret":{"type":"boolean"},"type":{"type":"string","enum":["bool","int"],"description":"JSON type the config document expects for this field; absent means string. Config decoding is strict, so a bool field sent as \"true\" is rejected at save time.\n"},"description":{"type":"string"}}}},"credential_fields":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"required":{"type":"boolean"},"secret":{"type":"boolean"},"type":{"type":"string","enum":["bool","int"],"description":"JSON type the config document expects for this field; absent means string. Config decoding is strict, so a bool field sent as \"true\" is rejected at save time.\n"},"description":{"type":"string"}}}}}},"PreviewRequest":{"type":"object","properties":{"profile_id":{"type":"string","format":"uuid","description":"Render personalization against this profile (optional)."},"params":{"type":"object","additionalProperties":{"type":"string"},"description":"Caller-supplied provider/system parameters."},"template":{"type":"string","description":"Message template whose variant is rendered into {{.Content.*}} — what the provider's payload template wraps. Channel providers only.\n"},"contact":{"type":"string","description":"Override the resolved destination ({{.Contact}})."},"execute":{"type":"boolean","default":false,"description":"Actually perform the request."}}},"ChannelProviderTestResult":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}}},"JourneyGraph":{"type":"object","description":"The journey's node/edge graph. Validated on every save: unique known\nnodes with per-type configs, at least one entry node, full\nreachability, acyclic, every leaf an exit node. Each node type requires its own edge\nlabels — condition \"yes\"/\"no\", goal \"on_met\"/\"on_timeout\", split one\nlabel per arm, wait/send/decide unlabeled. A **webhook** node is either\nall-unlabeled (continue whatever the outcome — the historical shape) or\ncarries BOTH \"on_success\" and \"on_error\"; half-labelled is refused,\nsince it would strand every run that took the missing outcome.\n\nA **webhook** node's `consent_purpose`, when set, must name a purpose in\nthe CDP catalogue: an unknown one comes back as a 422 issue attributed\nto that node, and a `{channel}` family is refused outright (a webhook\nnode has no channel to expand it against). Unchecked, either would be\ninvisible until run time, where a purpose nobody holds and a purpose\nnobody created both record the same `consent_denied` node skip. An\nunreadable catalogue accepts the name with a warning rather than\nblocking the save — the gate is re-checked live on every call.\n\nA send node's `channel` may name a built-in channel, \"auto\", or one this\ntenant declared in the CDP's /channels registry. The graph contract\nchecks only that it is non-empty — WHICH channels exist is per-tenant —\nso an unknown name comes back as a 422 issue attributed to that node.\nA declared channel's copy is read from the message-template variant it\nborrows (`template_variant`), so the \"no variant\" issue names the\nvariant to author, not the channel. When the registry itself cannot be\nread, the issue says so instead of calling the channel unknown — the\ntwo are different problems and only one of them is the author's. Node\npositions round-trip for the visual editor.\n\n**Parallel branches.** A label may carry MORE THAN ONE edge, and those\nbranches then execute **concurrently**: a wait with two unlabeled edges\nfans out to two branches, and a condition's \"yes\" may lead to two nodes\nat once. Each branch becomes its own JourneyRun (the forking run\ncontinues down the first branch, a `parent_run_id` branch run is created\nfor each of the rest), so a branch waits, retries and can be exited\nexactly like any run.\n\n**Entry fan-out.** A graph may have SEVERAL entry nodes (nodes with no\ninbound edge). The journey starts them all concurrently: the run begins at\nthe first and a branch run is created for each of the rest. The same\ndisjointness rule applies — two entries may not reach a shared node.\n\nJourneys have **no join node**: branches never rejoin, and each must end\nat its own exit. Saving a fan-out whose branches reconverge is a 422 —\na node reachable from two concurrent branches would execute twice, which\nfor a send node means contacting the profile twice. Branches under\nDIFFERENT labels are mutually exclusive (a condition's yes and no, a\nsplit's arms) and may rejoin freely, as they always have.\n","properties":{"nodes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["condition","wait","split","send","exit","goal","webhook","decide","profile"]},"name":{"type":"string"},"config":{"type":"object","description":"Per-type config. condition: `segment_id` (a saved segment), `filter` (the node's own querybuilder JSON), or BOTH — the two are ANDed, exactly as a batch campaign's audience_filter narrows its segment, and the probe runs against the segment's entity type. A rule VALUE in `filter` may carry personalization tokens ({{.Profile.Attributes.x}}, {{.Profile.Signals.y}}, {{.Run.State.trigger.attributes.z}}), rendered to literals by the engine just before the probe — the CDP only ever receives a plain filter. A value that is exactly one token takes the JSON TYPE of what it read (a number stays a number; digits with a leading zero stay a string); a token inside text stays text. `field`/`operator` are never rendered. A value that will not render fails the branch closed to \"no\". `expr` (expr-lang over attributes/signals/state) is legacy: journeys that stored one still evaluate it, but it cannot be combined with the other two and is no longer offered by the console. wait: exactly one of `duration` (\"30m\", \"4h\", \"2d\", \"1d12h\"), `until_best_send_time: true` (delays to the profile's best_send_hour signal), or `duration_from` — a personalization template rendering to a NUMBER of `duration_unit` (minute/hour/day/week) units, so the wait is computed per profile from a signal, an attribute, or the triggering event (`{{.Run.State.trigger.attributes.x}}`; an event-triggered run starts with its event in run state). `max_wait` caps the two bounded modes (best-send-time defaults to 24h); a profile-supplied wait is capped at 365 days even with no max_wait. With `duration_from`, `duration` is the FALLBACK used when the value will not render or parse — with none, the run continues immediately, and either way the outcome is recorded in run state as `wait:<node_id>`. split: `arms` [{label, weight}], at least two, unique labels, and the weights must add up to EXACTLY 100 — they are read as percentages everywhere they are shown. With `optimize: \"goal\"` the arms become the STARTING allocation: the engine re-weights toward whichever arm converts `goal_node` (a goal node in the same graph, required) best, measured from `journey_runs.state` over the last 30 days and cached for a minute. `explore_percent` (default 20) is spread evenly across the arms forever so a losing arm can recover; `min_samples` (default 100) holds the configured weights until every arm has that many runs. A stats read that fails, an arm with no data, or no conversions anywhere all keep the configured weights. With `optimize: \"winner\"` the split is a hold-and-commit A/B test instead: `test_percent` (1–99, default 20) of arriving traffic runs the arms at the configured weights, the rest is HELD at the split, and `hold_duration` + `hold_unit` (minute/hour/day/week, both required) after the first entrant the arm with the best `goal_node` conversion RATE (among arms with at least `min_wins` conversions, default 3; ties by higher wins, then arm order) is committed as the winner — held runs and all later traffic take its branch. Below `min_wins` the verdict is `inconclusive` and the split runs its configured weights. One verdict per graph version: editing the journey restarts the test. Monitor via the stats report's `experiments`; conclude early via POST /journeys/{id}/splits/{nodeId}/decide. `explore_percent`/`min_samples` belong to \"goal\" only, and the winner fields to \"winner\" only — mixing them is a save error. In BOTH optimizing modes every arm's path must be able to reach the referenced goal node (arms may rejoin): conversion is run-position-based, so an arm that never gets there reads as 0% forever — a save-time issue names the arm. profile: writes customer data back through the CDP — `mode` \"event\" records a CDP event (`event_type`, optional `timestamp_offset` signed duration like \"-2h\" for back-dating OR `timestamp` template rendering an RFC3339 instant; default is now) and `mode` \"attribute\" merges attributes onto the profile (other attributes untouched). Both take `attributes: [{key, value, value_type}]`, where **value is a template** over the send context ({{.Profile.Attributes.x}}, {{.Run.State.y}}, {{.Offer.Payload.z}}) so written values can be personalized, and value_type ∈ string (default) / integer / decimal / boolean / datetime / json / array_string names the type the rendered string is converted to — the CDP does NOT coerce, so an integer attribute given a string is refused. Writing the `campaign_touch` event type is rejected at save time: that ledger backs frequency caps, fatigue and campaign stats. Attribute mode requires `POST /cdp/api/v1/profiles/set` in the service key's scope. send: `template` (library name), `channel` (email/sms/rcs/ whatsapp/viber/push/webhook, an operator-declared channel, an onsite pull channel — web_banner/web_personalization/mobile_inapp — or \"auto\", resolved at delivery time via the profile's channel_affinity_* signals over the native channels AND the tenant's declared ones; \"auto\" never resolves to onsite channels), optional `hold` (onsite channels only: {mode: none|eligibility|custom, filter: querybuilder JSON for custom} — the serve-time hold condition pinned into the content entitlement at send time; \"eligibility\" snapshots the campaign's audience segment's filter tree), optional `provider` (a channel provider instance id; empty = the channel's default provider, and with \"auto\" a set provider also determines the concrete channel), optional `params` (provider parameters, rendered by webhook payload templates as {{.Params.name}}), optional `offer_from` (a decide node id whose chosen offer rides along; skipped when none was chosen), optional `contact_attribute` (resolve the destination from this profile attribute — static or computed — instead of identifier keys; email-, phone- addressed and auto channels only, no identifier fallback), optional `channel_signal_prefix` (\"auto\" only — the signal family the channel argmax runs over, `<prefix><channel>`; empty = `channel_affinity_`), optional `silent_hours` (a SilentHoursSpec overriding the campaign/tenant do-not-send configuration wholesale for this node's sends; {\"disabled\": true} opts out — the OTP-shaped case. Validated at save with the same rules as PUT /silent-hours, issues attributed to the node; pinned onto the send message at queue time like the rest of the node config, while the SCHEDULE itself is evaluated by delivery at send time) and `data`. goal: exactly one of `event_type` (+optional `event_filter` conditions on the event payload, matched in realtime: a map of attribute → {op, value}, where op is one of eq|neq|gt|gte|lt|lte|contains| exists|not_exists — `exists`/`not_exists` carry no value, and a BARE scalar value is equality, the shape every filter written before operators has. Ordering compares as numbers, else as timestamps, else as text; an absent attribute answers no to every question about its value, `neq` included), `expr`, `segment_id`, `filter` (polled on the wake cadence), plus required `timeout` (duration). webhook (the \"call external system\" action): `mode` = \"inline\" (default, and what a graph saved before external systems existed means) or \"system\". mode=system takes ONLY `system_id` (a /systems row), `params` (map of the system's declared parameters to Go TEMPLATE strings, rendered before the system's own body template consumes them as {{.Params.x}}) and `consent_purpose` — the system owns url/method/headers/body/ timeout and holds the credentials, which therefore never enter the graph; sending any of them on the node is a 422. mode=inline takes `url` (http/s), optional `method` (GET/POST/PUT/PATCH/DELETE, default POST), `headers`, `body` (Go template over Profile/Run.State), `timeout_sec` (1-60, default 10) and `network_id` (a CDP private network — the call dials through that tunnel, private destinations allowed within its allowed_cidrs; the id is existence-checked at save time and reported as a node-attributed 422 issue, and a network that disappears later fails the node rather than falling back to the default route) — a raw escape hatch whose headers are stored in the journey definition in clear text, which is why the structured auth schemes are system-only. Both modes take `consent_purpose` (gates the call on live consent), `response_mapping` (map of run-state key to a dotted JSONPath subset — `$.data.available`, `items[0].sku` — lifting response fields into TOP-LEVEL run state, so a later condition reads `state.in_stock` and copy renders {{.Run.State.code}}; a path that does not resolve leaves the key unset, and a key may not start with a reserved engine prefix: webhook:/decide:/split:/send:/goal:/wait:) and `success_when` (\"2xx\" default, \"any\", or an expression over {status, body} plus the mapped keys). The response status, truncated body and resolved `success` land in run state under \"webhook:<id>\". decide: optional `top_n` (default 1) — runs the campaign's NBA in-process, writing the winner under \"decide:<id>\" (offer_id, name, score, payload and `catalog_id`, the pool it came from, which a downstream send node stamps on its queued touch) — plus optional `catalog_id` / `offer_tags` and `context`, a {key: template} map rendered per run into the decide request's `context.*` root (the same root an offer's eligibility rule and score_expr read). A value that is exactly one token takes the JSON type of what it resolves to; the run's own state is merged in as `context.state`, which an author key of that name overrides. decide also takes an optional `items` block (item recommendations plan, task 4.5) that pins one recommendation call to the node, mirroring the `{{items \"<catalog>\" \"<strategy>\" <count> [seed]}}` template helper's arguments: `catalog` (required, non-empty), `strategy` — one of `trending`/`recently_viewed`/`similar_to`/`affinity` (NOT `blend`: a blend needs a list of per-part strategy/weight/seed this single-strategy pin cannot express, and is only reachable through the `/recommendations/{catalog}` HTTP endpoint's richer request body), `count` (0-10, 0 = default 3) and `seed` (a template string, rendered per run against `.Profile`/`.Run.State` exactly like `context` values — the seed item key for `similar_to`). The ranked rows land under the SAME \"decide:<id>\" state key as the offer decision, keyed \"items\": each row is the catalog item's own fields plus `item_key`/`score`/`reason`. A recommendations failure never fails the node or the run — it logs and stores an empty `items` array, so a downstream `{{range}}` just renders nothing. exit: none.\n"},"position":{"type":"object","properties":{"x":{"type":"number"},"y":{"type":"number"}}}},"required":["id","type"]}},"edges":{"type":"array","items":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"},"label":{"type":"string","description":"Branch label (\"yes\"/\"no\", \"on_met\"/\"on_timeout\", split arm) or absent. Several edges may share one label — those branches run in parallel (see the graph description). Two edges with the same label AND the same target are rejected.\n"}},"required":["from","to"]}}},"required":["nodes","edges"]},"JourneyDraftRequest":{"type":"object","description":"Natural-language journey drafting input.","properties":{"description":{"type":"string"}},"required":["description"]},"JourneyDraftResponse":{"type":"object","description":"The LLM-designed draft plus its validation issues (empty = ready to save). NEVER persisted — the editor loads it onto the canvas for review; saving goes through the normal POST/PUT with full validation.\n","properties":{"draft":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"graph":{"$ref":"#/components/schemas/JourneyGraph"},"entry_trigger":{"$ref":"#/components/schemas/EntryTrigger"}}},"issues":{"type":"array","description":"Empty means the draft is ready to save.","items":{"type":"object","properties":{"node_id":{"type":"string"},"message":{"type":"string"},"code":{"type":"string","description":"Stable reason where one exists (contact_attribute_undeclared)."}},"required":["message"]}}},"required":["draft","issues"]},"EntryTrigger":{"type":"object","description":"How profiles enter the journey.\n\n* `event` — matches ingested CDP events (`event_type` + optional\n  `filter` conditions on the payload, the same attribute → {op, value}\n  shape and operator set an event goal's `event_filter` uses — one\n  backend matcher serves both) in realtime.\n* `segment_entry` — enrols current members of `segment_id` on every\n  entry tick, so new members enter as they qualify.\n* `schedule` — enrols `segment_id` on a `cron`.\n* `immediate` — enrols `segment_id` ONCE, as soon as the journey is\n  running, and never again.\n* `planned` — enrols `segment_id` ONCE, at `run_at`.\n* `api` — enrols only via POST /journeys/{id}/enter.\n\n**Every enrolling kind carries its own `segment_id`.** A `schedule`\ntrigger used to borrow the campaign's segment implicitly; it no longer\ndoes, and a journey-based campaign has no campaign-level audience at all\n(existing schedule triggers were backfilled from it automatically).\n\n**A `planned` journey never fires late.** It must already be running when\n`run_at` arrives — the engine arms it on an earlier tick — or the slot is\npermanently missed and it enrols nobody. Saving one whose `run_at` is\nalready past is a 422 for that reason.\n","properties":{"kind":{"type":"string","enum":["event","segment_entry","schedule","immediate","planned","api"]},"event_type":{"type":"string"},"filter":{"type":"object","additionalProperties":true,"description":"Attribute-equality filter for kind=event."},"segment_id":{"type":"string","format":"uuid","description":"Required by segment_entry, schedule, immediate and planned — the audience that kind enrols.\n"},"audience_filter":{"$ref":"#/components/schemas/QueryBuilderFilter","description":"The trigger's OWN querybuilder conditions, ANDed with the segment's live filter — the same relationship a batch campaign's audience_filter has to its segment, so the control means the same thing on both screens. Either may stand alone. Enrolling kinds only; sending it on `event`/`api` is a 422 rather than silently ignored.\n"},"enroll_existing":{"type":"boolean","default":false,"description":"**kind=segment_entry only.** What to do with the profiles already in the segment when the journey starts watching it.\n`false` (the default) is \"enter the journey when you enter the segment\": the first sweep records current members as seen WITHOUT enrolling them, and only profiles that qualify afterwards enter. `true` enrols everybody currently in the segment, then new members as they arrive — the behaviour before this field existed, which was applied to every journey that predates it.\nThe snapshot is per journey (`journey_entry_seen`) and is latched by `entry_seeded_at` only once a full sweep completes, so a segment larger than one pass cannot half-snapshot and then enrol its tail.\n"},"cron":{"type":"string","description":"5-field cron for kind=schedule, evaluated in `timezone`. When both day of month and day of week are restricted a day matching either fires; an expression that never occurs (30 February) is refused."},"timezone":{"type":"string","description":"IANA zone the cron is evaluated in (kind=schedule; validated at save). Empty defaults to the configuring user's profile timezone for session callers, else the engine's historical local zone.\n","example":"Europe/Bratislava"},"run_at":{"type":"string","format":"date-time","description":"RFC3339 moment for kind=planned. Must be in the future at save time."}},"required":["kind"]},"Journey":{"type":"object","description":"One drag-and-drop journey attached to a campaign. `version` bumps on every update; live runs stay pinned to the immutable graph snapshot of the version they entered on. `live_runs`/`live_runs_old_versions` support the editor's \"runs still execute an older version\" warning. `reentry_cooldown_value` null means a profile can never re-enter after a finished run; 0 means it may re-enter immediately.\n","properties":{"id":{"type":"string","format":"uuid"},"campaign_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string"},"graph":{"$ref":"#/components/schemas/JourneyGraph"},"entry_trigger":{"$ref":"#/components/schemas/EntryTrigger"},"version":{"type":"integer"},"reentry_cooldown_value":{"type":"integer","nullable":true,"description":"How long after a finished run the profile may enter again, in `reentry_cooldown_unit`. Null = never; 0 = immediately.\n"},"reentry_cooldown_unit":{"type":"string","enum":["minute","hour","day","week","month"],"description":"Present exactly when `reentry_cooldown_value` is. `month` is calendar arithmetic, not 30 days.\n"},"is_active":{"type":"boolean"},"entry_armed_at":{"type":"string","format":"date-time","nullable":true,"description":"Fires-once triggers only. Set when the engine first saw the journey running while its moment was still ahead — what lets a `planned` journey refuse to fire late without a restart losing its slot.\n"},"entry_fired_at":{"type":"string","format":"date-time","nullable":true,"description":"Fires-once triggers only: when the single enrolment happened (or when a missed `planned` slot was closed out). Non-null means it will never enrol again — clear it with POST .../rearm to run the journey afresh.\n"},"entry_seeded_at":{"type":"string","format":"date-time","nullable":true,"description":"segment_entry with `enroll_existing: false`: when the membership SNAPSHOT completed. Null means it is still being taken (a large segment spans several ticks), and until it is set the journey enrols nobody — the profiles already in the segment are not \"newly added\".\n"},"created_by":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"live_runs":{"type":"integer","format":"int64"},"live_runs_old_versions":{"type":"integer","format":"int64"}},"required":["id","campaign_id","name","graph","entry_trigger","version","is_active"]},"JourneyRequest":{"type":"object","description":"Create/update body. Validation failures return 422 with `data.issues` — a list of {node_id?, message} the editor renders inline. Send-node templates must exist (active, with the configured channel variant); schedule triggers need a parseable cron; and every enrolling trigger kind (segment_entry, schedule, immediate, planned) needs its own existing segment of the campaign's entity type.\n","properties":{"name":{"type":"string"},"description":{"type":"string"},"graph":{"$ref":"#/components/schemas/JourneyGraph"},"entry_trigger":{"$ref":"#/components/schemas/EntryTrigger"},"reentry_cooldown_value":{"type":"integer","nullable":true,"minimum":0},"reentry_cooldown_unit":{"type":"string","enum":["minute","hour","day","week","month"],"description":"Defaults to `day` when a value is sent without one."},"reentry_cooldown_days":{"type":"integer","nullable":true,"minimum":0,"deprecated":true,"description":"The cooldown as a bare day count, superseded by `reentry_cooldown_value` + `reentry_cooldown_unit`. Still honoured (as days) because config-revision snapshots written before the unit existed carry it, and a restore replays the snapshot through this body. Ignored when `reentry_cooldown_value` is present.\n"},"is_active":{"type":"boolean","default":true}},"required":["name","graph","entry_trigger"]},"JourneyRun":{"type":"object","description":"One profile's live position in a journey. `state` carries per-run variables (split arms under \"split:<nodeId>\", send outcomes under \"send:<nodeId>\"). `wake_at` is the next engine evaluation time for waiting runs.\n","properties":{"id":{"type":"string","format":"uuid"},"journey_id":{"type":"string","format":"uuid"},"journey_version":{"type":"integer"},"profile_id":{"type":"string","format":"uuid"},"entity_type":{"type":"string"},"current_node_id":{"type":"string","description":"The next node to execute."},"state":{"type":"object","additionalProperties":true},"status":{"type":"string","enum":["running","waiting","completed","exited","failed"]},"error":{"type":"string"},"wake_at":{"type":"string","format":"date-time","nullable":true},"parent_run_id":{"type":"string","format":"uuid","description":"Set on a BRANCH run — the run that forked at a parallel fan-out. Absent on a root run (entered from a trigger, a segment or the API). A profile therefore has several live runs of one journey while it is inside a fan-out, one per concurrent branch; re-entry stays blocked until every one of them finishes.\n"},"branch_node_id":{"type":"string","description":"The node a branch run started at (the fan-out edge's target). Absent on root runs.\n"},"entered_at":{"type":"string","format":"date-time"},"finished_at":{"type":"string","format":"date-time","nullable":true},"updated_at":{"type":"string","format":"date-time"}},"required":["id","journey_id","journey_version","profile_id","status"]},"EnterJourneyRequest":{"type":"object","description":"Manual enrollment (the `api` entry trigger's front door; works for any journey as a test hook). entity_type defaults to the campaign's.\n","properties":{"profile_id":{"type":"string","format":"uuid"},"entity_type":{"type":"string"}},"required":["profile_id"]},"Destination":{"type":"object","description":"Optima Activation: one connected ad-platform account. Secrets are write-only — reads expose has_credentials, never values.\n","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","example":"prod-google-ads"},"platform":{"type":"string","description":"Implemented: google_ads (meta_ads/adform are later adapters)."},"account_ref":{"type":"string","description":"Ad-account handle. google_ads — the Ads customer id (digits; dashes accepted)."},"is_active":{"type":"boolean"},"config":{"type":"object","description":"Non-secret platform settings. google_ads: login_customer_id (MCC), api_version (default v21).\n"},"has_credentials":{"type":"boolean"},"created_by":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","name","platform","is_active"]},"DestinationRequest":{"type":"object","description":"Create/update body for a destination. platform is immutable after creation. Credentials are write-only — omit on update to keep stored secrets. google_ads requires developer_token, client_id, client_secret and refresh_token (offline-access OAuth token, scope adwords); AES-256-GCM encrypted at rest.\n","properties":{"name":{"type":"string"},"platform":{"type":"string"},"account_ref":{"type":"string"},"is_active":{"type":"boolean","default":true},"config":{"type":"object","nullable":true,"description":"google_ads reads `login_customer_id` (the manager account) and `api_version` (default v21). On update, omitting it or sending `null` keeps the stored config; `{}` clears it.\n"},"credentials":{"type":"object","additionalProperties":{"type":"string"}}},"required":["name","platform"]},"AudienceSync":{"type":"object","description":"Optima Activation: continuously mirrors one Campaign segment to one remote ad-platform audience of SHA-256-hashed match keys. Membership is consent-gated live at every run (consent_purpose, basis-aware) and suppression-checked; an erased or consent-withdrawn profile is removed from the remote list on the next run. The membership snapshot stores hashes only — never raw contacts, never profile ids.\n","properties":{"id":{"type":"string","format":"uuid"},"destination_id":{"type":"string","format":"uuid"},"segment_id":{"type":"string","format":"uuid"},"name":{"type":"string","description":"Also the default remote audience name (config.audience_name overrides)."},"match_keys":{"type":"array","items":{"type":"string"},"description":"\"<type>:<identifier_key>\" tokens, type ∈ email|phone — which profile identifiers become platform match keys (e.g. [\"email:email\",\"phone:phone\"]). Default [\"email:email\"].\n"},"sync_mode":{"type":"string","enum":["full_reconcile","delta"],"description":"full_reconcile (default) re-asserts the full consented set every run and removes the previously-synced difference (self-healing removals); delta pushes only new members (removals identical).\n"},"schedule":{"type":"string","description":"5-field cron evaluated in `timezone`; empty = manual-only via POST /audiences/{id}/sync. When both day of month and day of week are restricted a day matching either fires; an expression that never occurs (30 February) is refused."},"timezone":{"type":"string","description":"IANA zone the schedule cron is evaluated in. Empty means the syncer's historical local zone.\n","example":"Europe/Bratislava"},"consent_purpose":{"type":"string","description":"Consent purpose gating membership (default advertising), evaluated live per run against each member's CDP consents (lawful-basis aware) and used as the X-Purpose of the engine's CDP reads.\n"},"remote_audience_id":{"type":"string","description":"Engine-cached remote list resource (e.g. customers/N/userLists/M)."},"config":{"type":"object","description":"Per-sync platform settings. google_ads: audience_name, audience_resource (pin an existing list — never created), membership_life_span_days (10000 = no expiry, default; else 1..540), batch_size (default 5000), default_phone_prefix (e.g. \"+421\"), consent_ad_user_data / consent_ad_personalization (default GRANTED).\n"},"is_active":{"type":"boolean"},"created_by":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","destination_id","segment_id","name","sync_mode"]},"AudienceSyncRequest":{"type":"object","description":"Create/update body for an audience sync. destination_id is immutable after creation. consent_purpose is validated against the CDP purpose catalog at save (best-effort) and enforced live at every run.\n","properties":{"destination_id":{"type":"string","format":"uuid"},"segment_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"match_keys":{"type":"array","items":{"type":"string"}},"sync_mode":{"type":"string","enum":["full_reconcile","delta"]},"schedule":{"type":"string"},"timezone":{"type":"string","description":"IANA zone the schedule cron is evaluated in (validated at save). Empty defaults to the configuring user's profile timezone for session callers, else the syncer's historical local zone.\n","example":"Europe/Bratislava"},"consent_purpose":{"type":"string"},"config":{"type":"object"},"is_active":{"type":"boolean","default":false}},"required":["destination_id","segment_id","name"]},"AudienceSyncRun":{"type":"object","description":"One executed (or running) audience sync. matched = segment members; consented = past the consent gate; added/removed = member keys the platform accepted (0 when the upload was aborted); in sink mode they are the members that would be added/removed - nothing was sent and no snapshot is stored; skipped = excluded (no/withdrawn consent, suppressed contact, no usable identifier). job_ref is the opaque platform job (Google offline-user-data job).\n","properties":{"id":{"type":"string","format":"uuid"},"sync_id":{"type":"string","format":"uuid"},"scheduled_for":{"type":"string","format":"date-time"},"started_at":{"type":"string","format":"date-time"},"finished_at":{"type":"string","format":"date-time","nullable":true},"status":{"type":"string","enum":["running","completed","failed"]},"matched":{"type":"integer"},"consented":{"type":"integer"},"added":{"type":"integer"},"removed":{"type":"integer"},"skipped":{"type":"integer"},"held_out":{"type":"integer","description":"Profiles excluded because they fall in the entity's global control group. Counted separately from `skipped` — nothing was wrong with the member; it is deliberately withheld so the holdout stays uncontacted across every surface.\n"},"error":{"type":"string"},"note":{"type":"string","description":"Set when the run completed without contacting the platform, e.g. the tenant's outbound mode is `sink`. Not an error.\n"},"job_ref":{"type":"string"}},"required":["id","sync_id","scheduled_for","status"]}}},"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"tags":[{"name":"Health","description":"Public liveness probes for the Campaign and NBA services."},{"name":"Segments","description":"Reusable audience definitions, their members, counts and facets."},{"name":"Campaigns","description":"Create, edit and run campaigns: activation, pausing, archiving, reopening and duplication."},{"name":"Approvals","description":"The approval workflow for campaigns: requesting, approving, rejecting, and the approval queue."},{"name":"Offers","description":"Offers inside a campaign or an offer catalog."},{"name":"Offer catalogs","description":"Catalogs of reusable offers for next-best-action decisioning."},{"name":"Journeys","description":"Multi-step journeys: authoring, activation, entering profiles, runs and split decisions."},{"name":"Pre-flight checks","description":"Dry runs before a send: reach, rendering, trace, simulation, entitlement and test sends."},{"name":"Reporting and responses","description":"Campaign and journey statistics, recorded responses, lift, attribution, predictions and insights."},{"name":"Next best action","description":"Decisioning calls that pick the best offer for a profile."},{"name":"Templates","description":"Message templates, previews, rendering, translation and AI-assisted drafting."},{"name":"Documents","description":"Document templates rendered per recipient into PDFs, with preview and rendering."},{"name":"Channels","description":"Delivery channels, channel providers, receipts and the provider catalog."},{"name":"Code pools","description":"Pools of single-use codes, their upload, generation and remaining stock."},{"name":"Languages","description":"The languages a tenant sends in."},{"name":"Contact policies","description":"Fatigue limits, response policies, silent hours and control groups that decide who may be contacted and when."},{"name":"External systems","description":"Connections to external systems that campaigns call or read from."},{"name":"Destinations","description":"Ad-platform and other activation destinations."},{"name":"Audiences","description":"Audiences synchronised to destinations and their sync runs."},{"name":"Revisions and changelog","description":"The change history of campaign resources, field-level diffs, and rollback to an earlier revision."}],"paths":{"/campaign/health":{"get":{"tags":["Health"],"summary":"Health check","security":[],"responses":{"200":{"description":"Service and Campaign DB healthy.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}}}}},"/campaign/api/v1/changelog":{"get":{"tags":["Revisions and changelog"],"summary":"Suite-wide configuration audit feed","description":"Every recorded configuration change across the suite, newest first.\nThis is the auditing entry point: filter by resource, by actor, by\naction, or by time window.\n","parameters":[{"name":"resource_type","in":"query","required":false,"schema":{"type":"string","enum":["campaign","offer","offer_catalog","journey","template","segment","fatigue_policy","response_policy","document","code_pool"]}},{"name":"resource_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"campaign_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"Scope to one campaign's tree (itself plus its offers and journeys)."},{"$ref":"#/components/parameters/RevisionActor"},{"$ref":"#/components/parameters/RevisionAction"},{"$ref":"#/components/parameters/RevisionFrom"},{"$ref":"#/components/parameters/RevisionTo"},{"$ref":"#/components/parameters/RevisionIncludeSnapshot"},{"name":"page","in":"query","required":false,"schema":{"type":"integer","default":0}},{"name":"size","in":"query","required":false,"schema":{"type":"integer","default":50}}],"responses":{"200":{"description":"Newest first, with page metadata.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ConfigRevision"}}}}]}}}},"400":{"description":"Unparseable `from`/`to` timestamp."}}}},"/campaign/api/v1/campaigns/{id}/changelog":{"get":{"tags":["Revisions and changelog"],"summary":"One campaign's composite changelog","description":"The campaign's own revisions PLUS every revision of its offers and\njourneys, interleaved newest first. That composite view is the point:\n\"who changed this campaign\" almost never means the campaign row alone.\n\nThe path owns the scope - a conflicting `?campaign_id=` is ignored, so\nthis route can never return another campaign's history.\n","parameters":[{"$ref":"#/components/parameters/CampaignId"},{"name":"resource_type","in":"query","required":false,"schema":{"type":"string","enum":["campaign","offer","journey"]},"description":"Narrow the composite feed to one level of the tree."},{"$ref":"#/components/parameters/RevisionActor"},{"$ref":"#/components/parameters/RevisionAction"},{"$ref":"#/components/parameters/RevisionFrom"},{"$ref":"#/components/parameters/RevisionTo"},{"$ref":"#/components/parameters/RevisionIncludeSnapshot"},{"name":"page","in":"query","required":false,"schema":{"type":"integer","default":0}},{"name":"size","in":"query","required":false,"schema":{"type":"integer","default":50}}],"responses":{"200":{"description":"`data` is a list of ConfigRevision, newest first.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ConfigRevision"}}}}]}}}},"400":{"description":"Unparseable `from`/`to` timestamp."},"404":{"description":"Not found, or the id in the path is not a uuid."}}}},"/campaign/api/v1/campaigns/{id}/revisions":{"get":{"tags":["Revisions and changelog"],"summary":"List a campaign's revisions","description":"The campaign row's own history (use `.../changelog` for the composite\nview including offers and journeys).\n\nHistory outlives the object: this stays readable after the campaign is\ndeleted, which is exactly when it is needed most. An unknown id simply\nhas no revisions.\n","parameters":[{"$ref":"#/components/parameters/CampaignId"},{"$ref":"#/components/parameters/RevisionActor"},{"$ref":"#/components/parameters/RevisionAction"},{"$ref":"#/components/parameters/RevisionFrom"},{"$ref":"#/components/parameters/RevisionTo"},{"$ref":"#/components/parameters/RevisionIncludeSnapshot"},{"name":"page","in":"query","required":false,"schema":{"type":"integer","default":0}},{"name":"size","in":"query","required":false,"schema":{"type":"integer","default":50}}],"responses":{"200":{"description":"`data` is a list of ConfigRevision, newest first.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ConfigRevision"}}}}]}}}},"404":{"description":"Not found, or the id in the path is not a uuid."}}}},"/campaign/api/v1/campaigns/{id}/revisions/{revision}":{"get":{"tags":["Revisions and changelog"],"summary":"Read one campaign revision","description":"Includes the full `snapshot` - the configuration a restore would replay.","parameters":[{"$ref":"#/components/parameters/CampaignId"},{"$ref":"#/components/parameters/RevisionNumber"}],"responses":{"200":{"description":"`data` is the ConfigRevision.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ConfigRevision"}}}]}}}},"400":{"description":"`revision` is not a positive integer."},"404":{"description":"Revision not found."}}}},"/campaign/api/v1/campaigns/{id}/revisions/{revision}/restore":{"post":{"tags":["Revisions and changelog"],"summary":"Roll a campaign back to an earlier revision","description":"Replays the revision's snapshot through the campaign's normal update\npath, then records the rollback as a new `restore` revision carrying\n`restored_from` (so a restore is itself auditable, and restoring a\nrestore works).\n\nTwo deliberate limits:\n\n* **Status is not restored.** Lifecycle is not configuration: rolling\n  back an audience definition never re-activates a paused campaign nor\n  pauses a live one.\n* **A `delete` revision cannot be restored** (409). Resurrecting a row\n  would silently re-point references that were resolved on the\n  assumption it was gone.\n\nRollback is not a privileged write path: the snapshot is re-validated\nas a PUT, and the referenced template must exist and be active, so\none naming a since-deleted segment or provider, or a deleted or\ninactive template, is rejected with 422. The template check is\nrestore-only: a draft PUT may name a template that does not exist\nyet.\n","parameters":[{"$ref":"#/components/parameters/CampaignId"},{"$ref":"#/components/parameters/RevisionNumber"}],"responses":{"200":{"description":"`data` is a RestoreResult.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RestoreResult"}}}]}}}},"400":{"description":"`revision` is not a positive integer."},"404":{"description":"Revision not found, or the campaign no longer exists."},"409":{"description":"The revision records a delete, or has no stored configuration."},"422":{"description":"The stored configuration is no longer valid (a referenced object is gone, or its template no longer exists or is inactive)."}}}},"/campaign/api/v1/campaigns/{id}/offers/{offerId}/revisions":{"get":{"tags":["Revisions and changelog"],"summary":"List an offer's revisions","parameters":[{"$ref":"#/components/parameters/CampaignId"},{"$ref":"#/components/parameters/OfferId"},{"$ref":"#/components/parameters/RevisionIncludeSnapshot"},{"name":"page","in":"query","required":false,"schema":{"type":"integer","default":0}},{"name":"size","in":"query","required":false,"schema":{"type":"integer","default":50}}],"responses":{"200":{"description":"`data` is a list of ConfigRevision, newest first.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ConfigRevision"}}}}]}}}},"404":{"description":"Not found, or the id in the path is not a uuid."}}}},"/campaign/api/v1/campaigns/{id}/offers/{offerId}/revisions/{revision}":{"get":{"tags":["Revisions and changelog"],"summary":"Read one offer revision","parameters":[{"$ref":"#/components/parameters/CampaignId"},{"$ref":"#/components/parameters/OfferId"},{"$ref":"#/components/parameters/RevisionNumber"}],"responses":{"200":{"description":"`data` is the ConfigRevision, snapshot included.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ConfigRevision"}}}]}}}},"404":{"description":"Revision not found."}}}},"/campaign/api/v1/campaigns/{id}/offers/{offerId}/revisions/{revision}/restore":{"post":{"tags":["Revisions and changelog"],"summary":"Roll an offer back to an earlier revision","description":"Replays the snapshot through the offer's normal update path (the eligibility expression is recompiled, a referenced eligibility segment must still exist and match the entity type) and records a `restore` revision.\n","parameters":[{"$ref":"#/components/parameters/CampaignId"},{"$ref":"#/components/parameters/OfferId"},{"$ref":"#/components/parameters/RevisionNumber"}],"responses":{"200":{"description":"`data` is a RestoreResult.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RestoreResult"}}}]}}}},"404":{"description":"Revision not found, or the offer no longer exists."},"409":{"description":"The revision records a delete."},"422":{"description":"The stored configuration is no longer valid."}}}},"/campaign/api/v1/campaigns/{id}/journeys/{journeyId}/revisions":{"get":{"tags":["Revisions and changelog"],"summary":"List a journey's revisions","parameters":[{"$ref":"#/components/parameters/CampaignId"},{"$ref":"#/components/parameters/JourneyId"},{"$ref":"#/components/parameters/RevisionIncludeSnapshot"},{"name":"page","in":"query","required":false,"schema":{"type":"integer","default":0}},{"name":"size","in":"query","required":false,"schema":{"type":"integer","default":50}}],"responses":{"200":{"description":"`data` is a list of ConfigRevision, newest first.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ConfigRevision"}}}}]}}}},"404":{"description":"Not found, or the id in the path is not a uuid."}}}},"/campaign/api/v1/campaigns/{id}/journeys/{journeyId}/revisions/{revision}":{"get":{"tags":["Revisions and changelog"],"summary":"Read one journey revision","description":"The snapshot carries the whole graph and entry trigger, so the console can render an old canvas beside the current one.\n","parameters":[{"$ref":"#/components/parameters/CampaignId"},{"$ref":"#/components/parameters/JourneyId"},{"$ref":"#/components/parameters/RevisionNumber"}],"responses":{"200":{"description":"`data` is the ConfigRevision, snapshot included.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ConfigRevision"}}}]}}}},"404":{"description":"Revision not found."}}}},"/campaign/api/v1/campaigns/{id}/journeys/{journeyId}/revisions/{revision}/restore":{"post":{"tags":["Revisions and changelog"],"summary":"Roll a journey back to an earlier revision","description":"Replays the snapshot through the journey's normal update path: the graph\nis fully re-validated, and the save bumps the journey version and\nsnapshots the restored graph. Live runs therefore keep executing the\nversion they entered on - a rollback never rewrites a run in flight.\n\nValidation failures return the same **422 with structured\n`data.issues`** a normal save does, so the canvas renders them inline.\n","parameters":[{"$ref":"#/components/parameters/CampaignId"},{"$ref":"#/components/parameters/JourneyId"},{"$ref":"#/components/parameters/RevisionNumber"}],"responses":{"200":{"description":"`data` is a RestoreResult whose `resource` is the JourneyDetail.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RestoreResult"}}}]}}}},"403":{"description":"`campaign requires approval`: the campaign is active and the caller is not an approver (a journey write would put new sends live unapproved)."},"404":{"description":"Revision not found, or the journey no longer exists."},"409":{"description":"The revision records a delete."},"422":{"description":"Graph validation failed - `data.issues` carries node-attributed messages - or a referenced template no longer exists.\n"}}}},"/campaign/api/v1/templates/{id}/revisions":{"get":{"tags":["Revisions and changelog"],"summary":"List a message template's revisions","parameters":[{"$ref":"#/components/parameters/TemplateId"},{"$ref":"#/components/parameters/RevisionIncludeSnapshot"},{"name":"page","in":"query","required":false,"schema":{"type":"integer","default":0}},{"name":"size","in":"query","required":false,"schema":{"type":"integer","default":50}}],"responses":{"200":{"description":"`data` is a list of ConfigRevision, newest first.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ConfigRevision"}}}}]}}}},"404":{"description":"Not found, or the id in the path is not a uuid."}}}},"/campaign/api/v1/templates/{id}/revisions/{revision}":{"get":{"tags":["Revisions and changelog"],"summary":"Read one template revision","parameters":[{"$ref":"#/components/parameters/TemplateId"},{"$ref":"#/components/parameters/RevisionNumber"}],"responses":{"200":{"description":"`data` is the ConfigRevision, snapshot included.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ConfigRevision"}}}]}}}},"404":{"description":"Revision not found."}}}},"/campaign/api/v1/templates/{id}/revisions/{revision}/restore":{"post":{"tags":["Revisions and changelog"],"summary":"Roll a message template back to an earlier revision","description":"Replays the snapshot through the SAME pipeline PUT runs (variants re-parsed and every template string re-validated, declared channels, attachment references incl. the caller's PII gate and the PII gate on a document attachment's own layout, coupon refs, and the language mutations, which restore exactly as the snapshot recorded them rather than being wiped).\n","parameters":[{"$ref":"#/components/parameters/TemplateId"},{"$ref":"#/components/parameters/RevisionNumber"}],"responses":{"200":{"description":"`data` is a RestoreResult.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RestoreResult"}}}]}}}},"403":{"description":"The snapshot's attachments (or a referenced document's layout) carry a PII level above the caller's access level."},"404":{"description":"Revision not found, or the template no longer exists."},"409":{"description":"The revision records a delete."},"422":{"description":"The stored variants are no longer valid."}}}},"/campaign/api/v1/segments/{id}/revisions":{"get":{"tags":["Revisions and changelog"],"summary":"List a segment's revisions","parameters":[{"$ref":"#/components/parameters/SegmentId"},{"$ref":"#/components/parameters/RevisionIncludeSnapshot"},{"name":"page","in":"query","required":false,"schema":{"type":"integer","default":0}},{"name":"size","in":"query","required":false,"schema":{"type":"integer","default":50}}],"responses":{"200":{"description":"`data` is a list of ConfigRevision, newest first.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ConfigRevision"}}}}]}}}},"404":{"description":"Not found, or the id in the path is not a uuid."}}}},"/campaign/api/v1/segments/{id}/revisions/{revision}":{"get":{"tags":["Revisions and changelog"],"summary":"Read one segment revision","parameters":[{"$ref":"#/components/parameters/SegmentId"},{"$ref":"#/components/parameters/RevisionNumber"}],"responses":{"200":{"description":"`data` is the ConfigRevision, snapshot included.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ConfigRevision"}}}]}}}},"404":{"description":"Revision not found."}}}},"/campaign/api/v1/segments/{id}/revisions/{revision}/restore":{"post":{"tags":["Revisions and changelog"],"summary":"Roll a segment back to an earlier revision","description":"Replays the snapshot through the segment's normal update path, so the stored querybuilder filter is re-validated before it becomes live again. A material change clears the approval of every approved campaign targeting the segment.\n","parameters":[{"$ref":"#/components/parameters/SegmentId"},{"$ref":"#/components/parameters/RevisionNumber"}],"responses":{"200":{"description":"`data` is a RestoreResult.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RestoreResult"}}}]}}}},"404":{"description":"Revision not found, or the segment no longer exists."},"409":{"description":"The revision records a delete."},"422":{"description":"The stored filter is no longer valid."}}}},"/campaign/api/v1/offer-catalogs/{id}/revisions":{"get":{"tags":["Revisions and changelog"],"summary":"List an offer catalogue's revisions","parameters":[{"$ref":"#/components/parameters/CatalogId"},{"$ref":"#/components/parameters/RevisionIncludeSnapshot"},{"name":"page","in":"query","required":false,"schema":{"type":"integer","default":0}},{"name":"size","in":"query","required":false,"schema":{"type":"integer","default":50}}],"responses":{"200":{"description":"`data` is a list of ConfigRevision, newest first.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ConfigRevision"}}}}]}}}},"404":{"description":"Not found, or the id in the path is not a uuid."}}}},"/campaign/api/v1/offer-catalogs/{id}/revisions/{revision}":{"get":{"tags":["Revisions and changelog"],"summary":"Read one offer catalogue revision","parameters":[{"$ref":"#/components/parameters/CatalogId"},{"$ref":"#/components/parameters/RevisionNumber"}],"responses":{"200":{"description":"`data` is the ConfigRevision, snapshot included.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ConfigRevision"}}}]}}}},"404":{"description":"Revision not found."}}}},"/campaign/api/v1/offer-catalogs/{id}/revisions/{revision}/restore":{"post":{"tags":["Revisions and changelog"],"summary":"Roll an offer catalogue back to an earlier revision","description":"Replays the snapshot through the catalogue's PUT rules (immutable entity type, object default payload, compilable scoring). A material change clears the approval of every approved campaign ranking over the catalogue.\n","parameters":[{"$ref":"#/components/parameters/CatalogId"},{"$ref":"#/components/parameters/RevisionNumber"}],"responses":{"200":{"description":"`data` is a RestoreResult.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RestoreResult"}}}]}}}},"404":{"description":"Revision not found, or the catalogue no longer exists."},"409":{"description":"The revision records a delete."},"422":{"description":"The stored configuration is no longer valid."}}}},"/campaign/api/v1/offer-catalogs/{id}/offers/{offerId}/revisions":{"get":{"tags":["Revisions and changelog"],"summary":"List a catalogue offer's revisions","parameters":[{"$ref":"#/components/parameters/CatalogId"},{"$ref":"#/components/parameters/OfferId"},{"$ref":"#/components/parameters/RevisionIncludeSnapshot"},{"name":"page","in":"query","required":false,"schema":{"type":"integer","default":0}},{"name":"size","in":"query","required":false,"schema":{"type":"integer","default":50}}],"responses":{"200":{"description":"`data` is a list of ConfigRevision, newest first.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ConfigRevision"}}}}]}}}},"404":{"description":"Not found, or the id in the path is not a uuid."}}}},"/campaign/api/v1/offer-catalogs/{id}/offers/{offerId}/revisions/{revision}":{"get":{"tags":["Revisions and changelog"],"summary":"Read one catalogue offer revision","parameters":[{"$ref":"#/components/parameters/CatalogId"},{"$ref":"#/components/parameters/OfferId"},{"$ref":"#/components/parameters/RevisionNumber"}],"responses":{"200":{"description":"`data` is the ConfigRevision, snapshot included.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ConfigRevision"}}}]}}}},"404":{"description":"Revision not found."}}}},"/campaign/api/v1/offer-catalogs/{id}/offers/{offerId}/revisions/{revision}/restore":{"post":{"tags":["Revisions and changelog"],"summary":"Roll a catalogue offer back to an earlier revision","description":"Restores a catalogue-owned offer. The offer is looked up within the path's catalogue (404 otherwise), so a revision is only ever replayed into its own catalogue. Clears the approval of every approved campaign ranking over the catalogue.\n","parameters":[{"$ref":"#/components/parameters/CatalogId"},{"$ref":"#/components/parameters/OfferId"},{"$ref":"#/components/parameters/RevisionNumber"}],"responses":{"200":{"description":"`data` is a RestoreResult.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RestoreResult"}}}]}}}},"404":{"description":"Revision not found, or the offer is not (or no longer) in this catalogue."},"409":{"description":"The revision records a delete."},"422":{"description":"The stored configuration is no longer valid."}}}},"/campaign/api/v1/documents/{id}/revisions":{"get":{"tags":["Revisions and changelog"],"summary":"List a document template's revisions","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/RevisionIncludeSnapshot"},{"name":"page","in":"query","required":false,"schema":{"type":"integer","default":0}},{"name":"size","in":"query","required":false,"schema":{"type":"integer","default":50}}],"responses":{"200":{"description":"`data` is a list of ConfigRevision, newest first.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ConfigRevision"}}}}]}}}},"404":{"description":"Not found, or the id in the path is not a uuid."}}}},"/campaign/api/v1/documents/{id}/revisions/{revision}":{"get":{"tags":["Revisions and changelog"],"summary":"Read one document template revision","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/RevisionNumber"}],"responses":{"200":{"description":"`data` is the ConfigRevision, snapshot included.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ConfigRevision"}}}]}}}},"404":{"description":"Revision not found."}}}},"/campaign/api/v1/documents/{id}/revisions/{revision}/restore":{"post":{"tags":["Revisions and changelog"],"summary":"Roll a document template back to an earlier revision","description":"Replays the snapshot through the document save path (layout, templates, content refs and the caller's PII gate). A material change clears the campaigns sending a template that attaches the document.\n","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/RevisionNumber"}],"responses":{"200":{"description":"`data` is a RestoreResult.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RestoreResult"}}}]}}}},"403":{"description":"The layout references content above the caller's PII level."},"404":{"description":"Revision not found, or the document template no longer exists."},"409":{"description":"The revision records a delete."},"422":{"description":"The stored configuration is no longer valid."}}}},"/campaign/api/v1/code-pools/{id}/revisions":{"get":{"tags":["Revisions and changelog"],"summary":"List a code pool's revisions","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/RevisionIncludeSnapshot"},{"name":"page","in":"query","required":false,"schema":{"type":"integer","default":0}},{"name":"size","in":"query","required":false,"schema":{"type":"integer","default":50}}],"responses":{"200":{"description":"`data` is a list of ConfigRevision, newest first.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ConfigRevision"}}}}]}}}},"404":{"description":"Not found, or the id in the path is not a uuid."}}}},"/campaign/api/v1/code-pools/{id}/revisions/{revision}":{"get":{"tags":["Revisions and changelog"],"summary":"Read one code pool revision","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/RevisionNumber"}],"responses":{"200":{"description":"`data` is the ConfigRevision, snapshot included.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ConfigRevision"}}}]}}}},"404":{"description":"Revision not found."}}}},"/campaign/api/v1/code-pools/{id}/revisions/{revision}/restore":{"post":{"tags":["Revisions and changelog"],"summary":"Roll a code pool's configuration back to an earlier revision","description":"Restores pool configuration only — never codes. The kind cannot change. A rename away from a name active templates claim from is refused unless `force=true`, as on PUT. A material change (including a rename) clears the campaigns sending a template that claims from the old or the new name.\n","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"force","in":"query","required":false,"schema":{"type":"boolean"},"description":"Restore a rename away from a pool name active templates claim from (as on PUT)."},{"$ref":"#/components/parameters/RevisionNumber"}],"responses":{"200":{"description":"`data` is a RestoreResult.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RestoreResult"}}}]}}}},"404":{"description":"Revision not found, or the code pool no longer exists."},"409":{"description":"The revision records a delete, or it renames a pool active templates claim from (without force=true)."},"422":{"description":"The stored configuration is no longer valid."}}}},"/campaign/api/v1/fatigue-policies/{id}/revisions":{"get":{"tags":["Revisions and changelog"],"summary":"List a fatigue policy's revisions","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/RevisionIncludeSnapshot"},{"name":"page","in":"query","required":false,"schema":{"type":"integer","default":0}},{"name":"size","in":"query","required":false,"schema":{"type":"integer","default":50}}],"responses":{"200":{"description":"`data` is a list of ConfigRevision, newest first.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ConfigRevision"}}}}]}}}},"404":{"description":"Not found, or the id in the path is not a uuid."}}}},"/campaign/api/v1/fatigue-policies/{id}/revisions/{revision}":{"get":{"tags":["Revisions and changelog"],"summary":"Read one fatigue policy revision","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/RevisionNumber"}],"responses":{"200":{"description":"`data` is the ConfigRevision, snapshot included.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ConfigRevision"}}}]}}}},"404":{"description":"Revision not found."}}}},"/campaign/api/v1/fatigue-policies/{id}/revisions/{revision}/restore":{"post":{"tags":["Revisions and changelog"],"summary":"Roll a fatigue policy back to an earlier revision","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/RevisionNumber"}],"responses":{"200":{"description":"`data` is a RestoreResult.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RestoreResult"}}}]}}}},"404":{"description":"Revision not found, or the policy no longer exists."},"409":{"description":"The revision records a delete."},"422":{"description":"The stored configuration is no longer valid."}}}},"/campaign/api/v1/segments":{"get":{"tags":["Segments"],"summary":"List segments","description":"Lists saved segments, newest organisation filters included. `folder` is\n**opt-in by key presence**: omitting it lists every folder, while\n`?folder=` (empty value) lists only root-level (\"ungrouped\") segments.\nTags AND together — a segment must carry all of them to match.\n","parameters":[{"name":"entity_type","in":"query","required":false,"schema":{"type":"string"}},{"name":"search","in":"query","required":false,"description":"Case-insensitive **substring** match on the segment name, for\ntypeahead pickers; LIKE metacharacters are escaped. Blank is no\nfilter. Spelled `search` rather than `name` on purpose — the CDP's\nreport list uses `name=` for an *exact* match.\n","schema":{"type":"string"},"example":"high-value"},{"name":"folder","in":"query","required":false,"description":"Materialized folder path, normalised server-side. Present-but-empty\nselects the root folder; absent applies no folder filter.\n","schema":{"type":"string"},"example":"Lifecycle/Winback"},{"name":"subtree","in":"query","required":false,"description":"With `folder`, also match every descendant folder.","schema":{"type":"boolean","default":false}},{"name":"tag","in":"query","required":false,"description":"Comma-separated tags; a segment must carry ALL of them.","schema":{"type":"string"},"example":"vip,q3"},{"name":"page","in":"query","schema":{"type":"integer","minimum":0}},{"name":"size","in":"query","description":"Omitted (or 0) means the platform default of 100; 100 is also the cap.","schema":{"type":"integer","minimum":1,"maximum":100,"default":100}}],"responses":{"200":{"description":"Segments with page metadata.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Segment"}}}}]}}}}}},"post":{"tags":["Segments"],"summary":"Create a segment","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SegmentRequest"}}}},"responses":{"201":{"description":"Segment created.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Segment"}}}]}}}},"400":{"description":"Invalid payload or structurally invalid filter (bad combinator, unknown operator/namespace)."},"409":{"description":"A segment with this name already exists for the entity type."}}}},"/campaign/api/v1/segments/facets":{"get":{"tags":["Segments"],"summary":"Distinct segment folders and tags","description":"The distinct folder paths and tags in use, for building the folder tree\nand the tag filter without paging through every segment. The root\nfolder is not listed — clients offer it as a fixed \"ungrouped\" entry.\n","parameters":[{"name":"entity_type","in":"query","required":false,"description":"Scope both lists to one entity type, so the tree has no branches that are empty under the current selection.","schema":{"type":"string"}}],"responses":{"200":{"description":"Folder paths and tags.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OrganizeFacets"}}}]}}}}}}},"/campaign/api/v1/segments/counts":{"get":{"tags":["Segments"],"summary":"Live member counts for several segments","description":"The member count for each of the given segments, in one request.\n\nA segments LIST says what each segment is and nothing about its size,\nso choosing between two of them meant opening both. The count already\nexisted per segment (`GET /segments/{id}/count`); what did not exist\nwas a way to ask for a page of them without a request each.\n\nEach count is a live profile query against the CDP under the caller's\n`X-Purpose`, so the batch is capped at 100 ids and the fan-out is\nbounded — the cost is a function of the PAGE being shown, not of the\ncatalogue. Ids are deduplicated.\n\nPer-segment failures are reported per segment in `errors` rather than\nfailing the batch: one segment whose filter references a since-deleted\nsignal must not blank the size column for the rest. An authorization or\npurpose denial IS fatal to the request — it is the same answer for\nevery segment, and rendering it into each row would say the segments\nare broken when it is the request that is.\n\nA GET rather than a POST because this is a read, and the read-only\nroles (`campaign_viewer`, `analytics_editor`, `auditor`) are GET-only\nacross the Campaign API.\n","parameters":[{"name":"ids","in":"query","required":false,"description":"Comma-separated segment ids; at most 100. Empty returns an empty map.","schema":{"type":"string"}},{"name":"X-Purpose","in":"header","required":false,"description":"Forwarded to the CDP for each count, so the numbers reflect what the caller may see.","schema":{"type":"string"}}],"responses":{"200":{"description":"Counts by segment id, plus any per-segment failures.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"counts":{"type":"object","additionalProperties":{"type":"integer","format":"int64"}},"errors":{"type":"object","description":"Present per segment whose count failed; absent keys succeeded.","additionalProperties":{"type":"string"}}}}}}]}}}},"400":{"description":"More than 100 ids."},"403":{"description":"The caller may not read profiles under the declared purpose."}}}},"/campaign/api/v1/segments/suggest":{"post":{"tags":["Segments"],"summary":"AI audience suggestion (draft only, never saved)","description":"Translates a natural-language audience description into a validated\nquerybuilder filter via the CDP's `POST /cdp/api/v1/segments/translate`,\nasks the Campaign LLM for a proposed name/description, and attaches a\nlive member-count preview. LLM metadata and the count preview are\nbest-effort: their failure degrades to response `warnings`, the filter\nis still returned.\n","parameters":[{"$ref":"#/components/parameters/PurposeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuggestSegmentRequest"}}}},"responses":{"200":{"description":"Draft segment.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SuggestSegmentResponse"}}}]}}}},"422":{"description":"The LLM could not produce a filter that passes validation."},"429":{"$ref":"#/components/responses/AIRateLimited"},"502":{"description":"A CDP request failed; the message is the fixed `CDP unavailable`."}}}},"/campaign/api/v1/segments/{id}":{"parameters":[{"$ref":"#/components/parameters/SegmentId"}],"get":{"tags":["Segments"],"summary":"Get a segment","responses":{"200":{"description":"Segment.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Segment"}}}]}}}},"404":{"description":"Segment not found."}}},"put":{"tags":["Segments"],"summary":"Update a segment","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SegmentRequest"}}}},"responses":{"200":{"description":"Segment updated. `data` also carries `approvals_cleared` (ApprovalsCleared).","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Segment"}}}]}}}},"400":{"description":"Invalid payload or filter."},"404":{"description":"Segment not found."},"409":{"description":"Name conflict."}}},"delete":{"tags":["Segments"],"summary":"Delete a segment","responses":{"200":{"description":"Segment deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"404":{"description":"Segment not found."},"409":{"description":"The segment is still referenced by a campaign, offer eligibility gate or audience sync. The message gives the counts (\"segment is in use: 2 campaign(s), 1 audience sync(s)\", zero parts omitted), or \"segment is still in use\" if counting failed."}}}},"/campaign/api/v1/segments/{id}/members":{"get":{"tags":["Segments"],"summary":"List segment members (live CDP proxy)","description":"Paged proxy of the CDP's `GET /cdp/api/v1/profiles?filter=`\nusing the segment's stored audience definition. Profile payloads are\nreturned verbatim from the CDP; the caller's `X-Purpose` header is\nforwarded so CDP privacy gates evaluate the true purpose.\n","parameters":[{"$ref":"#/components/parameters/SegmentId"},{"$ref":"#/components/parameters/PurposeHeader"},{"name":"page","in":"query","schema":{"type":"integer","minimum":0}},{"name":"size","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"include_attributes","in":"query","schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"CDP profile objects with CDP page metadata.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SegmentMember"}}}}]}}}},"404":{"description":"Segment not found (or the CDP rejected the stored filter)."},"502":{"description":"A CDP request failed; the message is the fixed `CDP unavailable`."}}}},"/campaign/api/v1/segments/{id}/count":{"get":{"tags":["Segments"],"summary":"Live member count","description":"Metadata-only probe of the CDP profiles API (`size=1`), returning `{\"count\": n}`.","parameters":[{"$ref":"#/components/parameters/SegmentId"},{"$ref":"#/components/parameters/PurposeHeader"}],"responses":{"200":{"description":"Member count.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"count":{"type":"integer","format":"int64"}}}}}]}}}},"404":{"description":"Segment not found."},"502":{"description":"A CDP request failed; the message is the fixed `CDP unavailable`."}}}},"/campaign/api/v1/campaigns":{"get":{"tags":["Campaigns"],"summary":"List campaigns","description":"Lists campaigns newest first, with page metadata carrying the\nuntruncated total. `folder` is **opt-in by key presence**: omitting it\nlists every folder, while `?folder=` (empty value) lists only\nroot-level (\"ungrouped\") campaigns. Tags AND together — a campaign must\ncarry all of them to match. The organisation grammar is identical to\n/segments, deliberately.\n","parameters":[{"name":"entity_type","in":"query","schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"string","enum":["draft","active","paused","archived","completed","stopped"]}},{"name":"include_archived","in":"query","required":false,"description":"Archived campaigns are excluded from an unfiltered listing (they are off the board). Set this to bring them back, or name `status=archived` to list only those — an explicit status is always honoured as written.\n","schema":{"type":"boolean","default":false}},{"name":"search","in":"query","required":false,"description":"Case-insensitive **substring** match on the campaign name; LIKE\nmetacharacters are escaped. Blank is no filter.\n","schema":{"type":"string"},"example":"summer"},{"name":"folder","in":"query","required":false,"description":"Materialized folder path, normalised server-side. Present-but-empty\nselects the root folder; absent applies no folder filter.\n","schema":{"type":"string"},"example":"Lifecycle/Winback"},{"name":"subtree","in":"query","required":false,"description":"With `folder`, also match every descendant folder.","schema":{"type":"boolean","default":false}},{"name":"tag","in":"query","required":false,"description":"Comma-separated tags; a campaign must carry ALL of them.","schema":{"type":"string"},"example":"vip,q3"},{"name":"page","in":"query","schema":{"type":"integer","minimum":0,"default":0}},{"name":"size","in":"query","description":"Omitted (or 0) means the platform default of 100; 100 is also the cap.","schema":{"type":"integer","minimum":1,"maximum":100,"default":100}}],"responses":{"200":{"description":"Campaigns, newest first, with page metadata.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Campaign"}}}}]}}}}}},"post":{"tags":["Campaigns"],"summary":"Create a campaign (status starts as draft)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignRequest"}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"400":{"description":"Validation failed (bad type, missing cron, unknown segment, entity-type mismatch, bad cap)."},"409":{"description":"A campaign with this name already exists for the entity type."},"422":{"description":"A stop condition is malformed; `data.issues: [{index, message}]` names the offending condition.\n"}}}},"/campaign/api/v1/campaigns/facets":{"get":{"tags":["Campaigns"],"summary":"Distinct campaign folders and tags","description":"The distinct folder paths and tags in use, for building the folder tree\nand the tag filter without paging through every campaign. The root\nfolder is not listed — clients offer it as a fixed \"ungrouped\" entry.\nRegistered before /campaigns/{id}, so \"facets\" is never read as an id.\n","parameters":[{"name":"entity_type","in":"query","required":false,"description":"Scope both lists to one entity type, so the tree has no branches that are empty under the current selection.","schema":{"type":"string"}}],"responses":{"200":{"description":"Folder paths and tags.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OrganizeFacets"}}}]}}}}}}},"/campaign/api/v1/campaigns/{id}":{"get":{"tags":["Campaigns"],"summary":"Get a campaign","parameters":[{"$ref":"#/components/parameters/CampaignId"}],"responses":{"200":{"description":"The campaign.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"allOf":[{"$ref":"#/components/schemas/Campaign"},{"type":"object","properties":{"delivery":{"$ref":"#/components/schemas/CampaignDelivery"}}}]}}}]}}}},"404":{"description":"Not found."}}},"put":{"tags":["Campaigns"],"summary":"Update a campaign (status unchanged)","parameters":[{"$ref":"#/components/parameters/CampaignId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignRequest"}}}},"responses":{"200":{"description":"Updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"400":{"description":"Validation failed."},"404":{"description":"Not found."},"409":{"description":"Duplicate name."}}},"delete":{"tags":["Campaigns"],"summary":"Delete a campaign (its offers cascade)","parameters":[{"$ref":"#/components/parameters/CampaignId"}],"responses":{"200":{"description":"Deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"404":{"description":"Not found."},"409":{"description":"Campaign is active (pause it first)."}}}},"/campaign/api/v1/campaigns/{id}/activate":{"post":{"tags":["Campaigns"],"summary":"Activate a campaign (from draft or paused)","parameters":[{"$ref":"#/components/parameters/CampaignId"}],"responses":{"200":{"description":"Now active.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"400":{"description":"The campaign is not complete enough to run. Batch campaigns need a segment, a channel and an existing active template carrying a variant for that channel, a consent purpose (or the \"none\" opt-out), a schedule_cron when recurring, an enabled provider when one is pinned, and — for a \"{channel}\" consent purpose — every expansion present in the CDP purpose catalogue. These are checked here rather than at save so a draft may be incomplete. Every campaign type: each active offer it can hand out (its own, its default catalogue's, and those of catalogues its journeys' decide nodes rank over) must carry a consent purpose present in the CDP catalogue; a \"{channel}\" family expands over the campaign's channel, the pinned provider's channel (batch \"auto\" with a pin), the channels auto can resolve to (unpinned batch \"auto\"), or the native plus declared channels (every other campaign) — the message names the offer.\n"},"403":{"description":"No standing approval on record. Activation requires an approver to have called `/approval/approve` first (message: `campaign requires approval before activation`). Callers who hold approval rights — plus root and application keys — skip the queue: their activation auto-records the standing approval under their own identity instead of failing.\n"},"404":{"description":"Not found."},"409":{"description":"Not activatable from the current status. A `completed` one-off (its single dispatch has run) and a `stopped` campaign cannot be activated directly. Also returned when the standing approval the activation relied on was cleared by a concurrent content edit (the campaign needs approval again), or with message `campaign changed concurrently` when a rival lifecycle write (stop, pause, archive) moved the status first. A one-off that already ran and a campaign stopped by a stop condition answer \"... reopen it to send again\" / \"... reopen it to run again\": use `POST /campaigns/{id}/reopen` first. When a stop condition is already met the body is `{status: \"error\", message: \"stop condition already met\", data: {issues: [{index, message}]}}` (`index` is the 0-based position of the met condition); change or remove the condition before activating.\n","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"error"},"message":{"type":"string"},"data":{"type":"object","properties":{"issues":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer","description":"0-based index into stop_conditions."},"message":{"type":"string"}}}}}}}}}}},"500":{"description":"The channel vocabulary, the channel providers or the campaign's offers could not be read to run the checks (never a silent pass).\n"}}}},"/campaign/api/v1/campaigns/{id}/reopen":{"post":{"tags":["Campaigns"],"summary":"Reopen a completed or stopped campaign as a draft","description":"Moves a `completed` or `stopped` campaign back to `draft` so it can be\nedited, re-approved and activated again. Stamps `reopened_at`, clears\n`stop_state`, and clears a standing approval (recorded as an\n`approval_reset` revision); the reopen itself is recorded as a `reopen`\nrevision. Callable by the same roles as `/activate`.\n","parameters":[{"$ref":"#/components/parameters/CampaignId"}],"responses":{"200":{"description":"Reopened; `data` is the Campaign (status `draft`).","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Campaign"}}}]}}}},"404":{"description":"Not found."},"409":{"description":"Not reopenable: message `cannot reopen a campaign in status \"X\"` (only completed and stopped qualify)."}}}},"/campaign/api/v1/campaigns/{id}/duplicate":{"post":{"tags":["Campaigns"],"summary":"Duplicate a campaign as a new draft","description":"Copies the campaign's settings, its own offers and its journeys into a\nNEW campaign — a new id, so its touches, stats, runs and lift start\nempty. The copy is named \"<name> (copy)\", or \"(copy 2)\", \"(copy 3)\"…\nwhen taken; it is a `draft` with no approval, no prediction, no stop\nstate and a fresh `control_seed`. Journeys are copied inactive at\nversion 1 with a fresh graph snapshot. One transaction: the copy is\nwhole or absent. Create revisions are recorded for the campaign, each\noffer and each journey. Callable by the campaign authoring roles.\n","parameters":[{"$ref":"#/components/parameters/CampaignId"}],"responses":{"201":{"description":"Duplicated; `data` is the new Campaign.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Campaign"}}}]}}}},"403":{"description":"`feature_not_licensed`: the campaign has journeys and the journeys feature is not licensed, or its channel or a journey send node is an onsite channel whose feature is not licensed. Nothing is copied."},"404":{"description":"Not found."},"409":{"description":"The chosen copy name was taken concurrently (try again)","or 100 copies already exist.":null}}}},"/campaign/api/v1/campaigns/{id}/request-approval":{"post":{"tags":["Approvals"],"summary":"Request activation approval for a campaign","description":"Opens (or refreshes) an approval request — a repeat call re-stamps the requester and timestamp, so an edited campaign re-enters the queue fresh. Any campaigner may call this. The standing approval, if any, stays in force until the request is decided by an approver via `/approval/approve` or `/approval/reject`.\n","parameters":[{"$ref":"#/components/parameters/CampaignId"}],"responses":{"200":{"description":"Approval requested. Returns the updated campaign.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"400":{"description":"The caller could not be attributed (no identifiable requester)."},"404":{"description":"Not found."},"409":{"description":"Archived campaigns cannot request approval."}}}},"/campaign/api/v1/campaigns/{id}/approval/approve":{"post":{"tags":["Approvals"],"summary":"Approve a campaign for activation (approval rights required)","description":"Records the standing approval under the caller's identity. Works with or without an open request — pre-approving is the same right as activating directly, which approvers already hold. Self-approval is deliberately legal (unlike content).\n","parameters":[{"$ref":"#/components/parameters/CampaignId"}],"responses":{"200":{"description":"Campaign approved. Returns the updated campaign.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"400":{"description":"The caller could not be attributed (no identifiable approver)."},"403":{"description":"Approval rights required."},"404":{"description":"Not found."},"409":{"description":"Archived campaigns cannot be approved."}}}},"/campaign/api/v1/campaigns/{id}/approval/reject":{"post":{"tags":["Approvals"],"summary":"Reject a campaign's approval request (approval rights required)","description":"Requires a JSON body `{\"reason\": \"...\"}` (non-empty after trimming, max 2000 characters). REVOKES any standing approval — rejection doubles as the approvers' kill switch — and if the campaign is currently active, pauses it.\n","parameters":[{"$ref":"#/components/parameters/CampaignId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["reason"],"properties":{"reason":{"type":"string","maxLength":2000,"description":"Why the request was rejected, shown to the requester."}}}}}},"responses":{"200":{"description":"Approval rejected (and the campaign paused, if it was active). Returns the updated campaign.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"400":{"description":"Missing/blank reason (after trimming), reason over 2000 characters, or the caller could not be attributed.\n"},"403":{"description":"Approval rights required."},"404":{"description":"Not found."},"409":{"description":"Archived campaigns cannot be rejected."}}}},"/campaign/api/v1/campaign-approvals":{"get":{"tags":["Approvals"],"summary":"List campaigns awaiting approval (approval rights required)","description":"The approvers' queue: campaigns with an open (undecided) approval request, newest first. Pagination and the response envelope mirror `GET /campaigns` exactly — same `page`/`size` parsing, same `PageMeta` envelope — so the console renders both lists with one component. Unlike `/campaigns`, this list takes no entity_type/ status/folder/tag/search filters; it is scoped to open requests only.\n","parameters":[{"name":"page","in":"query","schema":{"type":"integer","minimum":0,"default":0}},{"name":"size","in":"query","description":"Omitted (or 0) means the platform default of 100; 100 is also the cap.","schema":{"type":"integer","minimum":1,"maximum":100,"default":100}}],"responses":{"200":{"description":"Campaigns with an open approval request, with page metadata carrying the untruncated total.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Campaign"}}}}]}}}},"403":{"description":"Approval rights required."}}}},"/campaign/api/v1/campaigns/{id}/pause":{"post":{"tags":["Campaigns"],"summary":"Pause an active campaign","parameters":[{"$ref":"#/components/parameters/CampaignId"}],"responses":{"200":{"description":"Now paused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"404":{"description":"Not found."},"409":{"description":"Only active campaigns can pause","or the campaign changed concurrently (a rival lifecycle write won).":null}}}},"/campaign/api/v1/campaigns/{id}/archive":{"post":{"tags":["Campaigns"],"summary":"Archive a campaign (take it off the default listing)","description":"Shelves a draft, paused or completed campaign. An ACTIVE campaign is refused — pausing is what stops a live send, and archiving must never do it by side effect. The status it was archived from is recorded, so `/unarchive` restores exactly that.\n","parameters":[{"$ref":"#/components/parameters/CampaignId"}],"responses":{"200":{"description":"Now archived.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"404":{"description":"Not found."},"409":{"description":"Already archived, or active (pause it first)."}}}},"/campaign/api/v1/campaigns/{id}/unarchive":{"post":{"tags":["Campaigns"],"summary":"Restore an archived campaign","description":"Returns the campaign to the status it was archived from — never a guess. A completed one-off therefore comes back `completed` (and a stopped campaign `stopped`); reopen it (`POST /campaigns/{id}/reopen`) to edit and activate it again.\n","parameters":[{"$ref":"#/components/parameters/CampaignId"}],"responses":{"200":{"description":"Restored to its pre-archive status.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"404":{"description":"Not found."},"409":{"description":"The campaign is not archived."}}}},"/campaign/api/v1/campaigns/{id}/offers":{"get":{"tags":["Offers"],"summary":"List a campaign's offers (priority desc, then name)","parameters":[{"$ref":"#/components/parameters/CampaignId"},{"name":"active_only","in":"query","schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"Offers.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Offer"}}}}]}}}},"404":{"description":"Campaign not found."}}},"post":{"tags":["Offers"],"summary":"Create an offer","parameters":[{"$ref":"#/components/parameters/CampaignId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OfferRequest"}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"400":{"description":"Validation failed (broken expr, non-object payload, unknown segment, bad cap)."},"404":{"description":"Campaign not found."},"409":{"description":"An offer with this name already exists in the campaign."}}}},"/campaign/api/v1/campaigns/{id}/offers/{offerId}":{"get":{"tags":["Offers"],"summary":"Get an offer","parameters":[{"$ref":"#/components/parameters/CampaignId"},{"$ref":"#/components/parameters/OfferId"}],"responses":{"200":{"description":"The offer.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Offer"}}}]}}}},"404":{"description":"Campaign or offer not found."}}},"put":{"tags":["Offers"],"summary":"Update an offer","parameters":[{"$ref":"#/components/parameters/CampaignId"},{"$ref":"#/components/parameters/OfferId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OfferRequest"}}}},"responses":{"200":{"description":"Updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"400":{"description":"Validation failed."},"404":{"description":"Campaign or offer not found."},"409":{"description":"Duplicate name."}}},"delete":{"tags":["Offers"],"summary":"Delete an offer","parameters":[{"$ref":"#/components/parameters/CampaignId"},{"$ref":"#/components/parameters/OfferId"}],"responses":{"200":{"description":"Deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"404":{"description":"Campaign or offer not found."}}}},"/campaign/api/v1/campaigns/{id}/offers/{offerId}/send":{"post":{"tags":["Offers"],"summary":"Dispatch an already-decisioned offer (decide-to-send)","description":"Verifies a recent matching `decisioned` touch exists for this\ncampaign/offer/profile — via the campaign_touch ledger (valid 1 hour)\nor, for a decision made moments ago that the ledger does not show\nyet, the short-lived record of that decision — then queues the send for\ndelivery and logs a `queued`\ncampaign_touch (the frequency-cap ledger entry for the send; it carries\n`catalog_id` for a catalogue-owned offer, like every other touch of\none). Decide\nand act stay two separate, composable steps: `/decide` never sends.\n","parameters":[{"$ref":"#/components/parameters/CampaignId"},{"$ref":"#/components/parameters/OfferId"},{"$ref":"#/components/parameters/PurposeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendOfferRequest"}}}},"responses":{"202":{"description":"Send queued (asynchronous — delivery outcome arrives as sent/failed campaign_touch events). `warnings` reports a failed queued-touch write.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"400":{"description":"No resolvable template, or the template has no variant for the channel."},"404":{"description":"Campaign or offer not found."},"409":{"description":"Campaign not active, offer inactive, catalogue offer's entity type differs from the campaign's, or no recent `decisioned` touch for this profile (call /decide first). Catalogue-owned offers resolve here too; no extra decisioned touch is written — the mandatory prior /decide already wrote the touch the global cap counts.\n"},"503":{"description":"Send pipeline unavailable (send queue not connected), or the profile's person could not be resolved (\"person resolution unavailable\"). The decide's burst-dedup marker and the frequency cap are keyed on the PERSON, so a decision made for one member of a person is spendable by a send naming another; the published message and its queued touch carry the person key.\n"}}}},"/campaign/api/v1/offer-catalogs":{"get":{"tags":["Offer catalogs"],"summary":"List offer catalogues","parameters":[{"name":"entity_type","in":"query","schema":{"type":"string"}},{"name":"search","in":"query","schema":{"type":"string"},"description":"Case-insensitive substring match on the name."},{"name":"active","in":"query","schema":{"type":"boolean","default":false}},{"name":"page","in":"query","schema":{"type":"integer"}},{"name":"size","in":"query","description":"Omitted (or 0) means the platform default of 100; 100 is also the cap.","schema":{"type":"integer","minimum":1,"maximum":100,"default":100}}],"responses":{"200":{"description":"Catalogues (paged).","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/OfferCatalog"}}}}]}}}}}},"post":{"tags":["Offer catalogs"],"summary":"Create an offer catalogue","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OfferCatalogRequest"}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"400":{"description":"Missing name or entity_type."},"409":{"description":"A catalogue with this name already exists."}}}},"/campaign/api/v1/offer-catalogs/{id}":{"get":{"tags":["Offer catalogs"],"summary":"Get an offer catalogue","parameters":[{"$ref":"#/components/parameters/CatalogId"}],"responses":{"200":{"description":"The catalogue.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OfferCatalog"}}}]}}}},"404":{"description":"Not found."}}},"put":{"tags":["Offer catalogs"],"summary":"Update an offer catalogue (entity_type is immutable)","parameters":[{"$ref":"#/components/parameters/CatalogId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OfferCatalogRequest"}}}},"responses":{"200":{"description":"Updated. `data` also carries `approvals_cleared` (ApprovalsCleared).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"404":{"description":"Not found."},"409":{"description":"Duplicate name, or an attempt to change entity_type."}}},"delete":{"tags":["Offer catalogs"],"summary":"Delete an offer catalogue","description":"Refused (409) while any LIVE journey's decide node references the catalogue (the /usage answer — repoint those nodes first), while any campaign names it as its default offer source (clear it there first), or while the catalogue still owns offers (FK RESTRICT — delete them first). Pinned journey graph snapshots do NOT block deletion; runs pinned to old snapshots get empty decisions.\n","parameters":[{"$ref":"#/components/parameters/CatalogId"}],"responses":{"200":{"description":"Deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"404":{"description":"Not found."},"409":{"description":"Referenced by live journeys, or still contains offers."}}}},"/campaign/api/v1/offer-catalogs/{id}/usage":{"get":{"tags":["Offer catalogs"],"summary":"List what references this catalogue (live journeys + campaigns defaulting to it)","parameters":[{"$ref":"#/components/parameters/CatalogId"}],"responses":{"200":{"description":"Referencing journeys and campaigns.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CatalogUsageResponse"}}}]}}}},"404":{"description":"Not found."}}}},"/campaign/api/v1/offer-catalogs/{id}/offers":{"get":{"tags":["Offers"],"summary":"List a catalogue's offers (priority desc, then name)","parameters":[{"$ref":"#/components/parameters/CatalogId"},{"name":"active_only","in":"query","schema":{"type":"boolean","default":false}},{"name":"tag","in":"query","schema":{"type":"string"},"description":"Comma-separated; an offer must carry ALL of them."}],"responses":{"200":{"description":"Offers.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Offer"}}}}]}}}},"404":{"description":"Catalogue not found."}}},"post":{"tags":["Offers"],"summary":"Create a catalogue offer","description":"Same validation as campaign offers. The offer's entity type is ALWAYS the catalogue's (a per-offer override could smuggle a mismatched offer past the decide-time entity check).\n","parameters":[{"$ref":"#/components/parameters/CatalogId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OfferRequest"}}}},"responses":{"201":{"description":"Created. `data` also carries `approvals_cleared` (ApprovalsCleared).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"400":{"description":"Validation failed (broken expr, non-object payload, unknown segment, bad cap)."},"404":{"description":"Catalogue not found."},"409":{"description":"An offer with this name already exists in the catalogue."}}}},"/campaign/api/v1/offer-catalogs/{id}/offers/{offerId}":{"get":{"tags":["Offers"],"summary":"Get a catalogue offer","parameters":[{"$ref":"#/components/parameters/CatalogId"},{"$ref":"#/components/parameters/OfferId"}],"responses":{"200":{"description":"The offer.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Offer"}}}]}}}},"404":{"description":"Catalogue or offer not found."}}},"put":{"tags":["Offers"],"summary":"Update a catalogue offer","parameters":[{"$ref":"#/components/parameters/CatalogId"},{"$ref":"#/components/parameters/OfferId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OfferRequest"}}}},"responses":{"200":{"description":"Updated. `data` also carries `approvals_cleared` (ApprovalsCleared).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"400":{"description":"Validation failed."},"404":{"description":"Catalogue or offer not found."},"409":{"description":"Duplicate name."}}},"delete":{"tags":["Offers"],"summary":"Delete a catalogue offer","parameters":[{"$ref":"#/components/parameters/CatalogId"},{"$ref":"#/components/parameters/OfferId"}],"responses":{"200":{"description":"Deleted. `data` carries only `approvals_cleared` (ApprovalsCleared).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"404":{"description":"Catalogue or offer not found."}}}},"/campaign/api/v1/offer-catalogs/{id}/offers/{offerId}/stats":{"get":{"tags":["Reporting and responses"],"summary":"Cross-campaign performance of one catalogue offer","parameters":[{"$ref":"#/components/parameters/CatalogId"},{"$ref":"#/components/parameters/OfferId"},{"$ref":"#/components/parameters/PurposeHeader"},{"name":"days","in":"query","schema":{"type":"integer","minimum":1,"maximum":365,"default":30}}],"responses":{"200":{"description":"The offer's funnel across every deciding campaign.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CatalogOfferStatsResponse"}}}]}}}},"404":{"description":"Catalogue or offer not found."}}}},"/campaign/api/v1/campaigns/{id}/audience/count":{"get":{"tags":["Pre-flight checks"],"summary":"Live audience count","description":"How many profiles the campaign's audience currently resolves to — the saved segment's filter AND the campaign's own `audience_filter` — read from the CDP as a metadata-only probe (`size=1`). The caller's `X-Purpose` is forwarded, so the count is the one that caller is allowed to see.\n\n`segment_id` and `audience_filter` query overrides answer the same question for an audience that is still being edited (the console shows the reach of a change before it is saved). An override present but EMPTY clears that half of the audience. A campaign with neither half answers `{\"count\": 0, \"defined\": false}` rather than an error — an audience-less draft is legal.\n","parameters":[{"$ref":"#/components/parameters/CampaignId"},{"$ref":"#/components/parameters/PurposeHeader"},{"name":"segment_id","in":"query","schema":{"type":"string"},"description":"Preview override for the saved segment (\"\" = no segment)."},{"name":"audience_filter","in":"query","schema":{"type":"string"},"description":"Preview override for the saved conditions, as querybuilder JSON (\"\" = no conditions).\n"}],"responses":{"200":{"description":"Audience count.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"count":{"type":"integer","format":"int64"},"defined":{"type":"boolean","description":"False when the campaign has neither a segment nor conditions; count is then 0.\n"},"audience_cap":{"type":"integer","description":"The most profiles one batch run of this campaign may send; 0 = unlimited. Only for one_off_batch and recurring_batch campaigns with a defined audience; absent otherwise.\n"}}}}}]}}}},"400":{"description":"The audience_filter override is not a valid, non-empty filter."},"404":{"description":"Campaign or segment not found."},"502":{"description":"A CDP request failed; the message is the fixed `CDP unavailable`."}}}},"/campaign/api/v1/campaigns/{id}/preflight/reach":{"post":{"tags":["Pre-flight checks"],"summary":"Pre-flight reach funnel","description":"How many people will actually get this, and why not the rest. The audience count above is the top of a funnel with a dozen gates below it — consent, contact resolution, suppression, frequency cap, fatigue, control group, render, outbound mode — every one of which runs per profile inside delivery at send time. This endpoint reports the whole ladder before the campaign is activated.\n\nRead-only: no send is published, no `campaign_touch` is written and no profile is modified. The stages are produced by the SAME gate functions the live send path calls (`delivery.Evaluate` in dry-run mode), never by a second implementation of them.\n\n**Every stage carries `basis`, and it is load-bearing.** `exact` is a real count (one composed CDP query, or a configuration fact identical for every profile); `sampled` is extrapolated from the stride sample and carries `passing_low`/`passing_high`; `skipped` means the gate was NOT checked (it does not apply, or sampling was off) — which is a different claim from \"nobody was dropped\"; `unavailable` means the read behind the stage failed and the stages below carried on from the population above it. A UI must render sampled and assumed numbers visibly differently from counted ones.\n\n`sample_size: 0` runs only the stages that can be counted exactly (audience ∧ consent ∧ contact ∧ control rule, composed cumulatively) — cheap enough to re-run as a marketer types in an audience editor.\n\nFor `inbound_offer` campaigns — which have no audience and no dispatch — the response `shape` is `decision_distribution` instead: which offers win across a sample of profiles, why the others were excluded, and how often NOTHING was eligible. Journey campaigns are refused with 400; their reach is per send node and is a projection, not a count.\n\nAuthorization: `campaign_editor`, `campaign_admin`, `engineer`, `admin` and — by the explicit control-stream policy naming this path — `campaign_viewer` and `analytics_editor`.\n","parameters":[{"$ref":"#/components/parameters/CampaignId"},{"$ref":"#/components/parameters/PurposeHeader"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"sample_size":{"type":"integer","minimum":0,"description":"Profiles walked down the ladder. Omitted takes the `preflight_sample_default` instance setting (500); 0 runs only the exact stages; anything above `preflight_sample_max` is clamped, and `sample.requested` reports what was asked for while `sample.drawn` reports what was used.\n"},"segment_id":{"type":"string","description":"Preview override for the saved segment (\"\" = no segment)."},"audience_filter":{"description":"Preview override for the saved conditions (querybuilder JSON).","type":"object"},"channel":{"type":"string","description":"Overrides the campaign's channel. Required to get exact consent and contact stages out of a `channel: \"auto\"` campaign — otherwise each sampled profile resolves its own channel and no single predicate can be counted.\n"}}}}}},"responses":{"200":{"description":"The reach report.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PreflightReachReport"}}}]}}}},"400":{"description":"A journey campaign (use the journey endpoint), or an invalid audience_filter override.\n"},"404":{"description":"Campaign or segment not found."},"502":{"description":"A CDP request failed; the message is the fixed `CDP unavailable`."},"503":{"description":"Pre-flight is not configured in this process."}}}},"/campaign/api/v1/campaigns/{id}/preflight/render":{"post":{"tags":["Pre-flight checks"],"summary":"Pre-flight render proof","description":"What this campaign's message looks like for one real person, and what did not fill in.\n\nUnlike `/templates/{id}/render`, the caller names a PROFILE rather than a template: the campaign supplies the template, the channel, the offer and the provider, and every one of them is resolved by the code the send path uses. The response therefore carries the RESOLUTION TRACE alongside the copy — which channel was chosen and why, which variant carries it, which provider instance would accept it, which offer supplied the payload.\n\n`context_gaps` is the \"Hi ,\" detector: every template placeholder that resolved to nothing for this profile, with `missing` (the key is not on the profile at all) distinguished from `empty` (it is there and holds no value). Placeholders the author guarded with the `default` helper are deliberately excluded — they are already handled, and listing them trains the reader to ignore the list. With `sample_size` each gap also carries `rate`: the share of the audience with the same gap, which is the number that changes what the marketer writes.\n\nThe gates that are about whether to SEND rather than about what would be sent — cap, fatigue, control group, consent — are reported but not enforced, and the walk continues past a refusal. That is deliberate: the profiles a marketer most wants to look at are often the ones the campaign would not reach.\n\nRead-only: no send, no `campaign_touch`, no profile write. Onsite channels answer with the UN-rendered variant and the frozen `data`, because Optima Edge renders those at visit time in its own template language.\n\nAuthorization: `campaign_editor`, `campaign_admin`, `engineer`, `admin` and — by the explicit control-stream policy naming this path — `campaign_viewer` and `analytics_editor`.\n","parameters":[{"$ref":"#/components/parameters/CampaignId"},{"$ref":"#/components/parameters/PurposeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["profile_id"],"properties":{"profile_id":{"type":"string","description":"Whose data renders the message."},"channel":{"type":"string","description":"Overrides the campaign's channel — needed in practice for a `channel: \"auto\"` campaign, whose variant differs per profile.\n"},"offer_id":{"type":"string","description":"Render with one specific offer's payload."},"language":{"type":"string","description":"Overrides the ladder's language resolution like a campaign pin (\"show me the German version\"). Omitted = resolve as the live send would (the campaign's pin, else this profile's preferred-language attribute, else the default copy). The resolution's `language` reports which mutation actually rendered.\n"},"sample_size":{"type":"integer","minimum":0,"description":"Omitted means \"this profile only\". Above 0 adds the population companion (per-placeholder gap rates), clamped to `preflight_sample_max`.\n"}}}}}},"responses":{"200":{"description":"The render proof.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PreflightRenderReport"}}}]}}}},"400":{"description":"A journey campaign (use the node endpoint), a campaign with no message template, a missing profile_id, or a render/config failure — the last is answered as 400 rather than 500 because it is exactly what the caller opened the proof to find.\n"},"404":{"description":"Campaign not found."},"502":{"description":"A CDP request failed; the message is the fixed `CDP unavailable`."},"503":{"description":"Pre-flight is not configured in this process."}}}},"/campaign/api/v1/campaigns/{id}/preflight/trace":{"post":{"tags":["Pre-flight checks"],"summary":"Pre-flight per-profile dry run","description":"What would happen to this person. The delivery gate ladder run against one profile by the LIVE gate functions, writing nothing, returning every gate's verdict with the evidence behind it — which consent purpose and its lawful basis, which identifier keys were looked for, which fatigue policy and its window, which control bucket and the seed it came from.\n\nTerminates at the first failing gate by default; `continue_after_failure` evaluates the rest anyway, which is what a support engineer debugging a chain of problems wants. The VERDICT is unchanged either way — a completed walk cannot be mistaken for a send that would have gone out.\n\nSome failures are structural: a missing template, an erased profile, an unresolvable provider leave the gates below with nothing to judge, so the walk still stops and the response says where in `halted_at` / `halted_because`.\n\nThe provider's rate-limit slot is REPORTED, never consumed — a rehearsal must not make a real send wait for an allowance nothing used.\n\nAuthorization: `campaign_editor`, `campaign_admin`, `engineer`, `admin` and — by the explicit control-stream policy naming this path — `campaign_viewer` and `analytics_editor`.\n","parameters":[{"$ref":"#/components/parameters/CampaignId"},{"$ref":"#/components/parameters/PurposeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["profile_id"],"properties":{"profile_id":{"type":"string"},"channel":{"type":"string","description":"Overrides the campaign's channel."},"offer_id":{"type":"string"},"continue_after_failure":{"type":"boolean","default":false,"description":"Evaluate the rest of the ladder past a failed gate."}}}}}},"responses":{"200":{"description":"The dry run.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PreflightTraceReport"}}}]}}}},"400":{"description":"A journey campaign, a campaign with no template, or a missing profile_id."},"404":{"description":"Campaign not found."},"502":{"description":"A CDP request failed; the message is the fixed `CDP unavailable`."},"503":{"description":"Pre-flight is not configured in this process."}}}},"/campaign/api/v1/campaigns/{id}/preflight/test-send":{"post":{"tags":["Pre-flight checks"],"summary":"Pre-flight seed send","description":"Render the campaign's message against one profile and DELIVER IT to an address you name. This is the only pre-flight surface that leaves the building.\n\nThree rules make it safe, and each is deliberate:\n\n**It never writes a `campaign_touch`.** The touch ledger is the frequency-cap, fatigue and analytics source of truth; a proof sent to an internal address is not a customer touch, and recording one would spend a real profile's cap, move a real campaign's KPI and pollute a lift measurement. The send is recorded in `campaign_test_sends` instead — an operator audit trail, deliberately outside the ledger, readable at `GET .../preflight/test-sends` and swept after `preflight_test_send_retention_days` (default 180).\n\n**The destination is always an explicit override.** `to` is required. There is no mode that sends to the profile's own resolved contact — that is not a test, it is a campaign with an audience of one, and it is already expressible by activating one.\n\n**The gate ladder is reported, then selectively bypassed.** Cap, fatigue and control group are reported and skipped (properties of the customer's contact budget, which this send does not spend). Consent is reported and NOT enforced, with its real verdict on the response and a warning when it would have blocked. Suppression IS enforced, against the override destination: if a colleague unsubscribed their own address, a test must not be the thing that mails them anyway. In a sandbox (`outbound_mode=sink`) the message is rendered and recorded but not transmitted, and `outcome` is `suppressed`.\n\nRate-limited per caller. Onsite channels are refused: they have no destination, and their proof is the render endpoint.\n\nAuthorization: `campaign_editor`, `campaign_admin`, `engineer`, `admin`. **The read-only roles are excluded** — they are granted each read-only pre-flight endpoint by name, never `/preflight/*` as a whole, so this sending endpoint stays out of their reach.\n","parameters":[{"$ref":"#/components/parameters/CampaignId"},{"$ref":"#/components/parameters/PurposeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["profile_id","to"],"properties":{"profile_id":{"type":"string","description":"Whose data renders the message."},"to":{"type":"string","description":"Where it actually goes. REQUIRED, and never the profile's own contact.\n"},"channel":{"type":"string"},"offer_id":{"type":"string"},"language":{"type":"string","description":"Overrides the ladder's language resolution like a campaign pin (\"send me the German version\"). Omitted = resolve as the live send would.\n"}}}}}},"responses":{"200":{"description":"The seed send's result. A provider failure is reported here (with `outcome: failed`) rather than as an error status — the audit row was still written, and the caller needs both facts.\n","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PreflightTestSendResult"}}}]}}}},"400":{"description":"A journey campaign, a campaign with no template, a missing profile_id or `to`, or an onsite channel.\n"},"404":{"description":"Campaign not found."},"429":{"description":"Too many seed sends from this caller; see Retry-After."},"502":{"description":"A CDP request failed; the message is the fixed `CDP unavailable`."},"503":{"description":"Pre-flight or the seed-send audit trail is not configured in this process. A proof that left the building unrecorded is not a mode this design has.\n"}}}},"/campaign/api/v1/campaigns/{id}/preflight/test-sends":{"get":{"tags":["Pre-flight checks"],"summary":"Seed-send audit trail","description":"Who sent a proof of this campaign, to where, and what happened. The rendered body is NOT stored — only its sha256, because the audit question (\"was this the same message?\") is answered by the hash and storing personalized customer data to answer it would be the wrong trade.\n","parameters":[{"$ref":"#/components/parameters/CampaignId"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":500,"default":100}}],"responses":{"200":{"description":"The trail, newest first.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PreflightTestSend"}}}}]}}}},"404":{"description":"Not found, or the id in the path is not a uuid."},"503":{"description":"The seed-send audit trail is not configured in this process."}}}},"/campaign/api/v1/journeys/{id}/preflight/reach":{"post":{"tags":["Pre-flight checks"],"summary":"Journey pre-flight reach projection","description":"Who enters this journey, where they go, and how many actually receive each send node's message.\n\nA journey has no single audience and no single message, so the answer is PER SEND NODE and every number above the delivery gates is a PROJECTION. Three inputs produce it: the entry population (from the graph's entry trigger), a path projection that walks the pinned graph carrying a fraction, and the full delivery funnel run against each send node's projected sub-population.\n\n**Calibration is the honest part.** A journey that has never run reports every behavioural stage as `assumed` with the assumption stated; one with history reports them as `sampled` with the observed rate and its window. The two are never mixed silently, and `basis` is how a UI tells them apart.\n\nPer node type: a **split** multiplies by its arm weights (the ones an optimizing split's own history earned) and is `exact` IN EXPECTATION — the realized split varies, which the node's note says. A **condition** that is a pure profile predicate is bulk-counted exactly, composed with the entry audience; one that reads run state or a personalized filter cannot be, and is reported as an assumed even split. A **wait** passes the fraction through and adds to `arrives_after`, because a 30-day wait means the projection describes a population arriving over 30 days. A **goal** is unknowable ahead of time: the journey's own historical conversion at that node, else a declared assumption. A **parallel fan-out** carries the FULL fraction into every branch — dividing it would understate every branch.\n\nSend nodes the projection never reaches are reported in `unreachable`. That is a graph-level bug the DAG validator cannot see, because the SHAPE is fine and the DATA makes it unreachable.\n\nRead-only. The walk is always over the PINNED graph snapshot, never the draft: runs are pinned to the version they entered on.\n\nAuthorization: `campaign_editor`, `campaign_admin`, `engineer`, `admin` and — by the explicit control-stream policy naming this path — `campaign_viewer` and `analytics_editor`.\n","parameters":[{"$ref":"#/components/parameters/JourneyIdTop"},{"$ref":"#/components/parameters/PurposeHeader"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"version":{"type":"integer","description":"Graph version to project (default the journey's active version)."},"sample_size":{"type":"integer","minimum":0,"description":"Passed to each send node's delivery funnel."},"assume_entrants":{"type":"integer","format":"int64","description":"The entry population for an `api` trigger, which nothing can know. Without it that stage reports `unavailable` rather than a fabricated zero.\n"},"event_lookback_days":{"type":"integer","description":"Window an `event` trigger's population is counted over (default 30)."},"assume":{"type":"object","additionalProperties":{"type":"string"},"description":"Pin goal outcomes by node id: \"met\" or \"timeout\"."}}}}}},"responses":{"200":{"description":"The projection.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PreflightJourneyReachReport"}}}]}}}},"400":{"description":"The stored graph or entry trigger is invalid."},"404":{"description":"Journey, graph version, or the journey's campaign not found."},"502":{"description":"A CDP request failed; the message is the fixed `CDP unavailable`."},"503":{"description":"Pre-flight is not configured in this process."}}}},"/campaign/api/v1/journeys/{id}/preflight/simulate":{"post":{"tags":["Pre-flight checks"],"summary":"Journey simulation for one profile","description":"Walk the pinned graph snapshot in memory for one profile, on a fast-forwarded clock.\n\n**No `journey_runs` row is created, no send is published, no touch is written, no profile attribute is modified.** Per node type: a **condition** is evaluated for real against the live profile (the caller's `X-Purpose` is forwarded, so a simulation can never surface data the caller may not read). A **split** is DETERMINISTIC — the arm pinned by `assume`, else the highest-weight one marked `assumed`; simulating a coin flip and reporting the result as fact is worse than useless. A **wait** is fast-forwarded, including `until_best_send_time` resolved against the profile's own signal and `duration_from` rendered per profile, and every later step carries its projected timestamp. A **send** is the full gate ladder plus the render, inert — a journey simulation is a walk whose send nodes are traces. A **decide** runs the real pipeline in test mode and its winner lands in the simulated state, so a downstream `offer_from` renders with it. A **goal** cannot be simulated: `assume` it, or it takes the timeout branch marked `assumed`. A **webhook** is rendered rather than fired, with credential-bearing headers redacted. A **profile** node's writes are returned as a DIFF and folded into the simulation's own profile so later templates render with them — but a condition the CDP evaluates cannot see them, and such a condition is flagged `stale_profile` rather than silently answering about stored data.\n\nA **parallel fan-out** returns a TREE (`branches`), not a flattened list.\n\n`execute_webhooks: true` fires action nodes for real, subject to the outbound gate and the existing SSRF guard. It is opt-in because the endpoint on the other side cannot tell a rehearsal from a real action, and requires journey write access: the caller must be allowed `PUT /campaign/api/v1/campaigns/{campaign_id}/journeys/{journey_id}` for this journey (campaign_viewer and analytics_editor may simulate, but not with execute_webhooks).\n\nAuthorization: `campaign_editor`, `campaign_admin`, `engineer`, `admin` and — by the explicit control-stream policy naming this path — `campaign_viewer` and `analytics_editor`.\n","parameters":[{"$ref":"#/components/parameters/JourneyIdTop"},{"$ref":"#/components/parameters/PurposeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["profile_id"],"properties":{"profile_id":{"type":"string"},"version":{"type":"integer","description":"Graph version (default the journey's active version)."},"trigger_event":{"type":"object","additionalProperties":true,"description":"Seeds Run.State for an event-triggered journey."},"assume":{"type":"object","additionalProperties":{"type":"string"},"description":"Pin goal outcomes (\"met\"/\"timeout\") and split arms (an arm label) by node id.\n"},"execute_webhooks":{"type":"boolean","default":false},"max_steps":{"type":"integer","default":200}}}}}},"responses":{"200":{"description":"The simulated walk.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/JourneySimulation"}}}]}}}},"400":{"description":"A missing profile_id, or a stored graph that is invalid."},"403":{"description":"execute_webhooks was requested by a caller without journey write access."},"404":{"description":"Journey, graph version, or campaign not found."},"409":{"description":"execute_webhooks was requested and the tenant's outbound mode forbids it.\n"},"503":{"description":"Pre-flight or the journey engine is not configured in this process."}}}},"/campaign/api/v1/journeys/{id}/nodes/{nodeId}/preflight/render":{"post":{"tags":["Pre-flight checks"],"summary":"Journey send node render proof","description":"What one send node's message looks like for one person — the journey counterpart of the campaign render proof, with the one input the campaign form does not have: RUN STATE.\n\nA node's copy may read `{{.Run.State.x}}` set by an earlier node, and its `offer_from` may point at a decide node's winner. There are therefore three ways to supply the state, in increasing fidelity and cost: nothing (which is what a FRESH ENTRANT sees, and a real check), an explicit `state` map, or `simulate_from_entry`, which runs the simulation first and renders with the state it produced. The response reports which was used in `state_source`.\n\n`context_gaps` works exactly as on the campaign proof: every placeholder that resolved to nothing, `missing` distinguished from `empty`, and `default`-guarded paths excluded.\n\nRead-only.\n\nAuthorization: `campaign_editor`, `campaign_admin`, `engineer`, `admin` and — by the explicit control-stream policy naming this path — `campaign_viewer` and `analytics_editor`.\n","parameters":[{"$ref":"#/components/parameters/JourneyIdTop"},{"$ref":"#/components/parameters/NodeId"},{"$ref":"#/components/parameters/PurposeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["profile_id"],"properties":{"profile_id":{"type":"string"},"version":{"type":"integer"},"state":{"type":"object","additionalProperties":true,"description":"Seeds Run.State directly."},"offer_id":{"type":"string","description":"Supplies the offer an `offer_from` node would inherit from a decide node's winner.\n"},"simulate_from_entry":{"type":"boolean","default":false},"trigger_event":{"type":"object","additionalProperties":true},"assume":{"type":"object","additionalProperties":{"type":"string"}}}}}}},"responses":{"200":{"description":"The render proof.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/JourneyNodeRenderReport"}}}]}}}},"400":{"description":"A missing profile_id, an unknown node, a node that is not a send node, or a render/config failure — the last is a 400 because it is what the caller opened the proof to find.\n"},"404":{"description":"Journey, graph version, or campaign not found."},"503":{"description":"Pre-flight is not configured in this process."}}}},"/campaign/api/v1/journeys/{id}/nodes/{nodeId}/preflight/entitle":{"post":{"tags":["Pre-flight checks"],"summary":"Onsite pre-flight entitlement","description":"The onsite channels' counterpart of the seed send. `web_banner`/`web_personalization`/`mobile_inapp` have no provider and no destination — Optima Edge serves them from an entitlement when the profile's device next shows up — so a \"test send\" for them is the render proof plus, optionally, a real single-profile entitlement pinned to the TESTER's own profile, so they can load the site and see it in place.\n\nThis is **the only pre-flight surface that writes to a live serving table**, and three things make that acceptable: it is opt-in rather than a side effect of a read-only surface; the row is marked `origin: \"preflight\"`, which is what keeps its impressions, clicks and dismissals OUT of the `campaign_touch` ledger (the onsite feedback consumer and the daily pruner both key off it, so a marketer previewing their own banner cannot move the campaign's numbers); and the TTL is short and clamped (default 2h, max 24h), swept by the existing onsite pruner.\n\n`profile_id` is the tester's own profile — the one their browser or app is tracked as. Without a tracked device the ladder's device gate refuses, and the response says so.\n\n**Ownership and consent.** Unlike the seed send's arbitrary `to` address, this writes against a REAL profile — so it enforces that profile's REAL consent state (a withheld purpose reports `written: false`, not a bypass) and may only ever target the SIGNED-IN CALLER'S OWN profile: `profile_id` must carry an email-typed identifier (the keys the email channel and any email-kind custom channel address, `email` by default) equal (case-insensitively) to the caller's own email. An API-key/service caller has no email identity to prove that with and is refused outright.\n\nRate-limited per caller, with the same per-user budget as the seed send (test sends and onsite proofs share it); the limit is checked before the profile lookup. Recorded in the seed-send audit trail with outcome `entitled`.\n\nAuthorization: `campaign_editor`/`campaign_approver`/`campaign_admin` and the account/instance admins. **`campaign_viewer` is excluded** — it writes.\n","parameters":[{"$ref":"#/components/parameters/JourneyIdTop"},{"$ref":"#/components/parameters/NodeId"},{"$ref":"#/components/parameters/PurposeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["profile_id"],"properties":{"profile_id":{"type":"string","description":"The tester's OWN profile, as their device is tracked."},"version":{"type":"integer"},"ttl_hours":{"type":"integer","minimum":1,"maximum":24,"default":2},"state":{"type":"object","additionalProperties":true,"description":"Seeds Run.State so the frozen {{.Data.*}} match the real node."},"offer_id":{"type":"string"}}}}}},"responses":{"200":{"description":"The proof. A refused ladder (no tracked device, no Edge configuration) is reported here with `written: false` and the gate that refused, not as an error status.\n","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OnsitePreflightEntitlement"}}}]}}}},"400":{"description":"A missing profile_id, an unknown node, or a non-onsite channel."},"403":{"description":"The caller has no signed-in identity (an API-key/service caller), or `profile_id` is unknown or does not carry an email-typed identifier equal to the caller's own email — one answer for both, so the endpoint is no existence oracle.\n"},"404":{"description":"Journey, graph version, or campaign not found."},"429":{"description":"Too many proofs from this caller; see Retry-After."},"503":{"description":"Pre-flight, the entitlement store or the seed-send audit trail is not configured in this process.\n"}}}},"/campaign/api/v1/journeys/{id}/nodes/{nodeId}/preflight/test-send":{"post":{"tags":["Pre-flight checks"],"summary":"Journey send-node seed send","description":"The seed send for one journey send node: the node's template, channel, provider, parameters, channel-signal prefix, contact attribute and data (from the pinned graph version) rendered against one profile and DELIVERED to the address you name. The node's routing replaces the campaign's wholesale, as in a live run: a field the node leaves empty is empty, never the campaign's. The same rules as `POST /campaigns/{id}/preflight/test-send`: no `campaign_touch`, an explicit destination, the audit row in `campaign_test_sends`, the per-caller throttle, and the same roles (authoring only, never the read-only pre-flight grants). An `offer_from` node needs `offer_id` to carry its offer. A message that reads run state (`{{.Run.State.*}}`) cannot be proved faithfully, since a seed send has no run: the response carries a warning, and those values render empty. The audit row records the node id.\n","parameters":[{"$ref":"#/components/parameters/JourneyIdTop"},{"$ref":"#/components/parameters/NodeId"},{"$ref":"#/components/parameters/PurposeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["profile_id","to"],"properties":{"profile_id":{"type":"string"},"to":{"type":"string","description":"Where it actually goes. Never the profile's own contact."},"version":{"type":"integer","description":"Graph version; omitted = the journey's current one."},"offer_id":{"type":"string","description":"The offer the message carries (an `offer_from` node takes it from a decide node at run time)."},"language":{"type":"string","description":"Language override (\"send me the German version\"); omitted = resolved as the live send would."}}}}}},"responses":{"200":{"description":"The seed send's result (a provider failure is reported as outcome failed, not as an error status).","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PreflightTestSendResult"}}}]}}}},"400":{"description":"Missing profile_id or `to`."},"404":{"description":"Journey, graph version or node not found."},"422":{"description":"Not a send node, an invalid send config, or an onsite channel."},"429":{"description":"Too many seed sends from this caller; see Retry-After."},"503":{"description":"Pre-flight or the seed-send audit trail is not configured in this process."}}}},"/campaign/api/v1/campaigns/{id}/stats":{"get":{"tags":["Reporting and responses"],"summary":"Campaign funnel stats","description":"Aggregates the campaign's campaign_touch events into the decisioned→queued→sent→delivered/failed→opened/clicked funnel via one CDP analytics query. The caller's X-Purpose is forwarded.\n","parameters":[{"$ref":"#/components/parameters/CampaignId"},{"$ref":"#/components/parameters/PurposeHeader"},{"name":"days","in":"query","schema":{"type":"integer","minimum":1,"maximum":365,"default":30},"description":"Window size, counting back from now."},{"name":"interval","in":"query","schema":{"type":"string","enum":["day","week","month"]},"description":"When set, the response additionally carries `timeline`: the funnel bucketed over time (one extra CDP aggregate).\n"}],"responses":{"200":{"description":"The funnel.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CampaignStats"}}}]}}}},"404":{"description":"Campaign not found."}}}},"/campaign/api/v1/campaigns/{id}/batch-runs":{"get":{"tags":["Reporting and responses"],"summary":"Batch campaign run history","description":"A batch campaign's runs, newest first (scheduled_for, then started_at). Empty list for a campaign that has not run. 404 for an unknown campaign.\n","parameters":[{"$ref":"#/components/parameters/CampaignId"},{"name":"limit","in":"query","schema":{"type":"integer","maximum":100,"default":20},"description":"Most runs to return. Values above 100 are clamped; 0 or less means the default."}],"responses":{"200":{"description":"The runs.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"runs":{"type":"array","items":{"$ref":"#/components/schemas/BatchRun"}}},"required":["runs"]}}}]}}}},"400":{"description":"limit is not a number."},"404":{"description":"Campaign not found."},"500":{"description":"The campaign or its runs could not be read."},"503":{"description":"Batch runs are not configured in this process."}}}},"/campaign/api/v1/campaigns/{id}/responses":{"get":{"tags":["Reporting and responses"],"summary":"Per-offer response matrix for one campaign","description":"What customers ANSWERED, per offer: one row per offer, the five response actions as columns, and the offer's `decisioned` count as the response-rate denominator.\n\nOne CDP analytics aggregate dimensioned `offer_id x action x response_source`, with `campaign_id` pinned server-side. The caller's X-Purpose is forwarded; a user session also forwards X-On-Behalf-Of, so the CDP evaluates purpose authorization against the acting user.\n\nOffer names resolve at read time from the campaign's own offers UNIONED with its default catalogue's — a campaign decide over a catalogue offer stamps `campaign_id`, so resolving only the campaign's own offers would report every borrowed offer as deleted. An `offer_id` present in the ledger but no longer in the store is still reported, with its raw id and `deleted: true`: those responses happened and still count toward a response rule.\n\nNo `action` parameter. Narrowing the matrix to one column would show zeros where the other four used to be, which reads as \"no responses\" rather than \"not asked about\"; a request carrying one is rejected with a 400 naming `…/responses/events`, where the filter lives.\n","parameters":[{"$ref":"#/components/parameters/CampaignId"},{"$ref":"#/components/parameters/PurposeHeader"},{"name":"days","in":"query","schema":{"type":"integer","minimum":1,"maximum":365,"default":30},"description":"Window size, counting back from now. Above 365 is REJECTED, not clamped: a caller asking for two years and silently getting one would report the answer as two years' worth.\n"},{"name":"offer_id","in":"query","schema":{"type":"string"},"description":"Narrows the matrix to one offer's row."}],"responses":{"200":{"description":"The matrix.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OfferResponses"}}}]}}}},"400":{"description":"days out of range, or action passed (it belongs on …/responses/events)."},"404":{"description":"Campaign not found."},"502":{"description":"The CDP analytics query failed."}}}},"/campaign/api/v1/campaigns/{id}/responses/events":{"get":{"tags":["Reporting and responses"],"summary":"The individual answers behind one response count","description":"The paginated `campaign_touch` rows behind a matrix cell, newest first, with attributes.\n\nWith no `action` the five response actions are listed — the message axis (queued/sent/opened/…) shares this ledger and is filtered out SERVER-side, so `total` stays true and pages stay whole. `action` also accepts `decisioned`, because a decision is the row a response is reported against: the console's report dialog reads its candidate list from this route.\n\n`profile_id` is customer data and reaches the caller through the ordinary privacy stack (X-Purpose, and X-On-Behalf-Of for a user session). Not an indexed lookup — the read is bounded by the window and the page, but it scans, and should not be polled.\n","parameters":[{"$ref":"#/components/parameters/CampaignId"},{"$ref":"#/components/parameters/PurposeHeader"},{"$ref":"#/components/parameters/ResponseWindowDays"},{"$ref":"#/components/parameters/ResponseOfferId"},{"$ref":"#/components/parameters/ResponseAction"},{"$ref":"#/components/parameters/ResponseSource"},{"$ref":"#/components/parameters/ResponsePage"},{"$ref":"#/components/parameters/ResponseSize"}],"responses":{"200":{"description":"One page of answers.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OfferResponseEvents"}}}]}}}},"400":{"description":"Unknown action, or days out of range."},"404":{"description":"Campaign not found."},"502":{"description":"The CDP read failed."}}}},"/campaign/api/v1/offer-catalogs/{id}/responses":{"get":{"tags":["Reporting and responses"],"summary":"Per-offer response matrix for one offer catalogue","description":"The campaign matrix, pool-wide. Identical shape and semantics to `/campaigns/{id}/responses`, pinned on `catalog_id` instead.\n\n`catalog_id` is stamped off the OFFER, not the flow, so this spans catalogue-only decides AND every campaign that decided an offer out of the pool. That is the question a shared catalogue asks; restricting it to catalogue-only decides would make a heavily-used pool look empty.\n\nThere is deliberately no `campaign_id` filter — for one campaign's use of the pool, ask that campaign's own route.\n","parameters":[{"$ref":"#/components/parameters/CatalogId"},{"$ref":"#/components/parameters/PurposeHeader"},{"$ref":"#/components/parameters/ResponseWindowDays"},{"$ref":"#/components/parameters/ResponseOfferId"}],"responses":{"200":{"description":"The matrix.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OfferResponses"}}}]}}}},"400":{"description":"days out of range, or action passed (it belongs on …/responses/events)."},"403":{"description":"Offer catalogues are not licensed for this account."},"404":{"description":"Offer catalogue not found."},"502":{"description":"The CDP analytics query failed."}}}},"/campaign/api/v1/offer-catalogs/{id}/responses/events":{"get":{"tags":["Reporting and responses"],"summary":"The individual answers behind one pool-wide response count","description":"`/campaigns/{id}/responses/events`, pinned on `catalog_id`. Same filters, paging, row shape and privacy forwarding.\n","parameters":[{"$ref":"#/components/parameters/CatalogId"},{"$ref":"#/components/parameters/PurposeHeader"},{"$ref":"#/components/parameters/ResponseWindowDays"},{"$ref":"#/components/parameters/ResponseOfferId"},{"$ref":"#/components/parameters/ResponseAction"},{"$ref":"#/components/parameters/ResponseSource"},{"$ref":"#/components/parameters/ResponsePage"},{"$ref":"#/components/parameters/ResponseSize"}],"responses":{"200":{"description":"One page of answers.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OfferResponseEvents"}}}]}}}},"400":{"description":"Unknown action, or days out of range."},"403":{"description":"Offer catalogues are not licensed for this account."},"404":{"description":"Offer catalogue not found."},"502":{"description":"The CDP read failed."}}}},"/campaign/api/v1/campaigns/{id}/lift":{"get":{"tags":["Reporting and responses"],"summary":"Campaign incremental lift (control-group report)","description":"The goal-centric counterpart of /stats: what the campaign actually CAUSED, measured against its control group.\n\nDeliberately separate from the engagement funnel. That one answers \"did the messaging work mechanically\" (delivery, opens, clicks — all treatment-only, because a control group receives nothing); this one answers \"did the campaign cause anything\". Merging them is how the first quietly gets read as the second.\n\nEach arm is measured with one CDP funnel query anchoring the goal event to that profile's OWN touch within `window_days`, so the counts are exact at any cohort size. The control arm is built from `control_group` touches of the campaign's measured-against reason; the treated arm from `sent` touches (not `queued` — a queued-but-failed send reached nobody and belongs in neither arm).\n\n`status` is `ok`, `not_enough_data` (either arm below 100 profiles), `goal_not_configured` (cohort sizes only — collecting holdouts is still correct) or `no_control_group`. Never an error.\n","parameters":[{"$ref":"#/components/parameters/CampaignId"},{"$ref":"#/components/parameters/PurposeHeader"},{"name":"days","in":"query","schema":{"type":"integer","minimum":1,"default":90},"description":"How far back touches are counted. Wider than the stats default: a cohort needs time to clear the 100-profile floor.\n"}],"responses":{"200":{"description":"The lift report.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/LiftResult"}}}]}}}},"404":{"description":"Campaign not found."}}}},"/campaign/api/v1/attribution":{"get":{"tags":["Reporting and responses"],"summary":"Multi-touch attribution report","description":"Which touches get credit for a conversion, under one or more rule-based models (`first_touch`, `last_touch`, `linear`, `position_based`, `time_decay`) computed side by side from one ordered touch list per profile. Deliberately top-level and cross-campaign — campaign_id/journey_id/channel below are optional scope pins, not required identifiers.\n\nThe unit of credit is a DELIVERED touch, never a decision: `sent`/`delivered`/`opened`/`clicked` are creditable, `decisioned`/`queued`/`control_group` never are — which of the creditable actions count is `credit_actions`, `clicked`-and-stronger by default. Conversions whose profile has no creditable touch in the lookback window land in `unattributed`, never hidden.\n\nBeside lift, never instead of it — the response always carries a standing note saying so. Cached for a short TTL (the fetch is many analytics round trips); the cache key is built from every parameter's EFFECTIVE (post-default) value, so two spellings of the same question (one naming `days=30` explicitly, the other omitting it) share one entry. `refresh=true` bypasses the cached read but still refreshes the cache.\n","parameters":[{"$ref":"#/components/parameters/PurposeHeader"},{"name":"conversion_event","in":"query","required":true,"schema":{"type":"string"},"description":"The event type that counts as a conversion. Must not be `campaign_touch` — a touch is not a conversion.\n"},{"name":"value_attr","in":"query","schema":{"type":"string"},"description":"Optional numeric event attribute summed as `total_value`/per-cell `value`."},{"name":"filter","in":"query","schema":{"type":"string"},"description":"Optional JSON row-native filter object (the conversion event's own attribute keys), narrowing which events of that type count. Passed through to the CDP verbatim.\n"},{"name":"days","in":"query","schema":{"type":"integer","minimum":1,"maximum":365,"default":30},"description":"The conversion period — clamped to 1..365."},{"name":"lookback_days","in":"query","schema":{"type":"integer","minimum":1,"maximum":365,"default":30},"description":"How far before a conversion a touch may still be credited — clamped to 1..365."},{"name":"models","in":"query","schema":{"type":"string","default":"first_touch,last_touch,linear,position_based,time_decay"},"description":"Comma-separated model names. Every element must be one of `first_touch`, `last_touch`, `linear`, `position_based`, `time_decay`; default is all five, in that order. Row sort uses the FIRST named model, so reordering this changes which model's ranking the table shows.\n"},{"name":"credit_actions","in":"query","schema":{"type":"string","default":"clicked"},"description":"Comma-separated touch actions eligible for credit. Allow-list: `sent`, `delivered`, `opened`, `clicked` — anything else (in particular `decisioned`, `queued`, `control_group`) is rejected with 400, which is what keeps them out of the credit pool by construction.\n"},{"name":"position_weights","in":"query","schema":{"type":"string","default":"40,20,40"},"description":"`first,middle,last` percentages for `position_based`, three non-negative numbers summing to 100 (±0.01). The middle share splits evenly across all middle touches.\n"},{"name":"half_life_days","in":"query","schema":{"type":"number","format":"double","default":7},"description":"Half-life for `time_decay`, in days. Must be > 0."},{"name":"campaign_id","in":"query","schema":{"type":"string","format":"uuid"},"description":"Optional scope pin. 404 when the campaign does not exist."},{"name":"journey_id","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"channel","in":"query","schema":{"type":"string"}},{"name":"refresh","in":"query","schema":{"type":"boolean","default":false},"description":"true bypasses the cached read (a fresh answer is still cached for the next caller)."}],"responses":{"200":{"description":"The attribution matrix.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AttributionResult"}}}]}}}},"400":{"description":"Missing/invalid conversion_event, an unknown model or credit_action, or position_weights/half_life_days out of range."},"404":{"description":"campaign_id names no campaign."},"502":{"description":"The CDP read failed."}}}},"/campaign/api/v1/control-groups":{"get":{"tags":["Contact policies"],"summary":"List every entity type's global control group","responses":{"200":{"description":"`data` is a list of ControlGroupSettings.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ControlGroupSettings"}}}}]}}}},"503":{"description":"Control groups are not configured on this deployment."}}}},"/campaign/api/v1/control-groups/{entity_type}":{"get":{"tags":["Contact policies"],"summary":"Get one entity type's global control group","description":"An entity type nobody has configured answers a zero-valued `off` record rather than 404 — \"no holdout\" is a real, meaningful state.\n","parameters":[{"$ref":"#/components/parameters/ControlEntityType"}],"responses":{"200":{"description":"`data` is a ControlGroupSettings.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ControlGroupSettings"}}}]}}}},"503":{"description":"Control groups are not configured on this deployment."}}},"put":{"tags":["Contact policies"],"summary":"Set one entity type's global control group","description":"The global control group binds EVERY campaign for this entity type except those with `control_exempt` — a holdout individual campaigns could opt out of by accident is not global, and the total-marketing-impact number it exists to produce would be silently wrong.\n\n`mode: rule` needs a `filter` (the same querybuilder grammar the profiles page uses; TRUE ⇒ in control). `mode: auto` needs a `percent`. Whichever field the mode does not use is cleared, so the console never shows a stale holdout size.\n\nThe seed is preserved across ordinary edits: a change of `percent` is MONOTONE (raising a holdout keeps everyone already in it and adds more), so live experiments survive it. `rotate_seed: true` re-draws membership from scratch and invalidates every prior lift number for this entity type.\n\nThe body is validated first. The entity type must then exist in the CDP entity catalogue, except when the request turns an existing holdout off (`mode: off`), so a holdout whose entity type was removed from the CDP can still be switched off.\n","parameters":[{"$ref":"#/components/parameters/ControlEntityType"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ControlGroupSettingsRequest"}}}},"responses":{"200":{"description":"`data` is the stored ControlGroupSettings.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ControlGroupSettings"}}}]}}}},"400":{"description":"Malformed body or invalid mode/filter/percent combination, or the entity type is not in the CDP entity catalogue (not checked when turning an existing holdout off)."},"503":{"description":"Control groups are not configured on this deployment, or the CDP entity catalogue could not be read (try again)."}}}},"/campaign/api/v1/control-groups/{entity_type}/preview":{"post":{"tags":["Contact policies"],"summary":"Estimate a proposed global control group's size","description":"How many profiles a holdout would withhold, before saving it. Exact for `rule` mode (a CDP count over the filter); for `auto` mode it is the expectation over a uniform assignment — `exact: false` says so.\n","parameters":[{"$ref":"#/components/parameters/ControlEntityType"},{"$ref":"#/components/parameters/PurposeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ControlGroupSettingsRequest"}}}},"responses":{"200":{"description":"`data` is {entity_type, mode, total_profiles, held_out, targetable, exact}.\n","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ControlGroupPreview"}}}]}}}},"400":{"description":"The proposed configuration is incomplete."}}}},"/campaign/api/v1/campaigns/{id}/onsite-deliveries":{"get":{"tags":["Reporting and responses"],"summary":"List onsite content entitlements (monitor)","description":"Pages the campaign's onsite pull-channel entitlements (web_banner, web_personalization, mobile_inapp — rows written at send time and served by Optima Edge). Read-only debugging view: state, impression counts and expiry answer \"why didn't my banner show\". State changes happen only through the delivery pipeline and the onsite event consumer.\n","parameters":[{"$ref":"#/components/parameters/CampaignId"},{"name":"state","in":"query","schema":{"type":"string","enum":["active","delivered","clicked","dismissed","expired"]},"description":"Filter to one entitlement state."},{"name":"page","in":"query","schema":{"type":"integer","minimum":0}},{"name":"size","in":"query","description":"Omitted (or 0) means the platform default of 100; 100 is also the cap.","schema":{"type":"integer","minimum":0,"maximum":100,"default":100}}],"responses":{"200":{"description":"The entitlement page (data) with paging meta.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/OnsiteDelivery"}}}}]}}}},"404":{"description":"Campaign not found."}}}},"/campaign/api/v1/campaigns/{id}/predict":{"post":{"tags":["Reporting and responses"],"summary":"Predict campaign performance (AI, advisory)","description":"Assembles an evidence bundle (comparable campaigns' funnels over 90 days, target segment size, an engagement-signal sample — degraded pieces are noted, not fatal), asks the LLM for predicted open/click/conversion ranges with rationale + confidence, stores the result on the campaign and returns `{prediction, evidence}`. Advisory only — activation never reads it.\n","parameters":[{"$ref":"#/components/parameters/CampaignId"},{"$ref":"#/components/parameters/PurposeHeader"}],"responses":{"200":{"description":"`data` is {prediction: Prediction, evidence: object}.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PredictionResponse"}}}]}}}},"404":{"description":"Campaign not found."},"429":{"$ref":"#/components/responses/AIRateLimited"},"502":{"description":"The LLM call failed or returned unusable output."}}}},"/campaign/api/v1/campaigns/{id}/insights":{"post":{"tags":["Reporting and responses"],"summary":"Analyze campaign performance (AI, advisory)","description":"One-button performance analysis of a running or completed campaign. Assembles an evidence bundle (the stats funnel + breakdowns, the lift report quoted verbatim, the stored prediction, up to 8 same-type/channel comparable campaigns — degraded pieces are noted, not fatal), asks the LLM for a structured verdict + four markdown sections (vs_industry, vs_your_campaigns, why, suggestions; industry figures are the model's approximate general knowledge, explicitly hedged), stores the result in the campaign's insight history and returns `{insight, evidence, id}`. Advisory only.\n","parameters":[{"$ref":"#/components/parameters/CampaignId"},{"$ref":"#/components/parameters/PurposeHeader"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"days":{"type":"integer","minimum":1,"maximum":365,"default":90,"description":"Stats window for the evidence bundle."}}}}}},"responses":{"200":{"description":"`data` is {insight: object, evidence: object, id: string} — `insight` is the freshly generated analysis (verdict, summary, sections, generated_at), NOT a CampaignInsight row: row identity (id, campaign_id, model, created_by, created_at) lives only in the sibling `id` field, not on `insight` itself. `id` is present when the insight was persisted; a store failure instead returns 200 with a warnings envelope carrying only `{insight, evidence}`.\n","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/InsightResponse"}}}]}}}},"400":{"description":"Unparseable request body, or `days` outside 1-365."},"404":{"description":"Campaign not found."},"422":{"description":"Draft campaign, or no touches in the window — nothing to analyze."},"429":{"$ref":"#/components/responses/AIRateLimited"},"500":{"description":"Failed to fetch the campaign."},"502":{"description":"The LLM call failed or returned unusable output."},"503":{"description":"Insight history store unavailable."}}},"get":{"tags":["Reporting and responses"],"summary":"Campaign insight history","description":"Stored analyses for this campaign, newest first. `data` is {insights: CampaignInsight[]}.\n","parameters":[{"$ref":"#/components/parameters/CampaignId"},{"name":"limit","in":"query","schema":{"type":"integer","default":10,"maximum":50}}],"responses":{"200":{"description":"`data` is {insights: CampaignInsight[]}.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/InsightListResponse"}}}]}}}},"404":{"description":"Campaign not found."},"500":{"description":"Failed to fetch the campaign or list its insight history."},"503":{"description":"Insight history store unavailable."}}}},"/campaign/api/v1/journeys/{id}/stats":{"get":{"tags":["Reporting and responses"],"summary":"Journey node drop-off report","description":"Run counts by (current node, status) plus status totals. `data` additionally carries `experiments`: one entry per winner-test split decision (all graph versions) — node, version, status (collecting/decided/inconclusive), started_at/deadline/decided_at, the winner, and per-arm `{label, runs, wins}` evidence (live while collecting, the frozen verdict snapshot afterwards).\n","parameters":[{"$ref":"#/components/parameters/JourneyIdTop"}],"responses":{"200":{"description":"`data` is a JourneyNodeStats (with `experiments`).","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/JourneyNodeStats"}}}]}}}},"404":{"description":"Journey not found."}}}},"/campaign/api/v1/journeys/{id}/splits/{nodeId}/decide":{"post":{"tags":["Journeys"],"summary":"Conclude a winner-test split now","description":"Ends the node's winner test early on the evidence collected so far — the same verdict rule the deadline applies (best conversion rate among arms with at least `min_wins` conversions; ties by higher wins, then arm order). Below `min_wins` the verdict is an honest `inconclusive` — an early call never fabricates a winner. Held runs are woken immediately and flow through the verdict; the decision is immutable once made (edit the journey to run a new test on the next graph version).\n","parameters":[{"$ref":"#/components/parameters/JourneyIdTop"},{"name":"nodeId","in":"path","required":true,"schema":{"type":"string"},"description":"The winner-mode split node's id in the journey's current graph."}],"responses":{"200":{"description":"`data.decision` is the concluded SplitDecision (status, winner, per-arm stats snapshot); `data.woken` counts the held runs woken to flow through it.\n","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SplitDecideResponse"}}}]}}}},"400":{"description":"The node is a split, but not a winner test."},"404":{"description":"Journey unknown, or the node is not a split in the current graph."},"409":{"description":"The test has not started (no entrant yet) or already concluded."},"503":{"description":"Split decisions unavailable."}}}},"/campaign/api/v1/languages":{"get":{"tags":["Languages"],"summary":"The tenant's language vocabulary (multilanguage templates)","description":"Singleton settings document: the available languages (raw profile-attribute value → display label, exactly one default) and the per-entity-type attribute carrying the preferred language. An empty document (never configured, or cleared) means the feature is off and every send renders the template's base variants.\n","responses":{"200":{"description":"`data` is the LanguageSettings (empty document when never configured).","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/LanguageSettings"}}}]}}}}}},"put":{"tags":["Languages"],"summary":"Replace the language vocabulary","description":"Replaces the whole document; `{}` clears the vocabulary. Validated all-or-nothing (exactly one default, unique non-empty values, and every `entity_attributes` entry names an entity type in the CDP entity catalogue and an attribute declared on it). Removing a language is SOFT: template mutations for it become unreachable and fall back to the default, campaign language pins degrade the same way — nothing blocks, nothing breaks.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LanguageSettingsRequest"}}}},"responses":{"200":{"description":"`data` is the stored LanguageSettings.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/LanguageSettings"}}}]}}}},"400":{"description":"Validation failed (including an unknown entity type or an attribute not declared on it); nothing was stored."},"503":{"description":"Language settings are not available, or the CDP entity catalogue could not be read (try again; when the CDP refuses the Campaign service's access the message says it is not permitted, and an administrator must fix that); nothing was stored."}}}},"/campaign/api/v1/silent-hours":{"get":{"tags":["Contact policies"],"summary":"The tenant's silent-hours configuration","description":"Singleton settings document: one optional general do-not-send spec plus optional per-channel specs. An empty document (never configured) means the feature is off. Enforcement happens in delivery immediately before transmission — a queued backlog cannot leak past a window.\n","responses":{"200":{"description":"`data` is the SilentHoursSettings (empty document when never configured).","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SilentHoursSettings"}}}]}}}}}},"put":{"tags":["Contact policies"],"summary":"Replace the silent-hours configuration","description":"Whole-document replace, validated all-or-nothing: spec rules (timezone, window shape, holiday country, the always-silent scan) at both levels, channel keys against the tenant's effective push channels — native or operator-declared (onsite channels rejected — they are exempt by design). Edits apply to already-queued sends too: campaign and tenant specs are re-read live at deliver time.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SilentHoursRequest"}}}},"responses":{"200":{"description":"`data` is the stored SilentHoursSettings.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SilentHoursSettings"}}}]}}}},"400":{"description":"Validation failed; nothing was stored."},"503":{"description":"A per-channel key could not be checked because the CDP's channel registry is unreachable, so a declared channel is indistinguishable from an unknown one. Nothing was stored; retry.\n"}}}},"/campaign/api/v1/silent-hours/countries":{"get":{"tags":["Contact policies"],"summary":"List the compiled holiday-calendar countries","description":"The public-holiday calendars a silent-hours spec may reference (rickar/cal, compiled in per country). Codes are lowercase ISO 3166-1 alpha-2.\n","responses":{"200":{"description":"`data` is an array of {code, name}.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/HolidayCountry"}}}}]}}}}}}},"/campaign/api/v1/response-policies":{"get":{"tags":["Contact policies"],"summary":"List cross-offer response policies","parameters":[{"name":"entity_type","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"`data` is a list of ResponsePolicy.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ResponsePolicy"}}}}]}}}}}},"post":{"tags":["Contact policies"],"summary":"Create a cross-offer response policy","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponsePolicyRequest"}}}},"responses":{"201":{"description":"`data` is the stored ResponsePolicy.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ResponsePolicy"}}}]}}}},"400":{"description":"Malformed payload, a missing name or entity_type, an empty rule list (a policy with no rules blocks nothing while reading as though it does), or a rule whose action is not a customer response, whose min is below 1, or whose window_days is negative.\n"},"409":{"description":"A policy with this name already exists."}}}},"/campaign/api/v1/response-policies/{id}":{"get":{"tags":["Contact policies"],"summary":"Get one response policy","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"`data` is the ResponsePolicy.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ResponsePolicy"}}}]}}}},"404":{"description":"Response policy not found."}}},"put":{"tags":["Contact policies"],"summary":"Update a response policy","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponsePolicyRequest"}}}},"responses":{"200":{"description":"`data` is the stored ResponsePolicy.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ResponsePolicy"}}}]}}}},"400":{"description":"Same validation as create — it runs on update too."},"404":{"description":"Response policy not found."},"409":{"description":"A policy with this name already exists."}}},"delete":{"tags":["Contact policies"],"summary":"Delete a response policy","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Deleted. Decides the policy was blocking resume immediately.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"404":{"description":"Response policy not found."}}}},"/campaign/api/v1/response-policies/{id}/revisions":{"get":{"tags":["Revisions and changelog"],"summary":"List a response policy's revisions","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/RevisionIncludeSnapshot"},{"name":"page","in":"query","required":false,"schema":{"type":"integer","default":0}},{"name":"size","in":"query","required":false,"schema":{"type":"integer","default":50}}],"responses":{"200":{"description":"`data` is a list of ConfigRevision, newest first.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ConfigRevision"}}}}]}}}},"404":{"description":"Not found, or the id in the path is not a uuid."}}}},"/campaign/api/v1/response-policies/{id}/revisions/{revision}":{"get":{"tags":["Revisions and changelog"],"summary":"Read one response policy revision","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/RevisionNumber"}],"responses":{"200":{"description":"`data` is the ConfigRevision, snapshot included.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ConfigRevision"}}}]}}}},"404":{"description":"Revision not found."}}}},"/campaign/api/v1/response-policies/{id}/revisions/{revision}/restore":{"post":{"tags":["Revisions and changelog"],"summary":"Roll a response policy back to an earlier revision","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/RevisionNumber"}],"responses":{"200":{"description":"`data` is a RestoreResult.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RestoreResult"}}}]}}}},"404":{"description":"Revision not found, or the policy no longer exists."},"409":{"description":"The revision records a delete."},"422":{"description":"The stored configuration is no longer valid."}}}},"/campaign/api/v1/fatigue-policies":{"get":{"tags":["Contact policies"],"summary":"List fatigue policies","parameters":[{"name":"entity_type","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"`data` is a list of FatiguePolicy.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/FatiguePolicy"}}}}]}}}}}},"post":{"tags":["Contact policies"],"summary":"Create a fatigue policy","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FatiguePolicyRequest"}}}},"responses":{"201":{"description":"`data` is the stored FatiguePolicy.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FatiguePolicy"}}}]}}}},"400":{"description":"Malformed payload, or a missing/invalid name, max_touches, window_days or campaign_types value."},"409":{"description":"A policy with this name already exists."},"422":{"description":"A scope-shape rule failed — an unknown `scope`; `entity_type` missing on a profile-scoped policy or present on a hierarchy one; `anchor_entity_type` / `relation_types` on a profile-scoped policy or missing on a hierarchy one; `campaign_types` on a hierarchy policy; or an `anchor_entity_type` the CDP entity catalogue does not know.\n"},"503":{"description":"The CDP entity catalogue was unavailable, so anchor_entity_type could not be validated."}}}},"/campaign/api/v1/fatigue-policies/{id}":{"get":{"tags":["Contact policies"],"summary":"Get one fatigue policy","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"`data` is the FatiguePolicy.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FatiguePolicy"}}}]}}}},"404":{"description":"Fatigue policy not found."}}},"put":{"tags":["Contact policies"],"summary":"Update a fatigue policy","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FatiguePolicyRequest"}}}},"responses":{"200":{"description":"`data` is the stored FatiguePolicy.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FatiguePolicy"}}}]}}}},"400":{"description":"Malformed payload, or a missing/invalid name, max_touches, window_days or campaign_types value."},"404":{"description":"Fatigue policy not found."},"409":{"description":"A policy with this name already exists."},"422":{"description":"A scope-shape rule failed — an unknown `scope`; `entity_type` missing on a profile-scoped policy or present on a hierarchy one; `anchor_entity_type` / `relation_types` on a profile-scoped policy or missing on a hierarchy one; `campaign_types` on a hierarchy policy; or an `anchor_entity_type` the CDP entity catalogue does not know.\n"},"503":{"description":"The CDP entity catalogue was unavailable, so anchor_entity_type could not be validated."}}},"delete":{"tags":["Contact policies"],"summary":"Delete a fatigue policy","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Fatigue policy deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"404":{"description":"Fatigue policy not found."}}}},"/campaign/api/v1/code-pools":{"get":{"tags":["Code pools"],"summary":"List coupon code pools","parameters":[{"name":"page","in":"query","schema":{"type":"integer","minimum":0}},{"name":"size","in":"query","schema":{"type":"integer","minimum":0,"maximum":100}}],"responses":{"200":{"description":"`data` is a list of CodePool.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CodePool"}}}}]}}}}}},"post":{"tags":["Code pools"],"summary":"Create a coupon code pool","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CodePoolRequest"}}}},"responses":{"201":{"description":"`data` is the stored CodePool (counts all zero — a new pool owns no codes yet).","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CodePool"}}}]}}}},"400":{"description":"Malformed payload, an invalid pool name (quotes/backticks, wrong charset, over 64 chars), or kind=generated with a missing/invalid pattern."},"409":{"description":"A pool with this name already exists."}}}},"/campaign/api/v1/code-pools/{id}":{"get":{"tags":["Code pools"],"summary":"Get one coupon code pool","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"`data` is the CodePool.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CodePool"}}}]}}}},"404":{"description":"Code pool not found."}}},"put":{"tags":["Code pools"],"summary":"Update a coupon code pool","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"force","in":"query","description":"Rename the pool even though active templates or documents claim from the old name via {{coupon}} (their sends then fail with reason code_pool_missing). Ignored when the name is unchanged.","schema":{"type":"boolean","default":false}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CodePoolRequest"}}}},"responses":{"200":{"description":"`data` is the stored CodePool. `data` also carries `approvals_cleared` (ApprovalsCleared).","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CodePool"}}}]}}}},"400":{"description":"Malformed payload, an invalid pool name, kind=generated with a missing/invalid pattern, or an attempt to change kind (immutable after creation)."},"404":{"description":"Code pool not found."},"409":{"description":"A pool with this name already exists, or the name is changing while an active message template (base variants or a translation) or active document template (layout or password template) claims from the old name via {{coupon}} — the message names them as `template \"<name>\"` or `document \"<name>\"`. Pass force=true to rename anyway."}}},"delete":{"tags":["Code pools"],"summary":"Delete a coupon code pool","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"force","in":"query","description":"Delete even if the pool still has issued or redeemed codes (cascades to its codes).","schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"Code pool deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"404":{"description":"Code pool not found."},"409":{"description":"The pool still has issued or redeemed codes, or an active message template (base variants or a translation) or active document template (any layout string or the password template) claims from it via {{coupon}} — the message names those templates (as `template \"<name>\"` or `document \"<name>\"`). Pass force=true to delete anyway; sends of such a template then fail with reason code_pool_missing."}}}},"/campaign/api/v1/code-pools/{id}/upload":{"post":{"tags":["Code pools"],"summary":"Upload a CSV of codes into an `uploaded` pool","description":"Multipart form upload, field name \"file\": one code per line, an optional leading \"code\" header row (case-insensitive), blank lines skipped, in-file duplicates deduplicated. Re-uploading a file already imported reports every line as a duplicate rather than erroring — ON CONFLICT DO NOTHING at the store layer. `duplicates` counts codes already in this pool. A code that already exists in another pool is not imported and is reported in `skipped_other_pool` instead.\n","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary"}},"required":["file"]}}}},"responses":{"200":{"description":"`data` reports how many codes landed.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"inserted":{"type":"integer","format":"int64"},"duplicates":{"type":"integer","format":"int64"},"skipped_other_pool":{"type":"integer","format":"int64"},"total_free":{"type":"integer","format":"int64"}}}}}]}}}},"400":{"description":"The pool's kind is not \"uploaded\", the \"file\" form field is missing, or the CSV failed to parse (over 500,000 codes, a code over 64 characters, or one containing a control character)."},"404":{"description":"Code pool not found."},"413":{"description":"The file exceeds the configured maximum upload size (campaign_upload_max_mb)."}}}},"/campaign/api/v1/code-pools/{id}/generate":{"post":{"tags":["Code pools"],"summary":"Mint codes into a `generated` pool","description":"Expands the pool's pattern `count` times, inserting with ON CONFLICT DO NOTHING and regenerating any shortfall from in-batch or cross-table collisions (up to 5 rounds) before giving up.\n","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateCodesRequest"}}}},"responses":{"200":{"description":"`data.inserted` is how many new codes were minted.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"inserted":{"type":"integer","format":"int64"}}}}}]}}}},"400":{"description":"Malformed payload, or the pool's kind is not \"generated\"."},"404":{"description":"Code pool not found."},"409":{"description":"The pattern space is too small for the requested count even after 5 regeneration rounds."}}}},"/campaign/api/v1/code-pools/{id}/remaining":{"get":{"tags":["Code pools"],"summary":"Live per-state code counts for a pool","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"`data` is {free, claimed, issued, redeemed, expired}.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"free":{"type":"integer","format":"int64"},"claimed":{"type":"integer","format":"int64"},"issued":{"type":"integer","format":"int64"},"redeemed":{"type":"integer","format":"int64"},"expired":{"type":"integer","format":"int64"}}}}}]}}}},"404":{"description":"Code pool not found."}}}},"/campaign/api/v1/channels":{"get":{"tags":["Channels"],"summary":"Channel summary — provider instances + default per channel","responses":{"200":{"description":"`data` is a list of ChannelStatus: the native channels (email, sms, rcs, whatsapp, viber, push, webhook), the tenant's declared channels (`custom: true`), and any channel still holding providers after its declaration was removed.\n","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ChannelStatus"}}}}]}}}}}}},"/campaign/api/v1/channels/vocabulary":{"get":{"tags":["Channels"],"summary":"The effective channel vocabulary — native ∪ the tenant's declared channels","description":"What a channel picker renders. Native channels are compiled in; operator-declared ones come from the CDP's `/cdp/api/v1/channels` registry, where consent purposes, the preference centre and the erasure job also read them. Each entry names the message-template variant that carries its copy (`template_variant`): a native channel is its own variant, a declared one borrows a built-in schema.\n","responses":{"200":{"description":"`data` is a list of `{name, label, contact_kind, template_variant, custom, is_active}`.\n","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ChannelVocabularyEntry"}}}}]}}}},"503":{"description":"The CDP's channel registry could not be read, so the declared half of the vocabulary is unknown. Reported rather than answered with the native channels alone — a picker silently missing the channels an operator declared reads as \"the declaration never landed\". Check that the Campaign service key is granted `GET /cdp/api/v1/channels`.\n"}}}},"/campaign/api/v1/channels/catalog":{"get":{"tags":["Channels"],"summary":"Supported provider types and their config/credential field schemas","responses":{"200":{"description":"`data` is a list of ChannelProviderSpec. Includes the generic `http` provider on each of the tenant's declared channels. Degrades to the native catalog when the CDP's channel registry is unreadable.\n","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ChannelProviderSpec"}}}}]}}}}}}},"/campaign/api/v1/channels/providers":{"get":{"tags":["Channels"],"summary":"List channel provider instances","parameters":[{"name":"channel","in":"query","description":"Filter by channel — native or operator-declared. An unmatched name returns an empty list rather than an error.\n","schema":{"type":"string"}}],"responses":{"200":{"description":"`data` is a list of ChannelProvider (defaults first).","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ChannelProvider"}}}}]}}}}}},"post":{"tags":["Channels"],"summary":"Create a channel provider instance","description":"The first provider of a channel automatically becomes its default; is_default true displaces the current default. Config and credentials are validated against the provider type's schema (webhook templates parse-checked) before persisting. A `config.network_id` is checked to exist at save time — a typo is a 400 here rather than a permanent send failure later; disabled networks are accepted, matching connectors. Without a `network_id`, a literal private, loopback, link-local, CGNAT or cloud-metadata host in `config.url` or `config.auth.token_url` is a 400 (`config.url: ...`). Loopback is always refused; another private range only unless your platform operator has allowed it. A templated host is checked when dialled. The same check applies to an SMTP provider's `config.host` (as `config.host: ...`). A provider that becomes the channel default re-routes every unpinned send on the channel, so it clears the standing approval of those campaigns in the same transaction (listed in `approvals_cleared`). An onsite channel needs its licence feature (403 otherwise).\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChannelProviderRequest"}}}},"responses":{"201":{"description":"Provider created; `data` is the ChannelProvider and also carries `approvals_cleared` (ApprovalsCleared).","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ChannelProvider"}}}]}}}},"400":{"description":"Unknown channel/provider type, invalid config, missing required credential, or a config.network_id that does not exist."},"409":{"description":"A provider with this name already exists."},"503":{"description":"Credentials supplied but credential encryption is not configured on this instance."}}}},"/campaign/api/v1/channels/providers/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"tags":["Channels"],"summary":"Get one channel provider (never returns credential values)","responses":{"200":{"description":"`data` is the ChannelProvider.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ChannelProvider"}}}]}}}},"404":{"description":"Provider not found."}}},"put":{"tags":["Channels"],"summary":"Update a channel provider","description":"channel/provider_type are immutable (recreate to re-type). Omitting `credentials` keeps the stored secrets; sending a map replaces them. A literal private `config.url` or `config.auth.token_url` is checked as on create, but a URL equal to the stored one is re-checked only when the provider is being activated, so a provider saved before the check existed can still be deactivated.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChannelProviderRequest"}}}},"responses":{"200":{"description":"Provider updated. `data` also carries `approvals_cleared` (ApprovalsCleared).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"400":{"description":"Validation failed or channel/provider_type changed."},"404":{"description":"Provider not found."},"409":{"description":"A provider with this name already exists, OR `credentials_required`: the update changes a destination part (smtp host/port/user, base_url, http url/auth target, network_id) while omitting `credentials`. Re-send the credentials, or send `{}` to clear them.\n","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/GenericResponse"},{"$ref":"#/components/schemas/CredentialsRequiredResponse"}]}}}}}},"delete":{"tags":["Channels"],"summary":"Delete a channel provider","description":"Campaigns pinning this provider fall back to the channel default (provider_id nulled). Deleting the default promotes the channel's oldest remaining provider. Both re-route approved campaigns, so their standing approval is cleared in the same transaction.\n","responses":{"200":{"description":"Provider deleted. `data` is `{approvals_cleared}` (ApprovalsCleared).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"404":{"description":"Provider not found (or a malformed id)."}}}},"/campaign/api/v1/channels/providers/{id}/default":{"post":{"tags":["Channels"],"summary":"Make this provider its channel's default","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"`data` is the updated ChannelProvider. `data` also carries `approvals_cleared` (ApprovalsCleared).","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ChannelProvider"}}}]}}}},"404":{"description":"Provider not found."}}}},"/campaign/api/v1/channels/providers/{id}/test":{"post":{"tags":["Channels"],"summary":"Live connection test for one provider","description":"Non-destructive probe — SMTP TCP reachability, Mailgun domain fetch, Twilio account fetch, FCM OAuth token minting, APNs key validation, webhook OAuth2 token fetch. A non-oauth2 webhook provider opens a TCP connection to the endpoint's host and port through the SSRF guard (and the provider's private network when set) and sends no request; success reads \"endpoint reachable (TCP connect only, no request sent)\" and a blocked destination fails naming the guard. A templated or empty endpoint URL has no fixed target and reports \"no live check\". Other provider types without a probe (infobip/sinch) report parameter validity only, with the message \"connection parameters valid (no live check available for this provider type)\"; \"connection OK\" means a probe really connected. No message is sent. The `smtp` probe (and every real send) dials through the provider's private network when one is configured, otherwise through the same SSRF guard the HTTP-based providers use: loopback/RFC1918/link-local/CGN targets come back `success: false` with a message naming the blocked destination rather than a connect/refused distinction that would map internal hosts. An internal relay needs an explicit allowlist entry by the operator (or a private network) to pass.\n","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"`data` is a ChannelProviderTestResult (success may be false).","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ChannelProviderTestResult"}}}]}}}},"404":{"description":"Provider not found."},"409":{"description":"The tenant's outbound mode is `off` (Environments): no egress at all, probes included. Probes stay allowed in `sink`."},"503":{"description":"Stored credentials but credential encryption is not configured on this instance."}}}},"/campaign/api/v1/channels/providers/{id}/preview":{"post":{"tags":["Channels"],"summary":"Render (dry run) the request this provider would send","description":"For provider type `http` only — every other type builds its request inside a provider-specific API client and has nothing to show (400). Returns the exact method, URL, headers and body, rendered against a real profile when `profile_id` is given (the caller's X-Purpose is forwarded, so a preview can never surface data the caller may not read). Credential-bearing headers are redacted, and an OAuth2 Authorization header reads `Bearer <fetched at send time>` rather than minting a token as a side effect of looking. **Nothing is sent unless `execute: true`** — the endpoint on the other side cannot tell a rehearsal from a real action. A render or config failure (a missing required parameter, an unparsable template) comes back as a 400 with the reason: that is what the preview is for. Credentials are attached only when the request's host is the literal host of the provider's `url`; otherwise the request carries none and `request.credentials_withheld` is true.\n","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PreviewRequest"}}}},"responses":{"200":{"description":"`data` is {request: {method, url, headers, body}, executed, status?, body?}.\n","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProviderPreviewResponse"}}}]}}}},"400":{"description":"Not an http provider, or the request could not be rendered."},"404":{"description":"Provider not found, or the `profile_id` names no profile (`profile not found`)."},"409":{"description":"`execute: true` while the tenant's outbound mode is `sink` or `off` (Environments) — the render-only preview stays available."},"502":{"description":"The CDP profile read failed; the message is the fixed `CDP unavailable`."},"503":{"description":"Stored credentials but credential encryption is not configured on this instance."}}}},"/campaign/api/v1/systems/{id}/preview":{"post":{"tags":["External systems"],"summary":"Render (dry run) the request this external system would send","description":"Same contract as the provider preview; see that endpoint.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PreviewRequest"}}}},"responses":{"200":{"description":"`data` is the rendered request (+ the response when executed).","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProviderPreviewResponse"}}}]}}}},"400":{"description":"The request could not be rendered."},"404":{"description":"External system not found, or the `profile_id` names no profile (`profile not found`)."},"502":{"description":"The CDP profile read failed; the message is the fixed `CDP unavailable`."}}}},"/campaign/api/v1/channels/reencrypt":{"post":{"tags":["Channels"],"summary":"Re-encrypt channel-provider, external-system and destination credentials","description":"Key rotation: blobs that fail to decrypt with the current credential key are decrypted with the previous key and re-encrypted with the current key; already-current blobs are untouched. The previous key is Campaign's own previous key, or the CDP credential key's previous key when Campaign uses that one. Outside a rotation there is no previous key, so the call only reports. Call it once per tenant. Not licence-gated.\n","responses":{"200":{"description":"Per-table results (`providers` covers external systems too).","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"providers":{"$ref":"#/components/schemas/ReencryptResult"},"destinations":{"$ref":"#/components/schemas/ReencryptResult"}}}}}]}}}},"503":{"description":"Credential encryption is not configured","or the previous key is malformed.":null}}}},"/campaign/api/v1/channels/providers/{id}/receipt-token/rotate":{"post":{"tags":["Channels"],"summary":"Rotate the provider's delivery-receipt path token","description":"Mints a new receipt callback token and returns the provider with its new `receipt_url` (empty until the instance's receipt callback address is configured). Providers are born with a token; rotate when it leaked or to cut off an account-level webhook. Callbacks registered with the old URL stop being admitted at the edge gateway within one config-poll interval (≤30s). For providers WITHOUT a native webhook signature (Infobip, Postmark, Sinch), the unguessable URL is the endpoint's entire authenticity guarantee — the console shows that note next to the copyable URL. Account-level providers (Meta, Vonage, SendGrid, Mailgun, Postmark, Mandrill, Sinch) need the new URL pasted into their own console; Meta additionally uses the token as the webhook `hub.verify_token`.\n","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"`data` is the ChannelProvider with the new `receipt_url`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ChannelProvider"}}}]}}}},"404":{"description":"Provider not found."}}}},"/campaign/api/v1/documents":{"get":{"tags":["Documents"],"summary":"List document templates (ordered by name)","description":"Document templates — frame + flow layouts rendered per recipient into a PDF. Analyst read comes from the blanket GET grant.\n","parameters":[{"name":"entity_type","in":"query","schema":{"type":"string"}},{"name":"active","in":"query","schema":{"type":"boolean"}},{"name":"search","in":"query","schema":{"type":"string"},"description":"Case-insensitive substring match on the name."},{"name":"page","in":"query","schema":{"type":"integer","minimum":0,"default":0}},{"name":"size","in":"query","description":"Omitted (or 0) means the platform default of 100; 100 is also the cap.","schema":{"type":"integer","minimum":1,"maximum":100,"default":100}}],"responses":{"200":{"description":"Document templates with page metadata.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DocumentTemplate"}}}}]}}}}}},"post":{"tags":["Documents"],"summary":"Create a document template","description":"The layout is parse-validated (structure, every template string) and referentially validated (every referenced content item must be servable — published pin present; PDF backgrounds are deep-checked through the exact gofpdi import the renderer performs, with PNG/JPEG as the documented fallback when a designed PDF cannot be imported). Every content item the layout references (backgrounds, images, fonts) must also carry a PII level at or below the caller's own PII access level — the same gate template attachments enforce.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentRequest"}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DocumentTemplate"}}}]}}}},"400":{"description":"Layout, password template or filename template invalid."},"403":{"description":"The layout references content above the caller's PII access level."},"409":{"description":"A document template with this name already exists."}}}},"/campaign/api/v1/documents/preview":{"post":{"tags":["Documents"],"summary":"Render an UNSAVED layout to a PDF (the editor's live preview)","description":"Renders the request's layout and answers the PDF bytes directly. The profile half of the context comes from either `profile_id` (read live from the CDP under the request's X-Purpose — the same read /documents/{id}/render performs, so a preview proves what a send would produce) or the hand-written `attributes`/`signals`, which is how a template is authored before a matching profile exists. When `password_template` is supplied the AES-256 password step runs too — a template that renders an empty password is a 422 (`document_password_empty`), the same fail-closed rule the send path enforces. Analyst-permitted (writes nothing). Every content item the layout references (backgrounds, images, fonts) must carry a PII level at or below the caller's own PII access level, or the whole preview is refused before any PDF bytes are produced.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentPreviewRequest"}}}},"responses":{"200":{"description":"The rendered PDF.","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Layout invalid or render failed (reason in the message)."},"403":{"description":"The declared purpose is not granted for reading this profile","or the layout references content above the caller's PII access level.":null},"404":{"description":"profile_id matched no profile in the CDP."},"422":{"description":"The password template rendered empty for this context."}}}},"/campaign/api/v1/documents/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"tags":["Documents"],"summary":"Get one document template","responses":{"200":{"description":"The document template.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DocumentTemplate"}}}]}}}},"404":{"description":"Not found."}}},"put":{"tags":["Documents"],"summary":"Update a document template (full replace)","description":"Runs the same layout validation as create, including the PII gate on every content item the layout references.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentRequest"}}}},"responses":{"200":{"description":"Updated. `data` also carries `approvals_cleared` (ApprovalsCleared).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"400":{"description":"Validation failed."},"403":{"description":"The layout references content above the caller's PII access level."},"404":{"description":"Not found."}}},"delete":{"tags":["Documents"],"summary":"Delete a document template","responses":{"200":{"description":"Deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"404":{"description":"Not found."}}}},"/campaign/api/v1/documents/{id}/render":{"post":{"tags":["Documents"],"summary":"Render a saved document template to a PDF","description":"The standalone \"template + values → PDF\" capability. The body carries either `profile_id` (deliver-style context read via the CDP with the caller's X-Purpose — purpose authorization, PII level and consent are the CDP's call) or a raw `values` map (exposed as `{{.Run.State.*}}`, arrays for table blocks included), or both. When the template carries a `password_template` the returned PDF is AES-256 encrypted with the rendered password; a template whose password renders empty is a 422 — never a silently unprotected document. The Content-Disposition filename is the template's `public_filename` resolved now. Analyst-permitted (writes nothing). The stored layout's content refs are re-checked against the caller's PII access level at render time too (PII only — a stored layout that would otherwise fail the save-time approved-pin check still renders).\n","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentRenderRequest"}}}},"responses":{"200":{"description":"The rendered (possibly encrypted) PDF.","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Render failed (reason in the message)."},"403":{"description":"The stored layout references content above the caller's PII access level."},"404":{"description":"Template or profile not found."},"422":{"description":"Template inactive, or the password rendered empty."}}}},"/campaign/api/v1/templates":{"get":{"tags":["Templates"],"summary":"List message templates (ordered by name)","parameters":[{"name":"entity_type","in":"query","schema":{"type":"string"}},{"name":"active","in":"query","schema":{"type":"boolean"},"description":"true returns only active templates."},{"name":"search","in":"query","description":"Case-insensitive **substring** match on the template name, for\ntypeahead pickers; LIKE metacharacters are escaped. Blank is no\nfilter. Same semantics as the segments list's `search`.\n","schema":{"type":"string"},"example":"winback"},{"name":"channel","in":"query","description":"Keep only templates carrying that channel's variant (variant-key\nexistence, so a multi-channel template matches under each of its\nchannels). `auto` means \"has at least one variant\" — the delivery\nchannel is resolved at send time.\n\nAn OPERATOR-DECLARED channel is resolved to the variant it borrows,\nand matches a template that either carries that variant OR names\nthe channel in `channels` — so a template written before the\nchannel was declared stays findable.\n","schema":{"type":"string","enum":["email","sms","rcs","whatsapp","viber","push","webhook","auto"]}},{"name":"page","in":"query","schema":{"type":"integer","minimum":0,"default":0}},{"name":"size","in":"query","description":"Omitted (or 0) means the platform default of 100; 100 is also the cap.","schema":{"type":"integer","minimum":1,"maximum":100,"default":100}}],"responses":{"200":{"description":"Templates with page metadata.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/MessageTemplate"}}}}]}}}}}},"post":{"tags":["Templates"],"summary":"Create a message template","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TemplateRequest"}}}},"responses":{"201":{"description":"Created. The envelope's `warnings` lists non-blocking notes, one per profile attribute the default copy or a language mutation reads that the template's entity type does not declare (`attribute \"x\" (email.subject) is not declared on entity \"customer\"`; a mutation's location carries its language, `de:email.subject`); absent when there are none or the entity catalogue could not be read within about two seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"400":{"description":"Variant validation failed (unknown channel/field, missing required field, template parse error)."},"409":{"description":"A template with this name already exists."},"422":{"description":"A template string uses a construct that cannot be bounded at run time (range over a literal, `{{range}}` nested deeper than 3, a recursive `{{template}}`). `data.issues` is `[{message}]`; the message names the channel, field and construct. Stored templates saved before this check keep rendering under the runtime limits (by default 256 KiB output, 2 s, 1 000 000 range iterations per field).\n"}}}},"/campaign/api/v1/templates/generate":{"post":{"tags":["Templates"],"summary":"Draft message copy with the LLM (never saved)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateCopyRequest"}}}},"responses":{"200":{"description":"`data.variants` is an array of drafts, each a field map matching the requested schema and already parse-validated (drafts that fail validation are dropped). The keys are the channel's variant fields, except under `format: mjml` where the design comes back as `body_mjml`. Nothing is persisted.\n","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/GenerateCopyResponse"}}}]}}}},"400":{"description":"Invalid request, or a non-text `format` on a channel other than email."},"429":{"$ref":"#/components/responses/AIRateLimited"},"502":{"description":"LLM unavailable or returned nothing usable."}}}},"/campaign/api/v1/templates/preview":{"post":{"tags":["Templates"],"summary":"Preview UNSAVED template text (the editor's live preview)","description":"Renders ad-hoc template strings over a sample (or live) send context —\nno template is loaded or saved. `fields` maps field name → template\nsource; escaping follows delivery exactly (`html/template` for email\n`body_html`, `text/template` otherwise). Single-value inputs (webhook\nURLs, parameter values, condition values) send one entry under any\nname with `channel` omitted.\n\nA broken template is the ANSWER, not a request failure: the call\nreturns 200 and the field carries `ok: false` plus the exact Go parse\nor execution error with the line it points at. Successful fields also\nreport `references` — every context path the template reads, each\nmarked `resolved` against the supplied context (the \"Hi ,\" detector).\n\nWith `profile_id`, the live profile's attributes/signals are read via\nthe CDP under the caller's `X-Purpose`. Onsite channels\n(`web_banner`/`web_personalization`/`mobile_inapp`) are refused with\n422 — their fields render in the edge personalization language;\npreview those via the CDP's `/cdp/api/v1/edge/preview`.\n\nPreviews apply the save-time check; an unboundable construct is that\nfield's `ok: false` error.\n","parameters":[{"$ref":"#/components/parameters/PurposeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TemplatePreviewRequest"}}}},"responses":{"200":{"description":"`data.fields` maps each requested field to\n`{ok, rendered?, error?: {message, line?}, references?:\n[{path, defaulted?, resolved}]}`. `line` 0/absent means the error\ncarried no position.\n","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TemplatePreviewResponse"}}}]}}}},"400":{"description":"Malformed request (no fields, more than 64 fields, bad JSON)."},"404":{"description":"profile_id not found in the CDP."},"422":{"description":"Onsite channel — preview via /cdp/api/v1/edge/preview."}}}},"/campaign/api/v1/templates/{id}":{"get":{"tags":["Templates"],"summary":"Get a template","parameters":[{"$ref":"#/components/parameters/TemplateId"}],"responses":{"200":{"description":"The template.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MessageTemplate"}}}]}}}},"404":{"description":"Not found."}}},"put":{"tags":["Templates"],"summary":"Update a template","parameters":[{"$ref":"#/components/parameters/TemplateId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TemplateRequest"}}}},"responses":{"200":{"description":"Updated. `data` is the template plus `approvals_cleared` (ApprovalsCleared; `[]` when no campaign's approval was reset; campaigns that reference the template through a catalogue offer, inactive ones included, are reset too). The envelope's `warnings` lists non-blocking notes, one per profile attribute the default copy or a language mutation reads that the template's entity type does not declare (`attribute \"x\" (email.subject) is not declared on entity \"customer\"`; a mutation's location carries its language, `de:email.subject`); absent when there are none or the entity catalogue could not be read within about two seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"400":{"description":"Variant validation failed."},"404":{"description":"Not found."},"409":{"description":"Duplicate name, or a rename of a template that draft, active or paused campaigns still send (by batch template, journey send node, or an offer's `payload.template`, including the campaign's catalogue offers, inactive ones included). Same body as the delete refusal: `data.campaigns` lists them as `{id, name, status}`."},"422":{"description":"A template string uses a construct that cannot be bounded at run time (range over a literal, `{{range}}` nested deeper than 3, a recursive `{{template}}`). `data.issues` is `[{message}]`; the message names the channel, field and construct. Stored templates saved before this check keep rendering under the runtime limits (by default 256 KiB output, 2 s, 1 000 000 range iterations per field).\n"}}},"delete":{"tags":["Templates"],"summary":"Delete a template","parameters":[{"$ref":"#/components/parameters/TemplateId"}],"responses":{"200":{"description":"Deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"404":{"description":"Not found."},"409":{"description":"The template is still used by draft, active or paused campaigns (by batch template, journey send node, or an offer's `payload.template`, including the campaign's catalogue offers, inactive ones included). The message names up to five of them with their status and adds \"and N more\" past that. `data.campaigns` lists all of them as `{id, name, status}`, ordered by name; this is a structured shape specific to this endpoint.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"message":{"type":"string"},"data":{"type":"object","properties":{"campaigns":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","enum":["draft","active","paused"]}}}}}}}}}}}}}},"/campaign/api/v1/templates/{id}/render":{"post":{"tags":["Templates"],"summary":"Render a channel variant (preview)","parameters":[{"$ref":"#/components/parameters/TemplateId"},{"$ref":"#/components/parameters/PurposeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RenderTemplateRequest"}}}},"responses":{"200":{"description":"`data.rendered` maps each variant field to its rendered string; `data.language` names the language whose mutation rendered (\"\" = the base/default copy). Renders with the same context as `/templates/preview`: `{{shortlink}}` renders the raw target, `{{coupon}}` the sample code, and `{{items}}` resolves for the `profile_id` given (and fails without one).\n","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RenderTemplateResponse"}}}]}}}},"400":{"description":"Unknown channel variant or render error."},"404":{"description":"Template (or profile_id) not found."}}}},"/campaign/api/v1/templates/{id}/translate":{"post":{"tags":["Templates"],"summary":"Draft a language mutation by translating the default copy (AI)","description":"Translate-from-default: machine-translates the template's DEFAULT copy — the base variants — into a target vocabulary language as a starting point for a mutation. The draft is returned for review and NEVER saved.\n\nDefensive by construction, since prompt-only constraints cannot be trusted: every `{{...}}` template action must survive the translation exactly (canonical multiset comparison), the translated copy must still pass the save-time variant rules (validated overlaid on the full source variant), and violations trigger a bounded self-repair loop. A draft still broken afterwards is a 502, never a result.\n\nField taxonomy: only human-text fields (subject, bodies, titles, button/CTA labels) are translated; URLs, deep links, identifiers and numeric knobs are carried into the draft VERBATIM; structured documents (push `buttons`, `data`, WhatsApp `template_params`) are carried untranslated with a warning. Visual emails translate the MJML DESIGN's text, never the compiled `body_html` — the draft omits `body_html` and the builder compiles it from the translated design, keeping the staleness contract intact. Webhook and onsite variants are refused (422): they carry structured payloads / edge-language fields, not prose.\n","parameters":[{"$ref":"#/components/parameters/TemplateId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["channel","target_language"],"properties":{"channel":{"type":"string","description":"Whose copy translates; a declared channel translates the variant it borrows.\n"},"target_language":{"type":"string","description":"The vocabulary VALUE of the mutation being drafted. Must exist in `/campaign/api/v1/languages` and must not be the default (the default's copy IS the base variants). Its label is what the translator is instructed with.\n"}}}}}},"responses":{"200":{"description":"`data` is the draft: `fields` (the complete mutation cell — translated prose + verbatim carry-overs; `body_html` omitted for visual emails), `design` (the translated MJML, when the variant has one), `language`, `variant_key`, `repair_rounds` and `warnings`. Nothing is persisted.\n","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TranslateTemplateResponse"}}}]}}}},"400":{"description":"Unknown/default target language, no such variant, or nothing translatable."},"404":{"description":"Template not found."},"422":{"description":"Webhook or onsite variant — no prose to translate."},"429":{"$ref":"#/components/responses/AIRateLimited"},"502":{"description":"The LLM failed, or its draft could not be validated after repair."}}}},"/campaign/api/v1/responses":{"post":{"tags":["Reporting and responses"],"summary":"Report customer responses to decided offers (NBA response collection)","description":"The trusted intake surface —\na call-centre app, a CRM, an ordering system — reports what a\ncustomer did with an offer, against the `nba_id` the decide returned.\nAuthorized like every other write route in this API: `campaign_editor`/\n`campaign_admin`/`engineer`/`admin` have full access; the read-only roles\nare GET-only (there is nothing to read here, so they effectively get\nnothing).\n\nThe handler validates SHAPE only (well-formed `nba_id`, a known\n`action`, `profile_id` present) and queues each response; being\naccepted for processing IS the 202 — nothing is resolved or written\nsynchronously. A background\nprocess resolves the `nba_id` (a short-lived\ncache written at decide time, falling back to a profile-scoped\n`campaign_touch` ledger read for a response that arrives after the\ncache entry expired), verifies it belongs to the given `profile_id`,\ndeduplicates by `(nba_id, action)`, and logs the response as an\nordinary `campaign_touch` event under the resolved purpose. A 4xx\nfrom that write (e.g. an erased profile) is terminal — a response\nnever resurrects an erased profile.\n\nThe WHOLE batch is validated before anything is published: a\npartially published batch would be re-reported in full on retry, and\nthe consumer's dedup is the only thing standing between that and\nduplicate touches.\n\n\n`profile_id` is REQUIRED, unlike on the Edge surface\n(`POST /edge/v1/nba/responses`). It is what makes the ledger fallback\nreachable — the CDP's profile-scoped event read is indexed, whereas\nresolving a bare `nba_id` globally would be a scan across\nevery profile's events — and it lets the consumer refuse a response\nwhose profile does not own the resolved decision, closing\ncross-customer misattribution from an upstream bug.\n\n\nThe touch also records WHICH SURFACE reported the answer, in the\n`response_source` attribute: `console` when the caller is a user\nsession (a human testing response rules from the campaign console),\n`api` otherwise, and `edge` from the public gateway route. It is\nderived from the credential presented, never from the body — a\nservice key cannot launder its production responses as console tests,\nand the console cannot disclaim its own. Console responses are REAL\ntouches: they suppress and count exactly like a customer's own\nanswer, and the marking exists so a human can tell later why a profile\nstopped being offered something (see\n`GET /campaigns/{id}/responses`).\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"responses":{"type":"array","maxItems":200,"items":{"type":"object","properties":{"nba_id":{"type":"string","description":"The 26-character id from the decide response's winning offer."},"profile_id":{"type":"string","format":"uuid"},"action":{"type":"string","enum":["presented","accepted","postponed","rejected","realized"]},"reason":{"type":"string","description":"Caller-supplied code annotating the response (\"too_expensive\"). Optional on every action.\n"},"reference_id":{"type":"string","description":"The reporting system's own handle for the outcome (an order id). Optional on every action."},"value":{"type":"number","description":"The outcome's monetary value, if any. Optional on every action, not gated to `realized`."},"ts":{"type":"integer","format":"int64","description":"Reporter's client timestamp (epoch seconds), diagnostics only."}},"required":["nba_id","profile_id","action"]}}},"required":["responses"]}}}},"responses":{"202":{"description":"Every response in the batch was accepted for processing (published, not yet resolved).","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"accepted":{"type":"integer","description":"Count of responses published."}}}}}]}}}},"400":{"description":"Empty batch, more than 200 responses in one batch, a malformed `nba_id` (must be 26 characters), a missing `profile_id`, or an `action` outside presented/accepted/postponed/rejected/realized.\n"},"503":{"description":"Response collection temporarily unavailable (response queue not connected). Retry-After header set."}}}},"/campaign/api/v1/campaigns/{id}/journeys":{"get":{"tags":["Journeys"],"summary":"List a campaign's journeys","parameters":[{"$ref":"#/components/parameters/CampaignId"}],"responses":{"200":{"description":"`data` is a list of Journey (with live-run counts).","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Journey"}}}}]}}}},"404":{"description":"Campaign not found."}}},"post":{"tags":["Journeys"],"summary":"Create a journey","description":"Journeys can only be saved on `journey_based` campaigns — on batch types the dispatcher and the journey would contact the segment independently, and on `inbound_offer` nothing meaningful triggers. Other types get a 422 issue (same rule on update). A send node on an onsite channel (`web_banner`, `web_personalization`, `mobile_inapp`) needs that channel's licence feature, like a campaign saved on it (403 `feature_not_licensed`; same rule on update and restore).\n","parameters":[{"$ref":"#/components/parameters/CampaignId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JourneyRequest"}}}},"responses":{"201":{"description":"`data` is the stored Journey at version 1.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Journey"}}}]}}}},"403":{"description":"`feature_not_licensed`: a send node uses an onsite channel the licence lacks. Or `campaign requires approval`: the campaign is active and the caller is not an approver (a journey write would put new sends live unapproved)."},"404":{"description":"Campaign not found."},"422":{"description":"Validation failed; `data.issues` is a list of {node_id?, message, code?}. Besides the graph structure and node configs, save checks each node against the CDP: a send node's `contact_attribute` must be declared in the CDP contact-attribute registry with the channel's kind (issue `code: contact_attribute_undeclared`; an unreadable registry answers 503), a profile node in attribute mode may only write attributes declared on the campaign's entity type, a decide node's `items.catalog` must name an existing recommendation catalogue (matched exactly; a name that differs only in case gets a \"did you mean\" hint), and a webhook node's `success_when` must compile against `status`, `body` and its `response_mapping` keys. When the CDP cannot answer, the attribute and catalogue checks are skipped rather than failing the save.\n"}}}},"/campaign/api/v1/campaigns/{id}/journeys/draft":{"post":{"tags":["Journeys"],"summary":"Draft a journey from a natural-language description (AI)","description":"Embeds the tenant's catalogs (segments, active templates + channels, the campaign's offers, CDP signal names) into the prompt, validates the LLM's output with the exact save-time rules (structure, entry trigger, cron and the template, segment, event type, catalogue, network, purpose and attribute references), and returns the unsaved draft with any issues. Nothing is persisted.\n","parameters":[{"$ref":"#/components/parameters/CampaignId"},{"$ref":"#/components/parameters/PurposeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JourneyDraftRequest"}}}},"responses":{"200":{"description":"`data` is a JourneyDraftResponse (draft + issues).","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/JourneyDraftResponse"}}}]}}}},"404":{"description":"Campaign not found."},"429":{"$ref":"#/components/responses/AIRateLimited"},"502":{"description":"The LLM call failed or returned unusable output."}}}},"/campaign/api/v1/campaigns/{id}/journeys/{journeyId}":{"get":{"tags":["Journeys"],"summary":"Get one journey","parameters":[{"$ref":"#/components/parameters/CampaignId"},{"$ref":"#/components/parameters/JourneyId"}],"responses":{"200":{"description":"`data` is the Journey with live-run counts.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Journey"}}}]}}}},"404":{"description":"Campaign or journey not found."}}},"put":{"tags":["Journeys"],"summary":"Update a journey (bumps version)","description":"Every update bumps `version` and snapshots the new graph; runs entered on older versions keep executing their pinned snapshot. Check `live_runs_old_versions` in the response to warn operators.\n","parameters":[{"$ref":"#/components/parameters/CampaignId"},{"$ref":"#/components/parameters/JourneyId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JourneyRequest"}}}},"responses":{"200":{"description":"`data` is the stored Journey at the new version.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Journey"}}}]}}}},"403":{"description":"`campaign requires approval`: the campaign is active and the caller is not an approver (a journey write would put new sends live unapproved)."},"404":{"description":"Campaign or journey not found."},"422":{"description":"Validation failed; `data.issues` is a list of {node_id?, message}. The save runs the same checks as creating a journey (see `POST /campaign/api/v1/campaigns/{id}/journeys`).\n"}}},"delete":{"tags":["Journeys"],"summary":"Delete a journey","parameters":[{"$ref":"#/components/parameters/CampaignId"},{"$ref":"#/components/parameters/JourneyId"}],"responses":{"200":{"description":"Journey deleted (finished runs cascade).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"404":{"description":"Campaign or journey not found."},"409":{"description":"Journey has live runs; exit them first."}}}},"/campaign/api/v1/campaigns/{id}/journeys/{journeyId}/activate":{"post":{"tags":["Journeys"],"summary":"Turn a journey on","description":"Flips `is_active` WITHOUT bumping the journey version — a toggle is not an edit to the graph, and a bump would strand every live run on the previous snapshot.\n","parameters":[{"$ref":"#/components/parameters/CampaignId"},{"$ref":"#/components/parameters/JourneyId"}],"responses":{"200":{"description":"Now active.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"403":{"description":"`campaign requires approval`: the campaign is active and the caller is not an approver (a journey write would put new sends live unapproved)."},"404":{"description":"Campaign or journey not found."},"409":{"description":"Already active."}}}},"/campaign/api/v1/campaigns/{id}/journeys/{journeyId}/deactivate":{"post":{"tags":["Journeys"],"summary":"Turn a journey off","description":"Stops the journey being enrolled into. Live runs are NOT exited — the engine simply stops picking the journey up, so a run parked on a wait node resumes if the journey is turned back on. Version is untouched.\n","parameters":[{"$ref":"#/components/parameters/CampaignId"},{"$ref":"#/components/parameters/JourneyId"}],"responses":{"200":{"description":"Now inactive.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"404":{"description":"Campaign or journey not found."},"409":{"description":"Already inactive."}}}},"/campaign/api/v1/campaigns/{id}/journeys/{journeyId}/rearm":{"post":{"tags":["Journeys"],"summary":"Let a spent immediate/planned journey enrol again","description":"Clears `entry_armed_at`/`entry_fired_at`, which is what stops a fires-once journey after its single enrolment. Deliberately separate from activate: the journey never stopped being active, and re-arming re-enrols a WHOLE SEGMENT rather than flipping a switch.\nA `planned` journey whose `run_at` is already past is refused — re-armed it would look ready and then never fire, because a planned journey never fires late. Move `run_at` forward first.\n","parameters":[{"$ref":"#/components/parameters/CampaignId"},{"$ref":"#/components/parameters/JourneyId"}],"responses":{"200":{"description":"Re-armed; it will enrol on a following tick.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"403":{"description":"`campaign requires approval`: the campaign is active and the caller is not an approver (a journey write would put new sends live unapproved)."},"404":{"description":"Campaign or journey not found."},"409":{"description":"The trigger enrols repeatedly (nothing to re-arm), it has not enrolled yet, or a planned run_at is in the past.\n"}}}},"/campaign/api/v1/journeys/webhook/test":{"post":{"tags":["Journeys"],"summary":"Render (and optionally send) an action node's request","description":"The \"Call system\" node's own test, in **either mode**. It dispatches on `config.mode` exactly as the journey engine does: an inline node's own URL/headers/body, or the request the node's registered **system** builds from the node's rendered parameters.\n\nIt does not replace `/systems/{id}/test` (a token-endpoint probe) or `/systems/{id}/preview` (an arbitrary request for that system): those answer for the SYSTEM. This answers for the NODE — its parameters, its run state, and its `response_mapping` and `success_when` applied to the answer, which is what the journey branches on and what neither of the other two can see.\n\nThe config is taken from the BODY, not from a stored journey: the question is asked while the node is being typed. It is validated with the same rules a save applies (422 on anything a save would refuse).\n\n`execute` is off by default — the endpoint on the other side cannot tell a test from a real action. Rendering needs no egress and works in every outbound mode; executing passes the Environments outbound gate (409 in `off`) and dials through the same SSRF guard and private network resolution a run would use.\n\nA transport failure (DNS, refused, timeout, blocked by the guard) is the ANSWER, not a server fault: it rides a 200 with `error` set and `success: false` — the branch the run would take.\n\nAuthorization: `campaign_editor`, `campaign_admin`, `engineer`, `admin`.\n","parameters":[{"$ref":"#/components/parameters/PurposeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["config"],"properties":{"config":{"type":"object","additionalProperties":true,"description":"The webhook node's config object, exactly as the graph stores it — inline (url, method, headers, body, timeout_sec, network_id) or system (mode, system_id, params), plus response_mapping/success_when either way.\n"},"profile_id":{"type":"string","description":"Renders {{.Profile.*}} against a real profile. The caller's X-Purpose is forwarded, so the CDP's purpose and PII gates apply — a test cannot show data the caller may not read.\n"},"state":{"type":"object","additionalProperties":true,"description":"Seeds {{.Run.State.*}}, so a node reading an earlier node's output is testable without walking the journey to it.\n"},"execute":{"type":"boolean","default":false,"description":"Actually perform the request."}}}}}},"responses":{"200":{"description":"`data` is `{request, executed, status, duration_ms, body, success, mapped, mapping_note, error}`. Only `request` is present on a render; `success` is the `success_when` verdict.\n","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WebhookProbeResponse"}}}]}}}},"400":{"description":"The request could not be rendered: a broken template, or — in system mode — a required parameter the node does not supply.\n"},"404":{"description":"The node names a system that does not exist, or the `profile_id` names no profile (`profile not found`)."},"409":{"description":"The tenant's outbound mode forbids egress."},"422":{"description":"The node config is invalid — the same message a save returns, including a `success_when` that does not compile against `status`, `body` and the `response_mapping` keys."},"502":{"description":"The CDP profile read failed; the message is the fixed `CDP unavailable`."},"503":{"description":"Sending test requests is not configured on this server."}}}},"/campaign/api/v1/journeys/{id}/enter":{"post":{"tags":["Journeys"],"summary":"Enroll one profile (manual / api trigger)","parameters":[{"$ref":"#/components/parameters/JourneyIdTop"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnterJourneyRequest"}}}},"responses":{"201":{"description":"`data` is the created JourneyRun at the entry node.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/JourneyRun"}}}]}}}},"400":{"description":"Invalid payload, the profile does not exist in the CDP, or the profile is of another entity type than the entry's (the request's `entity_type` when given, else the campaign's). The profile check runs under the Campaign service's own access and the instance's batch purpose (the purpose the journey reads the profile with), not the caller's purpose.\n"},"404":{"description":"Journey not found."},"409":{"description":"Journey/campaign not active, or the profile's PERSON already has a live run (entered for this or any other member) or is inside the re-entry cooldown.\n"},"503":{"description":"The CDP could not answer the profile check (\"profile check unavailable; try again\"), or the profile's person could not be resolved (\"person resolution unavailable\"); runs are unique per person, so the entry is refused rather than guessed. Retry. When the CDP refuses the Campaign service's own access to the profile check, the message says so instead (\"not permitted for the campaign service\") and retrying does not help: an administrator must fix the service's access.\n"}}}},"/campaign/api/v1/journeys/{id}/runs":{"get":{"tags":["Journeys"],"summary":"List a journey's runs (monitor)","description":"Paginated, newest first. `page.total` SATURATES at 10000: the exact total used to be a window count that read every run of the journey on every page load (and spilled to disk past a few hundred thousand), which a journey with millions of runs makes untenable. Use the returned row count against `size` to decide whether another page exists — that stays correct past the cap.\n","parameters":[{"$ref":"#/components/parameters/JourneyIdTop"},{"name":"status","in":"query","schema":{"type":"string","enum":["running","waiting","completed","exited","failed"]}},{"name":"profile_id","in":"query","description":"Restrict to one profile — the \"what happened to this customer\" lookup.","schema":{"type":"string","format":"uuid"}},{"name":"filter","in":"query","description":"A querybuilder tree over the campaign's entity, resolved to profile ids through the CDP before the runs are read (runs are held by Campaign; customer data is not). The same grammar segments and campaign audiences use, so `identifier.email` and `profile.tier` both work. ANDed with `profile_id` when both are given.\n\nA filter matching more than 1000 profiles is REFUSED with 422 rather than truncated: a truncated list looks like a complete answer, and \"this customer has no run\" is exactly the wrong conclusion to draw from one.\n","schema":{"type":"string"}},{"name":"page","in":"query","schema":{"type":"integer","minimum":0,"default":0}},{"name":"size","in":"query","description":"Omitted (or 0) means this endpoint's default of 50; 100 is the cap.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}],"responses":{"200":{"description":"`data` is a list of JourneyRun, newest first, with page metadata.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/JourneyRun"}}}}]}}}},"404":{"description":"Journey not found."},"422":{"description":"The profile filter was rejected by the CDP, or matches too many profiles."}}}},"/campaign/api/v1/journeys/{id}/runs/{runId}":{"get":{"tags":["Journeys"],"summary":"Get one run (state inspector)","parameters":[{"$ref":"#/components/parameters/JourneyIdTop"},{"$ref":"#/components/parameters/RunId"}],"responses":{"200":{"description":"`data` is the JourneyRun.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/JourneyRun"}}}]}}}},"404":{"description":"Journey or run not found."}}}},"/campaign/api/v1/journeys/{id}/runs/{runId}/exit":{"post":{"tags":["Journeys"],"summary":"Force-exit a live run (kill switch)","parameters":[{"$ref":"#/components/parameters/JourneyIdTop"},{"$ref":"#/components/parameters/RunId"}],"responses":{"200":{"description":"Run exited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"404":{"description":"Journey or run not found."},"409":{"description":"Run is not live (already finished)."}}}},"/nba/health":{"get":{"tags":["Health"],"summary":"Health check (NBA service)","description":"Served by the separate NBA service on its own port (default 2610), not by the Campaign service.\n","security":[],"responses":{"200":{"description":"Service healthy.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}}}}},"/nba/api/v1/campaigns/{id}/decide":{"post":{"tags":["Next best action"],"summary":"Next-Best-Action decide","description":"Served by the NBA service (default port **2610**, not 2600). Ranks the\ncampaign's active offers — or, when the request names a `catalog_id` or\nthe campaign has one configured as its default offer source, that\ncatalogue's — for one profile: eligibility segment →\neligibility expression → live CDP consent check → frequency cap\n(campaign_touch ledger + short-lived burst dedup) → score by\n`score_signal` (priority tie-break) → top N. A `decisioned`\ncampaign_touch event is logged per returned offer (unless test_mode),\ncarrying `campaign_id` (who decided) and, when the offer came from a\nshared catalogue, `catalog_id` (which pool it came from).\n\nDecide-only by design: it never queues a send. Requires an active\ncampaign unless `test_mode` is set. Include `X-Purpose` when the CDP\nruns in strict privacy mode — it is forwarded to every CDP read.\n","parameters":[{"$ref":"#/components/parameters/CampaignId"},{"$ref":"#/components/parameters/PurposeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DecideRequest"}}}},"responses":{"200":{"description":"Ranked offers with per-offer exclusion reasons.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Decision"}}}]}}}},"400":{"description":"Invalid body."},"404":{"description":"Campaign or profile not found (erased profiles surface here)."},"409":{"description":"Campaign is not active (use test_mode to dry-run). This covers an automatically `stopped` campaign too — a campaign that reached a stop condition decides nothing more, which for an inbound_offer campaign is the enforcement point, since it has no dispatch of its own.\n"},"502":{"description":"A CDP request failed; the message is the fixed `CDP unavailable`."},"503":{"description":"The licence snapshot has not loaded yet (the process just started, or its control-plane poll has never succeeded)."}}}},"/nba/api/v1/offer-catalogs/{id}/decide":{"post":{"tags":["Next best action"],"summary":"Catalogue-only Next-Best-Action decide","description":"Served by the NBA service (default port **2610**). Ranks a shared\noffer catalogue's active offers for one profile with NO campaign\nanywhere in the flow — decision-as-a-service over the catalogue. The\npipeline is the campaign decide's, with the campaign's inputs\nreplaced: the entity type comes from the catalogue, only each offer's\nGLOBAL frequency cap applies (no campaign cap; the per-channel limit\ncounts only when `channel` is supplied), consent gates on the offer's\nown purpose alone (`{channel}` purposes need the request `channel` or\nfail closed), fatigue runs with the catalogue's entity type and the\nrequest channel, and control groups — including the entity's global\nholdout — do not apply. A `decisioned` campaign_touch is logged per\nreturned offer (unless test_mode) carrying `catalog_id` (+ `channel`\nwhen supplied) instead of `campaign_id`.\n\nUnlike a campaign's catalogue decide (empty decision, never an error),\na missing catalogue here is a 404 and an inactive one a 409 — there is\nno pinned journey run to protect on a direct call. Requires an active\ncatalogue unless `test_mode` is set. Include `X-Purpose` when the CDP\nruns in strict privacy mode.\n","parameters":[{"$ref":"#/components/parameters/CatalogId"},{"$ref":"#/components/parameters/PurposeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogDecideRequest"}}}},"responses":{"200":{"description":"Ranked offers with per-offer exclusion reasons (`data.catalog_id` set, no `campaign_id`).","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Decision"}}}]}}}},"400":{"description":"Invalid body (bad profile_id, unknown channel)."},"404":{"description":"Offer catalogue or profile not found (erased profiles surface here)."},"409":{"description":"Offer catalogue is not active (use test_mode to dry-run)."},"502":{"description":"A CDP request failed; the message is the fixed `CDP unavailable`."},"503":{"description":"The licence snapshot has not loaded yet (the process just started, or its control-plane poll has never succeeded)."}}}},"/campaign/api/v1/systems/catalog":{"get":{"tags":["External systems"],"summary":"External-system form definition","description":"The config/credential field schema for an external system (the webhook http fields plus required_consent_purpose / timeout_sec / retry).\n","responses":{"200":{"description":"`data` is a one-element list of ChannelProviderSpec.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ChannelProviderSpec"}}}}]}}}}}}},"/campaign/api/v1/systems":{"get":{"tags":["External systems"],"summary":"List external systems","description":"Registered HTTP integrations journey action nodes call. Never returns channel providers, and never credential values.\n","responses":{"200":{"description":"`data` is a list of ChannelProvider with kind=system.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ChannelProvider"}}}}]}}}}}},"post":{"tags":["External systems"],"summary":"Register an external system","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalSystemRequest"}}}},"responses":{"201":{"description":"Created; `data` is the ChannelProvider.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ChannelProvider"}}}]}}}},"400":{"description":"Invalid config (no url, bad method/auth/retry, unparsable template, or a literal private, loopback, link-local, CGNAT or metadata host in config.url / config.auth.token_url with no network_id; loopback always, other private ranges unless your platform operator has allowed them; templated hosts are checked when dialled)."},"409":{"description":"A provider or system with that name already exists."},"503":{"description":"Credential encryption is not configured on this instance but credentials were sent."}}}},"/campaign/api/v1/systems/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"tags":["External systems"],"summary":"Get one external system","responses":{"200":{"description":"`data` is the ChannelProvider.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ChannelProvider"}}}]}}}},"404":{"description":"Not found (a channel provider id answers 404 here too)."}}},"put":{"tags":["External systems"],"summary":"Update an external system","description":"A URL equal to the stored one is re-checked against the private-address rule only when the system is being activated, so a system saved before the check existed can still be deactivated.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalSystemRequest"}}}},"responses":{"200":{"description":"`data` is the updated ChannelProvider.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ChannelProvider"}}}]}}}},"400":{"description":"Invalid config, including a literal private, loopback, link-local, CGNAT or metadata host in config.url / config.auth.token_url (see POST /systems)."},"404":{"description":"Not found."},"409":{"description":"Name already taken, OR `credentials_required`: the update changes `url`, an `auth` target or `network_id` while omitting `credentials`.\n","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/GenericResponse"},{"$ref":"#/components/schemas/CredentialsRequiredResponse"}]}}}}}},"delete":{"tags":["External systems"],"summary":"Delete an external system","description":"Refused while a live journey definition still binds an action node to it — deactivate instead to stop calls immediately without breaking the graphs. Past graph VERSIONS are not consulted: a run pinned to an old snapshot that names a deleted system fails that node permanently with a clear reason.\n","responses":{"200":{"description":"Deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"404":{"description":"Not found."},"409":{"description":"In use by one or more journeys."}}}},"/campaign/api/v1/systems/{id}/test":{"post":{"tags":["External systems"],"summary":"Live connection test for one external system","description":"Probes the OAuth2 token endpoint where that scheme is configured. Otherwise a fixed endpoint URL gets a TCP connect only through the SSRF guard (\"endpoint reachable (TCP connect only, no request sent)\"; a blocked destination fails naming the guard) and a templated or empty URL reports config validity only. No request is sent to an arbitrary endpoint — a real request may be a real action.\n","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"`data` is a ChannelProviderTestResult (success may be false).","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ChannelProviderTestResult"}}}]}}}},"404":{"description":"Not found."},"409":{"description":"The tenant's outbound mode is `off` (Environments); probes stay allowed in `sink`."},"503":{"description":"Stored credentials but credential encryption is not configured on this instance."}}}},"/campaign/api/v1/destinations":{"get":{"tags":["Destinations"],"summary":"List activation destinations","responses":{"200":{"description":"Destinations (has_credentials only, never secrets).","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Destination"}}}}]}}}}}},"post":{"tags":["Destinations"],"summary":"Create an activation destination","description":"Connects one ad-platform account (google_ads first). Credentials are AES-256-GCM encrypted at rest.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DestinationRequest"}}}},"responses":{"201":{"description":"Destination created.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Destination"}}}]}}}},"400":{"description":"Unsupported platform / missing account_ref or credentials."},"409":{"description":"Duplicate name."},"503":{"description":"Credential encryption not configured."}}}},"/campaign/api/v1/destinations/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"tags":["Destinations"],"summary":"Get a destination","responses":{"200":{"description":"Destination.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Destination"}}}]}}}},"404":{"description":"Not found."}}},"put":{"tags":["Destinations"],"summary":"Update a destination","description":"platform is immutable. Omit credentials to keep the stored secrets; send a full credential map to replace them. Omitting `config` (or sending `null`) keeps the stored config; `{}` clears it. Changing `account_ref`, `login_customer_id` or `api_version` without `credentials` answers 409 `credentials_required`.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DestinationRequest"}}}},"responses":{"200":{"description":"Updated destination.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Destination"}}}]}}}},"400":{"description":"Validation failed (incl. platform change)."},"404":{"description":"Not found."},"409":{"description":"Name already taken, OR `credentials_required`: the update changes `account_ref`, `login_customer_id` or `api_version` while omitting `credentials`.\n","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/GenericResponse"},{"$ref":"#/components/schemas/CredentialsRequiredResponse"}]}}}}}},"delete":{"tags":["Destinations"],"summary":"Delete a destination","description":"Its audience syncs, runs and membership snapshots are removed with it (CASCADE). Remote audiences on the ad platform are left as-is.\n","responses":{"200":{"description":"Deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"404":{"description":"Not found."}}}},"/campaign/api/v1/destinations/{id}/test":{"post":{"tags":["Destinations"],"summary":"Test a destination connection","description":"Live, non-destructive credential + reachability check (google_ads: OAuth token mint + a trivial GAQL query). Mutates no remote audience.\n","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Test outcome (check data.success).","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"}}}}}]}}}},"404":{"description":"Not found."},"409":{"description":"The tenant's outbound mode is `off` (Environments); probes stay allowed in `sink`."},"503":{"description":"Credential encryption not configured."}}}},"/campaign/api/v1/audiences":{"get":{"tags":["Audiences"],"summary":"List audience syncs","parameters":[{"name":"destination_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Audience syncs.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AudienceSync"}}}}]}}}}}},"post":{"tags":["Audiences"],"summary":"Create an audience sync","description":"Mirrors a segment to a remote ad-platform audience. Created inactive by default; activate to let the scheduler run it (or trigger manually). Validates the destination, segment, match_keys grammar, sync_mode, cron and consent_purpose (against the CDP catalog, best-effort).\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AudienceSyncRequest"}}}},"responses":{"201":{"description":"Audience sync created.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AudienceSync"}}}]}}}},"400":{"description":"Validation failed."},"409":{"description":"Duplicate name."}}}},"/campaign/api/v1/audiences/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"tags":["Audiences"],"summary":"Get an audience sync","responses":{"200":{"description":"Audience sync.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AudienceSync"}}}]}}}},"404":{"description":"Not found."}}},"put":{"tags":["Audiences"],"summary":"Update an audience sync","description":"destination_id is immutable — create a new sync to re-home it. The update re-anchors the cron schedule (first firing after the edit).\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AudienceSyncRequest"}}}},"responses":{"200":{"description":"Updated audience sync.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AudienceSync"}}}]}}}},"400":{"description":"Validation failed (incl. destination change)."},"404":{"description":"Not found."},"409":{"description":"Duplicate name."}}},"delete":{"tags":["Audiences"],"summary":"Delete an audience sync","description":"Stops mirroring; runs + membership snapshot die with it. The remote audience is left as-is on the ad platform.\n","responses":{"200":{"description":"Deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"404":{"description":"Not found."}}}},"/campaign/api/v1/audiences/{id}/sync":{"post":{"tags":["Audiences"],"summary":"Trigger an audience sync run now","description":"Claims an immediate manual run and executes it in the background. Poll GET /audiences/{id}/runs for the outcome.\n","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"202":{"description":"Run claimed and queued.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AudienceSyncRun"}}}]}}}},"404":{"description":"Not found."},"409":{"description":"A run for this second is already claimed."},"503":{"description":"Audience syncer is not running."}}}},"/campaign/api/v1/audiences/{id}/runs":{"get":{"tags":["Audiences"],"summary":"List an audience sync's runs","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":20}}],"responses":{"200":{"description":"Newest runs first.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AudienceSyncRun"}}}}]}}}},"404":{"description":"Not found."}}}}}}