{"openapi":"3.0.3","info":{"title":"Optima Edge — public API","version":"0.1.0","description":"The PUBLIC surface of Optima Edge (the gateway role) — the\nendpoint web and mobile SDKs talk to. It is served from the DMZ tier,\nwhich holds no data-plane credentials and no secrets; everything it\naccepts is capped, allowlisted, and rate-limited.\n\n**Authentication**: every `/edge/v1/*` request carries the `X-Edge-Key`\nheader with a public `oek_…` SDK key. The key is not a secret — it\nidentifies configuration (platform, origin allowlist, rate limit) and\ngrants access to nothing but this surface. For `platform=web` keys the\nactual request's `Origin` must be in the key's allowlist; mobile keys\nhave no Origin and skip the check (rate limits and payload caps are the\neffective control there). **Same-origin exception**: a request whose\n`Origin` is exactly this gateway's own `scheme://host` is always\nadmitted regardless of the key's allowlist — `Origin` is browser-set and\nunforgeable cross-site, so this only ever matches a first-party fetch\nfrom a page the gateway itself served. It exists for the hosted form\npage (`GET /edge/v1/pages/{token}/{slug}`)'s inline submit script, which\nposts back to this same host and has nothing to do with the operator's\ncustomer-site `AllowedOrigins` list.\n\n**CORS**: preflight is answered permissively for the whole surface —\n`OPTIONS /edge/v1/*` returns `204` with the requesting `Origin`\nreflected, `Access-Control-Allow-Methods: GET, POST, OPTIONS`,\n`Access-Control-Allow-Headers: X-Edge-Key, Content-Type` and\n`Access-Control-Max-Age: 600`. It is not listed as an operation below\nbecause OpenAPI has no wildcard path template. A preflight cannot see\nheader values, so allowlisting happens on the actual request: an origin\nmismatch is `403` **without** `Access-Control-Allow-Origin`, so browsers\nalso block the response. Allowed responses also carry\n`Access-Control-Expose-Headers: ETag, Retry-After` so a browser client\ncan read the revalidation tag and the backoff hint.\n\n**Rate limiting**: per-IP (default 600/min; the\n`edge_ip_rpm` instance setting at 0 turns it off) and per-key\n(default 6000/min, per-key override) minute buckets.\n`429` responses carry `Retry-After` seconds.\n\n**Ingest** (`POST /edge/v1/track|identify|consent`): fire-and-forget with\nin-band feedback. `202` means the request was durably queued for processing\n(acceptance is the durability point); `503` + `Retry-After` means it was NOT\n— the SDK's client-side retry queue re-sends (the gateway never buffers).\nInput hard caps REJECT, never truncate: a body over 64KB\nor more than the per-request hit limit (default 20,\nnever below 20) is `413`, and the SDKs halve the batch and retry; > 50\nprops/hit, keys > 128 chars, string values > 4KB, props values other than\nscalar-or-string-array, a `device_id` not matching `^[A-Za-z0-9_-]{8,64}$`\nand unknown JSON fields are `400`. Only unknown categories and duplicate\nmessage ids are per-hit drops reported in the 202 body. Consent is\nSDK-declared and edge-enforced: in `consent_mode=require`, hits not\ndeclaring the required purposes are dropped with reason `missing_consent`.\nThe `consent` block may additionally carry an external CMP's own signal (an\nIAB TCF string, a Google Consent Mode state, or vendor keys); when the\noperator has enabled `cmp_mode`, the 202 body gains one request-level\n`consent: {status}` object saying what became of it — a CMP problem is never\na per-hit drop. In `cmp_mode=enforce` the decoded signal REPLACES the\ndeclared `purposes` (see `ConsentDeclaration`), so a banner refusal of a\nrequired purpose is what produces the `missing_consent` drops.\n\nThis spec is deliberately separate from the CDP's `oapi3.yml`: the admin\nAPI that CONFIGURES edge lives there under `/cdp/api/v1/edge/*`.\n"},"tags":[{"name":"Health","description":"Public liveness probe."},{"name":"Tracking","description":"Event tracking, identify, and the managed tags (trackers) a site loads."},{"name":"Consent","description":"Consent declarations from a site's banner or an app."},{"name":"Content","description":"Published content items, onsite campaign content and its interaction events, and public asset and file links."},{"name":"Next best action","description":"Reporting how a visitor responded to a next-best-action offer."},{"name":"Forms","description":"Web forms, hosted form pages, and double opt-in confirmation."},{"name":"Preferences","description":"The preference centre and one-click unsubscribe."},{"name":"Delivery receipts","description":"Delivery and engagement receipts posted back by messaging providers."},{"name":"Email tracking","description":"Email click and open tracking links."},{"name":"Shortlinks","description":"Short links minted for campaign messages."},{"name":"Web SDK","description":"The Web SDK bundle served from the gateway."}],"components":{"securitySchemes":{"EdgeKey":{"type":"apiKey","in":"header","name":"X-Edge-Key","description":"Public SDK key ('oek_' + 32 base62 chars), created via the CDP admin API. Web keys additionally require a browser origin: the request's Origin header must be one of the key's allowed_origins (full origin, scheme://host[:port], exact match) or the gateway's own origin. A same-origin GET carries no Origin header at all, so when Origin is absent two other browser-set headers are accepted as the same proof: `Sec-Fetch-Site: same-origin` (sent to secure contexts only) or a Referer whose origin is the gateway's own. A missing Origin with neither is rejected with 403."}},"schemas":{"AckResponse":{"type":"object","description":"Bare acknowledgement. Edge does not use the CDP's response envelope — these endpoints answer providers and mail clients, not API callers.\n","properties":{"status":{"type":"string","enum":["ok","accepted"]}},"required":["status"]},"EdgeError":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"message":{"type":"string","description":"Reason phrase. 5xx responses never include internal detail."}}},"ContentItem":{"type":"object","description":"The shared rendering contract all Edge surfaces use. Structured items\ncarry `payload` (operator-authored JSON); unstructured items carry\n`html` (a raw HTML/CSS/JS document, loaded as is). Personalized items\narrive already rendered server-side — the operator-authored template\ndecides exactly what appears; non-personalized items are served\nexactly as published. Published content is visible to anyone holding\nthe public SDK key (plus, for personalized items, that device's\ntemplate-selected data).\n","properties":{"id":{"type":"string","description":"Item id (operator items — uuid; campaign items — the entitlement token)."},"type":{"type":"string","description":"Rendering hint (operator items — banner | inline | custom | banner_consent; campaign items — the channel name)."},"format":{"type":"string","enum":["structured","unstructured"]},"payload":{"type":"object","description":"Operator-authored JSON (structured items; personalized string values pre-rendered). Campaign web_personalization items carry modifications:[selector, op, value?, attr?] — set_attr's attr is restricted to href, src, srcset, alt, title, class, id, value, placeholder, data-*, aria-* (event handlers, style, srcdoc and form targets are refused at save and, for a row saved before that rule existed, dropped at serve time), and a rendered href/src/srcset value must be a relative reference or one of http:, https:, mailto:, tel: — a scheme outside that set drops the modification, the rest of the item still serves; mobile_inapp items title?/body/image_url?/cta_label?/cta_url?/data?. For a kind=items item this is the item's rendered `template` (with `{{range .Items}}` resolved against the ranked recommendation rows) — never the raw {kind, catalog, strategy, count, template} envelope. For a banner_consent item this is the stored banner definition plus `purpose_details` — see ConsentBannerPayload."},"html":{"type":"string","description":"The HTML/CSS/JS document (unstructured items; pre-rendered when personalized)."},"priority":{"type":"integer","description":"Items are ordered by priority desc (campaign items carry 0 and follow operator items)."},"origin":{"type":"string","enum":["campaign"],"description":"Present on campaign-delivered items only."},"channel":{"type":"string","enum":["web_banner","web_personalization","mobile_inapp"],"description":"Campaign items only."},"token":{"type":"string","description":"Campaign items only — echo it back with impression/click/dismiss events."},"display":{"type":"object","description":"Campaign items only — the variant's display governance. dismissible: draw a close control; max_impressions: the server stops serving after this many impressions (0 = unlimited); stop_on_click: a click ends the entitlement. mobile_inapp items also carry placement (always: overlay = drawn by the app's OptimaHost in a native frame, served on the __overlay slot; inline = drawn by the OptimaSlot named in the request, served only on that slot), and position/style when the template sets them (the overlay frame: card inset from the edges, bar edge to edge, modal centred over a dimmed backdrop). An HTML in-app message is served with format unstructured and its document in html.","properties":{"dismissible":{"type":"boolean"},"max_impressions":{"type":"integer"},"stop_on_click":{"type":"boolean"},"placement":{"type":"string","enum":["overlay","inline"]},"position":{"type":"string","enum":["top","bottom","center"]},"style":{"type":"string","enum":["card","bar","modal"]}}}}},"ContentResponse":{"type":"object","properties":{"slot":{"type":"string"},"items":{"type":"array","items":{"$ref":"#/components/schemas/ContentItem"}}}},"TrackerEntry":{"type":"object","description":"Public tracker-inventory wire shape. Deliberately does not carry\n`id`/timestamps — those are admin-API concerns. `kind`, `config` and\n`url_patterns` (since 1.1) describe a MANAGED tag the SDK runs itself\n(the tag manager); an SDK ≤ 1.0.x ignores them and treats\nevery row as `page`.\n","required":["name","description","purpose","kind","config","url_patterns"],"properties":{"name":{"type":"string"},"description":{"type":"string"},"purpose":{"type":"string","description":"The consent purpose name this tracker's collection maps to."},"kind":{"type":"string","enum":["page","script","pixel","html"]},"config":{"type":"object","description":"Kind-specific body: page `{}`; script `{src, async?, defer?, attributes?}`; pixel `{src}` with `{{ts}}`/`{{url}}` macros; html `{html}`. html bodies are served verbatim to every holder of the tenant's public SDK key, so they must never contain secrets."},"url_patterns":{"type":"array","items":{"type":"string"},"description":"path.Match globs against the full page URL without the fragment (`*` never crosses `/`); empty = every page."}}},"TrackersResponse":{"type":"object","properties":{"trackers":{"type":"array","items":{"$ref":"#/components/schemas/TrackerEntry"}}}},"EdgeFormField":{"type":"object","properties":{"key":{"type":"string","description":"The target's key: an attribute key, an identifier key, or a consent purpose name."},"kind":{"type":"string","enum":["attribute","identifier","consent"]},"input_type":{"type":"string","enum":["text","email","phone","number","checkbox","select","textarea","hidden"]},"label":{"type":"string","description":"Resolved label — Labels[lang] when the request named a language and an override exists, else the field's default label."},"placeholder":{"type":"string"},"required":{"type":"boolean"},"options":{"type":"array","description":"select options only.","items":{"type":"object","properties":{"value":{"type":"string"},"label":{"type":"string"}}}}}},"EdgeForm":{"type":"object","description":"The public rendering of one published web form.","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"lang":{"type":"string","description":"The language the labels resolved against (the request's ?lang=, possibly empty)."},"fields":{"type":"array","items":{"$ref":"#/components/schemas/EdgeFormField"}},"nonce":{"type":"string","description":"Sealed, scoped to (tenant, form); required unchanged on POST /edge/v1/forms/{id}/submit."},"min_submit_interval_sec":{"type":"integer","description":"The minimum render-to-submit interval below which a submission is treated as automated."},"success_message":{"type":"string"},"success_redirect_url":{"type":"string"},"double_opt_in":{"type":"boolean"},"submit_url":{"type":"string","description":"Relative path: /edge/v1/forms/{id}/submit."}}},"FormSubmitRequest":{"type":"object","required":["nonce"],"additionalProperties":false,"description":"At least one identifier field must resolve to a value, or `device_id` must be set — otherwise there is nothing to attach the submission to (`400 no identifier to attach to`).\n","properties":{"device_id":{"type":"string","pattern":"^[A-Za-z0-9_-]{8,64}$","description":"Optional SDK device id. When set, the submission attaches to (or creates) this device's profile even if no identifier field was submitted."},"nonce":{"type":"string","description":"The `nonce` from the render this submission answers, unchanged — scoped to (tenant, form), and the clock start for `min_submit_interval_sec`."},"lang":{"type":"string","description":"Echoed onto the resulting write for downstream template/language selection; not validated against the render's ?lang=."},"fields":{"type":"object","maxProperties":64,"description":"Target key → raw value, one entry per rendered field, plus the hidden honeypot key `_hp` (must stay empty or the submission is rejected). Checkbox/consent fields accept a boolean or \"true\"/\"on\"/\"false\"/\"off\"; number fields accept a JSON number or a numeric string; select fields must match one of the field's option values; everything else is a string ≤ 4096 characters (regex-validated when the field declares one). A key that names a real field but was elided from this render (progressive profiling or the `max_fields` cap) or that names no field on the form at all is dropped rather than rejecting the whole submission — see `FormSubmitResponse.dropped`.\n"},"assertion":{"$ref":"#/components/schemas/IdentityAssertion"}}},"FormSubmitResponse":{"type":"object","properties":{"accepted":{"type":"boolean"},"dropped":{"type":"array","description":"Per-field feedback for submitted keys that were not admitted.","items":{"type":"object","properties":{"key":{"type":"string"},"reason":{"type":"string","description":"not_asked (the key names a real field on the form, but it was elided from this render by progressive profiling or the max_fields cap) | not_in_form (the key names no field on the form at all)."}}}},"double_opt_in":{"type":"boolean","description":"The form's configured double_opt_in flag","echoed back — true means a confirmation message rather than activating any submitted consents immediately.":null}}},"ContentEventsRequest":{"type":"object","required":["events"],"additionalProperties":false,"properties":{"events":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"object","required":["token","action"],"properties":{"token":{"type":"string","pattern":"^[0-9A-Za-z]{32}$","description":"The campaign item's entitlement token from GET /edge/v1/content."},"action":{"type":"string","enum":["impression","click","dismiss"]},"ts":{"type":"integer","format":"int64","description":"Client timestamp (ms) — diagnostics only."}}}}}},"NBAResponsesRequest":{"type":"object","description":"NBA response collection. Deliberately carries NO profile id: the gateway cannot verify a device→profile binding for a response the way it can for a tracked hit, and accepting a client-supplied one would let any caller claim any profile responded. An unknown `profile_id` field is rejected outright with a 400 rather than silently dropped. The Campaign service resolves the profile from its own short-lived cache of the decision (`nba_response_resolve_ttl_hours`, default 72h) — sound because an SDK reports a response seconds to minutes after its decide, orders of magnitude inside that window.\n","required":["events"],"additionalProperties":false,"properties":{"events":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"object","required":["nba_id","action"],"properties":{"nba_id":{"type":"string","description":"The 26-character id from the decide response's winning offer."},"action":{"type":"string","enum":["presented","accepted","postponed","rejected","realized"]},"reason":{"type":"string","maxLength":256,"description":"Caller-supplied code annotating the response (\"too_expensive\"). Optional."},"reference_id":{"type":"string","maxLength":256,"description":"The reporting system's own handle for the outcome. Optional."},"value":{"type":"number","description":"The outcome's monetary value, if any. Optional on every action."},"ts":{"type":"integer","format":"int64","description":"Client timestamp (epoch seconds) — diagnostics only."}}}}}},"ConsentDeclaration":{"type":"object","description":"The visitor's consent state as known to the SDK, attached per REQUEST\n(every hit in the batch inherits it).\n\n`purposes` is what the SDK itself declares — and **its absence is\nnot the same statement as its emptiness**:\n\n  - **no `purposes` key at all** (or an explicit `null`) means the\n    visitor has not decided yet. Under `consent_mode=optional` the\n    data is collected and stamped with the tenant's full configured\n    `collection_purposes` set, exactly as it always has been for a\n    client that declares nothing.\n  - **`purposes: []`** — the key present, the array empty — is an\n    EXPLICIT REFUSAL: the visitor was asked and said no to\n    everything (the Optima Web SDK sends exactly this after a\n    reject-all). Under `consent_mode=optional` the data is still\n    collected — optional means consent governs USE, not\n    collection — but it is stamped with NO purpose provenance,\n    never with the full collection set (the same outcome a\n    CMP-enforced empty granted set has). Under\n    `consent_mode=require` a refusal of a required purpose is\n    refused at the gateway with the per-hit reason\n    `missing_consent`; that is the mode for tenants who want a\n    refusal to mean \"collect nothing\".\n\nA client that has no consent state to report must therefore OMIT\n`purposes`, never send it empty.\n\nThe other three fields\ncarry an external Consent Management Platform's own signal verbatim —\nat most one is typically set, all three may be. They are read only\nwhen the operator has set `cmp_mode` to `observe` or `enforce`;\notherwise the signal is ignored (and the response carries no\n`consent` object). Decoding is authoritative on the server side: the\ngateway decodes far enough to answer you synchronously, the platform\nre-decodes and records the decision as `profile_consents` rows with a\nreceipt whose evidence is the raw signal below.\n\n**`cmp_mode: observe`** — `purposes` is used exactly as sent; the CMP\nsignal is only recorded and counted.\n\n**`cmp_mode: enforce`** — the CMP is the authority. When the signal\ndecodes, the purposes it maps to as GRANTED **replace** `purposes`\nwholesale for this request: an SDK that declares `marketing` while\nthe visitor's banner refused it collects nothing under `marketing`.\nThe substituted set is what `consent_mode=require` is checked\nagainst (so a refusal of a required purpose drops the whole batch\nwith `missing_consent`, and the refusal itself is still recorded),\nand what the stored data's purpose provenance is stamped with. A\npurpose the CMP grants but that is absent from `collection_purposes`\nis still not collected — substitution replaces the declaration, it\ndoes not widen what the tenant collects. A signal that grants NOTHING\nis read as a refusal, not as an absent declaration: whatever is still\ncollected is stamped with no purposes at all, never with the tenant's\nfull `collection_purposes` set.\n\nWhichever way a request ends, a CMP signal it carried is recorded\nwhenever `cmp_mode` is active for the tenant, the key is still valid\nthere, and the signal maps to at least one purpose — including when\nthe batch is dropped in full, when every hit is dropped as an unknown\ncategory or a duplicate, and when an identify request has everything\nfiltered out by its allowlists. A tenant whose configuration has the mode\noff, a key already revoked, or a signal\nthat maps to zero purposes records nothing.\n\n**Unparseable under `enforce`** — if the signal will not decode there\nis NO substitution: `purposes` stands and the request is handled as\nit would be with no CMP part at all (the response still says\n`consent.status = unparseable`). \"We could not read your banner's\nanswer\" is not the same statement as \"your banner said no\", and a\nbroken CMP integration must never silently narrow collection.\n\nCap violations are a 400 for the whole request — a signal that had to\nbe truncated is not evidence of anything.\n","properties":{"purposes":{"type":"array","maxItems":32,"items":{"type":"string","maxLength":128}},"tcf":{"type":"string","maxLength":4096,"description":"An IAB TCF v2.x TC string. Only the core segment (the part before\nthe first `.`) is decoded, and only its PurposesConsent and\nPurposesLITransparency bitfields — vendor ranges and publisher\nsegments are ignored. A string that will not decode does not cost\nyou any data: the hits are still accepted and the response says\n`consent.status = unparseable`.\n"},"gcm":{"type":"object","maxProperties":16,"additionalProperties":{"type":"string","enum":["granted","denied"],"maxLength":32},"description":"Google Consent Mode v2 state — the seven standard signals\n(ad_storage, analytics_storage, ad_user_data, ad_personalization,\nfunctionality_storage, personalization_storage,\nsecurity_storage). Key names are capped at 64 characters and\nvalues at 32; over-cap is a 400 for the whole request. Within the\ncaps, unknown keys and values other than granted/denied are\nskipped silently — the caps reject, the semantics skip.\n"},"keys":{"type":"object","maxProperties":64,"additionalProperties":{"type":"boolean"},"description":"Vendor-defined consent keys, name → granted. Names must be 1-64\ncharacters of `[a-z0-9_-]` to be decoded (over-64 names are\nrejected with a 400; other out-of-charset names are skipped).\nReachable from the operator's cmp_purpose_map as `key:<name>`.\n"}}},"ConsentSignalFeedback":{"type":"object","description":"Request-level answer about the CMP signal that was sent, present in a\n202 body ONLY when the request carried one AND `cmp_mode` is not\n`off`. The signal is per-request, so this is deliberately not a\nper-hit `dropped` entry — that would fabricate a granularity the\ninput does not have.\n","properties":{"status":{"type":"string","enum":["mapped","unparseable","unmapped"],"description":"`mapped` — decoded, and at least one Optima purpose came out of\nthe tenant's cmp_purpose_map. `unparseable` — the TCF part would\nnot decode; the request was still accepted in full, and the raw\nsignal is still recorded, keeping whatever\nthe GCM/vendor-key parts decoded to. `unmapped` — the signal\ndecoded but produced no Optima purpose at all (no token matched\ncmp_purpose_map, or nothing decodable was in it): the mapping or\nthe signal is misconfigured, NOT the visitor denying anything.\n"}}},"TrackRequest":{"type":"object","required":["device_id","hits"],"additionalProperties":false,"properties":{"device_id":{"type":"string","pattern":"^[A-Za-z0-9_-]{8,64}$","description":"SDK-generated, client-persisted device identifier."},"sent_at":{"type":"string","format":"date-time","description":"SDK send time — used server-side for clock-skew correction of hit timestamps."},"consent":{"$ref":"#/components/schemas/ConsentDeclaration"},"hits":{"type":"array","minItems":1,"maxItems":20,"items":{"$ref":"#/components/schemas/TrackHit"}}}},"TrackHit":{"type":"object","required":["message_id","category"],"additionalProperties":false,"properties":{"message_id":{"type":"string","pattern":"^[A-Za-z0-9_-]{8,64}$","description":"SDK-generated unique id (UUID recommended) — the dedup key for retry storms."},"category":{"type":"string","maxLength":128,"description":"Semantic category; must be mapped by the operator or the hit is dropped as unknown_category."},"name":{"type":"string","maxLength":4096},"ts":{"type":"string","format":"date-time","description":"Client-clock event time; skew-corrected and clamped server-side."},"context":{"type":"object","additionalProperties":false,"properties":{"url":{"type":"string","maxLength":4096},"referrer":{"type":"string","maxLength":4096},"title":{"type":"string","maxLength":4096},"language":{"type":"string","maxLength":4096},"screen_w":{"type":"integer"},"screen_h":{"type":"integer"},"ua":{"type":"string","maxLength":4096}}},"props":{"type":"object","maxProperties":50,"description":"Custom fields (JSON scalars or arrays of strings only). Stored ONLY where the category mapping maps them."}}},"TrackResponse":{"type":"object","properties":{"accepted":{"type":"integer"},"dropped":{"type":"array","items":{"type":"object","properties":{"message_id":{"type":"string"},"reason":{"type":"string","description":"unknown_category | duplicate | missing_consent. Per-HIT\nfeedback only — a problem with the request-level CMP signal\nnever appears here; it is reported once in the `consent`\nobject below (an unparseable signal costs no hits).\n"}}}},"consent":{"$ref":"#/components/schemas/ConsentSignalFeedback"}}},"IdentityAssertion":{"type":"object","required":["key","value","exp","sig"],"additionalProperties":false,"description":"Backend-signed proof that the visitor holds ONE identifier. Minted by the\ncustomer's backend with the SDK key's identify secret — never by the SDK:\nsig = base64url(HMAC-SHA256(secret, tenant_id \"\\n\" edge_key_token \"\\n\" key \"\\n\" value \"\\n\" exp)),\ntenant_id being the SDK key token's tenant (\"default\" for unprefixed tokens) and the\nwhole secret string the HMAC key. exp is a unix time in the future, at most 24 h ahead.\nA valid assertion selects the profile that already owns (key, value) and links the\ndevice to it: an unowned device is attached; a device whose profile is anonymous\n(holds only tracking device identifiers — a returning customer's earlier browsing) is\nmerged into it; a device already bound to a different known customer is not merged —\nthe operator's identity rules decide. Without an assertion, an identifier another\nprofile owns is recorded only as an unverified claim. When the SDK key has no identify\nsecret the assertion is ignored. Invalid or expired → 400 `invalid_assertion`.\n\nHandling: mint a fresh assertion per login, keep exp short (the console snippets\ndefault to 1 h), and never cache or log it — until exp it is replayable from any\ndevice.\n","properties":{"key":{"type":"string","maxLength":128},"value":{"type":"string","maxLength":4096},"exp":{"type":"integer","format":"int64"},"sig":{"type":"string","description":"base64url, unpadded (trailing '=' tolerated)"}}},"IdentifyRequest":{"type":"object","required":["device_id"],"additionalProperties":false,"description":"At least one of identifiers / attributes / assertion must be present.","properties":{"device_id":{"type":"string","pattern":"^[A-Za-z0-9_-]{8,64}$"},"identifiers":{"type":"object","maxProperties":16,"additionalProperties":{"type":"string","maxLength":4096},"description":"Identifier key → value. Only keys in the operator's identify_allowed_keys are attached; the device key itself is never accepted from the payload."},"attributes":{"type":"object","maxProperties":50,"description":"Profile attribute key → value (JSON scalars or arrays of strings only). Only keys in the operator's identify_allowed_attributes are stored; values are coerced to the entity schema's declared types (an uncoercible value drops that attribute, never the request)."},"consent":{"$ref":"#/components/schemas/ConsentDeclaration"},"assertion":{"$ref":"#/components/schemas/IdentityAssertion"}}},"IdentifyResponse":{"type":"object","properties":{"accepted":{"type":"integer","description":"Accepted identifiers + accepted attributes."},"dropped":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"reason":{"type":"string","description":"not_allowed | device_key | attribute_not_allowed"}}}},"consent":{"$ref":"#/components/schemas/ConsentSignalFeedback"}}},"ConsentRequest":{"type":"object","required":["device_id","consents"],"additionalProperties":false,"properties":{"device_id":{"type":"string","pattern":"^[A-Za-z0-9_-]{8,64}$"},"consents":{"type":"array","minItems":1,"maxItems":32,"items":{"type":"object","required":["purpose","granted"],"properties":{"purpose":{"type":"string","maxLength":128},"granted":{"type":"boolean"},"expires_at":{"type":"string","format":"date-time","nullable":true}}}},"consent":{"allOf":[{"$ref":"#/components/schemas/ConsentDeclaration"}],"description":"The same CMP block track/identify accept, so an SDK can attach the\nsignal to every request it makes without special-casing this\nendpoint. Only the CMP carriers (tcf/gcm/keys) are read here —\ndeclared `purposes` have no role in an explicit consent write, and\nare ignored.\n"},"banner_id":{"type":"string","pattern":"^[A-Za-z0-9-]{1,64}$","description":"The `id` of the `banner_consent` item from `GET /edge/v1/content`\nthis decision was taken on. Optional: omit it and the request\nbehaves exactly as it always has (plain consent rows, no receipt).\n\nWith it, the decision is recorded as a §3 **consent receipt**\n(`channel: \"banner\"`, `collection_point: \"banner:<id>\"`,\n`actor: \"edge\"`, evidence `{banner_id, decisions}`) alongside the\nconsent rows (`source: \"banner\"`). Denials are recorded rows, not\nomissions.\n\n**The banner definition is the allowlist.** The platform looks the id\nup in the tenant's configuration and admits only the purposes\nthat banner asks about; anything else is dropped and counted\n(`not_asked`). An id that is unknown, unpublished, or not a banner\nis dropped whole (`banner_unknown`) — unpublishing a banner is\ntherefore also its revocation, effective within one config poll.\n\nThe policy key/version/hash written into the receipt are the ones\n**frozen into the banner at save time**, never a live lookup:\nthey attest to the text that was actually shown. Publishing a newer\npolicy deliberately changes nothing until an operator re-saves the\nbanner.\n\nNote that a `banner_id` asserts display on a **client-supplied id**\n— there is no serve-side token binding this post to a served\nbanner, so the receipt evidences \"a decision posted against this\nbanner definition\", not a gateway-verified impression. The\nallowlist above is what bounds it.\n\nInvalid shapes are a uniform `400`; the endpoint never reveals\nwhether an id exists.\n"},"lang":{"type":"string","maxLength":16,"description":"The language the banner was rendered in; becomes the receipt's\n`locale`. This is the language SHOWN, not the policy text's own\nlocale (an authoring-time property). Ignored without `banner_id`.\n"},"decided_at":{"type":"string","format":"date-time","description":"When the visitor made this decision, on the device clock (RFC 3339,\nmillisecond precision). Optional. With it, the stored consent version\nis the decision time instead of the arrival time, so a retried older\ndecision can never overwrite a newer one. The server corrects it for\ndevice clock skew with `sent_at` (version =\n`decided_at + (received_at − sent_at)`), never lets it exceed the\narrival time, and applies no staleness bound; a value before 1970 is\ntreated as absent (arrival time is used). Absent, the version is the\narrival time. A banner decision post (`banner_id`) is always\nversioned by arrival time.\n"},"sent_at":{"type":"string","format":"date-time","description":"When THIS attempt was sent, on the device clock (RFC 3339). Set it\nafresh on every retry. Used only to correct `decided_at` for clock\nskew; ignored without `decided_at`.\n"}}}}},"paths":{"/edge/health":{"get":{"tags":["Health"],"summary":"Public liveness probe","operationId":"edgeHealth","description":"No auth. Returns liveness only — no version or build info.","responses":{"200":{"description":"The gateway is up.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]}}}}}}}}},"/edge/v1/content":{"get":{"tags":["Content"],"summary":"Fetch published content for a slot","operationId":"edgeGetContent","security":[{"EdgeKey":[]}],"description":"Served from the gateway's poll-cached configuration. An item is\nreturned when it is published, inside its schedule window, and — if\nit carries URL targeting — one of its glob patterns matches the\n`url` parameter (`path.Match` semantics: `*` does not cross `/`). An\nitem with URL targeting never matches a request that sent no `url`.\n\nItems come in two formats: `structured` carries the JSON rendering\ncontract in `payload`; `unstructured` carries a raw HTML/CSS/JS\ndocument in `html`, to be loaded by the SDK as is.\n\n**Personalization**: items the operator marked personalized are\nrendered server-side against the device's profile context when the\nSDK sends `device_id`. What personal data appears in the output is\ndecided entirely by the operator-authored template — the raw\ncontext never leaves the platform, and an unavailable context\ndegrades to unpersonalized output (never an error). A response\ncontaining personalized items is `Cache-Control: no-store` and\ncarries no ETag.\n\n**Campaign content**: with `device_id` the response also carries the\ndevice profile's live onsite campaign entitlements (channels\nweb_banner / web_personalization / mobile_inapp), marked\n`origin: \"campaign\"` and carrying a `token` the SDK echoes back with\nimpression/click/dismiss events (`POST /edge/v1/content/events`). Eligibility is re-evaluated per request server-side: the\ncampaign's pinned hold condition, live consent, and the impression\nbudget — a no-longer-eligible item simply disappears. web_banner\nitems match the requested `slot` + URL globs; web_personalization\nitems are page-level (URL globs, any slot); mobile_inapp items match\n`screen`. Rendering happens per request against the live profile\nwith the campaign's frozen values as `{{.Data.*}}`. Any campaign\nitem makes the response `no-store`. Campaign lookup failures degrade\nto ABSENCE — operator content always serves.\n\n**Item-level recommendations**: a structured item whose `payload`\ndeclares `{\"kind\": \"items\", \"catalog\": ..., \"strategy\": ...,\n\"count\": ..., \"template\": {...}}` (save-time contract: non-empty\n`catalog`, `strategy` one of `trending` / `recently_viewed` /\n`affinity` — `similar_to`/`blend` are rejected onsite, not\nexpressible without a seed item or parts — `count` 0-20, and\n`personalized: true` is required) is resolved server-side into\nranked rows for the requesting device's profile (`trending` also\nresolves for an unknown device; the profile-scoped strategies do\nnot) and rendered against `template` with those rows addressable as\n`{{range .Items}}...{{end}}`; the served `payload` is the rendered\n`template`, never the raw `{kind, catalog, ...}` envelope. Resolution\ngenuinely fails open: an unknown catalogue, an unresolved device, a\nmalformed payload, or a resolver error all just drop the item — the\nrest of the slot still serves. Without `device_id` an items item\nnever gets a resolution round trip at all and always drops. A\nresponse containing a matched items item is `Cache-Control: no-store`\n(whether or not it ultimately resolved), exactly like a matched\npersonalized item.\n\n**Consent banner**: a `banner_consent` item is present exactly when\nthis visitor still needs asking — the server owns that decision, and\nan already-answered visitor simply gets no banner. Suppression takes\nall three of: every asked purpose carries a recorded decision (a\nrecorded refusal counts — re-asking a refusal on every page view is\nthe dark pattern this avoids), the profile's newest banner/CMP\nconsent receipt is younger than `reask.days` (unless that is 0), and\nthat receipt's policy `(key, version)` still equals the banner's\nfrozen pair (unless `reask.on_policy_change` is false). Everything\nelse asks: no `device_id`, an unavailable context, an unknown\nprofile, a decision recorded somewhere other than a banner/CMP\nsurface, an expired re-ask window, a changed policy version. The\nfailure posture is deliberate — asking twice is annoying, silently\nnot asking is a compliance hole. The one non-serving branch that is\nnot a suppression is a `purposes: \"visible\"` banner whose catalogue\nhas no visible purpose left: there is no question to put. Post the\nanswer to `POST /edge/v1/consent` with the item's `banner_id`. A slot\nholding a matched banner is always `no-store`, whether the banner was\nserved or suppressed — the decision is per-device by construction.\n\n**Licensing**: this route admits either the Edge package's content\nfeature or the consent-banner feature, and the response is filtered\nby item type — a banners-only licence receives its banners and none\nof the content suite's items (nor any campaign entitlement), and a\ncontent-only licence receives everything but banners. `403` only when\nneither is licensed.\n\nOtherwise `ETag` is an opaque validator covering BOTH the\nconfig-snapshot stamp and the served item set, so it also changes\nwhen a scheduled item's window opens/closes or a URL match\ntoggles — cases where the config itself never moved and the stamp\nalone would keep a stale `304` in a client's cache.\n`Cache-Control: private, max-age=30` matches the poll staleness.\nSend `If-None-Match` to get `304` when nothing changed.\n","parameters":[{"name":"slot","in":"query","required":true,"schema":{"type":"string","maxLength":128},"description":"The content slot to render (e.g. homepage_hero)."},{"name":"url","in":"query","required":false,"schema":{"type":"string","maxLength":4096},"description":"The full page URL, used for glob targeting."},{"name":"screen","in":"query","required":false,"schema":{"type":"string","maxLength":256},"description":"The current mobile screen name, used for mobile_inapp glob targeting."},{"name":"device_id","in":"query","required":false,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{8,64}$"},"description":"The SDK device id; enables personalization for items that opted in, campaign content, AND consent-banner re-ask suppression (without it a matched banner always shows). Omit for fully cacheable, unpersonalized broadcast content."}],"responses":{"200":{"description":"Eligible published items, priority desc (possibly empty). Present headers depend on the items: a response carrying personalized, campaign, kind=items or banner_consent content is `Cache-Control: no-store` and carries NO ETag.\n","headers":{"ETag":{"schema":{"type":"string"},"description":"Opaque validator covering the config snapshot stamp and the served item set. Absent on per-device responses."},"Cache-Control":{"schema":{"type":"string"},"description":"private, max-age=30 — or no-store for a per-device response."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentResponse"}}}},"304":{"description":"Not modified (If-None-Match matched the current opaque validator","which covers both the config-snapshot stamp and the served item set).":null},"400":{"description":"Missing or oversized slot/url parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EdgeError"}}}},"401":{"description":"Missing, unknown or revoked X-Edge-Key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EdgeError"}}}},"403":{"description":"Origin not allowlisted for this web key, client blocked by the UA policy, or the account's licence includes NEITHER the Edge package nor the consent-banner feature (the public body never says which — naming a package the visitor cannot buy would leak the client's commercial arrangement). Holding just one of the two is not a 403: the response is filtered to that licence's item types.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EdgeError"}}}},"429":{"description":"Rate limited.","headers":{"Retry-After":{"schema":{"type":"string"},"description":"Seconds until the minute bucket resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EdgeError"}}}},"503":{"description":"Gateway configuration unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EdgeError"}}}}}}},"/edge/v1/content/events":{"post":{"tags":["Content"],"summary":"Report campaign-content feedback (impression / click / dismiss)","operationId":"edgeContentEvents","security":[{"EdgeKey":[]}],"description":"The SDK reports what happened to served campaign items\n(`origin: \"campaign\"` entries from `GET /edge/v1/content`), echoing\neach item's `token`. The gateway does shape-only admission — the\ntoken is the authentication; the Campaign service resolves it,\ndrops unknowns, and turns valid events into entitlement state\ntransitions plus ordinary campaign_touch events (first impression =\n`opened`, click = `clicked` and — for stop_on_click items — stops\nfurther serving, dismiss = `dismissed` and stops serving).\n\n`delivered` is deliberately NOT accepted here: it is published by\nthe serving tier on first serve, so an SDK cannot fabricate funnel\nstages it didn't cause.\n\n`202` means the batch was accepted for processing.\nOn `503` retry the WHOLE batch — server-side state guards and the\nidempotency window absorb replays of events that already got\nthrough.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentEventsRequest"}}}},"responses":{"202":{"description":"All events accepted onto the feedback stream.","content":{"application/json":{"schema":{"type":"object","properties":{"accepted":{"type":"integer"}}}}}},"400":{"description":"Empty/oversized batch, malformed token, or an action other than impression/click/dismiss.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EdgeError"}}}},"401":{"description":"Missing, unknown or revoked X-Edge-Key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EdgeError"}}}},"403":{"description":"Origin not allowlisted for this web key, client blocked by the UA policy, or the account's licence does not include the Edge package (the public body never says which — naming a package the visitor cannot buy would leak the client's commercial arrangement).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EdgeError"}}}},"429":{"description":"Rate limited.","headers":{"Retry-After":{"schema":{"type":"string"},"description":"Seconds until the minute bucket resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EdgeError"}}}},"503":{"description":"Feedback stream unavailable — retry the batch.","headers":{"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EdgeError"}}}}}}},"/edge/v1/nba/responses":{"post":{"tags":["Next best action"],"summary":"Report customer responses to decided offers (NBA response collection)","operationId":"edgeNBAResponses","security":[{"EdgeKey":[]}],"description":"NBA response collection: a web or mobile SDK reports\nwhat happened to a decided offer it displayed — presented, accepted,\npostponed, rejected, or (a downstream system confirmed) realized —\nechoing the decision's `nba_id`.\n\nThe gateway does SHAPE-ONLY admission (a well-formed `nba_id`, a\nknown `action`) and queues the event; `202` means it was accepted for\nprocessing. It resolves nothing — the public tier\nholds no data-plane credential, so the id is opaque here and only\nthe Campaign service can say what it resolves to. The id IS the\ncapability: 80 random bits, and it carries no profile id, so it is\nsafe to hold in a browser.\n\n**Carries no `profile_id`.** See `NBAResponsesRequest` for why, and\n`POST /campaign/api/v1/responses` (Campaign API) for the\ntrusted surface that requires one.\n\nGated behind the Decision-package licence (the same `nba` feature the\ndecide endpoints require) AND its own operator kill switch\n(the `edge_nba_responses_enabled` instance setting, **default OFF**): a new\npublic internet-facing endpoint ships closed until an operator opts\nin. While closed the route answers `404`, indistinguishable from a\nroute that does not exist.\n\nOn `503` retry the WHOLE batch — the consumer's `(nba_id, action)`\ndedup absorbs replays of events that already got through. No\nbuffering happens in the gateway.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NBAResponsesRequest"}}}},"responses":{"202":{"description":"All responses accepted for processing.","content":{"application/json":{"schema":{"type":"object","properties":{"accepted":{"type":"integer"}}}}}},"400":{"description":"Empty/oversized (>50) batch, malformed nba_id (must be 26 characters), an action other than presented/accepted/postponed/rejected/realized, or an unknown field (e.g. profile_id) in the body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EdgeError"}}}},"401":{"description":"Missing, unknown or revoked X-Edge-Key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EdgeError"}}}},"403":{"description":"Origin not allowlisted for this web key, client blocked by the UA policy, or the account's licence does not include the Decision package (`nba` feature). The public body never names which — naming a package the visitor cannot buy would leak the client's commercial arrangement.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EdgeError"}}}},"404":{"description":"NBA response reporting is switched off for this instance (the instance setting `edge_nba_responses_enabled`). Ships closed by default; deliberately indistinguishable from the route not existing.\n"},"429":{"description":"Rate limited.","headers":{"Retry-After":{"schema":{"type":"string"},"description":"Seconds until the minute bucket resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EdgeError"}}}},"503":{"description":"Response stream unavailable — retry the batch.","headers":{"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EdgeError"}}}}}}},"/edge/v1/track":{"post":{"tags":["Tracking"],"summary":"Submit a batch of tracked hits","operationId":"edgeTrack","security":[{"EdgeKey":[]}],"description":"Hits are validated against the caps (400 on violation), checked\nagainst the category mappings (unknown categories dropped with\nin-band feedback), deduplicated on message_id per key\n(within the dedup window), and queued as one batch. Processing\nresolves-or-creates the profile by device id on the tracking entity\nconfigured for the SDK key's platform (web/mobile — possibly the\nsame entity), applies the consent\ngate and clock-skew clamp, maps allowlisted fields to event\nattributes (a value that won't coerce drops the attribute, not the\nhit), and writes through the standard CDP path — provenance stamped\nwith declared ∩ configured collection purposes.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrackRequest"}}}},"responses":{"202":{"description":"Accepted (see per-hit feedback).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrackResponse"}}}},"400":{"description":"Malformed body or cap violation (rejected, never truncated).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EdgeError"}}}},"401":{"description":"Missing, unknown or revoked X-Edge-Key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EdgeError"}}}},"403":{"description":"Origin not allowlisted / client blocked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EdgeError"}}}},"413":{"description":"Body over 64KB, or more hits than the per-request limit (never below 20). The SDKs halve the batch and retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EdgeError"}}}},"429":{"description":"Rate limited.","headers":{"Retry-After":{"schema":{"type":"string"}}}},"503":{"description":"Ingest queue unavailable — nothing was stored; retry.","headers":{"Retry-After":{"schema":{"type":"string"}}}}}}},"/edge/v1/identify":{"post":{"tags":["Tracking"],"summary":"Attach identifiers and allowlisted attributes to the device profile","operationId":"edgeIdentify","security":[{"EdgeKey":[]}],"description":"Attaches allowlisted identifiers and sets allowlisted profile\nattributes on the profile keyed by the device id (both allowlists are\noperator-configured; anything else is dropped with a per-key reason).\nThe profile belongs to the tracking entity configured for the SDK\nkey's platform (web/mobile — the operator may point them at one\nentity or two). The device id is the only identifier the caller has\nproven it holds; every other identifier is a CLAIM. Claims nobody\nowns attach to the device's profile. A claim another profile already\nowns is never attached and never selects that profile: it is\nrecorded as hashed evidence (`claimed_identifiers` on the `identify`\nevent, when that event type is declared) and identity rulesets\ndecide any merge. To link a returning customer's new device\nimmediately, send an `assertion` minted by your backend for the\nlogged-in identifier: the device's anonymous profile (only tracking\ndevice identifiers) is merged into the customer; a device already\nbound to a different known customer is not merged — identity\nrulesets decide. Disabled entirely when the operator sets\nidentify_enabled=false.\n\n**At the tenant's `max_profiles` cap**, an identify that would create\na profile (a device with no profile yet) is dropped whole, including any attached CMP consent, although it\nstill answers `202`. The operator's monitoring counts each drop.\nIdentifies for\nexisting profiles are unaffected.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IdentifyRequest"}}}},"responses":{"202":{"description":"Accepted (per-key feedback for dropped identifiers).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IdentifyResponse"}}}},"400":{"description":"Malformed body","cap violation":null,"or invalid_assertion.":null,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EdgeError"}}}},"401":{"description":"Missing, unknown or revoked X-Edge-Key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EdgeError"}}}},"403":{"description":"Identify disabled, origin not allowlisted, or client blocked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EdgeError"}}}},"429":{"description":"Rate limited.","headers":{"Retry-After":{"schema":{"type":"string"}}}},"503":{"description":"Ingest queue unavailable.","headers":{"Retry-After":{"schema":{"type":"string"}}}}}}},"/edge/v1/consent":{"post":{"tags":["Consent"],"summary":"Record consent statements for the device profile","operationId":"edgeConsent","security":[{"EdgeKey":[]}],"description":"Lands as ordinary profile_consents rows via the normal consent write\npath (source \"edge\"), resolved against the device-id profile\n(created if it does not exist yet).\n\nAn optional `consent` block may carry an external CMP signal, exactly\nas on track/identify; it is recorded separately (source \"cmp\", with a\nreceipt) and never merged into the explicit `consents` above.\n\nPosting `banner_id` (and `lang`) turns this into a **banner decision\npost**: the decision is recorded with a consent receipt carrying the\nbanner's frozen policy triple, filtered to the purposes that banner\nasks about. See the `banner_id` property for the full semantics.\n\nThis endpoint is never gated by `consent_mode=require`, which governs\ndata COLLECTION: a consent post collects nothing — it *is* the\nconsent, and gating it would leave no way to record the grant that\nlifts the gate.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConsentRequest"}}}},"responses":{"202":{"description":"Accepted.","content":{"application/json":{"schema":{"type":"object","properties":{"accepted":{"type":"integer"},"consent":{"$ref":"#/components/schemas/ConsentSignalFeedback"}}}}}},"400":{"description":"Malformed body or cap violation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EdgeError"}}}},"401":{"description":"Missing, unknown or revoked X-Edge-Key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EdgeError"}}}},"403":{"description":"Origin not allowlisted / client blocked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EdgeError"}}}},"429":{"description":"Rate limited.","headers":{"Retry-After":{"schema":{"type":"string"}}}},"503":{"description":"Ingest queue unavailable.","headers":{"Retry-After":{"schema":{"type":"string"}}}}}}},"/edge/v1/trackers":{"get":{"tags":["Tracking"],"summary":"List the active tracker inventory","operationId":"edgeGetTrackers","security":[{"EdgeKey":[]}],"description":"The operator-authored tracker inventory, active\nrows only, sorted by name. No licence gate — consent compliance is\ncore, the same rationale as `/track`, `/identify` and `/consent`.\n\n**Deliberately static**: this is the tracker catalogue, not a\nper-visitor verdict — the SDK holds the banner/CMP decisions\nclient-side and joins them to this list itself. That is why the\nresponse carries no `id`/timestamps (the admin API is where those\nlive) and is cacheable exactly like `GET /edge/v1/content`: `ETag`\nis the config-snapshot stamp, `Cache-Control: private, max-age=30`,\nand `If-None-Match` gets a `304` when nothing changed. It is never\n`no-store` — folding a per-visitor verdict in would force that on\nevery page load, which is the tradeoff this endpoint refuses.\n\nManaged tags (`kind` ≠ `page`) are run by the SDK on pages matching\n`url_patterns` once `purpose` is granted; the list stays static\nbecause both the consent verdict and the URL are joined client-side.\n","responses":{"200":{"description":"Active trackers, sorted by name (possibly empty).","headers":{"ETag":{"schema":{"type":"string"},"description":"Config snapshot stamp."},"Cache-Control":{"schema":{"type":"string"},"description":"private, max-age=30"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrackersResponse"}}}},"304":{"description":"Not modified (If-None-Match matched the current config stamp)."},"401":{"description":"Missing, unknown or revoked X-Edge-Key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EdgeError"}}}},"403":{"description":"Origin not allowlisted for this web key, or client blocked by the UA policy.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EdgeError"}}}},"429":{"description":"Rate limited.","headers":{"Retry-After":{"schema":{"type":"string"},"description":"Seconds until the minute bucket resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EdgeError"}}}},"503":{"description":"Gateway configuration unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EdgeError"}}}}}}},"/edge/v1/receipts/{provider_id}/{token}":{"parameters":[{"name":"provider_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The campaign channel provider instance the callback belongs to."},{"name":"token","in":"path","required":true,"schema":{"type":"string"},"description":"The provider's receipt path token (rotate via the Campaign API). A capability, not a secret — a leaked token only lets someone enqueue receipts that then fail signature verification inside Optima."}],"post":{"tags":["Delivery receipts"],"summary":"Provider delivery-receipt callback","operationId":"edgeReceipt","description":"The URL message providers (Twilio, Meta, Infobip, Vonage, SendGrid,\nMailgun, Postmark, Mandrill, Sinch) call back on to report what\nhappened to an accepted message — delivered, bounced, opened,\nclicked. No `X-Edge-Key` (providers cannot send custom headers):\nadmission is the unguessable path token, plus per-provider\nand per-IP rate limits and a replay dedup on\nthe body hash.\n\nThe gateway verifies NOTHING cryptographic — provider webhook\nsignatures need Campaign credentials, which the DMZ tier must not\nhold. The raw body plus an allowlist of signature headers is\nqueued for processing; Optima verifies,\nresolves the send correlation, and logs the touch. `202` means\n\"queued\" — including receipts that will later be dropped as\nunverifiable (why something is dropped is never leaked to the\ncaller).\n","requestBody":{"required":true,"description":"The provider's native webhook payload, verbatim (JSON or form-encoded).","content":{"application/json":{"schema":{"type":"object"}},"application/x-www-form-urlencoded":{"schema":{"type":"object"}}}},"responses":{"202":{"description":"Accepted responsibility (queued, or a detected replay).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AckResponse"}}}},"400":{"description":"Empty body."},"401":{"description":"Unknown provider id or wrong path token (identical response for both)."},"413":{"description":"Body over the size limit (64KB)."},"429":{"description":"Rate limited.","headers":{"Retry-After":{"schema":{"type":"string"}}}},"503":{"description":"Receipt queue unavailable — retry (every provider has a retry ladder; the gateway never buffers).","headers":{"Retry-After":{"schema":{"type":"string"}}}}}},"get":{"tags":["Delivery receipts"],"summary":"Meta webhook verification handshake","operationId":"edgeReceiptHandshake","description":"Answers Meta's `hub.challenge` verification handshake — the one\nreceipt request the gateway answers itself, and it needs no secret:\nthe `hub.verify_token` the operator pastes into Meta's console IS\nthe receipt path token (constant-time compared). Any other GET is\nrefused.\n","parameters":[{"name":"hub.mode","in":"query","schema":{"type":"string","enum":["subscribe"]}},{"name":"hub.verify_token","in":"query","schema":{"type":"string"}},{"name":"hub.challenge","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"The raw hub.challenge value.","content":{"text/plain":{"schema":{"type":"string"}}}},"400":{"description":"Not a subscription handshake."},"401":{"description":"Unknown provider id or wrong path token."},"403":{"description":"hub.verify_token does not match the receipt path token."}}}},"/edge/v1/preferences/unsubscribe":{"post":{"tags":["Preferences"],"summary":"RFC 8058 one-click unsubscribe","operationId":"edgeOneClickUnsubscribe","description":"The target of the `List-Unsubscribe-Post` header Optima\nstamps on outgoing mail. No confirmation page, no JS, no cookies —\na 2xx means done. Withdraws every consent purpose scoped to the\nsend's channel (from the token) and converts the opt-out into\n§7f contact suppressions — a channel-wide row plus per-purpose\nrows — so it survives erasure and re-import. The token is the\nencrypted profile token minted when the message is sent\n(180-day TTL).\n\nA GET on this URL (mail scanners follow every emailed link) hits\nthe token route with the literal \"unsubscribe\" — an invalid token,\nthe uniform 404, and NO mutation: RFC 8058 mandates POST exactly\nbecause GET-based unsubscribes produce phantom opt-outs.\n","parameters":[{"name":"token","in":"query","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"description":"Mail providers send `List-Unsubscribe=One-Click` (form-encoded); the body is not evaluated.","content":{"application/x-www-form-urlencoded":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Unsubscribed (queued for processing).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AckResponse"}}}},"404":{"description":"Unknown or expired link (uniform for invalid, expired, and tampered tokens — no existence oracle)."},"429":{"description":"Rate limited.","headers":{"Retry-After":{"schema":{"type":"string"}}}},"503":{"description":"Temporarily unavailable — the mail provider retries.","headers":{"Retry-After":{"schema":{"type":"string"}}}}}}},"/edge/v1/r/{code}":{"get":{"summary":"Short-link redirect","operationId":"edgeLinkRedirect","description":"The URL link shortener's public redirect. Codes are minted by the campaign\ndelivery pipeline's `{{shortlink}}` personalization helper; this\nroute answers **302** to the stored target URL.\n\n**No `X-Edge-Key`** — clicks come from inboxes, not the SDK.\nAdmission is the unguessable 10-character path code itself (2-char\ntenant alias + 8 random base62, case-sensitive). **Every miss is the\nsame 404**: malformed code, unknown alias, never-minted or pruned\nrow — the code is the entire credential, so distinguishing them\nwould make this route an oracle for which codes exist.\n\n**Tracking is separate from redirecting.** A tracked, unexpired\nlink's click is queued and recorded as a single `campaign_touch`\nwith `action=clicked`, carrying `url` + `code` attributes\n(touch-only since 2026-08-11 — the separate `link_click` event type\nis no longer produced; stored ones remain historical). The redirect\nitself never waits on it, and a failed enqueue is a lost click,\nnever an error page. Expired links (past `shortlink_ttl_days`)\nkeep redirecting untracked until pruned (`shortlink_grace_days`),\nthen 404.\n\n**Scanners**: HEAD probes and operator-blocklisted User-Agents get\nthe redirect but are never recorded; soft signals (missing or\nscanner-pattern UA, click seconds after mint) record the click with\n`suspected_bot: true` so analytics can discount it. Repeated clicks\non one code collapse inside `shortlink_click_dedup_window_sec`.\n","tags":["Shortlinks"],"parameters":[{"name":"code","in":"path","required":true,"description":"The 10-character public code (2-char tenant alias + 8-char base62 code).","schema":{"type":"string","minLength":10,"maxLength":10}}],"responses":{"302":{"description":"Redirect to the stored target URL (`Cache-Control: no-store` — per-recipient tracking URLs must not be replayed by shared caches)."},"404":{"description":"Uniform miss — malformed, unknown or pruned code."},"429":{"description":"Per-IP rate limit exceeded."},"503":{"description":"The resolver is temporarily unreachable; retry after the indicated delay. Deliberately NOT 404 — a human mid-navigation must see \"try again\", not \"this link is dead\".","headers":{"Retry-After":{"schema":{"type":"string"}}}}}}},"/edge/v1/c/{token}":{"get":{"summary":"Email tracking click redirect","operationId":"edgeEmailClickRedirect","description":"The email link-tracking redirect. Links in rendered campaign emails are rewritten to this\nroute when click tracking is on; it answers **302** to the target\nsealed inside the token.\n\n**No `X-Edge-Key`** — clicks come from inboxes. Admission is the\nsealed AES-256-GCM token itself (stateless: profile, campaign\ncontext, purpose and the target URL all ride encrypted in the path;\nno database row exists). The gateway cannot read it — resolution\nhappens on an internal tier, which alone holds the decryption key. Open-redirect safety is by construction: the\ntarget was fixed when the email rendered, inside authenticated\nciphertext.\n\n**Every miss is the same 404**: tampered token, wrong/rotated-away\nkey, or an open-pixel token replayed here. **The redirect never\nexpires** — a click past `email_tracking_window_days` still lands on\nthe target; only the `campaign_touch action=clicked` stops being\nrecorded. Recording is queued fire-and-forget (a failed enqueue is a\nlost click, never an error page), deduplicated per token inside\n`shortlink_click_dedup_window_sec`, and dropped terminally for\nerased profiles. Scanner stance identical to `/edge/v1/r/{code}`.\n","tags":["Email tracking"],"parameters":[{"name":"token","in":"path","required":true,"description":"The sealed tracking token (base64url, a few hundred characters).","schema":{"type":"string","maxLength":2048}}],"responses":{"302":{"description":"Redirect to the sealed target URL (`Cache-Control: no-store`)."},"404":{"description":"Uniform miss — invalid or foreign-keyed token."},"429":{"description":"Per-IP rate limit exceeded."},"503":{"description":"The resolver is temporarily unreachable; retry after the indicated delay.","headers":{"Retry-After":{"schema":{"type":"string"}}}}}}},"/edge/v1/o/{token}":{"get":{"summary":"Email open-tracking pixel","operationId":"edgeEmailOpenPixel","description":"The email open pixel.\nInjected into rendered campaign emails when open tracking is on.\n\nAnswers the constant 43-byte transparent 1×1 GIF with **200\nunconditionally** — valid token, junk token, no token content\nchecks, tracking backend down: always the same image (`Cache-Control: no-store`\nso re-opens re-fetch). There is deliberately no error outcome: a 404\nwould render broken-image icons in inboxes, and a uniform response\nis no oracle. Recording is only ever the fire-and-forget publish:\nthe platform unseals the token and logs a `campaign_touch\naction=opened` under the send's stored purpose, deduplicated inside\n`email_open_dedup_window_sec`, dropped past\n`email_tracking_window_days` and for erased profiles. Proxy\nprefetches (Apple MPP, Gmail image proxy) and fetches seconds after\nthe send are recorded with `suspected_bot: true` — flagged, never\ndropped. HEAD probes and operator-blocklisted User-Agents get the\nimage but are never recorded.\n\n**Push opens**: the same token rides the FCM/APNs data payload as an open-tracking field\nwhen open tracking is on; a mobile SDK calls this endpoint on\nnotification open (`Optima Android SDK` `push.trackOpen`). Push\ntokens carry `channel: push` and are exempt from the early-fetch\n`suspected_bot` heuristic.\n","tags":["Email tracking"],"parameters":[{"name":"token","in":"path","required":true,"description":"The sealed tracking token (base64url).","schema":{"type":"string","maxLength":2048}}],"responses":{"200":{"description":"The 1×1 transparent GIF — always.","content":{"image/gif":{"schema":{"type":"string","format":"binary"}}}},"429":{"description":"Per-IP rate limit exceeded."}}}},"/edge/v1/assets/{token}":{"get":{"tags":["Content"],"summary":"Serve a published content asset","operationId":"edgeGetAsset","description":"Public serving for the Content Manager library. Answers **302** to a short-lived presigned object-store\nURL, which is what the browser actually fetches the bytes from.\n\n**Legacy surface**: kept serving for links already distributed, but\nthe console and the API mint only the opaque sealed form\n(`/edge/v1/files/{sealed}/{filename}`) since the opaque-file-link change — this route's 302 exposes the storage host and\nobject key, which is exactly what that change closes.\n\n**No `X-Edge-Key`.** A browser cannot send a custom header on an\n`<img src>` subresource load, so admission is the unguessable path\ntoken itself (`oct_<tenant>_<32 base62>`, minted by the CDP when the\nitem is created and stable for the item's whole life). The tenant is\nread from the token's prefix. Same model as the receipt callbacks.\n\n**Every miss is the same 404** — unknown token, unpublished item,\narchived item, unlicensed tenant, missing rendition, backend\nunavailable. The token is the entire credential, so distinguishing\nthem would turn this route into an oracle for which tokens exist.\n\n**Variants**: `?variant=` selects a rendition by name; anything not\npublished falls back to `original`, which is why publication requires\none. The `ETag` is that rendition's content hash, frozen when the\nversion was approved, so a conditional request is answered **304**\nfrom the gateway's polled config with no round trip at all.\n\n**Publish latency**: what is served comes from the config snapshot,\nso a publish or an unpublish takes effect within one\npoll interval (≤30 s by default).\n\n**Editing does not interrupt serving**: the item's workflow status\nreturns to `draft` while an author works, but serving is driven by\nthe pinned revision and its frozen rendition map, so the approved\nbytes stay up until a new version is approved in turn.\n\nThe gateway holds no object-store credentials: it asks an internal\nservice for a signed URL, passing only\n`{tenant, token, variant}` and never a storage key.\n","parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string"},"description":"The item's public token (`oct_<tenant>_<random>`)."},{"name":"variant","in":"query","required":false,"schema":{"type":"string","maxLength":64},"description":"Rendition name; falls back to `original`."},{"name":"If-None-Match","in":"header","required":false,"schema":{"type":"string"},"description":"Conditional request against the rendition's content hash."}],"responses":{"302":{"description":"Redirect to a presigned download URL.","headers":{"Location":{"schema":{"type":"string"},"description":"The presigned URL. A bearer credential with a short life."},"ETag":{"schema":{"type":"string"},"description":"The rendition's frozen sha256."},"Cache-Control":{"schema":{"type":"string"},"description":"`private, max-age=60` — a shared cache must never hand the signed URL to another visitor."}}},"304":{"description":"The rendition is unchanged. Answered from the polled config; no round trip.","headers":{"ETag":{"schema":{"type":"string"}}}},"404":{"description":"Not found — uniformly, for every reason. See the description.\n"},"429":{"description":"Per-IP rate limit exceeded.","headers":{"Retry-After":{"schema":{"type":"integer"}}}}}}},"/edge/v1/sdk/v1/{file}":{"get":{"summary":"Serve the Optima Web SDK bundle (floating major-version alias)","operationId":"edgeGetSDKBundleV1","description":"The Optima Web SDK bundle,\nserved by the gateway itself so a tenant's `<script>` tag can\npoint at their own edge host instead of a third-party CDN:\n\n```html\n<script async src=\"https://edge.shop.example/edge/v1/sdk/v1/optima.js\"\n        data-key=\"oek_shop_…\"></script>\n```\n\n**No `X-Edge-Key`** — a `<script src>` load cannot send a custom\nheader, and the bundle carries no tenant- or customer-specific data;\n`ipRateLimit` is the only gate.\n\n**`v1` is a floating alias**, not the exact SDK semver: it resolves\nto whatever release this gateway currently embeds that keeps the\n`v1` wire contract. Because what it serves can change on every\nrelease, the response is cached for only an hour — long enough to\nmatter, short enough that a rollout reaches visitors same-day. The\nentry bundle (`optima.js`) resolves its own lazy chunks\n(`display.js`, `forms.js`) relative to its own script URL, falling\nback to this same `v1` path, and loads them via a cross-origin\ndynamic `import()` — hence the CORS and Cross-Origin-Resource-Policy\nheaders on every file here, identical for all three.\n\nFor a response that never changes under a stable URL — safe to cache\nfor a full year — pin `GET /edge/v1/sdk/{version}/{file}` instead\n(see `GET /edge/v1/sdk/version` for what \"current\" resolves to).\n","tags":["Web SDK"],"parameters":[{"name":"file","in":"path","required":true,"schema":{"type":"string","enum":["optima.js","display.js","forms.js"]},"description":"The bundle file. Anything else is a uniform 404."},{"name":"If-None-Match","in":"header","required":false,"schema":{"type":"string"},"description":"Conditional request against the file's sha256 ETag."}],"responses":{"200":{"description":"The bundle file.","headers":{"Content-Type":{"schema":{"type":"string"},"description":"`text/javascript; charset=utf-8`."},"Cache-Control":{"schema":{"type":"string"},"description":"`public, max-age=3600` — the alias floats, so it is not cached as immutable."},"ETag":{"schema":{"type":"string"},"description":"The file's sha256","as a strong validator.":null},"Access-Control-Allow-Origin":{"schema":{"type":"string"},"description":"`*` — a public, key-less, immutable-by-content static asset."},"Cross-Origin-Resource-Policy":{"schema":{"type":"string"},"description":"`cross-origin` — required for the lazy chunks' cross-origin `import()`."},"X-Content-Type-Options":{"schema":{"type":"string"},"description":"`nosniff`."}},"content":{"text/javascript":{"schema":{"type":"string","format":"binary"}}}},"304":{"description":"Unchanged, per `If-None-Match`.","headers":{"ETag":{"schema":{"type":"string"}}}},"404":{"description":"Unknown file name."},"429":{"description":"Per-IP rate limit exceeded.","headers":{"Retry-After":{"schema":{"type":"integer"}}}}}}},"/edge/v1/sdk/{version}/{file}":{"get":{"summary":"Serve the Optima Web SDK bundle (exact pinned version)","operationId":"edgeGetSDKBundleVersioned","description":"The same three files as `GET /edge/v1/sdk/v1/{file}`, addressed by\nexact semver instead of the floating `v1` alias. Because this path\nnever resolves to different bytes, the response is cached as\n**immutable** for a full year.\n\nThis gateway keeps only the ONE version it currently embeds — there\nis no history of past releases to fall back to — so `version` must\nequal what `GET /edge/v1/sdk/version` reports right now, or the\nrequest is a 404 (never a redirect, never the current bundle\nserved under the wrong name).\n","tags":["Web SDK"],"parameters":[{"name":"version","in":"path","required":true,"schema":{"type":"string"},"description":"Must equal the gateway's currently embedded SDK version."},{"name":"file","in":"path","required":true,"schema":{"type":"string","enum":["optima.js","display.js","forms.js"]},"description":"The bundle file. Anything else is a uniform 404."},{"name":"If-None-Match","in":"header","required":false,"schema":{"type":"string"},"description":"Conditional request against the file's sha256 ETag."}],"responses":{"200":{"description":"The bundle file.","headers":{"Content-Type":{"schema":{"type":"string"},"description":"`text/javascript; charset=utf-8`."},"Cache-Control":{"schema":{"type":"string"},"description":"`public, max-age=31536000, immutable`."},"ETag":{"schema":{"type":"string"},"description":"The file's sha256","as a strong validator.":null},"Access-Control-Allow-Origin":{"schema":{"type":"string"},"description":"`*`."},"Cross-Origin-Resource-Policy":{"schema":{"type":"string"},"description":"`cross-origin`."},"X-Content-Type-Options":{"schema":{"type":"string"},"description":"`nosniff`."}},"content":{"text/javascript":{"schema":{"type":"string","format":"binary"}}}},"304":{"description":"Unchanged, per `If-None-Match`.","headers":{"ETag":{"schema":{"type":"string"}}}},"404":{"description":"Unknown file name, or `version` does not match the currently embedded SDK."},"429":{"description":"Per-IP rate limit exceeded.","headers":{"Retry-After":{"schema":{"type":"integer"}}}}}}},"/edge/v1/sdk/version":{"get":{"summary":"Report the currently embedded Optima Web SDK version","operationId":"edgeGetSDKVersion","description":"Tiny JSON so a console (or an operator with curl) can see what SDK\nrelease a given edge deployment ships, without pulling the bundle\nitself. This is also what `GET /edge/v1/sdk/{version}/{file}`\nvalidates its `version` path parameter against.\n","tags":["Web SDK"],"responses":{"200":{"description":"The embedded version.","headers":{"Cache-Control":{"schema":{"type":"string"},"description":"`public, max-age=60`."}},"content":{"application/json":{"schema":{"type":"object","properties":{"version":{"type":"string","example":"0.4.0"}}}}}},"429":{"description":"Per-IP rate limit exceeded.","headers":{"Retry-After":{"schema":{"type":"integer"}}}}}}},"/edge/v1/forms/{id}":{"get":{"tags":["Forms"],"summary":"Fetch the JSON rendering of a published web form","operationId":"edgeGetForm","security":[{"EdgeKey":[]}],"description":"Public rendering surface for Optima Edge web forms. Intended for\na customer's own front-end embedding the form in its own markup;\n`GET /edge/v1/pages/{token}/{slug}` is the hosted, standalone\nequivalent that needs no front-end code at all.\n\n**Progressive profiling**: with `device_id`, `ask_once` fields the\ndevice's profile already answers (a non-empty attribute, an\nidentifier on file, or any recorded consent decision) are omitted\nfrom `fields`. An unavailable profile context degrades to \"ask\neverything\" rather than an error. The remaining set is also capped\nto the form's configured `max_fields` (required fields kept first,\ndeclared order otherwise preserved for the kept fields). Fields\ndropped by either rule simply never appear in `fields` here — the\n`not_asked` / `not_in_form` drop reasons are reported only on\n`POST /edge/v1/forms/{id}/submit`, when a submitted key names a\nfield this render didn't show (or no field at all).\n\n**Labels**: `?lang=` selects a field's `Labels[lang]` override,\nfalling back to its default `label` when absent.\n\n**The render nonce**: every response mints a fresh `nonce`,\nscoped to (tenant, form) and required unchanged on the eventual\n`POST /edge/v1/forms/{id}/submit` — it is also the minimum\nrender-to-submit interval's clock start. The response is therefore\nalways `Cache-Control: no-store`.\n","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The form id."},{"name":"device_id","in":"query","required":false,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{8,64}$"},"description":"The SDK device id; enables progressive-profiling elision."},{"name":"lang","in":"query","required":false,"schema":{"type":"string","maxLength":16},"description":"Field-label language override."}],"responses":{"200":{"description":"The rendered form.","headers":{"Cache-Control":{"schema":{"type":"string"},"description":"`no-store` — the nonce is per render."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EdgeForm"}}}},"400":{"description":"Malformed device_id or oversized lang.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EdgeError"}}}},"401":{"description":"Missing, unknown or revoked X-Edge-Key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EdgeError"}}}},"403":{"description":"Origin not allowlisted for this web key, client blocked by the UA policy, or the account's licence does not include landing pages (the public body never names the package).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EdgeError"}}}},"404":{"description":"Unknown or unpublished form.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EdgeError"}}}},"429":{"description":"Rate limited.","headers":{"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EdgeError"}}}},"503":{"description":"Gateway configuration unavailable","or the render nonce could not be minted.":null,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EdgeError"}}}}}}},"/edge/v1/forms/{id}/submit":{"post":{"tags":["Forms"],"summary":"Submit a published web form","operationId":"edgeSubmitForm","security":[{"EdgeKey":[]}],"description":"Shape-admits the submitted `fields` against the form definition\n(`FormSubmitRequest.fields`), then queues the submission\n— acceptance is what `202` means, no gateway buffering. Processing\nre-filters against the CURRENT form definition before writing\n(the definition is the allowlist, enforced there too — config can\nnarrow between render and submit), resolves/creates the profile,\nstamps provenance from the form's configured collection purposes,\nand — when the form is `double_opt_in` — sends a confirmation\nmessage instead of activating submitted consents immediately.\n\n**At the tenant's `max_profiles` cap**, a submit that would create a\nprofile is dropped whole, submitted consents included, although it still\nanswers `202`. The operator's monitoring counts each drop. Submits for\nexisting profiles are unaffected.\n\n**Bot rejection is uniform and gives no oracle.** An invalid,\nexpired, or wrong-(tenant,form)-scoped `nonce`, a submission before\n`min_submit_interval_sec` has elapsed since the render, and a\nfilled honeypot field (`_hp` non-empty) all answer the SAME `403\nsubmission rejected` — a caller cannot tell which check failed, or\nwhether it looks like a bot at all.\n\n**Orphan-profile guard**: if every identifier field was\nempty/elided AND `device_id` is absent, there is nothing to attach\nthe submission to — `400 no identifier to attach to`.\n\n**Required fields must be answered.** An empty string counts as\nunanswered: a required field submitted as `\"\"`, or a required\ncheckbox/consent submitted unticked (`false`, `\"false\"`), answers\n`400 field <key> is required`. An empty optional field is skipped\n(never validated, never stored), so an empty identifier is never\nattached.\n\n**Identity**: the device resolves (or creates) the profile; submitted\nidentifiers are claims that attach only when nobody owns them. With\nno `device_id` and no `assertion`, the first identifier (the\ndouble-opt-in address first) anchors: a new address is a sign-up\nand is written normally, but when it names an EXISTING profile\nnothing is written to that profile — no identifiers, attributes,\nconsents or `form_submitted` event — except, under double opt-in,\npending consent rows the owner's mailbox must confirm.\nAuthenticated server-side integrations that update existing\ncustomers use the CDP API. A valid `assertion` selects its owner\nand merges the device's anonymous profile into it (a device bound\nto a different known customer is never merged).\n\n**Nonce replay**: a nonce already seen within the dedup window\n(`edge_dedup_window_sec`) is `409 already submitted` — the render\nnonce itself stays valid for its full 24h window, but a second\nsubmission inside the (much shorter) dedup window is treated as a\nduplicate, not a resubmission.\n","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The form id (must match the id the nonce was sealed for)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormSubmitRequest"}}}},"responses":{"202":{"description":"Accepted for processing (see per-field feedback).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormSubmitResponse"}}}},"400":{"description":"Malformed/unknown-field body, malformed device_id, more than 64 fields, a field failing type coercion/regex/select-option validation, no identifier to attach to (see description), or invalid_assertion.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EdgeError"}}}},"401":{"description":"Missing, unknown or revoked X-Edge-Key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EdgeError"}}}},"403":{"description":"Submission rejected — uniformly, for an invalid/expired/ wrong-scope nonce, a too-fast submit, or a filled honeypot field. See the description: deliberately indistinguishable.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EdgeError"}}}},"404":{"description":"Unknown form.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EdgeError"}}}},"409":{"description":"The nonce was already used within the dedup window (duplicate submission).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EdgeError"}}}},"413":{"description":"Body over the size limit (64KB)."},"429":{"description":"Rate limited.","headers":{"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EdgeError"}}}},"503":{"description":"Gateway configuration unavailable, edge tracking (`edge_settings`) not configured for this tenant, or the ingest queue is unavailable — nothing was stored; retry.","headers":{"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EdgeError"}}}}}}},"/edge/v1/pages/{token}/{slug}":{"get":{"tags":["Forms"],"summary":"Serve a published form's hosted standalone page","operationId":"edgeGetFormPage","description":"The hosted equivalent of `GET /edge/v1/forms/{id}`: a full HTML\ndocument a marketer can link to directly, with no front-end code at\nall. A GET here is a browser NAVIGATION, so it carries no custom\nheader — the SDK key token that would normally be `X-Edge-Key` rides\nthe URL path instead, and consequently the per-key Origin allowlist\ndoes not apply (a navigation has no Origin). The per-IP rate limit\nand the landing-pages licence gate still do.\n\nRenders the built-in form shell unless the form has an\noperator-authored `page_body`, in which case that body is rendered\nas a Go template against the device's personalization context (when\nthe form opted into personalization) plus `.Form` (the form markup)\nand `.Title` — the same exposure-allowlist rule onsite content\nbodies already follow.\n\nShips a strict per-response `Content-Security-Policy` (a fresh\n`script-src` nonce covers only the page's own inline submit script;\n`connect-src 'self'` permits that script's fetch back to\n`POST /edge/v1/forms/{id}/submit` — see the same-origin exception in\nthe top-level Authentication note — and `img-src https: data:`\npermits images an operator-authored `page_body` embeds) and\n`X-Frame-Options: DENY`. Never cached.\n\nThe page reads the SDK's `_optima_did` cookie when same-site, or the\n`?device_id=` the SDK appends.\n","parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string"},"description":"The SDK key token (would normally be the X-Edge-Key header; a navigation cannot send custom headers)."},{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"description":"The form's slug."},{"name":"device_id","in":"query","required":false,"schema":{"type":"string"},"description":"The SDK device id; malformed values degrade to none rather than erroring a page load."},{"name":"lang","in":"query","required":false,"schema":{"type":"string"},"description":"Field-label language override."}],"responses":{"200":{"description":"The rendered hosted page.","headers":{"Cache-Control":{"schema":{"type":"string"},"description":"`no-store`."},"Content-Security-Policy":{"schema":{"type":"string"}},"X-Frame-Options":{"schema":{"type":"string"},"description":"`DENY`."}},"content":{"text/html":{"schema":{"type":"string"}}}},"403":{"description":"The account's licence does not include landing pages.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EdgeError"}}}},"404":{"description":"Not found — uniformly for an unknown/revoked token, an unknown\ntenant, or an unknown/unpublished slug. The token is the entire\ncredential, so distinguishing them would turn this route into\nan oracle for which tokens and slugs exist.\n"},"429":{"description":"Per-IP rate limit exceeded.","headers":{"Retry-After":{"schema":{"type":"string"}}}},"503":{"description":"The page could not be rendered (nonce mint or template failure).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EdgeError"}}}}}}},"/edge/v1/forms/confirm/{token}":{"parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string","maxLength":2048},"description":"The encrypted double-opt-in confirmation token from the mailed link."}],"get":{"tags":["Forms"],"summary":"Show the double-opt-in confirmation page (does not confirm)","operationId":"edgeGetFormConfirm","description":"The link `POST /edge/v1/forms/{id}/submit` mails out for a\n`double_opt_in` form (`form.double_opt_in_template`, rendered with\n`confirm_url`/`form_name`/`purposes`). Token-authenticated exactly\nlike `GET/PUT /edge/v1/preferences/{token}`: no `X-Edge-Key` — the\nsealed token IS the credential, so this route carries no per-key\nOrigin allowlist or rate limit either, only the per-IP limiter.\n\n**This GET never mutates anything** — the same rule\n`GET /edge/v1/preferences/{token}` follows, and for the identical\nreason: mail scanners and link-prefetchers follow every URL in an\nemail automatically, and a GET that flipped pending consent to\ngranted would let a scanner's \"click\" manufacture double opt-in\nconsent no human ever gave. It runs the full token validation\n(length cap, decrypt, `channel` must be the confirmation channel,\nlanding-pages licence check on the token's tenant — any failure is\nthe uniform `404` below, an unlicensed tenant is `403`) and, on\nsuccess, serves a small page with a visible button inside a real\n`<form method=\"POST\">` pointed at this same URL. Nothing is queued\nuntil that form is actually submitted — see\n`POST /edge/v1/forms/confirm/{token}`.\n","responses":{"200":{"description":"The confirmation page (a \"confirm subscription\" button posting to this same URL).","headers":{"Cache-Control":{"schema":{"type":"string"},"description":"`no-store`."},"Content-Type":{"schema":{"type":"string"},"description":"`text/html; charset=utf-8`."},"Content-Security-Policy":{"schema":{"type":"string"},"description":"`default-src 'none'; form-action 'self'`."},"X-Frame-Options":{"schema":{"type":"string"},"description":"`DENY`."}},"content":{"text/html":{"schema":{"type":"string"}}}},"403":{"description":"The account's licence does not include landing pages.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EdgeError"}}}},"404":{"description":"Not found — uniformly for a malformed/tampered/expired token or\none sealed for a different channel. See the description.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EdgeError"}}}},"429":{"description":"Per-IP rate limit exceeded.","headers":{"Retry-After":{"schema":{"type":"string"}}}}}},"post":{"tags":["Forms"],"summary":"Confirm a double-opt-in web form signup","operationId":"edgeConfirmForm","description":"Performs the confirmation the GET page's button posts to: the SAME\ntoken validation chain as `GET /edge/v1/forms/confirm/{token}`\n(length cap, decrypt, `channel`, licence — uniform `404`/`403` on\nfailure), then — and only then — queues one `form_confirm` envelope\nfor processing. Acceptance is what the `200`/`302` below\nmeans, no gateway buffering.\n\n**Processing decides what actually happens**: it flips only the\nconsent still pending from the submission that mailed this link\n(the token names that submission's receipt), limited to the LIVE\nform's consent purposes while the form exists (config may have\nnarrowed since the mail went out). A newer submission of the same\naddress re-pends under its own receipt, so an older link then\nconfirms nothing. A link minted before receipt binding confirms\npending consent within the form's current purposes, and nothing\nonce the form has been deleted (re-submit the form). If nothing\nmatches (an already-confirmed, double-clicked or superseded link)\nthe click is a no-op — this endpoint answers identically either\nway, since the gateway holds no consent state to report back.\n\nThe confirmation link is valid for 7 days and names the profile that\nOWNS the confirmed address (never the profile of whoever submitted\nthe form). When the token also sealed the submitting SDK device and\nthis request carries the same `_optima_did` cookie, that device is\nlinked to the address owner — attached when unowned, or its profile\nmerged when that profile is anonymous (holds only tracking device\nidentifiers); a device already bound to a different known customer\nis never merged — as proof that one person holds both the mailbox\nand the device. Without\nthe cookie (e.g. the gateway does not share the site's cookie\ndomain) consent is still confirmed and the device is simply not\nlinked.\n","responses":{"200":{"description":"Confirmed (or already was) — a minimal static thank-you page. Served when the form has no `success_redirect_url`, or the form has been deleted since the mail went out.\n","headers":{"Cache-Control":{"schema":{"type":"string"},"description":"`no-store`."},"Content-Type":{"schema":{"type":"string"},"description":"`text/html; charset=utf-8`."},"Content-Security-Policy":{"schema":{"type":"string"},"description":"`default-src 'none'`."},"X-Frame-Options":{"schema":{"type":"string"},"description":"`DENY`."}},"content":{"text/html":{"schema":{"type":"string"}}}},"302":{"description":"Redirect to the form's `success_redirect_url`, when configured.","headers":{"Location":{"schema":{"type":"string"}}}},"403":{"description":"The account's licence does not include landing pages.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EdgeError"}}}},"404":{"description":"Not found — uniformly for a malformed/tampered/expired token or\none sealed for a different channel. See the description.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EdgeError"}}}},"429":{"description":"Per-IP rate limit exceeded.","headers":{"Retry-After":{"schema":{"type":"string"}}}},"503":{"description":"The ingest queue is unavailable; retry.","headers":{"Retry-After":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EdgeError"}}}}}}},"/edge/v1/files/{sealed}/{filename}":{"get":{"tags":["Content"],"summary":"Stream a file addressed by an opaque sealed link","operationId":"edgeGetFile","description":"The opaque public file link surface — the ONLY form new public file URLs are minted in. `sealed`\nis an encrypted blob (AES-256-GCM) carrying\nthe tenant, the source kind (`content`: a public content item's\npublished variant; `document`: a generated campaign document, whose\nref is its stored document record — read per request, expiry\nenforced, deletion = revocation), the reference and the\nauthored filename; `filename` is that exposed filename, so the\naddress bar shows nothing internal and Ctrl+S saves a sensibly named\nfile.\n\n**The gateway streams the bytes — it never redirects.** A 302 would\nput the storage host, bucket and object key into the browser, which\nis the leak this scheme closes. The DMZ gateway cannot even read the\ntoken: it forwards both path segments to an internal\nservice, which decrypts, re-validates the source (the\nitem must still be public with the sealed rendition still published;\nthis re-check is also the revocation — unpublishing kills every link\never minted), verifies the URL filename **exactly** matches the one\nsealed at mint time, applies the Edge content licence, and signs a\nshort-TTL storage URL the gateway fetches server-side.\n\n**No `X-Edge-Key`** — links land in emails, SMS and pages; the sealed\ntoken is the entire credential.\n\n**Every miss is the same 404** — malformed or tampered token, expired\ntoken, unpublished item, withdrawn rendition, filename mismatch,\nunlicensed tenant, backend unavailable, storage down, oversize file\n(100 MB streaming cap). Distinguishing them would make this an oracle\nfor which links exist.\n\n**Slow downloads.** The stream is bounded by time, not by the\nlistener's write timeout: every chunk re-arms a 30 s write deadline,\nso a large file completes on a slow but steady link. The gateway cuts\nthe connection mid-body once the stream passes\n`edge_file_max_stream_sec` (default 1800) or the client takes less\nthan 16 KiB/s over a 30 s window.\n\n**Resume.** A single `Range: bytes=a-b` (also `a-` and `-n`) is\nforwarded to storage and answered **206** with `Content-Range`, so an\ninterrupted download can resume. `If-Range` is forwarded and `ETag`\npasses through. A multi-range or malformed `Range` is ignored (a normal\n200). A range past the end is **416** with `Content-Range: bytes */<size>`.\nIf storage answers a range with 206 but no `Content-Range`, the whole file is\nfetched again and answered 200.\nThe 100 MB cap applies to the response's `Content-Length`.\n","parameters":[{"name":"sealed","in":"path","required":true,"schema":{"type":"string","maxLength":768},"description":"The encrypted link token (base64url, ~200 chars)."},{"name":"filename","in":"path","required":true,"schema":{"type":"string","maxLength":128,"pattern":"^[A-Za-z0-9._-]+$"},"description":"The exposed filename, exactly as minted into the link."}],"responses":{"200":{"description":"The file bytes, streamed.","content":{"*/*":{"schema":{"type":"string","format":"binary","description":"The stored rendition's bytes. The media type is whatever the rendition carries, echoed in Content-Type.\n"}}},"headers":{"Content-Type":{"schema":{"type":"string"},"description":"The stored rendition's content type."},"Content-Disposition":{"schema":{"type":"string"},"description":"`attachment; filename=\"…\"` with the verified exposed filename."},"X-Content-Type-Options":{"schema":{"type":"string"},"description":"`nosniff`."},"Cache-Control":{"schema":{"type":"string"},"description":"`private, max-age=60`."},"Accept-Ranges":{"schema":{"type":"string"},"description":"`bytes`."},"ETag":{"schema":{"type":"string"},"description":"The stored object's ETag","when storage sends one.":null}}},"206":{"description":"The requested byte range, streamed. Same headers as 200 plus `Content-Range`.","content":{"*/*":{"schema":{"type":"string","format":"binary","description":"The requested bytes of the stored rendition."}}},"headers":{"Content-Range":{"schema":{"type":"string"},"description":"`bytes a-b/<size>`."}}},"404":{"description":"Not found — uniformly, for every reason. See the description."},"416":{"description":"The range lies past the end of the file.","headers":{"Content-Range":{"schema":{"type":"string"},"description":"`bytes */<size>`."}}},"429":{"description":"Per-IP rate limit exceeded.","headers":{"Retry-After":{"schema":{"type":"integer"}}}},"503":{"description":"The gateway's concurrent file-stream slots are all in use; retry shortly.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"`5`."}}}}}},"/edge/v1/preferences/{token}":{"parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string"},"description":"The encrypted profile token from an unsubscribe/preferences link."}],"get":{"tags":["Preferences"],"summary":"Current preference state","operationId":"edgeGetPreferences","description":"Returns the purposes marked visible_in_preference_center with the\nprofile's current decision on each (`granted` true/false, or null\nwhen no decision was ever recorded). **Strictly non-mutating.** The\nconsent state is read via the platform (the public gateway holds no\ndata-plane credentials). The response shape is unchanged: `purposes[].description`\nis simply the text resolved for the requested language, per `lang`\nbelow.\n\n**Content negotiation.** When `Accept` lists `text/html` and not\n`application/json` (a browser following the emailed link), the same\nURL serves a small hosted preference page instead: one labelled\ncheckbox per visible purpose and a save button that `PUT`s the\nchoices to this same path. `Accept: */*`, no `Accept`, or any\nJSON-capable `Accept` keeps the JSON response. The page is still\nstrictly non-mutating, and an invalid token is the same uniform `404`.\n","parameters":[{"name":"lang","in":"query","required":false,"schema":{"type":"string"},"description":"Language for `purposes[].description`: exact tag, then primary subtag (`sk-SK` → `sk`), then the purpose's default text. Absent: the first `Accept-Language` tag is used the same way; absent too: the default text."}],"responses":{"200":{"description":"The visible purposes and their states. Served `Cache-Control: no-store` (per-profile state) with `Vary: Accept-Language` (the body depends on the resolved language).","headers":{"Cache-Control":{"schema":{"type":"string"},"description":"Always `no-store`."},"Vary":{"schema":{"type":"string"},"description":"`Accept-Language` for JSON; `Accept, Accept-Language` for the HTML page."},"Content-Security-Policy":{"schema":{"type":"string"},"description":"HTML page only: `default-src 'none'; script-src 'nonce-<n>'; style-src 'nonce-<n>'; connect-src 'self'; base-uri 'none'; form-action 'none'`."}},"content":{"application/json":{"schema":{"type":"object","properties":{"purposes":{"type":"array","items":{"type":"object","properties":{"purpose":{"type":"string"},"description":{"type":"string"},"channel":{"type":"string","description":"Set for channel-scoped purposes."},"topic":{"type":"string","description":"Preference-centre grouping label."},"granted":{"type":"boolean","nullable":true,"description":"null = no decision recorded."}}}}}}},"text/html":{"schema":{"type":"string"}}}},"404":{"description":"Unknown or expired link (uniform)."},"429":{"description":"Rate limited.","headers":{"Retry-After":{"schema":{"type":"string"}}}},"503":{"description":"State read temporarily unavailable."}}},"put":{"tags":["Preferences"],"summary":"Set several preferences at once","operationId":"edgePutPreferences","description":"Accepts decisions only for purposes visible in the preference\ncentre. Writes are queued: processing records the\nconsent rows with a §3 evidence receipt (channel\n\"preference_center\", the campaign the link was minted for as the\ncollection point) and converts channel-scoped withdrawals into §7f\ncontact suppressions.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"consents":{"type":"array","minItems":1,"maxItems":32,"items":{"type":"object","required":["purpose","granted"],"properties":{"purpose":{"type":"string"},"granted":{"type":"boolean"}}}}}}}}},"responses":{"202":{"description":"Queued.","content":{"application/json":{"schema":{"type":"object","properties":{"accepted":{"type":"integer"}}}}}},"400":{"description":"Malformed body or a purpose outside the visible set."},"404":{"description":"Unknown or expired link (uniform)."},"429":{"description":"Rate limited.","headers":{"Retry-After":{"schema":{"type":"string"}}}},"503":{"description":"Ingest queue unavailable.","headers":{"Retry-After":{"schema":{"type":"string"}}}}}}}}}