{"openapi":"3.0.3","info":{"title":"Optima CDP API","version":"1.0","description":"Customer Data Platform (CDP) API for ingesting and managing customer profiles,\nevents, entities, and event types.\n\n**Authentication**: All `/cdp/api/v1/` endpoints accept either:\n- `X-APIKey` header — machine-to-machine API key auth (SHA-512 hashed, role-based route permissions)\n- `Authorization: Bearer <token>` header — human operator session auth (opaque token issued by `/cdp/auth/login`)\n\nThe literal value `\"root\"` is explicitly rejected for API key auth.\n\n**Required headers**: Every request must include `X-Request-ID` (a client-generated unique ID for tracing).\n\nUpdate and delete operations on stored data are asynchronous — callers\nget no read-after-write guarantee for them.\n\n**Feature licence**: surfaces outside the mandatory CDP core (Connect, Edge\ncontent, AI assists — including `/content/generate-image*` and the\n`/llm/providers*` registry — and, in the Campaign/NBA APIs, Campaign,\nDecision and Activation) are gated by the calling tenant's account licence. An unlicensed\ncall answers **403** with a structured body:\n`{\"status\":\"error\",\"message\":\"…\",\"data\":{\"reason\":\"feature_not_licensed\",\"feature\":\"content\",\"package\":\"edge\",\"package_licensed\":false}}`.\n`data.package` names what would grant it, so a console can render an upsell\ninstead of a dead end. `data.package_licensed` is true when the account\nalready holds that package (the feature was excluded from the licence or\nswitched off by the tenant: do not offer an upgrade) and false when the\npackage itself is missing. An account with no stored licence has every package.\nA tenant's `settings.disabled_features` denylist NARROWS the licence and can\nnever widen it — and it is feature-exact: every catalogue key has its own\ngate (route gates for `dashboards`, `metrics`, `computed_attributes`,\n`datasets`, `content_library`, each `assist_*` key and `llm_providers`;\nthe API-family check for core keys that are also path segments;\nsave-time value checks for `streaming`/`kafka`/`cdc` on a connector's\nkind, protocol and envelope).\n\n**Password change required**: a user created through `POST\n/cdp/api/v1/users/add`, or an instance administrator whose initial\npassword was generated at installation, must choose a new password first. Login and refresh return `password_change_required: true`,\nand that session reaches only `GET /cdp/auth/users/me` and `POST\n/cdp/auth/users/me/password` (and logout). Every other session-authenticated\nrequest, on the CDP and on the Campaign/NBA APIs, answers **403** with\n`{\"status\":\"error\",\"message\":\"…\",\"data\":{\"reason\":\"password_change_required\"}}`\n— not 401, so a client must not treat it as an expired session. API keys\nare unaffected.\n"},"servers":[{"url":"http://localhost:2500","description":"Local development server"}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-APIKey"},"BearerAuth":{"type":"http","scheme":"bearer","description":"Opaque session token (64-char hex) obtained from POST /cdp/auth/login. Immediately revocable via POST /cdp/auth/logout."}},"parameters":{"PurposeHeader":{"name":"X-Purpose","in":"header","required":false,"description":"Declared processing purpose(s) for the privacy gates, applied to the\ncustomer data plane: profile/event reads and writes, plus custom-dataset\nrecord and profile-link reads. Accepts a comma-separated list\n(`marketing,analytics`) — data may be collected or read under several\npurposes at once. The caller must be authorized for EVERY supplied\npurpose or the request is rejected with 403 (Gate 1). When\nstrict privacy mode this header is mandatory on these endpoints; in\n`audit`/`enforce` modes it is optional. May also be supplied as the\n`?purpose=` query parameter. In strict mode a missing purpose returns\n403 with `data.reason` set to `purpose_required`.\n\nOn writes the declared set is stamped onto stored attribute rows as\ncollection-purpose provenance (schema-tagged attributes store the\nintersection with their tags); on reads a multi-purpose declaration\nunion-filters over exactly the declared set.\n(Custom datasets are excluded from purpose semantics — non-customer data.)\n","schema":{"type":"string"},"example":"marketing,analytics"},"OnBehalfOfAppHeader":{"name":"X-On-Behalf-Of-App","in":"header","required":false,"description":"Application delegation. A `delegation_allowed`\nservice application (the Campaign suite) relays a request made with\nANOTHER application's key and names that application's id here; Gate 1\n(purpose grants), the PII access level and every privacy manifest are\nthen evaluated against the named application. It must exist, be\nenabled, not be a root key, and be pinned to the resolved tenant (or be\n`cross_tenant_allowed`) — otherwise 403. Mutually exclusive with\n`X-On-Behalf-Of` (400). The audit actor records\n`<caller> obo_app:<application id>`.\n\nAn application with `delegation_enforces_user_roles` may not send this\nheader at all (403): it can only act on behalf of users.\n","schema":{"type":"string","format":"uuid"}}},"responses":{"ManifestForbidden":{"description":"The request's privacy manifest exceeds the acting principal's clearance\n(the caller, or the delegated user/application). A filter, report,\nmetric, cohort or identifier lookup is refused when it references an\nattribute above the actor's `pii_access_level`, a purpose-tagged\nattribute whose tags the declared (X-Purpose) and granted purposes do\nnot cover, or an external signal / cohort whose source purposes the\nactor holds none of. Saved reports, metrics, cohorts and dataset\ntransforms are judged on their LIVE manifest (current schemas), never\nonly on the copy stored at save. Also returned, with\n`data.reason: purpose_required` (no `field`), by a data route called\nwithout `X-Purpose` while the workspace runs in strict privacy mode.\nOther 403 causes carry no `data`.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManifestForbiddenResponse"},"example":{"status":"error","message":"insufficient pii access level for profile.email: requires 3","data":{"reason":"pii_level","field":"profile.email"}}}}},"AnalyticsUnavailable":{"description":"The analytics store could not be read (this includes a lazy cohort's membership read while resolving a cohort.* filter). Not a problem with the definition; retry shortly. Report, ad-hoc query and metric runs answer the same way (report and ad-hoc runs used to answer 500). When the store is under shared memory pressure (its per-user or total memory budget, not this query's own limit) or hit its own execution timeout, the message names the reason and `Retry-After` is set.","headers":{"Retry-After":{"description":"Seconds to wait before retrying. Set only for shared memory pressure or a store-side timeout.","schema":{"type":"integer","example":2}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"AnalyticsRefused":{"description":"The definition cannot run: it does not translate (unknown field or cohort, invalid filter), a lazy cohort.* has more than 1,000,000 members, or the analytics store refused the query or a lazy cohort's scan for its cost or text (the query's own memory limit or a rejection of the query itself; shared memory pressure is a 503 instead, and a store-side timeout a 504). The message says why; for a lazy cohort it says to materialize the cohort.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"AnalyticsTimeout":{"description":"The query's time budget (instance setting analytics_query_timeout_sec) ran out, including while resolving a lazy cohort.* filter's members, or the analytics store's own timeout stopped the query. Not worth retrying unchanged. A cohort that is not materialized is evaluated over every profile on each run.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"AIDelegationForbidden":{"description":"An AI assist call carried X-On-Behalf-Of or X-On-Behalf-Of-App that the calling key may not use: the key is not delegation_allowed, the delegated user is not an active member of the tenant, or the delegated application is unknown, disabled, a root key or pinned to another tenant. Checked on every AI assist route before the per-minute budget, whatever ai_requests_per_minute is. (400 when both headers are sent.)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"AIRateLimited":{"description":"The caller's AI assist budget for this minute is spent (instance setting ai_requests_per_minute, default 30, counted per tenant and caller across the CDP's segment translate, profile summary, AI explain, script assist, image generation and LLM provider test endpoints and the Campaign API's assist endpoints). A delegated call (X-On-Behalf-Of / X-On-Behalf-Of-App) is counted per delegating identity; a delegation header the key may not use is refused with 403 first, whatever the limit (AIDelegationForbidden). Retry after the number of seconds in Retry-After.","headers":{"Retry-After":{"description":"Seconds until the next one-minute window.","schema":{"type":"integer","minimum":1,"maximum":60}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"schemas":{"GenericResponse":{"type":"object","description":"Standard response envelope used by all endpoints.","properties":{"status":{"type":"string","example":"ok"},"message":{"type":"string","example":"entity created"},"data":{"description":"Endpoint-specific payload; absent on success-with-no-body responses."},"warnings":{"type":"array","description":"Warn-level contract violations encountered during ingestion. Present only when at least one warn-level rule fired (on_type_mismatch, on_unknown_attribute, or on_missing_required set to \"warn\") or a value was converted by on_type_mismatch \"coerce\" (level \"coerce\"). The request was accepted; these fields were skipped (type_mismatch with level \"warn\"), stored converted (level \"coerce\") or flagged for caller attention.\n","items":{"type":"object","properties":{"field":{"type":"string"},"rule":{"type":"string"},"actual_value":{},"level":{"type":"string","enum":["warn","coerce"]}}}},"trace":{"type":"string","description":"Stack trace, only present when the server runs in debug mode."},"page":{"$ref":"#/components/schemas/PageMeta"}},"required":["status","message"]},"PageMeta":{"type":"object","description":"Pagination metadata returned alongside every list response.","properties":{"page":{"type":"integer","format":"int64","description":"Zero-based page index that was used."},"size":{"type":"integer","format":"int64","description":"Page size that was used (capped at 100)."},"total":{"type":"integer","format":"int64","description":"Total number of rows matching the query (before LIMIT). `-1` on a cursor page (`after` was sent): the total is not computed.\n"},"next_after":{"type":"string","format":"uuid","description":"Cursor paging only: the last id of a full page, to send as `after` for the next page. Absent on the last page and on offset pages.\n"},"next_before":{"type":"integer","format":"int64","description":"Backward id paging of a scanned list (the agent log with `profile_id`): the id of the last row scanned, masked or not, to send as `before`. Present only while `has_more` is true.\n"},"has_more":{"type":"boolean","description":"Present on profile-filtered log reads; false only when the end of the list was reached.\n"}},"required":["page","size","total"]},"DataType":{"type":"string","enum":["string","decimal","integer","boolean","datetime","json","array_string"],"description":"EAV value-type names used when declaring attribute schemas on entities and\nevent types.  Each name maps to a specific typed value:\n- `string` → value_string\n- `decimal` → value_number (float64)\n- `integer` → value_integer (int64, coerced from JSON numbers)\n- `boolean` → value_boolean\n- `datetime` → value_datetime (accepts RFC3339/ISO-8601 strings or unix timestamps)\n- `json` → value_json (serialised object)\n- `array_string` → value_array (every element stringified)\n"},"EntityObject":{"type":"object","description":"Definition of a profile entity type (e.g. `customer`, `household`).\nEntities are control-plane metadata that describe the shape of profiles\nstored in the data plane.\n","required":["entity_type"],"properties":{"entity_type":{"type":"string","example":"customer"},"parent_entity_type":{"type":"string","example":"household","description":"Optional parent entity for hierarchical models."},"description":{"type":"string","example":"Individual end-customer profile"},"attributes":{"type":"object","description":"Map of attribute name → data type.","additionalProperties":{"$ref":"#/components/schemas/DataType"},"example":{"email":"string","age":"integer","revenue_ltv":"decimal","opted_in":"boolean","registered_at":"datetime"}},"pii_levels":{"type":"object","description":"Map of attribute name → PII sensitivity level (0–255).","additionalProperties":{"type":"integer","minimum":0,"maximum":255},"example":{"email":3}},"identifiers":{"type":"array","description":"List of identifier key names that can be used to resolve this entity.","items":{"type":"string"},"example":["email","phone","loyalty_id"]},"pii_identifiers":{"type":"object","description":"Map of identifier name → PII sensitivity level.","additionalProperties":{"type":"integer","minimum":0,"maximum":255},"example":{"email":3,"phone":3}},"strict":{"type":"boolean","default":false,"description":"When true, the ingestion handler rejects profile attributes whose\nkeys are not declared in `attributes`, returning HTTP 422. When\nfalse (default) unknown keys are accepted and typed by JSON inference.\n"},"attribute_purposes":{"type":"object","description":"Map of attribute name → list of consent purposes that must be active\nfor the attribute to be returned to the caller (Gate 2 enforcement).\n","additionalProperties":{"type":"array","items":{"type":"string"}},"example":{"email":["marketing","analytics"],"phone":["marketing"]}}}},"EntityUpdateRequest":{"type":"object","description":"Partial update of an entity definition: omitted fields keep their stored\nvalue, an explicit empty value (`{}`, `[]`, `\"\"`, `false`) sets it. Send\n`attribute_purposes: {}` to clear every purpose tag, and omit it to leave\nthe tags as they are. A map field that is sent replaces the stored map\nwhole.\n","required":["entity_type"],"properties":{"entity_type":{"type":"string","example":"customer"},"parent_entity_type":{"type":"string","description":"Parent entity for hierarchical models. An empty string clears it."},"description":{"type":"string","example":"Updated description"},"attributes":{"type":"object","description":"Map of attribute name → data type. Replaces the stored map when sent.","additionalProperties":{"$ref":"#/components/schemas/DataType"}},"pii_levels":{"type":"object","description":"Map of attribute name → PII sensitivity level (0–255). Replaces the stored map when sent.","additionalProperties":{"type":"integer","minimum":0,"maximum":255}},"identifiers":{"type":"array","description":"Identifier key names. An empty array clears them.","items":{"type":"string"}},"pii_identifiers":{"type":"object","description":"Map of identifier name → PII sensitivity level. Replaces the stored map when sent.","additionalProperties":{"type":"integer","minimum":0,"maximum":255}},"strict":{"type":"boolean","description":"Reject undeclared attribute keys. `false` turns strict mode off; omit to keep the stored value."},"attribute_purposes":{"type":"object","description":"Map of attribute name → consent purposes. `{}` clears every tag; omit to keep them.","additionalProperties":{"type":"array","items":{"type":"string"}}}}},"EventTypeObject":{"type":"object","description":"Definition of an event type (e.g. `page_view`, `purchase`). Event types\ndeclare the schema of the EAV attributes that events of this type carry.\n","required":["event_type"],"properties":{"event_type":{"type":"string","example":"purchase"},"description":{"type":"string","example":"Customer completed a purchase"},"attributes":{"type":"object","description":"Map of attribute name → data type.","additionalProperties":{"$ref":"#/components/schemas/DataType"},"example":{"order_id":"string","amount":"decimal","item_count":"integer","currency":"string"}},"pii_levels":{"type":"object","description":"Map of attribute name → PII sensitivity level.","additionalProperties":{"type":"integer","minimum":0,"maximum":255},"example":{"card_last4":2}},"strict":{"type":"boolean","default":false,"description":"When true, the ingestion handler rejects event attributes whose keys\nare not declared in `attributes`, returning HTTP 422.\n"},"attribute_purposes":{"type":"object","description":"Map of attribute name → list of consent purposes required for the\nattribute to be visible (Gate 2 enforcement).\n","additionalProperties":{"type":"array","items":{"type":"string"}},"example":{"card_last4":["payment_analytics"]}},"required_consent_purposes":{"type":"array","items":{"type":"string"},"description":"Consent-gated COLLECTION (the instance's collection-gate setting): events of this\ntype are stored only when the profile holds granted consent for\nevery listed purpose whose lawful basis is `consent` (conjunctive;\npurposes on other bases are no-ops). Unknown consent quarantines\nthe event; an explicit withdrawal drops it (silently to the\ncaller, always audited). Empty (default) = no gate. Purpose names\nmust exist in the consent-purpose catalog.\n\nNote for Optima Edge with `cmp_mode=enforce`: the very first hit\ncarrying a CMP refusal may QUARANTINE rather than drop, because\nthe refusal row the gateway just accepted is written\nasynchronously and may not be readable yet. The quarantine\nre-check then finds the withdrawal and drops the event\nterminally — \"an explicit no beats quarantine\" — and subsequent\nhits drop directly. That is this machinery behaving as designed,\nnot a gap; nothing reads consent synchronously on the write path.\n","example":["tracking"]}}},"IdentifierObject":{"type":"object","description":"A single external identifier attached to a profile.","required":["key","value"],"properties":{"key":{"type":"string","example":"email"},"value":{"type":"string","example":"jane@example.com"}}},"CohortMembershipObject":{"type":"object","description":"A cohort a profile belongs to (slim view used on profile reads).","properties":{"id":{"type":"string"},"name":{"type":"string","example":"high_churn_risk"},"description":{"type":"string"}}},"ProfileObject":{"type":"object","description":"Profile as returned by the listing endpoint.","properties":{"id":{"type":"string","format":"uuid","example":"550e8400-e29b-41d4-a716-446655440000"},"entity_type":{"type":"string","example":"customer"},"redacted_attributes":{"type":"array","items":{"type":"string"},"description":"Attribute keys the privacy filter withheld for this caller\n(enforce/strict modes). Lets clients distinguish \"redacted\"\nfrom \"never set\". Absent when nothing was withheld.\n"},"attribute_purposes":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Collection-purpose provenance of the returned attributes: the\nconsent purposes each value was collected under. Only keys that\nsurvived the privacy filter are listed; rows with no recorded\nprovenance (legacy writes) are omitted. Not populated on the\n`resolve_identity=true` merged view.\n","example":{"revenue_ltv":["analytics"],"email_pref":["marketing","analytics"]}},"attribute_collection_basis":{"type":"object","additionalProperties":{"type":"string"},"description":"Read-only. Lawful basis each returned attribute was collected under\n(same keys rule as attribute_purposes; legacy rows with no stored\nbasis are omitted). Metadata only — no read path gates on it.\n","example":{"email_pref":"consent"}},"identifiers":{"type":"array","items":{"$ref":"#/components/schemas/IdentifierObject"}},"attributes":{"type":"object","description":"EAV attributes, only present when `include_attributes=true` was requested. Values are typed according to the entity's attribute schema.\n","additionalProperties":{},"example":{"age":30,"opted_in":true,"revenue_ltv":1249.99}},"computed_attributes":{"type":"object","description":"Computed-attribute values, only present when `include_computed=true` was requested. Each key is a computed attribute name; the value is the evaluated result (segment name for segmentations, a number for functions). A definition whose stored inputs (the profile/event/ related attributes and signals it reads) the caller could not read is not evaluated and is listed in `redacted_computed_attributes`.\n","additionalProperties":{},"example":{"services_segment":"fix_only","avg_order_value":124.99}},"redacted_computed_attributes":{"type":"array","items":{"type":"string"},"description":"Computed attributes withheld for this caller because their\ndefinition reads stored inputs above the caller's PII level or\npurpose clearance (enforce/strict modes; audit/off log and serve).\nAbsent when nothing was withheld.\n"},"signals":{"type":"array","description":"Signal values for the profile, only present when `include_signals=true` was requested. A withheld external signal still appears, carrying `withheld` and no value — absence would be indistinguishable from \"never computed\".\n","items":{"$ref":"#/components/schemas/SignalValueObject"}},"cohorts":{"type":"array","description":"Cohorts the profile currently belongs to, only present when `include_cohorts=true` was requested. Each entry is a cohort whose filter expression matches the profile's current signal values.\n","items":{"$ref":"#/components/schemas/CohortMembershipObject"}},"created_at":{"type":"string","format":"date-time"},"reconstructed_at":{"type":"string","format":"date-time","description":"Present only when the profile was reconstructed from history via the `?at=` parameter. Indicates the point-in-time timestamp used.\n"},"cluster_id":{"type":"string","format":"uuid","description":"Identity cluster root id. Present only when `resolve_identity=true` and the profile belongs to a multi-member cluster; `attributes` is then the merged view across cluster members (per the entity's ruleset merge policy).\n"},"cluster_members":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Profile ids merged into the resolved view (present with cluster_id)."}}},"SetProfileRequest":{"type":"object","description":"Create or update a profile. The server performs basic identity resolution:\nif any of the supplied identifiers already exist in the store the data is\nwritten to the matching profile; otherwise a new profile is created. At\nleast one identifier is required.\n","required":["entity_type","identifiers","source"],"properties":{"entity_type":{"type":"string","example":"customer"},"identifiers":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/IdentifierObject"}},"attributes":{"type":"object","description":"Arbitrary attribute values. Types are coerced against the entity schema when available.","additionalProperties":{},"example":{"age":30,"opted_in":true,"email":"jane@example.com"}},"remove_attributes":{"type":"array","items":{"type":"string"},"description":"Attribute keys to delete from the profile — the removal channel the\nupsert-merge otherwise lacks (clearing a typed EAV value means removing\nthe attribute). A key may not appear in both attributes and\nremove_attributes (400). Keys absent on the profile are a no-op; on a\nbrand-new profile removals are ignored. Removing a contract-required\nattribute without re-supplying it is a contract violation. Removed rows\nare recorded as 'delete' history in h_profile_attributes.\n","example":["nickname"]},"remove_identifiers":{"type":"array","items":{"$ref":"#/components/schemas/IdentifierObject"},"description":"Identifier (key, value) pairs to delete from the profile — the\nidentifier counterpart of remove_attributes. Both key and value are\nrequired, and a pair may not also appear in identifiers (400). Pairs\nabsent on the profile are a no-op; on a brand-new profile removals are\nignored. Removed rows are recorded as 'delete' history. Optima Campaign uses it to drop push tokens the\nplatform reports as unregistered.\n","example":[{"key":"push_token_fcm","value":"d1x...9f"}]},"source":{"type":"string","description":"Origin system that produced this data. Required.","example":"crm"},"consents":{"type":"array","description":"Optional consent records to ingest alongside the profile.","items":{"$ref":"#/components/schemas/ConsentItem"}}}},"ProfileIDsRequest":{"type":"object","required":["entity_type"],"properties":{"entity_type":{"type":"string","example":"customer"},"filter":{"type":"object","description":"Optional query-builder filter, as on `GET /profiles`. Omit it to match every profile.","additionalProperties":true,"example":{"combinator":"and","rules":[{"field":"profile.country","operator":"=","value":"DE"}]}},"after_id":{"type":"string","format":"uuid","description":"Keyset position; the previous response's `next_after_id`."},"limit":{"type":"integer","minimum":1,"maximum":5000,"default":1000}}},"ProfileIDsResponse":{"type":"object","required":["ids"],"properties":{"ids":{"type":"array","items":{"type":"string","format":"uuid"}},"next_after_id":{"type":"string","format":"uuid","description":"Present only when the page is full."}}},"ProfileChangesRequest":{"type":"object","required":["entity_type"],"properties":{"entity_type":{"type":"string","example":"customer"},"filter":{"type":"object","description":"Optional query-builder filter, as on `GET /profiles`.","additionalProperties":true,"example":{"combinator":"and","rules":[{"field":"profile.country","operator":"=","value":"DE"}]}},"cursor":{"type":"string","description":"Opaque cursor of the previous response; omit on the first call."},"limit":{"type":"integer","minimum":1,"maximum":5000,"default":1000},"exclude_writes":{"type":"object","description":"Attribute writes that do not count as a change: rows written with `source`\nwhose key is in `keys`. A consumer that writes attributes itself uses this\nso its own output does not bring the profiles back. Consent writes, other\nsources and other keys on the same profile still count. Keys the caller may not\nread (above its PII clearance) are ignored silently: their writes still count\nas changes, so the field cannot be used to probe unreadable attributes.\n","required":["source","keys"],"properties":{"source":{"type":"string","maxLength":100,"example":"optima_agent"},"keys":{"type":"array","minItems":1,"maxItems":200,"items":{"type":"string","minLength":1,"maxLength":200},"example":["churn_risk"]}}}}},"ProfileChangesResponse":{"type":"object","required":["ids","next_cursor"],"properties":{"ids":{"type":"array","description":"May repeat across windows (the windows overlap by 5 minutes).","items":{"type":"string","format":"uuid"}},"next_cursor":{"type":"string","description":"Opaque; send it as `cursor` on the next call."}}},"ProfileViewsRequest":{"type":"object","required":["profile_ids"],"properties":{"profile_ids":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"string","format":"uuid"}},"attributes":{"type":"array","maxItems":100,"items":{"type":"string"},"description":"Stored attribute keys to return."},"events":{"type":"object","required":["types","last_n","within_days"],"properties":{"types":{"type":"array","minItems":1,"maxItems":20,"items":{"type":"string"}},"last_n":{"type":"integer","minimum":1,"maximum":20},"within_days":{"type":"integer","minimum":1,"maximum":365}}},"identifiers":{"type":"boolean","description":"Also return each profile's identifiers, filtered by the caller's PII level as GET /profiles filters them. Default false."}}},"ProfileViewsResponse":{"type":"object","required":["profiles"],"properties":{"profiles":{"type":"array","items":{"type":"object","required":["id","entity_type","attributes"],"properties":{"id":{"type":"string","format":"uuid"},"entity_type":{"type":"string"},"attributes":{"type":"object","additionalProperties":{}},"redacted_attributes":{"type":"array","description":"Requested keys withheld by the privacy gates.","items":{"type":"string"}},"events":{"type":"array","items":{"$ref":"#/components/schemas/EventObject"}},"identifiers":{"type":"array","description":"Present only when requested and at least one identifier survived the PII filter.","items":{"$ref":"#/components/schemas/IdentifierObject"}}}}}}},"EventsFeedRequest":{"type":"object","required":["event_type"],"properties":{"event_type":{"type":"string","example":"purchase"},"cursor":{"type":"string","description":"Opaque cursor of the previous response; omit on the first call."},"start_at":{"type":"string","format":"date-time","description":"Where the first call starts (ignored once a cursor is sent). Default is the beginning of history."},"limit":{"type":"integer","minimum":1,"maximum":1000,"default":500}}},"EventsFeedResponse":{"type":"object","required":["events","next_cursor"],"properties":{"events":{"type":"array","description":"At least once; de-duplicate on `id`.","items":{"$ref":"#/components/schemas/EventObject"}},"next_cursor":{"type":"string"}}},"SetProfileByIDRequest":{"type":"object","description":"A batch item that addresses an EXISTING profile directly instead of\nresolving identifiers. Same fields as `SetProfileRequest`, except that\n`profile_id` replaces `identifiers` (setting both, or an empty\n`identifiers` list beside `profile_id`, is a 400). `entity_type` must\nmatch the profile.\n","required":["profile_id","entity_type","source"],"properties":{"profile_id":{"type":"string","format":"uuid"},"entity_type":{"type":"string","example":"customer"},"attributes":{"type":"object","additionalProperties":{}},"remove_attributes":{"type":"array","items":{"type":"string"}},"remove_identifiers":{"type":"array","items":{"$ref":"#/components/schemas/IdentifierObject"}},"source":{"type":"string","example":"agent"},"consents":{"type":"array","items":{"$ref":"#/components/schemas/ConsentItem"}}}},"SetProfilesBatchRequest":{"type":"object","required":["profiles"],"properties":{"profiles":{"type":"array","minItems":1,"maxItems":1000,"description":"1 to `profile_batch_max` items (default 500). Each item either\nresolves identifiers (`SetProfileRequest`) or addresses an existing\nprofile by `profile_id` (`SetProfileByIDRequest`).\n","items":{"oneOf":[{"$ref":"#/components/schemas/SetProfileRequest"},{"$ref":"#/components/schemas/SetProfileByIDRequest"}]}}}},"SetProfilesBatchResponse":{"type":"object","properties":{"results":{"type":"array","description":"One entry per request item, in request order.","items":{"type":"object","properties":{"profile_id":{"type":"string","format":"uuid"},"created":{"type":"boolean","description":"true when the item created a new profile, false when it updated an existing one."}}}}}},"RemoveProfilesRequest":{"type":"object","required":["ids"],"properties":{"ids":{"type":"array","minItems":1,"items":{"type":"string","format":"uuid"},"example":["550e8400-e29b-41d4-a716-446655440000"]}}},"RemoveProfilesByFilterRequest":{"type":"object","description":"Deletes every profile of the entity type matching the querybuilder\nfilter and/or cohort. At least one of `filter`/`cohort` is required —\nan unscoped bulk delete must go through explicit ids instead.\n","required":["entity_type"],"properties":{"entity_type":{"type":"string","example":"customer"},"filter":{"type":"string","description":"Querybuilder filter JSON (same grammar as `GET /profiles?filter=`). Requires `entity_type` (400 otherwise)."},"cohort":{"type":"string","description":"Restrict to members of this cohort (same as `GET /profiles?cohort=`)."}}},"ExportProfilesRequest":{"type":"object","description":"CSV export scope + column selection. Base columns (profile_id,\nentity_type, created_at) are always present; each listed identifier/\nattribute/signal/computed name and consent purpose adds one column.\nAttribute values pass the same privacy filter as the list endpoint.\n","required":["entity_type"],"properties":{"entity_type":{"type":"string"},"filter":{"type":"string","description":"Querybuilder filter JSON."},"cohort":{"type":"string"},"identifiers":{"type":"array","items":{"type":"string"}},"attributes":{"type":"array","items":{"type":"string"}},"signals":{"type":"array","items":{"type":"string"}},"computed":{"type":"array","items":{"type":"string"},"description":"Computed attribute names. A column whose definition reads stored inputs above the caller's PII level or purpose clearance exports empty cells (enforce/strict modes).\n"},"consents":{"type":"array","items":{"type":"string"},"description":"Purpose names; each exports a granted/denied/none column."}}},"DedupIdentifiersRequest":{"type":"object","required":["entity_type"],"properties":{"entity_type":{"type":"string"},"key":{"type":"string","description":"Restrict to one identifier key (e.g. email)."},"dry_run":{"type":"boolean","default":true},"limit":{"type":"integer","minimum":1,"maximum":1000,"default":100,"description":"Maximum duplicate groups processed in this call."}}},"DedupIdentifiersResponse":{"type":"object","properties":{"dry_run":{"type":"boolean"},"groups_total":{"type":"integer","description":"Total duplicate groups matching the scope (before limit)."},"processed":{"type":"integer"},"merged":{"type":"integer"},"failed":{"type":"integer"},"error":{"type":"string","description":"First merge error, when any failed."},"groups":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string","description":"Blanked (empty string) when `value_redacted` is true — the identifier key's PII level (the entity's `pii_identifiers` tag) exceeds the caller's `pii_access_level`."},"value_redacted":{"type":"boolean","description":"True when `value` was withheld by the caller's PII clearance."},"canonical":{"type":"string","format":"uuid","description":"The oldest profile — merge target."},"duplicates":{"type":"array","items":{"type":"string","format":"uuid"}}}}}}},"MergeProfilesRequest":{"type":"object","description":"Merge the source profile into the target. The target survives and absorbs\nthe source's events, attributes, and identifiers. The source profile row\nis removed and the merge recorded as a `profile_link`. Both profiles must\nshare the same `entity_type` and must not already be merged.\n","required":["target_profile_id","source_profile_id"],"properties":{"target_profile_id":{"type":"string","format":"uuid","description":"The profile that survives the merge.","example":"550e8400-e29b-41d4-a716-446655440000"},"source_profile_id":{"type":"string","format":"uuid","description":"The profile that is absorbed and deleted. Must have the same `entity_type` as the target.","example":"661f9500-f3ac-52e5-b827-557766551111"},"relation_creator":{"type":"string","description":"System or user that triggered the merge. Stored in the resulting `profile_link` row.","example":"identity-service"}}},"LinkProfilesRequest":{"type":"object","description":"Record a non-merging relationship between two profiles (e.g. household membership).","required":["parent_profile_id","child_profile_id"],"properties":{"parent_profile_id":{"type":"string","format":"uuid","example":"550e8400-e29b-41d4-a716-446655440000"},"child_profile_id":{"type":"string","format":"uuid","example":"661f9500-f3ac-52e5-b827-557766551111"},"relation_type":{"type":"string","example":"household_member"},"relation_creator":{"type":"string","example":"cdp-api"},"identifier_key":{"type":"string","description":"Identifier key used to establish the link.","example":"household_id"},"identifier_value":{"type":"string","example":"hh-00123"}}},"ProfileLinkObject":{"type":"object","description":"A single profile-link (stitching/relationship) edge.","properties":{"parent_profile_id":{"type":"string","format":"uuid","example":"550e8400-e29b-41d4-a716-446655440000"},"child_profile_id":{"type":"string","format":"uuid","example":"661f9500-f3ac-52e5-b827-557766551111"},"relation_type":{"type":"string","example":"household_member"},"relation_creator":{"type":"string","example":"cdp-api"},"identifier_key":{"type":"string","example":"household_id"},"identifier_value":{"type":"string","description":"Blanked (empty string) when `identifier_value_redacted` is true — the identifier key's PII level, on either endpoint's entity schema (most restrictive wins), exceeds the caller's `pii_access_level`.","example":"hh-00123"},"identifier_value_redacted":{"type":"boolean","description":"True when `identifier_value` was withheld by the caller's PII clearance."},"confidence":{"type":"number","format":"float","description":"Identity-graph resolution confidence (1.0 for manually created links).","example":1},"rule_id":{"type":"string","description":"Identity rule that produced the edge (empty for manual links)."},"ruleset_id":{"type":"string","description":"Identity ruleset that produced the edge (empty for manual links)."},"created_at":{"type":"string","format":"date-time"},"resolved_at":{"type":"string","format":"date-time","description":"For identity links, the time the identity cluster last changed. Resolution rewrites a cluster's edges only when they change, so an unchanged re-resolve leaves this time as it was. It is not the time of the last resolve."}}},"ProfileLinksBatchRequest":{"type":"object","required":["profile_ids"],"properties":{"profile_ids":{"type":"array","minItems":1,"maxItems":500,"items":{"type":"string","format":"uuid"},"description":"Profiles to read links for. Duplicates are read once."},"direction":{"type":"string","enum":["both","parent","child"],"default":"both","description":"Which side of the link each requested profile is matched on."},"relation_type":{"type":"string","description":"Optional filter by relation type."}},"example":{"profile_ids":["550e8400-e29b-41d4-a716-446655440000"],"direction":"parent"}},"ProfileLinksBatchResponse":{"type":"object","properties":{"links_by_profile":{"type":"object","description":"Requested profile id → the links filed under it. Every requested id is present.","additionalProperties":{"type":"array","items":{"$ref":"#/components/schemas/ProfileLinkObject"}}}}},"UpdateProfileLinkRequest":{"type":"object","description":"Patch the non-key attributes of a profile link. Only the fields present\nin the body are applied. The two profiles in the relation and the\n`relation_type` addressing key are never changed here — to retype or\nre-point a link, delete it and create a new one.\n","properties":{"relation_creator":{"type":"string","example":"identity-service"},"identifier_key":{"type":"string","example":"household_id"},"identifier_value":{"type":"string","example":"hh-00999"},"confidence":{"type":"number","format":"float","example":0.85},"rule_id":{"type":"string"},"ruleset_id":{"type":"string"}}},"EventObject":{"type":"object","description":"A single behavioural event. On ingestion the caller provides `profile_id`,\n`event_type`, `source`, and optional `timestamp`/`attributes`; the server\nassigns `id` unless the caller supplies a valid UUID (an invalid one is\nignored). Without a client `id`, requests carrying `X-Idempotency-Key`\nget ids derived from the tenant, key, position and event content, so a\nretry of the same batch after a partial publish (503) re-sends the same\nids and duplicates are identifiable. The API does not guarantee\ndeduplication of stored events.\n","required":["profile_id","event_type","source"],"properties":{"id":{"type":"string","format":"uuid","description":"Event id. On writes a valid UUID is used as a retry key, not stored verbatim - the stored id is derived from the tenant, profile_id and this value (the same input always gives the same id; read it back from the response), so it cannot collide with another profile's event. Otherwise server-assigned.","example":"7f3e9100-a1bc-43d5-c938-668877662222"},"profile_id":{"type":"string","format":"uuid","example":"550e8400-e29b-41d4-a716-446655440000"},"event_type":{"type":"string","example":"purchase"},"timestamp":{"type":"string","format":"date-time","description":"Event timestamp. Defaults to server receive time when omitted.","example":"2024-06-01T14:22:00Z"},"source":{"type":"string","description":"Origin system. Required.","example":"web-storefront"},"attributes":{"type":"object","description":"EAV attribute values. On write, types are coerced against the event type schema when available. On read (`include_attributes=true`), typed Go values are returned.\n","additionalProperties":{},"example":{"order_id":"ORD-9982","amount":149.99,"item_count":3,"currency":"USD"}},"redacted_attributes":{"type":"array","items":{"type":"string"},"description":"Read-only. Attribute keys the privacy filter withheld for this\ncaller (enforce/strict modes), matching the profile read's field of\nthe same name. Lets clients distinguish \"redacted\" from \"never\nset\". Absent when nothing was withheld.\n"},"attribute_purposes":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Read-only. Collection-purpose provenance of the returned attributes\n(only keys that survived the privacy filter; legacy rows with no\nrecorded provenance are omitted). Ignored on writes.\n"},"attribute_collection_basis":{"type":"object","additionalProperties":{"type":"string"},"description":"Read-only. Lawful basis each returned attribute was collected under\n(same keys rule as attribute_purposes; legacy rows omitted).\n"},"reconstructed_at":{"type":"string","format":"date-time","description":"Present only when the event was reconstructed from history via the `?at=` parameter. Indicates the point-in-time timestamp used.\n"}}},"CreateEventsRequest":{"type":"object","required":["events"],"properties":{"events":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/EventObject"}}}},"EventUpdate":{"type":"object","description":"Partial update for a single event. The event's identity (profile, type, timestamp) is immutable; `source`, `attributes` and `remove_attributes` may be changed. At least one of the three must be supplied. Attributes are upserted (merged): keys in `attributes` are added or overwritten; omitted keys keep their stored values. `remove_attributes` deletes the listed keys; a key may not appear in both `attributes` and `remove_attributes`. Strict-mode and data-contract validation apply as on ingestion; `required` is satisfied by attributes already stored on the event, and a `required` attribute cannot be removed (422). Changes are recorded in `h_events` / `h_event_attributes` (insert/update/delete).\n","required":["id"],"properties":{"id":{"type":"string","format":"uuid"},"source":{"type":"string","example":"backfill-job"},"attributes":{"type":"object","description":"Attribute values to add or overwrite, typed per the event-type schema.","additionalProperties":{},"example":{"amount":249.99,"currency":"USD"}},"remove_attributes":{"type":"array","description":"Attribute keys to delete from the event.","items":{"type":"string"},"example":["coupon"]}}},"UpdateEventsRequest":{"type":"object","required":["events"],"properties":{"events":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/EventUpdate"}}}},"RemoveEventsRequest":{"type":"object","required":["ids"],"properties":{"ids":{"type":"array","minItems":1,"items":{"type":"string","format":"uuid"}}}},"EventAttrRule":{"type":"object","description":"One condition of the simplified event attribute filter (AND-combined).\nRequires an event type; keys must be declared in its schema. Operators:\n=, !=, <, <=, >, >= (typed), contains/begins_with/ends_with (string),\nin/not_in (array value, each element coerced to the attribute's type),\nexists/not_exists. json/array attributes are not filterable.\n","required":["key","operator"],"properties":{"key":{"type":"string"},"operator":{"type":"string","enum":["=","!=","<","<=",">",">=","contains","begins_with","ends_with","in","not_in","exists","not_exists"]},"value":{}}},"EventFilterBody":{"type":"object","description":"Filter conditions for the bulk event endpoints. `from`/`to` bound the\nevent timestamp (inclusive) and accept RFC3339 or datetime-local\n(\"2006-01-02T15:04[:05]\") values interpreted as UTC. `attr_filters`\nrules require `event_type`.\n","properties":{"profile_id":{"type":"string","format":"uuid"},"event_type":{"type":"string"},"source":{"type":"string"},"from":{"type":"string","example":"2026-07-01T00:00"},"to":{"type":"string","example":"2026-07-15T23:59"},"attr_filters":{"type":"array","items":{"$ref":"#/components/schemas/EventAttrRule"}}}},"ExportEventsRequest":{"allOf":[{"$ref":"#/components/schemas/EventFilterBody"},{"type":"object","properties":{"attributes":{"type":"array","items":{"type":"string"},"description":"Event attribute keys exported as extra columns after the base\nones (event_id, profile_id, event_type, timestamp, source).\nValues pass the same privacy filter as the list endpoint.\n"}}}]},"Aggregate":{"type":"object","description":"An aggregation over a profile's events or related (child) profiles. Used\nboth as a numeric operand in `function` expressions and as the subject of\nan `aggregate` condition leaf in segmentations.\n","required":["function","over"],"properties":{"function":{"type":"string","enum":["count","sum","avg","min","max","uniq","any"],"description":"Aggregate function. `count` ignores `attribute`."},"over":{"type":"string","enum":["events","related_profiles"],"description":"What to aggregate over."},"event_type":{"type":"string","description":"Required when `over=events`.","example":"purchase"},"scope":{"type":"string","enum":["self"],"description":"events: whose events to aggregate (currently only the profile's own)."},"relation":{"type":"string","enum":["children"],"description":"related_profiles: which related profiles to aggregate (only direct children)."},"child_entity_type":{"type":"string","description":"related_profiles: optional filter restricting children to this entity type.","example":"service"},"attribute":{"type":"string","description":"Value attribute to aggregate. Required for every function except `count`.","example":"amount"},"where":{"$ref":"#/components/schemas/ConditionNode","description":"Optional filter over the aggregated rows' attributes (attribute leaves only)."}}},"ConditionNode":{"type":"object","description":"A node of a boolean condition tree. A node is either a **group**\n(`logic` + `conditions`) or a **leaf** (`source` + `operator` + `value`).\nLeaves compare a profile attribute (`source=attribute`), an aggregate\n(`source=aggregate`) or a signal's latest value\n(`source=signal_ref`) against a value.\n","properties":{"logic":{"type":"string","enum":["and","or"],"description":"Group form — boolean combinator for `conditions`."},"conditions":{"type":"array","description":"Group form — child nodes.","items":{"$ref":"#/components/schemas/ConditionNode"}},"source":{"type":"string","enum":["attribute","aggregate","signal_ref"],"description":"Leaf form — what the left-hand side refers to."},"attribute":{"type":"string","description":"Leaf form — attribute key (when `source=attribute`)."},"aggregate":{"$ref":"#/components/schemas/Aggregate"},"signal_name":{"type":"string","description":"Leaf form — the signal whose latest value is compared (**required** when `source=signal_ref`). Compared numerically; a profile with no computed value falls back to the numeric default, exactly as a missing attribute does.\n"},"operator":{"type":"string","enum":["eq","neq","gt","gte","lt","lte","in","nin"],"description":"Leaf form — comparison operator (`in`/`nin` expect an array value)."},"value":{"description":"Leaf form — scalar comparison value, or an array for `in`/`nin`."}}},"ExprNode":{"type":"object","description":"A node of a `function`'s arithmetic expression tree. `type` selects the\nnode shape:\n- `literal` → `value`\n- `attribute` → `attribute` (the profile's own numeric attribute)\n- `signal_ref` → `signal_name` (the signal's latest value)\n- `aggregate` → `aggregate`\n- `binary` → `operator` (`+ - * /`) + `left` + `right`\n- `function` → `function` (allow-listed math fn) + `args`\n","required":["type"],"properties":{"type":{"type":"string","enum":["literal","attribute","signal_ref","aggregate","binary","function"]},"value":{"type":"number","description":"type=literal: the numeric constant."},"attribute":{"type":"string","description":"type=attribute: the profile attribute name."},"signal_name":{"type":"string","description":"'type=signal_ref': the signal whose latest value is the operand (**required** for that type). Read numerically; a profile with no computed value falls back to the numeric default.\n"},"aggregate":{"$ref":"#/components/schemas/Aggregate"},"operator":{"type":"string","enum":["+","-","*","/"],"description":"type=binary: the arithmetic operator."},"left":{"$ref":"#/components/schemas/ExprNode"},"right":{"$ref":"#/components/schemas/ExprNode"},"function":{"type":"string","enum":["round","floor","ceil","abs","exp","log","log2","log10","sqrt","pow","greatest","least","intDiv","modulo"],"description":"type=function: allow-listed math function."},"args":{"type":"array","items":{"$ref":"#/components/schemas/ExprNode"}}}},"ComputedDefinition":{"type":"object","description":"The structured, SQL-translatable definition. For `segmentation` use\n`segments` + `default_segment`; for `function` use `expression`.\n","properties":{"segments":{"type":"array","description":"segmentation: ordered, named buckets. First matching segment wins.","items":{"type":"object","required":["name","condition"],"properties":{"name":{"type":"string","example":"fix_only"},"condition":{"$ref":"#/components/schemas/ConditionNode"}}}},"default_segment":{"type":"string","description":"segmentation: value used when no segment matches.","example":"mixed"},"expression":{"$ref":"#/components/schemas/ExprNode"}}},"ComputedAttributeObject":{"type":"object","description":"A computed (virtual) profile attribute. Only the definition is stored; the\nvalue is evaluated on demand from stored data and surfaced through\n`GET /profiles?include_computed=true`. Always scoped to an entity type and\nunique by `(entity_type, name)`.\n","required":["entity_type","name","kind","definition"],"properties":{"id":{"type":"string","format":"uuid","description":"Server-assigned id (present on reads, ignored on writes)."},"entity_type":{"type":"string","description":"Entity type this attribute is defined on.","example":"customer"},"name":{"type":"string","description":"Attribute name; behaves like a normal profile attribute key.","example":"services_segment"},"description":{"type":"string"},"kind":{"type":"string","enum":["segmentation","function"]},"value_type":{"$ref":"#/components/schemas/DataType","description":"Result type. Defaults to `string` for segmentations and `decimal` for functions when omitted.\n"},"definition":{"$ref":"#/components/schemas/ComputedDefinition"},"enabled":{"type":"boolean","default":true,"description":"Disabled attributes are skipped by `include_computed`."}}},"AttributeRule":{"type":"object","description":"Per-attribute validation and transformation rule. All keys are optional;\nat least one should be set. Tiers are evaluated in order: JSON rules\n(Tier 1) → expr expressions (Tier 2) → named functions (Tier 3).\n","properties":{"required":{"type":"boolean","description":"Field must be present and non-empty."},"format":{"type":"string","description":"Regex pattern the value must match. At most 1024 bytes (enforced on save; compiled once when the contract loads).","example":"^[^@]+@[^@]+$"},"min":{"type":"number","description":"Numeric lower bound, or minimum string length for string values."},"max":{"type":"number","description":"Numeric upper bound, or maximum string length for string values."},"enum":{"type":"array","items":{"type":"string"},"description":"Value must be one of these strings.","example":["US","DE","FR"]},"coerce_from":{"type":"object","description":"Rename incoming keys before validation (e.g. rename \"phone_number\" to \"phone\").","additionalProperties":{"type":"string"},"example":{"phone_number":"phone"}},"validate_expr":{"type":"string","description":"Tier 2 expr expression that returns bool. Receives `value` (field value)\nand `attrs` (full attribute map). Built-ins: `trim_lower`, `phone_e164`,\n`parse_iso_date`, `truncate`. Save enforces static limits (400):\npredicate functions (all, any, map, filter, …) nest at most 2 deep and a literal range a..b spans fewer than 1000 elements (dynamic ranges are bounded by the runtime budget). At ingest each run is bounded (1 048 576 steps / 50 ms);\na run over budget rejects the write with 422 \"data contract\nviolation\" naming rule `expr_budget`.\n","example":"value matches \"^\\\\+[0-9]{7,15}$\""},"transform_expr":{"type":"string","description":"Tier 2 expr expression applied before validation. Receives `value` and\nreturns the new value. Same built-ins, static limits and budget as\n`validate_expr`: a transform over its budget rejects the write with\n422 \"data contract violation\" naming rule `expr_budget`.\n","example":"phone_e164(value)"}}},"DataContractObject":{"type":"object","description":"A data contract defines per-attribute validation and transformation rules\napplied at ingestion time before data reaches the batch inserter. Each\ncontract is scoped to either an entity type or an event type. Only one\ncontract can exist per `(scope, scope_name)` pair.\n","required":["scope","scope_name"],"properties":{"scope":{"type":"string","enum":["entity","event_type"],"description":"Whether this contract applies to profile (entity) or event ingestion.","example":"entity"},"scope_name":{"type":"string","description":"The entity_type or event_type name this contract covers.","example":"customer"},"rules":{"type":"object","description":"Map of attribute name → AttributeRule.","additionalProperties":{"$ref":"#/components/schemas/AttributeRule"},"example":{"email":{"required":true,"format":"^[^@]+@[^@]+$"},"age":{"min":0,"max":150},"country":{"enum":["US","DE","FR"]}}},"on_unknown_attribute":{"type":"string","enum":["allow","warn","reject"],"default":"allow","description":"Action when an attribute is present in the payload but not declared in the entity/event schema. An entity or event type with no declared attributes is free form: unknown-attribute and type-mismatch checks apply only once at least one attribute is declared.\n"},"on_type_mismatch":{"type":"string","enum":["coerce","warn","reject"],"default":"coerce","description":"Action when a value does not match the declared EAV type. `coerce` converts the value to the declared type (numeric string → number, integral only for `integer`; number/bool → string; `true/false/1/0` → boolean; JSON-object string → json; scalar → one-element `array_string`) and stores it, still returning a `{rule: type_mismatch, level: coerce}` warning. A value that cannot be converted is dropped and reported with `level: warn`. `warn` always drops. `reject` fails the write with 422.\n"},"on_missing_required":{"type":"string","enum":["warn","reject"],"default":"reject","description":"Action when a required attribute is missing."},"enabled":{"type":"boolean","default":true,"description":"Disabled contracts are skipped entirely during ingestion."}}},"ManifestForbiddenResponse":{"description":"The 403 body of a privacy-manifest denial: the error envelope plus data.reason / data.field naming the first field the acting principal (or connector clearance) does not clear; `purpose_required` (no field) means a strict-mode call without `X-Purpose`. Other 403 causes return the plain error envelope without data.","allOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"type":"object","properties":{"data":{"type":"object","required":["reason"],"properties":{"reason":{"type":"string","enum":["pii_level","purpose_not_declared","purpose_not_granted","signal_purpose","purpose_required"]},"field":{"type":"string","description":"The denied field (e.g. profile.email, dataset.orders.card); empty for a manifest-wide denial."}}}}}]},"IdentifierConflictResponse":{"description":"The 409 body of a profile write whose identifiers resolve to two or more different profiles: the error envelope plus the request's identifier keys grouped per owning profile, in request order. It carries no identifier values and no profile ids. `index` is the batch item (batch only).","allOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"type":"object","properties":{"data":{"type":"object","required":["reason","groups"],"properties":{"reason":{"type":"string","enum":["identifier_conflict"]},"index":{"type":"integer","description":"The conflicting batch item (/profiles/set/batch only)."},"groups":{"type":"array","items":{"type":"object","required":["identifier_keys"],"properties":{"identifier_keys":{"type":"array","items":{"type":"string"}}}}}}}}}]},"ErrorResponse":{"type":"object","properties":{"status":{"type":"string","example":"error"},"message":{"type":"string","example":"entity 'customer' already exists"},"trace":{"type":"string","description":"Stack trace (debug mode only)."}},"required":["status","message"]},"CredentialsRequiredResponse":{"type":"object","description":"Returned with 409 `credentials_required` when an update changes where a stored credential would be sent (host, URL, type, protocol, network…) without re-supplying it. Re-send the request with the credential, or clear the stored one explicitly. `fields` names the destination parts that changed (DTO field names); `credentials` (instance settings only) names the secret settings to re-enter.\n","properties":{"status":{"type":"string","example":"error"},"message":{"type":"string","example":"credentials must be re-entered when the destination changes"},"data":{"type":"object","properties":{"code":{"type":"string","enum":["credentials_required"]},"fields":{"type":"array","items":{"type":"string"},"example":["api_host"]},"credentials":{"type":"array","items":{"type":"string"},"example":["smtp_pass"]}},"required":["code","fields"]}},"required":["status","message","data"]},"LoginRequest":{"type":"object","required":["email","password"],"properties":{"email":{"type":"string","format":"email","example":"admin@example.com"},"password":{"type":"string","minLength":8,"description":"8 characters to 72 bytes (UTF-8); bcrypt reads no further.","example":"s3cr3tP@ss"}}},"LoginResponse":{"type":"object","properties":{"access_token":{"type":"string","description":"Short-lived opaque session token (64-char hex, default 1 h TTL) used in Authorization Bearer header."},"refresh_token":{"type":"string","description":"Longer-lived opaque session token (64-char hex, default 7 d TTL) used to obtain new tokens via POST /cdp/auth/refresh."},"expires_at":{"type":"integer","description":"Unix timestamp when the access token expires."},"password_change_required":{"type":"boolean","description":"true = the session is restricted until the user changes the password (POST /cdp/auth/users/me/password); every route but GET /cdp/auth/users/me, that one and logout answers 403 data.reason=password_change_required. Always false on the pair the password change returns.\n"}}},"ChangePasswordRequest":{"type":"object","required":["current_password","new_password"],"properties":{"current_password":{"type":"string"},"new_password":{"type":"string","minLength":8,"description":"Same rules as the password reset (8 characters to 72 bytes). Must differ from current_password."}}},"UserResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"email":{"type":"string","format":"email"},"first_name":{"type":"string"},"last_name":{"type":"string"},"organization":{"type":"string"},"org_unit":{"type":"string"},"org_role":{"type":"string"},"display_name":{"type":"string"},"status":{"type":"string","enum":["active","disabled","locked"]},"roles":{"type":"array","description":"Role names held by the user. Built-ins include admin, engineer, analytics_editor and data_viewer (see GET /cdp/api/v1/roles for the full catalogue), but custom roles created via POST /cdp/api/v1/roles are also possible — a role is assignable when it is global or a custom of the account owning the tenant.\n","items":{"type":"string"}},"pii_access_level":{"type":"integer","description":"Maximum PII sensitivity level the user is allowed to access (0 = none, higher = more sensitive)."},"timezone":{"type":"string","description":"The user's display/scheduling IANA timezone (e.g. Europe/Bratislava). Empty = unset: displays fall back to UTC, and schedules the user configures keep each surface's historical evaluation zone. Used as the default zone when this user saves cron schedules and as the viewer zone for analytics bucketing.\n","example":"Europe/Bratislava"},"last_login_at":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"purposes":{"type":"array","description":"Processing purposes the user is authorized for.","items":{"type":"string"},"example":["marketing","analytics"]},"password_change_required":{"type":"boolean","description":"The user must replace a password someone else chose (set by POST /cdp/api/v1/users/add and for an instance administrator whose initial password was generated at installation; cleared by any password change or reset).\n"},"pii_access_level_effective":{"type":"integer","nullable":true,"description":"The user's EFFECTIVE PII clearance in the resolved tenant (multitenancy §4): the tenant's `user_pii_levels` override if one is set, else `pii_access_level`. Additive and detail-endpoint-only — `GET /cdp/auth/users/me` sets it; list responses omit it rather than imply a resolved value for a tenant that was never consulted.\n"}}},"UpdateOwnProfileRequest":{"type":"object","description":"Self-service profile update body (PATCH /users/me). All fields are optional; an omitted/empty field leaves the stored value unchanged.\n","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"organization":{"type":"string"},"org_unit":{"type":"string"},"org_role":{"type":"string"},"display_name":{"type":"string"},"timezone":{"type":"string","description":"IANA timezone name (400 on unknown names). Setting it also rewrites the caller's current session in place, so schedule/analytics defaults pick it up immediately; other sessions catch up on token refresh. To reset, set \"UTC\" (empty leaves the stored value).\n","example":"Europe/Bratislava"}}},"Permission":{"type":"object","description":"A single route permission granted to a role.","required":["object","action"],"properties":{"object":{"type":"string","description":"Route pattern the role may access: a trailing `/*` matches everything below that prefix, and a `:name` segment matches any single path segment.","example":"/cdp/api/v1/profiles/*"},"action":{"type":"string","description":"HTTP method, or '*' for any method.","example":"GET"}}},"CreateRoleRequest":{"type":"object","required":["name"],"properties":{"name":{"type":"string","maxLength":64,"pattern":"^[a-z0-9][a-z0-9_-]{0,63}$","description":"Unique role name. 'root' is reserved and rejected, and the name must match ^[a-z0-9][a-z0-9_-]{0,63}$ (no ':' — Optima reserves that character to namespace an account's custom roles).\n","example":"reporter"},"description":{"type":"string"},"account_id":{"type":"string","description":"Scope of the new role (access-model redesign). Instance administrators (and root keys) only: omitted/empty creates a GLOBAL, built-in-style role; a value creates that account's custom role. An account administrator never sends this — their account is derived from the resolved tenant — and a value naming another account is refused with 403. A custom role may not shadow a global role's name (409).\n","example":"acme"},"permissions":{"type":"array","items":{"$ref":"#/components/schemas/Permission"}}}},"UpdateRoleRequest":{"type":"object","description":"Patches a role. Both fields are optional. A non-null `permissions` REPLACES the role's entire permission set (an empty array clears all grants); omitting `permissions` leaves them untouched.\n","properties":{"description":{"type":"string"},"permissions":{"type":"array","items":{"$ref":"#/components/schemas/Permission"}}}},"RoleResponse":{"type":"object","properties":{"name":{"type":"string"},"account_id":{"type":"string","description":"Empty for a global/built-in role, or the owning account for an account custom role. Custom roles are stored in auth_rules under the namespaced subject `a:<account_id>:<name>`; every membership surface (tenant members, account members, invites) keeps the plain name.\n","example":"acme"},"description":{"type":"string"},"is_system":{"type":"boolean","description":"Built-in roles cannot be deleted (their permissions can still be edited)."},"permissions":{"type":"array","items":{"$ref":"#/components/schemas/Permission"}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"AvailablePermission":{"type":"object","description":"A registered API route an admin can grant to a role.","properties":{"path":{"type":"string","description":"Route as registered (may contain :params).","example":"/cdp/api/v1/profiles/:profile_id"},"methods":{"type":"array","items":{"type":"string"},"example":["GET"]},"suggested_object":{"type":"string","description":"Route pattern ready to use as a Permission.object. A route with path parameters collapses to a \"<prefix>/*\" wildcard covering everything below its first parameter, matching how the built-in roles are written.\n","example":"/cdp/api/v1/profiles/*"}}},"ContactAttribute":{"type":"object","description":"One declaration in the contact-attribute registry.","properties":{"attribute":{"type":"string","description":"Profile attribute holding a contact address."},"contact_kind":{"type":"string","enum":["email","phone"]},"created_by":{"type":"string","description":"Who declared it (`migration` for rows backfilled from existing campaigns and journeys)."},"created_at":{"type":"string","format":"date-time"}}},"DeliveryChannel":{"type":"object","description":"One operator-declared outbound channel. `contact_kind` is drawn from the EXISTING four kinds deliberately: a custom channel declares which of them it uses rather than inventing a fifth, so every line of normalization, identifier lookup, suppression hashing and erasure conversion applies to it unchanged.\n","properties":{"name":{"type":"string","pattern":"^[a-z][a-z0-9_]{1,30}$","example":"call_center","description":"The value stored on campaigns, consent purposes and touches. Immutable."},"label":{"type":"string","example":"Call centre"},"contact_kind":{"type":"string","enum":["email","phone","token","none"]},"identifier_keys":{"type":"array","items":{"type":"string"},"description":"CDP identifier keys carrying the contact, in lookup order. Empty uses the kind's defaults (email → email; phone → phone, phone_number, msisdn).\n"},"template_variant":{"type":"string","default":"webhook","description":"Which built-in message-template variant schema this channel's templates use. `webhook` is a single `body`.\n"},"is_active":{"type":"boolean","default":true},"created_by":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["name","contact_kind"]},"ConsentPurposeObject":{"type":"object","description":"An operator-defined named consent purpose (e.g. `marketing`, `analytics`).","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","example":"marketing"},"description":{"type":"string","example":"Use data for marketing communications"},"lawful_basis":{"type":"string","enum":["consent","legitimate_interest","contract","legal_obligation","vital_interests","public_task"],"description":"GDPR Art. 6 basis. Determines how Gate 3 interprets the absence of a consent row: `consent` (opt-in, missing row blocks), `legitimate_interest` (opt-out, missing row allows, granted=0 is an objection), the four others skip Gate 3 entirely (audited as `not_applicable`).\n"},"on_withdrawal":{"type":"string","enum":["retain","erase"],"description":"`erase` turns an explicit withdrawal of this purpose into a purpose-scoped erasure request — whichever path recorded it (this API's DELETE or `granted: false` POST, Connect imports, Optima Edge, quarantine release), but only when it withdraws an existing grant (a first refusal with no prior grant never erases); `retain` (default) keeps already-collected data. Incompatible with channel-scoped or preference-centre-visible purposes (400) — the withdrawal is the record that must be kept.\n"},"channel":{"type":"string","description":"Marks the purpose channel-scoped (metadata — drives `{channel}` placeholder resolution in campaign consent purposes and preference-centre grouping; no gate reads it). A built-in channel (except `auto`) or an active declared delivery channel.\n"},"topic":{"type":"string","description":"Free-form preference-centre grouping label."},"visible_in_preference_center":{"type":"boolean","description":"Opt-in flag rendering the purpose as a customer toggle on the (Edge-hosted) preference page. Deliberately default-false — operational purposes must never leak into the subject-facing UI.\n"},"is_active":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"descriptions":{"type":"object","additionalProperties":{"type":"string"},"description":"Per-language descriptions keyed by language code (BCP 47-shaped, lower-case primary subtag, e.g. `sk`, `pt-BR`); `description` is the default text rendered when no key matches the visitor's language (exact tag, then primary subtag). Validated at save: keys must be language codes (`default` is refused) of at most 35 bytes, values non-empty and <= 2000 bytes, at most 64 entries — a 400 names the offending key. PUT replaces the whole map. Read by the consent banner (`purpose_details[].descriptions`) and the preference centre (`GET /edge/v1/preferences/{token}?lang=`).\n","example":{"sk":"Meranie používania stránky","de":"Messung der Nutzung"}}}},"ConsentPurposeRequest":{"type":"object","required":["name"],"properties":{"name":{"type":"string","example":"analytics"},"description":{"type":"string"},"lawful_basis":{"type":"string","enum":["consent","legitimate_interest","contract","legal_obligation","vital_interests","public_task"],"default":"consent"},"on_withdrawal":{"type":"string","enum":["retain","erase"],"default":"retain"},"channel":{"type":"string","description":"A channel from GET /cdp/api/v1/channels/effective — a built-in channel or an active declared delivery channel. On update the purpose's current channel is always accepted."},"topic":{"type":"string"},"visible_in_preference_center":{"type":"boolean","default":false},"is_active":{"type":"boolean","default":true,"description":"Omitted means active."},"descriptions":{"type":"object","additionalProperties":{"type":"string"},"description":"Per-language descriptions keyed by language code (BCP 47-shaped, lower-case primary subtag, e.g. `sk`, `pt-BR`); `description` is the default text rendered when no key matches the visitor's language (exact tag, then primary subtag). Validated at save: keys must be language codes (`default` is refused) of at most 35 bytes, values non-empty and <= 2000 bytes, at most 64 entries — a 400 names the offending key. PUT replaces the whole map. Read by the consent banner (`purpose_details[].descriptions`) and the preference centre (`GET /edge/v1/preferences/{token}?lang=`).\n","example":{"sk":"Meranie používania stránky","de":"Messung der Nutzung"}}}},"ConsentPurposeUpdateRequest":{"type":"object","example":{"is_active":false},"description":"Mutable purpose columns (the name is fixed). A partial update: omitted fields keep their stored value; an explicit empty value clears (`channel: \"\"`, `descriptions: {}`); `lawful_basis: \"\"` resets to `consent` and `on_withdrawal: \"\"` to `retain`. An omitted `lawful_basis` is not a basis change, so it never needs `acknowledge_retroactive`.\n","properties":{"description":{"type":"string"},"lawful_basis":{"type":"string","enum":["","consent","legitimate_interest","contract","legal_obligation","vital_interests","public_task"],"description":"Omitted keeps the stored basis; an explicit empty value resets to `consent`."},"on_withdrawal":{"type":"string","enum":["","retain","erase"],"description":"Omitted keeps the stored value; an explicit empty value resets to `retain`."},"channel":{"type":"string","description":"A channel from GET /cdp/api/v1/channels/effective — a built-in channel or an active declared delivery channel. On update the purpose's current channel is always accepted."},"topic":{"type":"string"},"visible_in_preference_center":{"type":"boolean","description":"Omitted keeps the stored value."},"is_active":{"type":"boolean","description":"Omitted keeps the stored value."},"descriptions":{"type":"object","additionalProperties":{"type":"string"},"description":"Per-language descriptions keyed by language code (BCP 47-shaped, lower-case primary subtag, e.g. `sk`, `pt-BR`); `description` is the default text rendered when no key matches the visitor's language (exact tag, then primary subtag). Validated at save: keys must be language codes (`default` is refused) of at most 35 bytes, values non-empty and <= 2000 bytes, at most 64 entries — a 400 names the offending key. Omitted keeps the stored map; an object (including `{}`) replaces it whole. Read by the consent banner (`purpose_details[].descriptions`) and the preference centre (`GET /edge/v1/preferences/{token}?lang=`).\n","example":{"sk":"Meranie používania stránky","de":"Messung der Nutzung"}}}},"ConsentPolicyRequest":{"type":"object","required":["key","version","text"],"properties":{"key":{"type":"string","example":"web_signup_marketing"},"version":{"type":"integer","minimum":1},"locale":{"type":"string","example":"en"},"text":{"type":"string","description":"The exact consent text shown to the subject."},"purposes":{"type":"array","items":{"type":"string"},"description":"Purposes the text covers (must exist in the catalog)."},"is_active":{"type":"boolean","default":true,"description":"Omitted means active. A receipt can reference only an active version."}}},"ConsentPolicyObject":{"type":"object","description":"One immutable version of the consent text a subject was shown.","properties":{"id":{"type":"string","format":"uuid"},"key":{"type":"string"},"version":{"type":"integer"},"locale":{"type":"string"},"text":{"type":"string"},"text_hash":{"type":"string","description":"SHA-256 of the text, computed server-side."},"purposes":{"type":"array","items":{"type":"string"}},"is_active":{"type":"boolean"},"created_by":{"type":"string"},"created_at":{"type":"string","format":"date-time"}}},"ConsentReceiptInput":{"type":"object","required":["policy_key","policy_version"],"description":"Evidence of the consent interaction. The policy text hash is resolved server-side from the referenced consent-policy version — a client can never assert what text was shown, only which stored version.\n","properties":{"policy_key":{"type":"string"},"policy_version":{"type":"integer","minimum":1},"locale":{"type":"string","description":"Locale of the policy row. Omitted resolves to the version's only locale row (400 listing the available locales when there are several); a named locale must match exactly, with no fallback.\n"},"channel":{"type":"string","example":"web","description":"web | mobile | csv_import | api | crm | ..."},"collection_point":{"type":"string","description":"Free-form: form id, screen name, connector id."},"evidence":{"type":"object","additionalProperties":true,"description":"JSON escape hatch (checkbox states, screenshot refs)."}}},"ConsentReceiptObject":{"type":"object","description":"One stored consent receipt (immutable; pseudonymized — never deleted — on erasure).\n","properties":{"receipt_id":{"type":"string","format":"uuid"},"ts":{"type":"string","format":"date-time"},"profile_id":{"type":"string"},"entity_type":{"type":"string"},"purposes":{"type":"array","items":{"type":"string"},"description":"Every purpose the interaction decided."},"granted":{"type":"array","items":{"type":"string"},"description":"The subset granted."},"policy_key":{"type":"string"},"policy_version":{"type":"integer"},"policy_hash":{"type":"string"},"locale":{"type":"string"},"channel":{"type":"string"},"collection_point":{"type":"string"},"actor":{"type":"string"},"ip":{"type":"string"},"user_agent":{"type":"string"},"request_id":{"type":"string"},"evidence":{"type":"string"}}},"ConsentItem":{"type":"object","required":["purpose"],"properties":{"purpose":{"type":"string","example":"marketing"},"granted":{"type":"boolean","default":false},"source":{"type":"string","enum":["implicit","explicit","api"],"example":"explicit"},"expires_at":{"type":"string","format":"date-time","nullable":true,"description":"RFC3339 timestamp when this consent expires. Omit (or null) for no expiration (unlimited). Once expired, the consent is treated as NOT granted by the privacy gate (PII attributes for this purpose are blocked).\n","example":"2027-01-01T00:00:00Z"}}},"SetConsentsRequest":{"type":"object","required":["profile_id","consents"],"properties":{"profile_id":{"type":"string","format":"uuid"},"entity_type":{"type":"string","example":"customer","description":"Optional provenance (the consent key is profile-global). Omitted: derived from the profile, or stored as '' when the profile does not exist yet (out-of-order imports keep working).\n"},"consents":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/ConsentItem"}},"receipt":{"$ref":"#/components/schemas/ConsentReceiptInput"}}},"ConsentObject":{"type":"object","description":"Current consent record for a profile/purpose pair.","properties":{"profile_id":{"type":"string","format":"uuid"},"entity_type":{"type":"string"},"purpose":{"type":"string"},"granted":{"type":"boolean"},"source":{"type":"string"},"consented_at":{"type":"string","format":"date-time"},"expires_at":{"type":"string","format":"date-time","nullable":true,"description":"When this consent expires; null/absent means no expiration (unlimited)."},"updated_at":{"type":"string","format":"date-time"},"receipt_id":{"type":"string","description":"The consent receipt that produced this state; absent/empty means the state was recorded without evidence.\n"}}},"ConsentsBatchRequest":{"type":"object","required":["profile_ids"],"properties":{"profile_ids":{"type":"array","minItems":1,"maxItems":500,"items":{"type":"string","format":"uuid"}}}},"RetentionPolicyRequest":{"type":"object","required":["retain_days"],"properties":{"scope":{"type":"string","enum":["profile_attribute","event","event_attribute"],"default":"profile_attribute","description":"What the policy targets. `profile_attribute` (default) — profile EAV attributes filtered by entity_type/attribute_key/purpose. `event` — whole events of a given event_type. `event_attribute` — a specific attribute within events of a given event_type.\n"},"entity_type":{"type":"string","example":"customer","description":"Required when scope is `profile_attribute`."},"event_type":{"type":"string","example":"page_view","description":"Required when scope is `event` or `event_attribute`."},"attribute_key":{"type":"string","description":"Scope the policy to a single attribute. Optional for the attribute scopes (empty means all attributes); refused for `event`."},"purpose":{"type":"string","description":"Scope the policy to a specific consent purpose. Must be an active purpose; attribute scopes only (events carry no provenance), refused for `event`."},"retain_days":{"type":"integer","minimum":1,"example":365},"on_expiry":{"type":"string","enum":["anonymize","delete"],"default":"anonymize"},"is_active":{"type":"boolean","default":true,"description":"Omit to activate the policy (create and PUT alike); only an explicit `false` leaves it inactive."}}},"RetentionPolicyObject":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"scope":{"type":"string","enum":["profile_attribute","event","event_attribute"]},"entity_type":{"type":"string"},"event_type":{"type":"string"},"attribute_key":{"type":"string"},"purpose":{"type":"string"},"retain_days":{"type":"integer"},"on_expiry":{"type":"string"},"is_active":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"ErasureRequest":{"type":"object","required":["profile_id","entity_type"],"properties":{"profile_id":{"type":"string","format":"uuid"},"entity_type":{"type":"string","example":"customer"},"requested_by":{"type":"string","deprecated":true,"description":"Ignored. The actor is always taken from the authenticated caller."},"scope":{"type":"string","enum":["full","pii_only","purpose","attribute_list"],"default":"full"},"purpose":{"type":"string","description":"Required for, and only valid with, scope=purpose. Must be a known purpose."},"attribute_list":{"type":"array","items":{"type":"string"},"description":"Required (non-empty) for, and only valid with, scope=attribute_list."}}},"ConsentStatsResponse":{"type":"object","required":["series","from","to","granularity"],"properties":{"series":{"type":"array","description":"One row per bucket and purpose with at least one change, ordered by period then purpose.","items":{"$ref":"#/components/schemas/ConsentStatsRow"}},"from":{"type":"string","format":"date-time"},"to":{"type":"string","format":"date-time"},"granularity":{"type":"string","enum":["day","week"]}}},"ConsentStatsRow":{"type":"object","required":["period","purpose","granted","withdrawn"],"properties":{"period":{"type":"string","format":"date-time","description":"Start of the UTC day, or of the UTC ISO week (Monday 00:00)."},"purpose":{"type":"string"},"granted":{"type":"integer","format":"int64","minimum":0},"withdrawn":{"type":"integer","format":"int64","minimum":0}}},"ErasureRequestObject":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"profile_id":{"type":"string","format":"uuid"},"entity_type":{"type":"string"},"requested_by":{"type":"string"},"status":{"type":"string","enum":["pending","in_progress","completed","failed"],"description":"Lifecycle state. `pending` = filed, no pass has run yet;\n`in_progress` = being erased (`phase` says which pass);\n`completed` = every submitted delete is applied and a residual\ncheck finds no row left that the scope deletes; `failed` = the\nlast pass errored (`last_error` says why).\n\nThe status stays `in_progress` from the first pass until the\nsettle pass completes (about the configured sweep delay, default\n60 min, after filing); the data is usually gone within minutes,\nand `completed` confirms no residual rows. Every request runs\nTWICE and is then checked: the first pass deletes the data\n(`phase` `erasing`), then waits for a sweep pass (`phase`\n`sweep_scheduled`, due at `next_check_at`) that removes anything\nwritten while the first one ran, and a settle check (`phase`\n`settling`) marks the request `completed` only once the data\nstore shows every submitted delete applied (`completed_at` is\nthat check) and a residual probe of every table the scope deletes\nfrom finds none of those rows left (narrower scopes only look at\nrows written before the request). A delete that fails or stays\nunapplied for more than 6 hours fails the request with\n`last_error`, and so do rows still present past the sweep delay\nplus 6 hours. A `full` request is first claimed a few minutes\nafter creation, once every data-plane writer has loaded it: from\nthen until 72 hours after completion, writes for that profile are\ndropped. A first pass can span several scheduler ticks: a `full`\nerasure of a profile with events (and a `pii_only` one that falls\nback to a full erasure) deletes the event rows only once their\nattribute rows are gone, and between those ticks the request\nreads `pending` again. A child delete unapplied for more than 6\nhours, or failing in the data store, ends the pass as `failed`;\nso does a state read that keeps timing out on a request older\nthan 24 hours (younger ones are re-pended). The system re-pends a\n`failed` request after 30 minutes, up to 5 attempts, after which\nit stays `failed` for operator attention\n(`GET /privacy/erasure?status=failed`).\n"},"phase":{"type":"string","enum":["erasing","sweep_scheduled","settling"],"description":"Which pass an `in_progress` request is in; absent for every other\nstatus. `erasing` = a deletion pass (the first or the sweep pass)\nis running; `sweep_scheduled` = the first pass is done and the\nsweep pass is due at `next_check_at`; `settling` = the sweep pass\nis done and the settle check is confirming that every delete\napplied and no rows are left.\n"},"next_check_at":{"type":"string","format":"date-time","description":"When the sweep pass of a `sweep_scheduled` request becomes due.\nThe scheduler picks it up on its next tick after that time, so a\nvalue in the past means it is due now. Present only with `phase`\n`sweep_scheduled`, and absent when the sweep pass is due at once.\n"},"scope":{"type":"string"},"purpose":{"type":"string"},"attribute_list":{"type":"array","items":{"type":"string"}},"completed_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"last_error":{"type":"string","description":"Why the erasure job last failed this request: an executor error, a state read that kept timing out, or a data-store delete that failed or stalled (its fail reason). Absent once the request moves on.\n"}}},"AuditLogEntry":{"type":"object","description":"Single privacy audit log entry representing one data access or mutation.","properties":{"event_id":{"type":"string","format":"uuid"},"ts":{"type":"string","format":"date-time"},"actor":{"type":"string","description":"API key or user ID that performed the operation."},"operation":{"type":"string","description":"What was done: `read`, `write`, `delete`, `export`, `merge`,\n`llm_summary` (profile data sent to an LLM),\n`collection_blocked`, `purpose_basis_change` and others. Not a\nclosed set.\n","example":"read"},"entity_type":{"type":"string"},"profile_id":{"type":"string"},"purpose":{"type":"string"},"attributes":{"type":"array","items":{"type":"string"},"description":"Attribute keys touched by the operation. On a `redacted` row,\nonly the withheld keys; identifier keys whose value was withheld\nare listed by name.\n"},"consent_status":{"type":"string","description":"The consent outcome the row was decided with: `granted` (every\nconsent-gated attribute allowed), `withdrawn` (some withheld),\n`absent` (all withheld, or no consent record), `not_applicable`\n(the attributes' purposes are not consent-based), `not_required`\n(no consent gate applied, e.g. a refusal or an identifier read)\nand `denied` (a withheld external signal). Not a closed set.\n","example":"granted"},"request_id":{"type":"string"},"result":{"type":"string","description":"Outcome of the operation. Reads and exports: `allowed` (nothing\nwithheld; `attributes` lists every attribute read), `redacted`\n(`enforce` or `strict` withheld attributes, identifier values or\nhistory entries; `attributes` lists only the withheld ones),\n`blocked` (refused before any data was read or written, e.g. the\nstrict-mode `purpose_required` 403; `operation` is `read` for\nGET/HEAD, `delete` for DELETE, `write` otherwise). In the\nnon-blocking modes `audit` and `off` nothing is withheld and a\nread records what `enforce` would have withheld instead:\n`pii_level_exceeded` (an attribute or identifier value above the\ncaller's PII level), `attribute_purpose_blocked`,\n`consent_blocked` or `provenance_blocked`, or `denied` for a\ndenial without a reason. A withheld external signal records\n`signal_purpose_blocked`. A write refused by the purpose\ncollection check records `purpose_collection_blocked`. An\n`llm_summary` row records `allowed llm=<provider> model=<model>\npii_ceiling=<level>`. Consent-gated collection records\n`dropped`, `quarantined`, `would_drop` and `would_quarantine`\n(collection gate in `audit`), and `released` when a quarantined\nevent is released. Not a closed set: new reasons may be added.\n","example":"redacted"},"would_block":{"type":"array","items":{"type":"string"},"description":"Attributes the stricter tagged consent-scope rule would\nhave withheld while the effective scope did not (recorded when\nrunning in `shadow`). Empty/absent otherwise.\n"},"via_connection":{"type":"string","format":"uuid","description":"The remote MCP connection (`GET /cdp/api/v1/mcp/connections` id)\nthe request came through. Set only when the remote MCP server forwarded\n`X-Optima-Connection` for an OAuth connection owned by the calling\nAPI key. Absent for console sessions, raw API keys and direct API\ncalls.\n"}}},"AttributePurposesRequest":{"type":"object","required":["attribute_purposes"],"properties":{"attribute_purposes":{"type":"object","description":"Map of attribute name → list of required consent purposes.","additionalProperties":{"type":"array","items":{"type":"string"}},"example":{"email":["marketing","analytics"],"phone":["marketing"]}}}},"CallerPurposesRequest":{"type":"object","required":["purposes"],"properties":{"purposes":{"type":"array","items":{"type":"string"},"example":["marketing","analytics"]}}},"PIIAccessLevelRequest":{"type":"object","properties":{"pii_access_level":{"type":"integer","nullable":true,"minimum":0,"example":2,"description":"Nullable so a `null` (clear the tenant override, restoring the instance default) is distinguishable from an omitted field. The application endpoint, and the user endpoint's `scope=instance_default` branch, both require this non-null — neither has anything to fall back to.\n"},"scope":{"type":"string","enum":["tenant","instance_default"],"description":"User endpoint only (ignored by the application endpoint). `tenant` (default) sets or clears the resolved tenant's PII override; `instance_default` sets the instance-wide default column and stays instance-persona only.\n","example":"tenant"}}},"CreateApplicationRequest":{"type":"object","required":["name"],"properties":{"name":{"type":"string","example":"marketing-pipeline"},"description":{"type":"string","example":"Key used by the marketing ingestion pipeline"}}},"UpdateApplicationRequest":{"type":"object","required":["name"],"description":"Updates application metadata. The API key, root flag, and PII access level are NOT settable here.","properties":{"name":{"type":"string","example":"marketing-pipeline"},"description":{"type":"string","example":"Updated description"}}},"SetApplicationEnabledRequest":{"type":"object","required":["enabled"],"properties":{"enabled":{"type":"boolean","description":"Set false to revoke (disable) the application's keys; true to re-enable.","example":false}}},"MCPConnection":{"type":"object","description":"A connected AI app (remote MCP OAuth connection). Never includes key material or token hashes.","properties":{"id":{"type":"string","format":"uuid"},"client_name":{"type":"string"},"redirect_host":{"type":"string"},"application_id":{"type":"string","format":"uuid"},"application_name":{"type":"string"},"status":{"type":"string","enum":["pending","active","revoked","key_invalid","expired"]},"created_at":{"type":"string","format":"date-time"},"last_used_at":{"type":"string","format":"date-time","nullable":true},"last_ip":{"type":"string"},"revoked_at":{"type":"string","format":"date-time","nullable":true},"revoked_by":{"type":"string","description":"User email, or app:<application id> for an API-key caller."}}},"ApplicationResponse":{"type":"object","description":"Management view of an application. Never includes key material (hashes).","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string"},"mcp_connection_count":{"type":"integer","description":"Live connected AI apps (remote MCP OAuth connections) minted for this key. Populated on the tenant list and the account list; 0 elsewhere."},"enabled":{"type":"boolean"},"is_root":{"type":"boolean"},"pii_access_level":{"type":"integer"},"tenant_id":{"type":"string","description":"The tenant this key is pinned to (multitenancy §4). Stamped at creation from the caller's resolved tenant; existing pre-multitenancy rows read as `default`."},"roles":{"type":"array","items":{"type":"string"},"description":"The key's catalog roles (access-model redesign). Plain role names — the same vocabulary a user's tenant membership uses — enforced like a session's roles. Always present; `[]` means the key relies on its per-hash extra grants alone. Edited via PUT /applications/{id}/roles."},"cross_tenant_allowed":{"type":"boolean","description":"Provider-operator flag: whether the key may select a tenant with `X-Tenant`. Present ONLY for the instance persona (root key or `instance_admin`) — omitted entirely for a tenant admin, who can neither read nor change it. Edited via PUT /applications/{id}/instance-flags."},"delegation_allowed":{"type":"boolean","description":"Provider-operator flag: whether the key may present `X-On-Behalf-Of`. Instance persona only, like `cross_tenant_allowed`."},"delegation_enforces_user_roles":{"type":"boolean","description":"Provider-operator flag: when true, the key must send `X-On-Behalf-Of` on every request, and each request is authorized against both the key's own roles and the acting user's roles (both must allow the route). Instance persona only, like `delegation_allowed`."},"previous_key_expires_at":{"type":"string","format":"date-time","description":"When the rotated-out key stops authenticating. Present only while a previous key is inside its rotation grace window (instance setting `api_key_rotation_grace_hours`)."},"key_rotation_grace_hours":{"type":"integer","description":"The instance's current rotation grace window in hours (0 = none)."},"created_at":{"type":"string"},"updated_at":{"type":"string"}}},"SetApplicationRolesRequest":{"type":"object","description":"Replaces the key's catalog role set wholesale. An empty/absent array clears it back to per-hash-grant-only.","properties":{"roles":{"type":"array","items":{"type":"string"},"example":["engineer","vip_agent"]}}},"ApplicationGrantsRequest":{"type":"object","description":"Replaces the key's per-hash extra route grants wholesale. An empty array removes every extra grant.","properties":{"permissions":{"type":"array","items":{"$ref":"#/components/schemas/Permission"}}}},"ApplicationGrantsResponse":{"type":"object","properties":{"permissions":{"type":"array","items":{"$ref":"#/components/schemas/Permission"}}}},"CreatedApplicationResponse":{"type":"object","description":"Returned by create and rotate. Includes the plaintext API key, shown only once.","allOf":[{"$ref":"#/components/schemas/ApplicationResponse"},{"type":"object","properties":{"api_key":{"type":"string","description":"Plaintext API key — store it now; it is never retrievable again."}}}]},"PIIAccessLevelEntry":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","enum":["application","user"]},"pii_access_level":{"type":"integer"},"has_override":{"type":"boolean","description":"Whether a per-tenant override row (`user_pii_levels`) actually exists behind `pii_access_level` — always `false` for `application` entries. Distinct from \"the level equals the instance default\": an override whose value happens to match the default is still an override."}}},"TemplateResponse":{"type":"object","properties":{"name":{"type":"string","example":"email_verification"},"subject_tmpl":{"type":"string","example":"[Optima] Verify your email address"},"body_tmpl":{"type":"string","example":"Hello {{if .first_name}}{{.first_name}}{{else}}there{{end}}, ..."},"body_html_tmpl":{"type":"string","description":"The HTML body (html/template, auto-escaping) when the template's body format is html; empty for a plain-text template. Exactly one of body_tmpl / body_html_tmpl is set.\n"},"reserved":{"type":"boolean","description":"True for the three reserved auth templates (`password_reset`, `email_verification`, `tenant_invite`). The console renders the editor read-only when true and the caller lacks the persona below — writes are still enforced server-side regardless of what the console shows.\n"},"write_allowed":{"type":"boolean","description":"Whether THIS caller may create/update/delete the template, computed by the same gate the write endpoints enforce. Always true for a non-reserved name; for a reserved one true only for the persona (`password_reset`/`email_verification`: the instance operator in the default tenant; `tenant_invite`: a full tenant administrator). The console disables the editor only when `reserved` is true and this is false.\n"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"CreateTemplateRequest":{"type":"object","description":"A template carries EITHER a plain-text body or an HTML body, never both and never neither — supplying both, or neither, is a 400.\n","required":["name","subject_tmpl"],"properties":{"name":{"type":"string","example":"welcome_email"},"subject_tmpl":{"type":"string","example":"Welcome to Optima, {{.first_name}}!"},"body_tmpl":{"type":"string","description":"The plain-text body (text/template). Omit for an HTML template.","example":"Hello {{.first_name}}, your account is ready."},"body_html_tmpl":{"type":"string","description":"The HTML body (html/template, auto-escaping). Omit for a plain-text template."}}},"SubscriptionResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"receiver":{"type":"string","enum":["user","app"]},"receiver_id":{"type":"string","format":"uuid"},"event_type":{"type":"string","example":"validation_failed"},"channel":{"type":"string","enum":["email","webhook"]},"filters":{"type":"object","additionalProperties":true,"description":"Filter conditions as stored. Each key is a payload field name; the value is either a plain JSON value (JSON-equality) or an operator rule `{\"op\": \"<operator>\", \"value\": <value>}` — see CreateSubscriptionRequest.filters for the full grammar. Empty object matches all events.\n"},"webhook_url":{"type":"string","format":"uri","description":"Delivery target for channel=webhook subscriptions."},"enabled":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"secret_configured":{"type":"boolean","description":"The subscription signs with its own secret (`X-Optima-Signature: v2=…`). False on a webhook subscription created before per-subscription secrets: its deliveries fail until the secret is rotated.\n"},"secret":{"type":"string","example":"whsec_3f1b2a90c4d84e0f9a8b7c6d5e4f3a2b3f1b2a90c4d84e0f9a8b7c6d5e4f3a2b","description":"The plaintext signing secret. Present ONLY in the create response of a webhook subscription, the update response that switches a subscription without a secret to channel=webhook, and the rotate response; never stored in the clear and never returned again.\n"}}},"CreateSubscriptionRequest":{"type":"object","required":["receiver","receiver_id","event_type","channel"],"properties":{"receiver":{"type":"string","enum":["user","app"],"description":"`user` delivers to the user's stored email address; `app` delivers to the webhook URL supplied as `_webhook_url` in the notification data (webhook channel).\n"},"receiver_id":{"type":"string","format":"uuid"},"event_type":{"type":"string","description":"Event type to subscribe to. Data-change events are derived from the platform's own write activity and fire on every matching data update: `event.created`, `event.updated`, `event.deleted`, `profile.created`, `profile.updated`, `profile.deleted`, `profile.merged`, `consent.updated`, `consent.withdrawn`, `dataset.record.created`, `dataset.record.updated`, `dataset.record.deleted`, `dataset.deleted`. Custom application event types are also accepted (free-form string). `profile.updated` also fires for attribute removals — the payload then carries the deleted keys in `removed_keys` (alongside any `attribute_keys` upserted in the same request).\n**Breaking change: payloads carry ids and CHANGED KEYS, never attribute/identifier VALUES.** A subscriber that needs the values reads them back through the ordinary CDP API, under its own purpose/PII grants — this disclosure path runs before any Gate 2/3/4 privacy check, so raw values never rode it safely.\n","example":"profile.updated"},"channel":{"type":"string","enum":["email","webhook"],"description":"`email` requires a user receiver (delivered to the user's login email). App receivers must use `webhook` — an application has no email address, so `receiver: app` with `channel: email` is rejected with 400. A user receiver cannot use `webhook` either — a user has no webhook address — so `receiver: user` with `channel: webhook` is rejected with 400 on create and update.\n"},"filters":{"type":"object","additionalProperties":true,"description":"Optional filter conditions matched against the notification's data payload; every key must match for the subscription to fire. Each key is a payload field name; dotted keys reach nested maps in the payload by traversal. An exact top-level key always wins over traversal — if a payload contains a literal key `\"a.b\"`, a filter key `\"a.b\"` matches it directly and never walks into nested `a`. A missing path segment or non-map intermediate counts as absent (matches `not_exists`, fails everything else). Its value is either a plain JSON value (matched by JSON equality, same as `eq`) or an operator rule object with exactly the keys `op` (and `value`, where the operator takes one): `{\"op\": \"gt\", \"value\": 5}`. Supported operators: `eq` (equal), `ne` (not equal), `gt`/`gte`/`lt`/`lte` (numeric ordering — both the payload value and `value` must be numbers), `contains` (substring match on a string payload value, or element match on an array payload value — including `attribute_keys`/`identifier_keys`/`set_keys`), `exists`/`not_exists` (test presence of the payload key; `value` is omitted, e.g. `{\"op\": \"exists\"}`). Saving a subscription rejects an unknown operator, a malformed rule shape, a non-numeric value for an ordering operator, or a key naming `attributes`/`identifiers` (or a `attributes.*`/`identifiers.*` dotted path) — see below — with 400 at save time; at match time an unrecognized rule fails closed (never matches, never errors).\n**Breaking change: data-change payloads carry ids and CHANGED KEYS, never attribute/identifier VALUES** — profiles: `profile_id`, `entity_type`, `attribute_keys`, `identifier_keys` (a profile.updated caused by `remove_attributes` / `remove_identifiers` additionally carries `removed_keys` / `removed_identifier_keys`); events (created): `event_id`, `profile_id`, `entity_type`, `event_type`, `timestamp`, `source`, `attribute_keys`; events (updated): `event_id`, `profile_id`, `entity_type`, `source`, `set_keys`, `removed_keys` — `entity_type` is `\"\"` (present, not omitted) when the update carried no signal-invalidation effect; `event_type` is present when the update's producer carries it (every producer since 2026-10-09) and OMITTED — never `\"\"` — for an older one (a `\"\"` value would silently mismatch an `event_type` filter/template); consents (unchanged): `profile_id`, `entity_type`, `purpose`, `granted`; dataset records: `dataset_name`, `record_id`, `record_key`, `attribute_keys`. A subscriber that needs a value reads it back through the ordinary CDP API. A filter saved before this change that targeted `attributes.*`/`identifiers.*` now fails closed (never matches — it is rejected outright on any subsequent save).\n","example":{"entity_type":"customer","attribute_keys":{"op":"contains","value":"email"}}},"webhook_url":{"type":"string","format":"uri","description":"Absolute http(s) URL the notification is POSTed to for channel=webhook. Required when receiver=app (subscription-driven payloads carry no `_webhook_url`). Deliveries are HMAC-signed via `X-Optima-Signature` and SSRF-guarded (private/loopback/metadata ranges blocked unless allow-listed).\n","example":"https://example.com/hooks/cdp"},"enabled":{"type":"boolean","default":true}}},"CustomDatasetDefinition":{"type":"object","description":"Schema definition for an operator-defined custom dataset.","required":["name"],"properties":{"id":{"type":"string","format":"uuid","readOnly":true},"name":{"type":"string","description":"Unique dataset name (e.g. \"products\", \"campaigns\").","example":"products"},"description":{"type":"string"},"attribute_types":{"type":"object","description":"Map of attribute key → value type (string|decimal|integer|boolean|datetime|json|array_string).","additionalProperties":{"type":"string","enum":["string","decimal","integer","boolean","datetime","json","array_string"]},"example":{"name":"string","price":"decimal","in_stock":"boolean","tags":"array_string"}},"strict":{"type":"boolean","description":"When true, attributes not declared in attribute_types are rejected at ingest.","default":false},"pii_attributes":{"type":"object","description":"PII sensitivity level per attribute key (1–3, higher = more sensitive).","additionalProperties":{"type":"integer","minimum":1,"maximum":3}},"created_at":{"type":"string","format":"date-time","readOnly":true},"updated_at":{"type":"string","format":"date-time","readOnly":true}}},"CustomDatasetRecordInput":{"type":"object","description":"A single record to upsert into a custom dataset. Attributes are merged: keys in `attributes` are added or overwritten, omitted keys keep their stored values, and keys in `remove_attributes` are deleted. A key may not appear in both `attributes` and `remove_attributes`. Strict-mode and data-contract validation apply; a contract-`required` attribute cannot be removed. Changes are recorded in `h_custom_dataset_attributes`.\n","required":["record_key"],"properties":{"record_key":{"type":"string","description":"Natural deduplication key (e.g. product SKU, campaign ID).","example":"SKU-001"},"source":{"type":"string","description":"Origin of the record (api | import | manual). Defaults to \"api\".","example":"import"},"attributes":{"type":"object","description":"Attribute values to add or overwrite for this record.","additionalProperties":true,"example":{"name":"Running Shoes","price":89.99,"in_stock":true,"tags":["sport","summer"]}},"remove_attributes":{"type":"array","description":"Attribute keys to delete from the record.","items":{"type":"string"},"example":["clearance_price"]}}},"CustomDatasetRecordObject":{"type":"object","description":"A record returned from a custom dataset.","properties":{"id":{"type":"string","format":"uuid"},"dataset_name":{"type":"string"},"record_key":{"type":"string"},"source":{"type":"string"},"attributes":{"type":"object","additionalProperties":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"ProfileDatasetLinkObject":{"type":"object","description":"A profile–record association in a custom dataset.","properties":{"profile_id":{"type":"string","format":"uuid"},"record_key":{"type":"string"},"dataset_name":{"type":"string"},"link_type":{"type":"string","example":"purchased"},"created_at":{"type":"string","format":"date-time"}}},"HistoryValue":{"type":"object","description":"A typed attribute value in a history entry.","properties":{"type":{"type":"string","enum":["string","decimal","integer","boolean","datetime","json","array_string"],"description":"Value type. Omitted when `value_unknown` is true."},"value":{"description":"The actual typed value."},"value_unknown":{"type":"boolean","description":"True when the old value for an `update` entry is not available because the attribute was written before history tracking was enabled.\n"}}},"HistoryEntry":{"type":"object","description":"A single recorded change in the audit trail.","properties":{"timestamp":{"type":"string","format":"date-time","description":"When the change was recorded."},"scope":{"type":"string","enum":["profile","attributes","identifiers","links","consents"],"description":"Which aspect of the entity changed."},"action":{"type":"string","enum":["insert","update","delete"]},"key":{"type":"string","description":"Attribute or identifier key. Present for `attributes`, `identifiers`, and `consents` scopes."},"old_value":{"$ref":"#/components/schemas/HistoryValue","description":"Value before the change. Null for `insert`."},"new_value":{"$ref":"#/components/schemas/HistoryValue","description":"Value after the change. Null for `delete`."},"source":{"type":"string","description":"Origin system. Present when recorded on the history row."},"redacted":{"type":"boolean","description":"True when the entry's values were withheld by the privacy gates (PII level / purpose / consent) — the change stays visible, its data does not.\n"}}},"HistoryResponse":{"type":"object","description":"Audit trail response envelope.","properties":{"entity_id":{"type":"string","format":"uuid"},"total":{"type":"integer","description":"Total entries matching the filter (capped at 5000)."},"entries":{"type":"array","items":{"$ref":"#/components/schemas/HistoryEntry"}},"next_cursor":{"type":"string","description":"Opaque pagination cursor. Present when more entries exist beyond this page. Pass as `cursor` in the next request.\n"}}},"AnalyticsSource":{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["profiles","events","custom_dataset"]},"entity_type":{"type":"string","description":"Required when type = profiles (the entity being aggregated). On the events and custom_dataset sources it is optional and means something different: the entity type that profile-scoped filter conditions (`profile.*`, `event.*`, `consent.*`, …) resolve against. Required as soon as `filters` uses one of those namespaces.\n"},"event_type":{"type":"string","description":"Required when type = events."},"dataset_name":{"type":"string","description":"Required when type = custom_dataset."}}},"AnalyticsMetric":{"type":"object","required":["function"],"properties":{"function":{"type":"string","enum":["count","count_distinct","sum","avg","min","max"]},"field":{"type":"string","description":"Required for every function except count."},"alias":{"type":"string"}}},"AnalyticsDimension":{"type":"object","required":["field"],"properties":{"field":{"type":"string"},"granularity":{"type":"string","enum":["day","week","month","year"],"description":"Date bucketing; only valid on built-in datetime columns."},"alias":{"type":"string"}}},"AnalyticsTimeRange":{"type":"object","properties":{"field":{"type":"string","description":"Built-in datetime column; defaults to the source's primary timestamp."},"from":{"type":"string","description":"Inclusive lower bound (YYYY-MM-DD or RFC3339)."},"to":{"type":"string","description":"Upper bound. A date (YYYY-MM-DD) includes that whole day in the query timezone; a timestamp (YYYY-MM-DDThh:mm[:ss] or RFC3339) is an inclusive instant."}}},"AnalyticsOrderBy":{"type":"object","required":["field"],"properties":{"field":{"type":"string","description":"A selected metric/dimension output alias."},"direction":{"type":"string","enum":["asc","desc"]}}},"FunnelStep":{"type":"object","required":["event_type"],"properties":{"event_type":{"type":"string"},"label":{"type":"string","description":"Display label; defaults to event_type."},"filters":{"type":"object","description":"Optional react-querybuilder tree evaluated against each candidate event of this step's type, in the row-native grammar (this event type's own built-in columns and attribute keys — see QueryDefinition.filters). An event that fails the filter does not advance the funnel, so the profile stops at the previous step. Two steps may use the same event_type with different filters. Independent of the funnel-level filters, which select the profiles the funnel runs over.\n"}}},"EventRef":{"type":"object","required":["event_type"],"properties":{"event_type":{"type":"string"}}},"QueryDefinition":{"type":"object","required":["type"],"description":"Bounded JSON query grammar. No raw SQL is accepted; only allow-listed\nfunctions, operators, and granularities are emitted.\n  - type = aggregate: uses source + metrics + dimensions + filters.\n  - type = funnel:    uses entity_type + steps (each with optional per-step\n    filters) + window_days + filters.\n  - type = retention: uses entity_type + cohort_event + activity_event + granularity + periods.\n","properties":{"type":{"type":"string","enum":["aggregate","funnel","retention"]},"source":{"$ref":"#/components/schemas/AnalyticsSource"},"metrics":{"type":"array","items":{"$ref":"#/components/schemas/AnalyticsMetric"}},"dimensions":{"type":"array","items":{"$ref":"#/components/schemas/AnalyticsDimension"}},"filters":{"type":"object","description":"react-querybuilder JSON filter tree. Which grammar it is read in\ndepends on the query's unit of evaluation:\n  - **Profile-scoped** (the shared querybuilder grammar: `profile.*`,\n    `identifier.*`, `event.*`, `consent.*`, `signal.*`, `dataset.*`,\n    `related.*`, `computed.*`) for the `profiles` source and for\n    funnel/retention queries, whose rows are profiles. On a\n    retention query the filter selects which profiles enter a\n    cohort (it is applied to the cohort-defining subquery;\n    returning activity is not filtered). `cohort.*` works for every cohort:\n    a materialized one translates to a native subquery, a lazy\n    one ships its current members to the analytics store as an external\n    table. A lazy cohort is evaluated within the query's own\n    timeout and may ship at most 1,000,000 members; beyond either\n    the run is refused with a 400 asking to materialize the cohort.\n    A report run that used a lazy cohort is not cached.\n  - **Row-native** for the `events` and `custom_dataset` sources,\n    whose rows are events / dataset records. Field names are the same\n    vocabulary metrics and dimensions use: a built-in column of the\n    source (`timestamp`, `event_type`, `profile_id`, `record_key`,\n    `id`, `created_at`) or an attribute key of the source's schema.\n    Prefix a field with `attr.` to force attribute resolution for a\n    key that collides with a built-in column name, or with a\n    namespace below.\nOn the `events` and `custom_dataset` sources the two grammars **mix\nfreely in one tree**, under any combinator: a field in a\nprofile-scoped namespace is evaluated against the profile the row\nbelongs to (for a dataset record, against any profile linked to it),\nas a semi-join — so a record linked to several matching profiles is\nstill counted once, and `amount > 100 OR profile.country = 'US'`\nkeeps rows whose profile no longer exists. Doing this requires\n**`source.entity_type`** to be set on the events/custom_dataset\nsource: it scopes which profiles the condition resolves against, and\nwithout it the referenced attributes' PII levels and purposes cannot\nbe resolved. A request that uses a profile-scoped field without it is\nrejected. Per-step funnel filters judge a single event row and do\n**not** accept profile-scoped fields — the funnel-level `filters`\ncovers every step.\nOperators are the shared allow-list (`=`, `!=`, `<`, `<=`, `>`, `>=`,\n`in`, `not_in`, `contains`, `begins_with`, `ends_with`, `null`,\n`not_null`, `between`); row-native filters additionally reject\noperators that make no sense for the attribute's declared type (no\n`contains` on a number, no ordering on a boolean). Values are coerced\nto the attribute's declared type, so datetime comparisons take\n`YYYY-MM-DD` or RFC3339 strings. A comparison, `in` or `between`\nvalue on a UUID column (`id`, `profile_id`) must be a UUID in the\ncanonical 8-4-4-4-12 form, or the query answers 400\n`<column>: value is not a valid UUID ...` (the value is not\nechoed); the like-operators match the id as text, so a partial id\nworks. Nesting is capped at 3 levels.\nAttributes referenced by a filter count towards the report's\n`min_pii_level_required` and `required_purposes`.\n"},"time_range":{"$ref":"#/components/schemas/AnalyticsTimeRange"},"order_by":{"type":"array","items":{"$ref":"#/components/schemas/AnalyticsOrderBy"}},"limit":{"type":"integer"},"cache_ttl_seconds":{"type":"integer","description":"Per-report cache TTL override. 0 disables caching."},"timezone":{"type":"string","description":"IANA zone the query's datetimes are read in: zone-less time_range/filter values parse in it and granularity buckets (day/week/month/year, retention cohorts) align to its calendar. An explicit value pins the report to that zone (validated at save); empty resolves at run time to the viewing user's profile timezone, else UTC (the historical behaviour). The effective zone is part of the result cache identity.\n","example":"Europe/Bratislava"},"entity_type":{"type":"string","description":"Required for funnel and retention queries."},"steps":{"type":"array","description":"Ordered funnel steps (type = funnel; at least two).","items":{"$ref":"#/components/schemas/FunnelStep"}},"window_days":{"type":"integer","description":"Funnel conversion window in days (type = funnel; default 7)."},"cohort_event":{"allOf":[{"$ref":"#/components/schemas/EventRef"}],"description":"Cohort-defining event (type = retention)."},"activity_event":{"allOf":[{"$ref":"#/components/schemas/EventRef"}],"description":"Returning-activity event (type = retention)."},"granularity":{"type":"string","enum":["day","week","month"],"description":"Retention period granularity (type = retention; default week)."},"periods":{"type":"integer","description":"Number of retention period offsets to compute (type = retention; default 8)."}}},"ReportObject":{"type":"object","required":["name","definition"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string"},"definition":{"$ref":"#/components/schemas/QueryDefinition"},"visualization":{"type":"object","description":"Opaque UI-owned chart config; stored and returned verbatim (the backend never reads or validates it). The web console writes a ChartSpec here — `kind` plus the column-role mapping the report was last drawn with — and tolerates an absent, older or newer spec by falling back to a chart derived from the result's shape. Documented below for readers, NOT enforced: clients may store any object.","properties":{"kind":{"type":"string","enum":["bar","column","line","area","pie","donut","stat","heatmap","scatter","funnel","table"],"description":"Chart form. Which forms apply depends on definition.type."},"label":{"type":"string","description":"Result column driving the category axis. \"\" = deliberately none."},"series":{"type":"string","description":"Result column whose distinct values become series."},"values":{"type":"array","items":{"type":"string"},"description":"Numeric result columns plotted. With `series` set only the first is used; on `scatter` the first two are the x and y axes."},"stacked":{"type":"boolean"},"show_values":{"type":"boolean"},"limit":{"type":"integer","description":"Max categories drawn; the remainder is reported, not dropped silently."}}},"min_pii_level_required":{"type":"integer","description":"Computed by the backend at create/update; read-only."},"required_purposes":{"type":"array","items":{"type":"string"},"description":"Computed by the backend at create/update; read-only."},"folder":{"type":"string","description":"Materialized folder path, e.g. \"Campaign reports/2025/Prolongation\"; \"\" = root. Normalised server-side (segments trimmed, empties dropped)."},"tags":{"type":"array","items":{"type":"string"},"description":"Free-form labels for discovery. Normalised server-side (trimmed, de-duplicated case-insensitively)."},"created_by":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"ReportFacets":{"type":"object","description":"Distinct folder paths and tags across all reports.","properties":{"folders":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}}}},"MetricObject":{"type":"object","required":["name","definition"],"description":"A named scalar KPI the scheduler recomputes on its own interval and alerts on when it moves. Shares the analytics aggregate grammar with reports, constrained to exactly one metric and no dimensions.","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string"},"definition":{"allOf":[{"$ref":"#/components/schemas/QueryDefinition"}],"description":"Must be type=aggregate with exactly one entry in `metrics` and no `dimensions` — a metric is one number. Any absolute `time_range.from`/`to` is STRIPPED on save; only `time_range.field` survives, because the measurement window is the rolling `window_days` resolved at every check."},"unit":{"type":"string","description":"Display suffix owned by the UI ('€', 'orders'); never interpreted."},"window_days":{"type":"integer","minimum":0,"maximum":3650,"default":0,"description":"Rolling lookback in whole days, resolved fresh at every check. 0 means no time filter at all (e.g. \"total number of profiles\"), which is a valid metric — not \"zero days of data\"."},"check_interval_minutes":{"type":"integer","minimum":5,"maximum":525600,"default":1440,"description":"How often the scheduler recomputes. Values below 5 are clamped to 5."},"enabled":{"type":"boolean"},"alert_enabled":{"type":"boolean"},"alert_direction":{"type":"string","enum":["increase","decrease","both"],"default":"both","description":"Relative rules only (ignored when alert_kind is absolute)."},"alert_change_pct":{"type":"number","default":15,"description":"Relative rules only. Relative move against the previous value that fires an alert."},"alert_min_value":{"type":"number","default":0,"description":"Relative rules only. Noise floor. Movement is ignored while the larger of the previous and current value is below this, so low-volume metrics do not alert on a 2 -> 1 \"50% drop\"."},"alert_cooldown_minutes":{"type":"integer","minimum":0,"maximum":525600,"default":1440,"description":"Quiet period after a fired alert, so an oscillating metric cannot mail repeatedly."},"alert_kind":{"type":"string","enum":["relative","absolute","no_data","period_over_period"],"default":"relative","description":"relative fires on a percentage move against the previous value (alert_direction, alert_change_pct, alert_min_value apply). absolute alerts ONCE PER EXCURSION: when the value is above alert_above or below alert_below and no alert was delivered for the current excursion yet. A value that stays beyond the bound does not re-alert; returning inside the band (at or between the bounds) ends the excursion, and a direct jump from above to below starts a new one. The first evaluation of a metric only establishes a baseline and never alerts; a value that is already beyond a bound then alerts on the next check. The cooldown defers rather than drops: a crossing it suppresses is delivered by the first check after the cooldown that still sees the value beyond the bound. Any edit of the metric re-arms the rule. An absolute rule needs at least one bound (400 otherwise). no_data alerts ONCE PER SPELL when the metric has returned no value (no rows, NULL, NaN) or zero for alert_stale_minutes; it re-arms when data returns. period_over_period is the relative rule measured against the value recorded alert_compare_days ago (the stored point nearest that instant, within one check interval); without such a point, or when the metric's window length changed since, the check skips with no_comparison_baseline."},"alert_above":{"type":"number","nullable":true,"description":"Absolute rule only. Alert when the value rises past this. Null = not watched. Ignored for no_data and period_over_period rules."},"alert_below":{"type":"number","nullable":true,"description":"Absolute rule only. Alert when the value falls past this. Null = not watched. With both bounds, alert_below must be less than alert_above (400 otherwise). Ignored for no_data and period_over_period rules."},"alert_stale_minutes":{"type":"integer","minimum":5,"maximum":525600,"default":60,"description":"no_data rule only. How long the metric must stay without data before the alert fires. Timing is bounded by the check interval: the clock starts at the first check that sees no data and the alert fires at the first check at or after start + this many minutes, so with the defaults (check interval 1440, stale 60) the first alert comes about 24 hours after data stops."},"alert_compare_days":{"type":"integer","enum":[1,7],"default":7,"description":"period_over_period rule only. Compare with the value recorded this many days ago."},"alert_recipients":{"type":"array","items":{"type":"string","format":"email"},"description":"Email addresses of ACTIVE users who are members of this tenant. Validated on write (400 naming any ineligible address) and re-validated at send time, so removing someone from the workspace stops their alerts without editing every metric. Free-form addresses are deliberately rejected. Empty falls back to the metric's creator. Maximum 25. See GET /cdp/api/v1/analytics/metrics/recipients for the selectable set."},"min_pii_level_required":{"type":"integer","readOnly":true},"required_purposes":{"type":"array","items":{"type":"string"},"readOnly":true},"folder":{"type":"string","description":"Materialized folder path; '' = root. Normalised server-side."},"tags":{"type":"array","items":{"type":"string"}},"last_checked_at":{"type":"string","format":"date-time","readOnly":true},"next_check_at":{"type":"string","format":"date-time","readOnly":true},"last_value":{"type":"number","readOnly":true,"description":"Last successfully computed value; absent until the first successful check."},"value_withheld":{"type":"boolean","readOnly":true,"description":"True when the caller does not clear the metric's live privacy manifest: the metric is listed without `last_value`."},"last_error":{"type":"string","readOnly":true,"description":"The last check's failure, '' when it succeeded. A failing metric keeps its previous last_value rather than reporting a fabricated 0."},"last_alert_at":{"type":"string","format":"date-time","readOnly":true},"created_by":{"type":"string","readOnly":true},"created_at":{"type":"string","format":"date-time","readOnly":true},"updated_at":{"type":"string","format":"date-time","readOnly":true}}},"MetricPreviewRequest":{"type":"object","required":["definition"],"description":"The body of POST /analytics/metrics/preview — only what it takes to produce the number. Deliberately not MetricObject: requiring `name` there meant the editor could not show a result until the operator had named a metric they were still deciding whether to keep.","properties":{"definition":{"allOf":[{"$ref":"#/components/schemas/QueryDefinition"}],"description":"Same constraints as MetricObject.definition (aggregate, one metric, no dimensions)."},"window_days":{"type":"integer","minimum":0,"maximum":3650,"default":0,"description":"Rolling lookback resolved against now. 0 = no time filter."},"unit":{"type":"string","description":"Echoed back on the result; has no effect on the computation."}}},"MetricFacets":{"type":"object","description":"Distinct folder paths and tags across all metrics.","properties":{"folders":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}}}},"MetricValueObject":{"type":"object","description":"One recorded point of a metric's history.","properties":{"computed_at":{"type":"string","format":"date-time"},"value":{"type":"number"},"window_from":{"type":"string","format":"date-time","description":"Absent for an all-time metric."},"window_to":{"type":"string","format":"date-time"}}},"MetricAlertObject":{"type":"object","description":"One fired alert, frozen under the thresholds configured when it fired — editing the metric later never rewrites what was sent to whom.","properties":{"id":{"type":"string","format":"uuid"},"metric_id":{"type":"string","format":"uuid"},"metric_name":{"type":"string"},"fired_at":{"type":"string","format":"date-time"},"direction":{"type":"string","enum":["increase","decrease","nodata"],"description":"nodata on a no_data alert."},"previous_value":{"type":"number"},"current_value":{"type":"number"},"change_pct":{"type":"number","description":"Signed relative change. A rise from a zero baseline has no defined ratio and is reported as 100."},"threshold_pct":{"type":"number"},"threshold_value":{"type":"number","description":"The bound an absolute alert crossed. Absent on relative alerts; threshold_pct is 0 on absolute ones."},"compare_days":{"type":"integer","description":"The distance a period_over_period alert compared over. Absent on every other kind."},"recipients":{"type":"array","items":{"type":"string"},"description":"Who the alert was actually published to, after the send-time membership re-check. Empty means it reached nobody — visible in `note`, never silent."},"notified":{"type":"boolean"},"note":{"type":"string"}}},"MetricRunResult":{"type":"object","description":"The scalar produced by an on-demand run or preview. Records nothing.","properties":{"value":{"type":"number"},"unit":{"type":"string"},"window_from":{"type":"string","format":"date-time"},"window_to":{"type":"string","format":"date-time"},"executed_at":{"type":"string","format":"date-time"},"duration_ms":{"type":"integer"}}},"MetricCheckResult":{"type":"object","description":"The outcome of a forced check — a real check, not a simulation.","properties":{"value":{"type":"number","description":"The recorded value. Omitted when a no_data rule's metric returned no value (see no_data)."},"no_data":{"type":"boolean","description":"Present and true when a no_data rule's metric returned no value this check. No value or change_pct is reported then."},"previous_value":{"type":"number"},"change_pct":{"type":"number","description":"Omitted for no_data rules, which watch for missing data rather than change."},"alert":{"$ref":"#/components/schemas/MetricAlertObject"},"alert_skip_reason":{"type":"string","enum":["alerting_disabled","no_baseline","no_change","below_min_value","direction_not_watched","below_threshold","in_cooldown","no_crossing","already_alerted","concurrent_check","data_present","no_data_below_stale","no_comparison_baseline"],"description":"Why an otherwise-moving metric did not alert. Empty when an alert fired. Lets an operator tell \"nothing moved\" apart from \"it moved but I muted it\". no_crossing: an absolute rule's value is inside its band. already_alerted: an absolute rule's value is still beyond the bound it already alerted for in this excursion. concurrent_check: the rule fired, but an overlapping check recorded the alert first or the metric was edited mid-check, so this check did not alert. data_present: a no_data rule's metric returned data this check. no_data_below_stale: a no_data rule has seen no data for less than alert_stale_minutes so far. no_comparison_baseline: a period_over_period rule has no usable recorded value from alert_compare_days ago (none within tolerance, a different window length, or the lookup failed)."}}},"AnalyticsResult":{"type":"object","description":"Generic column/row envelope nested in GenericResponse.data.","properties":{"columns":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string"}}}},"rows":{"type":"array","items":{"type":"array","items":{}}},"meta":{"type":"object","properties":{"executed_at":{"type":"string","format":"date-time"},"duration_ms":{"type":"integer"},"cached":{"type":"boolean"},"total_rows":{"type":"integer"},"truncated":{"type":"boolean","description":"Aggregate queries only, present when true. The aggregate hit the effective row limit; counts may be incomplete. A result of exactly the limit is flagged too.\n"}}}}},"AnalyticsOverview":{"type":"object","description":"Home-screen aggregate counts. Everything here is a row count or a bucket sum; no attribute values are exposed.\n","properties":{"generated_at":{"type":"string","format":"date-time"},"months":{"type":"integer","description":"Width of the event histogram, in whole months ending with the current one."},"recent_days":{"type":"integer","description":"Window the `recent` counters are measured over (fixed at 30)."},"profiles":{"type":"object","properties":{"total":{"type":"integer","format":"int64"},"recent":{"type":"integer","format":"int64"},"by_entity_type":{"type":"array","description":"Largest population first.","items":{"type":"object","properties":{"entity_type":{"type":"string"},"count":{"type":"integer","format":"int64"},"recent":{"type":"integer","format":"int64"},"last_created_at":{"type":"string","format":"date-time","description":"Newest profile creation; omitted when the entity type has no profiles."}}}}}},"events":{"type":"object","properties":{"total":{"type":"integer","format":"int64"},"recent":{"type":"integer","format":"int64"},"last_event_at":{"type":"string","format":"date-time","description":"Newest event timestamp — the ingestion freshness signal. Omitted on an empty table."},"by_type_month":{"type":"array","description":"One entry per (event type, month) inside the window, oldest month first. Months in which an event type produced nothing are omitted; events dated past the end of the current month are outside the window.\n","items":{"type":"object","properties":{"event_type":{"type":"string"},"month":{"type":"string","example":"2026-07","description":"Bucket label, YYYY-MM (UTC)."},"count":{"type":"integer","format":"int64"}}}},"by_type":{"type":"array","description":"Each event type's total inside the same window, largest first.","items":{"type":"object","properties":{"event_type":{"type":"string"},"count":{"type":"integer","format":"int64"}}}}}}}},"DashboardItemObject":{"type":"object","required":["type"],"description":"A tile on the 12-column grid. type = 'report' requires report_id +\ndisplay_mode; type = 'metric' requires metric_id (display_mode is\noptional and defaults to the headline number); type = 'text' requires\ncontent.\n\nA tile may only carry the target its own type names — a metric tile with\na report_id, or vice versa, is a 400 rather than a silently empty tile.\nBoth ids are ON DELETE SET NULL: a tile whose report or metric was\ndeleted survives as a visibly-broken tile the operator can remove, not a\nrow that vanishes from someone else's dashboard.\n","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["report","text","metric"]},"title":{"type":"string"},"col":{"type":"integer","minimum":0,"description":"Starting column 0–11. col + w must not exceed 12."},"row":{"type":"integer","minimum":0,"description":"Starting row (0-based)."},"w":{"type":"integer","minimum":1,"maximum":12,"description":"Width in columns (1–12)."},"h":{"type":"integer","minimum":1,"description":"Height in row units."},"report_id":{"type":"string","format":"uuid","description":"type = report only."},"metric_id":{"type":"string","format":"uuid","description":"type = metric only. The tile renders the metric's latest recorded value and its series; both are served by the existing /analytics/metrics/{id} and /{id}/values endpoints, so a dashboard never triggers a recomputation just by being opened."},"display_mode":{"type":"string","enum":["graph","table","both","value"],"description":"What the tile renders. The vocabulary is per-type and the API rejects a value belonging to the other type.\ntype = report (required): the report's own chart (\"graph\"), that chart plus the data table (\"both\"), or the table alone (\"table\"). Since chart form became a per-report setting (`Report.visualization`), \"table\" is expressible as a report saved with `kind: table` — the web console therefore reads all three values but only writes graph/both, and re-saving a legacy \"table\" tile converts it to \"both\". Still accepted on write for clients that rely on it.\ntype = metric (optional, defaults to \"value\"): the headline number with its change since the previous check (\"value\"), the recorded series (\"graph\"), or both."},"content":{"type":"string","maxLength":10000,"description":"Markdown; type = text only. At most 10000 characters (400 otherwise)."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"DashboardObject":{"type":"object","required":["name"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string"},"created_by":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"items":{"type":"array","description":"Included on the single-dashboard GET.","items":{"$ref":"#/components/schemas/DashboardItemObject"}}}},"LayoutUpdate":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"type":"object","required":["item_id"],"properties":{"item_id":{"type":"string","format":"uuid"},"col":{"type":"integer","minimum":0},"row":{"type":"integer","minimum":0},"w":{"type":"integer","minimum":1,"maximum":12},"h":{"type":"integer","minimum":1}}}}}},"Matcher":{"type":"object","required":["field","field_type","compare"],"description":"One field comparison between two candidate profiles.","properties":{"field":{"type":"string","example":"email"},"field_type":{"type":"string","enum":["identifier","attribute"]},"compare":{"type":"string","enum":["exact","normalized","domain_only","fuzzy"],"description":"`fuzzy` fires when the Jaro-Winkler similarity of the two normalized values reaches `fuzzy_threshold` (or the default threshold when unset)."},"weight":{"type":"number","description":"Contribution to score (weighted_threshold rules)."},"required":{"type":"boolean","description":"If true, the rule cannot fire unless this matcher fires."},"fuzzy_threshold":{"type":"number","minimum":0,"maximum":1,"description":"Per-matcher Jaro-Winkler threshold override, between 0 and 1 (400 otherwise)."}}},"RuleObject":{"type":"object","required":["name","match_type","matchers"],"properties":{"id":{"type":"string","format":"uuid"},"ruleset_id":{"type":"string","format":"uuid"},"priority":{"type":"integer","description":"Lower is evaluated first; first match wins."},"name":{"type":"string"},"match_type":{"type":"string","enum":["deterministic","probabilistic"]},"matchers":{"type":"array","items":{"$ref":"#/components/schemas/Matcher"}},"logic":{"type":"string","enum":["all","weighted_threshold"]},"min_score":{"type":"number","description":"Required summed weight for weighted_threshold."},"confidence":{"type":"number","minimum":0,"maximum":1,"description":"Confidence produced when the rule fires, between 0 and 1 (400 otherwise)."},"min_match_count":{"type":"integer"},"is_active":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"RulesetObject":{"type":"object","required":["entity_type","name"],"properties":{"id":{"type":"string","format":"uuid"},"entity_type":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"is_active":{"type":"boolean"},"merge_policy":{"type":"string","enum":["latest_wins","source_priority","root_wins","additive"],"description":"Attribute-merge policy for the resolved view."},"rules":{"type":"array","description":"Included on the single-ruleset GET.","items":{"$ref":"#/components/schemas/RuleObject"}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"ResolveRequest":{"type":"object","required":["entity_type"],"description":"Provide either profile_id (resolve an existing profile) or identifiers (ad-hoc).","properties":{"profile_id":{"type":"string","format":"uuid"},"identifiers":{"type":"object","additionalProperties":{"type":"string"},"example":{"email":"user@example.com"}},"entity_type":{"type":"string"},"dry_run":{"type":"boolean","description":"Return the would-be cluster without writing."}}},"ClusterMember":{"type":"object","properties":{"profile_id":{"type":"string","format":"uuid"},"is_root":{"type":"boolean"},"confidence":{"type":"number"}}},"ResolvedEdge":{"type":"object","properties":{"source_profile_id":{"type":"string"},"target_profile_id":{"type":"string"},"rule_id":{"type":"string"},"rule_name":{"type":"string"},"confidence":{"type":"number"}}},"ResolveResult":{"type":"object","properties":{"cluster_id":{"type":"string","description":"Root profile id; empty when the seed matched nothing."},"entity_type":{"type":"string"},"members":{"type":"array","items":{"$ref":"#/components/schemas/ClusterMember"}},"edges":{"type":"array","items":{"$ref":"#/components/schemas/ResolvedEdge"}},"dry_run":{"type":"boolean"}}},"ClusterObject":{"type":"object","properties":{"cluster_id":{"type":"string"},"entity_type":{"type":"string"},"members":{"type":"array","items":{"$ref":"#/components/schemas/ClusterMember"}}}},"ResolvePersonsRequest":{"type":"object","required":["profile_ids"],"properties":{"profile_ids":{"type":"array","minItems":1,"maxItems":500,"items":{"type":"string","format":"uuid"}}}},"PersonMemberObject":{"type":"object","properties":{"profile_id":{"type":"string","format":"uuid"},"confidence":{"type":"number"}}},"PersonObject":{"type":"object","description":"A resolved person. person_key is the cluster root id, or the queried profile id for a one-member person. contact_members is the subset of member ids whose link confidence clears campaign_contact_min_confidence in both directions.","properties":{"person_key":{"type":"string"},"members":{"type":"array","items":{"$ref":"#/components/schemas/PersonMemberObject"}},"contact_members":{"type":"array","items":{"type":"string","format":"uuid"}}}},"ResolvePersonsResponse":{"type":"object","properties":{"scope":{"type":"string","enum":["person","profile"]},"persons":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/PersonObject"}}}},"SignalObject":{"type":"object","description":"A freshness-aware behavioural signal definition. Two kinds: `template` signals are computed by the built-in template library; `external` signals carry values supplied by the customer's own model (bulk push endpoint or a Connect `data_type: signals` feed) and are never computed by the platform.","required":["name","entity_type"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"entity_type":{"type":"string"},"description":{"type":"string"},"kind":{"type":"string","enum":["template","external"],"default":"template","description":"Fixed at create — an update that changes it is rejected with 400 (flipping template/external would orphan or fabricate value provenance)."},"template_name":{"type":"string","description":"Built-in template this signal instantiates. Required for kind=template, must be empty for kind=external."},"parameters":{"type":"object","additionalProperties":true,"description":"Template parameter bindings. Must be empty for kind=external."},"recompute_interval":{"type":"integer","description":"kind=template: seconds between recomputations; 0 = recompute on every read. kind=external: the default validity window — how long a pushed value stays valid when the pusher supplies no valid_until. Defaults to 86400."},"transform_expr":{"type":"string","description":"Optional expr expression post-processing the raw value. For template signals it is evaluated per profile on every recompute; for external signals it is applied AT INGEST to every pushed value (so an operator can rescale a foreign score without asking the customer to change their export). `value` is typed by the output type — a string for string signals (`upper(value)`), a number otherwise (`value * 100`) — and mixing the two is rejected at save. The result is cast back to the output type (an `integer` signal truncates); a runtime error or an unusable result stores the raw value unchanged. Not retroactive. Save enforces static limits (400): predicate functions (all, any, map, filter, …) nest at most 2 deep and a literal range a..b spans fewer than 1000 elements (dynamic ranges are bounded by the runtime budget). A run over its execution budget (1 048 576 steps / 200 ms) is NOT a raw-value fallback: a computed signal is skipped for the rest of that recompute batch (the error is logged); a pushed value is skipped with an `expr_budget` reason, as is every later value in the same push."},"output_type":{"type":"string","enum":["decimal","integer","string","boolean"],"description":"For kind=template — read-only, derived from the template (the template decides what it produces; a conflicting value is rejected with 400). For kind=external — required on create: the declared type every pushed value is validated against."},"is_active":{"type":"boolean"},"source_purposes":{"type":"array","items":{"type":"string"},"description":"kind=external only: the collection purposes the producing model's INPUT data was gathered under, declared by the operator. Empty = unknown provenance (reads unrestricted; purpose-scoped erasure treats unknown as \"derived from everything\" and deletes)."},"staleness_action":{"type":"string","enum":["serve","exclude"],"default":"serve","description":"kind=external only: what decisioning does with a value past valid_until — `serve` reads it as-is, `exclude` makes NBA treat the offer as ineligible (exclusion reason `score_stale`)."},"model_ref":{"type":"string","description":"kind=external only: free-form label of the producing model, e.g. \"databricks:churn_v3\"."},"external_erased_count":{"type":"integer","format":"int64","readOnly":true,"description":"kind=external only: values deleted by purpose-scoped erasure that will never be re-supplied by recomputation."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"SignalTemplateObject":{"type":"object","description":"A built-in signal template in the read-only library.","properties":{"name":{"type":"string"},"output_type":{"type":"string","enum":["decimal","integer","string","boolean"]},"description":{"type":"string"},"parameter_schema":{"type":"object","additionalProperties":true,"description":"JSON Schema for this template's parameters."}}},"NotificationProviderObject":{"type":"object","description":"A tenant SMTP provider for notification email. `password` is write-only; `has_credentials` reports whether one is stored. `is_default`, `has_credentials`, `created_by` and the timestamps are read-only.","required":["name","host","port","from_addr"],"properties":{"id":{"type":"string","format":"uuid","readOnly":true},"name":{"type":"string","example":"Acme mail relay"},"provider_type":{"type":"string","enum":["smtp"],"default":"smtp"},"host":{"type":"string","example":"smtp.acme.example"},"port":{"type":"integer","minimum":1,"maximum":65535,"example":587},"username":{"type":"string","example":"notifications@acme.example"},"password":{"type":"string","writeOnly":true},"clear_credentials":{"type":"boolean","writeOnly":true,"description":"Drop the stored password (update only)."},"has_credentials":{"type":"boolean","readOnly":true},"from_addr":{"type":"string","format":"email","example":"no-reply@acme.example"},"from_name":{"type":"string","example":"Acme","description":"Display name; must not contain an address."},"is_default":{"type":"boolean","readOnly":true},"is_active":{"type":"boolean","default":true},"created_by":{"type":"string","readOnly":true},"created_at":{"type":"string","format":"date-time","readOnly":true},"updated_at":{"type":"string","format":"date-time","readOnly":true}}},"NotificationProviderTestResult":{"type":"object","properties":{"success":{"type":"boolean"},"latency_ms":{"type":"integer"},"message":{"type":"string","example":"connected and authenticated"},"sent":{"type":"boolean","description":"True when send=true delivered the test message."},"sent_to":{"type":"string","format":"email"}}},"AccountSubscriptionRequest":{"type":"object","description":"Create needs `user_id` and `event_type`; on update every field is optional and `user_id` cannot change.","properties":{"user_id":{"type":"string","format":"uuid"},"event_type":{"type":"string","example":"account.usage_threshold"},"filters":{"type":"object","additionalProperties":true,"example":{"threshold":100}},"enabled":{"type":"boolean","default":true}}},"AccountSubscriptionResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"account_id":{"type":"string"},"user_id":{"type":"string","format":"uuid"},"user_email":{"type":"string","format":"email"},"event_type":{"type":"string","example":"account.usage_threshold"},"channel":{"type":"string","enum":["email"]},"filters":{"type":"object","additionalProperties":true},"enabled":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"LLMProviderObject":{"type":"object","description":"A per-tenant LLM provider (Bring your own LLM). Credentials are write-only; `has_credentials` reports presence. `max_pii_level` / `timeout_sec` null = inherit the instance value. `is_default` is read-only here — change it via POST /llm/providers/{id}/default, and it is scoped PER PURPOSE (a tenant has one default text provider and one default image provider).","required":["name","api_host","model"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"purpose":{"type":"string","enum":["text","image"],"default":"text","description":"Which kind of model this is. `text` serves every LLM feature (segment suggestion, copy generation, journey drafting, prediction); `image` serves the Content Manager's AI image generation. Immutable after creation — changing it would invalidate provider_type and move the row between default slots, so create a second provider instead. Omitted = text, so older bodies without it keep their meaning."},"provider_type":{"type":"string","enum":["openai_compatible","azure_openai","anthropic","openrouter","openai_images"],"default":"openai_compatible","description":"Legal values depend on `purpose`. TEXT — openai_compatible covers vLLM, Ollama /v1, LiteLLM, OpenRouter and OpenAI; azure_openai puts the deployment (model) in the path with an api-key header (capabilities.api_version overrides the api-version query, default 2024-10-21); anthropic speaks the Messages API (system prompt hoisted, max_tokens from capabilities.max_tokens, default 4096). IMAGE — openrouter is an OpenAI-compatible chat call with modalities=[\"image\"]; openai_images is POST {api_host}/images/generations. Pairing a shape with the wrong purpose is a 400 naming both halves. Bedrock/Vertex are deliberately excluded — front them with LiteLLM or your own gateway."},"api_host":{"type":"string","description":"Base URL including the version path where applicable."},"model":{"type":"string"},"api_key":{"type":"string","description":"Write-only. Omit on update to keep the stored credential; absent on create = the keyless self-hosted case."},"clear_credentials":{"type":"boolean","description":"Update only: true removes the stored credential (switch to keyless)."},"has_credentials":{"type":"boolean","readOnly":true},"max_pii_level":{"type":"integer","nullable":true,"description":"Attribute-sensitivity ceiling for prompts. Null = inherit. Raising it above the instance ceiling requires instance_admin."},"timeout_sec":{"type":"integer","nullable":true},"capabilities":{"type":"object","additionalProperties":true,"description":"Probe-written ({\"supports_json_object\": bool, \"max_tokens\": n}), hand-overridable."},"price_input_per_mtok":{"type":"number","nullable":true,"minimum":0,"description":"Price of one million input tokens in `price_currency`. Set together with `price_output_per_mtok` and `price_currency`, or all three null; one without the others is a 400. Used to turn a money budget into tokens."},"price_output_per_mtok":{"type":"number","nullable":true,"minimum":0,"description":"Price of one million output tokens; see `price_input_per_mtok`."},"clear_prices":{"type":"boolean","description":"Update only: true removes the stored prices and currency. An update that sends no price field keeps them. Cannot be combined with price fields (400)."},"price_currency":{"type":"string","nullable":true,"pattern":"^[A-Z]{3}$","description":"ISO 4217 code of both prices, e.g. EUR."},"is_default":{"type":"boolean","readOnly":true},"is_active":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"SignalValueObject":{"type":"object","description":"A computed signal value with freshness metadata.","properties":{"name":{"type":"string"},"value":{"description":"The computed value (number or string per output_type). Null when withheld."},"output_type":{"type":"string","enum":["decimal","integer","string","boolean"]},"computed_at":{"type":"string","format":"date-time"},"valid_until":{"type":"string","format":"date-time"},"stale":{"type":"boolean","description":"True when valid_until is in the past."},"withheld":{"type":"string","enum":["purpose","stale"],"description":"External signals only. `purpose` — the definition's source_purposes are disjoint from the request's declared purposes (value and freshness metadata withheld; audited). `stale` — the definition's staleness_action is `exclude` and the value is past valid_until (or absent). NBA maps these to the score_purpose_denied / score_stale exclusion reasons."}}},"SignalCohortObject":{"type":"object","description":"A named filter expression over a profile's signal values. Evaluated lazily by default; set `materialized: true` to have the scheduler precompute membership on `refresh_interval_sec` — reads then serve the stored set (cost proportional to member count instead of entity size, staleness bounded by the interval).","required":["entity_type","name","filter_expr"],"properties":{"id":{"type":"string","format":"uuid"},"entity_type":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"filter_expr":{"type":"string","description":"expr expression over the profile's SIGNAL values for this entity type — the evaluation environment is `signal name → value` and nothing else, so profile attributes, identifiers and events are not in scope (model those as a signal first). Undefined variables are allowed at compile time: a name that is not a signal makes the expression false for every profile rather than erroring, so a typo yields an empty cohort. Example: \"churn_risk_score > 0.7 && rfm_frequency < 2\". Save enforces static limits (400): predicate functions (all, any, map, filter, …) nest at most 2 deep and a literal range a..b spans fewer than 1000 elements (dynamic ranges are bounded by the runtime budget). An evaluation over its execution budget (1 048 576 steps / 500 ms) fails the whole cohort, not one profile: a materialized refresh records it as the cohort's last_error, and a lazy read — `GET /cohorts/{id}/members` or the profile-list `?cohort=` filter — answers 422 naming `expr_budget`. A `cohort.<name>` reference elsewhere in a querybuilder filter tree surfaces as an ordinary query error, not this 422. Changing the expression of a materialized cohort resets its refresh state — reads fall back to lazy evaluation until the scheduler re-materializes (due immediately, landing within ~1 min)."},"is_active":{"type":"boolean"},"materialized":{"type":"boolean","default":false,"description":"Opt-in membership precomputation. Recommended for large entity types (the lazy path scans every signal value of the entity per read). Switching it off sweeps the stored membership rows."},"refresh_interval_sec":{"type":"integer","minimum":60,"default":300,"description":"Seconds between scheduler membership refreshes."},"last_refreshed_at":{"type":"string","format":"date-time","readOnly":true,"description":"When membership was last materialized; absent until the first refresh (reads evaluate lazily until then)."},"last_error":{"type":"string","readOnly":true,"description":"Last refresh failure, empty after a successful refresh."},"member_count":{"type":"integer","readOnly":true,"description":"Member count as of the last refresh. Only reported for materialized cohorts."},"required_any_purposes":{"type":"array","readOnly":true,"description":"External-signal purpose groups the filter expression depends on; a reader of the cohort's membership (members endpoint, `?cohort=`, `cohort.<name>` filter leaves, `include_cohorts`) must hold at least one purpose of every group. Computed at save and re-derived live.","items":{"type":"array","items":{"type":"string"}}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"ConnectorRequest":{"type":"object","required":["name","kind","protocol","data_type"],"example":{"name":"crm_daily_export","description":"Nightly profile export to the CRM bucket.","kind":"batch_sink","protocol":"s3","data_type":"profiles","credentials":{"access_key_id":"AKIAEXAMPLE","secret_access_key":"example-secret"},"connection":{"endpoint":"https://s3.eu-west-1.amazonaws.com","bucket":"crm-exports","region":"eu-west-1","entity_type":"customer"},"privacy":{"purposes":["marketing","analytics"],"pii_level":2}},"properties":{"name":{"type":"string","description":"Unique connector name."},"description":{"type":"string"},"kind":{"type":"string","enum":["batch_source","batch_sink","stream_source","stream_sink"]},"protocol":{"type":"string","enum":["sftp","s3","gcs","azure_blob","kafka","nats","upload","sql"]},"data_type":{"type":"string","enum":["profiles","events","consents","profile_links","custom_dataset","signals"]},"dataset_name":{"type":"string","description":"Required when data_type=custom_dataset."},"credentials":{"type":"object","additionalProperties":{"type":"string"},"description":"Key→value credential map. Write-only: not returned on reads.\n\nprotocol=sql, by dialect:\n  postgres/mysql/mssql/oracle/redshift: username, password\n  snowflake:                            username, private_key\n  bigquery:                             service_account_json\n  databricks:                           token\n\nprotocol=sql, postgres/redshift only: ca_cert (optional PEM CA\n  bundle; replaces the system trust roots for certificate\n  verification — see connection.ssl_mode below). Installed in\n  memory only; never written to disk.\n\nprotocol=sftp: host_key (the server's public host key, a\n  known-hosts line or a bare authorized-keys entry). Required\n  on save unless connection.insecure_skip_host_key is true — a\n  save without a host_key or that flag is refused with\n  \"sftp host_key required (set insecure_skip_host_key to opt\n  out)\", and a host_key that does not parse is refused too. An\n  update with no or empty credentials keeps the stored ones (or\n  clears them) and is not re-judged (the console can still rename\n  a connector, or clear credentials outright); a connector saved\n  before this rule and never updated fails its next run with the\n  same message until an editor sets one of the two. Creating an\n  sftp connector additionally requires credentials.username\n  (refused with \"credentials.username is required\"), and the\n  host_key rule applies to the create itself: a create with no\n  credentials and no insecure_skip_host_key is refused.\n\nprotocol=nats (stream_source/stream_sink): nkey_seed | token |\n  username + password. nkey_seed is an nkeys user seed string\n  (precedence nkey_seed > token > username) — the\n  form the platform's CDC ingress broker issues reader\n  credentials in; a malformed\n  seed is rejected at connector construction, not at dial.\n\nprotocol=kafka: username, password, sasl_mechanism (plain |\n  scram-sha-256 | scram-sha-512; default plain), and optional\n  ca_cert / client_cert / client_key. sasl_mechanism is not a\n  secret: an update whose credentials omit it keeps the stored\n  value while the protocol stays kafka. Send it (e.g. \"plain\")\n  to change it; `{}` still clears everything."},"connection":{"type":"object","additionalProperties":true,"description":"Non-secret connection params (host, bucket, topic, etc.).\n\nObject-store connectors are refused at save (400, \"connection.<key>\nis required\") when a required key is missing: s3 needs endpoint,\nregion and bucket (endpoint must be an http(s) URL); gcs needs\nbucket (endpoint and region default); azure_blob needs\naccount_name and container (endpoint is optional).\n\nKeys are matched exactly, the way the connector service reads them. A\ndocument with two keys that differ only by letter case (for\nexample `tls` and `TLS`) is refused with 400, and so is a value\nof the wrong JSON type where a protocol expects a string (for\nexample a numeric `connection.network_id` or `connection.host`).\n\nprotocol=sql (warehouse and database connectors; requires the\n\"warehouse\" feature — 403 with reason=feature_not_licensed\notherwise). Validated at save; a violation is a 400.\n\n  dialect            required. One of postgres, mysql, mssql,\n                     oracle, redshift, snowflake, bigquery,\n                     databricks.\n  host, port,        wire dialects (postgres, mysql, mssql,\n  database           oracle, redshift): host and database are\n                     required; port defaults per dialect\n                     (5432/3306/1433/1521/5439).\n  account,           snowflake: account is required; warehouse\n  warehouse, role    and role are optional.\n  project            bigquery: required; database = the dataset.\n  workspace_url,     databricks: both required; database =\n  warehouse_id       catalog.schema.\n  tls                \"require\" (default) or \"disable\". \"disable\"\n                     is refused unless network_id is set —\n                     plaintext is only defensible inside a\n                     private network the operator controls.\n  ssl_mode           postgres/redshift only: \"verify-full\"\n                     (default — the server certificate's chain\n                     AND hostname are verified) or \"require\" (the\n                     explicit opt-out: TLS still encrypts, but no\n                     certificate is verified at all). tls\n                     \"disable\" still wins over either. A\n                     connector saved before this default existed\n                     switches to verify-full on its next run;\n                     pair with credentials.ca_cert if the server's\n                     certificate is not signed by a public CA, or\n                     set ssl_mode to \"require\" to keep the old\n                     behavior.\n  query              sources: required. The statement every run\n                     executes; its result column names are what\n                     the connector's field mappings are written\n                     against (the /test probe lists them). May\n                     contain {cursor} and {now}, which are BOUND\n                     as timestamp parameters, never interpolated.\n                     A NULL cell imports as an empty value, the\n                     same as an empty CSV cell, and two result\n                     columns with the SAME name collapse to the\n                     last one, exactly as duplicate CSV headers\n                     do — alias them in the SELECT. A run whose\n                     query returns no rows succeeds with a \"query\n                     returned no rows\" note on the run log; a row\n                     that fails to map or ingest is counted as\n                     failed/skipped and the read continues. THE\n                     SESSION IS PINNED READ-ONLY ON POSTGRES AND\n                     MYSQL ONLY (default_transaction_read_only /\n                     SET SESSION TRANSACTION READ ONLY); the other\n                     six dialects have no equivalent session\n                     setting, so there the credentials you\n                     configure are the only thing stopping a\n                     statement that writes — give a source\n                     read-only credentials.\n  incremental        sources: bool, cursor-based windowing. When\n                     set, {cursor} binds the end of the last\n                     successful window and is advanced to the\n                     CURRENT run's start time — only if that run\n                     had no structural failure, so a failed run\n                     re-reads its window and rows committed\n                     upstream mid-run are picked up next time.\n                     Unset: every run binds initial_cursor. (The\n                     cursor is the batch schedule's export_cursor\n                     column, reused for imports.)\n  initial_cursor     sources: RFC3339 instant the first\n                     incremental run starts from. Unset — or\n                     unparsable, which logs a warning rather than\n                     failing the run — is the Unix epoch, i.e.\n                     everything. It is also what the /test probe\n                     binds, so the query a test runs is the query\n                     the first run runs.\n  table              sinks: required. Unquoted one-to-three part\n                     identifier (table, schema.table,\n                     catalog.schema.table), each part <= 128\n                     chars. The run loads into a staging table\n                     beside it (<table>__optima_stage, all text\n                     columns named after the exported columns)\n                     and only touches the target once the load\n                     is complete, so a failed run leaves the\n                     previous contents intact. On mysql and oracle\n                     the swap also parks the previous copy under\n                     <table>__optima_old on its way past. BOTH\n                     suffixes are owned by the connector: it drops\n                     a leftover of either before it needs the\n                     name, so a crashed run cannot brick every\n                     subsequent one — do not use those names for\n                     tables of your own. ORACLE EXCEPTION: its DDL\n                     auto-commits, so its swap cannot be a\n                     transaction. The statements are ordered\n                     rename-first, which guarantees the previous\n                     contents are never DESTROYED — but not that\n                     the table is always there: a failure of the\n                     middle statement leaves no <table> at all,\n                     with the previous data in\n                     <table>__optima_old, one manual rename from\n                     recovery. The run log names the published\n                     table as \"<dialect>:<table>\" where a file\n                     sink names object keys.\n  write_mode         sinks: required, \"replace\" or \"merge\".\n                     \"replace\" swaps the staged table into place\n                     — the target ends up with EXACTLY the rows\n                     this run exported, so a shrinking audience\n                     shrinks the table (and, unless\n                     skip_empty_export is set on the schedule, an\n                     empty export empties it; the run log says\n                     which happened). Note that the target ends\n                     up BEING the staging table, so indexes,\n                     constraints and grants on the previous table\n                     do not survive a replace run — put a merge\n                     sink on a table you have shaped yourself.\n                     \"merge\" upserts on\n                     key_columns and leaves unmatched target rows\n                     alone. MERGE NEEDS A UNIQUE OR PRIMARY KEY\n                     ON THE TARGET's key_columns: the staging\n                     table carries no constraints and the\n                     connector does not create one on your table.\n                     Without it MySQL (ON DUPLICATE KEY) appends\n                     instead of updating, and the MERGE dialects\n                     duplicate a target row that appears twice.\n  key_columns        sinks: array, required (non-empty) when\n                     write_mode is \"merge\". Every entry must be\n                     one of the exported columns (the field\n                     mappings' target names, or the data type's\n                     default columns when none are configured);\n                     a key that is not exported fails the run\n                     before anything is staged.\n  query_timeout_sec  optional, default 300, max 3600 (a larger\n                     value is clamped to the ceiling, a negative\n                     one is refused). On the wire dialects it\n                     bounds the WHOLE read, not just the first\n                     row: a large pull that outlives it is cut\n                     off, and the run fails without advancing the\n                     cursor.\n  network_id         unchanged: routes the connection through a\n                     private network.\n\nprotocol=nats (stream_source/stream_sink). Validated at save (400)\nand re-checked at dial time (the authority).\n\n  url                required when network_id is unset — there\n                     is no default route any more (it used to\n                     default to the platform's own\n                     message bus, which would let a tenant\n                     connector attach to it).\n                     Comma-separated cluster lists are checked\n                     host by host. Every host must resolve\n                     public (not loopback/RFC1918/link-local/\n                     CGN/unspecified) unless it falls inside\n                     an operator-configured allow list (off by\n                     default), and the platform's own message\n                     bus host is always refused regardless of\n                     the allow list. With network_id set the private\n                     network's own tunnel dialer applies instead\n                     (it already blocks loopback; RFC1918 there\n                     is the tunnel's purpose).\n  subject            stream sink/source: refused if it is a\n                     platform-reserved namespace (the\n                     platform's own subjects and stream names,\n                     and system subjects) or if it carries a\n                     wildcard token (* or >) — a wildcard can\n                     subscribe across an entire reserved\n                     namespace without ever matching one of\n                     those prefixes literally. Plain\n                     \"notifications\" is not denied.\n  source_subject     REMOVED: a 400 on save. It\n                     subscribed the connector service's internal\n                     connection to any subject with no\n                     destination guard; stream sinks derive\n                     records from the platform's own writes\n                     only.\n\nprotocol=kafka (stream_source/stream_sink): brokers is required\n(comma-separated or JSON array) and every broker host is\nsubject to the same public-only guard as protocol=nats' url,\nunless network_id is set. connection.tls (bool, default true —\nan explicit false is required to dial in the clear) and\nconnection.tls_server_name (optional certificate name override)\nplus credentials.ca_cert / credentials.client_cert /\ncredentials.client_key (PEM, optional customer CA / mTLS)\nconfigure the transport; SASL/PLAIN (explicit, or the default\nwhen a username is set without sasl_mechanism) over tls:false\nis refused at save and again at every dial unless network_id is\nset."},"privacy":{"$ref":"#/components/schemas/ConnectorPrivacyRequest"}}},"ConnectorResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string"},"kind":{"type":"string","enum":["batch_source","batch_sink","stream_source","stream_sink"]},"protocol":{"type":"string","enum":["sftp","s3","gcs","azure_blob","kafka","nats","upload","sql"]},"data_type":{"type":"string","enum":["profiles","events","consents","profile_links","custom_dataset","signals"]},"dataset_name":{"type":"string"},"has_credentials":{"type":"boolean","description":"True when encrypted credentials are stored."},"connection":{"type":"object","additionalProperties":true,"description":"Non-secret params. Cross-protocol keys: entity_type (profiles/events/consents; on batch sources the entity type imported rows are written under, on stream sinks a scope that forwards only that entity type's records — records that carry no entity type, e.g. profile deletes/merges, profile_links and dataset changes, still pass through so in-scope deletions are not lost; export_filter narrows further on top), timezone (batch imports; IANA name for naive CSV timestamps, validated at save), import_filter (sources) / export_filter (stream sinks) — row filters {profile_filter: <querybuilder tree, profiles only; fields: profile.<attr>, identifier.<key>, and for profiles stream sinks signal.<name> / computed.<name> evaluated against the profile's current state>, rules: [{key, operator, value}], event_types: [<event type names, events connectors only; empty = all>], include_updates_deletes: <bool; events stream sinks — forward event.updated/deleted records, which carry no event_type, even while event_types is set>}, export_enrichment (profiles stream sinks only; opt-in projection {identifiers: [<identifier keys>], attributes: [<stored attr names>], signals: [<signal names>], computed: [<computed attr names>]}, each list accepting \"*\" for all — additively attaches the selected stored identifiers / attributes / signals / computed attributes to every matched profile record by reading the data plane per matched record. Additive: the record's own changed/created identifiers and attributes are always kept and win over the stored read (read-your-write staleness); the selection only ADDS extra stored fields, it never drops a changed-but-unselected field), export_projection (profiles stream sinks only; opt-in field allow-list {identifiers, attributes, signals, computed} that REDUCES the payload — for each namespace given a concrete key list only those keys survive, \"*\" or an omitted namespace is left untouched; applied after enrichment), purposes (profile/event sources; JSON array or CSV of active consent purposes stamped onto ingested attribute rows as collection provenance — validated against the catalog at save, 400 on unknown/inactive names), signal_names (data_type=signals sources and stream sinks; JSON array or CSV of active kind=external signal names this connector fills or emits — validated at save against the catalog and against connection.entity_type, 400 on an unknown name or a cross-entity pin. Empty = every external signal. Pinning EXACTLY ONE makes the signal.name field mapping optional, since the configuration already says which signal every row fills; a row naming a signal outside the pinned set is skipped, not written. On a stream sink the same pin filters the OUTBOUND feed: a derived record whose signal_name is not in the set is not forwarded (counted as skipped), and a record with no resolvable name is dropped rather than passed — the pin names what may leave. For data_type=signals connection.entity_type is also honoured and, unlike other data types, an unset value means EVERY entity rather than customer — the entity otherwise comes from each signal definition), csv_delimiter / csv_quote (batch connectors; single characters, defaults \",\" and double quote — the CSV dialect used when parsing imports and writing exports; \"\\t\"/\"tab\" accepted for tab), envelope (stream sources; \"debezium\" unwraps a Debezium change event to the row before mapping, so field mappings are written against the table's columns rather than payload.after.* — accepts the schemas-enabled, schemas-disabled and already-flattened (ExtractNewRecordState) shapes, and snapshot reads (op \"r\") are ingested as ordinary rows), debezium_deletes (stream sources with envelope=debezium; \"skip\" (default) drops delete/truncate/tombstone events, \"emit\" forwards the delete's before-image stamped with __op = \"d\" (the ExtractNewRecordState add.fields=op field convention, so a transform script can branch on payload.get(\"__op\")) — opt-in only, because the ingestors upsert and an unhandled before-image would RESURRECT the deleted row, so use it only with a transform script that maps it onto a deletion marker; \"delete\" (events and custom_dataset connectors only — refused at save for every other data type, profiles included, whose deletions go through erasure) turns the before-image into a true deletion: a custom_dataset delete removes the record named by its dataset_record_key, an events delete removes the event whose id derives from its event_key — stream sources have no field mappings, so event imports that should be deletable must set event_key (or dataset_record_key) in the stream source's transform script or send it in the canonical record shape, and the id is scoped to the importing connector; in this mode an already-flattened row (ExtractNewRecordState) stamped __op = \"d\" (add.fields=op) or __deleted = \"true\" (delete.handling.mode=rewrite) is a delete too)."},"is_active":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"created_by":{"type":"string","description":"Auth caller identity (user email, root, or app key hash) that created the connector."},"updated_by":{"type":"string","description":"Auth caller identity that last updated the connector."},"last_run":{"allOf":[{"$ref":"#/components/schemas/ConnectorLastRun"}],"description":"The connector's most recent run. Present on LIST reads only (GET /connect/connectors), fetched alongside the connectors so the list can answer \"does this work\" without one request per row. ABSENT when the connector has never run — which is a different answer from a run that moved nothing, and callers should render it as such rather than as zeroes."},"run_once":{"type":"boolean","description":"LIST reads only: the batch schedule is a one-time job. Absent (false) for connectors without a schedule. An inactive run_once connector with a last_run is a completed one-time job."},"privacy":{"allOf":[{"$ref":"#/components/schemas/ConnectorPrivacyResponse"}],"description":"The stored privacy clearance (sinks). ABSENT on a sink means the clearance is missing: under enforce/strict privacy mode such a connector exports only values with no purpose tag, PII level 0 and no collection provenance, and every run records \"privacy clearance missing — re-save the connector to authorise\"."}}},"ConnectorLastRun":{"type":"object","description":"The newest row of a connector's run log, as carried on a list row.","properties":{"status":{"type":"string","enum":["running","success","partial","failed"]},"started_at":{"type":"string","format":"date-time"},"finished_at":{"type":"string","format":"date-time","description":"Absent while the run is still in flight."},"rows_processed":{"type":"integer","format":"int64"},"rows_failed":{"type":"integer","format":"int64"},"rows_skipped":{"type":"integer","format":"int64"},"error_summary":{"type":"string","description":"Present on partial/failed runs."}}},"ConnectorPrivacyRequest":{"type":"object","description":"A sink connector's privacy clearance (batch_sink / stream_sink only —\na source sending it gets 400). Every value the connector exports\npasses the CDP read gates against it: purpose tags (Gate 2), consent\nunder each purpose's lawful basis (Gate 3), PII level, collection\nprovenance (Gate 4, when provenance-based read gating is on), the\nexternal-signal purpose gate and computed-attribute input gating.\nWithheld values are an empty CSV/SQL cell (the run note lists the\ncolumns) or are dropped from a stream record and listed in\nredacted_attributes / redacted_identifiers / redacted_computed /\nredacted_signals. The saver must hold every purpose and at least\npii_level (root and full tenant admins pass) — 403 otherwise. Omitted\non update: the stored clearance is re-checked against the saver and\nre-stamped.\n\nAn empty object is a valid clearance: it authorises untagged, PII-0\ndata only (distinct from a missing clearance, which is never\nauthorised).","example":{"purposes":["marketing","analytics"],"pii_level":2},"properties":{"purposes":{"type":"array","items":{"type":"string"},"description":"Active consent purposes, listed explicitly (\"*\" is refused). Omitted = none (only untagged values clear)."},"pii_level":{"type":"integer","minimum":0,"maximum":255,"default":0,"description":"Omitted = 0."},"purpose_groups":{"type":"array","items":{"type":"array","items":{"type":"string"}},"description":"Optional any-of groups, each a non-empty subset of purposes. A value is exported only when it is permitted under at least one purpose of EVERY group. Without groups, purposes is the one group."}}},"ConnectorPrivacyResponse":{"allOf":[{"$ref":"#/components/schemas/ConnectorPrivacyRequest"},{"type":"object","required":["purposes","pii_level","authorized_by","authorized_at"],"properties":{"purposes":{"type":"array","items":{"type":"string"},"description":"Always present; [] for an empty clearance."},"pii_level":{"type":"integer","minimum":0,"maximum":255},"authorized_by":{"type":"string","description":"Caller identity whose save authorised this clearance."},"authorized_at":{"type":"string","format":"date-time"}}}]},"SQLTransformRequest":{"type":"object","required":["name","target"],"description":"A scheduled SQL transform. One request shape covers both targets; `target`\nsays which field group is load bearing, and the fields belonging to the\nother group are CLEARED on save (a stray `connector_id` on a dataset\ntransform would tie it to that connector's ON DELETE CASCADE).","properties":{"name":{"type":"string","description":"Unique transform name."},"description":{"type":"string"},"target":{"type":"string","enum":["warehouse","dataset"],"description":"warehouse — run `statement` on the sql connector named by `connector_id`.\ndataset   — run saved aggregate report `report_id` against Optima's own\n            data plane and materialise the result into custom dataset\n            `dataset_name`."},"connector_id":{"type":"string","format":"uuid","description":"target=warehouse: an existing connector with protocol=sql. Validated at save."},"statement":{"type":"string","description":"target=warehouse: the statement to execute. May carry the {cursor} and {now} tokens (bound at run time); any other {token} is rejected at save."},"report_id":{"type":"string","format":"uuid","description":"target=dataset: an existing analytics report whose stored definition is type=aggregate — only an aggregate has the row-per-key form a dataset record needs."},"dataset_name":{"type":"string","description":"target=dataset: an existing custom dataset the result rows are written into."},"record_key_column":{"type":"string","description":"target=dataset: the result column identifying a record, so a re-run updates rows instead of duplicating them."},"cron_expr":{"type":"string","description":"Cron expression (5 fields), evaluated in `timezone`; an expression that never occurs (such as 30 February) is refused with 400. Empty = manual-only: the definition is kept but runs start only via POST /connect/sql-transforms/{id}/run."},"timezone":{"type":"string","description":"IANA zone cron_expr is evaluated in, validated at save. Empty = UTC.","example":"Europe/Bratislava"},"is_active":{"type":"boolean","description":"Omitted on create = active; omitted on update = the current state is kept, so a form that does not carry the pause toggle cannot resume a paused transform."}}},"SQLTransform":{"type":"object","description":"A stored SQL transform definition, with its schedule bookkeeping.","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string"},"target":{"type":"string","enum":["warehouse","dataset"]},"connector_id":{"type":"string","format":"uuid","description":"target=warehouse only."},"statement":{"type":"string","description":"target=warehouse only."},"report_id":{"type":"string","format":"uuid","description":"target=dataset only."},"dataset_name":{"type":"string","description":"target=dataset only."},"record_key_column":{"type":"string","description":"target=dataset only."},"cron_expr":{"type":"string","description":"Empty = manual-only."},"timezone":{"type":"string","description":"IANA zone cron_expr is evaluated in; empty = UTC."},"is_active":{"type":"boolean","description":"A paused transform is not scheduled, and its manual-run endpoint answers 409."},"last_run_at":{"type":"string","format":"date-time","nullable":true},"next_run_at":{"type":"string","format":"date-time","nullable":true,"description":"Cleared on every save and on pause; the scheduler recomputes it from cron_expr."},"created_by":{"type":"string","description":"Auth caller identity (user email, root, or app key hash) that created the transform. For a dataset transform this is also whose entitlement the scheduled report run inherits."},"updated_by":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"last_run":{"allOf":[{"$ref":"#/components/schemas/SQLTransformRun"}],"description":"The transform's most recent run, on get and list reads. ABSENT when the transform has never run — a different answer from a run that wrote nothing, and callers should render it as such rather than as zeroes."}}},"SQLTransformRun":{"type":"object","description":"One execution of a transform.","properties":{"id":{"type":"string","format":"uuid"},"transform_id":{"type":"string","format":"uuid"},"started_at":{"type":"string","format":"date-time"},"finished_at":{"type":"string","format":"date-time","description":"Absent while the run is still in flight."},"status":{"type":"string","enum":["running","success","partial","failed"]},"rows_affected":{"type":"integer","format":"int64","description":"Rows written by the transform."},"rows_failed":{"type":"integer","format":"int64"},"error_summary":{"type":"string","description":"Present on partial/failed runs."},"sweep":{"type":"object","description":"What a dataset run's sweep did. Absent when no sweep was considered: a warehouse\ntransform, a run that is still in flight, failed or partial, a cancelled run, an empty\nreport, or one whose owned records could not be listed.\n","required":["deleted"],"properties":{"skipped":{"type":"string","enum":["truncated","shrink_guard"],"description":"Why nothing was deleted. `truncated`: the report returned as many rows as its row\nlimit, so it may have been cut short (`would_delete` and `owned` are absent).\n`shrink_guard`: more than half of the owned records would have been deleted; queue a\nrun with `force_sweep=true` to confirm. Absent when the sweep ran.\n"},"would_delete":{"type":"integer","format":"int64","description":"Owned records whose key the report no longer returns. Absent when zero or unknown."},"owned":{"type":"integer","format":"int64","description":"Records this transform owned before the sweep. Absent when zero or unknown."},"deleted":{"type":"integer","format":"int64","description":"Records the sweep deleted (0 when it was skipped)."}}}}},"FieldMappingRequest":{"type":"object","required":["csv_column","target_field"],"properties":{"csv_column":{"type":"string","description":"Column header in the CSV file (imports match it, exports write it)."},"target_field":{"type":"string","description":"Import token: identifier.<key>, attribute.<key>, event_type, event_timestamp, source, event_key (events: a stable source key the event id derives from, scoped per connector), consent.*, profile_link.*, dataset.record_key, signal.* (signals imports: signal.name + signal.value required; signal.computed_at / signal.valid_until / signal.model_version optional), _skip. Batch sinks use the export grammar instead: the data type's core row fields (e.g. profile_id, entity_type, created_at) plus identifier./attribute. where applicable; profiles exports additionally accept computed.<name> and signal.<name>. A computed.<name> target must name an existing computed attribute for the entity type of the connector's schedule export_filter (falling back to connection.entity_type); computed.* is the all-computed token and is not checked. Without a resolvable entity type a computed.<name> mapping is refused."},"field_type":{"type":"string","enum":["string","integer","decimal","boolean","datetime","json","array_string"],"default":"string","description":"How imports parse attribute.* values; ignored on exports."},"is_required":{"type":"boolean","default":false,"description":"Imports only — the whole row fails when the column is missing/empty."},"sort_order":{"type":"integer","default":0}}},"FieldMappingResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"csv_column":{"type":"string"},"target_field":{"type":"string"},"field_type":{"type":"string"},"is_required":{"type":"boolean"},"sort_order":{"type":"integer"}}},"BatchScheduleRequest":{"type":"object","properties":{"cron_expr":{"type":"string","description":"Cron expression for automatic scheduling, evaluated in the schedule's timezone (UTC when unset); an expression that never occurs (such as 30 February) is refused with 400. Empty = manual-only: the schedule (path pattern, export filter) is kept but runs start only via POST /connect/connectors/{id}/trigger."},"timezone":{"type":"string","description":"IANA zone cron_expr is evaluated in (validated at save). Empty defaults to the configuring user's profile timezone for session callers, else stays empty = UTC (the historical behaviour).","example":"Europe/Bratislava"},"path_pattern":{"type":"string","description":"Required for every protocol except sql (400 \"path_pattern is required\"); a sql connector refuses it (400 \"path_pattern is not used by sql connectors\"), and refuses match_mode=regex too. Import: pattern for objects to read — a shell glob (e.g. imports/*.csv) when match_mode=glob, or a Go regular expression (e.g. data_\\d{4}-\\d{2}-\\d{2}\\.csv) when match_mode=regex. Export: object key to write, with tokens {date}/{datetime}/{run_id}, plus {part} (required when export_filter.page_size > 0) for the 1-based page number."},"match_mode":{"type":"string","enum":["glob","regex"],"default":"glob","description":"Import sources: how path_pattern selects objects. glob (default) matches with shell globbing after {date}/{datetime} token expansion; regex matches keys against path_pattern as a Go regular expression (no token expansion, validated at save). Ignored by sinks."},"export_filter":{"$ref":"#/components/schemas/ConnectorExportFilter"},"run_once":{"type":"boolean","default":false,"description":"One-time job: the first fully successful run deactivates the connector (shown as Completed). Failed/partial runs keep it active for a retry."},"skip_empty_export":{"type":"boolean","default":true,"description":"Batch sinks: when true (default) an export run producing no rows creates no output file; when false a header-only CSV is written. For a `sql` sink it decides between leaving the target table untouched and replacing it with an empty one (the run log says which happened), and a skipped-empty sql export does NOT advance export_filter.incremental's cursor — a CSV one does. Omitting the field defaults to true."},"fail_if_exists":{"type":"boolean","default":false,"description":"Batch sinks: when true, an export run fails instead of overwriting a file that already exists at the target key (checked per file, so a paginated run also fails if any part exists). Default false (overwrite)."}}},"ConnectorExportFilter":{"type":"object","description":"Sink-only row selection for batch export runs. Validated against the connector's data_type at save.","properties":{"entity_type":{"type":"string","description":"Profiles/consents/signals connectors. Must name an entity type that exists in the tenant (400 otherwise)."},"event_types":{"type":"array","items":{"type":"string"},"description":"Events connectors; empty = all."},"dataset_name":{"type":"string","description":"Custom-dataset connectors."},"since":{"type":"string","description":"RFC3339 / YYYY-MM-DD lower bound, on the data type's own timestamp column (events: timestamp; consents: updated_at; profiles/profile_links/custom datasets: created_at; signals: computed_at). Kept as configured across incremental runs — see incremental below, which windows on a different, ingest-time column instead of replacing this."},"limit":{"type":"integer","description":"Max rows per run; 0 = no limit."},"page_size":{"type":"integer","description":"Split the run into files of at most this many rows each; requires a {part} token in path_pattern. 0 = single file. Applied on top of limit (which caps total rows)."},"incremental":{"type":"boolean","description":"Export only rows newer than export_cursor (start of the previous successful run), minus a 10-minute overlap margin. The cursor windows on ingested_at, the time the row was stored, so neither writer lag nor a row's own caller- or source-supplied timestamp (event timestamp, signal computed_at) can drop it behind the cursor. Rows written before ingested_at existed fall back to their previous ingest-time column (created_at for events/profiles/profile_links/custom datasets, updated_at for consents). The margin now only covers clock skew between hosts. That makes exports at-least-once across the margin: a downstream consumer should dedupe by row id (event id, profile id, etc.). since keeps applying on top, unmodified, as its own independent window. NOTE the sink-type difference when a run produces no rows and skip_empty_export is set: a CSV sink still ADVANCES the cursor (nothing was withheld — there was nothing to write), while a `sql` sink does NOT, because the run aborts before publishing and the next run re-reads the same window. Harmless for a replace/merge sink, but it means a sql sink's window can span several ticks."},"profile_filter":{"type":"object","additionalProperties":true,"description":"Full querybuilder tree (same grammar as GET /profiles filter param); profiles connectors, and consents connectors (exports consents of the matching profiles). Requires entity_type."},"attr_filters":{"type":"array","description":"Simplified attribute rules; events (exactly one event type required) and custom datasets.","items":{"type":"object","properties":{"key":{"type":"string"},"operator":{"type":"string","enum":["=","!=","<","<=",">",">=","contains","begins_with","ends_with","exists","not_exists"]},"value":{}}}},"parent_entity_types":{"type":"array","items":{"type":"string"},"description":"profile_links connectors only: export links whose parent profile has one of these entity types."},"child_entity_types":{"type":"array","items":{"type":"string"},"description":"profile_links connectors only: export links whose child profile has one of these entity types. Combined with parent_entity_types as OR."},"signal_names":{"type":"array","items":{"type":"string"},"description":"signals connectors only: export only these signals. Empty/absent = every signal of the (optionally) filtered entity, which is more data than most destinations asked for and possibly more than they are entitled to."}}},"BatchScheduleResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"cron_expr":{"type":"string"},"path_pattern":{"type":"string"},"export_filter":{"type":"object","additionalProperties":true},"run_once":{"type":"boolean"},"skip_empty_export":{"type":"boolean","description":"Batch sinks: skip creating an output file when the export produces no rows."},"fail_if_exists":{"type":"boolean","description":"Batch sinks: fail the run instead of overwriting a file that already exists at the target key."},"match_mode":{"type":"string","enum":["glob","regex"],"description":"Import sources: glob (default) or regex object-key matching for path_pattern."},"timezone":{"type":"string","description":"IANA zone cron_expr is evaluated in; empty = UTC."},"last_run_at":{"type":"string","format":"date-time","nullable":true},"next_run_at":{"type":"string","format":"date-time","nullable":true},"export_cursor":{"type":"string","format":"date-time","nullable":true,"description":"Incremental exports — end of the last successfully exported window."}}},"ExportPreviewRequest":{"type":"object","properties":{"export_filter":{"$ref":"#/components/schemas/ConnectorExportFilter"}}},"ExportPreviewResponse":{"type":"object","properties":{"count":{"type":"integer","format":"int64","description":"Estimated rows the export would write, already capped by the filter's limit."},"data_type":{"type":"string","description":"The connector's data type the count is for."}}},"TransformScriptRequest":{"type":"object","required":["direction"],"properties":{"direction":{"type":"string","enum":["import","export"]},"script":{"type":"string","maxLength":65536,"description":"Starlark script with a transform(payload) function. An empty or whitespace-only value REMOVES any stored transform for the direction, so the connector runs transform-free (idempotent — a no-op when nothing is stored). At most 64 KiB. Compiled at save under the same step (5 000 000), memory (256 MB heap growth) and 5 s budgets as the connector runtime.\n"}}},"TransformScriptResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"direction":{"type":"string","enum":["import","export"]},"script":{"type":"string"},"updated_at":{"type":"string","format":"date-time"}}},"TransformTestRequest":{"type":"object","required":["script","payload"],"properties":{"script":{"type":"string","maxLength":65536,"description":"Starlark script with a transform(payload) function. At most 64 KiB."},"payload":{"type":"string","maxLength":1048576,"description":"Raw JSON text of a sample source message (at most 1 MiB). Invalid JSON is reported back as an error rather than rejected."}}},"TransformTestResponse":{"type":"object","properties":{"ok":{"type":"boolean","description":"True when the script compiled and ran without error."},"skipped":{"type":"boolean","description":"True when transform returned None — the message would be dropped."},"error":{"type":"string","description":"Compile or runtime error message; empty on success."},"record":{"type":"object","additionalProperties":true,"description":"The record the pipeline extracted from the transform's returned dict, in the same key shape the script returns (identifiers, attributes, event_type, consent_*, etc.). Only recognised, non-empty keys appear. Present only when ok is true and skipped is false."}}},"TransformAssistRequest":{"type":"object","required":["prompt"],"properties":{"prompt":{"type":"string","description":"Natural-language description of the desired transform (truncated at 4000 characters)."},"script":{"type":"string","description":"Optional current editor content, given to the model as context so it can amend rather than start over (truncated at 16000 characters)."}}},"TransformAssistResponse":{"type":"object","properties":{"feasible":{"type":"boolean","description":"False when the model judged the request impossible under the transform contract — notes explains why."},"code":{"type":"string","description":"Complete candidate Starlark script (empty when feasible is false). Never persisted server-side."},"notes":{"type":"string","description":"Short remarks — assumptions made, or the reason the request cannot be fulfilled."},"compile_ok":{"type":"boolean","description":"True when the generated code passed a server-side Starlark compile check (after up to 2 self-repair rounds)."},"compile_error":{"type":"string","description":"Compile error for the generated code, when compile_ok is false."},"repair_rounds":{"type":"integer","description":"Number of self-repair LLM calls that produced this code (compile error fed back to the model, capped server-side at 2). When the cap is hit the last draft is returned anyway with compile_ok=false so the operator can fix it or ask again."},"direction":{"type":"string","enum":["import","export"],"description":"Script direction derived from the connector kind."},"data_type":{"type":"string","description":"The connector's data type the script targets."}}},"RunLogResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"connector_id":{"type":"string","format":"uuid"},"started_at":{"type":"string","format":"date-time"},"finished_at":{"type":"string","format":"date-time","nullable":true},"status":{"type":"string","enum":["running","success","partial","failed"]},"rows_processed":{"type":"integer","format":"int64"},"rows_skipped":{"type":"integer","description":"Rows dropped by the import row filter / path_pattern glob."},"rows_failed":{"type":"integer","format":"int64"},"error_summary":{"type":"string","description":"On failed/partial runs, the error reason. On a successful run, a non-error diagnostic when nothing was processed (e.g. no objects found, or none matched the path pattern)."},"object_keys":{"type":"array","items":{"type":"string"},"description":"Files the run touched: the object an export wrote, or the objects an import read (capped at 200)."}}},"StreamLogEntryResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"connector_id":{"type":"string","format":"uuid"},"logged_at":{"type":"string","format":"date-time"},"kind":{"type":"string","enum":["sample","error"]},"direction":{"type":"string","enum":["import","export"],"description":"import = stream_source, export = stream_sink."},"payload_before":{"type":"string","description":"The message as read from the stream (import) or derived for it (export), before any transform. Truncated at 4 KB. On kind=error, the payload tied to the error when one exists."},"payload_after":{"type":"string","nullable":true,"description":"The post-transform payload. Present only when a transform script ran (samples only)."},"error":{"type":"string","description":"The error message (kind=error only)."}}},"AIExplainRequest":{"type":"object","required":["subject"],"properties":{"kind":{"type":"string","default":"error","description":"Assistant behaviour; supported: error."},"subject":{"type":"string","description":"The text to explain (truncated at 8000 chars)."},"context":{"type":"object","additionalProperties":{"type":"string"},"description":"Optional labelled details included in the prompt."}}},"AIExplainResponse":{"type":"object","properties":{"kind":{"type":"string"},"explanation":{"type":"string"}}},"TriggerResponse":{"type":"object","properties":{"run_id":{"type":"string","format":"uuid","description":"ID of the queued run (202)","or of the run already in flight (409).":null}}},"UploadedFileResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"filename":{"type":"string"},"size_bytes":{"type":"integer"},"uploaded_at":{"type":"string","format":"date-time"},"processed_at":{"type":"string","format":"date-time","nullable":true,"description":"Null while pending; set once the file has been imported."}}},"TestConnectionResponse":{"type":"object","properties":{"success":{"type":"boolean","description":"True when the connectivity check passed."},"message":{"type":"string","description":"Human-readable summary of the result."},"details":{"description":"Optional extra info (e.g. first 5 object keys for batch_source).","nullable":true}}},"NetworkRequest":{"type":"object","required":["name","type"],"properties":{"name":{"type":"string","description":"Unique per tenant (case-insensitive)."},"type":{"type":"string","enum":["ssh","socks5","http_connect","wireguard"],"description":"All four types are implemented."},"description":{"type":"string"},"enabled":{"type":"boolean","default":true},"config":{"type":"object","description":"Non-secret params. The network's OWN endpoint (ssh/proxy `host`, wireguard `endpoint`) must be a routable address: loopback, link-local (incl. 169.254.169.254), unspecified and multicast are rejected at save time, because that endpoint is dialed directly — before any tunnel exists — and would otherwise make /test report whether an arbitrary internal address is listening. ssh: host (required), port (default 22), user (required), host_key (required — known-hosts line or authorized-keys entry), keepalive_sec (default 30), probe_addr (optional host:port dialed through the tunnel by /test). socks5 / http_connect: host + port (both required), probe_addr (optional). wireguard: endpoint (host:port of the customer's public listener, required), peer_public_key (base64 or hex, required), local_address (this peer's tunnel IP(s), required, CIDR suffix tolerated), allowed_ips (default 0.0.0.0/0 + ::/0), dns (the customer's internal resolver — names then resolve INSIDE the tunnel), mtu (default 1420), keepalive_sec (persistent keepalive, default 25), probe_addr."},"credentials":{"type":"object","additionalProperties":{"type":"string"},"description":"Write-only; never returned. ssh: private_key (PEM) or password (one required on create). socks5 / http_connect: username + password (optional — many egress proxies are network-ACLed). wireguard: private_key (base64 or hex, required on create) and optional preshared_key. On update: omitted = keep stored, empty object = clear."},"allowed_cidrs":{"type":"array","items":{"type":"string"},"description":"Destination allowlist for dials through the tunnel (literal-IP destinations); empty = unrestricted within the tunnel's own reach. Bare IPs are accepted as /32 (or /128)."}}},"NetworkResponse":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","enum":["ssh","socks5","http_connect","wireguard"]},"description":{"type":"string"},"enabled":{"type":"boolean"},"credentials_set":{"type":"boolean","description":"Whether encrypted credentials are stored (credentials themselves are write-only)."},"config":{"type":"object","nullable":true},"allowed_cidrs":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["up","down","unknown"],"description":"Last observed tunnel state (persisted by /test and background reconcile runs)."},"status_detail":{"type":"string","description":"Last failure reason; empty while up."},"last_ok_at":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"created_by":{"type":"string"},"updated_by":{"type":"string"}}},"NetworkTestResponse":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string","description":"\"tunnel is up\" or the structured failure reason."},"latency_ms":{"type":"integer","description":"Time the handshake (plus probe_addr dial, when set) took."}}},"EdgeSettingsRequest":{"type":"object","required":["entity_type","device_identifier_key"],"properties":{"entity_type":{"type":"string","description":"The web (and default) tracking entity — every edge write lands on one of the configured tracking entities, routed by the SDK key's platform (must exist)."},"device_identifier_key":{"type":"string","description":"The identifier key holding the SDK-generated device id (web/default entity)."},"mobile_entity_type":{"type":"string","description":"Tracking entity for mobile SDK keys; empty = same as entity_type (the platforms may share one entity). Must exist when set."},"mobile_device_identifier_key":{"type":"string","description":"Device identifier key for mobile SDK keys; empty = same as device_identifier_key."},"identify_enabled":{"type":"boolean","default":true,"description":"Whether /edge/v1/identify is accepted at all."},"identify_allowed_keys":{"type":"array","items":{"type":"string"},"description":"Identifier keys identify may attach (must not contain the device key). Empty = none."},"identify_allowed_attributes":{"type":"array","items":{"type":"string"},"description":"Profile attributes identify may set/update on the tracking entity. Every entry must exist in the entity's attribute schema; purpose-tagged attributes outside collection_purposes are a structured 400 in enforce/strict privacy mode. Empty = none."},"consent_mode":{"type":"string","enum":["require","optional"],"default":"optional"},"required_purposes":{"type":"array","items":{"type":"string"},"description":"consent_mode=require gate — hits not declaring all of these are dropped. Must exist in the purpose catalog."},"collection_purposes":{"type":"array","items":{"type":"string"},"description":"Provenance stamp set — stored purposes are the SDK-declared set ∩ this. Must exist in the purpose catalog."},"public_base_url":{"type":"string","format":"uri","description":"The externally reachable base URL of the gateway (e.g. https://track.example.com), used to build hosted form/page URLs. Empty = no hosted pages until configured."},"cmp_mode":{"type":"string","enum":["off","observe","enforce"],"default":"off","description":"How a decoded CMP signal (IAB TCF v2.x, Google Consent Mode v2, vendor keys) affects collection: off ignores it, observe audits without gating, enforce gates collection on the mapped purposes. enforce requires a non-empty cmp_purpose_map."},"cmp_purpose_map":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Maps a CMP vendor's own purpose/category token (tcf:N, tcf:li:N, gcm:<key>, key:<name>) to one or more CDP consent purposes. Purposes reached from a tcf:li: token must have lawful_basis=legitimate_interest; every other token must map only to consent-basis purposes. At most 256 tokens, 8 purposes per token; every target purpose must exist and be active."}}},"EdgeSettingsResponse":{"type":"object","properties":{"entity_type":{"type":"string"},"device_identifier_key":{"type":"string"},"mobile_entity_type":{"type":"string"},"mobile_device_identifier_key":{"type":"string"},"identify_enabled":{"type":"boolean"},"identify_allowed_keys":{"type":"array","items":{"type":"string"}},"identify_allowed_attributes":{"type":"array","items":{"type":"string"}},"consent_mode":{"type":"string","enum":["require","optional"]},"required_purposes":{"type":"array","items":{"type":"string"}},"collection_purposes":{"type":"array","items":{"type":"string"}},"public_base_url":{"type":"string","description":"Empty until configured — no hosted form/page URL can be built."},"cmp_mode":{"type":"string","enum":["off","observe","enforce"]},"cmp_purpose_map":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}},"updated_at":{"type":"string","format":"date-time"}}},"EdgeSDKKeyRequest":{"type":"object","required":["name","platform"],"properties":{"name":{"type":"string"},"platform":{"type":"string","enum":["web","mobile"]},"allowed_origins":{"type":"array","items":{"type":"string"},"description":"Required non-empty for web keys; each a bare scheme://host[:port] origin (no paths, no wildcards). Ignored at request time for mobile keys (no Origin header exists), format-checked if present."},"rate_limit_rpm":{"type":"integer","minimum":1,"nullable":true,"description":"Per-key requests/minute override; null = the instance default."},"active":{"type":"boolean","default":true}}},"EdgeSDKKeyResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"token":{"type":"string","description":"'oek_' + 32 base62 chars. Public by design (identifies config, grants nothing secret) — returned on every read."},"platform":{"type":"string","enum":["web","mobile"]},"allowed_origins":{"type":"array","items":{"type":"string"}},"active":{"type":"boolean"},"revoked_at":{"type":"string","format":"date-time","nullable":true},"rate_limit_rpm":{"type":"integer","nullable":true},"identify_secret_configured":{"type":"boolean","description":"Whether the key has an identify signing secret. The secret itself is returned only once, by the rotate endpoint."},"identify_secret_set_at":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"EdgeIdentifySecretResponse":{"type":"object","description":"Returned ONCE. A customer backend signs identity assertions with it: sig = base64url(HMAC-SHA256(secret, tenant_id \"\\n\" key_token \"\\n\" key \"\\n\" value \"\\n\" exp)), exp a unix time at most 24 h ahead. See docs/oapi3_edge.yml IdentityAssertion.\n","properties":{"key_id":{"type":"string","format":"uuid"},"secret":{"type":"string","description":"'eis_' + 64 hex chars. Use the whole string as the HMAC key."},"set_at":{"type":"string","format":"date-time"},"tenant_id":{"type":"string","description":"The tenant_id MAC input (the SDK key token's tenant; \"default\" for unprefixed tokens)."},"key_token":{"type":"string","description":"The edge_key_token MAC input."}}},"EdgeCategoryMappingRequest":{"type":"object","required":["category","event_type"],"properties":{"category":{"type":"string","maxLength":128,"description":"The semantic SDK category (page_visit, add_to_cart, …). Unique."},"event_type":{"type":"string","description":"The CDP event type hits of this category become (must exist)."},"attribute_mapping":{"type":"object","additionalProperties":{"type":"string"},"description":"Allowlist mapping of hit fields to event attributes. Keys are source tokens ($name, $context.<url|referrer|title|language|screen_w|screen_h|ua>, $props.<key>); values are attribute keys of the event type. Everything unmapped is dropped."},"active":{"type":"boolean","default":true}}},"EdgeCategoryMappingResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"category":{"type":"string"},"event_type":{"type":"string"},"attribute_mapping":{"type":"object","additionalProperties":{"type":"string"}},"active":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"EdgeTrackerRequest":{"type":"object","required":["name","purpose"],"properties":{"name":{"type":"string","maxLength":128,"description":"The tracker/script's display name (e.g. \"Google Analytics 4\"). Unique per tenant (409 on a clash)."},"description":{"type":"string","maxLength":1024},"purpose":{"type":"string","description":"The CDP consent purpose this tracker's collection maps to. Must be an active purpose in the catalogue."},"is_active":{"type":"boolean","default":true},"kind":{"type":"string","enum":["page","script","pixel","html"],"default":"page","description":"How the Web SDK runs the tracker.\n`page` = the site's own `<script type=\"text/plain\" data-optima-tracker>` placeholder;\n`script` = a vendor `<script src>` the SDK injects; `pixel` = an image beacon;\n`html` = a raw HTML/JS body through the SDK code runner (403 while the\ninstance setting `edge_tag_html_enabled` is off).\n"},"config":{"type":"object","description":"Kind-specific body. page: must be empty. script: `{src (https, ≤2048), async?, defer?, attributes?}` —\nattributes ≤16 entries, keys `data-*|id|crossorigin|referrerpolicy|integrity`, string values ≤512.\npixel: `{src}` (https, ≤2048; macros `{{ts}}` and `{{url}}` only). html: `{html}` (≤65536 bytes).\nhtml bodies are served verbatim to every holder of the tenant's public SDK key, so they must never contain secrets.\n"},"url_patterns":{"type":"array","maxItems":32,"items":{"type":"string","maxLength":512},"description":"path.Match globs against the full page URL (no fragment); `*` never crosses `/`; character classes rejected. Empty = every page."}}},"EdgeTrackerResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string"},"purpose":{"type":"string"},"is_active":{"type":"boolean"},"kind":{"type":"string","enum":["page","script","pixel","html"]},"config":{"type":"object"},"url_patterns":{"type":"array","items":{"type":"string"}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"EdgePreviewRequest":{"type":"object","description":"Ad-hoc edge-dialect template preview. For kind=payload, `source` is the structured JSON document as a STRING. `context` mirrors the serve-time personalization context ({{.Attributes.x}}, {{if .Consents.x}}, {{.Parents.<entity>.x}}, {{range .Children.<entity>}}, {{range .Datasets.<name>}}, {{.Data.x}}, {{.Found}}); omitted = the empty context an unknown device resolves to.\n","properties":{"kind":{"type":"string","enum":["html","text","payload"]},"source":{"type":"string"},"context":{"type":"object","properties":{"found":{"type":"boolean"},"attributes":{"type":"object"},"consents":{"type":"object","additionalProperties":{"type":"boolean"}},"parents":{"type":"object","additionalProperties":{"type":"object"}},"children":{"type":"object","additionalProperties":{"type":"array","items":{"type":"object"}}},"datasets":{"type":"object","additionalProperties":{"type":"array","items":{"type":"object"}}},"data":{"type":"object"}}}},"required":["kind","source"]},"EdgePreviewResponse":{"type":"object","description":"Outcome of one edge preview. A broken template answers ok=false with the exact error — the request itself still succeeds.\n","properties":{"ok":{"type":"boolean"},"rendered":{"type":"string"},"error":{"type":"object","properties":{"message":{"type":"string"},"line":{"type":"integer","description":"0/absent = the error carried no position."}}}}},"EdgeCMPCoveragePurpose":{"type":"object","description":"One Optima purpose's granted/denied tally over the window.","properties":{"granted":{"type":"integer","format":"int64"},"denied":{"type":"integer","format":"int64"}}},"EdgeCMPCoverageKey":{"type":"object","description":"One SDK key's CMP coverage. total counts every tracked request seen while a CMP mode was active — INCLUDING requests that carried no signal, which is what makes total-minus-signal meaningful. Keys with all-zero counts are returned rather than omitted. Under consent_mode=require with an enforce-mode CMP, a batch that fails the require gate is refused at the gateway and never reaches the counters — those visitors are absent from both total and each purpose's denied, not folded into either.\n","properties":{"key_id":{"type":"string"},"key_name":{"type":"string"},"total":{"type":"integer","format":"int64"},"signal":{"type":"integer","format":"int64","description":"Requests whose CMP part decoded to at least one external token."},"unparseable":{"type":"integer","format":"int64","description":"Requests whose TCF part would not decode. A broken site integration, not lost data — the request was still accepted."},"purposes":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/EdgeCMPCoveragePurpose"}}}},"EdgeCMPCoverageResponse":{"type":"object","description":"Aggregated CMP coverage over the requested window. approximate is always true: the counters are best-effort counters, not a ledger.\n","properties":{"days":{"type":"integer"},"approximate":{"type":"boolean"},"keys":{"type":"array","items":{"$ref":"#/components/schemas/EdgeCMPCoverageKey"}}}},"EdgeContentItemRequest":{"type":"object","required":["slot","name"],"properties":{"slot":{"type":"string","maxLength":128,"description":"The content slot the SDK requests (GET /edge/v1/content?slot=…)."},"name":{"type":"string","description":"Operator-facing label; never served to SDKs."},"content_type":{"type":"string","enum":["banner","inline","custom","banner_consent"],"default":"banner","description":"Rendering hint only — EXCEPT `banner_consent`, the consent banner (see `payload`). It also selects which licence feature governs the item: `banner_consent` needs \"banners\", every other type needs \"content\". The endpoints admit either feature and then enforce the per-item one (403 with reason=feature_not_licensed), so a banners-only tenant can author banners without the content suite and vice versa; the list is filtered to the licensed types. `banner_consent` additionally forces `payload_format=structured` and `personalized=false` (400 otherwise), and has its payload validated and normalized at save time.\n"},"payload_format":{"type":"string","enum":["structured","unstructured"],"default":"structured","description":"structured = the JSON rendering contract in payload; unstructured = raw HTML/CSS/JS in body, served to SDKs as is."},"payload":{"type":"object","description":"The structured-JSON rendering-contract payload served verbatim to SDKs. Never put per-customer or confidential data here — published content is visible to anyone holding the public SDK key. A payload carrying `\"kind\": \"items\"` opts into item-level onsite recommendations instead of being served verbatim: `{\"kind\": \"items\", \"catalog\": \"<name>\", \"strategy\": \"trending\"|\"recently_viewed\"|\"affinity\", \"count\": 0-20, \"template\": {...}}`. Validated at save time: `catalog` non-empty; `strategy` one of the three above — `similar_to`/`blend` are rejected (400, names the strategy) as not available onsite (no seed item / can't express the blend over this wire); `count` an integer 0-20 (0 = the default of 6); `personalized` MUST be `true` (400 otherwise) — the payload is resolved and rendered server-side, never served as-is. `template`'s string values are parse-validated as ordinary personalization templates (same rule as any personalized payload) and may address `{{range .Items}}...{{end}}` over the resolved recommendation rows.\nWith `content_type: banner_consent` the payload is instead a CLOSED contract (any other top-level key is a 400), validated and NORMALIZED at save — what is stored is never the bytes sent. `purposes` (required) is either the string `\"visible\"` (every catalogue purpose with visible_in_preference_center, resolved at SERVE time) or a non-empty array of purpose names; each named purpose must exist, be active, be visible_in_preference_center and have `lawful_basis=\"consent\"` — the 400 names the purpose and the rule it failed, and duplicates collapse. `languages` (required) is an object keyed by language with at least one entry and a `\"default\"` one; each entry is an object of STRING fields — `title`, `body`, `object_label`, and the button/link labels the Web SDK renders: `accept_all`, `reject_all`, `manage` (reveals the per-purpose choices), `save`, `policy_link_text` (its href is `layout.policy_url`) — plus the one nested exception `buttons`, the SDK's pre-1.1.2 label object whose keys are limited to `accept_all`, `reject_all` and `save` and whose values must be strings (still honoured as a fallback after the flat fields); `\"default\"` must carry a non-empty title and body.\n`layout` is opaque EXCEPT `layout.css`: an optional stylesheet (≤ 16384 bytes) stored AS AUTHORED (comments kept) and served stripped of comments/whitespace. It is validated at save so it can only reach the banner: every selector must start with `.optima-consent`, `.optima-overlay` or `#optima-overlay` (styling the container itself is allowed by design) and may not use a top-level sibling combinator `~` or `+`, which would style the host page NEXT TO the banner — descendant and `>` child combinators only go deeper into the banner's own subtree and stay allowed, and a `~`/`+` inside parentheses, brackets or a string is not top-level. The refusal is positional: a sibling combinator is refused ANYWHERE in the selector, including between two banner-internal elements (`.optima-consent__purpose + .optima-consent__purpose`) — use a descendant or `>` child combinator from the container instead, which covers those cases; at-rules are limited to `@media`/`@supports` (nested rules are checked too), `@font-face` and `@keyframes` (whose offsets must be `from`, `to` or a percentage); `url()` must use `https:` or `data:` and must be closed; `expression(`, `behavior:`, `-moz-binding:` and `javascript:` are refused; a backslash outside a quoted string is refused anywhere (a CSS escape is how `\\75 rl(` becomes `url(` — escapes are refused, not decoded; inside a string a backslash is ordinary content); the sequence `</style` is refused anywhere. A failure is a 400 whose message names the line and the rule (`line 3: selector \".header\" must start with …`). A blank sheet is stored as absent. While the instance setting `edge_banner_css_enabled` is off, a NEW or CHANGED sheet is a 403 (`custom banner css is disabled on this instance`); re-saving the stored sheet unchanged, or a save without the key, is still accepted.\n`policy` (required) is `{\"key\": \"<policy key>\", \"version\": <int>, \"locale\": \"<locale>\"}`, where version and locale are optional (locale defaults to `\"\"`, the default-locale text). The stored object is FROZEN to the resolved `{key, version, locale, hash, pinned}` — a client-sent hash is discarded, never trusted — so publishing newer policy text does not move an already-saved banner. `pinned` records WHY that version is there and decides what the next save does. Sending an explicit `version` pins it (`pinned: true`) and every later save keeps that exact version; omitting `version` resolves the newest active one and records `pinned: false`, so a PUT that round-trips the stored object re-resolves to the newest active version instead of re-freezing one the author never chose. A reference carrying a version but no `pinned` field reads as pinned (back-compat). An unknown key/version is a 400, and an explicitly named version that is NOT active is a 400 naming the remedy (\"omit version to use the newest active version\") — an already-frozen reference to a since-deactivated version keeps serving, only new saves are refused. `reask` (optional) is `{\"days\": <int >= 0>, \"on_policy_change\": <bool>}` and BOTH defaults (0 = never re-ask by age, on_policy_change = true) are written into the stored payload, so serve time never defaults anything. `layout` (optional) is an object, opaque to the server and passed through verbatim for the SDK to interpret; an explicit `null` is dropped rather than stored.\n"},"body":{"type":"string","maxLength":262144,"description":"The raw HTML/CSS/JS document (payload_format=unstructured only; max 256KB)."},"personalized":{"type":"boolean","default":false,"description":"Opts into server-side Go-template rendering against the requesting device's profile context ({{.Attributes.x}}, {{.Consents.x}}, {{.Parents.<entity>.x}}, {{range .Children.<entity>}}, {{range .Datasets.<name>}}, {{.Found}}). Templates are parse-validated at save and checked against the execution-budget rules (a 400 names the construct — {{range}} over a numeric literal or constant variable, range nesting deeper than 3, recursive {{template}}). At serve time each render call is bounded to 320 KiB of output and 200 ms; an item that exceeds either is dropped from the response. false = the content is served verbatim with no template processing."},"targeting":{"type":"object","description":"Phase-1 grammar: {} (always) or {\"url\": {\"match\": \"glob\", \"patterns\": [\"https://…/*\"]}}. No regex."},"priority":{"type":"integer","default":0,"description":"Items in a slot are served sorted by priority desc."},"starts_at":{"type":"string","format":"date-time","nullable":true,"description":"Schedule window start (null = open)."},"ends_at":{"type":"string","format":"date-time","nullable":true,"description":"Schedule window end (null = open). Must be after starts_at."}}},"EdgeFormOption":{"type":"object","description":"One <select> option on a form field.","properties":{"value":{"type":"string"},"label":{"type":"string"}}},"EdgeFormFieldRequest":{"type":"object","required":["target_kind","target_key","label"],"properties":{"target_kind":{"type":"string","enum":["attribute","identifier","consent"],"description":"What the field writes — a profile attribute","a profile identifier":null,"or a consent decision for one of the form's consent_purposes.":null},"target_key":{"type":"string","maxLength":128,"description":"The attribute key / identifier key / consent purpose name. Must be declared on the tracking entity (attribute/identifier) or listed in consent_purposes (consent). Attribute keys matching ^(card|cc|pan|cvv|cvc|iban|account_number) (case-insensitive) are always rejected — no payment data through a public form."},"input_type":{"type":"string","enum":["text","email","phone","number","checkbox","select","textarea","hidden"],"default":"text","description":"No file-upload type in v1."},"label":{"type":"string","maxLength":256},"labels":{"type":"object","additionalProperties":{"type":"string"},"description":"Per-language label overrides keyed by the tenant's language value, e.g. {\"sk\":\"Meno\"}. label is the fallback."},"placeholder":{"type":"string"},"required":{"type":"boolean","default":false},"validation_regex":{"type":"string","description":"RE2 pattern the whole value must match. Compiled at save time — an invalid pattern is a 400."},"options":{"type":"array","items":{"$ref":"#/components/schemas/EdgeFormOption"},"description":"Required non-empty when input_type=select."},"ask_once":{"type":"boolean","default":false,"description":"Progressive profiling — omit the field when the profile already holds a value for this target."}}},"EdgeFormRequest":{"type":"object","required":["slug","name","entity_type","fields"],"description":"The body for POST /edge/forms and PUT /edge/forms/:id. Status\ntransitions happen only through the publish/unpublish endpoints,\nnever through this body.\n\nSaving is refused with 422 unless the tenant declares event type\nform_submitted with a string attribute form_id — the platform emits\nthat event on every submit, and the operator must opt into the\nschema knowingly before a form can go live.\n","properties":{"slug":{"type":"string","pattern":"^[a-z0-9][a-z0-9-]{1,63}$","description":"Unique; identifies the hosted page (/edge/v1/pages/{key}/{slug}) and the submit endpoint."},"name":{"type":"string","description":"Operator-facing label."},"entity_type":{"type":"string","description":"Must be edge settings' entity_type or mobile_entity_type — every form write lands on one of the configured tracking entities."},"collection_purposes":{"type":"array","items":{"type":"string"},"description":"Provenance stamp for attribute/identifier writes (same semantics as edge settings' collection_purposes). Must exist in the purpose catalog."},"consent_purposes":{"type":"array","items":{"type":"string"},"description":"Purposes a consent-target field may decide. Must exist in the purpose catalog."},"policy_key":{"type":"string","description":"consent_policies row the receipt references. Required when any field targets a consent purpose; must resolve together with policy_version (400 otherwise)."},"policy_version":{"type":"integer"},"max_fields":{"type":"integer","minimum":0,"default":0,"description":"Progressive-profiling cap: at most this many remaining fields are shown per render. 0 = show every remaining field. Must be <= the number of fields."},"min_submit_interval_sec":{"type":"integer","minimum":0,"maximum":3600,"default":3,"description":"Anti-abuse floor between render and submit below which a submission is rejected as automated."},"double_opt_in":{"type":"boolean","default":false,"description":"Requires a confirmation click before the identifier/consent decisions take effect. Needs an identifier field for double_opt_in_identifier and a double_opt_in_template. Every purpose in consent_purposes must have lawful_basis consent (400 otherwise); publish re-checks it."},"double_opt_in_identifier":{"type":"string","default":"email","description":"Identifier key whose submitted value receives the confirmation mail."},"double_opt_in_template":{"type":"string","description":"notification_templates.name rendered for the confirmation mail. Required when double_opt_in is true and must name an existing notification template (400 otherwise); publish re-checks it."},"page_body":{"type":"string","maxLength":196608,"description":"Hosted page's raw HTML shell with {{.Form}} where the form goes. Empty = the built-in shell. Always rendered as a Go template, so it is parse-validated and checked against the execution-budget rules at save (400 on a range over a numeric literal or constant, range nesting deeper than 3, or a recursive template call) and rendered under a 256 KiB output / 200 ms budget at serve. Larger than 192 KiB (196608 bytes) is a 400 at save."},"page_personalized":{"type":"boolean","default":false,"description":"Opts page_body into server-side Go-template rendering against the device's profile context (same rule as edge content items' personalized). Parse-validated at save."},"page_title":{"type":"string"},"success_message":{"type":"string"},"success_redirect_url":{"type":"string"},"fields":{"type":"array","minItems":1,"maxItems":64,"items":{"$ref":"#/components/schemas/EdgeFormFieldRequest"},"description":"Each attribute/identifier/consent target may appear at most once."}}},"EdgeFormFieldResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"position":{"type":"integer","description":"Render order; stable identity within the form."},"target_kind":{"type":"string","enum":["attribute","identifier","consent"]},"target_key":{"type":"string"},"input_type":{"type":"string"},"label":{"type":"string"},"labels":{"type":"object","additionalProperties":{"type":"string"}},"placeholder":{"type":"string"},"required":{"type":"boolean"},"validation_regex":{"type":"string"},"options":{"type":"array","items":{"$ref":"#/components/schemas/EdgeFormOption"}},"ask_once":{"type":"boolean"}}},"EdgeFormResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","enum":["draft","published","archived"]},"entity_type":{"type":"string"},"collection_purposes":{"type":"array","items":{"type":"string"}},"consent_purposes":{"type":"array","items":{"type":"string"}},"policy_key":{"type":"string"},"policy_version":{"type":"integer"},"policy_hash":{"type":"string","description":"SHA-256 of the referenced policy's text, copied at save time (the DMZ role has no grant on consent_policies, so the receipt must be self-contained)."},"max_fields":{"type":"integer"},"min_submit_interval_sec":{"type":"integer"},"double_opt_in":{"type":"boolean"},"double_opt_in_identifier":{"type":"string"},"double_opt_in_template":{"type":"string"},"page_body":{"type":"string"},"page_personalized":{"type":"boolean"},"page_title":{"type":"string"},"success_message":{"type":"string"},"success_redirect_url":{"type":"string"},"published_at":{"type":"string","format":"date-time","nullable":true,"description":"Kept as history after unpublish."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"fields":{"type":"array","items":{"$ref":"#/components/schemas/EdgeFormFieldResponse"}},"page_url":{"type":"string","description":"public_base_url + /edge/v1/pages/{web SDK key token}/{slug}. Absent until both edge settings' public_base_url and at least one active web SDK key exist."}}},"RecommendationCatalogRequest":{"type":"object","required":["name","dataset_name","field_roles"],"description":"The body for POST/PUT /recommendations/catalogs. field_roles,\ninteraction_events and business_rules are strict-decoded (unknown\nkeys reject) and validated server-side (recommend.ParseCatalog) —\n422 on a shape/constraint violation, 400 if dataset_name doesn't\nresolve to an existing custom dataset or any referenced field\n(field_roles.title/image/url/price/availability when non-empty,\nevery affinity field, every business_rules.exclude/require field)\nis absent from that dataset's attribute_types.\n","properties":{"name":{"type":"string","minLength":1,"maxLength":128,"description":"Unique catalogue name."},"dataset_name":{"type":"string","description":"An existing custom dataset (POST /custom-datasets) holding the item catalogue."},"field_roles":{"type":"object","description":"Which dataset fields carry the title/image/url/price/availability roles, plus optional affinity fields (each field, an optional signal name defaulting to affinity_<field>, and an optional weight defaulting to 1).","properties":{"title":{"type":"string","description":"Required dataset field for the item's display title."},"image":{"type":"string"},"url":{"type":"string"},"price":{"type":"string"},"availability":{"type":"string"},"affinity":{"type":"array","maxItems":8,"items":{"type":"object","required":["field"],"properties":{"field":{"type":"string"},"signal":{"type":"string","description":"Signal name to score against. Default: affinity_<field>."},"weight":{"type":"number","minimum":0,"description":"Default 1."}}}}}},"interaction_events":{"type":"array","maxItems":16,"description":"Event types that feed interaction weighting (view/cart/purchase), each naming the item-key attribute on the event.","items":{"type":"object","required":["event_type","action","item_attribute"],"properties":{"event_type":{"type":"string"},"action":{"type":"string","enum":["view","cart","purchase"]},"item_attribute":{"type":"string","description":"Event attribute carrying the item key. For an active catalogue it must be a declared string attribute of event_type (400 otherwise): item keys are read as strings."},"session_attribute":{"type":"string","description":"Optional session grouping attribute. Default groups by (profile_id, day)."},"weight":{"type":"number","minimum":0,"description":"Default by action: view=1, cart=3, purchase=5."}}}},"business_rules":{"type":"object","properties":{"pins":{"type":"array","maxItems":20,"items":{"type":"object","required":["item_key","slot"],"properties":{"item_key":{"type":"string"},"slot":{"type":"integer","minimum":1},"starts_at":{"type":"string","format":"date-time"},"ends_at":{"type":"string","format":"date-time"}}}},"boosts":{"type":"array","maxItems":50,"description":"Each boost specifies exactly one of item_key or (field + value).","items":{"type":"object","required":["factor"],"properties":{"item_key":{"type":"string"},"field":{"type":"string"},"value":{"type":"string"},"factor":{"type":"number","exclusiveMinimum":0}}}},"exclude":{"type":"array","maxItems":32,"items":{"$ref":"#/components/schemas/RecommendationAttrRule"}},"require":{"type":"array","maxItems":32,"items":{"$ref":"#/components/schemas/RecommendationAttrRule"}}}},"is_active":{"type":"boolean","description":"Omit to default true on create, or preserve the stored value on update."}}},"RecommendationAttrRule":{"type":"object","required":["field","op","value"],"properties":{"field":{"type":"string"},"op":{"type":"string","enum":["eq","neq","lt","lte","gt","gte"]},"value":{"type":"string"}}},"RecommendationCatalogObject":{"type":"object","description":"The response DTO for a recommendation catalogue — request fields plus server-assigned id/timestamps.","properties":{"id":{"type":"string","format":"uuid","readOnly":true},"name":{"type":"string"},"dataset_name":{"type":"string"},"field_roles":{"type":"object","description":"As stored — see RecommendationCatalogRequest.field_roles."},"interaction_events":{"type":"array","items":{"type":"object"},"description":"As stored — see RecommendationCatalogRequest.interaction_events."},"business_rules":{"type":"object","description":"As stored — see RecommendationCatalogRequest.business_rules."},"is_active":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"ReencryptResult":{"type":"object","properties":{"total":{"type":"integer"},"reencrypted":{"type":"integer"},"already_current":{"type":"integer"},"failed":{"type":"array","items":{"type":"string"},"description":"Ids whose blob opened under neither key or could not be stored."}}},"RecommendRequest":{"type":"object","required":["profile_id","strategy"],"description":"The body for POST /recommendations/{catalog}. `filter` reuses\nEventAttrRule's grammar, but only its six comparison operators\n(=, !=, <, <=, >, >=) translate to the recommendation engine's\nsimplified AND filter — any other operator (contains, begins_with,\nends_with, in, not_in, exists, not_exists) is rejected with 400\nnaming the operator, before ranking runs.\n","properties":{"profile_id":{"type":"string","format":"uuid"},"strategy":{"type":"string","enum":["trending","recently_viewed","similar_to","affinity","blend"],"description":"similar_to requires seed_item; blend requires 1-4 blend parts (a part may itself be similar_to, in which case seed_item is still required)."},"count":{"type":"integer","minimum":0,"description":"Number of items to return. 0 or omitted defaults to 10; a value above the instance's recommend_max_count setting is clamped to it; a negative value is rejected with 400."},"seed_item":{"type":"string","description":"Required for strategy=similar_to (and for blend when one of its parts is similar_to); rejected otherwise. An unknown seed item is not an error — it yields an empty result."},"filter":{"type":"array","maxItems":32,"items":{"$ref":"#/components/schemas/EventAttrRule"},"description":"Caller filter, ANDed with the catalogue's own business_rules.require/exclude and pushed down to the dataset query."},"blend":{"type":"array","minItems":1,"maxItems":4,"items":{"$ref":"#/components/schemas/RecommendBlendPart"},"description":"Required (and only valid) when strategy=blend."},"exclude_purchased":{"type":"boolean","description":"Drop items the profile purchased within the catalogue's purchase-interaction lookback window (365 days)."},"fields":{"type":"array","maxItems":32,"items":{"type":"string"},"description":"Response field projection. Empty = every declared role field (title/image/url/price/availability/affinity)."}}},"RecommendBlendPart":{"type":"object","required":["strategy","weight"],"properties":{"strategy":{"type":"string","enum":["trending","recently_viewed","similar_to","affinity"],"description":"Any non-blend strategy."},"weight":{"type":"number","exclusiveMinimum":0},"max":{"type":"integer","minimum":1,"description":"Optional per-part candidate cap."}}},"RecommendedItemObject":{"type":"object","description":"One ranked, rule-applied, field-projected recommendation. `reason`\nnames the pipeline stage that produced the item: trending /\nrecently_viewed / similar_to / affinity / blend, or \"pinned\" for a\nmerchandiser pin. `score` can legitimately be 0 for a pinned item\nthat was never independently scored — never treat score 0 as\n\"absent\" or filter it out.\n","properties":{"item_key":{"type":"string"},"fields":{"type":"object","description":"Only the requested/role fields actually present on the record — never synthesized."},"score":{"type":"number"},"reason":{"type":"string","description":"English phrase, unchanged for compatibility. Use reason_code to translate."},"reason_code":{"type":"string","enum":["trending","recently_viewed","co_occurrence","affinity","pinned"],"description":"Stable machine form of reason. A blend reports its winning part's code. Omitted only on a result cached before this field existed (cache TTL is seconds)."},"reason_params":{"type":"object","additionalProperties":{"type":"string"},"description":"What the phrase interpolates: co_occurrence {seed: item key}, affinity {field, value} (the same values reason already shows). Omitted for trending, recently_viewed, pinned."},"pinned":{"type":"boolean","description":"Omitted (false) on an ordinary ranked item."}}},"RecommendResponse":{"type":"object","properties":{"catalog":{"type":"string"},"strategy":{"type":"string"},"items":{"type":"array","items":{"$ref":"#/components/schemas/RecommendedItemObject"},"description":"Always present as an array — no matching candidates is a 200 with an empty items array, never an error."}}},"ContentItemRequest":{"type":"object","required":["name"],"description":"The WRITABLE subset of a content item. It deliberately carries no\nstatus and no renditions: publication moves through the workflow\nendpoints and renditions through the upload endpoint, so a PUT can\nnever publish an item or rewrite its variants.\n","properties":{"name":{"type":"string","maxLength":200},"description":{"type":"string","maxLength":2000},"folder":{"type":"string","description":"Materialized path, e.g. `campaigns/summer-2026`. Normalised server-side."},"tags":{"type":"array","items":{"type":"string"},"description":"Trimmed, de-duplicated case-insensitively, capped."},"pii_level":{"type":"integer","minimum":0,"maximum":255,"description":"Gates downloads against the caller's `pii_access_level`. Mutually exclusive with `public`. Bounded at 255, the platform's PII-level ceiling — a higher value would be reachable by nobody."},"public":{"type":"boolean","description":"Ask for a public URL. Rejected with 400 when `pii_level` > 0 — PII-levelled content is never served anonymously."},"public_filename":{"type":"string","maxLength":128,"description":"Optional exposed-filename template for public links: literal `[A-Za-z0-9._-]` text plus `{yyyy}` `{yy}` `{mm}` `{dd}`. 400 on any other character or placeholder. Empty defaults to the rendition's upload filename."}}},"ContentVariantObject":{"type":"object","description":"One named rendition. The storage key is deliberately not exposed; ask for a download URL instead.","properties":{"name":{"type":"string"},"filename":{"type":"string","description":"The uploaders original filename, returned as the downloads Content-Disposition."},"content_type":{"type":"string"},"size_bytes":{"type":"integer","format":"int64"},"sha256":{"type":"string","description":"Hex digest of the bytes; doubles as the public ETag."},"uploaded_by":{"type":"string"},"generated":{"type":"object","description":"AI provenance ({prompt, provider, model, generation_id, generated_by, generated_at}), absent on ordinary human uploads. A human re-upload of the rendition clears it."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"ContentItemResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string"},"folder":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["draft","pending_approval","published","rejected","archived"],"description":"State of the CURRENT draft. It does NOT decide what is served publicly — the pins below do."},"pii_level":{"type":"integer"},"public":{"type":"boolean"},"public_token":{"type":"string","description":"The unguessable path credential the public URL is built from, stable for the item's whole life. Returned because it is not confidential — it appears in every published URL — and a console cannot show an author their link before the public base URL is configured."},"public_url":{"type":"string","description":"Where Optima Edge serves this item — the opaque sealed streaming form `/edge/v1/files/{sealed}/{filename}` (nothing internal appears in it, and each read mints a fresh but equally valid token). Present only when the item is actually servable AND the instance's public content URL and link signing are configured — a URL that would 404 is omitted rather than guessed."},"public_filename":{"type":"string","description":"The exposed-filename template for public links: literal `[A-Za-z0-9._-]` text plus the date placeholders `{yyyy}` `{yy}` `{mm}` `{dd}`, resolved when a link is minted, with the extension enforced from the stored content type. Empty defaults to the rendition's upload filename."},"published_revision":{"type":"integer","description":"The revision pinned for public serving. Null when nothing is on the air."},"published_variants":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/ContentVariantObject"},"description":"The rendition map FROZEN at approval — what the public URL actually serves, which during a draft edit may differ from `variants`."},"published_at":{"type":"string","format":"date-time"},"submitted_by":{"type":"string"},"submitted_at":{"type":"string","format":"date-time"},"decided_by":{"type":"string"},"decided_at":{"type":"string","format":"date-time"},"decision_reason":{"type":"string","description":"The reviewer's rejection message, shown to the author."},"self_approved":{"type":"boolean","description":"The recorded decision was made by the identity that requested it. Root and admin are permitted to do this, so the flag makes it visible rather than preventing it; the authoritative trace is the revision ledger, which records the actor of the request_publish and approve entries permanently."},"variants":{"type":"array","items":{"$ref":"#/components/schemas/ContentVariantObject"},"description":"The items CURRENT renditions, `original` first."},"created_by":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"ContentFieldChange":{"type":"object","description":"One top-level field difference between the snapshots either side of a change. An absent side means the field did not exist then.","properties":{"field":{"type":"string"},"from":{},"to":{}}},"ContentRevisionResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"item_id":{"type":"string","format":"uuid"},"item_name":{"type":"string","description":"The items name AT THE TIME of the change, so history stays readable after a rename or a delete."},"revision":{"type":"integer","description":"Monotonic per item, starting at 1."},"action":{"type":"string","enum":["create","update","upload_variant","delete_variant","rename_variant","request_publish","approve","reject","unpublish","archive","unarchive","restore","delete"]},"snapshot":{"type":"object","description":"The full post-change item. Omitted from list responses; present on a single-revision read, which is what a restore replays."},"diff":{"type":"array","items":{"$ref":"#/components/schemas/ContentFieldChange"}},"restored_from":{"type":"integer","description":"Set on `restore` — the revision whose snapshot was replayed."},"actor":{"type":"string"},"actor_type":{"type":"string","enum":["","user","application","root"]},"created_at":{"type":"string","format":"date-time"}}},"ContentFacets":{"type":"object","properties":{"folders":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}}}},"ContentGenerateCapabilities":{"type":"object","properties":{"available":{"type":"boolean","description":"Whether a generate call can work right now."},"reason":{"type":"string","description":"The refusal sentence when available is false — identical wording to the generate endpoint's."},"max_variants":{"type":"integer","description":"Per-request variant ceiling (llm_image_max_variants)."},"daily_limit":{"type":"integer","description":"Per-tenant daily image cap; 0 = uncapped."},"remaining_quota":{"type":"integer","description":"Images left today; -1 = uncapped."}}},"ContentGenerationSaveRequest":{"type":"object","required":["name"],"properties":{"index":{"type":"integer","minimum":0,"description":"Which image of the generation to save (0-based)."},"name":{"type":"string","description":"The new content item's name."},"folder":{"type":"string","description":"Target folder, normalised like every other content folder."},"tags":{"type":"array","items":{"type":"string"}}}},"ContentGenerateRequest":{"type":"object","required":["prompt"],"properties":{"prompt":{"type":"string","maxLength":4000,"description":"The marketer's prompt, sent to the provider verbatim. Never contains profile data."},"n":{"type":"integer","minimum":0,"description":"Wanted variant count. 0 means 1; the server clamps to llm_image_max_variants and to the remaining daily quota."}}},"ContentGeneratedImage":{"type":"object","properties":{"index":{"type":"integer","description":"Position within the generation; identifies the image to the promote call."},"mime":{"type":"string"},"size_bytes":{"type":"integer","format":"int64"},"data_uri":{"type":"string","description":"Inline base64 preview (data:<mime>;base64,...). The bytes are also staged server-side; saving promotes the staged copy, nothing round-trips back."}}},"ContentGenerationResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"prompt":{"type":"string"},"provider":{"type":"string"},"model":{"type":"string"},"requested":{"type":"integer"},"produced":{"type":"integer","description":"May be lower than requested on a partial provider failure; the successes are kept."},"images":{"type":"array","items":{"$ref":"#/components/schemas/ContentGeneratedImage"}},"remaining_quota":{"type":"integer","description":"Today's remaining per-tenant image budget after this request; -1 when uncapped."},"created_at":{"type":"string","format":"date-time"}}},"EdgeContentItemResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slot":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","enum":["draft","published","archived"]},"content_type":{"type":"string"},"payload_format":{"type":"string","enum":["structured","unstructured"]},"payload":{"type":"object"},"body":{"type":"string"},"personalized":{"type":"boolean"},"targeting":{"type":"object"},"priority":{"type":"integer"},"starts_at":{"type":"string","format":"date-time","nullable":true},"ends_at":{"type":"string","format":"date-time","nullable":true},"published_at":{"type":"string","format":"date-time","nullable":true,"description":"Kept as history after unpublish."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"AccountObject":{"type":"object","description":"A customer account — the billing entity one or more tenants (environments) hang off.","properties":{"id":{"type":"string"},"name":{"type":"string"},"plan":{"type":"string"},"billing_ref":{"type":"string"},"tenants":{"type":"integer","description":"The account's environment count. Present on list responses only."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","name","plan"]},"AccountMemberObject":{"type":"object","description":"One user's aggregated role set in one account.","properties":{"email":{"type":"string","format":"email"},"account_id":{"type":"string"},"roles":{"type":"array","items":{"type":"string"}}},"required":["email","account_id","roles"]},"TenantObject":{"type":"object","description":"A tenant row. `ch_database` is deliberately NOT exposed — the tenant's data-store database name is an internal routing detail.\n","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","enum":["provisioning","active","suspended"]},"account_id":{"type":"string","description":"Empty on a pre-accounts row the backfill did not reach."},"account_name":{"type":"string","description":"Joined in only by listings that group tenants by account."},"environment":{"type":"string","enum":["production","sandbox","development"],"description":"A LABEL — it drives provisioning defaults and presentation, never scoping. The behavioural half is `settings.outbound_mode`.\n"},"settings":{"type":"object","description":"Per-tenant setting overrides."},"quotas":{"$ref":"#/components/schemas/TenantQuotas"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","name","status"]},"TenantQuotas":{"type":"object","description":"Per-tenant operational ceilings. An ABSENT key means unlimited — the same thing a stored zero means to the enforcement — so an unconstrained tenant answers `{}` rather than a wall of zeros.\n","properties":{"max_profiles":{"type":"integer","format":"int64"},"max_events_per_day":{"type":"integer","format":"int64"},"max_connectors":{"type":"integer"},"rpm":{"type":"integer"},"rpm_service":{"type":"integer"}}},"TenantQuotaUsage":{"type":"object","description":"The coarse 15-minute rollup the platform writes, and the one the quota enforcement actually checks against. A different measurement from the metered daily rows, and it lags by design.\n","properties":{"profiles":{"type":"integer","format":"int64"},"events_today":{"type":"integer","format":"int64"},"connectors":{"type":"integer"},"computed_at":{"type":"string","format":"date-time"}}},"TenantMemberInfo":{"type":"object","description":"One row of a tenant's team listing: the membership (explicit tenant_members rows, or account-inherited where no explicit row exists) joined with the user account, when one exists. An invited-but-never-registered email has `user_status: \"\"`.\n","properties":{"email":{"type":"string","format":"email"},"roles":{"type":"array","items":{"type":"string"}},"role_source":{"type":"string","enum":["tenant","account"]},"display_name":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"user_status":{"type":"string","description":"`\"\"` when the email has no user account yet."}},"required":["email","roles","role_source"]},"TenantInviteObject":{"type":"object","description":"One pending tenant membership invitation. The raw token / hash is never returned.","properties":{"id":{"type":"string","format":"uuid"},"email":{"type":"string","format":"email"},"tenant_id":{"type":"string"},"roles":{"type":"array","items":{"type":"string"}},"expires_at":{"type":"string","format":"date-time"},"invited_by":{"type":"string"},"created_at":{"type":"string","format":"date-time"}},"required":["id","email","tenant_id","roles","expires_at"]},"UsageDayTotals":{"type":"object","description":"One metered day, summed across the tenants that count.","properties":{"day":{"type":"string","format":"date"},"billable_profiles":{"type":"integer","format":"int64"},"profiles_total":{"type":"integer","format":"int64"},"profiles_anonymous":{"type":"integer","format":"int64"},"customers_observed":{"type":"integer","format":"int64"},"events_stored":{"type":"integer","format":"int64"},"events_ingested":{"type":"integer","format":"int64"},"connect_events":{"type":"integer","format":"int64"},"operations":{"type":"integer","format":"int64"},"operations_breakdown":{"type":"object","additionalProperties":{"type":"integer","format":"int64"}}},"required":["day"]},"UsageTotals":{"type":"object","description":"One window folded up: the PEAK for stocks (billable profiles) and the SUM for flows (events, operations).\n","properties":{"billable_profiles":{"type":"integer","format":"int64"},"profiles_total":{"type":"integer","format":"int64"},"profiles_anonymous":{"type":"integer","format":"int64"},"customers_observed":{"type":"integer","format":"int64"},"events_stored":{"type":"integer","format":"int64"},"events_ingested":{"type":"integer","format":"int64"},"connect_events":{"type":"integer","format":"int64"},"operations":{"type":"integer","format":"int64"},"operations_breakdown":{"type":"object","additionalProperties":{"type":"integer","format":"int64"}},"days_with_data":{"type":"integer","description":"How many days of the window produced a row — the divisor for projections, and what makes a gap visible instead of silently deflating an average.\n"}}},"UsageLimits":{"type":"object","description":"The derived band, frozen at contract time. Zero means \"unmetered for this quantity\", which is how a licence written before a quantity existed keeps behaving.\n","properties":{"billable_profiles":{"type":"integer","format":"int64"},"stored_events":{"type":"integer","format":"int64"},"operations":{"type":"integer","format":"int64"},"connect_events":{"type":"integer","format":"int64"}}},"UsageConstants":{"type":"object","description":"The per-customer constants a band is derived from.","properties":{"profiles_per_customer":{"type":"number"},"events_per_customer_month":{"type":"number"},"retention_months":{"type":"integer"},"operations_per_customer_month":{"type":"number"},"connect_events_per_customer_month":{"type":"number"}}},"AccountLicence":{"type":"object","description":"One account's contract in structured form. A MISSING licence means every package is licensed and nothing is metered against a band. `notified_thresholds` is stripped from every read.\n","properties":{"account_id":{"type":"string"},"packages":{"type":"array","items":{"type":"string"}},"excluded_features":{"type":"array","items":{"type":"string"},"description":"Features carved out of the licensed packages (\"campaign without journeys\"). Never core keys. The resolved `features` is the packages' features minus these."},"billing_period":{"type":"string","enum":["monthly","annual"]},"contract_start":{"type":"string","format":"date","description":"Annual periods run from here, not from the calendar year."},"customer_count":{"type":"integer","format":"int64"},"constants":{"$ref":"#/components/schemas/UsageConstants"},"limits":{"$ref":"#/components/schemas/UsageLimits"},"billable_entity_types":{"type":"object","additionalProperties":{"type":"number"}},"primary_entity_type":{"type":"string"},"billable_identifier_keys":{"type":"array","items":{"type":"string"}},"active_window_days":{"type":"integer"},"ramp_until":{"type":"string","description":"A date, or empty. Overage is suppressed while in ramp."},"peak_guard_pct":{"type":"integer"},"max_tenants":{"type":"integer","description":"Hard ceiling on non-offboarded tenants this account may create. 0 = unset, resolves to the instance setting `account_max_tenants` (registry default 3). Unlike the soft usage licence this is a HARD 403 above the ceiling — a tenant is a provisioned set of databases, not metered data.\n"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["account_id","packages","billing_period"]},"LicencePackage":{"type":"object","description":"One entry of the package catalogue the licence editor renders from.","properties":{"package":{"type":"string"},"features":{"type":"array","items":{"type":"string"}},"requires":{"type":"array","items":{"type":"string"}},"mandatory":{"type":"boolean","description":"True for `core`, which is granted whatever the row says — the editor renders it as fixed rather than as an unchecked box that does nothing.\n"}}},"MetricAssessment":{"type":"object","description":"One metered quantity's standing in a period.","properties":{"metric":{"type":"string"},"used":{"type":"integer","format":"int64"},"limit":{"type":"integer","format":"int64","description":"The MONTHLY band. On an annual contract the comparison is month-by-month, which is why `ratio` is not simply used/limit there.\n"},"ratio":{"type":"number","description":"Fraction of band consumed (0 when unmetered). On an annual contract this is the averaged — or, on a peak-guard breach, the worst — monthly ratio.\n"},"projected":{"type":"integer","format":"int64"},"projected_ratio":{"type":"number","description":"`projected` over the band it is billed against. On an annual contract a flow metric's band is `limit` times the months in the period; billable profiles keeps the monthly band.\n"},"overage":{"type":"integer","format":"int64","description":"Billable excess in metric units; always zero during ramp."},"over":{"type":"boolean"}}},"MonthAssessment":{"type":"object","description":"One month's standing inside an annual period.","properties":{"month":{"type":"string"},"totals":{"$ref":"#/components/schemas/UsageTotals"},"ratios":{"type":"object","additionalProperties":{"type":"number"}},"complete":{"type":"boolean","description":"False for the month the period is currently inside — an incomplete month must not drag the running average down.\n"}}},"UsageAssessment":{"type":"object","description":"A period's full standing: what was used, against what band, where it is heading, and what (if anything) is billable on top.\n","properties":{"period_start":{"type":"string","format":"date"},"period_end":{"type":"string","format":"date"},"billing_period":{"type":"string","enum":["monthly","annual"]},"totals":{"$ref":"#/components/schemas/UsageTotals"},"limits":{"$ref":"#/components/schemas/UsageLimits"},"metrics":{"type":"array","items":{"$ref":"#/components/schemas/MetricAssessment"}},"months":{"type":"array","description":"Present on annual periods only.","items":{"$ref":"#/components/schemas/MonthAssessment"}},"averaged":{"type":"boolean","description":"An annual contract's overage was computed on the running monthly average rather than month by month.\n"},"peak_guard_breached":{"type":"boolean","description":"Some month exceeded peak_guard_pct of band, which WAIVES the averaging — it protects against a seasonal client running 3x for a quarter and averaging to par.\n"},"in_ramp":{"type":"boolean","description":"Suppresses every overage: the first months are metered but overage-free, and the band is set from observed data at the end.\n"},"customer_count":{"type":"integer","format":"int64","description":"The DECLARED number the band was sized from."},"profiles_per_customer":{"type":"number"},"contracted_profiles_per_customer":{"type":"number"},"elapsed_days":{"type":"integer"},"total_days":{"type":"integer"}}},"TenantUsageResponse":{"type":"object","description":"One tenant's metered usage over the requested window.","properties":{"tenant_id":{"type":"string"},"account_id":{"type":"string"},"environment":{"type":"string","enum":["production","sandbox","development"]},"counted":{"type":"boolean","description":"Whether this tenant's rows are billed. A sandbox says so on its own dashboard — the client should never have to infer from an account view that their test workspace is free.\n"},"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"},"days":{"type":"array","items":{"$ref":"#/components/schemas/UsageDayTotals"}},"totals":{"$ref":"#/components/schemas/UsageTotals"},"features":{"type":"array","description":"The resolved entitlement, so the console can gate navigation from one call.","items":{"type":"string"}},"quotas":{"$ref":"#/components/schemas/TenantQuotas"},"quota_usage":{"$ref":"#/components/schemas/TenantQuotaUsage"}}},"AccountUsageResponse":{"type":"object","description":"One account's usage. The window series (`days`) is what the trend chart draws; `current_period` is what the invoice follows — different windows on purpose, and labelled as such.\n","properties":{"account":{"$ref":"#/components/schemas/AccountObject"},"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"},"tenants":{"type":"array","items":{"$ref":"#/components/schemas/TenantObject"}},"licensed":{"type":"boolean"},"licence":{"$ref":"#/components/schemas/AccountLicence"},"current_period":{"$ref":"#/components/schemas/UsageAssessment"},"band":{"type":"string","description":"The band label derived from the licensed billable-profile limit."},"days":{"type":"array","items":{"$ref":"#/components/schemas/UsageDayTotals"}},"by_tenant":{"type":"array","description":"The period's usage split per contributing tenant.","items":{"type":"object","properties":{"tenant_id":{"type":"string"},"totals":{"$ref":"#/components/schemas/UsageTotals"}}}},"closed_periods":{"type":"array","description":"Previously closed billing periods, as stored assessments.","items":{"$ref":"#/components/schemas/UsageAssessment"}},"rollup":{"allOf":[{"$ref":"#/components/schemas/TenantQuotaUsage"}],"description":"The pre-licensing coarse `tenant_usage` aggregate, kept for compatibility. `licence`, `current_period` and `band` are present only when a licence is stored.\n"}}},"AccountLicenceResponse":{"type":"object","description":"The stored contract plus the catalogue the editor renders from.","properties":{"account_id":{"type":"string"},"licence":{"$ref":"#/components/schemas/AccountLicence"},"features":{"type":"array","description":"The RESOLVED feature set — every feature when no licence is stored. Computing it client-side would be a second implementation of the package map.\n","items":{"type":"string"}},"catalog":{"type":"array","items":{"$ref":"#/components/schemas/LicencePackage"}},"derived_limits":{"allOf":[{"$ref":"#/components/schemas/UsageLimits"}],"description":"Present only when a licence is stored."}},"required":["account_id","features","catalog"]},"DeletionRequestObject":{"type":"object","description":"A bulk delete parked for the cancellation window. Held in the database and real time, so it survives the browser being closed.\n","properties":{"id":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["profiles","events","dataset_records"]},"entity_type":{"type":"string"},"dataset_name":{"type":"string"},"matched_count":{"type":"integer"},"status":{"type":"string","enum":["pending","in_progress","completed","failed","cancelled"]},"scheduled_at":{"type":"string","format":"date-time"},"requested_by":{"type":"string"},"requested_at":{"type":"string","format":"date-time"},"started_at":{"type":"string","format":"date-time","nullable":true,"description":"Set once the job first claimed the request. A `pending` request with started_at set was re-scheduled after a transient failure, may be partly deleted, and cannot be cancelled."},"finished_at":{"type":"string","format":"date-time","nullable":true},"cancelled_at":{"type":"string","format":"date-time","nullable":true},"deleted_count":{"type":"integer"},"error":{"type":"string"}},"required":["id","kind","matched_count","status","scheduled_at","requested_at","deleted_count"]},"TenantSwitcherEntry":{"type":"object","description":"One tenant the session may switch into.","properties":{"tenant_id":{"type":"string"},"name":{"type":"string"},"account_id":{"type":"string"},"account_name":{"type":"string"},"environment":{"type":"string","enum":["production","sandbox","development"]},"role_source":{"type":"string","description":"Where the roles came from — a membership row, or an account-level grant."},"roles":{"type":"array","items":{"type":"string"}},"account_roles":{"type":"array","items":{"type":"string"},"description":"The caller's `account_members` roles for THIS row's account (e.g. `[\"account_admin\"]`), read INDEPENDENT of `roles`/ `role_source`'s wholesale tenant-wins-over-account precedence. Display/persona metadata only — never consulted by enforcement. An account_admin who also holds an explicit tenant membership row in every tenant of their account never carries `account_admin` in `roles` on any row (explicit rows win wholesale), which is exactly why a client detecting the account_admin persona must read this field, not `roles`. Absent when the row carries no account at all.\n"},"active":{"type":"boolean"},"outbound_mode":{"type":"string","enum":["live","sink","off"],"description":"The tenant's effective outbound mode, so the switcher can badge a tenant that does not deliver to the outside world.\n"}},"required":["tenant_id","name","roles","active"]},"DeliveryChannelSummary":{"type":"object","description":"One deliverable channel — native, or declared by this tenant.\n","properties":{"name":{"type":"string"},"label":{"type":"string"},"contact_kind":{"type":"string","enum":["email","phone","token","none"]},"template_variant":{"type":"string","description":"Which message-template variant carries this channel's copy. A native channel is its own variant; a declared one borrows a built-in schema, and Campaign needs to know which so its activation and send paths look the copy up in the right place.\n"},"custom":{"type":"boolean"},"is_active":{"type":"boolean"}},"required":["name","label","contact_kind","template_variant","custom","is_active"]},"LinkTopologyEntry":{"type":"object","description":"One (parent entity, child entity) pair that actually has profile_links rows, with the link count — a hint for which related-entity hops are meaningful when building cross-entity filters.\n","properties":{"parent_entity":{"type":"string"},"child_entity":{"type":"string"},"links":{"type":"integer","format":"int64"}},"required":["parent_entity","child_entity","links"]},"LinkRelationTypeEntry":{"type":"object","description":"One `profile_links.relation_type` value actually present in the data, with the number of edges carrying it. The column is free-form, so this aggregate is the only catalogue of relation types there is; authoring UIs offer it as the vocabulary (e.g. hierarchy-scoped fatigue policies). At most 200 entries, most-used first.\n","properties":{"relation_type":{"type":"string"},"links":{"type":"integer","format":"int64"}},"required":["relation_type","links"]},"DeletionRequestList":{"type":"object","description":"The scheduled/finished bulk deletes, newest first.","properties":{"requests":{"type":"array","items":{"$ref":"#/components/schemas/DeletionRequestObject"}},"total":{"type":"integer"}},"required":["requests","total"]},"AccountDetailResponse":{"type":"object","description":"One account with its environments and members.","properties":{"account":{"$ref":"#/components/schemas/AccountObject"},"tenants":{"type":"array","items":{"$ref":"#/components/schemas/TenantObject"}},"members":{"type":"array","items":{"$ref":"#/components/schemas/AccountMemberObject"}}},"required":["account","tenants","members"]},"ScheduledDeleteResponse":{"type":"object","description":"What the console offers to cancel, reported at scheduling time.","properties":{"request_id":{"type":"string","format":"uuid"},"scheduled_at":{"type":"string","format":"date-time"},"matched":{"type":"integer"},"status":{"type":"string"}},"required":["request_id","scheduled_at","matched","status"]},"BulkDeleteResult":{"type":"object","description":"The outcome of an immediate bulk delete. A dry run answers `matched` and `dry_run: true` instead of `deleted`.\n","properties":{"deleted":{"type":"integer"},"matched":{"type":"integer"},"dry_run":{"type":"boolean"}}},"CohortMembersResponse":{"type":"object","description":"A cohort's current members. For a MATERIALIZED cohort, membership is as-of `refreshed_at`, not as-of this request — that is part of the contract, not an implementation detail.\n","properties":{"cohort":{"type":"string"},"entity_type":{"type":"string"},"profile_ids":{"type":"array","items":{"type":"string","format":"uuid"}},"materialized":{"type":"boolean"},"refreshed_at":{"type":"string","format":"date-time","description":"Present only for a materialized cohort that has been refreshed."}},"required":["cohort","entity_type","profile_ids","materialized"]},"ActiveTenantResponse":{"type":"object","description":"The session's newly active tenant and the caller's roles in it.","properties":{"tenant_id":{"type":"string"},"roles":{"type":"array","items":{"type":"string"}}},"required":["tenant_id","roles"]},"AcceptedInviteResponse":{"type":"object","description":"The accepted invite's resulting membership.","properties":{"email":{"type":"string","format":"email"},"tenant_id":{"type":"string"},"roles":{"type":"array","items":{"type":"string"}}},"required":["email","tenant_id","roles"]},"PeekInviteResponse":{"type":"object","description":"What a valid, unconsumed invite token is FOR. `has_account` tells the console invite page which branch to render: an existing email gets a one-click accept, an unknown one gets an account-creation form.\n","properties":{"email":{"type":"string","format":"email"},"tenant_id":{"type":"string"},"tenant_name":{"type":"string"},"roles":{"type":"array","items":{"type":"string"}},"has_account":{"type":"boolean"}},"required":["email","tenant_id","tenant_name","roles","has_account"]},"NotificationTemplateFieldSpec":{"type":"object","description":"The fields one notification template's data payload carries.","properties":{"fields":{"type":"array","description":"Always present in the published data.","items":{"type":"string"}},"optional":{"type":"array","description":"Published only in some circumstances; templates should guard these with `{{if .key}}`.\n","items":{"type":"string"}},"sample":{"type":"object","description":"An example data payload for the preview."}},"required":["fields","sample"]},"NotificationTemplateFieldsResponse":{"type":"object","description":"The registry of notification data shapes — pinned to the publish sites by tests, and the only schema notification data has anywhere.\n","properties":{"injected":{"type":"array","description":"Keys available in EVERY template regardless of data.","items":{"type":"string"},"example":["api_base_url","template","data"]},"templates":{"type":"object","description":"Template name / subscription event type to its field spec.","additionalProperties":{"$ref":"#/components/schemas/NotificationTemplateFieldSpec"}}},"required":["injected","templates"]},"NotificationTemplatePartResult":{"type":"object","description":"The preview outcome for one template part.","properties":{"ok":{"type":"boolean"},"rendered":{"type":"string"},"error":{"type":"object","properties":{"message":{"type":"string"},"line":{"type":"integer","description":"0 or absent means the error carried no position."}}}},"required":["ok"]},"NotificationTemplatePreviewResponse":{"type":"object","properties":{"subject":{"$ref":"#/components/schemas/NotificationTemplatePartResult"},"body":{"$ref":"#/components/schemas/NotificationTemplatePartResult"},"body_html":{"allOf":[{"$ref":"#/components/schemas/NotificationTemplatePartResult"}],"description":"Present only when the request carried a non-empty body_html_tmpl.\n"},"warnings":{"type":"array","description":"Currently only `subject_crlf`: the rendered subject contains CR/LF, which the notification service refuses at send time as a header-injection attempt.\n","items":{"type":"string"}}},"required":["subject","body"]},"AgentSpec":{"type":"object","description":"The versioned definition of an agent. Validated on every write: tool names must be in the catalogue, attribute and purpose names must exist, and `purpose` is required when `actions` declares events or attributes.","required":["prompt","triggers","tools","actions"],"properties":{"prompt":{"type":"string"},"triggers":{"type":"array","items":{"type":"object","required":["kind"],"properties":{"kind":{"type":"string","enum":["event","schedule","continuous"],"description":"A `continuous` trigger stands alone (no other trigger) and needs `source`, `item_view` and `cron`; `actions.email` must equal `summary_email` and the spec must declare at least one attribute or event."},"event_type":{"type":"string","description":"Event triggers: the notification event type that starts a run. `account.*` is refused (422): account events go only to the account's own subscribers and never reach agents."},"filters":{"type":"object","additionalProperties":true,"description":"Notification filter-match syntax."},"delay":{"type":"string","description":"Go duration, at most 30 days. Exclusive with `delay_param`."},"delay_param":{"type":"string","description":"Key of a `duration` parameter. Exclusive with `delay`."},"stage":{"type":"string"},"cron":{"type":"string","description":"Five-field cron expression (schedule and continuous triggers). Exclusive with `cron_param`."},"cron_param":{"type":"string","description":"Key of a `cron` parameter holding the schedule. Exclusive with `cron`."},"filters_param":{"type":"string","description":"Key of a list parameter (`campaigns`, `metrics`, `forms`, `enum_list`, `string_list` or `users`) that sets `filter_field`. The list narrows the event trigger to events whose `filter_field` is in the list; it is resolved each time the triggers are loaded and each run, not only at instance creation. An empty list adds no filter."},"source":{"type":"object","description":"Continuous triggers only. What the sweep covers.","required":["type"],"properties":{"type":{"type":"string","enum":["profiles","events"]},"segment_id":{"type":"string","format":"uuid","description":"Profiles source: the segment whose members are swept."},"event_type":{"type":"string","description":"Events source: the event type swept; must exist in the event-type catalogue."}}},"refresh_after_days":{"type":"integer","minimum":1,"maximum":3650,"description":"Continuous, profiles source only: reprocess an item after this many days."},"item_view":{"type":"object","description":"Continuous triggers only. What the agent sees about each item; at most 8 KiB per item (the estimate 64 + 128 x attributes + 256 x last_n x event types is refused above that).","properties":{"attributes":{"type":"array","maxItems":40,"items":{"type":"string"}},"events":{"type":"object","required":["types","last_n","within_days"],"properties":{"types":{"type":"array","items":{"type":"string"}},"last_n":{"type":"integer","minimum":1,"maximum":20},"within_days":{"type":"integer","minimum":1,"maximum":365}}}}},"items_per_call":{"type":"integer","minimum":0,"maximum":50,"description":"Continuous: items per model call; 0 or omitted means 20."},"summary_email":{"type":"boolean","description":"Continuous: email the owner a summary after each sweep; must equal `actions.email`."}}}},"tools":{"type":"array","items":{"type":"string"},"description":"Names from GET /agents/tools. The caller must hold every tool."},"optional_tools":{"type":"array","items":{"type":"string"},"description":"Tools from `tools` that the agent can do without. The author still needs every listed tool, optional ones included; only the licence features of optional tools are skipped. The licence features of an optional tool do not hide a built-in definition or block creating an instance; a run simply lacks the tool when the tenant's licence does not include it. Each entry must also be listed in `tools` and appear once."},"actions":{"type":"object","required":["email"],"properties":{"email":{"type":"boolean"},"events":{"type":"array","items":{"type":"object","required":["type"],"properties":{"type":{"type":"string"},"properties":{"type":"object","additionalProperties":{"type":"string","enum":["string","number","bool"]}},"enums":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Property name to the values the agent may write."},"enum_params":{"type":"object","additionalProperties":{"type":"string"},"description":"Property name to the key of an `enum_list` or `string_list` parameter whose value replaces `enums` for that property at instance creation."}}}},"attributes":{"type":"array","items":{"type":"object","required":["key"],"properties":{"key":{"type":"string"},"enum":{"type":"array","items":{"type":"string"}}}}}}},"purpose":{"type":"string","description":"Processing purpose; required when `actions` declares events or attributes. Exclusive with `purpose_param`."},"purpose_param":{"type":"string","description":"Key of a `string` parameter holding the purpose. The value is checked against the tenant's active purposes when an instance is created (422 `unknown purpose`). Exclusive with `purpose`."},"grounded_numbers":{"type":"boolean","description":"When true, the subject and body of an email action are checked: each number of two or more digits must appear in a tool result of the run, its resolved parameters, its trigger data or the run time, or be a ratio or difference of two figures that belong together: sibling number fields of one JSON object (a ratio only as a part of a whole, at most 1, which covers percentages; a difference times 100 also grounds a percentage-point change), or, for differences only, the same field in consecutive elements of one array. Fields of one parameters or trigger-data object pair with each other; nothing pairs across results or with tool results. Figures with a k, K, M or bn suffix are scaled (\"47k\") and checked at the precision written. One-digit numbers, other digit runs glued to letters (\"BF24\", \"33x\") and scale words (\"1.5 million\") are not checked. A rejected email goes back to the model for repair; when repairs run out on a grounding miss the run fails with `ungrounded_numbers`. This guards against invented figures; it does not prove a figure correct."},"target_trigger_profile":{"type":"boolean","description":"When true, event and attribute actions may target only the profile of the triggering event."},"required_tools":{"type":"array","items":{"type":"string"},"description":"Tools (each also in `tools`, unique, not in `optional_tools`; not allowed with a continuous trigger, 422) the run cannot do without. A run whose offered tools (after the owner-route and licence narrowing) lack one fails before any model call with error `required_tool_unavailable`. A final step that proposes actions is refused, and the run fails with `required_tool_failed`, unless every required tool returned successfully at least once during the run (a failed call or no call both refuse); nothing is performed. A final with no actions is unaffected."},"max_actions":{"type":"integer","minimum":0,"description":"Most actions a run may return in its final step; 0 or absent means unlimited. A final step with more actions is refused as a validation error before any action is performed (the model repairs it, then the run fails). A negative value, or a value above 0 with a continuous trigger, is refused with 422. An event action must also set every property that has an `enums` or `enum_params` entry."},"params":{"type":"array","items":{"type":"object","required":["key","type"],"properties":{"key":{"type":"string"},"type":{"type":"string","enum":["string","number","duration","users","segment","campaign","bool","string_list","cron","campaigns","metrics","forms","enum_list"]},"required":{"type":"boolean"},"default":{"description":"Default value; its JSON type follows `type`."},"filter_field":{"type":"string","description":"List parameters only (`campaigns`, `metrics`, `forms`, `enum_list`, `string_list`, `users`): the event-data field that a trigger's `filters_param` narrows on."},"options":{"type":"array","items":{"type":"string"},"description":"`enum_list` only: the allowed values; empty means a free list."}}}}}},"AgentEventTypeNotDeclared":{"type":"object","description":"The 422 answer of instance creation when an event type of the definition is not declared in the tenant's event schema, or lacks properties.","required":["status","message","data"],"properties":{"status":{"type":"string","example":"error"},"message":{"type":"string","example":"Declare the event type \"lead.qualified\" before creating this agent."},"data":{"type":"object","required":["code","event_type","missing_properties"],"properties":{"code":{"type":"string","enum":["event_type_not_declared"]},"event_type":{"type":"string"},"missing_properties":{"type":"array","items":{"type":"string"},"description":"Properties the schema lacks or declares at another type; empty when the whole event type is missing."}}}}},"AgentToolObject":{"type":"object","description":"One tool of the agent tool catalogue, as the calling principal sees it.","required":["name","description","features","available"],"properties":{"name":{"type":"string"},"description":{"type":"string"},"features":{"type":"array","items":{"type":"string"},"description":"Licence features the tool needs."},"available":{"type":"boolean"},"reason":{"type":"string","enum":["unlicensed","not_permitted"],"description":"Why the tool is unavailable; omitted when `available` is true."},"reason_detail":{"type":"string","description":"Free text for people: the missing licence feature, or the first denied `<METHOD> <path>`. Omitted when `available` is true."}}},"AgentDefinitionRequest":{"type":"object","required":["name","spec"],"properties":{"name":{"type":"string","maxLength":200},"spec":{"$ref":"#/components/schemas/AgentSpec"}}},"AgentDefinitionVersionSummary":{"type":"object","properties":{"version":{"type":"integer"},"created_by":{"type":"string"},"created_at":{"type":"string","format":"date-time"}}},"AgentDefinitionObject":{"type":"object","description":"A definition with its current version's spec.","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"kind":{"type":"string","enum":["custom","builtin"],"description":"`builtin` definitions ship with Optima (created by migrations, immutable through this API) and need the `agents_builtin` licence feature; `custom` ones need `agents_custom`. A built-in whose tools need a feature the account lacks (for example Campaign) is not listed, and answers 404."},"builtin_key":{"type":"string","nullable":true,"description":"Stable key of a built-in definition; null for custom ones."},"current_version":{"type":"integer"},"archived_at":{"type":"string","format":"date-time","nullable":true},"created_by":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"spec":{"$ref":"#/components/schemas/AgentSpec"},"versions":{"type":"array","description":"Every version, newest first. Present on GET /agents/definitions/{id} only.","items":{"$ref":"#/components/schemas/AgentDefinitionVersionSummary"}}}},"AgentDefinitionVersionObject":{"type":"object","description":"One immutable version of a definition.","properties":{"definition_id":{"type":"string","format":"uuid"},"version":{"type":"integer"},"spec":{"$ref":"#/components/schemas/AgentSpec"},"created_by":{"type":"string"},"created_at":{"type":"string","format":"date-time"}}},"AgentLimits":{"type":"object","description":"The effective per-run guard rails of an agent instance. Every key is always present. The stored overrides are `AgentLimitOverrides`; keys an instance does not override take the defaults below, so a changed default reaches every instance that did not override that key.","required":["max_turns","max_tool_calls","run_deadline_seconds","run_tool_result_bytes","tool_result_bytes","max_repairs","max_consecutive_failures"],"properties":{"max_turns":{"type":"integer","minimum":1,"maximum":64,"default":24,"description":"Model calls of one run. A run that finishes makes at most `max_turns` - 1 tool calls (the final answer needs a turn); a run that only calls tools makes `max_turns` calls and ends `guard_rail_turns`. Each turn resends the whole conversation, so the worst-case input tokens grow roughly with the square of the turns. Applies to event and schedule runs and to every chunk run of a sweep (only the first chunk may call tools; later chunks spend turns on repairs)."},"max_tool_calls":{"type":"integer","minimum":1,"maximum":60,"default":20,"description":"Tool invocations of one run (error `guard_rail_tool_calls`). A value at or above `max_turns` never trips first: `guard_rail_turns` does."},"run_deadline_seconds":{"type":"integer","minimum":60,"maximum":1800,"default":600,"description":"Wall time of one event or schedule run (error `deadline_exceeded`, counted as a failure). It does not apply to continuous sweeps or previews. A run that outlives it by 60 seconds is failed as lost by housekeeping, and the token reservations of a run that died are held until then. With 60 seconds a slow provider can end runs as `deadline_exceeded`; long deadlines occupy a shared run slot for that long."},"run_tool_result_bytes":{"type":"integer","minimum":16384,"maximum":524288,"default":196608,"description":"Tool-result bytes a run may accumulate. They are resent to the model on every later turn, so a larger budget raises the token reservation and cost of each call; at the runtime's estimate of 3 bytes per token 512 KiB is about 175k tokens per late turn, and above about 384 KiB a model with a 200k context window can fail with `llm_error` (counted as a failure). Applies per run and per sweep chunk run, and the first chunk's results are resent with every later chunk of the pass, so on continuous agents a larger value raises the cost of every model call in the sweep."},"tool_result_bytes":{"type":"integer","minimum":4096,"maximum":131072,"default":32768,"description":"Size of one tool result shown to the model; a longer result is cut, and a single record larger than the limit comes back empty with a note, so very small values (4 to 8 KiB) starve the model. Never above `run_tool_result_bytes`."},"max_repairs":{"type":"integer","minimum":0,"maximum":5,"default":2,"description":"Self-repair attempts after an invalid answer (0 turns repair off)."},"max_consecutive_failures":{"type":"integer","minimum":1,"maximum":20,"default":5,"description":"Failed runs in a row that stop the instance. With 1 a single transient error stops it."}}},"AgentRunLimits":{"type":"object","description":"The limits a run started with, as recorded. Meanings and ranges are those of `AgentLimits`. A key the recorded snapshot lacks (a limit added after the run) is null, never 0.","properties":{"max_turns":{"type":"integer","nullable":true,"minimum":1,"maximum":64},"max_tool_calls":{"type":"integer","nullable":true,"minimum":1,"maximum":60},"run_deadline_seconds":{"type":"integer","nullable":true,"minimum":60,"maximum":1800},"run_tool_result_bytes":{"type":"integer","nullable":true,"minimum":16384,"maximum":524288},"tool_result_bytes":{"type":"integer","nullable":true,"minimum":4096,"maximum":131072},"max_repairs":{"type":"integer","nullable":true,"minimum":0,"maximum":5},"max_consecutive_failures":{"type":"integer","nullable":true,"minimum":1,"maximum":20}}},"AgentLimitOverrides":{"type":"object","nullable":true,"additionalProperties":false,"description":"The limits an instance overrides, chosen at creation and fixed for its life. Every key is optional; a null value is ignored. Absent, null and `{}` keep every default. Ranges and meanings are those of `AgentLimits`. `tool_result_bytes` must not exceed `run_tool_result_bytes` (the default stands in for a key not overridden). Built-in agents are tuned for the defaults: lowering turns, tool calls, the deadline or the run bytes can make their runs fail.","properties":{"max_turns":{"type":"integer","nullable":true,"minimum":1,"maximum":64},"max_tool_calls":{"type":"integer","nullable":true,"minimum":1,"maximum":60},"run_deadline_seconds":{"type":"integer","nullable":true,"minimum":60,"maximum":1800},"run_tool_result_bytes":{"type":"integer","nullable":true,"minimum":16384,"maximum":524288},"tool_result_bytes":{"type":"integer","nullable":true,"minimum":4096,"maximum":131072},"max_repairs":{"type":"integer","nullable":true,"minimum":0,"maximum":5},"max_consecutive_failures":{"type":"integer","nullable":true,"minimum":1,"maximum":20}}},"AgentInstanceCreateRequest":{"type":"object","description":"Creates an instance in the `draft` state. The API takes tokens only; the console converts money to tokens with the provider's price.","required":["name","definition_id","definition_version","llm_provider_id","budget_lifetime_tokens","budget_period","budget_period_tokens"],"properties":{"name":{"type":"string","maxLength":200},"definition_id":{"type":"string","format":"uuid"},"definition_version":{"type":"integer","minimum":1},"llm_provider_id":{"type":"string","format":"uuid","description":"An active text LLM provider."},"params":{"type":"object","additionalProperties":true,"description":"Values for the definition's `params`; missing keys take their defaults."},"budget_lifetime_tokens":{"type":"integer","format":"int64","minimum":1},"budget_period":{"type":"string","enum":["hour","day","week","month"]},"budget_period_tokens":{"type":"integer","format":"int64","minimum":1,"description":"At most `budget_lifetime_tokens`."},"time_zone":{"type":"string","nullable":true,"description":"IANA name; defaults to the creating user's time zone, else UTC."},"limits":{"nullable":true,"description":"Run limit overrides, fixed for the instance's life (there is no edit endpoint). Absent, null and `{}` keep every default.","allOf":[{"$ref":"#/components/schemas/AgentLimitOverrides"}]}}},"AgentPriceObject":{"type":"object","description":"The provider's token price per million tokens.","properties":{"input_per_mtok":{"type":"number"},"output_per_mtok":{"type":"number"},"currency":{"type":"string"}}},"AgentBudgetObject":{"type":"object","description":"An instance's token budget and how much of it is used.","properties":{"lifetime_tokens":{"type":"integer","format":"int64"},"period":{"type":"string","enum":["hour","day","week","month"]},"period_tokens":{"type":"integer","format":"int64"},"lifetime_used":{"type":"integer","format":"int64"},"period_used":{"type":"integer","format":"int64"},"period_start":{"type":"string","format":"date-time","description":"Start of the current budget window in the instance's time zone."}}},"AgentInstanceObject":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"definition_id":{"type":"string","format":"uuid"},"definition_name":{"type":"string"},"definition_version":{"type":"integer"},"owner_user_id":{"type":"string","format":"uuid"},"owner_email":{"type":"string"},"llm_provider_id":{"type":"string","format":"uuid","nullable":true,"description":"Null once the provider has been deleted."},"llm_provider_name":{"type":"string","nullable":true,"description":"Null once the provider has been deleted."},"llm_model":{"type":"string","nullable":true,"description":"Null once the provider has been deleted."},"price":{"nullable":true,"description":"Null while the provider has no prices.","allOf":[{"$ref":"#/components/schemas/AgentPriceObject"}]},"params":{"type":"object","additionalProperties":true},"time_zone":{"type":"string"},"state":{"type":"string","enum":["draft","dry_run","live","stopped","cancelled"]},"state_reason":{"type":"string","nullable":true,"description":"Why the system stopped the instance, when it did."},"budget":{"$ref":"#/components/schemas/AgentBudgetObject"},"consecutive_failures":{"type":"integer"},"limits":{"type":"object","description":"The overrides chosen at creation (`{}` when none), as stored.","additionalProperties":{"type":"integer"}},"effective_limits":{"description":"The limits a new run of this instance starts with (defaults with the overrides applied).","allOf":[{"$ref":"#/components/schemas/AgentLimits"}]},"continuous":{"nullable":true,"description":"Sweep progress and cost preview; null unless the pinned definition has a continuous trigger.","allOf":[{"$ref":"#/components/schemas/AgentContinuousObject"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"AgentContinuousObject":{"type":"object","description":"A continuous instance's sweep state and last cost preview. The estimate is scope_size x last_preview_tokens_per_item tokens, priced at the dearer of the provider's input and output rates (an upper bound).","properties":{"phase":{"type":"string","enum":["initial","incremental"],"description":"initial while the first full pass runs, incremental afterwards."},"scope_size":{"type":"integer","format":"int64","nullable":true,"description":"Items in scope when last measured; null before the first measurement."},"scope_size_at":{"type":"string","format":"date-time","nullable":true},"processed_in_pass":{"type":"integer","format":"int64","description":"Items processed in the current pass."},"last_preview_at":{"type":"string","format":"date-time","nullable":true},"last_preview_scope_size":{"type":"integer","format":"int64","nullable":true},"last_preview_tokens_per_item":{"type":"integer","format":"int64","nullable":true},"estimated_tokens":{"type":"integer","format":"int64","nullable":true,"description":"Null without both a scope size and a stored preview."},"estimated_cost":{"type":"number","nullable":true,"description":"Null without estimated_tokens or while the provider has no prices."},"budget_paused":{"type":"boolean","description":"True while a running (dry_run or live) instance waits for the next budget window."},"restart_pending":{"type":"boolean","description":"True from the moment a dry run goes live until the next sweep begins: that sweep deletes the item records that dry-run sweeps made, so the profiles (or events) only a dry run saw are processed again, live. Items a live run handled are kept."},"restart_on_live":{"type":"boolean","description":"True when going live now (switch from dry_run, or start from stopped) will set restart_pending, because the instance's latest continuous run was a dry run. Previews do not count; false in every other state."},"preview_status":{"type":"string","enum":["none","pending","ok","failed"],"description":"pending while a preview is queued or running; failed when the latest preview run did not finish ok (see preview_error); ok when a preview is stored; else none."},"preview_error":{"type":"string","nullable":true,"description":"The latest preview run's error code (for example no_sample_items, preview_incomplete, budget_exhausted); null unless preview_status is failed."}}},"AgentModeRequest":{"type":"object","required":["mode"],"properties":{"mode":{"type":"string","enum":["dry_run","live"]}}},"AgentPreviewAccepted":{"type":"object","description":"A cost preview was queued, or one was already pending or running.","properties":{"requested_at":{"type":"string","format":"date-time","description":"When the preview was requested; the earlier request's time when `duplicate` is true."},"duplicate":{"type":"boolean","description":"True when a preview was already pending or running, so nothing new was queued."}}},"AgentRunObject":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"instance_id":{"type":"string","format":"uuid"},"definition_version":{"type":"integer"},"trigger_kind":{"type":"string","enum":["event","schedule","continuous","preview"]},"trigger_ref":{"type":"string"},"stage":{"type":"string","nullable":true},"dry_run":{"type":"boolean"},"status":{"type":"string","enum":["running","ok","no_action","failed","skipped","budget_exhausted"]},"error":{"type":"string","nullable":true},"started_at":{"type":"string","format":"date-time"},"finished_at":{"type":"string","format":"date-time","nullable":true},"input_tokens":{"type":"integer","format":"int64"},"output_tokens":{"type":"integer","format":"int64"},"cost":{"type":"number","nullable":true},"items_processed":{"type":"integer","format":"int64","description":"Items a continuous sweep or preview processed in this run; 0 for other runs."},"items_failed":{"type":"integer","format":"int64","description":"Items whose processing failed in this run; each also has an item_failed log entry."},"items_skipped":{"type":"integer","format":"int64","description":"Items skipped in this run (left out and retried in a later pass)."},"limits":{"nullable":true,"description":"The limits this run started with (all keys present for runs recorded by this version); null for runs started before limits were recorded.","allOf":[{"$ref":"#/components/schemas/AgentRunLimits"}]},"log":{"type":"array","description":"The run's log entries, masked for the reader. Present on GET /agents/runs/{id} only.","items":{"$ref":"#/components/schemas/AgentLogEntryObject"}}}},"AgentLogEntryObject":{"type":"object","description":"One audit-log row. Masking: when the reader's PII clearance or purpose grants are below what the row was written under, `masked` is true and `target`, `object`, `read_refs` and `explanation` are withheld (null or empty); the rest of the row stays visible.","properties":{"id":{"type":"integer","format":"int64"},"instance_id":{"type":"string","format":"uuid"},"run_id":{"type":"string","format":"uuid","nullable":true},"kind":{"type":"string","enum":["created","started","stopped","mode_switched","cancelled","system_stopped","action","triggers_dropped","preview_requested","item_failed","run_summary"]},"actor":{"type":"string","nullable":true},"action_type":{"type":"string","nullable":true},"target":{"nullable":true,"description":"What the action touched (JSON). Withheld when masked."},"object":{"nullable":true,"description":"What the action wrote (JSON). On `run_summary` rows: `outcome` (the outcome the final step led to: `ok`, `no_action` or `failed`), `actions` (the number of actions the final step proposed, each attempted), `summary` (`provided`, `not_provided`, `withheld`) and `withheld_reason` (`too_long`, `personal_data`, `quoted_text`, `ungrounded_numbers`). Withheld when masked."},"explanation":{"type":"string","description":"On `action` rows the agent's stated reason; on `run_summary` rows the model's run summary (checked mechanically, absent when not provided or withheld). Withheld when masked."},"read_refs":{"nullable":true,"description":"References to the data the agent read (JSON). Withheld when masked."},"tools_used":{"type":"array","nullable":true,"items":{"type":"string"}},"dry_run":{"type":"boolean","nullable":true,"description":"On `action` and `run_summary` rows, whether the action or run was a dry run. On `started` and `mode_switched` rows, the resulting mode: true = dry_run, false = live. Null on the other lifecycle rows."},"masked":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"}}}}},"security":[{"ApiKeyAuth":[]}],"paths":{"/cdp/health":{"get":{"summary":"Health check","description":"Returns 200 when the server is up. No authentication required.","operationId":"healthCheck","security":[],"tags":["Health"],"responses":{"200":{"description":"Server is healthy.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"},"example":{"status":"ok","message":"healthy"}}}}}}},"/cdp/api/v1/entities":{"get":{"summary":"List entities","description":"Returns entity definitions, optionally filtered to a set of entity types.\nResults are paginated and sortable.\n","operationId":"getEntities","tags":["Entities"],"parameters":[{"name":"types","in":"query","description":"Filter to these entity types (repeatable).","schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":true,"example":["customer","household"]},{"name":"page","in":"query","schema":{"type":"integer","minimum":0,"default":0}},{"name":"size","in":"query","description":"Rows per page. Defaults to 100; maximum is 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":100}},{"name":"sort_by","in":"query","schema":{"type":"string","enum":["entity_type","parent_entity_type","description","created_at","updated_at"]}},{"name":"sort_dir","in":"query","schema":{"type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"List of entity definitions.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/EntityObject"}}}}]},"example":{"status":"ok","message":"fetched entities","data":[{"entity_type":"customer","description":"Individual end-customer","attributes":{"email":"string","age":"integer"},"identifiers":["email","phone"]}]}}}},"400":{"description":"Invalid query parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/entities/add":{"post":{"summary":"Create entity","description":"Creates a new entity definition. Returns 400 when an entity with the same\n`entity_type` already exists.\n","operationId":"createEntity","tags":["Entities"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityObject"},"example":{"entity_type":"customer","description":"Individual end-customer","attributes":{"email":"string","age":"integer","revenue_ltv":"decimal","opted_in":"boolean","registered_at":"datetime"},"pii_levels":{"email":3},"identifiers":["email","phone","loyalty_id"],"pii_identifiers":{"email":3,"phone":3}}}}},"responses":{"200":{"description":"Entity created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"},"example":{"status":"ok","message":"entity created"}}}},"400":{"description":"Invalid payload or duplicate entity type.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/entities/update":{"post":{"summary":"Update entity","description":"Updates an existing entity definition as a partial update: fields left out\nof the body keep their stored value, and an explicit empty value clears\none. Returns 400 when the entity does not exist. Note: this operation is\nasynchronous.\n","operationId":"updateEntity","tags":["Entities"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityUpdateRequest"},"example":{"entity_type":"customer","description":"Updated description","attributes":{"email":"string","age":"integer","revenue_ltv":"decimal"}}}}},"responses":{"200":{"description":"Entity updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"},"example":{"status":"ok","message":"entity updated"}}}},"400":{"description":"Invalid payload or entity not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/entities/remove":{"delete":{"summary":"Remove entity","description":"Deletes a single entity definition. Returns 400 when the entity does not\nexist. Note: this operation is asynchronous.\n","operationId":"removeEntity","tags":["Entities"],"parameters":[{"name":"type","in":"query","required":true,"description":"Entity type to remove.","schema":{"type":"string"},"example":"customer"}],"responses":{"200":{"description":"Entity removed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"},"example":{"status":"ok","message":"entity removed"}}}},"400":{"description":"Missing query parameter or entity not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/event-types":{"get":{"summary":"List event types","description":"Returns event type definitions, paginated and sortable.","operationId":"getEventTypes","tags":["Event Types"],"parameters":[{"name":"types","in":"query","description":"Filter to these event types (repeatable).","schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":true},{"name":"page","in":"query","schema":{"type":"integer","minimum":0}},{"name":"size","in":"query","description":"Rows per page. Defaults to 100; maximum is 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":100}},{"name":"sort_by","in":"query","schema":{"type":"string","enum":["event_type","description","created_at","updated_at"]}},{"name":"sort_dir","in":"query","schema":{"type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"List of event type definitions.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/EventTypeObject"}}}}]},"example":{"status":"ok","message":"fetched event types","data":[{"event_type":"purchase","description":"Customer completed a purchase","attributes":{"order_id":"string","amount":"decimal","item_count":"integer"}}]}}}},"400":{"description":"Invalid query parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/event-types/add":{"post":{"summary":"Create event type","description":"Creates a new event type. Returns 400 on duplicate name.","operationId":"createEventType","tags":["Event Types"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventTypeObject"},"example":{"event_type":"purchase","description":"Customer completed a purchase","attributes":{"order_id":"string","amount":"decimal","item_count":"integer","currency":"string"},"pii_levels":{"card_last4":2}}}}},"responses":{"200":{"description":"Event type created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"},"example":{"status":"ok","message":"event type created"}}}},"400":{"description":"Invalid payload or duplicate event type.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/event-types/update":{"post":{"summary":"Update event type","description":"Updates an existing event type. Returns 400 when not found.","operationId":"updateEventType","tags":["Event Types"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventTypeObject"},"example":{"event_type":"purchase","description":"Updated purchase event","attributes":{"order_id":"string","amount":"decimal"}}}}},"responses":{"200":{"description":"Event type updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"},"example":{"status":"ok","message":"event type updated"}}}},"400":{"description":"Invalid payload or event type not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/event-types/remove":{"delete":{"summary":"Remove event types","description":"Deletes one or more event types. Returns 400 when any of the requested\ntypes do not exist.\n","operationId":"removeEventTypes","tags":["Event Types"],"parameters":[{"name":"types","in":"query","required":true,"description":"Event types to remove (repeatable).","schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":true,"example":["purchase","page_view"]}],"responses":{"200":{"description":"Event type(s) removed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"},"example":{"status":"ok","message":"event type(s) removed"}}}},"400":{"description":"No types provided or one or more not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/profiles":{"get":{"summary":"List / look up profiles","description":"Returns profiles with their identifiers. Optionally filtered by profile id,\nan identifier key/value pair, or an arbitrary query-builder filter tree\n(JSON-encoded `filter` + `entity_type`). Every filter you give\n(`profile_id`, the `id_key`/`id_value` pair, `entity_type`, `filter`,\n`cohort`) is ANDed with the others: `profile_id` plus an identifier pair\nreturns the profile only if it carries that identifier. `id_key` and\n`id_value` are both-or-neither; sending one without the other (or one\nwith an empty value) is a 400. Pass `include_attributes=true` to also\nhydrate EAV attributes. `filter`, `cohort` and `id_key` are\nauthorized against the actor's clearance before the query runs (403\nManifestForbidden).\n","operationId":"getProfiles","tags":["Profiles"],"parameters":[{"$ref":"#/components/parameters/OnBehalfOfAppHeader"},{"name":"profile_id","in":"query","description":"Look up a single profile by its UUID.","schema":{"type":"string","format":"uuid"}},{"name":"id_key","in":"query","description":"Identifier key to filter by. Must be sent together with `id_value`; sending one without the other is a 400.","schema":{"type":"string"},"example":"email"},{"name":"id_value","in":"query","description":"Identifier value to filter by. Must be sent together with `id_key`; sending one without the other is a 400.","schema":{"type":"string"},"example":"jane@example.com"},{"name":"entity_type","in":"query","description":"Entity type scope for filter validation (required when `filter` is set). Used to resolve attribute schemas and PII metadata.\n","schema":{"type":"string"},"example":"customer"},{"name":"filter","in":"query","description":"JSON-encoded query-builder filter tree. Supports profile attributes,\nidentifiers, event aggregates, consents, custom dataset conditions, and\ncomputed attributes. Requires `entity_type`: a request that sets `filter`\nwithout it is refused with 400 `entity_type is required when filter is set`.\nExample:\n`{\"combinator\":\"and\",\"rules\":[{\"field\":\"profile.country\",\"operator\":\"=\",\"value\":\"DE\"}]}`\n","schema":{"type":"string"},"example":"{\"combinator\":\"and\",\"rules\":[{\"field\":\"event.purchase.count\",\"operator\":\">\",\"value\":0}]}"},{"name":"fields","in":"query","description":"Narrows what is READ about each matching profile. The only accepted\nvalue is `id`: the response carries `[{\"id\": \"...\"}]` and nothing\nelse — no identifiers, no attributes, and **no `page` block**, since\nthe page total is a full aggregate over the filtered set that this\nmode exists not to compute (ask for it the usual way with a\n`size=1` page and read `page.total`). The one exception is cursor\nmode (`after`): that ids page does carry a `page` block, with\n`next_after` and `total: -1`, because the next cursor has nowhere\nelse to go.\n\nIntended for callers that will address each profile individually\nafterwards — sampling, export planning, bulk jobs — for which the\nordinary page pays for a description of every profile that is then\ndiscarded. `ORDER BY` is fixed to the profiles table's own key, so\n`sort_by` / `sort_dir` are ignored in this mode (together with\n`after` they are a 400, not ignored); paging is only coherent if\nconsecutive requests agree on the order. An explicit `size` is at\nmost 100, as on every list; when `size` is omitted the page is up to\n5000 ids here (the 100-row page limit bounds pages of profile ROWS,\nwhich cost child lookups, filtering and an audit entry each).\n\nPrivacy is unchanged: purpose authorization (gate 1) has already\nrun, and gates 2–4 are attribute-scoped with no\nattribute or identifier to act on — this response is strictly less\ndisclosure than the full page. Every returned id is still written\nto the privacy audit log, as one batched entry per page.\n\nAny other value is rejected with 400 rather than silently serving\nthe full page the caller was trying to avoid.\n","schema":{"type":"string","enum":["id"]}},{"name":"sample_mod","in":"query","description":"Draw ONE profile in N from the matching population, chosen by\n`halfMD5` of the profile id. A uniform sample in a single query,\nreplacing a walk through the population's pages.\n\nRequires `fields=id` and is **rejected** (400) without it, rather\nthan ignored: a caller that believes it sampled and did not holds a\nprefix of the population and cannot tell. With `fields=id` the page\nceiling is 5000 rather than 100, since the point of the draw is that\na whole sample arrives in one request.\n\nThe hash matters as much as the arithmetic — it has no relationship\nto anything a campaign selects on, so the survivors are an\nindependent draw and a confidence interval computed from them is\nhonest. Taking a prefix, or a stride of pages, draws profiles that\nare adjacent in key order (cluster sampling), whose members are more\nalike than the population is.\n\nThe expected yield is `matching / sample_mod`; `size` caps it.\n","schema":{"type":"integer","minimum":2},"example":20},{"name":"after","in":"query","description":"Cursor paging. Returns the profiles whose `id` is after this profile\nUUID, in ascending `id` order, up to `size` (at most 100; with\n`fields=id` and `size` omitted, up to 5000). Start a walk from\n`00000000-0000-0000-0000-000000000000` and pass the response's\n`page.next_after` as `after` for the next page; a response without\n`next_after` is the last page. A walk visits each matching profile\nonce, without skipping or repeating a profile when rows are deleted\nmid-walk, and a deep page reads only the rows past the cursor\ninstead of re-reading every earlier page.\n\nNo total is computed: `page.total` is `-1` (\"not computed\") and the\n`created_at` sort is not run. Works with full-row pages and with\n`fields=id`. A full page is followed by `next_after` even when it was\nthe last one, so the walk may end with one empty page.\n\nRejected (400, naming the parameter) together with `page` > 0,\n`sort_by`, `sample_mod`, `profile_id` or `id_key`/`id_value`, and\nwhen the value is not a UUID.\n","schema":{"type":"string","format":"uuid"},"example":"00000000-0000-0000-0000-000000000000"},{"name":"include_attributes","in":"query","description":"When true, hydrates EAV attributes for each returned profile.","schema":{"type":"boolean","default":false}},{"name":"include_computed","in":"query","description":"When true, evaluates the enabled computed attributes defined on each returned profile's entity type and includes their values under `computed_attributes`. Definitions reading inputs above the caller's clearance are withheld and listed in `redacted_computed_attributes`.\n","schema":{"type":"boolean","default":false}},{"name":"computed","in":"query","description":"With `include_computed=true`: a comma-separated list of computed attribute names to evaluate instead of every enabled definition. Names that match no enabled definition are ignored: a list of only unknown names, or one with no names at all (`computed=,`), evaluates none and takes no heavy-read slot. An empty value (`computed=`) is the same as leaving the parameter out (every enabled definition). The clearance check still applies: a named definition reading inputs above the caller's clearance is withheld and listed in `redacted_computed_attributes`. No effect without `include_computed=true`.\n","schema":{"type":"string"},"example":"lifetime_value,preferred_channel"},{"name":"include_signals","in":"query","description":"When true, attaches each returned profile's active signal values (with freshness metadata) under `signals`. Stale values are recomputed inline up to a per-entity cap; beyond it, last-known values are served and the scheduler refreshes them.\n","schema":{"type":"boolean","default":false}},{"name":"signals_recompute","in":"query","description":"With `include_signals=true`: `false` serves the stored (last-known) signal values as they are, with their freshness metadata, and never recomputes inline, whatever `signal_refresh` says; a signal with no stored value is listed with `stale: true` and no value. The scheduler refreshes stale values. Meant for per-message reads that must not pay a recompute. Default `true` (today's behaviour). A value that is not a boolean is a 400.\n","schema":{"type":"boolean","default":true}},{"name":"signal_refresh","in":"query","description":"With `include_signals=true`: `inline` (default) recomputes stale or missing signal values before answering; `cached` serves stored values as they are, with their `computed_at`, `valid_until` and `stale` metadata, and only computes a signal that has no stored value. An external signal with `staleness_action=exclude` stays withheld when stale in both modes. Any other value is a 400. It has no effect without `include_signals=true` but is still validated.\n","schema":{"type":"string","enum":["inline","cached"],"default":"inline"}},{"name":"include_cohorts","in":"query","description":"When true, attaches the cohorts each returned profile belongs to under `cohorts` (active cohorts for the entity type whose filter matches the profile's current signal values). Also accepted on `GET /profiles/{id}`.\n","schema":{"type":"boolean","default":false}},{"name":"cohort","in":"query","description":"Restrict results to profiles whose current signal values satisfy the named cohort's filter expression. Requires `entity_type`. Evaluated inline (ANDed with any `filter`).\n","schema":{"type":"string"}},{"name":"resolve_identity","in":"query","description":"When true, returns the identity-resolved view: for each profile that belongs to a multi-member cluster, `attributes` is merged across cluster members per the entity's active ruleset merge policy, and `cluster_id` / `cluster_members` are populated. Also accepted on `GET /profiles/{id}`.\n","schema":{"type":"boolean","default":false}},{"name":"page","in":"query","schema":{"type":"integer","minimum":0}},{"name":"size","in":"query","description":"Rows per page. Defaults to 100; maximum is 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":100}},{"name":"sort_by","in":"query","schema":{"type":"string","enum":["entity_type","created_at"]}},{"name":"sort_dir","in":"query","schema":{"type":"string","enum":["asc","desc"]}},{"name":"purpose","in":"query","description":"Consent purpose for the request (`X-Purpose` header alternative).\nWhen `include_attributes=true` and privacy enforcement is active,\nattributes tagged for other purposes are filtered out.\n","schema":{"type":"string"},"example":"analytics"}],"responses":{"200":{"description":"List of profiles.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ProfileObject"}}}}]},"example":{"status":"ok","message":"fetched profiles","data":[{"id":"550e8400-e29b-41d4-a716-446655440000","entity_type":"customer","identifiers":[{"key":"email","value":"jane@example.com"}],"attributes":{"age":30,"opted_in":true},"created_at":"2024-06-01T12:00:00Z"}]}}}},"400":{"description":"Invalid query parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"$ref":"#/components/responses/ManifestForbidden"},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"The profile store is temporarily unable to answer: its shared memory budget (per-user or total, not this query's own limit) is exhausted, it hit its own execution timeout, or too many heavy profile reads were already running on the instance. The message names the reason and never carries SQL. Retry after `Retry-After` seconds. An inline signal recompute that finds the limit full does not fail the request: last-known values are served.","headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","example":2}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/profiles/set":{"post":{"summary":"Create or update profile","description":"Upserts a profile. If any supplied identifier already matches an existing\nprofile, attributes are appended to that profile (partial update — omitted\nattributes keep their stored values), and supplied identifiers no profile\nowns yet are added to it (a newly learned email or phone). Otherwise a new\nprofile is created. Returns the profile id and whether it was newly created.\n\nWhen the supplied identifiers already belong to two or more different\nprofiles (stored, or still being written), nothing is stored and the\nanswer is 409 `identifier_conflict`. Merge the profiles\n(`POST /profiles/merge`) or send the identifiers of one profile. Two\nidentifiers of the same profile are not a conflict.\n\nData-contract `required` rules are evaluated against the merged result: a\nrequired attribute is satisfied if it is in the payload **or** already\nstored on the profile. So a partial update need not re-send every required\nattribute; only a profile that would still be missing a required attribute\nis rejected (422).\n\nThe tenant's `max_profiles` quota counts **creates only**: at the cap an\nupdate of an existing profile is accepted and a request that would create a\nprofile is refused (403). It is checked against the coarse usage rollup.\n","operationId":"setProfile","tags":["Profiles"],"parameters":[{"$ref":"#/components/parameters/PurposeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetProfileRequest"},"example":{"entity_type":"customer","identifiers":[{"key":"email","value":"jane@example.com"},{"key":"phone","value":"+15551234567"}],"attributes":{"age":30,"opted_in":true,"revenue_ltv":1249.99},"source":"crm"}}}},"responses":{"200":{"description":"Profile created or updated.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"profile_id":{"type":"string","format":"uuid"}}}}}]},"example":{"status":"ok","message":"profile created","data":{"profile_id":"550e8400-e29b-41d4-a716-446655440000"}}}}},"400":{"description":"Invalid payload — including an attribute value that does not fit its\ndeclared type (`attribute '<key>': …`; was a 503 before 2026-10-09,\nnow refused before any write) — or, in `enforce`/`strict` privacy modes, a purpose\ncollection violation: an attribute tagged in the schema's\n`attribute_purposes` shares no purpose with the declared `X-Purpose`\nset. The violation body is\n`{status: error, message: \"purpose collection violation: attribute(s) a, b need one of the purposes [x, y]; declare one with the X-Purpose header\",\ndata: {violations: [{attribute, attribute_purposes,\ndeclared_purposes}]}}` (audit mode stores the data and only warns).\nAlso: `profile_id addressing is supported by /profiles/set/batch only`\nwhen the body carries `profile_id`, and `identifiers must contain at\nleast one item` for an empty `identifiers` list.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Creating this profile would exceed the tenant's `max_profiles` quota (`profile quota reached (<n> profiles)`). Updates of existing profiles are never refused by the quota.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The identifiers resolve to two or more different profiles; nothing is\nstored. `data.groups` lists the request's identifier keys per owning\nprofile. It never carries identifier values or profile ids.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IdentifierConflictResponse"},"example":{"status":"error","message":"identifiers resolve to more than one profile","data":{"reason":"identifier_conflict","groups":[{"identifier_keys":["email"]},{"identifier_keys":["phone","crm_id"]}]}}}}},"503":{"description":"Failed to store profile (write stream unavailable), or the tenant is at its profile quota and the identifier resolution needed to tell a create from an update failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/profiles/set/batch":{"post":{"summary":"Create or update profiles in one batch","description":"The batch form of `/profiles/set`: 1 to `profile_batch_max` items\n(instance setting, default 500, max 1000), each a\n`SetProfileRequest` or `SetProfileByIDRequest`, **all-or-nothing**. Every item passes the single\nendpoint's rules before anything is written — remove/set conflicts,\nconsent `expires_at`, contract normalisation, strict mode (422), purpose\nlimitation (audit mode stores, enforce/strict reject), and contract rules\nagainst the merged state. The first failing item answers with that\nstatus and a message prefixed `profiles[<i>]: `; nothing is stored.\n\nAn item may instead carry `profile_id` (an existing profile, with the\nmatching `entity_type`) and no `identifiers`: the profile is updated\nwithout identifier resolution. A `profile_id` that does not exist fails\nthe **whole** batch with `404 profiles[<i>]: profile not found`\n(drop that item and retry). Two items with the same `profile_id` are\nrejected like overlapping identifiers. A profile that is being erased\nasynchronously can still accept a write in the seconds between the\nerasure request and its completion, exactly as the identifier\npath can; callers that must not write to an erased profile re-read\n`POST /profiles/views` immediately before writing (an erased profile is\nabsent from it).\n\nTwo items whose identifiers overlap (same entity type and a shared\nkey/value) or that resolve to the same existing profile are rejected\n(400 `profiles[<j>]: duplicates profiles[<i>]`) — send one item per\nprofile. An item whose own identifiers belong to two or more different\nprofiles fails the whole batch with 409 `identifier_conflict` and its\n`index`, as on `/profiles/set`.\n\nIdentifier resolution is one read per entity type for the whole batch\nand the profile writes are one publish, so this is the fast path for bulk\nloads. Inline consents are stored like `/profiles/set` (best-effort after\nthe profiles). The `max_profiles` quota counts the batch's NEW profiles only, so an update-only batch is accepted at the cap.\nA batch counts as one request for the rate limits (per-IP and the\ntenant `rpm`/`rpm_service` quotas), like `/events/add`.\n\nAttribute values that do not fit their declared types are refused with\n`400 profiles[<i>]: attribute '<key>': …` before anything is written.\nValidation is all-or-nothing, but the write is not atomic: a 503 on the\npublish may leave the batch **partially applied** — retry the same batch\n(it is an upsert). A failure to publish the inline `consents` is also a\n503 (`failed to store consents`); `/profiles/set` behaves the same.\n","operationId":"setProfilesBatch","tags":["Profiles"],"parameters":[{"$ref":"#/components/parameters/PurposeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetProfilesBatchRequest"},"example":{"profiles":[{"entity_type":"customer","identifiers":[{"key":"email","value":"jane@example.com"}],"attributes":{"first_name":"Jane"},"source":"crm"},{"entity_type":"customer","identifiers":[{"key":"email","value":"john@example.com"}],"attributes":{"first_name":"John"},"source":"crm"}]}}}},"responses":{"200":{"description":"Every profile created or updated. `results` is in request order.\nContract warnings, if any, are in `warnings`, each tagged with its\nitem `index`.\n","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SetProfilesBatchResponse"}}}]},"example":{"status":"ok","message":"profiles stored","data":{"results":[{"profile_id":"550e8400-e29b-41d4-a716-446655440000","created":true},{"profile_id":"7d1c0a2e-5b7f-4a43-9b9e-2f0a7f3c1e11","created":false}]}}}}},"400":{"description":"Empty batch, more than `profile_batch_max` items, an invalid item\n(including an attribute value that does not fit its declared type),\nan intra-batch duplicate, an item with both or neither of `profile_id`\nand `identifiers` (`set either profile_id or identifiers`), an\n`invalid profile_id`, a `profile_id` item whose `entity_type` does not\nmatch the profile (`entity_type does not match the profile`), or\n(enforce/strict) a purpose collection\nviolation, whose body is the `/profiles/set` one plus the item index:\n`{status: error, message: \"profiles[<i>]: purpose collection violation\",\ndata: {index, violations: [...]}}`.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The tenant's `max_profiles` quota would be exceeded by the batch's new profiles.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"An item's `profile_id` does not exist (message `profiles[<i>]: profile not found`); nothing is stored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"An item's identifiers resolve to two or more different profiles (the `/profiles/set` 409 body plus the item `index`); nothing is stored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IdentifierConflictResponse"},"example":{"status":"error","message":"profiles[2]: identifiers resolve to more than one profile","data":{"reason":"identifier_conflict","index":2,"groups":[{"identifier_keys":["email"]},{"identifier_keys":["phone"]}]}}}}},"422":{"description":"Strict-mode or data-contract violation on an item (message prefixed `profiles[<i>]: `).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Schema read or profile resolution failed (nothing stored), or the write publish failed: the batch may be partially applied; retry the same batch — it is an upsert.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/profiles/remove":{"delete":{"summary":"Remove profiles","description":"Deletes profiles and their identifiers and attributes by id. Note:\nthis operation is asynchronous.\n","operationId":"removeProfiles","tags":["Profiles"],"parameters":[{"$ref":"#/components/parameters/PurposeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RemoveProfilesRequest"},"example":{"ids":["550e8400-e29b-41d4-a716-446655440000"]}}}},"responses":{"200":{"description":"Profiles removed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"},"example":{"status":"ok","message":"profiles removed"}}}},"400":{"description":"Invalid payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/deletion-requests":{"get":{"summary":"List scheduled and finished bulk deletes","description":"The queue a filtered delete lands in, newest first. The resolved ids are deliberately not included — a pending request can hold tens of thousands of them and nothing reading this wants the list.\n","operationId":"listDeletionRequests","tags":["Privacy"],"parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["pending","in_progress","completed","failed","cancelled"]}},{"name":"limit","in":"query","schema":{"type":"integer","default":25,"maximum":100}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"`data` is `{requests, total}`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DeletionRequestList"}}}]}}}}}}},"/cdp/api/v1/deletion-requests/{id}":{"delete":{"summary":"Cancel a scheduled bulk delete","description":"Calls off a delete that has not started. A request that is already executing answers **409** rather than 200 — telling somebody their data is safe while it is being deleted is the worst answer available here. So does a request the deletion job put back to `pending` after a transient failure (`started_at` is set): it may be partly deleted.\n","operationId":"cancelDeletionRequest","tags":["Privacy"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Cancelled; `data` is the request in its new state.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DeletionRequestObject"}}}]}}}},"404":{"description":"No such deletion request."},"409":{"description":"Already started (including a pending request with started_at set) or no longer pending, so no longer cancellable."}}}},"/cdp/api/v1/profiles/remove-by-filter":{"delete":{"summary":"Remove profiles by filter","description":"Deletes every profile of the entity type matching the querybuilder\nfilter and/or cohort (resolved server-side to the id set, then removed\nthrough the same write path as `/profiles/remove`). Requires at least\none of `filter`/`cohort`.\n\n**Deferred since 2026-08-17, and this is a BREAKING change.** The delete\nno longer happens during the call: it is scheduled\n`bulk_delete_delay_sec` (default 300) into the future and answers\n**202** with `{request_id, scheduled_at, matched}`, so an operator who\npicked the wrong filter has a window in which to cancel it via\n`DELETE /cdp/api/v1/deletion-requests/{id}`. Pass `?immediate=true` for\nthe old behaviour — a 200 with `{deleted}`, performed inline. A caller\nthat deletes and then asserts the rows are gone needs that flag.\n","operationId":"removeProfilesByFilter","tags":["Profiles"],"parameters":[{"name":"dry_run","in":"query","schema":{"type":"boolean"},"description":"true = return the exact would-be count without deleting: {matched, dry_run}."},{"name":"immediate","in":"query","schema":{"type":"boolean"},"description":"true = delete inline and return 200 {deleted}, skipping the cancellation window."},{"$ref":"#/components/parameters/PurposeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RemoveProfilesByFilterRequest"}}}},"responses":{"200":{"description":"Immediate delete (`?immediate=true`; `data.deleted` holds the count), a dry run, or nothing matched (`{matched: 0, deleted: 0}`; nothing is scheduled).\n","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BulkDeleteResult"}}}]}}}},"202":{"description":"Deletion scheduled; `data` is `{request_id, scheduled_at, matched, status}`. Cancellable until `scheduled_at`.\n","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ScheduledDeleteResponse"}}}]}}}},"400":{"description":"Invalid payload or filter, or more than 100000 matches (narrow the filter).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"$ref":"#/components/responses/ManifestForbidden"},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/profiles/export":{"post":{"summary":"Export profiles as CSV","description":"Streams a CSV of every profile matching the filter/cohort, with the\nselected identifier/attribute/signal/computed/consent columns.\nAttribute values pass the same purpose/PII/consent gates as\n`GET /profiles`; signal columns use stored values (no inline\nrecompute) but pass the same external-signal purpose gate and\nstaleness `exclude` rule as `GET /profiles?include_signals` and\n`GET /profiles/{profile_id}/signals` — a signal whose source\npurposes are disjoint from the declared `X-Purpose`, or an\n`exclude`-mode external signal past `valid_until`, exports as a\nblank cell and is audit-logged as denied. A requested signal with no\nenabled definition for the entity (e.g. a disabled external signal\nwhose stored values survive) is never shown by those reads either,\nand exports as a blank cell. Each exported profile is\nalso audit-logged for the attributes/consents it discloses.\n","operationId":"exportProfiles","tags":["Profiles"],"parameters":[{"$ref":"#/components/parameters/PurposeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExportProfilesRequest"}}}},"responses":{"200":{"description":"CSV file (attachment).","content":{"text/csv":{"schema":{"type":"string"}}}},"400":{"description":"Invalid payload or filter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"$ref":"#/components/responses/ManifestForbidden"},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/profiles/dedup-identifiers":{"post":{"summary":"Report or repair duplicate identifiers","description":"Identifiers are unique per entity type. This maintenance endpoint finds\n(key, value) pairs owned by more than one profile of the entity type\nand — unless `dry_run` (the default) — merges the younger duplicates\ninto the oldest profile via the standard merge operation. Merges apply\nasynchronously in the write pipeline, so a re-run may report the same\ngroups until those merges have been applied; process in batches via `limit`.\n","operationId":"dedupIdentifiers","tags":["Profiles"],"parameters":[{"$ref":"#/components/parameters/PurposeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DedupIdentifiersRequest"},"example":{"entity_type":"customer","key":"email","dry_run":true,"limit":100}}}},"responses":{"200":{"description":"Dedup report / pass summary.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DedupIdentifiersResponse"}}}]}}}},"400":{"description":"Invalid payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Entity schema read failed, so the PII gate on returned identifier values could not be enforced.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/profiles/merge":{"post":{"summary":"Merge profiles","description":"Merges the source profile into the target. All events, attributes, and\nidentifiers of the source are re-pointed to the target (with\n`origin_profile_id` preserved for provenance). The merge is recorded as a\n`profile_link` entry with `relation_type: merge` and the source profile\nrow is deleted.\n\n**Constraints (all return 400 on violation):**\n- Both profiles must exist.\n- `target_profile_id` and `source_profile_id` must be different.\n- Both profiles must have the same `entity_type` (e.g. you cannot merge a\n  `customer` profile into a `device` profile).\n- The pair must not already be merged (an existing `profile_link` with\n  `relation_type: merge` for the same source/target is rejected).\n","operationId":"mergeProfiles","tags":["Profiles"],"parameters":[{"$ref":"#/components/parameters/PurposeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MergeProfilesRequest"},"example":{"target_profile_id":"550e8400-e29b-41d4-a716-446655440000","source_profile_id":"661f9500-f3ac-52e5-b827-557766551111","relation_creator":"identity-service"}}}},"responses":{"200":{"description":"Profiles merged successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"},"example":{"status":"ok","message":"profiles merged"}}}},"400":{"description":"Bad request. Possible causes:\n- Invalid or missing UUID in `target_profile_id` / `source_profile_id`.\n- Either profile does not exist.\n- `target_profile_id` equals `source_profile_id`.\n- Profiles have different `entity_type` values.\n- Profiles are already merged.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/profiles/link":{"post":{"summary":"Link profiles","description":"Records a (non-merging) directed relationship between two profiles (e.g.\nhousehold membership). Both profiles must exist and must differ: linking a\nprofile to itself returns 400.\n","operationId":"linkProfiles","tags":["Profiles"],"parameters":[{"$ref":"#/components/parameters/PurposeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LinkProfilesRequest"},"example":{"parent_profile_id":"550e8400-e29b-41d4-a716-446655440000","child_profile_id":"661f9500-f3ac-52e5-b827-557766551111","relation_type":"household_member","relation_creator":"cdp-api","identifier_key":"household_id","identifier_value":"hh-00123"}}}},"responses":{"200":{"description":"Profiles linked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"},"example":{"status":"ok","message":"profiles linked"}}}},"400":{"description":"Invalid payload, profile not found, or the parent and child are the same profile.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/profiles/links/batch":{"post":{"summary":"List the links of many profiles","description":"The batched form of `GET /profiles/{profile_id}/links`: the\nprofile-link edges touching up to 500 profiles in one read. `direction`\npicks which side of each edge a requested id is matched on, exactly as\non the single-profile route. Each edge is filed under every requested\nprofile it touches on that side, so an edge between two requested\nprofiles appears under both. Every requested id (canonical lowercase\nform; duplicates are read once) is present in `links_by_profile`, with\nan empty list when it has no links. Identifier values are gated by the\ncaller's PII clearance as on the single-profile route, and one privacy\naudit row is written per requested profile.\n","operationId":"getProfileLinksBatch","tags":["Profiles"],"parameters":[{"$ref":"#/components/parameters/PurposeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfileLinksBatchRequest"}}}},"responses":{"200":{"description":"Links fetched.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProfileLinksBatchResponse"}}}]}}}},"400":{"description":"Invalid JSON, empty or more than 500 profile_ids, a malformed id, or an unknown direction.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Entity schema read failed, so the PII gate on returned identifier values could not be enforced.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/profiles/ids":{"post":{"summary":"Walk profile ids with a keyset cursor","description":"One page of the ids of the profiles of one entity type that match an\noptional filter, in ascending id order. Built for a caller that walks a\nwhole population (the continuous agent runtime): pass the previous\nresponse's `next_after_id` as `after_id` until it is absent. The walk is\na keyset (`id > after_id`), so it stays cheap on the last page and never\ncounts the population.\n\n`entity_type` is required. `filter` is the same query-builder filter as\n`GET /profiles` and is authorized against the caller's privacy rules\nlike any saved filter. `limit` is 1 to 5000 (default 1000); a value\noutside the range is refused, not clamped. `next_after_id` is present\nonly when the page is full. One privacy audit row is written per\nreturned profile id, because an id list is a disclosure.\n","operationId":"getProfileIDsPage","tags":["Profiles"],"parameters":[{"$ref":"#/components/parameters/PurposeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfileIDsRequest"}}}},"responses":{"200":{"description":"A page of ids.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProfileIDsResponse"}}}]}}}},"400":{"description":"Invalid JSON, missing `entity_type`, a malformed `after_id`, `limit` outside 1-5000, or an invalid filter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The filter reads attributes or purposes the caller is not cleared for, or the caller is not authorized for the `X-Purpose` purpose (`caller not authorized for purpose`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Entity schema read failed, so the filter could not be authorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/profiles/changes":{"post":{"summary":"Follow profile changes with an opaque cursor","description":"The ids of profiles of one entity type that were written (attributes\nand consents included) since a cursor, optionally narrowed by a `filter`. The first\ncall has no `cursor` and returns no ids, only a starting cursor; each\nlater call returns up to `limit` ids (1 to 5000, default 1000) and the\ncursor to send next.\n\nThe cursor is an opaque base64url string issued by the CDP. It is a\nposition, not an authority: it grants nothing beyond what the caller's\nroute and filter rights already allow. A cursor that does not decode, carries a time before 1970,\nwhose window ends before it starts, or that lies more than a minute in\nthe future is refused (`400 invalid cursor`). There is no maximum\ncursor age: a consumer that was stopped for weeks resumes from its\ncursor, and the first window after a long pause covers everything\nchanged since then, so that first page is expensive. Persist the\ncursor after each page you have processed.\n\nEach window reaches 5 minutes back into the previous one\n(`ChangeOverlap`), because a write becomes readable a moment\nafter its timestamp. A profile can therefore be returned again\nin a later window: de-duplicate on the consumer side. One privacy audit\nrow is written per returned id.\n","operationId":"getChangedProfileIDs","tags":["Profiles"],"parameters":[{"$ref":"#/components/parameters/PurposeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfileChangesRequest"}}}},"responses":{"200":{"description":"A page of changed ids and the next cursor.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProfileChangesResponse"}}}]}}}},"400":{"description":"Invalid JSON, missing `entity_type`, `limit` outside 1-5000, an invalid filter, an invalid `exclude_writes` (empty `source`, no or more than 200 `keys`), or `invalid cursor`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The filter reads attributes or purposes the caller is not cleared for, or the caller is not authorized for the `X-Purpose` purpose (`caller not authorized for purpose`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Entity schema read failed, so the filter could not be authorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/profiles/views":{"post":{"summary":"Read gated item views of many profiles","description":"For up to 100 profile ids, the requested stored attributes and,\noptionally, each profile's newest events of the listed types. Only\nstored attributes are returned (no computed attributes and no\nidentity-resolved view). `attributes` takes up to 100 keys; a key that\ndoes not exist is simply absent from the view. A requested attribute the\ncaller may not read (PII clearance, purpose limitation, consent) is\nomitted and listed in `redacted_attributes`. `events` takes 1 to 20\ntypes, `last_n` 1 to 20 and `within_days` 1 to 365. Profiles that do not\nexist (for example erased ones) are absent from `profiles`, which keeps\nrequest order. Ids are accepted in any case and returned lowercase.\n\n`events` returns event data, so it also needs an event read: both the\ncaller and, for an application acting for a user, that user must be\nallowed `GET /events` or `GET /profiles/{profile_id}/events`, else the\ncall is refused with 403 before anything is read or audited. Omit\n`events` to get attributes only.\n\n`identifiers: true` also returns each profile's identifiers, filtered\nby PII level like `GET /profiles` and audited on the profile's row.\n\nOne privacy audit row is written per profile returned, and one per\nreturned event.\n","operationId":"getProfileViews","tags":["Profiles"],"parameters":[{"$ref":"#/components/parameters/PurposeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfileViewsRequest"}}}},"responses":{"200":{"description":"The views of the profiles that exist.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProfileViewsResponse"}}}]}}}},"400":{"description":"Invalid JSON, empty or more than 100 `profile_ids`, a malformed id, more than 100 attributes, or an out-of-range `events` field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The caller is not authorized for the `X-Purpose` purpose (`caller not authorized for purpose`), or `events` was asked for and the caller (or its delegated user) holds no event read (`events require event read access`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Entity schema read failed, so the privacy gates could not be enforced.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/profiles/{profile_id}/links":{"get":{"summary":"List profile links","description":"Returns the profile-link (stitching/relationship) edges touching the\nprofile. By default both directions are returned; use `direction` to\nrestrict to edges where the profile is the parent or the child, and\n`relation_type` to filter by relationship type.\n","operationId":"getProfileLinks","tags":["Profiles"],"parameters":[{"$ref":"#/components/parameters/PurposeHeader"},{"name":"profile_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"direction","in":"query","description":"Which side of the link the profile is matched on.","schema":{"type":"string","enum":["both","parent","child"],"default":"both"}},{"name":"relation_type","in":"query","description":"Optional filter by relation type (e.g. `household_member`, `merge`, `identity`).","schema":{"type":"string"}}],"responses":{"200":{"description":"Links fetched.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ProfileLinkObject"}}}}]}}}},"400":{"description":"Invalid profile_id or direction.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Entity schema read failed, so the PII gate on returned identifier values could not be enforced.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/profiles/{profile_id}/links/{child_profile_id}":{"patch":{"summary":"Update profile link attributes","description":"Edits the non-key attributes of the link(s) from `{profile_id}` (parent)\nto `{child_profile_id}` (child). The two profiles in the relation are\nnever changed. Supply `relation_type` to narrow the update to a single\nrelation type; otherwise all links between the pair are updated. At least\none updatable field must be present in the body.\n","operationId":"updateProfileLink","tags":["Profiles"],"parameters":[{"$ref":"#/components/parameters/PurposeHeader"},{"name":"profile_id","in":"path","required":true,"description":"Parent profile id.","schema":{"type":"string","format":"uuid"}},{"name":"child_profile_id","in":"path","required":true,"description":"Child profile id.","schema":{"type":"string","format":"uuid"}},{"name":"relation_type","in":"query","description":"Optional — restrict the update to links of this relation type.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateProfileLinkRequest"},"example":{"relation_creator":"identity-service","confidence":0.85}}}},"responses":{"200":{"description":"Link(s) updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"},"example":{"status":"ok","message":"updated 1 link(s)"}}}},"400":{"description":"Invalid ids or no updatable fields supplied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No matching link found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"summary":"Remove a profile link","description":"Removes the link(s) from `{profile_id}` (parent) to `{child_profile_id}`\n(child). Supply `relation_type` to remove only links of that type;\nwithout it every link between the pair is removed.\n","operationId":"removeProfileLink","tags":["Profiles"],"parameters":[{"$ref":"#/components/parameters/PurposeHeader"},{"name":"profile_id","in":"path","required":true,"description":"Parent profile id.","schema":{"type":"string","format":"uuid"}},{"name":"child_profile_id","in":"path","required":true,"description":"Child profile id.","schema":{"type":"string","format":"uuid"}},{"name":"relation_type","in":"query","description":"Optional — restrict the deletion to links of this relation type.","schema":{"type":"string"}}],"responses":{"200":{"description":"Link(s) removed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"},"example":{"status":"ok","message":"removed 1 link(s)"}}}},"400":{"description":"Invalid ids.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No matching link found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/profiles/{profile_id}":{"get":{"summary":"Get single profile (live or point-in-time)","description":"Returns a single profile by id. Optionally reconstructs state at a past\ntimestamp using the append-only `h_*` history tables.\n\nWhen `?at=` is supplied the response includes `reconstructed_at` and the\nprofile state reflects what was recorded at or before that timestamp.\nProfiles that did not exist yet, or were deleted before `at`, return 404.\n\nA live read carries `attribute_collection_basis` (the lawful basis each\nreturned attribute was collected under) exactly like the profile list;\nvalues withheld by privacy are not listed.\n","operationId":"getProfileByID","tags":["Profiles"],"parameters":[{"name":"profile_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"at","in":"query","description":"ISO 8601 timestamp (e.g. `2026-01-15T12:00:00Z`). When supplied the profile is reconstructed from history at that point in time.\n","schema":{"type":"string","format":"date-time"}},{"name":"include_attributes","in":"query","schema":{"type":"boolean","default":false}},{"name":"include_cohorts","in":"query","description":"When true, attaches the cohorts this profile belongs to under `cohorts` (active cohorts for the entity type whose filter matches the profile's current signal values).\n","schema":{"type":"boolean","default":false}},{"name":"resolve_identity","in":"query","description":"When true, returns the identity-resolved (cluster-merged) view.","schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"Profile found (live or reconstructed).","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProfileObject"}}}]}}}},"400":{"description":"Invalid profile_id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Profile not found (or did not exist at the requested time).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/profiles/{profile_id}/attributes/{key}/purposes":{"patch":{"tags":["Profiles"],"summary":"Amend an attribute's collection-purpose provenance","description":"Replaces the stored collection-purpose provenance of one profile\nattribute without touching its value (the row is re-emitted as a new\nversion; an `h_profile_attributes` update entry records the change and\nthe audit log records operation `amend_purposes`). An empty `purposes`\nlist resets the attribute to legacy/undeclared provenance. Every named\npurpose must be an active catalog purpose (400 otherwise); in\n`enforce`/`strict` privacy modes a schema-tagged attribute additionally\nrequires overlap with its `attribute_purposes` tags (structured 400\nwith `data.violations[]`).\n","parameters":[{"name":"profile_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"key","in":"path","required":true,"schema":{"type":"string"},"description":"Attribute key."},{"$ref":"#/components/parameters/PurposeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"purposes":{"type":"array","items":{"type":"string"},"description":"New provenance set (empty = reset to legacy)."},"collection_basis":{"type":"string","description":"Optional correction of the stored lawful basis. Omitted =\nderive from the new purposes' own bases; empty string =\nreset to legacy; otherwise one of the six Art. 6 bases.\n"}}},"example":{"purposes":["marketing","analytics"]}}}},"responses":{"200":{"description":"Provenance amended.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"profile_id":{"type":"string","format":"uuid"},"key":{"type":"string"},"purposes":{"type":"array","items":{"type":"string"}}}}}}]},"example":{"status":"ok","message":"attribute purposes amended","data":{"profile_id":"550e8400-e29b-41d4-a716-446655440000","key":"revenue_ltv","purposes":["marketing","analytics"]}}}}},"400":{"description":"Invalid id/body, unknown or inactive purpose, or (enforce/strict) no overlap with the schema's attribute tags.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Profile or attribute not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/profiles/{profile_id}/summary":{"get":{"summary":"LLM-generated profile brief","description":"Returns a short (2–4 sentence) operator-facing summary of the profile,\ngenerated by the configured LLM from the profile's attributes, recent\nevents (≤50), and behavioural signal scores.\n\nThe same privacy three-gate filter as the profile read path applies, and\non top of it an **external-LLM PII cap** (default 0):\nattributes more sensitive than the cap are never sent to the third-party\nprovider, regardless of the caller's PII access level. Each call is\naudit-logged with the `llm_summary` operation. Returns 503 when\nLLM features are disabled on the instance.\n","operationId":"summarizeProfile","tags":["AI"],"parameters":[{"name":"profile_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"include_signals","in":"query","description":"Include signal scores in the summary input (default true; set `false` to skip).","schema":{"type":"boolean","default":true}},{"name":"purpose","in":"query","description":"Processing purpose for the privacy gates (or via `X-Purpose` header).","schema":{"type":"string"}}],"responses":{"200":{"description":"Summary generated.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"profile_id":{"type":"string","format":"uuid"},"summary":{"type":"string"},"based_on":{"type":"object","properties":{"attributes":{"type":"integer"},"events":{"type":"integer"},"signals":{"type":"integer"}}}}}}}]}}}},"400":{"description":"Invalid profile_id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"$ref":"#/components/responses/AIDelegationForbidden"},"404":{"description":"Profile not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"$ref":"#/components/responses/AIRateLimited"},"502":{"description":"LLM request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"LLM features are disabled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/segments/translate":{"post":{"summary":"Translate natural language into a segment filter","description":"Converts a plain-English audience description into a validated\nquery-builder filter for the given entity type, using the configured LLM.\n\nThe model emits filter JSON only; it is validated by the same logic as\n`GET /profiles?filter=` (with one automatic retry feeding the validation\nerrors back). An unknown or unauthorized field yields **422** and never\nreaches the database. With `\"execute\": true` the filter is also run: a\ncapped sample (≤100) of matching profile IDs is returned in\n`matched_ids`/`matched_count`, and `total_count` carries the true\nnumber of matching profiles. Returns 503 when\nLLM features are disabled on the instance.\n","operationId":"translateSegment","tags":["AI"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["entity_type","prompt"],"properties":{"entity_type":{"type":"string","example":"customer"},"prompt":{"type":"string","example":"German customers who purchased in the last 30 days with churn risk over 0.7"},"execute":{"type":"boolean","default":false}}}}}},"responses":{"200":{"description":"Filter generated (and executed when requested).","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"filter":{"type":"object","description":"A querybuilder.Filter tree (combinator + rules)."},"valid":{"type":"boolean"},"executed":{"type":"boolean"},"matched_ids":{"type":"array","items":{"type":"string","format":"uuid"}},"matched_count":{"type":"integer","description":"Length of the matched_ids sample (at most 100). Not the audience size; see total_count."},"total_count":{"type":"integer","format":"int64","description":"Number of profiles the filter matches. Present whenever executed is true (0 when nothing matches)."},"sample_capped":{"type":"boolean","description":"True when total_count exceeds the returned matched_ids sample (the sample is capped at 100)."}}}}}]}}}},"400":{"description":"Invalid request or unknown entity type.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"$ref":"#/components/responses/ManifestForbidden"},"422":{"description":"The LLM could not produce a valid filter (after one retry).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"$ref":"#/components/responses/AIRateLimited"},"502":{"description":"LLM request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"LLM features are disabled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/profiles/{profile_id}/events":{"get":{"summary":"Get events for a profile (live or point-in-time)","description":"Returns events belonging to a profile, newest first. Accepts `?at=` for\npoint-in-time reconstruction from `h_events`.\n\n`from`/`to` bound the event timestamp (inclusive) and are worth using\non long-lived profiles: the page size is clamped to 100, so an\nunbounded read of a busy profile spends the whole page on history the\ncaller may not care about.\n","operationId":"getProfileEventsByID","tags":["Profiles"],"parameters":[{"name":"profile_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"at","in":"query","description":"Reconstruct events at this timestamp.","schema":{"type":"string","format":"date-time"}},{"name":"event_type","in":"query","description":"Only events of this type.","schema":{"type":"string"}},{"name":"from","in":"query","description":"Inclusive lower timestamp bound (RFC3339 or datetime-local). Ignored with `at`.","schema":{"type":"string"}},{"name":"to","in":"query","description":"Inclusive upper timestamp bound (RFC3339 or datetime-local). Ignored with `at`.","schema":{"type":"string"}},{"name":"include_attributes","in":"query","schema":{"type":"boolean","default":false}},{"name":"page","in":"query","description":"Zero-based page index. Ignored with `at` (a point-in-time read returns the whole reconstructed timeline).","schema":{"type":"integer","minimum":0}},{"name":"size","in":"query","description":"Rows per page. Defaults to 100; maximum is 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":100}},{"name":"sort_by","in":"query","description":"Defaults to `timestamp` — unlike `GET /events`, an unsorted read here is newest first.","schema":{"type":"string","enum":["timestamp","event_type","created_at"]}},{"name":"sort_dir","in":"query","description":"Defaults to `desc` when `sort_by` is omitted.","schema":{"type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"Events for the profile, with page metadata (`page`) on live reads.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/EventObject"}},"page":{"$ref":"#/components/schemas/PageMeta"}}}]}}}},"400":{"description":"Invalid profile_id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Profile not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/profiles/{profile_id}/history":{"get":{"summary":"Profile audit trail","description":"Returns a time-ordered, diff-style audit trail of all recorded changes for\na profile across all h_* history tables.\n\nFilterable by `scope` (which table), `key` (attribute/identifier key),\n`action` (insert/update/delete), and time range (`from`/`to`).\nPaginated using opaque cursor tokens.\n","operationId":"getProfileHistory","tags":["Profiles"],"parameters":[{"name":"profile_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"from","in":"query","description":"Start of the time window (ISO 8601).","schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","description":"End of the time window (ISO 8601).","schema":{"type":"string","format":"date-time"}},{"name":"scope","in":"query","description":"Filter to a single history table.","schema":{"type":"string","enum":["profile","attributes","identifiers","links","consents"]}},{"name":"key","in":"query","description":"Filter to a specific attribute/identifier/purpose key.","schema":{"type":"string"}},{"name":"action","in":"query","description":"Filter to insert, update, or delete actions only.","schema":{"type":"string","enum":["insert","update","delete"]}},{"name":"page_size","in":"query","description":"Entries per page (1–500). Defaults to 100.","schema":{"type":"integer","minimum":1,"maximum":500,"default":100}},{"name":"cursor","in":"query","description":"Opaque pagination cursor from a previous response.","schema":{"type":"string"}},{"name":"order","in":"query","description":"Timestamp ordering of the trail (default asc).","schema":{"type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"Audit trail entries.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/HistoryResponse"}}}]}}}},"400":{"description":"Invalid profile_id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Profile not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/events/feed":{"post":{"summary":"Read one event type in ingest order","description":"One page of the events of one `event_type`, ordered by the time the\nplatform ingested them, for a consumer that sweeps new events. The first\ncall has no `cursor` and starts at `start_at` (default: the beginning of\nhistory, never before 1970-01-01); each response carries the opaque\n`next_cursor` to send next. `limit` is 1 to 1000 (default 500).\n\nThe feed stops 2 minutes behind the clock (`FeedSettle`): only events\ningested at least that long ago are returned, so an event cannot land\nbehind the cursor. Delivery is **at least once**: the ingest time is re-stamped\non some event updates, so an event can come back in a\nlater page. Consumers de-duplicate on the event id. A cursor that does\nnot decode, carries a time before 1970 or one more than a minute ahead\nof the clock is refused (`400 invalid cursor`). Events are gated like\n`GET /events`, with the same privacy audit rows. Events written before\ningest times were recorded are served only to a feed that starts from the\nbeginning of history.\n","operationId":"getEventsFeed","tags":["Events"],"parameters":[{"$ref":"#/components/parameters/PurposeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventsFeedRequest"}}}},"responses":{"200":{"description":"A page of events and the next cursor.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/EventsFeedResponse"}}}]}}}},"400":{"description":"Invalid JSON, missing `event_type`, `limit` outside 1-1000, `invalid cursor` (undecodable, a time before 1970, or ahead of the clock), or `start_at` before 1970-01-01.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The caller is not authorized for the `X-Purpose` purpose (`caller not authorized for purpose`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Event-type schema read failed, so the privacy gates could not be enforced.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/events/count":{"get":{"summary":"Count events matching a filter","description":"Exact count over the same filter grammar as the events list\n(profile_id/event_type/source/from/to + attr_filters). Exists so\ncallers needing counts over large windows — campaign frequency caps,\nfatigue policies — don't page results through the 100-row clamp.\nAt least one filter is required.\n","operationId":"countEvents","tags":["Events"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"profile_id","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"event_type","in":"query","schema":{"type":"string"}},{"name":"source","in":"query","schema":{"type":"string"}},{"name":"from","in":"query","schema":{"type":"string"},"description":"RFC3339 lower bound (inclusive)."},{"name":"to","in":"query","schema":{"type":"string"},"description":"RFC3339 upper bound (inclusive)."},{"name":"attr_filters","in":"query","schema":{"type":"string"},"description":"JSON-encoded array of EventAttrRule objects; requires event_type."},{"$ref":"#/components/parameters/PurposeHeader"}],"responses":{"200":{"description":"The count.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"count":{"type":"integer","format":"int64"}}}}}]}}}},"400":{"description":"No filter given, or invalid parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"$ref":"#/components/responses/ManifestForbidden"}}},"post":{"summary":"Count events for several filter sets at once","description":"Batched form of the GET above: one shared scope\n(`profile_id`/`event_type`/`source`) plus N filter sets, answered in a\nsingle pass over the events table. Counts are returned in **request\norder** — zip them against the queries you sent.\n\nUse it wherever several counts are needed about the same profile and\nevent type: a campaign's per-offer frequency caps, fatigue policies,\nthe steps of a funnel. Asked one at a time each is a round trip and its\nown scan.\n\nEach query owns its `from`/`to`, so a batch may mix windows of\ndifferent lengths. `attr_filters` follows the same grammar as the GET\nand requires `event_type` on the shared scope. Maximum 100 queries per\nrequest. If the shared scope is empty, every query must narrow on its\nown — an unfiltered full-table count is rejected.\n","operationId":"countEventsBatch","tags":["Events"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/PurposeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["queries"],"properties":{"profile_id":{"type":"string","format":"uuid"},"profile_ids":{"type":"array","maxItems":500,"items":{"type":"string","format":"uuid"},"description":"Ask the same queries about MANY profiles, answered per profile in `counts_by_profile` instead of `counts`. Mutually exclusive with `profile_id` (sending both is a 400). One grouped pass replaces one request per profile, which is what a caller walking a sample of profiles down the same gates otherwise pays.\n"},"event_type":{"type":"string","example":"campaign_touch"},"source":{"type":"string"},"queries":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"object","properties":{"from":{"type":"string","description":"RFC3339 lower bound (inclusive)."},"to":{"type":"string","description":"RFC3339 upper bound (inclusive)."},"attr_filters":{"type":"array","items":{"$ref":"#/components/schemas/EventAttrRule"}}}}}}},"example":{"profile_id":"8a1f0c22-7d64-4e11-9a0b-2c3d4e5f6a7b","event_type":"campaign_touch","queries":[{"from":"2026-07-06T00:00:00Z","attr_filters":[{"key":"action","operator":"=","value":"queued"},{"key":"campaign_id","operator":"=","value":"3f2a1b00-0000-0000-0000-000000000001"}]},{"from":"2026-07-06T00:00:00Z","attr_filters":[{"key":"action","operator":"=","value":"control_group"},{"key":"campaign_id","operator":"=","value":"3f2a1b00-0000-0000-0000-000000000001"}]}]}}}},"responses":{"200":{"description":"One count per query, in request order (`counts`) — or, for the `profile_ids` form, profile id to counts in that same order (`counts_by_profile`). A profile with no matching events is ABSENT from `counts_by_profile` rather than present with zeros; the caller knows which ids it asked about. Callers that prefetch must treat absence as \"not answered\" and read that profile live, never as a count of zero.\n","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"counts":{"type":"array","items":{"type":"integer","format":"int64"}},"counts_by_profile":{"type":"object","additionalProperties":{"type":"array","items":{"type":"integer","format":"int64"}}}}}}}]},"example":{"status":"OK","message":"counted events","data":{"counts":[7,2]}}}}},"400":{"description":"No queries, too many queries, more than 500 profiles, both profile_id and profile_ids, an unfiltered query, or invalid parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"$ref":"#/components/responses/ManifestForbidden"}}}},"/cdp/api/v1/events":{"get":{"summary":"List events","description":"Returns events, optionally filtered by profile id and/or event type.\nPass `include_attributes=true` to hydrate EAV attributes for each event.\nResults are ordered by timestamp descending by default.\n","operationId":"getEvents","tags":["Events"],"parameters":[{"name":"profile_id","in":"query","description":"Filter events belonging to this profile.","schema":{"type":"string","format":"uuid"}},{"name":"event_type","in":"query","description":"Filter events of this type.","schema":{"type":"string"},"example":"purchase"},{"name":"source","in":"query","description":"Filter events with this exact source.","schema":{"type":"string"}},{"name":"from","in":"query","description":"Inclusive lower timestamp bound (RFC3339 or datetime-local, UTC).","schema":{"type":"string"}},{"name":"to","in":"query","description":"Inclusive upper timestamp bound (RFC3339 or datetime-local, UTC).","schema":{"type":"string"}},{"name":"attr_filters","in":"query","description":"JSON-encoded array of EventAttrRule objects (simplified attribute\nfilter, AND-combined). Requires event_type.\n","schema":{"type":"string"},"example":"[{\"key\":\"amount\",\"operator\":\">\",\"value\":100}]"},{"name":"include_attributes","in":"query","description":"When true, hydrates EAV attributes for each returned event.","schema":{"type":"boolean","default":false}},{"name":"page","in":"query","schema":{"type":"integer","minimum":0}},{"name":"size","in":"query","description":"Rows per page. Defaults to 100; maximum is 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":100}},{"name":"sort_by","in":"query","schema":{"type":"string","enum":["timestamp","event_type","created_at"]}},{"name":"sort_dir","in":"query","description":"Defaults to `desc` with `sort_by=timestamp` when neither is given, so the newest events come first.\n","schema":{"type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"List of events.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/EventObject"}}}}]},"example":{"status":"ok","message":"fetched events","data":[{"id":"7f3e9100-a1bc-43d5-c938-668877662222","profile_id":"550e8400-e29b-41d4-a716-446655440000","event_type":"purchase","timestamp":"2024-06-01T14:22:00Z","source":"web-storefront","attributes":{"order_id":"ORD-9982","amount":149.99,"item_count":3}}]}}}},"400":{"description":"Invalid query parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"$ref":"#/components/responses/ManifestForbidden"},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/events/add":{"post":{"summary":"Ingest events","description":"Bulk-ingests events. Each event's attributes are typed against the event\ntype's declared schema when available (falling back to JSON-type inference).\nEvents and their attributes are written through at-least-once\nbatching — the response confirms acceptance, not durable write.\n","operationId":"createEvents","tags":["Events"],"parameters":[{"$ref":"#/components/parameters/PurposeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateEventsRequest"},"example":{"events":[{"profile_id":"550e8400-e29b-41d4-a716-446655440000","event_type":"purchase","timestamp":"2024-06-01T14:22:00Z","source":"web-storefront","attributes":{"order_id":"ORD-9982","amount":149.99,"item_count":3,"currency":"USD"}},{"profile_id":"550e8400-e29b-41d4-a716-446655440000","event_type":"page_view","source":"web-storefront","attributes":{"url":"/products/widget","referrer":"google"}}]}}}},"responses":{"200":{"description":"Events accepted for insertion. Returns assigned event ids. With\nthe collection gate switched on the data becomes an object\n`{ids, dropped, quarantined}` — dropped events were lawfully\nrefused (required consent withdrawn; audited, never an error),\nquarantined events await the missing consent in a holding queue\nand are stored with their original\ntimestamp once it arrives.\n","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"oneOf":[{"type":"array","items":{"type":"string","format":"uuid"}},{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string","format":"uuid"}},"dropped":{"type":"integer"},"quarantined":{"type":"integer"}}}]}}}]},"example":{"status":"ok","message":"events created","data":["7f3e9100-a1bc-43d5-c938-668877662222","8a4f0211-b2cd-54e6-d049-779988773333"]}}}},"400":{"description":"Invalid payload or attribute type mismatch — or, in\n`enforce`/`strict` privacy modes, a purpose collection violation\n(schema-tagged attribute with no overlap with the declared\n`X-Purpose` set): `data.violations[]` carries\n`{attribute, attribute_purposes, declared_purposes}`.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"The tenant has reached its daily event quota: \"daily event quota\nreached\". `Retry-After` gives the seconds until the next UTC\nmidnight. The whole batch is refused, except a batch made only of\n`campaign_touch` events from the Campaign service key, which is\nstill counted toward usage.\n","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Events cannot be accepted right now because a dependency is temporarily unavailable; retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/events/update":{"post":{"summary":"Update events","description":"Partially updates existing events: the mutable `source`, their\n`attributes`, and/or `remove_attributes`. Each event's identity (profile,\ntype, timestamp) is immutable. Attributes are upserted/merged (omitted\nkeys keep their stored values) into the event_attributes\nReplacingMergeTree; `remove_attributes` deletes the listed keys. Strict-mode\nand data-contract validation apply as on ingestion (a `required` attribute\ncannot be removed). Every change is recorded in `h_events` /\n`h_event_attributes` (insert/update/delete). At least one of\n`source`/`attributes`/`remove_attributes` must be set per event. Note:\nthis operation is asynchronous.\n","operationId":"updateEvents","tags":["Events"],"parameters":[{"$ref":"#/components/parameters/PurposeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateEventsRequest"},"example":{"events":[{"id":"7f3e9100-a1bc-43d5-c938-668877662222","source":"backfill-job","attributes":{"amount":249.99,"currency":"USD"},"remove_attributes":["coupon"]}]}}}},"responses":{"200":{"description":"Events updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"},"example":{"status":"ok","message":"events updated"}}}},"400":{"description":"Invalid payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"One of the referenced events does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/events/remove":{"delete":{"summary":"Remove events","description":"Deletes events and their attributes by id. Note: this operation is asynchronous.\n","operationId":"removeEvents","tags":["Events"],"parameters":[{"$ref":"#/components/parameters/PurposeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RemoveEventsRequest"},"example":{"ids":["7f3e9100-a1bc-43d5-c938-668877662222"]}}}},"responses":{"200":{"description":"Events removed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"},"example":{"status":"ok","message":"events removed"}}}},"400":{"description":"Invalid payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/events/remove-by-filter":{"delete":{"summary":"Remove events by filter","description":"Deletes every event matching the filter (profile, type, source, time\nrange). At least one condition is required. Returns the number of\ndeleted events.\n\n**Deferred since 2026-08-17 (BREAKING).** Answers 202 with\n`{request_id, scheduled_at, matched}` and runs after\n`bulk_delete_delay_sec`, cancellable until then via\n`DELETE /cdp/api/v1/deletion-requests/{id}`. `?immediate=true`\nrestores the inline 200.\n","operationId":"removeEventsByFilter","tags":["Events"],"parameters":[{"name":"dry_run","in":"query","schema":{"type":"boolean"},"description":"true = return the exact would-be count without deleting: {matched, dry_run}."},{"$ref":"#/components/parameters/PurposeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventFilterBody"}}}},"responses":{"200":{"description":"Events removed (`data.deleted` holds the count), or nothing matched (`{matched: 0, deleted: 0}`; nothing is scheduled).\n","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BulkDeleteResult"}}}]}}}},"400":{"description":"Invalid payload or empty filter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"$ref":"#/components/responses/ManifestForbidden"},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/events/export":{"post":{"summary":"Export events as CSV","description":"Streams a CSV of every event matching the filter, with base columns\nplus the selected attribute keys. Attribute values pass the same\nprivacy gates as `GET /events`. Each exported event is audit-logged.\n","operationId":"exportEvents","tags":["Events"],"parameters":[{"$ref":"#/components/parameters/PurposeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExportEventsRequest"}}}},"responses":{"200":{"description":"CSV file (attachment).","content":{"text/csv":{"schema":{"type":"string"}}}},"400":{"description":"Invalid payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"$ref":"#/components/responses/ManifestForbidden"},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/events/{event_id}":{"get":{"summary":"Get single event (live or point-in-time)","description":"Returns a single event by id. Accepts `?at=` for point-in-time\nreconstruction from `h_events` / `h_event_attributes`.\n","operationId":"getEventByID","tags":["Events"],"parameters":[{"name":"event_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"at","in":"query","description":"ISO 8601 timestamp. When supplied the event is reconstructed from history at that point in time.\n","schema":{"type":"string","format":"date-time"}},{"name":"include_attributes","in":"query","schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"Event found (live or reconstructed).","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/EventObject"}}}]}}}},"400":{"description":"event_id is not a UUID.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Event not found (or did not exist at the requested time).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/events/{event_id}/attributes/{key}/purposes":{"patch":{"tags":["Events"],"summary":"Amend an event attribute's collection-purpose provenance","operationId":"amendEventAttributePurposes","description":"Replaces the stored collection-purpose provenance of one event\nattribute without touching its value (the row is re-emitted as a new\nversion; an `h_event_attributes` update entry records the change and\nthe audit log records operation `amend_purposes`). An empty `purposes`\nlist resets the attribute to legacy/undeclared provenance. Every named\npurpose must be an active catalog purpose (400 otherwise); in\n`enforce`/`strict` privacy modes a schema-tagged attribute additionally\nrequires overlap with the event type's `attribute_purposes` tags\n(structured 400 with `data.violations[]`).\n","parameters":[{"name":"event_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"key","in":"path","required":true,"schema":{"type":"string"},"description":"Attribute key."},{"$ref":"#/components/parameters/PurposeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"purposes":{"type":"array","items":{"type":"string"},"description":"New provenance set (empty = reset to legacy)."},"collection_basis":{"type":"string","description":"Optional correction of the stored lawful basis. Omitted =\nderive from the new purposes' own bases; empty string =\nreset to legacy; otherwise one of the six Art. 6 bases.\n"}}},"example":{"purposes":["marketing","analytics"]}}}},"responses":{"200":{"description":"Provenance amended.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"event_id":{"type":"string","format":"uuid"},"key":{"type":"string"},"purposes":{"type":"array","items":{"type":"string"}}}}}}]},"example":{"status":"ok","message":"attribute purposes amended","data":{"event_id":"550e8400-e29b-41d4-a716-446655440000","key":"item","purposes":["marketing","analytics"]}}}}},"400":{"description":"Invalid id/body, unknown or inactive purpose, or (enforce/strict) no overlap with the event type's attribute tags.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Event or attribute not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/events/{event_id}/history":{"get":{"summary":"Event audit trail","description":"Returns a time-ordered audit trail for a single event across\n`h_events` and `h_event_attributes`.\n","operationId":"getEventHistory","tags":["Events"],"parameters":[{"name":"event_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"from","in":"query","description":"Start of the time window (ISO 8601).","schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","description":"End of the time window (ISO 8601).","schema":{"type":"string","format":"date-time"}},{"name":"scope","in":"query","description":"Filter to event-level changes or attribute changes.","schema":{"type":"string","enum":["profile","attributes"]}},{"name":"key","in":"query","description":"Filter to a specific attribute key.","schema":{"type":"string"}},{"name":"action","in":"query","schema":{"type":"string","enum":["insert","update","delete"]}},{"name":"page_size","in":"query","schema":{"type":"integer","minimum":1,"maximum":500,"default":100}},{"name":"cursor","in":"query","description":"Opaque pagination cursor from a previous response.","schema":{"type":"string"}},{"name":"order","in":"query","description":"Timestamp ordering of the trail (default asc).","schema":{"type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"Audit trail entries.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/HistoryResponse"}}}]}}}},"400":{"description":"event_id is not a UUID.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Event not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/computed-attributes":{"get":{"summary":"List computed attributes","description":"Returns computed-attribute definitions, optionally filtered to a single\nentity type and/or name. Results are paginated and sortable.\n","operationId":"getComputedAttributes","tags":["Computed Attributes"],"parameters":[{"name":"entity_type","in":"query","description":"Filter to a single entity type.","schema":{"type":"string"},"example":"customer"},{"name":"name","in":"query","description":"Filter to a single attribute name.","schema":{"type":"string"},"example":"services_segment"},{"name":"page","in":"query","schema":{"type":"integer","minimum":0}},{"name":"size","in":"query","description":"Rows per page. Defaults to 100; maximum is 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":100}},{"name":"sort_by","in":"query","schema":{"type":"string","enum":["entity_type","name","kind","created_at","updated_at"]}},{"name":"sort_dir","in":"query","schema":{"type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"List of computed-attribute definitions.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ComputedAttributeObject"}}}}]},"example":{"status":"ok","message":"fetched computed attributes","data":[{"id":"9a1b2c3d-0000-0000-0000-000000000000","entity_type":"customer","name":"services_segment","kind":"segmentation","value_type":"string","enabled":true,"definition":{"default_segment":"mixed","segments":[{"name":"fix_only","condition":{"logic":"and","conditions":[{"source":"aggregate","operator":"gte","value":1,"aggregate":{"function":"count","over":"related_profiles","relation":"children","child_entity_type":"service","where":{"logic":"and","conditions":[{"source":"attribute","attribute":"service_type","operator":"eq","value":"fixed"},{"source":"attribute","attribute":"status","operator":"eq","value":"active"}]}}},{"source":"aggregate","operator":"eq","value":0,"aggregate":{"function":"count","over":"related_profiles","relation":"children","child_entity_type":"service","where":{"logic":"and","conditions":[{"source":"attribute","attribute":"service_type","operator":"eq","value":"mobile"},{"source":"attribute","attribute":"status","operator":"eq","value":"active"}]}}}]}}]}}]}}}},"400":{"description":"Invalid query parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/computed-attributes/add":{"post":{"summary":"Create computed attribute","description":"Creates a new computed-attribute definition. The definition is validated\n(translated to SQL) before storage. Returns 400 on an invalid definition\nor when one with the same `(entity_type, name)` already exists. A name\nthat is declared as a contact attribute (`/privacy/contact-attributes`)\nis refused with 400 `data.code = computed_attribute_is_contact` and\n`data.attribute`: a send would read the computed value, which erasure\nnever hashes into a suppression.\n","operationId":"createComputedAttribute","tags":["Computed Attributes"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputedAttributeObject"},"example":{"entity_type":"customer","name":"avg_order_value","description":"Average purchase amount","kind":"function","value_type":"decimal","definition":{"expression":{"type":"binary","operator":"/","left":{"type":"aggregate","aggregate":{"function":"sum","over":"events","event_type":"purchase","attribute":"amount"}},"right":{"type":"aggregate","aggregate":{"function":"count","over":"events","event_type":"purchase"}}}}}}}},"responses":{"200":{"description":"Computed attribute created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"},"example":{"status":"ok","message":"computed attribute created"}}}},"400":{"description":"Invalid payload/definition or duplicate attribute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/computed-attributes/update":{"post":{"summary":"Update computed attribute","description":"Updates an existing computed-attribute definition, matched by\n`(entity_type, name)`. Returns 400 on an invalid definition or when no\nmatching attribute exists. This operation is asynchronous.\n","operationId":"updateComputedAttribute","tags":["Computed Attributes"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputedAttributeObject"},"example":{"entity_type":"customer","name":"avg_order_value","kind":"function","enabled":false,"definition":{"expression":{"type":"aggregate","aggregate":{"function":"avg","over":"events","event_type":"purchase","attribute":"amount"}}}}}}},"responses":{"200":{"description":"Computed attribute updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"},"example":{"status":"ok","message":"computed attribute updated"}}}},"400":{"description":"Invalid payload/definition or attribute not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/computed-attributes/remove":{"delete":{"summary":"Remove computed attribute","description":"Deletes a single computed-attribute definition by `(entity_type, name)`.\nReturns 400 when it does not exist. This operation is asynchronous.\n","operationId":"removeComputedAttribute","tags":["Computed Attributes"],"parameters":[{"name":"entity_type","in":"query","required":true,"schema":{"type":"string"},"example":"customer"},{"name":"name","in":"query","required":true,"schema":{"type":"string"},"example":"avg_order_value"}],"responses":{"200":{"description":"Computed attribute removed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"},"example":{"status":"ok","message":"computed attribute removed"}}}},"400":{"description":"Missing query parameter or attribute not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/contracts":{"get":{"summary":"List data contracts","description":"Returns all data contracts, optionally filtered by `scope` and/or `scope_name`.\n","operationId":"getContracts","tags":["Data Contracts"],"parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["entity","event_type"]},"description":"Filter by scope."},{"name":"scope_name","in":"query","schema":{"type":"string"},"description":"Filter by scope name.","example":"customer"}],"responses":{"200":{"description":"List of contracts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"},"example":{"status":"ok","message":"fetched contracts","data":[{"scope":"entity","scope_name":"customer","rules":{"email":{"required":true,"format":"^[^@]+@[^@]+$"}},"on_unknown_attribute":"allow","on_type_mismatch":"coerce","on_missing_required":"reject","enabled":true}]}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create data contract","description":"Creates a new data contract. Returns 400 if a contract already exists for\nthe given `(scope, scope_name)` pair. expr expressions in `validate_expr`\nand `transform_expr` are compiled at creation time and an error is returned\nif they are invalid, nest predicate functions more than 2 deep, or use a\nliteral range spanning 1000+ elements; a `format` regex over 1024 bytes\nis rejected likewise.\n","operationId":"createContract","tags":["Data Contracts"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataContractObject"},"example":{"scope":"entity","scope_name":"customer","rules":{"email":{"required":true,"format":"^[^@]+@[^@]+$"},"age":{"min":0,"max":150}},"on_unknown_attribute":"allow","on_type_mismatch":"coerce","on_missing_required":"reject","enabled":true}}}},"responses":{"200":{"description":"Contract created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"},"example":{"status":"ok","message":"contract created"}}}},"400":{"description":"Invalid payload, expr compile error, contract already exists, or the entity or event type must exist (the schema cache can lag a fresh type by about 5 s).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/contracts/{scope}/{scope_name}":{"get":{"summary":"Get a data contract","description":"Returns the contract for the given `(scope, scope_name)` pair.","operationId":"getContract","tags":["Data Contracts"],"parameters":[{"name":"scope","in":"path","required":true,"schema":{"type":"string","enum":["entity","event_type"]},"example":"entity"},{"name":"scope_name","in":"path","required":true,"schema":{"type":"string"},"example":"customer"}],"responses":{"200":{"description":"Contract found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"404":{"description":"Contract not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"put":{"summary":"Replace a data contract","description":"Replaces the full rules of an existing contract. Returns 404 if not found.\nexpr expressions are re-compiled and an error is returned for invalid ones.\nThe cached contract is invalidated immediately so the next ingestion\nrequest picks up the new rules.\n","operationId":"updateContract","tags":["Data Contracts"],"parameters":[{"name":"scope","in":"path","required":true,"schema":{"type":"string","enum":["entity","event_type"]},"example":"entity"},{"name":"scope_name","in":"path","required":true,"schema":{"type":"string"},"example":"customer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataContractObject"}}}},"responses":{"200":{"description":"Contract updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"},"example":{"status":"ok","message":"contract updated"}}}},"400":{"description":"Invalid payload, expr compile error, or the entity or event type must exist (the schema cache can lag a fresh type by about 5 s).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Contract not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"summary":"Delete a data contract","description":"Deletes a contract. Returns 404 if not found. The cached contract is\ninvalidated immediately.\n","operationId":"deleteContract","tags":["Data Contracts"],"parameters":[{"name":"scope","in":"path","required":true,"schema":{"type":"string","enum":["entity","event_type"]},"example":"entity"},{"name":"scope_name","in":"path","required":true,"schema":{"type":"string"},"example":"customer"}],"responses":{"200":{"description":"Contract deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"},"example":{"status":"ok","message":"contract deleted"}}}},"404":{"description":"Contract not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/auth/login":{"post":{"tags":["Auth"],"summary":"Login with email and password","description":"Returns opaque access and refresh session tokens on successful authentication. `password_change_required: true` means the session is restricted until POST /cdp/auth/users/me/password succeeds.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoginRequest"}}}},"responses":{"200":{"description":"Login successful.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/LoginResponse"}}}]}}}},"401":{"description":"Invalid credentials, account disabled, or account locked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/auth/logout":{"post":{"tags":["Auth"],"summary":"Logout — revoke session tokens","description":"Deletes the refresh token (immediate revocation). If an\n`Authorization: Bearer <token>` header is also present the access token\nis deleted too. No authentication is required — the token is\nthe credential.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["refresh_token"],"properties":{"refresh_token":{"type":"string","description":"The refresh token issued at login."}}}}}},"responses":{"200":{"description":"Logged out successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"400":{"description":"Missing or malformed request body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/auth/refresh":{"post":{"tags":["Auth"],"summary":"Refresh session tokens","description":"Issues new access and refresh tokens using a valid refresh token. The old refresh token is deleted (rotation).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["refresh_token"],"properties":{"refresh_token":{"type":"string"}}}}}},"responses":{"200":{"description":"Tokens refreshed.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/LoginResponse"}}}]}}}},"401":{"description":"Invalid or expired refresh token."}}}},"/cdp/auth/register":{"post":{"tags":["Auth"],"summary":"Self-register a new user account","description":"Creates a new user account with status `pending`. An email verification\nmessage is queued for delivery by email. The account cannot log in until the email is verified.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email","password","first_name","last_name"],"properties":{"email":{"type":"string","format":"email"},"password":{"type":"string","minLength":8,"description":"8 characters to 72 bytes (UTF-8); bcrypt reads no further."},"first_name":{"type":"string"},"last_name":{"type":"string"},"organization":{"type":"string"},"org_unit":{"type":"string"},"org_role":{"type":"string"},"display_name":{"type":"string"}}}}}},"responses":{"201":{"description":"Registration successful. Verification email dispatched.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"400":{"description":"Invalid request body or validation failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Email address already registered.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/auth/verify-email":{"post":{"tags":["Auth"],"summary":"Verify email address","description":"Activates a `pending` account using the token received by email.\nThe token is single-use and expires after 24 hours.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["token"],"properties":{"token":{"type":"string","description":"Email verification token (64-char hex string)."}}}}}},"responses":{"200":{"description":"Email verified, account is now active.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"400":{"description":"Invalid, expired, or already-used token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/auth/password-reset/request":{"post":{"tags":["Auth"],"summary":"Request a password reset","description":"Dispatches a password reset token to the given email address by\nemail. Always returns 200 to avoid leaking whether an email\nis registered. Token expires after 1 hour.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email"}}}}}},"responses":{"200":{"description":"Reset email dispatched (or silently ignored for unknown addresses).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"400":{"description":"Invalid email format.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/auth/password-reset/confirm":{"post":{"tags":["Auth"],"summary":"Confirm password reset","description":"Sets a new password using the token received by email.\nThe token is single-use and expires after 1 hour. An account locked\nby the failed-login auto-lock is unlocked on a successful reset; an\naccount locked by an administrator (`POST /users/lock`) stays\nlocked — a self-service reset never lifts an admin lock.\nNo reset token is issued at all while an admin lock is active,\nalthough the request endpoint still answers 200.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["token","password"],"properties":{"token":{"type":"string","description":"Password reset token (64-char hex string)."},"password":{"type":"string","minLength":8,"description":"New password, 8 characters to 72 bytes (UTF-8)."}}}}}},"responses":{"200":{"description":"Password updated successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"400":{"description":"Invalid/expired token, invalid request, or password too short.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/roles":{"get":{"tags":["Roles"],"summary":"List roles with their permissions","description":"Returns the roles visible in the caller's scope with their permission grants: the global catalog plus the custom roles of the account owning the RESOLVED tenant. Built-ins are listed first, then the account's customs alphabetically. Instance administrators (and root keys) may widen the view with `?account=`.\n","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"name":"account","in":"query","required":false,"schema":{"type":"string"},"description":"Instance administrators only: an account id to view that account's catalog, or `*` for every account's custom roles. Anyone else passing an account other than their own gets 403.\n"}],"responses":{"200":{"description":"List of roles.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/RoleResponse"}}}}]}}}}}},"post":{"tags":["Roles"],"summary":"Create a role","description":"Creates a new role and (optionally) its permission grants. The role is usable immediately; on a deployment with several API servers the others pick it up within the policy-reload interval.\n\nDefining roles is an ACCOUNT-level right: an account administrator creates custom roles in their own account (derived from the resolved tenant), and an instance administrator (or root key) may create global roles or any account's customs via `account_id`. A tenant administrator gets 403.\n","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateRoleRequest"}}}},"responses":{"201":{"description":"Role created.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RoleResponse"}}}]}}}},"400":{"description":"Validation error (missing/invalid name, reserved name, invalid permission or account id)."},"403":{"description":"Not permitted to define roles in this scope (a tenant administrator, or an account administrator naming another account).\n"},"404":{"description":"The requested account does not exist."},"409":{"description":"A role with that name already exists in the scope, or the custom role would shadow a global role's name.\n"}}}},"/cdp/api/v1/roles/available-permissions":{"get":{"tags":["Roles"],"summary":"List grantable route permissions","description":"Admin only. Enumerates the registered API routes (path + HTTP methods) so you know which objects/actions can be granted when creating or editing a role. `suggested_object` is a ready-to-use value for Permission.object. Reflects the live router, so it never drifts from the actual routes.\n","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Available route permissions.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AvailablePermission"}}}}]}}}}}}},"/cdp/api/v1/roles/{name}":{"parameters":[{"name":"name","in":"path","required":true,"schema":{"type":"string"}}],"get":{"tags":["Roles"],"summary":"Get a role and its permissions","description":"Resolved in the caller's scope: the account owning the resolved tenant prefers its OWN custom role over a same-named global. Instance administrators may disambiguate with `?account=`.\n","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"name":"account","in":"query","required":false,"schema":{"type":"string"},"description":"Instance administrators only — resolve the name in this account's scope (`*` = any)."}],"responses":{"200":{"description":"The role.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RoleResponse"}}}]}}}},"404":{"description":"Role not found."}}},"put":{"tags":["Roles"],"summary":"Update a role's description and/or permissions","description":"A non-null `permissions` array replaces the role's entire permission set. System roles can be edited but not deleted; modifying a system role's permissions requires `?force=true`.\n\nScope: an account administrator may edit only their own account's custom roles — built-in/global roles are the instance administrator's alone. A tenant administrator gets 403.\n","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"name":"account","in":"query","required":false,"schema":{"type":"string"},"description":"Instance administrators only — address the role in this account's scope (omitted = the global catalog)."},{"name":"force","in":"query","required":false,"schema":{"type":"boolean"},"description":"Required (true) to modify the permissions of a built-in system role."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateRoleRequest"}}}},"responses":{"200":{"description":"Updated role.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RoleResponse"}}}]}}}},"400":{"description":"Invalid request body."},"403":{"description":"Attempted to modify a system role's permissions without ?force=true, to edit a built-in role without instance administrator privileges, or to edit another account's role.\n"},"404":{"description":"Role not found."}}},"delete":{"tags":["Roles"],"summary":"Delete a role","description":"Removes the role and all its permission grants. Built-in (system) roles cannot be deleted, and a role still held by any tenant member, account member, API key or pending invite is rejected with 409 — there is no force/cascade option, holders must be reassigned first. Same scope rules as PUT: an account administrator addresses only their own account's customs.\n","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"name":"account","in":"query","required":false,"schema":{"type":"string"},"description":"Instance administrators only — address the role in this account's scope (omitted = the global catalog)."}],"responses":{"200":{"description":"Role deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"403":{"description":"Cannot delete a built-in system role, or not permitted to delete roles in this scope.\n"},"404":{"description":"Role not found."},"409":{"description":"The role is still held by at least one tenant member, account member, API key, pending invite or legacy user-role assignment. The response message breaks the count down by source (e.g. \"role is still held by 3 tenant members, 1 API key, 2 pending invites; reassign before deleting\"). Every holder is scoped to the role's own account for an account custom role, or counted instance-wide for a global role. There is no force/cascade option — reassign every holder first, then retry the delete.\n"}}}},"/cdp/auth/tenants":{"get":{"summary":"List my tenant memberships","description":"Multitenancy switcher support: every tenant the session user can reach — explicit memberships plus account-inherited ones (Environments; `role_source` says which, and explicit rows win wholesale) — with the member's roles and an `active` flag for the session's current tenant. Any authenticated user may call this — roles gate what a member can do inside a tenant, not whether they can list or select it. On tenant-scoped API routes a user may also send an `X-Tenant` header per request; it wins when the user is a member of that tenant (two browser tabs on two tenants), 403 otherwise.\n","operationId":"listMyTenants","tags":["Tenants"],"security":[{"BearerAuth":[]}],"responses":{"200":{"description":"`data` is an array of `{tenant_id, name, account_id?, account_name?, environment?, role_source?, roles, account_roles?, active, outbound_mode}` — the switcher groups by account and badges sandboxes.\n","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TenantSwitcherEntry"}}}}]}}}}}}},"/cdp/auth/tenant":{"post":{"summary":"Switch my active tenant","description":"Validates membership, persists the choice to the user's config (survives re-login), and rewrites the session's access blob in place — the token is NOT reissued and other sessions of the user stay valid.\n","operationId":"switchTenant","tags":["Tenants"],"security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["tenant_id"],"properties":{"tenant_id":{"type":"string","pattern":"^[a-z0-9][a-z0-9-]{1,30}$"}}}}}},"responses":{"200":{"description":"`data` is `{tenant_id, roles}` — the new active tenant.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ActiveTenantResponse"}}}]}}}},"403":{"description":"Not a member of the requested tenant."}}}},"/cdp/auth/invites/peek":{"post":{"summary":"Inspect a tenant membership invite without consuming it","description":"Public, non-consuming: unlike accept, peeking never claims the single-use token, so a mail scanner following the emailed link can't burn it before the invitee clicks (same reasoning as the DOI confirm GET). Returns who the invite is for, which tenant/roles it grants, and whether that email already has an account — `has_account` is what the console's `/login/invite` page branches on to show a one-click accept versus an account-creation form. Revealing `has_account` to a token holder is deliberate: the token already arrived in that mailbox. Invalid, expired, and already-used tokens all answer the same uniform 400 as accept — this endpoint is not an invite-existence oracle.\n","operationId":"peekTenantInvite","tags":["Tenants"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["token"],"properties":{"token":{"type":"string"}}}}}},"responses":{"200":{"description":"`data` is `{email, tenant_id, tenant_name, roles, has_account}`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PeekInviteResponse"}}}]}}}},"400":{"description":"Invalid or expired invite (uniform for all token failures)."}}}},"/cdp/auth/invites/accept":{"post":{"summary":"Accept a tenant membership invite","description":"Public, single-use: the invite token is the credential. An existing user gains the invited memberships — `password` is then IGNORED (acceptance is a membership grant, not a password change). An unknown email creates its user account lazily here (password required, min 8 chars, at most 72 bytes) — acceptance proves control of the mailbox, so the account starts active. Validation runs before the single-use claim, so a 400 (e.g. missing password, or one over 72 bytes, which is refused even for an existing account) never burns the token — retry with the same one. Invalid, expired, and already-used tokens all answer one uniform 400.\n","operationId":"acceptTenantInvite","tags":["Tenants"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["token"],"properties":{"token":{"type":"string"},"password":{"type":"string","maxLength":72,"description":"Required when the email has no account yet; ignored for existing accounts. At most 72 bytes (bcrypt)."},"first_name":{"type":"string"},"last_name":{"type":"string"}}}}}},"responses":{"200":{"description":"`data` is `{email, tenant_id, roles}`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AcceptedInviteResponse"}}}]}}}},"400":{"description":"Invalid or expired invite (uniform for all token failures)."}}}},"/cdp/api/v1/tenants/{id}/invites":{"post":{"summary":"Invite an email into a tenant","description":"Creates a single-use, expiring membership invitation (default 7 days) and emails it via the `tenant_invite` template. The 202 response is byte-identical whether or not the email already has a user account — the invite flow is not an existence oracle. Only an administrator of the NAMED tenant may call it: its `admin`, the `account_admin` of the account owning it, `instance_admin`, or root — an administrator of another tenant is refused. `instance_admin`/`account_admin` can never be requested in `roles` — those personas are never grantable through tenant membership.\n","operationId":"createTenantInvite","tags":["Tenants"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9-]{1,30}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email","roles"],"properties":{"email":{"type":"string","format":"email"},"roles":{"type":"array","items":{"type":"string"},"minItems":1,"description":"Roles from the global catalogue the member gets in this tenant."}}}}}},"responses":{"202":{"description":"Invite sent (identical for existing and unknown emails).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"400":{"description":"Invalid tenant id, email, or unknown roles, or `agent_runtime` requested (`agent_runtime is reserved for delegation-enforcing applications`)."},"403":{"description":"Caller does not administer this tenant, or a role in `roles` is instance_admin/account_admin."},"404":{"description":"Tenant not found or not active."}}},"get":{"summary":"List a tenant's pending invites","description":"No token hashes in the response. Requires an administrator of THIS tenant (its admin/account_admin, or instance_admin/root).\n","operationId":"listTenantInvites","tags":["Tenants"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9-]{1,30}$"}}],"responses":{"200":{"description":"`data` is the pending-invite array.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TenantInviteObject"}}}}]}}}},"400":{"description":"Invalid tenant id."},"403":{"description":"Caller does not administer this tenant."}}}},"/cdp/api/v1/tenants/{id}/invites/{invite_id}":{"delete":{"summary":"Revoke a pending tenant invite","description":"Requires an administrator of THIS tenant (its admin/account_admin, or instance_admin/root).\n","operationId":"deleteTenantInvite","tags":["Tenants"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9-]{1,30}$"}},{"name":"invite_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Invite revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"400":{"description":"Invalid tenant id."},"403":{"description":"Caller does not administer this tenant."},"404":{"description":"Invite not found (already accepted/revoked/expired)."}}}},"/cdp/api/v1/tenants/{id}/members":{"get":{"summary":"List a tenant's team","description":"Explicit `tenant_members` rows plus account-inherited members where no explicit row exists (`role_source` distinguishes them). Requires an administrator of THIS tenant (its admin/account_admin, or instance_admin/root).\n","operationId":"listTenantMembers","tags":["Tenants"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9-]{1,30}$"}}],"responses":{"200":{"description":"`data` is the member array.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TenantMemberInfo"}}}}]}}}},"400":{"description":"Invalid tenant id."},"403":{"description":"Caller does not administer this tenant."}}}},"/cdp/api/v1/tenants/{id}/members/{email}":{"put":{"summary":"Replace one member's role set in a tenant","description":"Editing an account-inherited member creates explicit rows, which then win wholesale over the account grant. `instance_admin`/`account_admin` can never be requested — those personas are never grantable through tenant membership. Reserved roles the member already holds (`instance_admin`, `account_admin`) are preserved; they cannot be granted or revoked here. Demoting the tenant's last explicit `admin` answers 409 (instance admins are exempt — they can always repair a tenant). Bumps the member's session epoch (revokes their existing sessions) when they have a user account.\n","operationId":"putTenantMember","tags":["Tenants"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9-]{1,30}$"}},{"name":"email","in":"path","required":true,"schema":{"type":"string","format":"email"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["roles"],"properties":{"roles":{"type":"array","items":{"type":"string"},"minItems":1,"description":"At least one role is required — DELETE removes the member."}}}}}},"responses":{"200":{"description":"Member updated. `data` is `{email, roles}`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"email":{"type":"string","format":"email"},"roles":{"type":"array","items":{"type":"string"}}}}}}]}}}},"400":{"description":"Invalid tenant id, invalid email, empty roles, unknown role, or `agent_runtime` requested (`agent_runtime is reserved for delegation-enforcing applications`)."},"403":{"description":"Caller does not administer this tenant, or a role is instance_admin/account_admin."},"409":{"description":"Would leave the tenant with no administrator."}}},"delete":{"summary":"Remove a member from a tenant","description":"Removing the tenant's last explicit `admin` answers 409 (instance admins are exempt). Bumps the member's session epoch when they have a user account.\n","operationId":"deleteTenantMember","tags":["Tenants"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9-]{1,30}$"}},{"name":"email","in":"path","required":true,"schema":{"type":"string","format":"email"}}],"responses":{"200":{"description":"Member removed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"400":{"description":"Invalid tenant id or email."},"403":{"description":"Caller does not administer this tenant."},"404":{"description":"Not a member of this tenant."},"409":{"description":"Would leave the tenant with no administrator."}}}},"/cdp/api/v1/accounts/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"One account with its tenants and members (root/instance_admin, or that account's own account_admin)","description":"Full detail for root/instance_admin. Also open READ-ONLY to the account's own `account_admin` (they need the name for the switcher/team pages). A foreign or unknown account answers 404 either way — no existence oracle.\n","operationId":"getAccount","tags":["Accounts"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"`data` is {account, tenants, members}.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AccountDetailResponse"}}}]}}}},"403":{"description":"Caller is a member of the account but not its account_admin","and not root/instance_admin.":null},"404":{"description":"Account not found","or not reachable by this caller.":null}}}},"/cdp/api/v1/accounts/{id}/members/{email}":{"put":{"summary":"Replace one member's roles across the account (root/instance_admin, or that account's own account_admin)","description":"Environments membership fallback: account roles apply in every tenant of the account that has NO explicit tenant_members row for the email — an explicit row wins wholesale, so per-tenant rows can narrow an account grant. Roles use the tenant role vocabulary plus `account_admin`; `instance_admin` is rejected here (resolution ignores it in account_members — the provider-operator persona requires an explicit default-tenant membership). Empty `roles` removes the membership.\nThe account's own `account_admin` may call this too — including granting/revoking `account_admin` itself, which is the point of the persona. Removing or downgrading the account's LAST `account_admin` is refused with 409 (instance persona exempt), the same rule `PUT /tenants/{id}/members/{email}` applies for `admin`.\n","operationId":"putAccountMember","tags":["Accounts"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"email","in":"path","required":true,"schema":{"type":"string","format":"email"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["roles"],"properties":{"roles":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"200":{"description":"Membership replaced.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"400":{"description":"Invalid email, unknown role, or instance_admin requested."},"403":{"description":"Caller is not root/instance_admin","and not this account's account_admin.":null},"404":{"description":"Account not found."},"409":{"description":"Would remove the account's last account_admin."}}}},"/cdp/api/v1/accounts/{id}/team":{"get":{"summary":"The account's whole team (root/instance_admin, or that account's own account_admin)","description":"Every `account_members` role plus the EFFECTIVE per-tenant roles across every tenant the account owns — an explicit `tenant_members` row wins WHOLESALE over the account-derived role in that one tenant, the same precedence resolution and `GET /tenants/{id}/members` use. Pending invites are deliberately NOT aggregated here; read them from the existing per-tenant `GET /tenants/{id}/invites`.\n","operationId":"getAccountTeam","tags":["Accounts"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"`data` is an array of {email, user_id?, display_name?, status?, account_roles[], tenants, tenant_sources} — `user_id` is empty for a member who has not registered yet — `tenants` maps tenant_id → roles[]; `tenant_sources` maps the same keys to where those roles come from.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"email":{"type":"string","format":"email"},"user_id":{"type":"string","format":"uuid"},"display_name":{"type":"string"},"status":{"type":"string"},"account_roles":{"type":"array","items":{"type":"string"}},"tenants":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}},"tenant_sources":{"type":"object","description":"Same keys as `tenants`. `tenant` = an explicit `tenant_members` row; `account` = derived from the member's account role because no explicit row exists. Writing roles for an `account` cell (`PUT /tenants/{id}/members/{email}`) creates an explicit row, which from then on replaces the account-derived roles in that tenant.\n","additionalProperties":{"type":"string","enum":["tenant","account"]}}},"required":["email","account_roles","tenants","tenant_sources"]}}}}]}}}},"403":{"description":"Caller is a member of the account but not its account_admin","and not root/instance_admin.":null},"404":{"description":"Account not found","or not reachable by this caller.":null}}}},"/cdp/api/v1/accounts/{id}/applications":{"get":{"summary":"The account's key inventory — applications across every tenant it owns (root/instance_admin, or that account's own account_admin)","description":"Same row shape as `GET /applications`, reused unpaginated across every tenant of the account: no plaintext key material, and the instance-only flags (`cross_tenant_allowed`, `delegation_allowed`) are omitted for a non-instance caller — an account_admin never sees them, same as the tenant-scoped listing.\n","operationId":"getAccountApplications","tags":["Accounts"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"`data` is the application array.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ApplicationResponse"}}}}]}}}},"403":{"description":"Caller is a member of the account but not its account_admin","and not root/instance_admin.":null},"404":{"description":"Account not found","or not reachable by this caller.":null}}}},"/cdp/api/v1/usage":{"get":{"summary":"This environment's metered contribution","description":"Licensing and usage metering, TENANT level. The resolved tenant's daily usage over the window, its resolved feature entitlement, and the operational quotas that apply to it.\n\n`totals` and `days` come from the daily billing job and count billable identifier keys only; the live profile counts are the `quotas` usage.\n\nDeliberately BAND-free: a tenant is an environment, the usage band is contracted on the ACCOUNT, and rendering \"62 % of band\" beside one environment's numbers would be a statement about a different thing. A sandbox reports `counted: false` on its own dashboard too, so a client never has to infer from the account view that their test workspace is free.\n\nQuotas are the other kind of limit and they DO belong here: they are set and enforced per tenant, and until now they were readable only through the root-only tenant admin endpoint — so the caller being throttled had no way to see how close they were before the 429. Read-only, own tenant only; writing them is still root's (`PUT /tenants/{id}/quotas`).\n","operationId":"getTenantUsage","tags":["Usage"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"from","in":"query","schema":{"type":"string","format":"date"},"description":"Inclusive start (YYYY-MM-DD). Defaults to 90 days ago."},{"name":"to","in":"query","schema":{"type":"string","format":"date"},"description":"Inclusive end (YYYY-MM-DD). Defaults to today."}],"responses":{"200":{"description":"`data` is {tenant_id, account_id, environment, counted, from, to, days[], totals, features[], quotas, quota_usage}. `days` is the per-day series; `totals` takes the PEAK for stocks (billable profiles) and the SUM for flows (events, operations).\n\n`quotas` holds only the limits that are set — an ABSENT key means unlimited, the same thing a stored zero means to the enforcement, so an unconstrained tenant returns `{}` rather than a wall of zeros. `quota_usage` is the coarse 15-minute rollup those limits are checked against (profiles, events_today, connectors, computed_at); it is a different measurement from `totals` and lags by design, and it is labelled separately for that reason. Both come from the same snapshot privacy enforcement reads.\n","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TenantUsageResponse"}}}]}}}},"400":{"description":"Invalid or reversed date range."}}}},"/cdp/api/v1/accounts/{id}/usage":{"get":{"summary":"The account's licence view — band, period-to-date, projection","description":"Licensing and usage metering, ACCOUNT level. Readable by an instance admin, a root key, or any member of the account (or of one of its tenants) — they can already see the underlying data by logging in.\n\n`current_period` assesses the billing period in progress against the contracted band: usage, ratio, projection to period end, and the billable overage. On an ANNUAL contract the assessment is month by month (the band is monthly), averaged across the year, with the averaging waived if any complete month exceeded `peak_guard_pct`. Overage is ALWAYS zero during ramp.\n\nSandbox and development environments appear in `by_tenant` and `tenants` with `counted: false` — they are never hidden, because omitting them makes clients assume they are billed anyway.\n\n`closed_periods` are immutable: once written they are never recomputed, so a retention run or a late-arriving event can never change a historical invoice.\n","operationId":"getAccountUsage","tags":["Usage"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"from","in":"query","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"`data` is {account, from, to, tenants[], licensed, licence, current_period, by_tenant[], band, days[], closed_periods[], rollup}. `licence`/`current_period`/`band` are present only when a licence is stored; `rollup` is the pre-licensing coarse `tenant_usage` aggregate, kept for compatibility.\n","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AccountUsageResponse"}}}]}}}},"400":{"description":"Invalid or reversed date range."},"403":{"description":"Caller is not an instance admin and not a member of this account."},"404":{"description":"Account not found."}}}},"/cdp/api/v1/accounts/{id}/notification-subscriptions":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List the account's alert subscriptions","operationId":"listAccountNotificationSubscriptions","tags":["Usage"],"description":"Account-level events (`account.*`, today `account.usage_threshold`) are mailed to the account's subscribers, rendered from the instance's account-alert templates and sent through instance SMTP. Readable by an instance admin or root key and by any member of the account (or of one of its tenants); application keys are refused.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"Subscriptions, oldest first.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AccountSubscriptionResponse"}}}}]}}}},"403":{"description":"Not a member of the account","or an application key.":null,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Subscribe an account member to an account alert","operationId":"createAccountNotificationSubscription","tags":["Usage"],"description":"Account administrators (and the instance operator) only. The receiving user must be a member of the account. Alerts go by email only. `filters` uses the subscription filter syntax, e.g. `{\"threshold\": 100}`.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountSubscriptionRequest"}}}},"responses":{"201":{"description":"Subscription created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"400":{"description":"user_id missing or unknown, the user is not a member of the account, event_type is not an account event, or invalid filters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Not an account administrator of this account","or an application key.":null,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Account not found (or not yours).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The user is already subscribed to this event.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/accounts/{id}/notification-subscriptions/{sid}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"sid","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"summary":"Get one account alert subscription","operationId":"getAccountNotificationSubscription","tags":["Usage"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"The subscription.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"403":{"description":"Not a member of the account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Subscription not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"put":{"summary":"Update an account alert subscription","operationId":"updateAccountNotificationSubscription","tags":["Usage"],"description":"Partial: `event_type`, `filters` and `enabled` are optional. `user_id` cannot change (400); delete and re-create instead. Account administrators only.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountSubscriptionRequest"}}}},"responses":{"200":{"description":"Subscription updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"400":{"description":"Invalid event_type or filters","or a changed user_id.":null,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Not an account administrator of this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Subscription or account not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The user is already subscribed to that event.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"summary":"Delete an account alert subscription","operationId":"deleteAccountNotificationSubscription","tags":["Usage"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"Subscription deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"403":{"description":"Not an account administrator of this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Subscription or account not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/accounts/{id}/licence":{"get":{"summary":"The account's feature licence and usage band","description":"Returns the stored contract, the resolved feature set, the package catalogue the console renders its editor from, and the limits that WOULD be derived from the current customer count and constants.\n\nA missing licence row means every package is licensed and nothing is metered — nothing changes until a licence is actually written.\n","operationId":"getAccountLicence","tags":["Usage"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"`data` is {account_id, licence?, features[], catalog[], derived_limits?}.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AccountLicenceResponse"}}}]}}}},"403":{"description":"Caller is not an instance admin and not a member of this account."},"404":{"description":"Account not found."}}}},"/cdp/api/v1/tenants":{"post":{"summary":"Create a tenant (root/instance_admin, or an account_admin within their own account's ceiling; async provisioning)","description":"Validates the id, records the tenant with `status: provisioning` (this claims the id — a concurrent create gets 409), answers **202**, and provisions in the background: creating the tenant's databases and applying the current schema, an initial-admin invite to `admin_email` (roles default to [\"admin\"]; the tenant starts with a pending invite, never a pre-made user), and finally the flip to `active` — resolution only accepts active tenants, so a half-provisioned tenant is never resolvable. Poll `GET /tenants/{id}` for the status; a row stuck in `provisioning` is retried via `POST /tenants/{id}/provision`. Answers **501** until multitenancy is enabled on the instance.\nEnvironments: `account_id` is required for root/instance_admin (create the account first via `POST /accounts`); `environment` (default `production`) labels the tenant and selects creation defaults — `sandbox`/`development` tenants start with `outbound_mode: sink` (nothing transmits until an operator flips it), `retention_days_default: 30` and modest quotas; `privacy_mode` is deliberately NOT relaxed. `id` is OPTIONAL: omitted, the server generates an opaque one — a tenant id names the tenant's databases and message subjects, so it is permanent and must carry no meaning (\"Acme / Sandbox\" belongs in `name`).\n**Account administrators**: an `account_admin` user session may also call this. `account_id` is then OPTIONAL when they administer exactly one account (it resolves silently); naming a DIFFERENT account than one they administer is refused (403), and omitting it while administering several is a 400 asking for it explicitly. Each create is gated by a hard ceiling — the account's own `account_licences.max_tenants` when set, else the instance setting `account_max_tenants` (registry default 3) — a 403 naming the ceiling once reached. root/instance_admin bypass the ceiling entirely.\n","operationId":"createTenant","tags":["Tenants"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"account_id":{"type":"string","description":"The owning account. Required for root/instance_admin; optional for an account_admin who administers exactly one account.\n"},"environment":{"type":"string","enum":["production","sandbox","development"],"default":"production"},"id":{"type":"string","pattern":"^[a-z0-9][a-z0-9-]{1,30}$","description":"Optional; server-generated (opaque) when omitted."},"name":{"type":"string"},"admin_email":{"type":"string","format":"email","description":"Seeds the initial-admin invite; omit to start memberless."},"admin_roles":{"type":"array","items":{"type":"string"},"description":"Roles for the seeded invite (default [\"admin\"])."}}}}}},"responses":{"202":{"description":"Provisioning started; `data` is the provisioning row.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TenantObject"}}}]}}}},"400":{"description":"Invalid id, email, environment, unknown roles, missing/unknown account_id, or (account_admin) account_id omitted while administering more than one account."},"403":{"description":"Caller is not root/instance_admin/account_admin; or an account_admin named a DIFFERENT account than one they administer; or the account's tenant ceiling is reached (message names the ceiling)."},"409":{"description":"Tenant id already exists."},"501":{"description":"Multitenancy is not enabled on this instance."}}}},"/cdp/auth/users/me/permissions":{"get":{"summary":"May I reach these paths?","description":"Answers, for each requested entry, whether the CALLER may reach it — evaluated by the same authorization check that judges the real request, so a client never has to encode a copy of the policy. Written for the console's navigation, which otherwise either shows screens that answer 403 or hardcodes a guess about role permissions an operator edits in the Roles screen.\n\nSelf-scoped: it reports the caller's own access and nobody else's, which is why it needs no authorization beyond a valid session. Session auth only — an API key has one fixed set of grants and no navigation to draw.\n\nSCOPE: `permissions` answers the route-permission check. `gates` covers the small set of checks an endpoint makes beyond its route permission (instance administrator, tenant administrator, approver and team checks) — each answered the way that endpoint itself decides, so the two cannot drift. `roles` is also returned so a client can compose further checks of its own without guessing.\n","operationId":"getMyPermissions","tags":["Users"],"security":[{"BearerAuth":[]}],"parameters":[{"name":"paths","in":"query","required":true,"description":"Comma-separated entries, each either a bare absolute path (uses `method`) or `METHOD /path` to ask about that entry's own method, e.g. `/cdp/api/v1/users,POST /campaign/api/v1/campaigns`. The answer map is keyed by the entry exactly as sent — a bare path stays bare, `METHOD /path` stays that string. Relative entries and unknown methods are dropped, never answered; duplicates (by the exact entry text) are collapsed; at most 100 are answered (each is an enforcer call).\n","schema":{"type":"string"}},{"name":"method","in":"query","description":"Default HTTP method for bare-path entries. Defaults to GET.","schema":{"type":"string","enum":["GET","POST","PUT","PATCH","DELETE"]}},{"name":"X-Tenant","in":"header","description":"Evaluate against this tenant instead of the session's active one — the same per-request override authentication honours, so the answer describes the tenant the asking screen is in.\n","schema":{"type":"string"}}],"responses":{"200":{"description":"`data` is `{tenant, method, roles, permissions, gates}`.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"message":{"type":"string"},"data":{"type":"object","properties":{"tenant":{"type":"string","example":"acme"},"method":{"type":"string","example":"GET","description":"The default method used for bare-path entries."},"roles":{"type":"array","items":{"type":"string"},"description":"The caller's roles in that tenant, as enforcement sees them."},"permissions":{"type":"object","additionalProperties":{"type":"boolean"},"description":"Keyed by each `paths` entry exactly as sent (a bare `/path` stays bare, `METHOD /path` stays that string).\n","example":{"/cdp/api/v1/users":false,"/cdp/api/v1/roles":false,"POST /campaign/api/v1/campaigns":true}},"gates":{"type":"object","description":"Checks an endpoint makes beyond its route permission, each answered the way the endpoint enforcing it decides — so a client never composes one itself. `instance_admin` is the caller's membership in the DEFAULT tenant (it stays true while they work inside any other tenant, and a local role of that name in another tenant does not grant it). `tenant_team` is a resolved role in the team set, OR `account_admin` of the account owning the resolved tenant, OR the instance persona. `campaign_approver` reads the resolved roles only, exactly as its handler does.\n","properties":{"campaign_approver":{"type":"boolean"},"tenant_team":{"type":"boolean"},"instance_admin":{"type":"boolean"}}}}}}}}}},"400":{"description":"No usable paths","or an unsupported method.":null},"401":{"description":"Not a valid user session."},"403":{"description":"The X-Tenant header names a tenant the caller is not a member of."}}}},"/cdp/auth/apps/me":{"get":{"summary":"Who is this API key, and may it call these paths?","description":"API-key self-description — the application-key counterpart of `/cdp/auth/users/me/permissions`, used by the remote MCP server to validate a pasted key and to filter its tool list per caller. Self-scoped, so it needs no route permission of its own; a key that would not authenticate on `/cdp/api/v1` (unknown, the literal `root`, or pinned to a non-active tenant) is refused here too.\n\n`permissions` is answered by the same authorization check, in the same order, that a real request with this key gets: the key's catalog roles (mapped through the role catalogue for the key's own tenant), then the key's own extra grants, evaluated in the tenant a real request would resolve for the same key and `X-Tenant` header: the key's own tenant without the header; root and cross-tenant keys select an active tenant with it; a plain key sending `X-Tenant` gets the same 403 a real request gets. Campaign (`/campaign/api/v1/...`) paths are answerable — they share the same role permissions. Omitted for root keys (root may call everything) and when no `paths` are given.\n\n`purposes` and `pii_access_level` are the application's clearance as privacy enforcement reads it (by key hash; not tenant-scoped). Root reports `pii_access_level: 255` and no purposes (it bypasses Gate 1). `active` mirrors `applications.enabled`.\n\nFor an application with `delegation_enforces_user_roles` the answer is the delegated user's, not the application's own: send `X-On-Behalf-Of: <email>` (without it, or with `X-On-Behalf-Of-App`, the call is a 403, like every other route of such an application). Each `permissions` probe is true only when it is allowed to the application AND to one of the user's roles in the tenant, and `purposes`, `pii_access_level` and `roles` are the user's (`app_roles` keeps the application's own roles). The user must be an active member of the tenant holding a role (403 otherwise). This is how the Optima Agents runtime learns exactly what the API will let an instance's owner do. Unflagged applications and the pasted-key flow of the remote MCP server are unchanged. Answers 503 when the authentication store is unavailable (not 401).\n","operationId":"getMyApplication","tags":["Applications"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"paths","in":"query","required":false,"description":"Comma-separated entries, each a bare absolute path (uses `method`) or `METHOD /path`, e.g. `/cdp/api/v1/profiles,POST /campaign/api/v1/segments`. The answer map is keyed by the entry exactly as sent. Relative entries and unknown methods are dropped; duplicates collapsed; at most 200 answered (entries past the 200th are dropped, never answered). Omit for a pure whoami.\n","schema":{"type":"string"}},{"name":"method","in":"query","description":"Default HTTP method for bare-path entries. Defaults to GET.","schema":{"type":"string","enum":["GET","POST","PUT","PATCH","DELETE"]}},{"name":"X-Tenant","in":"header","required":false,"description":"Tenant to describe the key in, resolved exactly as on `/cdp/api/v1` — only root and cross-tenant keys may send it (403 otherwise, and for an unknown or inactive tenant).\n","schema":{"type":"string"}},{"name":"X-On-Behalf-Of","in":"header","required":false,"description":"The delegated user's email. Required for an application with `delegation_enforces_user_roles` (the answer then describes that user's permissions and clearance); ignored for other applications.\n","schema":{"type":"string"}}],"responses":{"200":{"description":"`data` describes the key.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"message":{"type":"string","example":"application"},"data":{"type":"object","properties":{"application_id":{"type":"string"},"name":{"type":"string"},"tenant":{"type":"string","example":"acme"},"active":{"type":"boolean"},"root":{"type":"boolean"},"cross_tenant_allowed":{"type":"boolean"},"roles":{"type":"array","items":{"type":"string"},"description":"Plain catalog role names of the caller the answer describes: the key's own, or under `X-On-Behalf-Of` (an application with `delegation_enforces_user_roles`) the delegated user's roles in the tenant.\n"},"app_roles":{"type":"array","items":{"type":"string"},"description":"Plain catalog role names held by the key itself, also under `X-On-Behalf-Of` (then e.g. `[\"agent_runtime\"]`). Equal to `roles` for every other application.\n"},"purposes":{"type":"array","items":{"type":"string"}},"pii_access_level":{"type":"integer","example":2},"permissions":{"type":"object","additionalProperties":{"type":"boolean"},"example":{"/cdp/api/v1/profiles":true,"POST /campaign/api/v1/segments":false}}}}}}}}},"400":{"description":"Unsupported `method`, or an `Authorization` header sent without `X-APIKey` (this endpoint describes API keys, not sessions)."},"401":{"description":"Missing, unknown or literal-`root` API key."},"403":{"description":"The key's tenant is not active."},"503":{"description":"The authentication store is unavailable."}}}},"/cdp/auth/users/me/settings":{"get":{"summary":"Get my UI settings","description":"All of the caller's per-user UI settings as a key → JSON-value map (session auth only; e.g. the profiles list's column configuration under the \"profiles_columns\" key, or the console's home dashboard under \"home_dashboard\" — `{\"dashboard_id\": \"<uuid>\"}`).\n","operationId":"getMySettings","tags":["Users"],"security":[{"BearerAuth":[]}],"responses":{"200":{"description":"`data` is an object mapping setting keys to JSON values.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"object","description":"Setting key to its stored JSON value. Deliberately open — this is a per-user UI scratchpad (list column choices and the like), not a typed configuration surface.\n","additionalProperties":true}}}]}}}}}}},"/cdp/auth/users/me/settings/{key}":{"put":{"summary":"Store one UI setting","description":"The raw request body is the setting's JSON value (max 64KB).","operationId":"putMySetting","tags":["Users"],"security":[{"BearerAuth":[]}],"parameters":[{"name":"key","in":"path","required":true,"schema":{"type":"string","maxLength":128}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{}}}},"responses":{"200":{"description":"Stored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"400":{"description":"Invalid key or non-JSON/oversized value."}}},"delete":{"summary":"Delete one UI setting (reset to default)","operationId":"deleteMySetting","tags":["Users"],"security":[{"BearerAuth":[]}],"parameters":[{"name":"key","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Deleted (idempotent).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}}}}},"/cdp/auth/users/me":{"get":{"tags":["Users"],"summary":"Get the current user's own profile","description":"Returns the full profile of the currently authenticated user. Requires an active user session (Authorization: Bearer token). API-key callers are rejected with 403. `purposes` and `pii_access_level_effective` are resolved for the session's active tenant. One of the two routes a session restricted by `password_change_required` reaches.\n","security":[{"BearerAuth":[]}],"responses":{"200":{"description":"The current user's profile.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/UserResponse"}}}]}}}},"403":{"description":"Caller is not an active user session (e.g. API-key auth)."},"404":{"description":"User not found."}}},"patch":{"tags":["Users"],"summary":"Update the current user's own profile","description":"Updates the editable fields of the currently authenticated user. Only first_name, last_name, organization, org_unit, org_role and display_name may be changed; email, roles, status and PII access level are not self-editable. Omitted/empty fields are left unchanged. Requires an active user session (Authorization: Bearer token); API-key callers are rejected with 403.\n","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateOwnProfileRequest"}}}},"responses":{"200":{"description":"Updated profile.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/UserResponse"}}}]}}}},"400":{"description":"Invalid request body."},"403":{"description":"Caller is not an active user session (e.g. API-key auth), or the session must change its password first (data.reason=password_change_required)."},"404":{"description":"User not found."}}}},"/cdp/auth/users/me/password":{"post":{"tags":["Users"],"summary":"Change the current user's password","description":"Replaces the signed-in user's password. Reachable by a session restricted by `password_change_required` (and by any other session). A wrong `current_password` counts as a failed login, so repeated guesses lock the account like failed logins do. On success the must-change flag is cleared, every session issued before the change ends (including this one), and a fresh unrestricted token pair is returned. Requires an active user session; API-key callers are rejected with 403.\n","security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangePasswordRequest"}}}},"responses":{"200":{"description":"Password changed; the new session pair.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/LoginResponse"}}}]}}}},"400":{"description":"Invalid body (new_password shorter than 8 characters, a missing field), `current_password is incorrect`, or a new password equal to the current one.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"No valid session.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Caller is not a user session (e.g. API-key auth).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/users":{"get":{"tags":["Users"],"summary":"List all users","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"responses":{"200":{"description":"List of users.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/UserResponse"}}}}]}}}}}}},"/cdp/api/v1/notifications/templates":{"get":{"tags":["Notifications"],"summary":"List notification templates","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"responses":{"200":{"description":"List of notification templates.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TemplateResponse"}}}}]}}}}}},"post":{"tags":["Notifications"],"summary":"Create a notification template","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTemplateRequest"}}}},"responses":{"201":{"description":"Template created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"400":{"description":"Validation error (including a subject_tmpl/body_tmpl that does not parse as a Go template — templates are parse-checked at save time since the editor preview shipped), both or neither of body_tmpl/body_html_tmpl supplied, or template name already exists. Also returned when a template uses a construct that cannot be bounded at run time (range over a literal, `{{range}}` nested deeper than 3, a recursive `{{template}}`); the message names the construct. For one of the three reserved auth templates, also returned when subject_tmpl/body_tmpl/body_html_tmpl references `token` or `data` inside a template action: the CDP builds `reset_url`/`verify_url`/`invite_url` from `console_base_url` and passes only that finished link, never the raw token or the whole payload map — the message names the declared replacement field. Also returned for an `account.*` name: account alerts render from the instance's account templates (`/instance/notification-templates`), so a tenant copy would never be used.\n"},"403":{"description":"The name is one of the three reserved auth templates (`password_reset`, `email_verification`, `tenant_invite`). `password_reset`/`email_verification` render only from the default tenant for every user of the instance, so only the instance operator persona, resolved in the default tenant, may create/update/delete them; `tenant_invite` renders from the inviting tenant, so only that tenant's full-admin persona may.\n"}}}},"/cdp/api/v1/notifications/templates/fields":{"get":{"tags":["Notifications"],"summary":"Curated notification-template field registry","description":"The console's personalization helper source of truth: which data keys each known transactional template (and subscription event type) receives, which are optional, and a sample payload that renders the seeded template cleanly. `injected` keys (api_base_url, template, data) are available in every template. The set of fields is fixed per event type.\n","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"responses":{"200":{"description":"`data` is `{injected: [string], templates: {name: {fields, optional?, sample}}}`.\n","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/NotificationTemplateFieldsResponse"}}}]}}}}}}},"/cdp/api/v1/notifications/templates/preview":{"post":{"tags":["Notifications"],"summary":"Preview UNSAVED notification template text","description":"Renders ad-hoc subject/body template strings over sample `data`, exactly as the notification service renders at send time (same shared reader, real configured api_base_url, no missingkey option — a missing key renders `<no value>`). A broken template is the ANSWER: 200 with per-part `ok: false` and the exact parse/execution error plus the line it points at. A rendered subject containing CR/LF adds the `subject_crlf` warning — such a subject is refused at send time as a header-injection attempt. The preview applies the same save-time check; an unboundable construct is reported as that part's `ok: false` error. Every render is bounded (256 KiB output, 2 s, 1 000 000 range iterations by default).\n","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Template name (fills the injected `template` key)."},"subject_tmpl":{"type":"string"},"body_tmpl":{"type":"string"},"body_html_tmpl":{"type":"string","description":"Optional HTML body (html/template","auto-escaping) to preview alongside subject/body.":null},"data":{"type":"object","description":"Sample notification data (top-level template keys)."}}}}}},"responses":{"200":{"description":"`data` is `{subject: {ok, rendered?, error?: {message, line?}}, body: {…}, body_html?: {…} (present only when the request carried a non-empty body_html_tmpl), warnings?: [string]}`.\n","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/NotificationTemplatePreviewResponse"}}}]}}}},"400":{"description":"Malformed request body."}}}},"/cdp/api/v1/notifications/templates/{name}":{"get":{"tags":["Notifications"],"summary":"Get a notification template by name","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"name":"name","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Template details.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TemplateResponse"}}}]}}}},"404":{"description":"Template not found."}}},"put":{"tags":["Notifications"],"summary":"Update a notification template","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"name":"name","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"subject_tmpl":{"type":"string"},"body_tmpl":{"type":"string","nullable":true,"description":"The plain-text body. Absent/null keeps the stored value; \"\" clears it — which is how a template is switched to the HTML format.\n"},"body_html_tmpl":{"type":"string","nullable":true,"description":"The HTML body (html/template, auto-escaping). Absent/null keeps the stored value; \"\" clears it.\n"}}}}}},"responses":{"200":{"description":"Template updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"400":{"description":"No fields to update provided, a provided part does not parse as a Go template (parse-checked at save time), or the update would leave the template with both a text and an HTML body (or with neither). A request that touches neither body field is not body-checked, so a subject-only edit of a legacy row still works. Also returned when a template uses a construct that cannot be bounded at run time (range over a literal, `{{range}}` nested deeper than 3, a recursive `{{template}}`); the message names the construct. For one of the three reserved auth templates, also returned when a provided part references `token` or `data` inside a template action — see the POST response above. Also returned for an `account.*` name (see the POST response).\n"},"403":{"description":"`name` is a reserved auth template and the caller lacks the required persona — see the POST response above.\n"},"404":{"description":"Template not found."}}},"delete":{"tags":["Notifications"],"summary":"Delete a notification template","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"name":"name","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Template deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"403":{"description":"`name` is a reserved auth template and the caller lacks the required persona — see the POST response above.\n"},"404":{"description":"Template not found."}}}},"/cdp/api/v1/notifications/subscriptions":{"get":{"tags":["Notifications"],"summary":"List notification subscriptions","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"name":"event_type","in":"query","schema":{"type":"string"}},{"name":"channel","in":"query","schema":{"type":"string","enum":["email","webhook"]}},{"name":"receiver","in":"query","schema":{"type":"string","enum":["user","app"]}},{"name":"receiver_id","in":"query","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"List of subscriptions.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SubscriptionResponse"}}}}]}}}}}},"post":{"tags":["Notifications"],"summary":"Create a notification subscription","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSubscriptionRequest"}}}},"responses":{"201":{"description":"Subscription created. For channel=webhook the response carries `data.secret` once. Deliveries are signed `X-Optima-Signature: v2=<hex HMAC-SHA256(secret, tenant_id + \"\\n\" + subscription_id + \"\\n\" + X-Optima-Timestamp + \"\\n\" + body)>`; receivers verify it, check `tenant_id`/`subscription_id` in the body against what they expect, and reject timestamps older than five minutes.\n","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SubscriptionResponse"}}}]}}}},"400":{"description":"Validation error. A `webhook_url` whose host is a literal private, loopback, link-local or metadata address (or `localhost`) is refused with a `webhook_url:` message; hostnames are checked again when the webhook is dialled. An `account.*` event type is refused: account alerts are subscribed per account under `/accounts/{id}/notification-subscriptions`."},"503":{"description":"Credential encryption is not configured on this instance, so a webhook signing secret cannot be stored."}}}},"/cdp/api/v1/notifications/subscriptions/{id}":{"get":{"tags":["Notifications"],"summary":"Get a single notification subscription","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Subscription details.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SubscriptionResponse"}}}]}}}},"404":{"description":"Subscription not found."}}},"put":{"tags":["Notifications"],"summary":"Update a notification subscription","description":"A `webhook_url` is checked against the private-address rule only when it changes or the subscription is being enabled, so a subscription saved before the check existed can still be disabled. After merging with the stored values, `receiver: user` with `channel: webhook` (or `receiver: app` with `channel: email`) is rejected with 400, except that a legacy row already holding such a pair can still be disabled (`enabled: false` with `receiver` and `channel` left unchanged).","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"receiver":{"type":"string","enum":["user","app"]},"receiver_id":{"type":"string","format":"uuid"},"event_type":{"type":"string"},"channel":{"type":"string","enum":["email","webhook"]},"filters":{"type":"object","additionalProperties":true,"description":"Replaces the subscription's stored filters — see CreateSubscriptionRequest.filters for the operator-rule grammar (plain-value JSON equality, or `{\"op\": ..., \"value\": ...}`). Validated the same way at save time; an unknown operator is rejected with 400.\n"},"webhook_url":{"type":"string","format":"uri"},"enabled":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Subscription updated. When the update switches a subscription without a signing secret to channel=webhook, a secret is issued in the same update and returned once in `data.secret` (with `secret_configured: true`), as on create.\n","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SubscriptionResponse"}}}]}}}},"404":{"description":"Subscription not found."},"503":{"description":"The update needs a signing secret and secret encryption is not configured on this instance."}}},"delete":{"tags":["Notifications"],"summary":"Delete a notification subscription","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Subscription deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"404":{"description":"Subscription not found."}}}},"/cdp/api/v1/notifications/subscriptions/{id}/secret/rotate":{"post":{"tags":["Notifications"],"summary":"Rotate a webhook subscription's signing secret","description":"Issues a new signing secret and returns it once in `data.secret`. The previous secret stops signing immediately. A webhook subscription created before per-subscription secrets cannot deliver until its first rotation.\n","operationId":"rotateSubscriptionSecret","security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Secret rotated.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SubscriptionResponse"}}}]}}}},"400":{"description":"Not a webhook subscription."},"404":{"description":"Subscription not found."},"503":{"description":"Credential encryption is not configured on this instance."}}}},"/cdp/api/v1/notifications/providers":{"get":{"summary":"List the tenant's notification providers","operationId":"listNotificationProviders","tags":["Notifications"],"description":"The tenant's own SMTP transport for its notification email. Optima sends a tenant's subscription and direct mails through the active default provider and falls back to instance SMTP when there is none. The reserved auth templates (`password_reset`, `email_verification`, `tenant_invite`) and account alerts always use instance SMTP. The password is write-only; responses carry `has_credentials`.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"Providers (default first).","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/NotificationProviderObject"}}}}]}}}}}},"post":{"summary":"Register a notification provider","operationId":"createNotificationProvider","tags":["Notifications"],"description":"The tenant's first provider becomes the default (of two first providers created at once, exactly one does). `password` is optional and stored encrypted. A `host` that is a literal private, loopback, link-local or metadata address (or `localhost`) is refused with 400 `host: ...`; hostnames are checked again at send time, under the same egress policy as notification webhooks.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotificationProviderObject"}}}},"responses":{"201":{"description":"Provider created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"400":{"description":"Invalid payload: missing name/host/port/from_addr, port outside 1–65535, from_addr not a single bare address, an address in from_name, password combined with clear_credentials, or a blocked host.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Provider name already exists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Credential encryption unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/notifications/providers/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"summary":"Get a notification provider","operationId":"getNotificationProvider","tags":["Notifications"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"The provider (no password).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"404":{"description":"Provider not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"put":{"summary":"Update a notification provider","operationId":"updateNotificationProvider","tags":["Notifications"],"description":"A full replacement of the editable fields. Omit `password` to keep the stored one, send it to replace it, or set `clear_credentials: true` to drop it. Changing `host`, `port` or `username` without re-sending the password (or clearing it) returns 409 `credentials_required`. An unchanged host is re-checked against the egress policy only when the provider is being activated.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotificationProviderObject"}}}},"responses":{"200":{"description":"Provider updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"400":{"description":"Invalid payload or a blocked host.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Provider not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Provider name already exists, OR credentials_required — `host`, `port` or `username` changed while the stored password would be kept.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"$ref":"#/components/schemas/CredentialsRequiredResponse"}]}}}}}},"delete":{"summary":"Delete a notification provider","operationId":"deleteNotificationProvider","tags":["Notifications"],"description":"Deleting the default promotes the most recently updated active provider; with none left the tenant's mail goes through instance SMTP.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"Provider deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"404":{"description":"Provider not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/notifications/providers/{id}/default":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"summary":"Make a provider the tenant's default","operationId":"setDefaultNotificationProvider","tags":["Notifications"],"description":"An inactive default is ignored; mail then goes through instance SMTP. Concurrent set-default and delete calls are applied one after the other; the last one wins.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"Default set.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"404":{"description":"Provider not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/notifications/providers/{id}/test":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"send","in":"query","required":false,"schema":{"type":"boolean"},"description":"true also sends a test message to the caller's own address (user sessions only)."}],"post":{"summary":"Probe a notification provider","operationId":"testNotificationProvider","tags":["Notifications"],"description":"Connects through the notify egress policy and runs EHLO, STARTTLS when offered and AUTH when a username is set. With `send=true` it also mails a test message to the CALLER's own address, never to an address in the request. Honours the tenant's outbound mode: allowed in sink, refused in off (409). A failed probe is still a 200 with `success: false` and the SMTP error in `message`.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"Probe verdict.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/NotificationProviderTestResult"}}}]}}}},"400":{"description":"send=true without a user session.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Provider not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Tenant outbound mode is off.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Credential decryption failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/channels":{"get":{"tags":["Privacy"],"summary":"The effective outbound channel vocabulary","description":"Native channels (email, sms, rcs, whatsapp, viber, push, webhook, and the three onsite surfaces) plus this tenant's declared custom ones. What a channel picker renders, and what campaign/template/fatigue and consent-purpose saves are validated against — the channel vocabulary is no longer a database CHECK, because an operator-declared name cannot be enumerated ahead of time.\n","responses":{"200":{"description":"`data` is a list of {name, label, contact_kind, template_variant, custom, is_active}.\n","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DeliveryChannelSummary"}}}}]}}}}}}},"/cdp/api/v1/channels/custom":{"get":{"tags":["Privacy"],"summary":"List declared custom channels","responses":{"200":{"description":"`data` is a list of DeliveryChannel.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DeliveryChannel"}}}}]}}}}}},"post":{"tags":["Privacy"],"summary":"Declare a custom channel","description":"A call centre, an IVR dialer, a print bureau — an outbound channel this deployment uses that is not built in. Declaring it is what lets a consent purpose be scoped to it, the preference centre offer it, and the erasure job convert a withdrawal into a suppression against the right contact. engineer/admin only; every role that renders a channel picker may read.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeliveryChannel"}}}},"responses":{"200":{"description":"`data` is the saved DeliveryChannel.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DeliveryChannel"}}}]}}}},"400":{"description":"Bad name (must match ^[a-z][a-z0-9_]{1,30}$), a built-in name (a registry row named `sms` would change how every SMS contact is normalized and hashed, invalidating existing suppressions), an unknown contact_kind, or an unknown template_variant.\n"}}}},"/cdp/api/v1/channels/custom/{name}":{"parameters":[{"name":"name","in":"path","required":true,"schema":{"type":"string"}}],"put":{"tags":["Privacy"],"summary":"Update a declared channel","description":"The path name wins over the body, so an edit can never rename a row — renaming would orphan every consent purpose, campaign, template and suppression scoped to the old name.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeliveryChannel"}}}},"responses":{"200":{"description":"`data` is the saved DeliveryChannel.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DeliveryChannel"}}}]}}}},"400":{"description":"Invalid declaration."}}},"delete":{"tags":["Privacy"],"summary":"Delete a declared channel","description":"Refused while any consent purpose, campaign, template, fatigue policy or campaign channel provider still names it — deactivate instead, which stops new use without leaving rows scoped to a channel nothing can resolve.\n","responses":{"200":{"description":"Deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"404":{"description":"Not declared."},"409":{"description":"Still referenced."}}}},"/cdp/api/v1/privacy/purposes":{"get":{"summary":"List consent purposes","description":"Returns all operator-defined consent purposes.","operationId":"listConsentPurposes","tags":["Privacy"],"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"responses":{"200":{"description":"List of consent purposes.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ConsentPurposeObject"}}}}]}}}}}},"post":{"summary":"Create consent purpose","operationId":"createConsentPurpose","tags":["Privacy"],"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConsentPurposeRequest"}}}},"responses":{"200":{"description":"Consent purpose created.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ConsentPurposeObject"}}}]}}}},"400":{"description":"Invalid request body."},"409":{"description":"Consent purpose with this name already exists."},"422":{"description":"The purpose name contains a \".\" (new names may not; purposes created earlier with a dot keep working)."}}}},"/cdp/api/v1/privacy/purposes/{id}":{"put":{"summary":"Update consent purpose","description":"Updates a purpose's mutable columns (description, lawful_basis,\non_withdrawal, is_active — the name is fixed). A partial update:\nomitted fields keep their stored value. Changing the lawful\nbasis is retroactive: widening it (loosening Gate 3, e.g. consent →\nlegitimate_interest) is rejected with 409 unless the request carries\n`?acknowledge_retroactive=true`, and every basis change writes a\n`purpose_basis_change` privacy audit row. Narrowing is always allowed;\nan omitted lawful_basis is not a change.\n","operationId":"updateConsentPurpose","tags":["Privacy"],"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"acknowledge_retroactive","in":"query","required":false,"schema":{"type":"boolean"},"description":"Required (true) when the change widens the lawful basis."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConsentPurposeUpdateRequest"}}}},"responses":{"200":{"description":"Consent purpose updated.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ConsentPurposeObject"}}}]}}}},"404":{"description":"Consent purpose not found."},"409":{"description":"Basis widening without acknowledge_retroactive=true."}}},"delete":{"summary":"Delete consent purpose","operationId":"deleteConsentPurpose","tags":["Privacy"],"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Consent purpose deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"404":{"description":"Consent purpose not found."}}}},"/cdp/api/v1/privacy/consent-policies":{"get":{"summary":"List consent policies","description":"Returns every stored consent-policy version (the exact text data\nsubjects were shown, referenced by consent receipts). Rows are\nappend-only and immutable — a new wording is a new version.\n","operationId":"listConsentPolicies","tags":["Privacy"],"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"responses":{"200":{"description":"List of consent policies.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ConsentPolicyObject"}}}}]}}}}}},"post":{"summary":"Create consent policy version","description":"Stores a new immutable policy version. The text hash (SHA-256) is\ncomputed server-side; the named purposes must exist in the consent\npurpose catalog. There is no PUT and no DELETE — deactivate via PATCH.\n","operationId":"createConsentPolicy","tags":["Privacy"],"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConsentPolicyRequest"}}}},"responses":{"201":{"description":"Consent policy created.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ConsentPolicyObject"}}}]}}}},"400":{"description":"Invalid body or unknown purposes."},"409":{"description":"This key/version/locale already exists."}}}},"/cdp/api/v1/privacy/consent-policies/{id}":{"get":{"summary":"Get consent policy","operationId":"getConsentPolicy","tags":["Privacy"],"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The consent policy.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ConsentPolicyObject"}}}]}}}},"404":{"description":"Consent policy not found."}}},"patch":{"summary":"Activate/deactivate consent policy","description":"Flips is_active — the only mutable column of a policy row.","operationId":"patchConsentPolicyActive","tags":["Privacy"],"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"is_active":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Consent policy updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"404":{"description":"Consent policy not found."}}}},"/cdp/api/v1/privacy/consents/{profile_id}/receipts":{"get":{"summary":"List consent receipts of a profile","description":"Returns the profile's consent receipts (immutable evidence of consent\ninteractions) newest first. On erasure receipts are pseudonymized, not\ndeleted — profile_id becomes a salted hash and ip/user_agent/evidence\nare cleared, while the purpose/policy/timestamp columns survive.\n","operationId":"getConsentReceipts","tags":["Privacy"],"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"name":"profile_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":200}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"Consent receipts, newest first.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ConsentReceiptObject"}}}}]}}}}}}},"/cdp/api/v1/privacy/receipts/{receipt_id}":{"get":{"summary":"Get consent receipt","operationId":"getConsentReceipt","tags":["Privacy"],"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"name":"receipt_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The consent receipt.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ConsentReceiptObject"}}}]}}}},"404":{"description":"Consent receipt not found."}}}},"/cdp/api/v1/privacy/consents/batch":{"post":{"summary":"Get consents for multiple profiles","description":"Batched consent read for the campaign suite: returns every consent record of up to 500 profiles, keyed by profile id — every requested id is present in the response, possibly with an empty array. One query, not one GET per profile; same audit trail as the per-profile GET (one audit row per profile). Like the per-profile GET, it needs no `X-Purpose` header, in every privacy mode. When one is sent, its purposes are checked against the caller (or the delegated user) exactly as on the data routes and recorded on the audit rows (Optima Agents sends its definition's purpose).\n","operationId":"getConsentsBatch","tags":["Privacy"],"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"name":"X-Purpose","in":"header","required":false,"description":"Optional purpose(s), comma-separated (or `?purpose=`). Each must be granted to the caller (403 otherwise); they are recorded as the audit rows' purpose. Without it the rows carry no purpose.\n","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConsentsBatchRequest"}}}},"responses":{"200":{"description":"Consent records keyed by profile id.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"object","additionalProperties":{"type":"array","items":{"$ref":"#/components/schemas/ConsentObject"}}}}}]}}}},"400":{"description":"profile_ids must hold 1-500 UUIDs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`caller not authorized for purpose: <purpose>` (a sent `X-Purpose` is not granted to the caller).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Failed to get consents.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/privacy/consent-stats":{"get":{"summary":"Consent change statistics","description":"Counts consent grants and withdrawals per UTC day or UTC ISO week and\npurpose over the window `[from, to)`. Aggregates only: no profile id is\nreturned and small counts are not suppressed.\n\nA grant is a consent-history entry that sets a purpose to granted after\nit was absent or withdrawn; a withdrawal sets it to withdrawn after it was\ngranted. Re-affirmations, repeated refusals, and the snapshot entries\nwritten by profile deletion and merges count nothing. Buckets with no\nchange are absent. Entries removed by an erasure no longer count, so\npast figures can shrink after one.\n\nWeekly buckets start on Monday 00:00 UTC. A window that is not aligned\nto Monday 00:00 UTC gives a partial first and last bucket. The response\nechoes `from` and `to` as RFC3339 UTC. Needs a privacy role.\n","operationId":"getConsentStats","tags":["Privacy"],"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"name":"from","in":"query","required":true,"description":"Start of the window, inclusive (RFC3339).","schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","required":true,"description":"End of the window, exclusive (RFC3339). Must be after `from`; the window is at most 366 days.","schema":{"type":"string","format":"date-time"}},{"name":"granularity","in":"query","required":false,"schema":{"type":"string","enum":["day","week"],"default":"week"}},{"name":"purpose","in":"query","required":false,"description":"Only this purpose. Must be an active purpose in the catalogue.","schema":{"type":"string"}}],"responses":{"200":{"description":"The change counts.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ConsentStatsResponse"}}}]}}}},"400":{"description":"Missing or invalid `from`, `to`, `granularity`, or an unknown `purpose`; `from` not before `to`; window over 366 days.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"The statistics read timed out or ran out of memory, or the purpose catalogue is unavailable; retry with a shorter window.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/privacy/consents/{profile_id}":{"get":{"summary":"Get profile consents","description":"Returns all consent records for the given profile.","operationId":"getProfileConsents","tags":["Privacy"],"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"name":"profile_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Consent records for the profile.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ConsentObject"}}}}]}}}}}}},"/cdp/api/v1/privacy/consents":{"post":{"summary":"Set profile consents","description":"Upserts consent records for a profile. Uses ReplacingMergeTree semantics —\na new row is inserted for each purpose; the most recent decision per purpose is the one that applies.\n`entity_type` is optional provenance: when omitted it is derived from the\nprofile, or stored as '' when the profile does not exist yet. An optional\n`receipt` object attaches evidence of the interaction (one receipt covers\nthe whole batch); without it the stored state carries an empty receipt_id.\nThe response data carries `{receipt_id}` when a receipt was recorded.\n","operationId":"setConsents","tags":["Privacy"],"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetConsentsRequest"}}}},"responses":{"200":{"description":"Consent records stored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"400":{"description":"Invalid request body or missing required fields, or a `receipt` that does not resolve to one active consent-policy version (\"receipt references unknown consent policy 'k' version 1 locale 'fr'\", \"… locale '' (available: de, en)\", \"receipt references inactive consent policy 'k' version 1\").\n"},"422":{"description":"Validation error (e.g. invalid expires_at format)."},"503":{"description":"Failed to store consents (write stream unavailable); retry later."}}}},"/cdp/api/v1/privacy/consents/{profile_id}/{purpose}":{"delete":{"summary":"Withdraw consent","description":"Records a consent withdrawal (granted=0) for a profile/purpose pair.\n`?entity_type=` is optional (derived from the profile when omitted).\nWhen the purpose is configured `on_withdrawal: erase`, the data-plane\nwriter enqueues a purpose-scoped erasure request (requested_by\n`writer:on_withdrawal`, executed by the scheduler's erasure job) once\nthe withdrawal commits — asynchronously, only when it withdraws an\nexisting grant (no prior grant = no erasure), not when a newer grant\nsupersedes it, and not when an open purpose or full erasure request\nalready covers the profile. The same applies to every other consent\nwrite path.\n","operationId":"withdrawConsent","tags":["Privacy"],"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"name":"profile_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"purpose","in":"path","required":true,"schema":{"type":"string"}},{"name":"entity_type","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Consent withdrawn.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"404":{"description":"No consent record found for this profile/purpose pair."}}}},"/cdp/api/v1/privacy/suppressions/check":{"post":{"summary":"Check contact suppressions (batch)","description":"Answers, per probe, whether a contact is suppressed for a channel/\npurpose. Probes carry the peppered contact hash\n(a keyed HMAC-SHA256 of the normalized contact) — plaintext contacts never transit\nthis API. A stored suppression row applies when its hash matches and\nits channel and purpose each match or are empty (empty = suppressed\nfor all). Rows are written by the erasure job (withdrawals of\nchannel-scoped purposes are converted before profile_consents is\ndeleted) and by Edge unsubscribes. Used by\ndelivery immediately after contact resolution.\n","operationId":"checkSuppressions","tags":["Privacy"],"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["checks"],"properties":{"checks":{"type":"array","minItems":1,"maxItems":500,"items":{"type":"object","required":["contact_hash"],"properties":{"contact_hash":{"type":"string","description":"Peppered HMAC-SHA256 of the normalized contact."},"channel":{"type":"string"},"purpose":{"type":"string"}}}}}}}}},"responses":{"200":{"description":"One boolean per probe, in request order.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"suppressed":{"type":"array","items":{"type":"boolean"}}}}}}]}}}},"400":{"description":"Invalid request body."}}}},"/cdp/api/v1/privacy/contact-attributes":{"get":{"summary":"List contact attributes","description":"The contact-attribute registry: profile attributes that hold a\ncontact address, each declared with a contact kind (`email` or\n`phone`). When a channel-scoped withdrawal becomes a contact\nsuppression (erasure, Edge preference centre), the values of the\ndeclared attributes whose kind matches the channel are suppressed\nalongside the identifier contacts. Optima Campaign refuses to save a\ncampaign, journey send node or ad-hoc send whose `contact_attribute`\nis not declared with its channel's kind. An attribute may be declared\nwith both kinds (one row each).\n","operationId":"listContactAttributes","tags":["Privacy"],"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Every declaration, ordered by attribute then kind.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ContactAttribute"}}}}]}}}}}}},"/cdp/api/v1/privacy/contact-attributes/{attribute}":{"parameters":[{"name":"attribute","in":"path","required":true,"description":"Profile attribute name (1-255 letters, digits, `_`, `.`, `:` or `-`).","schema":{"type":"string"}}],"put":{"summary":"Declare a contact attribute","description":"Declares the attribute as a contact of `contact_kind`. Idempotent:\ndeclaring an existing (attribute, kind) pair returns the stored row\nunchanged. A computed attribute is refused with\n`data.code = contact_attribute_computed` — its values are not stored,\nso erasure could not suppress them. The reverse holds too: a computed attribute\ncannot be created under a declared name (`computed_attribute_is_contact`\non `/computed-attributes/add`).\n","operationId":"declareContactAttribute","tags":["Privacy"],"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["contact_kind"],"properties":{"contact_kind":{"type":"string","enum":["email","phone"]}}}}}},"responses":{"200":{"description":"The stored declaration.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ContactAttribute"}}}]}}}},"400":{"description":"Invalid attribute name or `contact_kind`, or a computed attribute\n(`data.code = contact_attribute_computed`, `data.attribute`).\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}}}},"delete":{"summary":"Remove a contact attribute","description":"Removes the attribute's declarations — every kind, or only the one\nnamed by `contact_kind`. While a live campaign (active or paused), the\ncurrent graph of a journey that can run, or an older journey version\nwith in-flight runs still sends through the attribute on a channel no\nremaining declaration covers, the delete answers 409\n`contact_attribute_in_use` — erasure and unsubscribes would otherwise\nstop suppressing those addresses. `force=true` removes it anyway.\nDrafts are not counted: saving and activating them re-check the\nregistry.\n","operationId":"deleteContactAttribute","tags":["Privacy"],"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"name":"contact_kind","in":"query","required":false,"schema":{"type":"string","enum":["email","phone"]}},{"name":"force","in":"query","required":false,"description":"Remove even while live campaigns or journeys use the attribute.","schema":{"type":"boolean"}}],"responses":{"200":{"description":"Removed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"400":{"description":"Invalid `contact_kind`."},"404":{"description":"No such declaration."},"409":{"description":"Still in use; repeat with `force=true` to remove anyway.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"reason":{"type":"string","enum":["contact_attribute_in_use"]},"references":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["campaign","journey","journey_version"]},"id":{"type":"string"},"name":{"type":"string","description":"For journey_version, \"<journey> (vN, in-flight runs)\"."},"campaign_id":{"type":"string","description":"The campaign itself for kind campaign; the owning campaign for journey kinds (console link /campaigns/{campaign_id}/journeys/{id})."}}}}}}}}]}}}}}}},"/cdp/api/v1/privacy/retention-policies":{"get":{"summary":"List retention policies","operationId":"listRetentionPolicies","tags":["Privacy"],"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"responses":{"200":{"description":"List of retention policies.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/RetentionPolicyObject"}}}}]}}}}}},"post":{"summary":"Create retention policy","operationId":"createRetentionPolicy","tags":["Privacy"],"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetentionPolicyRequest"}}}},"responses":{"200":{"description":"Retention policy created.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RetentionPolicyObject"}}}]}}}},"400":{"description":"Invalid request body."}}}},"/cdp/api/v1/privacy/retention-policies/{id}":{"put":{"summary":"Update retention policy","operationId":"updateRetentionPolicy","tags":["Privacy"],"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetentionPolicyRequest"}}}},"responses":{"200":{"description":"Retention policy updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"400":{"description":"Invalid request body."},"404":{"description":"Retention policy not found."}}},"delete":{"summary":"Delete retention policy","operationId":"deleteRetentionPolicy","tags":["Privacy"],"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Retention policy deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"404":{"description":"Retention policy not found."}}}},"/cdp/api/v1/privacy/erasure":{"post":{"summary":"Create erasure request","description":"Submits a data erasure (right-to-be-forgotten) request. The request is\nrecorded immediately with status `pending`. Actual data deletion is\nexecuted asynchronously by the scheduler.\n\nEvery request runs twice: a first pass, then (about an hour later) a\nsweep pass that removes anything written while the first ran, then a\nsettle check. The status goes `pending` → `in_progress` (with `phase`\n`erasing`, `sweep_scheduled` and `settling` in turn) → `completed`.\nA `full` request is first claimed a few minutes after creation; from\nthen until 72 hours after completion, new writes for the profile are\ndropped by every data-plane writer. Within a pass, a `full` erasure\nof a profile that has events deletes the event-attribute rows first\nand the events on a later tick, once those rows are gone. A pass that\ncannot confirm the state in time re-pends the request; one that keeps\ntiming out on a request older than 24 hours fails it. If an\nattribute delete stays unapplied for more than 6 hours or the data store\nreports it failing, the request is marked `failed` (retried\nafter 30 minutes, up to 5 attempts).\nPoll `GET /privacy/erasure/{id}` for the outcome.\n","operationId":"createErasureRequest","tags":["Privacy"],"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErasureRequest"}}}},"responses":{"200":{"description":"Erasure request created.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ErasureRequestObject"}}}]}}}},"400":{"description":"Invalid request body or missing required fields. Also returned when purpose is missing or unknown for scope=purpose, when attribute_list is empty for scope=attribute_list, or when purpose or attribute_list is given with a scope they do not apply to.\n"},"409":{"description":"A purpose-scoped request for the same profile and purpose is already pending or in progress (at most one open request per profile/purpose).\n"}}},"get":{"summary":"List erasure requests","description":"Returns erasure requests newest-first so operators can monitor the right-to-be-forgotten queue. Filter by status and page with limit/offset.\n","operationId":"listErasureRequests","tags":["Privacy"],"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"name":"status","in":"query","description":"Filter by status, in the same meaning as the `status` field: `pending` returns requests no pass has run on yet, `in_progress` returns every request between its first pass and the end of its settle check, including one waiting for its sweep pass.\n","schema":{"type":"string","enum":["pending","in_progress","completed","failed"]}},{"name":"limit","in":"query","schema":{"type":"integer","default":25,"maximum":100}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"Erasure requests.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"requests":{"type":"array","items":{"$ref":"#/components/schemas/ErasureRequestObject"}},"total":{"type":"integer"}}}}}]}}}},"400":{"description":"Invalid status filter."}}}},"/cdp/api/v1/privacy/erasure/{id}":{"get":{"summary":"Get erasure request","operationId":"getErasureRequest","tags":["Privacy"],"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Erasure request details.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ErasureRequestObject"}}}]}}}},"404":{"description":"Erasure request not found."}}}},"/cdp/api/v1/privacy/audit-log":{"get":{"summary":"Query privacy audit log","description":"Returns filtered entries from the append-only privacy audit log.\nSupports filtering by profile, actor, purpose, entity type, and date range.\n","operationId":"getAuditLog","tags":["Privacy"],"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"name":"profile_id","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"actor","in":"query","schema":{"type":"string"}},{"name":"purpose","in":"query","schema":{"type":"string"}},{"name":"entity_type","in":"query","schema":{"type":"string"}},{"name":"date_from","in":"query","description":"Lower bound (UTC). RFC 3339, `YYYY-MM-DDTHH:MM[:SS]` read as UTC, or a date `YYYY-MM-DD` meaning the start of that day. An unparseable value, or a range where `date_from` is after `date_to`, returns 400.","schema":{"type":"string"}},{"name":"date_to","in":"query","description":"Upper bound (UTC), same formats as `date_from`; a date `YYYY-MM-DD` includes that whole day.","schema":{"type":"string"}},{"name":"limit","in":"query","description":"Page size. Values above 1000 are clamped to 1000.","schema":{"type":"integer","minimum":1,"maximum":1000,"default":100}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Audit log entries.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AuditLogEntry"}}}}]}}}},"400":{"description":"A date filter could not be parsed, or `date_from` is after `date_to`."}}}},"/cdp/api/v1/entities/{entity_type}/attribute-purposes":{"put":{"summary":"Update entity attribute purposes","description":"Replaces the attribute_purposes map for the given entity type.","operationId":"updateEntityAttributePurposes","tags":["Privacy"],"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"name":"entity_type","in":"path","required":true,"schema":{"type":"string"},"example":"customer"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AttributePurposesRequest"}}}},"responses":{"200":{"description":"Attribute purposes updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"400":{"description":"Invalid request body."},"404":{"description":"Entity type not found."}}}},"/cdp/api/v1/event-types/{event_type}/attribute-purposes":{"put":{"summary":"Update event-type attribute purposes","description":"Replaces the attribute_purposes map for the given event type.","operationId":"updateEventTypeAttributePurposes","tags":["Privacy"],"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"name":"event_type","in":"path","required":true,"schema":{"type":"string"},"example":"purchase"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AttributePurposesRequest"}}}},"responses":{"200":{"description":"Attribute purposes updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"400":{"description":"Invalid request body."},"404":{"description":"Event type not found."}}}},"/cdp/api/v1/applications":{"post":{"summary":"Create application (API key)","description":"Creates a new non-root application and generates its API key. The plaintext key is returned ONCE in the response and never retrievable again — only its SHA-512 hash is stored. Requires admin role or root key. The key is pinned to the caller's resolved tenant. `X-Tenant` selects that tenant per the normal §4 resolution rule: root/ `instance_admin` may target ANY active tenant, and any other user session (including an `account_admin`) may target a tenant they are an effective member of — explicitly, or via account-derived wholesale roles — so an account_admin can create a key directly into any tenant of their own account. A tenant admin's keys are otherwise always born in their own tenant.\n","operationId":"createApplication","tags":["Applications"],"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateApplicationRequest"}}}},"responses":{"200":{"description":"Application created; response contains the plaintext API key.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CreatedApplicationResponse"}}}]}}}},"400":{"description":"Invalid request body, or the name `optima-campaign-service` (compared case-insensitively, ignoring surrounding spaces), which is reserved for the Campaign service application."},"409":{"description":"An application with this name already exists in the tenant (case-insensitive). Also returned, rarely, on an API key collision (retry)."}}},"get":{"summary":"List applications","description":"Returns applications (newest first), paginated. Never includes key hashes. Requires admin role or root key. A tenant admin sees only their own tenant's applications; the instance persona (root or `instance_admin` — the default tenant's admin fallback was retired by the access-model redesign) sees all. An `account_admin` sees only their own tenant here too — use `GET /accounts/{id}/applications` for the account-wide listing.","operationId":"listApplications","tags":["Applications"],"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"size","in":"query","required":false,"schema":{"type":"integer","maximum":100}}],"responses":{"200":{"description":"List of applications.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ApplicationResponse"}}}}]}}}}}}},"/cdp/api/v1/mcp/connections":{"get":{"summary":"List connected AI apps","description":"Lists the remote-MCP OAuth connections of the resolved tenant. Requires api_key_manager, auditor, admin or root.","operationId":"listMCPConnections","tags":["Applications"],"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"name":"application_id","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"status","in":"query","schema":{"type":"string","enum":["pending","active","revoked","key_invalid","expired"]}}],"responses":{"200":{"description":"Connections.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/MCPConnection"}}}}]}}}},"400":{"description":"Invalid status or application_id."}}}},"/cdp/api/v1/mcp/connections/{id}":{"delete":{"summary":"Revoke a connected AI app","description":"Revokes the connection and drops its token hashes; the AI app must re-authorize. Idempotent. Requires api_key_manager, admin or root.","operationId":"revokeMCPConnection","tags":["Applications"],"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Revoked.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"}}}}}]}}}},"404":{"description":"Unknown connection (or not a UUID)."}}}},"/cdp/api/v1/applications/{id}":{"get":{"summary":"Get application","description":"Returns a single application by id (without key material). Requires admin role or root key. An application outside the caller's tenant scope answers 404 (never 403) — a tenant admin must not learn whether a foreign id exists.","operationId":"getApplication","tags":["Applications"],"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The application.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ApplicationResponse"}}}]}}}},"404":{"description":"Application not found."}}},"put":{"summary":"Update application","description":"Updates the application's name and description. Requires admin role or root key. Root applications cannot be managed via the API. An application outside the caller's tenant scope answers 404, never 403.","operationId":"updateApplication","tags":["Applications"],"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateApplicationRequest"}}}},"responses":{"200":{"description":"Application updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"400":{"description":"Invalid request body, or a rename to the reserved name `optima-campaign-service` (compared case-insensitively, ignoring surrounding spaces). An application that already carries the name may keep it."},"403":{"description":"Root applications cannot be managed via the API."},"404":{"description":"Application not found."},"409":{"description":"An application with this name already exists in the tenant (case-insensitive)."}}},"delete":{"summary":"Delete application","description":"Permanently deletes the application (cascades to its purpose grants). Requires admin role or root key. Root applications cannot be deleted via the API. An application outside the caller's tenant scope answers 404, never 403.","operationId":"deleteApplication","tags":["Applications"],"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Application deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"403":{"description":"Root applications cannot be managed via the API."},"404":{"description":"Application not found."}}}},"/cdp/api/v1/applications/{id}/rotate":{"post":{"summary":"Rotate application API key","description":"Generates a new API key. The previous key keeps working for the rotation grace window (instance setting `api_key_rotation_grace_hours`, default 24 h, 0 = none) and is then retired together with its authorization rows; `revoke_previous=true` retires it immediately. The key rotated out by the rotation before this one is retired now. The new plaintext key is returned ONCE. Requires key authority. Root applications cannot be rotated via the API. An application outside the caller's tenant scope answers 404, never 403 (no cross-tenant key theft). A caller that is not a tenant administrator must hold the key's PII level and purposes (403 otherwise); a key may rotate itself. The response carries a plaintext key, so it is never cached or replayed by `X-Idempotency-Key`.\n","operationId":"rotateApplicationKey","tags":["Applications"],"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"revoke_previous","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Retire the previous key immediately instead of after the grace window."}],"responses":{"200":{"description":"Key rotated; response contains the new plaintext API key.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CreatedApplicationResponse"}}}]}}}},"400":{"description":"revoke_previous is not true or false."},"403":{"description":"Root applications cannot be managed via the API, or the caller does not hold the key's PII level and purposes."},"404":{"description":"Application not found."},"409":{"description":"API key collision (retry)."}}}},"/cdp/api/v1/applications/{id}/revoke-previous":{"post":{"summary":"Revoke the previous API key now","description":"Ends the rotation grace window without rotating: the rotated-out key stops authenticating at once and its authorization rows are removed. A no-op (200) when there is no previous key. Same authority as rotation.\n","operationId":"revokePreviousApplicationKey","tags":["Applications"],"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Previous key revoked (or there was none).","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ApplicationResponse"}}}]}}}},"403":{"description":"Root application, or the caller lacks authority over this key."},"404":{"description":"Application not found."}}}},"/cdp/api/v1/applications/{id}/enabled":{"patch":{"summary":"Revoke or re-enable application","description":"Toggles the application's `enabled` flag. When disabled, the application's keys are rejected at authentication. Requires admin role or root key. Root applications cannot be managed via the API. An application outside the caller's tenant scope answers 404, never 403.\n","operationId":"setApplicationEnabled","tags":["Applications"],"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetApplicationEnabledRequest"}}}},"responses":{"200":{"description":"Application enabled flag updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"400":{"description":"Invalid request body."},"403":{"description":"Root applications cannot be managed via the API."},"404":{"description":"Application not found."}}}},"/cdp/api/v1/applications/{id}/roles":{"put":{"summary":"Set application key roles","description":"Replaces the key's catalog role set (access-model redesign). Roles are PLAIN catalog names, enforced exactly like a user session's roles: the authentication maps each through the account owning the KEY's pinned tenant and allows on the first pass, before falling back to the key's own per-hash grants. Because roles follow the application id, key rotation cannot strip them — which is why they are the primary mechanism and the extra grants below are the escape hatch.\n\nValidation: `instance_admin` and `account_admin` are never grantable to a key (400); every other name must exist in the global catalog or in the customs of the account that owns the KEY's tenant (400 otherwise); a root application is refused (400 — it already bypasses authorization).\n\n**Authorization:** beyond the route permission this is the role ceiling. A full administrator of the KEY's own tenant (`admin`, `account_admin`, `instance_admin`) or the instance persona may set any roles. Anyone else (e.g. `api_key_manager`) may only set roles it holds itself in that tenant, never `admin`, and may not touch a key carrying instance flags or extra route grants; the check covers the key's current roles plus the requested ones. An application key may never change its OWN roles. An application outside the caller's tenant scope answers 404 before any 403, so a foreign key id is never confirmed.\n","operationId":"setApplicationRoles","tags":["Applications"],"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetApplicationRolesRequest"}}}},"responses":{"200":{"description":"Roles updated; the normalized set is echoed back.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"400":{"description":"Reserved role, unknown role, malformed name, or a root application."},"403":{"description":"A role above the caller's ceiling (admin, or a role it does not hold), a key with instance flags or extra grants, a key editing its own roles, or a caller that is not a tenant administrator and lacks the key's PII level and purposes."},"404":{"description":"Application not found (or outside the caller's tenant scope)."}}}},"/cdp/api/v1/applications/{id}/grants":{"get":{"summary":"Get application extra grants","description":"Returns the key's extra route grants — permissions attached to the key itself rather than to a role, valid in every tenant the key reaches. These are the narrow escape hatch beside the catalog roles above. An application outside the caller's tenant scope answers 404, never 403.\n","operationId":"getApplicationGrants","tags":["Applications"],"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The key's extra grants.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ApplicationGrantsResponse"}}}]}}}},"404":{"description":"Application not found (or outside the caller's tenant scope)."}}},"put":{"summary":"Replace application extra grants","description":"Replaces the whole extra-grant set. `object` must be an absolute route pattern (the same form `GET /roles/available-permissions` returns as `suggested_object`) and `action` an HTTP method or `*`; actions are upper-cased on save because methods are compared case-sensitively. The write covers EVERY hash the key still authenticates with — the current one and, during a rotation grace window, the old one — so a revoked grant cannot survive on the retiring key. A root application is refused (400).\n\n**Authorization:** same as PUT `/roles` — the administrator role for the KEY's own tenant, or the instance persona, on top of the route permission. The scope 404 still runs first. (The GET above is scope-gated only: reading a key's grants inside your own tenant grants nothing.)\n","operationId":"setApplicationGrants","tags":["Applications"],"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApplicationGrantsRequest"}}}},"responses":{"200":{"description":"Grants replaced; the normalized set is echoed back.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ApplicationGrantsResponse"}}}]}}}},"400":{"description":"Malformed object/action, or a root application."},"403":{"description":"Administrator role for the key's tenant (or the instance persona) required."},"404":{"description":"Application not found (or outside the caller's tenant scope)."}}}},"/cdp/api/v1/applications/{id}/purposes":{"get":{"summary":"Get application purposes","description":"Returns the list of consent purposes the application is authorized to request. An application outside the caller's tenant scope answers 404, never 403.","operationId":"getApplicationPurposes","tags":["Privacy"],"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Authorized purposes for the application.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"type":"string"}}}}]}}}},"404":{"description":"Application not found."}}},"put":{"summary":"Set application purposes","description":"Replaces the full list of authorized purposes for the application. Each purpose must exist in the consent-purposes catalog. The special purpose \"*\" (seeded inactive) authorizes the application for ANY declared purpose at Gate 1 — attribute purpose tags and data-subject consent are still evaluated against the concrete X-Purpose the caller sends. Intended for trusted service applications (e.g. optima-campaign-service) that forward the acting user's purpose. An application outside the caller's tenant scope answers 404, never 403. Any newly added purpose must be held by the caller (or the caller holds \"*\"); a caller who is not a full tenant admin of the key's tenant can never grant clearance above its own, and an application may never edit its own purposes.","operationId":"setApplicationPurposes","tags":["Privacy"],"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CallerPurposesRequest"}}}},"responses":{"200":{"description":"Application purposes replaced.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"400":{"description":"Invalid request body."},"403":{"description":"The caller lacks authority over this key, or is trying to add a purpose above its own clearance, or is the key itself."},"404":{"description":"Application not found."}}}},"/cdp/api/v1/applications/{id}/purposes/{purpose}":{"post":{"summary":"Grant application purpose","description":"Grants a single consent purpose to the application. Granting the special purpose \"*\" authorizes the application for any declared purpose at Gate 1 (see PUT /applications/{id}/purposes). An application outside the caller's tenant scope answers 404, never 403. The purpose must be held by the caller (or the caller holds \"*\"); a caller who is not a full tenant admin of the key's tenant can never grant clearance above its own, and an application may never edit its own purposes.","operationId":"grantApplicationPurpose","tags":["Privacy"],"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"purpose","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Purpose granted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"403":{"description":"The caller lacks authority over this key, or is trying to grant a purpose above its own clearance, or is the key itself."},"404":{"description":"Application or purpose not found."}}},"delete":{"summary":"Revoke application purpose","description":"Revokes a single consent purpose from the application. An application outside the caller's tenant scope answers 404, never 403.","operationId":"revokeApplicationPurpose","tags":["Privacy"],"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"purpose","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Purpose revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"404":{"description":"Application or purpose not found."}}}},"/cdp/api/v1/users/{id}/purposes":{"get":{"summary":"Get user purposes","description":"Returns the list of consent purposes the user is authorized to request, IN THE RESOLVED TENANT (multitenancy §4 — pin a different tenant with `X-Tenant`; the instance persona and `cross_tenant_allowed` service apps may select any active tenant, a tenant member may select one they belong to).\n\nThe addressed user must be a member of the resolved tenant — an explicit `tenant_members` row, or an account-derived one — including for the instance persona. A user outside that scope answers the SAME 404 an unknown id does, so the endpoint is not an existence oracle for the instance's user list.","operationId":"getUserPurposes","tags":["Privacy"],"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"X-Tenant","in":"header","description":"Resolve against this tenant instead of the caller's default (multitenancy §4).","schema":{"type":"string"}}],"responses":{"200":{"description":"Authorized purposes for the user, in the resolved tenant.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"type":"string"}}}}]}}}},"404":{"description":"User not found, or not a member of the resolved tenant (the two are deliberately indistinguishable)."}}},"put":{"summary":"Set user purposes","description":"Replaces the user's full list of authorized purposes IN THE RESOLVED TENANT (multitenancy §4 — pin a different tenant with `X-Tenant`). The special purpose \"*\" authorizes the user for any declared purpose at Gate 1 (see PUT /applications/{id}/purposes).\n\nAdministered by the resolved tenant's own admins — an `admin` role in the resolved tenant, an `account_admin` of the account owning it, or the instance persona (root key or `instance_admin`). The addressed user must additionally be a member of the resolved tenant (explicit or account-derived) — an unknown id and a real non-member answer the SAME 404.","operationId":"setUserPurposes","tags":["Privacy"],"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"X-Tenant","in":"header","description":"Resolve against this tenant instead of the caller's default (multitenancy §4).","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CallerPurposesRequest"}}}},"responses":{"200":{"description":"User purposes replaced, in the resolved tenant.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"400":{"description":"Invalid request body."},"403":{"description":"Tenant administrator privileges required (for the resolved tenant)."},"404":{"description":"User not found, or not a member of the resolved tenant."}}}},"/cdp/api/v1/users/{id}/purposes/{purpose}":{"post":{"summary":"Grant user purpose","description":"Adds one authorized purpose to the user IN THE RESOLVED TENANT (multitenancy §4 — pin a different tenant with `X-Tenant`).\n\nAdministered by the resolved tenant's own admins — an `admin` role in the resolved tenant, an `account_admin` of the account owning it, or the instance persona (root key or `instance_admin`). The addressed user must additionally be a member of the resolved tenant (explicit or account-derived) — an unknown id and a real non-member answer the SAME 404.","operationId":"grantUserPurpose","tags":["Privacy"],"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"purpose","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Tenant","in":"header","description":"Resolve against this tenant instead of the caller's default (multitenancy §4).","schema":{"type":"string"}}],"responses":{"200":{"description":"Purpose granted, in the resolved tenant.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"403":{"description":"Tenant administrator privileges required (for the resolved tenant)."},"404":{"description":"User not found, or not a member of the resolved tenant. Granting an unknown purpose name is NOT a 404: the grant is stored as given — it simply authorizes nothing at Gate 1 until the tenant's purpose catalogue defines it."}}},"delete":{"summary":"Revoke user purpose","description":"Removes one authorized purpose from the user IN THE RESOLVED TENANT (multitenancy §4 — pin a different tenant with `X-Tenant`).\n\nAdministered by the resolved tenant's own admins — an `admin` role in the resolved tenant, an `account_admin` of the account owning it, or the instance persona (root key or `instance_admin`). The addressed user must additionally be a member of the resolved tenant (explicit or account-derived) — an unknown id and a real non-member answer the SAME 404.","operationId":"revokeUserPurpose","tags":["Privacy"],"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"purpose","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Tenant","in":"header","description":"Resolve against this tenant instead of the caller's default (multitenancy §4).","schema":{"type":"string"}}],"responses":{"200":{"description":"Purpose revoked, in the resolved tenant.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"403":{"description":"Tenant administrator privileges required (for the resolved tenant)."},"404":{"description":"User not found, purpose not found, or user not a member of the resolved tenant."}}}},"/cdp/api/v1/applications/{id}/pii-access-level":{"patch":{"summary":"Set application PII access level","description":"Sets the PII clearance level for an application. Attributes with\n`pii_level > pii_access_level` are redacted from responses. An\napplication outside the caller's tenant scope answers 404, never 403.\n`pii_access_level` is required (400 if null/omitted) — this\nendpoint has no fallback value to clear it TO. Raising a key's level\nabove the caller's own is refused unless the caller is a full tenant\nadmin of the key's tenant; lowering always passes. An application may\nnever edit its own PII access level.\n","operationId":"patchApplicationPIIAccessLevel","tags":["Privacy"],"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PIIAccessLevelRequest"}}}},"responses":{"200":{"description":"PII access level updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"400":{"description":"Invalid request body."},"403":{"description":"The caller lacks authority over this key, or is trying to raise it above its own PII clearance, or is the key itself."},"404":{"description":"Application not found."}}}},"/cdp/api/v1/users/{id}/pii-access-level":{"patch":{"summary":"Set user PII access level","description":"Sets a user's PII clearance. The request body's `scope` (default `tenant`) selects WHICH value is written:\n\n- `tenant` sets or clears the RESOLVED tenant's override\n  (multitenancy §4 — pin a different tenant with `X-Tenant`).\n  Administered by that tenant's own admins — an\n  `admin` role in the resolved tenant, an `account_admin` of the\n  account owning it, or the instance persona. The addressed user must\n  be a member of the resolved tenant (explicit or account-derived) —\n  an unknown id and a real non-member answer the SAME 404. A `null`\n  `pii_access_level` DELETEs the override, restoring the instance\n  default.\n- `instance_default` sets the instance-wide default column — the\n  floor every tenant without an override falls back to.\n  **Instance persona only** (root key or `instance_admin`),\n  unchanged from before this endpoint gained tenant scope. A `null`\n  level is rejected (400): there is nothing for the instance default\n  to fall back to.","operationId":"patchUserPIIAccessLevel","tags":["Privacy"],"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"X-Tenant","in":"header","description":"Resolve against this tenant instead of the caller's default (multitenancy §4). Only relevant to `scope=tenant`.\n","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PIIAccessLevelRequest"}}}},"responses":{"200":{"description":"PII access level updated (or cleared, for a null tenant-scope level).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"400":{"description":"Invalid request body, unrecognised `scope`, or a null level under `scope=instance_default`."},"403":{"description":"Tenant administrator privileges required (scope=tenant, for the resolved tenant), or instance administrator privileges required (scope=instance_default)."},"404":{"description":"User not found, or (scope=tenant) not a member of the resolved tenant."}}}},"/cdp/api/v1/privacy/access-levels":{"get":{"summary":"Get all PII access levels","description":"Returns the effective PII access level for every application and user visible in the resolved tenant (multitenancy §4 — pin a different tenant with `X-Tenant`). Access is decided by the route permission alone — this is the console's Privacy > Access tab, reachable by any tenant role granted the route; only the DATA is scoped to the resolved tenant, not the caller.","operationId":"getPIIAccessLevels","tags":["Privacy"],"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"parameters":[{"name":"X-Tenant","in":"header","description":"Resolve against this tenant instead of the caller's default (multitenancy §4).","schema":{"type":"string"}}],"responses":{"200":{"description":"PII access level entries.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PIIAccessLevelEntry"}}}}]}}}}}}},"/cdp/api/v1/custom-datasets":{"get":{"summary":"List dataset definitions","operationId":"listCustomDatasets","tags":["Custom Datasets"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"List of dataset definitions.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CustomDatasetDefinition"}}}}]}}}}}},"post":{"summary":"Create dataset definition","operationId":"createCustomDataset","tags":["Custom Datasets"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomDatasetDefinition"},"example":{"name":"products","description":"Product catalog","attribute_types":{"name":"string","price":"decimal","in_stock":"boolean"},"strict":true}}}},"responses":{"201":{"description":"Dataset definition created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"400":{"description":"Invalid payload or missing required field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Dataset with that name already exists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/custom-datasets/{name}":{"parameters":[{"name":"name","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get dataset definition","operationId":"getCustomDataset","tags":["Custom Datasets"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"Dataset definition.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CustomDatasetDefinition"}}}]}}}},"404":{"description":"Dataset not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"put":{"summary":"Replace dataset definition","description":"Replaces attribute_types, strict, pii_attributes, and description. Existing records are not affected.","operationId":"updateCustomDataset","tags":["Custom Datasets"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomDatasetDefinition"}}}},"responses":{"200":{"description":"Dataset definition updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"404":{"description":"Dataset not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"summary":"Delete dataset definition","description":"Deletes the dataset definition. Without `?cascade=true` the request is rejected if\nany records exist in the dataset. With `?cascade=true` all records, attributes, and\nprofile–record links are deleted first (asynchronous).\n","operationId":"deleteCustomDataset","tags":["Custom Datasets"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"cascade","in":"query","description":"Set to \"true\" to delete all records before deleting the definition.","schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"Dataset deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"404":{"description":"Dataset not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Dataset has records; use ?cascade=true.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/custom-datasets/{name}/records":{"parameters":[{"name":"name","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List records in a dataset","operationId":"listCustomDatasetRecords","tags":["Custom Datasets"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/PurposeHeader"},{"name":"include_attributes","in":"query","schema":{"type":"boolean","default":false}},{"name":"attr_filters","in":"query","description":"JSON-encoded array of EventAttrRule objects (simplified attribute\nfilter, AND-combined, typed against the dataset schema).\n","schema":{"type":"string"}},{"name":"page","in":"query","schema":{"type":"integer","default":0}},{"name":"size","in":"query","schema":{"type":"integer","default":100,"maximum":100}}],"responses":{"200":{"description":"List of records.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CustomDatasetRecordObject"}}}}]}}}},"404":{"description":"Dataset not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Upsert records (single or batch)","description":"Accepts a JSON object (single record) or a JSON array (batch). Each record is\nidentified by `record_key`. Re-submitting the same `record_key` overwrites\nthe previous record via `ReplacingMergeTree(updated_at)` (partial update —\nomitted attributes keep their stored values).\n\nData-contract `required` rules are evaluated against the merged result: a\nrequired attribute is satisfied if it is in the payload **or** already\nstored on the record, so a partial update need not re-send every required\nattribute.\n\nA batch is validated all-or-nothing: if any record fails validation\n(400 or 422), no record of the request is written.\n","operationId":"upsertCustomDatasetRecords","tags":["Custom Datasets"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/CustomDatasetRecordInput"},{"type":"array","items":{"$ref":"#/components/schemas/CustomDatasetRecordInput"}}]},"example":[{"record_key":"SKU-001","source":"import","attributes":{"name":"Running Shoes","price":89.99,"in_stock":true}}]}}},"responses":{"200":{"description":"Records accepted. Returns an array of record UUIDs.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"type":"string","format":"uuid"}}}}]}}}},"400":{"description":"Invalid payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Dataset not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Strict-mode or data-contract violation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/custom-datasets/{name}/records/remove-by-filter":{"delete":{"summary":"Remove dataset records by attribute filter","description":"Deletes every record of the dataset matching the simplified attribute\nfilter (see EventAttrRule; AND-combined, typed against the dataset\nschema). At least one rule is required — a full wipe goes through\n`DELETE /custom-datasets/{name}/records`. Returns the deleted count.\n\n**Deferred since 2026-08-17 (BREAKING).** Answers 202 with\n`{request_id, scheduled_at, matched}` and runs after\n`bulk_delete_delay_sec`, cancellable until then via\n`DELETE /cdp/api/v1/deletion-requests/{id}`. `?immediate=true`\nrestores the inline 200.\n","operationId":"removeDatasetRecordsByFilter","tags":["Custom Datasets"],"parameters":[{"name":"dry_run","in":"query","schema":{"type":"boolean"},"description":"true = return the exact would-be count without deleting: {matched, dry_run}."},{"name":"name","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/PurposeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["attr_filters"],"properties":{"attr_filters":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/EventAttrRule"}}}}}}},"responses":{"200":{"description":"Records removed (`data.deleted` holds the count), or nothing matched (`{matched: 0, deleted: 0}`; nothing is scheduled).\n","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BulkDeleteResult"}}}]}}}},"400":{"description":"Invalid payload or filter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Dataset not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/custom-datasets/{name}/records/export":{"post":{"summary":"Export dataset records as CSV","description":"Streams a CSV of the records matching the (optional) simplified\nattribute filter, with base columns (record_key, source, created_at,\nupdated_at) plus the selected attribute columns. PII-level gates apply\nto attribute values exactly like the record list endpoint.\n","operationId":"exportDatasetRecords","tags":["Custom Datasets"],"parameters":[{"name":"name","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/PurposeHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"attr_filters":{"type":"array","items":{"$ref":"#/components/schemas/EventAttrRule"}},"attributes":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"200":{"description":"CSV file (attachment).","content":{"text/csv":{"schema":{"type":"string"}}}},"400":{"description":"Invalid payload or filter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Dataset not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/custom-datasets/{name}/records/{record_key}":{"parameters":[{"name":"name","in":"path","required":true,"schema":{"type":"string"}},{"name":"record_key","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a single record","operationId":"getCustomDatasetRecord","tags":["Custom Datasets"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/PurposeHeader"},{"name":"include_attributes","in":"query","schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"Record object.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CustomDatasetRecordObject"}}}]}}}},"404":{"description":"Record or dataset not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"summary":"Delete a record","description":"Deletes the record and all its attributes (asynchronous).","operationId":"deleteCustomDatasetRecord","tags":["Custom Datasets"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"Record deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"404":{"description":"Dataset not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/custom-datasets/{name}/records/{record_key}/profiles":{"get":{"summary":"List profiles linked to a record","operationId":"getRecordLinkedProfiles","tags":["Custom Datasets"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/PurposeHeader"},{"name":"name","in":"path","required":true,"schema":{"type":"string"}},{"name":"record_key","in":"path","required":true,"schema":{"type":"string"}},{"name":"link_type","in":"query","description":"Filter by link_type label.","schema":{"type":"string"}},{"name":"page","in":"query","schema":{"type":"integer","default":0}},{"name":"size","in":"query","schema":{"type":"integer","default":100,"maximum":100}}],"responses":{"200":{"description":"List of profile–record links.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ProfileDatasetLinkObject"}}}}]}}}},"404":{"description":"Record or dataset not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/profiles/{profile_id}/custom-dataset/{dataset_name}":{"get":{"summary":"List records linked to a profile within a dataset","operationId":"getProfileDatasetLinks","tags":["Custom Datasets"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"$ref":"#/components/parameters/PurposeHeader"},{"name":"profile_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"dataset_name","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"List of profile–record links for this profile within the dataset.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ProfileDatasetLinkObject"}}}}]}}}},"400":{"description":"Invalid profile_id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/profiles/{profile_id}/custom-dataset/{dataset_name}/{record_key}":{"parameters":[{"name":"profile_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"dataset_name","in":"path","required":true,"schema":{"type":"string"}},{"name":"record_key","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Link a profile to a record","operationId":"linkProfileToRecord","tags":["Custom Datasets"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"link_type":{"type":"string","description":"Label for the relationship (e.g. \"purchased\", \"enrolled_in\").","example":"purchased"}}}}}},"responses":{"201":{"description":"Link created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"400":{"description":"Invalid profile_id or payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Dataset or record not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a profile–record link's link_type","description":"Updates the `link_type` of an existing link. The profile/record/dataset identity is the addressing key and immutable; only `link_type` is mutable (an empty value clears it). The change is recorded in h_profile_custom_dataset_links with action 'update'.\n","operationId":"updateProfileRecordLink","tags":["Custom Datasets"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"link_type":{"type":"string","example":"leased"}}}}}},"responses":{"200":{"description":"Link updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"400":{"description":"Invalid profile_id or payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Record or link not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"summary":"Unlink a profile from a record","operationId":"unlinkProfileFromRecord","tags":["Custom Datasets"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"Link deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"400":{"description":"Invalid profile_id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Record not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/analytics/reports":{"get":{"summary":"List saved reports","operationId":"listReports","tags":["Analytics"],"description":"Lists saved reports, ordered by most-recently-updated first. Each carries min_pii_level_required and required_purposes so the UI can indicate runnability, plus folder and tags. Offset paginated: pass page + size to page the results (the response `page` meta carries page/size/total); omitting size returns every report. Optional folder/tag filters narrow the list. Requires analytics_editor or a broader role.\n","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"name","in":"query","description":"Exact-match filter on the report name.","schema":{"type":"string"}},{"name":"folder","in":"query","description":"Filter to a folder path. Presence of the key filters even when empty, so folder= selects root-level reports. Normalised like the stored path.","schema":{"type":"string"}},{"name":"subtree","in":"query","description":"When true (with a non-empty folder), include reports in descendant folders too, not just the exact folder.","schema":{"type":"boolean"}},{"name":"tag","in":"query","description":"Comma-separated tags; reports must carry ALL listed tags.","schema":{"type":"string"}},{"name":"type","in":"query","description":"Only reports whose definition has this query type. An unknown value is a 400.","schema":{"type":"string","enum":["aggregate","funnel","retention"]}},{"name":"page","in":"query","schema":{"type":"integer","minimum":0,"default":0}},{"name":"size","in":"query","description":"Rows per page. Maximum is 100; omit to return every report.","schema":{"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"List of reports.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ReportObject"}},"page":{"$ref":"#/components/schemas/PageMeta"}}}]}}}},"400":{"description":"Invalid pagination or an unknown type.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a report","operationId":"createReport","tags":["Analytics"],"description":"Validates the definition, computes min_pii_level_required and required_purposes, and stores them. Returns a warnings array if the creator lacks any required purpose (creation is not blocked). Requires analytics_editor or a broader role.\n","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportObject"}}}},"responses":{"201":{"description":"Report created.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ReportObject"}}}]}}}},"400":{"description":"Invalid payload or definition.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"A report with that name already exists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/analytics/reports/facets":{"get":{"summary":"List report folders and tags","operationId":"listReportFacets","tags":["Analytics"],"description":"Returns the distinct folder paths and tags across all reports, for building the folder tree and tag filter without paging through every report. Requires analytics_editor or a broader role.\n","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"Folder paths and tags in use.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ReportFacets"}}}]}}}}}}},"/cdp/api/v1/analytics/reports/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"summary":"Get a report","operationId":"getReport","tags":["Analytics"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"The report.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ReportObject"}}}]}}}},"404":{"description":"Report not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"put":{"summary":"Replace a report definition","operationId":"updateReport","tags":["Analytics"],"description":"Recomputes min_pii_level_required and required_purposes. The result cache is keyed on updated_at, so the update invalidates stale cached results. Requires analytics_editor or a broader role.\n","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportObject"}}}},"responses":{"200":{"description":"Report updated.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ReportObject"}}}]}}}},"403":{"$ref":"#/components/responses/ManifestForbidden"},"404":{"description":"Report not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"summary":"Delete a report","operationId":"deleteReport","tags":["Analytics"],"description":"Deletes the report; dashboard items referencing it have report_id set to NULL. Requires engineer/admin.\n","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"Report deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"404":{"description":"Report not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/analytics/reports/{id}/run":{"post":{"summary":"Execute a saved report","operationId":"runReport","tags":["Analytics"],"description":"Executes the report. Applies the two-check security gate (PII access\nlevel and purpose authorization) against the caller; either failure\nreturns 403. Results are cached; pass ?force_refresh=true to\nbypass the cache. Requires analytics_editor or a broader role.\n","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"force_refresh","in":"query","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"Query result.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AnalyticsResult"}}}]}}}},"400":{"$ref":"#/components/responses/AnalyticsRefused"},"403":{"$ref":"#/components/responses/ManifestForbidden"},"404":{"description":"Report not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"$ref":"#/components/responses/AnalyticsUnavailable"},"504":{"$ref":"#/components/responses/AnalyticsTimeout"}}}},"/cdp/api/v1/analytics/metrics":{"get":{"summary":"List metrics","operationId":"listMetrics","tags":["Analytics"],"description":"Lists saved metrics ordered by folder then name, each with its latest value, next check time and last error. Same folder/tag organisation as reports. Requires analytics_viewer or a broader role. A metric whose live privacy manifest the caller does not clear is listed with `value_withheld: true` and no `last_value`, rather than omitted.\n","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"name","in":"query","description":"Exact-match filter on the metric name.","schema":{"type":"string"}},{"name":"search","in":"query","description":"Case-insensitive substring of the name or description. LIKE wildcards (`%`, `_`) are literal. `name` stays an exact match.","schema":{"type":"string"}},{"name":"folder","in":"query","description":"Filter to a folder path. Presence of the key filters even when empty, so folder= selects root-level metrics.","schema":{"type":"string"}},{"name":"subtree","in":"query","description":"With a non-empty folder, include descendant folders too.","schema":{"type":"boolean"}},{"name":"tag","in":"query","description":"Comma-separated tags; metrics must carry ALL listed tags.","schema":{"type":"string"}},{"name":"enabled","in":"query","schema":{"type":"boolean"}},{"name":"alert_enabled","in":"query","schema":{"type":"boolean"}},{"name":"page","in":"query","schema":{"type":"integer","minimum":0,"default":0}},{"name":"size","in":"query","description":"Rows per page; omit to return every metric.","schema":{"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"List of metrics.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/MetricObject"}},"page":{"$ref":"#/components/schemas/PageMeta"}}}]}}}}}},"post":{"summary":"Create a metric","operationId":"createMetric","tags":["Analytics"],"description":"Validates the definition against both the metric shape constraints (aggregate, exactly one metric, no dimensions) and the shared analytics grammar, computes min_pii_level_required / required_purposes, strips any absolute time range, and validates alert recipients against the tenant's active users. next_check_at defaults to now, so the first value appears on the next scheduler tick. Refused with 403 (data.reason pii_level or purpose_not_granted) when the author could not run the metric: a metric is computed unattended and its value is listed to every reader. Requires analytics_editor or a broader role.\n","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetricObject"}}}},"responses":{"201":{"description":"Metric created.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MetricObject"}}}]}}}},"400":{"description":"Invalid definition, a non-scalar shape, or an alert recipient that is not an active user of this workspace (the message names them).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"$ref":"#/components/responses/ManifestForbidden"},"409":{"description":"A metric with that name already exists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/analytics/metrics/facets":{"get":{"summary":"List metric folders and tags","operationId":"metricFacets","tags":["Analytics"],"description":"Distinct folder paths and tags in use, for the folder tree and tag filter.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"Facets.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MetricFacets"}}}]}}}}}}},"/cdp/api/v1/analytics/metrics/recipients":{"get":{"summary":"List selectable alert recipients","operationId":"metricRecipients","tags":["Analytics"],"description":"The email addresses that may be set as alert recipients: the active users of the calling tenant. This is the allow-list the console renders as a picker — a metric alert can only ever be sent to someone who could already read the number by logging in.\n","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"Eligible recipient addresses.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"type":"string","format":"email"}}}}]}}}}}}},"/cdp/api/v1/analytics/metrics/alerts":{"get":{"summary":"List fired metric alerts (whole tenant)","operationId":"listMetricAlerts","tags":["Analytics"],"description":"The tenant-wide alert feed, newest first. Requires analytics_viewer or a broader role. Alerts for a metric whose live privacy manifest the caller does not clear are filtered out of the feed entirely (never returned with a placeholder), and `page.total` counts only the alerts the caller may see.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","minimum":0,"default":0}},{"name":"size","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"Fired alerts.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/MetricAlertObject"}},"page":{"$ref":"#/components/schemas/PageMeta"}}}]}}}}}}},"/cdp/api/v1/analytics/metrics/preview":{"post":{"summary":"Evaluate an unsaved metric","operationId":"previewMetric","tags":["Analytics"],"description":"Computes an unsaved definition + window so the editor can show the number before the metric exists. Records nothing and never alerts. Applies the PII/purpose gate against the submitted definition. Requires analytics_editor or a broader role.\n\nThe body is MetricPreviewRequest, not MetricObject: a preview needs a query and a window, not a named metric. Unknown fields are ignored, so posting a whole MetricObject also works.\n","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetricPreviewRequest"}}}},"responses":{"200":{"description":"The computed scalar.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MetricRunResult"}}}]}}}},"400":{"$ref":"#/components/responses/AnalyticsRefused"},"403":{"$ref":"#/components/responses/ManifestForbidden"},"503":{"$ref":"#/components/responses/AnalyticsUnavailable"},"504":{"$ref":"#/components/responses/AnalyticsTimeout"}}}},"/cdp/api/v1/analytics/metrics/{id}":{"get":{"summary":"Get a metric","operationId":"getMetric","tags":["Analytics"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The metric.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MetricObject"}}}]}}}},"404":{"description":"Metric not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"put":{"summary":"Update a metric","operationId":"updateMetric","tags":["Analytics"],"description":"Replaces the metric's mutable fields. next_check_at is reset to now so an edited definition, window or interval takes effect on the next tick; recorded history and last_value are preserved — an edit is not a reason to forget the series. Refused with 403 (data.reason pii_level or purpose_not_granted) when the author could not run the edited metric. Requires analytics_editor or a broader role.\n","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetricObject"}}}},"responses":{"200":{"description":"Metric updated.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MetricObject"}}}]}}}},"403":{"$ref":"#/components/responses/ManifestForbidden"},"404":{"description":"Metric not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"summary":"Delete a metric","operationId":"deleteMetric","tags":["Analytics"],"description":"Deletes the metric; its recorded history and fired alerts cascade. Requires engineer or admin (analytics_editor may create and edit but not delete, matching reports).\n","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Metric deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"404":{"description":"Metric not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/analytics/metrics/{id}/run":{"post":{"summary":"Compute a metric now (preview)","operationId":"runMetric","tags":["Analytics"],"description":"Computes the metric's current value and records NOTHING — deliberately separate from a check, so opening the console can never move the series or fire an alert. Applies the stored PII/purpose gate. Requires analytics_editor or a broader role. Surfaced in the web console as the \"Preview\" action.\n","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The computed scalar.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MetricRunResult"}}}]}}}},"400":{"$ref":"#/components/responses/AnalyticsRefused"},"403":{"$ref":"#/components/responses/ManifestForbidden"},"404":{"description":"Metric not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"$ref":"#/components/responses/AnalyticsUnavailable"},"504":{"$ref":"#/components/responses/AnalyticsTimeout"}}}},"/cdp/api/v1/analytics/metrics/{id}/check":{"post":{"summary":"Force a scheduled check now","operationId":"checkMetric","tags":["Analytics"],"description":"Runs a full check immediately: computes, records the point, advances next_check_at, evaluates the alert rule and SENDS the alert emails. This is a real check rather than a simulation, so an operator verifying an alert configuration sees exactly what the scheduler would do. Requires analytics_editor or a broader role. Surfaced in the web console as the \"Trigger\" action.\n","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The recorded value and the alert decision.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MetricCheckResult"}}}]}}}},"400":{"$ref":"#/components/responses/AnalyticsRefused"},"403":{"$ref":"#/components/responses/ManifestForbidden"},"404":{"description":"Metric not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"$ref":"#/components/responses/AnalyticsUnavailable"},"504":{"$ref":"#/components/responses/AnalyticsTimeout"}}}},"/cdp/api/v1/analytics/metrics/{id}/values":{"get":{"summary":"Get a metric's recorded history","operationId":"getMetricValues","tags":["Analytics"],"description":"The recorded series, OLDEST first (chart order). Requires analytics_viewer or a broader role.\n","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"since","in":"query","description":"RFC3339 lower bound on computed_at.","schema":{"type":"string","format":"date-time"}},{"name":"limit","in":"query","description":"Most recent N points (default 500, max 5000).","schema":{"type":"integer","minimum":1,"maximum":5000}}],"responses":{"200":{"description":"The series.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/MetricValueObject"}}}}]}}}},"403":{"$ref":"#/components/responses/ManifestForbidden"},"404":{"description":"Metric not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/analytics/metrics/{id}/alerts":{"get":{"summary":"List a metric's fired alerts","operationId":"listMetricAlertsForMetric","tags":["Analytics"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"page","in":"query","schema":{"type":"integer","minimum":0,"default":0}},{"name":"size","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"Fired alerts for this metric.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/MetricAlertObject"}},"page":{"$ref":"#/components/schemas/PageMeta"}}}]}}}},"403":{"$ref":"#/components/responses/ManifestForbidden"},"404":{"description":"Metric not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/analytics/query":{"post":{"summary":"Execute an ad-hoc (unsaved) query","operationId":"runAdhocQuery","tags":["Analytics"],"description":"Same grammar as a report definition, executed without saving. Applies the same PII and purpose security gate against the submitted definition. Ad-hoc results are not cached. Requires analytics_editor or a broader role.\n","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueryDefinition"}}}},"responses":{"200":{"description":"Query result.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AnalyticsResult"}}}]}}}},"400":{"$ref":"#/components/responses/AnalyticsRefused"},"403":{"$ref":"#/components/responses/ManifestForbidden"},"503":{"$ref":"#/components/responses/AnalyticsUnavailable"},"504":{"$ref":"#/components/responses/AnalyticsTimeout"}}}},"/cdp/api/v1/analytics/overview":{"get":{"summary":"Home-screen overview counts","operationId":"getAnalyticsOverview","tags":["Analytics"],"description":"Aggregate counts for the console home screen: profiles per entity type, events per event type per month, whole-table totals, and the newest event timestamp (ingestion freshness). Row counts only — no attribute values are read, so no PII level or purpose is required and no `X-Purpose` header applies. Readable by analytics_viewer or a broader role.\n","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"months","in":"query","description":"Width of the event histogram in whole calendar months, ending with the current one. Default 12, maximum 24; an absent, unparseable or out-of-range value falls back rather than erroring.\n","schema":{"type":"integer","minimum":1,"maximum":24,"default":12}}],"responses":{"200":{"description":"Overview counts.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AnalyticsOverview"}}}]}}}}}}},"/cdp/api/v1/analytics/dashboards":{"get":{"summary":"List dashboards","operationId":"listDashboards","tags":["Analytics"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"List of dashboards (without items).","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DashboardObject"}}}}]}}}}}},"post":{"summary":"Create a dashboard","operationId":"createDashboard","tags":["Analytics"],"description":"Requires analytics_editor or a broader role.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DashboardObject"}}}},"responses":{"201":{"description":"Dashboard created.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DashboardObject"}}}]}}}},"400":{"description":"Invalid payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"A dashboard with that name already exists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/analytics/dashboards/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"summary":"Get a dashboard (with items)","operationId":"getDashboard","tags":["Analytics"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"The dashboard including its full item list.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DashboardObject"}}}]}}}},"404":{"description":"Dashboard not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"put":{"summary":"Update a dashboard","operationId":"updateDashboard","tags":["Analytics"],"description":"Requires analytics_editor or a broader role.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DashboardObject"}}}},"responses":{"200":{"description":"Dashboard updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"404":{"description":"Dashboard not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"summary":"Delete a dashboard","operationId":"deleteDashboard","tags":["Analytics"],"description":"Cascade-deletes its items. Requires engineer/admin.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"Dashboard deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"404":{"description":"Dashboard not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/analytics/dashboards/{id}/items":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"summary":"List dashboard items","operationId":"listDashboardItems","tags":["Analytics"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"Items for the dashboard.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DashboardItemObject"}}}}]}}}}}},"post":{"summary":"Add a dashboard item","operationId":"createDashboardItem","tags":["Analytics"],"description":"Add a report tile or markdown text block. Requires analytics_editor or a broader role.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DashboardItemObject"}}}},"responses":{"201":{"description":"Item created.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DashboardItemObject"}}}]}}}},"400":{"description":"Invalid payload or type/field mismatch.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Dashboard not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/analytics/dashboards/{id}/items/{item_id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"item_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"put":{"summary":"Update a dashboard item","operationId":"updateDashboardItem","tags":["Analytics"],"description":"Update layout, title, display_mode, content, or swap report_id. Requires analytics_editor or a broader role.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DashboardItemObject"}}}},"responses":{"200":{"description":"Item updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"404":{"description":"Item not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"summary":"Remove a dashboard item","operationId":"deleteDashboardItem","tags":["Analytics"],"description":"Requires engineer/admin.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"Item removed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"404":{"description":"Item not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/analytics/dashboards/{id}/layout":{"put":{"summary":"Bulk-update item layout","operationId":"updateDashboardLayout","tags":["Analytics"],"description":"Update col/row/w/h for many items in one request (used on drag/resize). Requires analytics_editor or a broader role.\n","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LayoutUpdate"}}}},"responses":{"200":{"description":"Layout updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"400":{"description":"A tile's geometry is outside the 12-column grid (w 1-12, h at least 1, col and row not negative, col + w at most 12). The message names the item.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"An item id was not found on this dashboard.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/signals/templates":{"get":{"summary":"List built-in signal templates","operationId":"listSignalTemplates","tags":["Signals"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"The read-only built-in template library.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SignalTemplateObject"}}}}]}}}}}}},"/cdp/api/v1/signals/templates/{name}":{"parameters":[{"name":"name","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a signal template (with its parameter schema)","operationId":"getSignalTemplate","tags":["Signals"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"The template including its parameter schema.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SignalTemplateObject"}}}]}}}},"404":{"description":"Template not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/signals/cohorts":{"get":{"summary":"List signal cohorts","operationId":"listCohorts","tags":["Signals"],"description":"Paginated. Same filter contract as `GET /signals`: `search` is a\ncase-insensitive substring match over the cohort **name and\ndescription** (LIKE metacharacters are escaped, blank is no filter).\n","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"entity_type","in":"query","required":false,"schema":{"type":"string"}},{"name":"search","in":"query","required":false,"schema":{"type":"string"},"example":"churn"},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0}},{"name":"size","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"List of cohorts.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SignalCohortObject"}}}}]}}}}}},"post":{"summary":"Create a cohort","operationId":"createCohort","tags":["Signals"],"description":"Validates the filter expression. Requires analytics_editor or a broader role.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignalCohortObject"}}}},"responses":{"201":{"description":"Cohort created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"400":{"description":"Invalid payload or filter expression.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Cohort name already exists for entity type.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/signals/cohorts/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"summary":"Get a cohort","operationId":"getCohort","tags":["Signals"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"The cohort.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SignalCohortObject"}}}]}}}},"404":{"description":"Cohort not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"put":{"summary":"Update a cohort","operationId":"updateCohort","tags":["Signals"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignalCohortObject"}}}},"responses":{"200":{"description":"Cohort updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"400":{"description":"Invalid payload or filter expression; or the name or entity_type differs from the stored cohort (both are fixed after creation).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Cohort not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"summary":"Delete a cohort","operationId":"deleteCohort","tags":["Signals"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"Cohort deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"404":{"description":"Cohort not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/signals/cohorts/{id}/members":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"size","in":"query","required":false,"schema":{"type":"integer"}},{"$ref":"#/components/parameters/PurposeHeader"}],"get":{"summary":"List a cohort's member profile IDs","operationId":"getCohortMembers","tags":["Signals"],"description":"Returns the cohort's member profile ids. Materialized cohorts serve the precomputed membership set (response reports `materialized: true` plus `refreshed_at`, the as-of instant of the answer); lazy cohorts — and materialized ones not yet refreshed — evaluate the filter expression inline over current signal values. Runs privacy enforcement (strict mode requires X-Purpose) and the cohort's purpose-group manifest.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"Matching profile IDs (paged), with `materialized` and — for materialized cohorts — `refreshed_at` freshness metadata.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CohortMembersResponse"}}}]}}}},"403":{"$ref":"#/components/responses/ManifestForbidden"},"404":{"description":"Cohort not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The cohort's filter_expr exceeded its execution budget (message names expr_budget).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/signals":{"get":{"summary":"List signal definitions","operationId":"listSignals","tags":["Signals"],"description":"Paginated. `search` is a case-insensitive substring match over the\nsignal **name and description** (LIKE metacharacters are escaped, blank\nis no filter) — the list page's search box, where signals are as often\nlooked for by what they do as by what they are called.\n","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"entity_type","in":"query","required":false,"schema":{"type":"string"}},{"name":"search","in":"query","required":false,"schema":{"type":"string"},"example":"churn"},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0}},{"name":"size","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"List of signal definitions with page metadata.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SignalObject"}}}}]}}}}}},"post":{"summary":"Create a signal","operationId":"createSignal","tags":["Signals"],"description":"Validates the template and its parameters. Requires engineer/admin.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignalObject"}}}},"responses":{"201":{"description":"Signal created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"400":{"description":"Invalid payload or template parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Signal name already exists for entity type.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/signals/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"summary":"Get a signal definition","operationId":"getSignal","tags":["Signals"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"The signal definition.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SignalObject"}}}]}}}},"404":{"description":"Signal not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"put":{"summary":"Update a signal","operationId":"updateSignal","tags":["Signals"],"description":"Requires engineer/admin.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignalObject"}}}},"responses":{"200":{"description":"Signal updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"400":{"description":"Invalid payload or template parameters; or the name or entity_type differs from the stored signal (both are fixed after creation).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Signal not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"summary":"Delete a signal","operationId":"deleteSignal","tags":["Signals"],"description":"Requires engineer/admin.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"Signal deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"404":{"description":"Signal not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/signals/{id}/run":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"summary":"Enqueue a full recompute of a signal's entity type","operationId":"runSignal","tags":["Signals"],"description":"Enqueues every profile of the signal's entity type for background recomputation. Requires engineer/admin. Rejected with 400 for kind=external signals (nothing here computes them).","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"Recompute enqueued (returns total_profiles and enqueued counts).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"400":{"description":"The signal is external.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Signal not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/signals/{id}/values":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"summary":"Push external signal values (bulk)","operationId":"pushSignalValues","tags":["Signals"],"description":"Bulk ingress for a `kind: external` signal — the customer's own model pushes scored rows. Each row is resolved to a profile (by `profile_id` or by one identifier of the signal's entity type; resolve-only, a push never creates profiles), validated against the definition's `output_type`, run through `transform_expr`, and written with provenance `source: push`. Per-row failures (unknown profile, wrong entity type, uncoercible value) are reported in `skipped` and never fail the batch. `computed_at` defaults to now; `valid_until` defaults to `computed_at + recompute_interval`. Batch size is capped by the `signal_push_max_batch` instance setting (default 10000). Requires a purpose declaration in strict privacy mode — this writes customer data. Requires engineer/admin.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"X-Purpose","in":"header","required":false,"schema":{"type":"string"},"description":"Declared processing purposes (comma-separated). Required in strict privacy mode."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["values"],"properties":{"values":{"type":"array","items":{"type":"object","required":["value"],"properties":{"profile_id":{"type":"string","format":"uuid","description":"Direct profile reference. Either this or identifier is required."},"identifier":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"}},"description":"One identifier of the signal's entity type; entity-scoped resolve-only lookup."},"value":{"description":"The score. Coerced to the definition's output_type: numeric/boolean types accept JSON numbers, bools and numeric strings; string types require a string."},"computed_at":{"type":"string","format":"date-time","description":"When the model scored this profile. Defaults to now. Also serves as the dedup version — an older replay never overwrites a newer value."},"valid_until":{"type":"string","format":"date-time","description":"Defaults to computed_at + recompute_interval."},"model_version":{"type":"string","description":"The producing model version, stored on the value row."}}}}}}}}},"responses":{"200":{"description":"Accepted; per-row outcomes.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"written":{"type":"integer"},"skipped":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"reason":{"type":"string"}}}}}}}}]}}}},"400":{"description":"Not an external signal, inactive signal, empty batch, or batch over signal_push_max_batch.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Signal not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Write queue unavailable — nothing was written for the failing shard.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/profiles/{profile_id}/signals":{"parameters":[{"name":"profile_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"summary":"Get a profile's current signal values","operationId":"getProfileSignals","tags":["Signals"],"description":"Returns each active signal's value with freshness metadata; stale values are recomputed inline (best-effort) unless `signal_refresh=cached`, which serves stored values and only computes a signal with none.","parameters":[{"name":"signal_refresh","in":"query","description":"`inline` (default) recomputes stale or missing values; `cached` serves stored values and only computes a missing one. Any other value is a 400.","schema":{"type":"string","enum":["inline","cached"],"default":"inline"}}],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"The profile's signal values.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SignalValueObject"}}}}]}}}},"400":{"description":"Invalid profile_id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Profile not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/profiles/{profile_id}/signals/recompute":{"parameters":[{"name":"profile_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"summary":"Force-recompute a profile's signals","operationId":"recomputeProfileSignals","tags":["Signals"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"Recomputed signal values.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SignalValueObject"}}}}]}}}},"400":{"description":"Invalid profile_id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Profile not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/profiles/{profile_id}/signals/{name}/history":{"parameters":[{"name":"profile_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"name","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":100}}],"get":{"summary":"Get a signal's value over time for a profile","operationId":"getProfileSignalHistory","tags":["Signals"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"Signal value history (most recent first).","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SignalValueObject"}}}}]}}}},"400":{"description":"Invalid profile_id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/identity/rulesets":{"get":{"summary":"List identity rulesets","operationId":"listRulesets","tags":["Identity"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"entity_type","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"List of rulesets.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/RulesetObject"}}}}]}}}}}},"post":{"summary":"Create a ruleset","operationId":"createRuleset","tags":["Identity"],"description":"Requires engineer/admin.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RulesetObject"}}}},"responses":{"201":{"description":"Ruleset created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"400":{"description":"Invalid payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Ruleset name already exists for entity type.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/identity/rulesets/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"summary":"Get a ruleset (with its rules)","operationId":"getRuleset","tags":["Identity"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"The ruleset including its rules.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RulesetObject"}}}]}}}},"404":{"description":"Ruleset not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"put":{"summary":"Update a ruleset","operationId":"updateRuleset","tags":["Identity"],"description":"Requires engineer/admin.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RulesetObject"}}}},"responses":{"200":{"description":"Ruleset updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"404":{"description":"Ruleset not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"summary":"Delete a ruleset","operationId":"deleteRuleset","tags":["Identity"],"description":"Cascade-deletes its rules. Requires engineer/admin.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"Ruleset deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"404":{"description":"Ruleset not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/identity/rulesets/{id}/activate":{"post":{"summary":"Activate a ruleset","operationId":"activateRuleset","tags":["Identity"],"description":"Atomically deactivates any other active ruleset for the same entity type. Requires engineer/admin.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Ruleset activated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"404":{"description":"Ruleset not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/identity/rulesets/{id}/deactivate":{"post":{"summary":"Deactivate a ruleset","operationId":"deactivateRuleset","tags":["Identity"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Ruleset deactivated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"404":{"description":"Ruleset not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/identity/rulesets/{id}/rules":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"summary":"List rules in a ruleset","operationId":"listRules","tags":["Identity"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"Rules ordered by priority.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/RuleObject"}}}}]}}}}}},"post":{"summary":"Add a rule","operationId":"createRule","tags":["Identity"],"description":"Requires engineer/admin. Matcher grammar is validated.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RuleObject"}}}},"responses":{"201":{"description":"Rule created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"400":{"description":"Invalid payload or matcher grammar.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Ruleset not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/identity/rulesets/{id}/rules/{rule_id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"rule_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"put":{"summary":"Update a rule","operationId":"updateRule","tags":["Identity"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RuleObject"}}}},"responses":{"200":{"description":"Rule updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"400":{"description":"Invalid matcher grammar.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Rule not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"summary":"Delete a rule","operationId":"deleteRule","tags":["Identity"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"Rule deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"404":{"description":"Rule not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/identity/resolve":{"post":{"summary":"Resolve a profile or identifier set","operationId":"resolveIdentity","tags":["Identity"],"description":"Runs the active ruleset for the entity type over the seed's candidate set (profiles sharing a normalized identifier value) and returns the resulting cluster. dry_run=true computes without writing. Requires analytics_editor or a broader role.\n","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResolveRequest"}}}},"responses":{"200":{"description":"The resolved cluster (and which rules fired).","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ResolveResult"}}}]}}}},"400":{"description":"Missing seed or no active ruleset for the entity type.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/identity/persons":{"post":{"summary":"Resolve profiles to persons","operationId":"resolvePersons","tags":["Identity"],"description":"Batched \"which profiles are the same person\" read for the campaign suite: ids and link confidences only, no PII. Answers per the tenant's campaign_identity_scope setting — \"profile\" returns one single-member person per requested id without any identity lookup; \"person\" (the default) resolves each id's identity cluster, filtering members by identity_min_cluster_confidence and contact_members by campaign_contact_min_confidence.\n","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResolvePersonsRequest"}}}},"responses":{"200":{"description":"Resolved persons, keyed by the queried profile id.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ResolvePersonsResponse"}}}]}}}},"400":{"description":"profile_ids must hold 1-500 UUIDs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Person resolution failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/identity/rulesets/{id}/run":{"post":{"summary":"Bulk re-resolve a ruleset's entity type","operationId":"runRuleset","tags":["Identity"],"description":"Enqueues every profile of the ruleset's entity type for asynchronous re-resolution; the queue is drained in the background. Requires engineer/admin.\n","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Profiles enqueued for re-resolution.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"entity_type":{"type":"string"},"total_profiles":{"type":"integer"},"enqueued":{"type":"integer","description":"Newly-enqueued (excludes already-pending)."}}}}}]}}}},"404":{"description":"Ruleset not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/identity/clusters/{cluster_id}":{"get":{"summary":"Get cluster details + members","operationId":"getCluster","tags":["Identity"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"cluster_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Cluster membership.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ClusterObject"}}}]}}}},"404":{"description":"Cluster not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/profiles/link-topology":{"get":{"summary":"Entity-pair link topology","description":"Aggregate counts of profile_links grouped by the entity types of both endpoints (no profile data). Filter-building UIs use it to hint which related-entity hops actually exist in the data.\n","operationId":"getLinkTopology","tags":["Profiles"],"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"responses":{"200":{"description":"`data` is a list of {parent_entity, child_entity, links}.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/LinkTopologyEntry"}}}}]}}}}}}},"/cdp/api/v1/profiles/link-relation-types":{"get":{"summary":"Relation types present in profile links","description":"Aggregate counts of profile_links grouped by `relation_type` (no profile data), most-used first, capped at 200. Authoring UIs offer these as the relation-type vocabulary — the column is free-form, so the data is the only catalogue there is.\n","operationId":"getLinkRelationTypes","tags":["Profiles"],"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"responses":{"200":{"description":"`data` is a list of {relation_type, links}.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/LinkRelationTypeEntry"}}}}]}}}}}}},"/cdp/api/v1/profiles/{profile_id}/cluster":{"get":{"summary":"Get a profile's identity cluster","operationId":"getProfileCluster","tags":["Identity"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"profile_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The cluster the profile belongs to.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ClusterObject"}}}]}}}},"400":{"description":"Invalid profile_id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Profile has no resolved cluster.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/connect/connectors":{"get":{"summary":"List connectors","operationId":"listConnectors","tags":["Connect"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"kind","in":"query","required":false,"schema":{"type":"string","enum":["batch_source","batch_sink","stream_source","stream_sink"]}},{"name":"protocol","in":"query","required":false,"schema":{"type":"string","enum":["sftp","s3","gcs","azure_blob","kafka","nats","upload","sql"]},"description":"Only connectors of this protocol (ANDs with kind). An unknown value is a 400."},{"name":"page","in":"query","schema":{"type":"integer","minimum":0,"default":0}},{"name":"size","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":100},"description":"Omitted size defaults to the 100-row page cap."},{"name":"sort_by","in":"query","schema":{"type":"string","enum":["name","kind","protocol","data_type","is_active","created_at","updated_at"]}},{"name":"sort_dir","in":"query","schema":{"type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"List of connectors.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ConnectorResponse"}}}}]}}}},"400":{"description":"Invalid pagination or an unknown protocol.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a connector","operationId":"createConnector","tags":["Connect"],"description":"Requires engineer/admin.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorRequest"}}}},"responses":{"201":{"description":"Connector created.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ConnectorResponse"}}}]}}}},"400":{"description":"Invalid payload (including a blank dataset_name when data_type=custom_dataset).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The requested (or, on update without privacy, the stored) clearance exceeds the saver's own purposes or PII level, or connection.export_filter reads a field above the connector's clearance (ManifestForbiddenResponse body: data.reason / data.field).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManifestForbiddenResponse"}}}},"409":{"description":"Connector name already exists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/connect/connectors/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"summary":"Get a connector","operationId":"getConnector","tags":["Connect"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"The connector.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ConnectorResponse"}}}]}}}},"404":{"description":"Connector not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"put":{"summary":"Update a connector","operationId":"updateConnector","tags":["Connect"],"description":"Requires engineer/admin.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorRequest"}}}},"responses":{"200":{"description":"Connector updated.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ConnectorResponse"}}}]}}}},"400":{"description":"Invalid payload (including a blank dataset_name when data_type=custom_dataset).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The requested (or, on update without privacy, the stored) clearance exceeds the saver's own purposes or PII level, or connection.export_filter reads a field above the connector's clearance (ManifestForbiddenResponse body: data.reason / data.field).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManifestForbiddenResponse"}}}},"404":{"description":"Connector not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"credentials_required — `kind`, `protocol`, `connection.network_id` or an endpoint key (sftp host/port/insecure_skip_host_key, nats url, kafka brokers/tls/tls_server_name, sql dialect/host/port/database/ssl_mode/tls/workspace_url/account, s3/gcs endpoint/bucket, azure_blob endpoint/account_name) changed while the stored credentials would be kept. Re-send `credentials`, or `{}` to clear them.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CredentialsRequiredResponse"}}}}}},"delete":{"summary":"Delete a connector","operationId":"deleteConnector","tags":["Connect"],"description":"Requires engineer/admin.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"Connector deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"404":{"description":"Connector not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/connect/connectors/{id}/active":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"patch":{"summary":"Enable or disable a connector","operationId":"setConnectorActive","tags":["Connect"],"description":"Requires engineer/admin.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["active"],"properties":{"active":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Connector active state updated.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ConnectorResponse"}}}]}}}},"400":{"description":"body must be {\"active\": bool}.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Connector not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/connect/connectors/{id}/mappings":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"summary":"Get field mappings for a connector","operationId":"getFieldMappings","tags":["Connect"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"Field mappings.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/FieldMappingResponse"}}}}]}}}},"404":{"description":"Connector not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"put":{"summary":"Replace all field mappings (full replace, idempotent)","operationId":"upsertFieldMappings","tags":["Connect"],"description":"Replaces all existing mappings atomically. Requires engineer/admin. On batch sources mappings define CSV column parsing; on batch sinks they define the export column projection (which fields ship, under which CSV headers, in sort_order — no mappings = the data type's default columns) and target_field is validated against the export token grammar. Batch-source imports of profiles/events/consents require at least one identifier.* mapping (rows are matched or created by identifier); omitting it returns 400.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/FieldMappingRequest"}}}}},"responses":{"200":{"description":"Field mappings saved.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/FieldMappingResponse"}}}}]}}}},"400":{"description":"Invalid payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Connector not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/connect/connectors/{id}/schedule":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"summary":"Get the batch schedule for a connector","operationId":"getBatchSchedule","tags":["Connect"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"Batch schedule.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BatchScheduleResponse"}}}]}}}},"404":{"description":"Connector or schedule not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"put":{"summary":"Create or update the batch schedule","operationId":"upsertBatchSchedule","tags":["Connect"],"description":"Requires engineer/admin.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchScheduleRequest"}}}},"responses":{"200":{"description":"Schedule saved.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BatchScheduleResponse"}}}]}}}},"400":{"description":"Invalid payload, or an export_filter whose privacy manifest cannot be built (an unknown dataset or key; the message names it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"$ref":"#/components/responses/ManifestForbidden"},"404":{"description":"Connector not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The export_filter's privacy manifest could not be evaluated (a schema read failed). Nothing was saved.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/connect/connectors/{id}/export/preview":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"summary":"Preview the row count a batch export would write","operationId":"previewExport","tags":["Connect"],"description":"Batch sink connectors only. Estimates how many rows an export run would write for the given filter, without exporting. Requires engineer/admin. The count already reflects the filter's row limit. The filter is authorised against the connector's privacy clearance and against the caller.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"requestBody":{"required":false,"description":"Optional. When export_filter is provided it is previewed as-is (so the console can preview an unsaved edit); when omitted, the connector's stored schedule filter is used.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExportPreviewRequest"}}}},"responses":{"200":{"description":"Estimated export size.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ExportPreviewResponse"}}}]}}}},"400":{"description":"Not a batch sink, or the filter/preview query failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"$ref":"#/components/responses/ManifestForbidden"},"404":{"description":"Connector not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/connect/connectors/{id}/script":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"direction","in":"query","schema":{"type":"string","enum":["import","export"],"default":"import"}}],"get":{"summary":"Get the Starlark transform script","operationId":"getTransformScript","tags":["Connect"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"Transform script.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TransformScriptResponse"}}}]}}}},"404":{"description":"Connector or script not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"put":{"summary":"Create, update, or remove the Starlark transform script","operationId":"upsertTransformScript","tags":["Connect"],"description":"Requires engineer/admin. Sending an empty (or whitespace-only) `script` removes any stored transform for the direction so the connector runs transform-free — clearing the editor and saving is a supported no-op when nothing is stored.\n","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransformScriptRequest"}}}},"responses":{"200":{"description":"Script saved.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TransformScriptResponse"}}}]}}}},"400":{"description":"Invalid body, script over 64 KiB, or a script that fails to compile (including one that exceeds its step/memory/time budget — message contains script_budget).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Connector not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"summary":"Delete the transform script","operationId":"deleteTransformScript","tags":["Connect"],"description":"Requires engineer/admin.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"Script deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"404":{"description":"Script not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/connect/connectors/{id}/script/test":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"summary":"Dry-run a Starlark transform script against a sample payload","operationId":"testTransformScript","tags":["Connect"],"description":"Compiles the supplied script and runs its transform(payload) function against a sample JSON payload without saving anything or touching the data plane. Surfaces compile/runtime errors, the None-skip decision, and the extracted record so an operator can validate a script before committing it. Requires engineer/admin. The connector must exist, but its stored script is not used.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransformTestRequest"}}}},"responses":{"200":{"description":"Test outcome (a compile or runtime failure is reported in data.error with 200).","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TransformTestResponse"}}}]}}}},"400":{"description":"Invalid request body, script over 64 KiB or payload over 1 MiB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Connector not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/connect/connectors/{id}/script/assist":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"summary":"AI code assistant for the Starlark transform editor","operationId":"assistTransformScript","tags":["Connect"],"description":"Turns a natural-language request into a candidate Starlark transform script for a streaming connector, using the configured LLM. The system prompt teaches the model the transform contract, the Starlark dialect the runtime executes, and the direction- and data_type-specific payload/record shapes; the script direction is derived from the connector kind (stream_source = import, stream_sink = export). The generated code is advisory only — it is never saved; the operator copies it into the editor or discards it. The model may also answer that the request cannot be fulfilled (data.feasible = false, with the reason in data.notes). Generated code gets a server-side compile check (data.compile_ok / data.compile_error); code that fails it is sent back to the model with the compile error for up to 2 self-repair rounds (data.repair_rounds) before the last draft is returned as-is. Requires engineer/admin.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransformAssistRequest"}}}},"responses":{"200":{"description":"Assist outcome (feasible code, or a reasoned \"cannot be done\").","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TransformAssistResponse"}}}]}}}},"400":{"description":"Invalid body, missing prompt, or not a streaming connector.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"$ref":"#/components/responses/AIDelegationForbidden"},"404":{"description":"Connector not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"$ref":"#/components/responses/AIRateLimited"},"502":{"description":"The LLM request failed or returned an unparseable response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"LLM features are disabled on this instance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/connect/connectors/{id}/uploads":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"summary":"List uploaded CSV files (upload-protocol import connectors)","operationId":"listConnectorUploads","tags":["Connect"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"Uploaded files (metadata).","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/UploadedFileResponse"}}}}]}}}},"404":{"description":"Connector not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Upload a CSV file for an upload-protocol import connector","operationId":"uploadConnectorFile","description":"Multipart form with a single \"file\" field. Only valid for batch_source connectors with protocol \"upload\". Size capped at 25 MB by default.","tags":["Connect"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary"}}}}}},"responses":{"200":{"description":"File stored.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/UploadedFileResponse"}}}]}}}},"400":{"description":"Not an upload connector, or missing file field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Connector not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"413":{"description":"File exceeds the maximum upload size.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/connect/connectors/{id}/uploads/{upload_id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"upload_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"delete":{"summary":"Delete an uploaded CSV file","operationId":"deleteConnectorUpload","tags":["Connect"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"Deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"404":{"description":"File or connector not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/connect/runs":{"get":{"summary":"List runs across every connector","operationId":"listConnectorRuns","tags":["Connect"],"description":"The estate-wide run feed, newest first. The per-connector history answers\n\"how is THIS connector doing\"; this answers \"is anything broken\", which\notherwise costs one request per connector.\n\nEach entry carries the connector's name, kind and data type alongside the\nrun, so a caller who has not picked a connector can still read the answer.\nRuns whose connector has been deleted are omitted — they are history\nnobody can act on.\n","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["running","success","partial","failed"]},"description":"Omitted = every status. An unrecognised value is a 400, never a silent empty result."},{"name":"since","in":"query","schema":{"type":"string","format":"date-time"},"description":"RFC3339 lower bound on started_at."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"`data` is {runs[], total, connectors}. `total` counts every matching run and `connectors` the distinct connectors they belong to — both about the whole match, not the page: 40 failures on one connector and 40 connectors failing once are the same total and different problems.\n","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"runs":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/RunLogResponse"},{"type":"object","properties":{"connector_name":{"type":"string"},"connector_kind":{"type":"string"},"data_type":{"type":"string"}}}]}},"total":{"type":"integer","format":"int64"},"connectors":{"type":"integer","format":"int64"}}}}}]}}}},"400":{"description":"Unknown status, unparseable since, or an out-of-range limit/offset.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/connect/connectors/{id}/runs":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"summary":"List run logs for a connector","operationId":"listRunLogs","tags":["Connect"],"description":"For batch connectors, one entry per run. For streaming connectors, one entry per stream\nconnection \"session\": status=running while the stream is connected, with rows_processed /\nrows_failed / rows_skipped updated live (~10s flush); the session finishes on stop, config\nreload, or error (clean stop with terminal message failures ends as partial).\n","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","minimum":0,"default":0}},{"name":"size","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":100},"description":"Omitted size defaults to the 100-row page cap."},{"name":"sort_by","in":"query","schema":{"type":"string","enum":["started_at","finished_at","status","rows_processed","rows_failed"]}},{"name":"sort_dir","in":"query","schema":{"type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"Run log entries.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/RunLogResponse"}}}}]}}}},"404":{"description":"Connector not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/connect/connectors/{id}/runs/{run_id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"run_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"summary":"Get a single run log entry","operationId":"getRunLog","tags":["Connect"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"Run log entry.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RunLogResponse"}}}]}}}},"400":{"description":"Malformed id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Run log not found, or it belongs to a different connector.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/connect/connectors/{id}/stream-log":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"summary":"List recent stream samples and errors for a streaming connector","operationId":"listStreamLog","tags":["Connect"],"description":"Returns recent connect_stream_log entries, newest first: rate-limited samples of stream\nmessages (kind=sample; payload before and — when a transform script ran — after\ntransformation) and recent processing errors (kind=error). Written best-effort by the\nthe stream runtime (at most one sample per sampling interval per connector,\nerrors throttled to one per ~5s), pruned after the retention period (default\n7) — a bounded debugging window, not an archive. Payload excerpts are capped at 4 KB.\n","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"kind","in":"query","schema":{"type":"string","enum":["sample","error"]},"description":"Restrict to samples or errors; omitted returns both."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"since","in":"query","schema":{"type":"string","format":"date-time"},"description":"Only entries logged at or after this RFC3339 timestamp."}],"responses":{"200":{"description":"Stream log entries, newest first.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StreamLogEntryResponse"}}}}]}}}},"400":{"description":"Malformed id, kind, limit, or since.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Connector not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/connect/connectors/{id}/trigger":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"summary":"Trigger a manual batch import run","operationId":"triggerConnector","tags":["Connect"],"description":"Creates a run_log row with status=running. The connector service picks it up\non its next 30-second poll. Returns 202 Accepted immediately with the run_id.\nThe connector must be active (is_active=true). One run per connector at a time:\nwhile the connector has a run in flight (executing, or queued and not yet\npicked up) the trigger is refused with 409 and data.run_id names that run;\nnothing is queued. Scheduled (cron) occurrences that land while a run is in\nflight are skipped the same way.\n","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"202":{"description":"Run queued.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TriggerResponse"}}}]}}}},"400":{"description":"Connector is not active.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Connector not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The connector already has a run in flight. Nothing was queued; data.run_id is the run in flight.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TriggerResponse"}}}]}}}}}}},"/cdp/api/v1/ai/explain":{"post":{"summary":"AI assist — explain operator-facing text","operationId":"aiExplain","tags":["AI"],"description":"Generic LLM explanation of operator-facing text. `kind` selects the assistant\nbehaviour (\"error\" — diagnose an error message and suggest fixes; default).\nNo customer data flows through this endpoint — callers send system/diagnostic\ntext plus optional labelled context (connector name, protocol, …).\nRequires LLM features enabled on the instance (503 otherwise). Roles: engineer, admin, analytics_editor.\n","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AIExplainRequest"}}}},"responses":{"200":{"description":"Explanation generated.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AIExplainResponse"}}}]}}}},"400":{"description":"Invalid payload or unsupported kind.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"$ref":"#/components/responses/AIDelegationForbidden"},"429":{"$ref":"#/components/responses/AIRateLimited"},"502":{"description":"LLM request failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"LLM features disabled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/llm/providers":{"get":{"summary":"List the tenant's LLM providers","operationId":"listLLMProviders","tags":["AI"],"description":"Bring your own LLM — per-tenant provider rows the AI features resolve at request time (the default active row wins; no row falls back to the instance-wide LLM unless the tenant's `llm_fallback` setting is `deny`). No widening role policies exist for /llm/*, so this surface is reachable only by the tenant admin role and instance_admin/root — a provider row is an egress decision. Credentials are write-only; responses carry `has_credentials`.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"Providers (default first).","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/LLMProviderObject"}}}}]}}}}}},"post":{"summary":"Register an LLM provider","operationId":"createLLMProvider","tags":["AI"],"description":"The tenant's FIRST provider becomes the default automatically. `api_key` is optional — the keyless case (a self-hosted, network-authenticated endpoint) is first-class; when present it is stored AES-256-GCM encrypted. Setting `max_pii_level` above the instance ceiling requires instance_admin. Only `provider_type: openai_compatible` is accepted in this phase. An `api_host` that is a literal private, loopback, link-local or metadata address (or `localhost`) is refused with 400 `api_host: ...` (image providers included); hostnames are checked again when dialled. Loopback is always refused; another private range is accepted only if your platform operator has allowed it.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LLMProviderObject"}}}},"responses":{"201":{"description":"Provider created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"400":{"description":"Invalid payload or unsupported provider_type.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"max_pii_level above the instance ceiling without instance_admin.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Provider name already exists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Credential encryption unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/llm/providers/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"summary":"Get an LLM provider","operationId":"getLLMProvider","tags":["AI"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"The provider (no credential).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"404":{"description":"Provider not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"put":{"summary":"Update an LLM provider","operationId":"updateLLMProvider","tags":["AI"],"description":"Credentials are write-only: omit `api_key` to keep the stored one, set it to replace, or set `clear_credentials: true` to switch the provider keyless. Same instance_admin gate on raising `max_pii_level`. Prices are replaced only when sent: an update with none of `price_input_per_mtok`, `price_output_per_mtok` and `price_currency` keeps the stored prices, and `clear_prices: true` removes them (combining it with price fields is a 400). `purpose` is immutable — send it unchanged or omit it; a different value is a 422. Changing provider_type or api_host requires re-sending api_key (or clear_credentials); otherwise the update returns 409 `credentials_required`. An unchanged `api_host` is re-checked against the private-address rule only when the provider is being activated, so a provider saved before the check existed can still be deactivated.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LLMProviderObject"}}}},"responses":{"200":{"description":"Provider updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"400":{"description":"Invalid payload, or a provider_type that cannot serve the purpose.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"max_pii_level above the instance ceiling without instance_admin.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Provider not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"credentials_required — `provider_type` or `api_host` changed while the stored `api_key` would be kept. Re-send with `api_key`, or set `clear_credentials: true`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CredentialsRequiredResponse"}}}},"422":{"description":"Attempted to change an existing provider's purpose.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"summary":"Delete an LLM provider","operationId":"deleteLLMProvider","tags":["AI"],"description":"Deleting the default promotes the newest remaining active provider. A tenant left with no rows resolves to the instance default under `llm_fallback: allow`, or 503s under `deny` — never silently.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"Provider deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"404":{"description":"Provider not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/llm/providers/{id}/test":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"summary":"Live-probe an LLM provider","operationId":"testLLMProvider","tags":["AI"],"description":"The probe matches the provider's purpose. TEXT providers get one real completion asking for an exact JSON object, reporting `success` (the call completed), `structured_output` (the reply parsed as JSON — the part that predicts whether journey drafting will work), `latency_ms` and the trimmed raw output; on success the verdict is persisted onto the row's `capabilities.supports_json_object` (hand-overridable afterwards). IMAGE providers instead generate one small test image, which is discarded but DOES count against the daily generation quota — the provider billed for it either way, and a probe spending outside the ledger would make the limit a lie; `structured_output` is always false there, as there is no such question to ask an image backend. Either probe bypasses the llm_enabled kill switch (operators verify providers while setting up) but honours the tenant's outbound mode — allowed in sink, refused in off (409).","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"Probe verdict: {success, structured_output, latency_ms, message, output}.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"403":{"$ref":"#/components/responses/AIDelegationForbidden"},"404":{"description":"Provider not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Tenant outbound mode is off.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"$ref":"#/components/responses/AIRateLimited"},"503":{"description":"Credential decryption failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/llm/providers/{id}/default":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"summary":"Make a provider the tenant's default","operationId":"setDefaultLLMProvider","tags":["AI"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"Default set.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"404":{"description":"Provider not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/connect/reencrypt":{"post":{"summary":"Re-encrypt every stored credential with the current key","operationId":"reencryptConnectorCredentials","tags":["Connect"],"description":"Key rotation: every stored credential blob of the tenant (connector and private-network credentials, webhook signing secrets, LLM provider keys, notification provider passwords) that fails to decrypt with the current key is decrypted with the previous key and re-encrypted with the current key. Already-current blobs are untouched. The result is reported per family. Instance secrets are instance-wide: they are resealed, and reported under instance_secrets, only when the caller is an instance admin (root key or instance_admin); the other families are those of the resolved tenant, so call it once per tenant. Campaign credentials that share this key are resealed by POST /campaign/api/v1/channels/reencrypt. Not licence-gated. Requires engineer/admin.\n","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"Per-family results.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"connectors":{"$ref":"#/components/schemas/ReencryptResult"},"networks":{"$ref":"#/components/schemas/ReencryptResult"},"notification_secrets":{"$ref":"#/components/schemas/ReencryptResult"},"llm_providers":{"$ref":"#/components/schemas/ReencryptResult"},"notification_providers":{"$ref":"#/components/schemas/ReencryptResult"},"instance_secrets":{"$ref":"#/components/schemas/ReencryptResult","description":"Instance admins only; ids are setting keys."}}}}}]}}}},"503":{"description":"Encryption key not configured / old key invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/connect/connectors/{id}/test":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"summary":"Test connector connectivity","operationId":"testConnector","tags":["Connect"],"description":"Performs a non-destructive connectivity check against the connector's external system.\nDecrypts credentials, builds the appropriate client, and verifies access:\n- **batch_source**: calls `ListObjects` with a 10-second timeout; returns up to 5 object\n  keys in `details`.\n- **batch_sink / stream_sink**: validates that connection parameters are sufficient to\n  construct the client.\n- **stream_source**: validates that connection parameters are sufficient to construct the\n  source (does not consume messages).\n\nNo run_log row is created. The check runs synchronously; the caller waits for the result.\nRequires engineer/admin.\n","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"Connection test completed (check `data.success` for outcome).","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TestConnectionResponse"}}}]}}}},"404":{"description":"Connector not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Sink-kind connector while the tenant's outbound mode is `off` (Environments); probes stay allowed in `sink`, and source probes are never gated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal error (e.g. credential decryption failed).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Encryption key not configured.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/connect/sql-transforms":{"get":{"summary":"List SQL transforms","operationId":"listSQLTransforms","tags":["Connect"],"description":"Scheduled SQL transforms: a statement run on a warehouse connector, or a saved\naggregate report materialised into a custom dataset. Definitions are control-plane\nconfiguration (no customer data), so no `X-Purpose` is required. Requires the\n`connectors` and `warehouse` features; integration_viewer and analytics_viewer read; integration_editor, engineer and admin write.\n\nEach row carries its most recent run, so the list can answer \"does this work\"\nwithout one request per transform.\n","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"List of transforms, newest first.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SQLTransform"}}}}]}}}},"403":{"description":"The connectors or warehouse feature is not licensed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a SQL transform","operationId":"createSQLTransform","tags":["Connect"],"description":"Requires engineer/admin. Everything decidable from the payload is decided here rather\nthan left to fail as a scheduled run nobody is watching: the target's field group must\nbe complete, a warehouse `connector_id` must exist and use protocol=sql, its\n`statement` must carry no token other than `{cursor}`/`{now}`, a dataset `report_id`\nmust exist and be an aggregate report, `dataset_name` must exist, and `cron_expr` /\n`timezone` must parse.\n\n**Dataset transforms additionally apply the analytics execution gate** (PII level +\npurpose authorization) to the referenced report, at create AND update: a scheduled run\nhas no caller to check, so the transform inherits its author's entitlement at save\ntime. If you may not run the report now, you may not arrange for it to be run nightly.\nThe materialised dataset itself carries no purposes — custom datasets are outside\npurpose semantics.\n\nSaving snapshots the report's definition hash and live manifest; a later run of an\nedited report fails `report_changed`, of a reclassified one `classification_raised` —\nre-save to re-authorise.\n","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SQLTransformRequest"}}}},"responses":{"201":{"description":"Transform created.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SQLTransform"}}}]}}}},"400":{"description":"Invalid payload (unknown target, missing or unknown reference, bad statement token, bad cron or timezone).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"$ref":"#/components/responses/ManifestForbidden"},"409":{"description":"Transform name already exists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/connect/sql-transforms/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"summary":"Get a SQL transform","operationId":"getSQLTransform","tags":["Connect"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"The transform, with its most recent run.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SQLTransform"}}}]}}}},"404":{"description":"Transform not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"put":{"summary":"Update a SQL transform","operationId":"updateSQLTransform","tags":["Connect"],"description":"Requires engineer/admin. Full replacement of the editable fields, validated exactly as\non create — including the execution gate for dataset transforms, because an editor who\nmay not run a report must not be able to repoint a transform at it. `next_run_at` is\ncleared: the definition that produced the pending due time has just changed.\n\nSaving snapshots the report's definition hash and live manifest; a later run of an\nedited report fails `report_changed`, of a reclassified one `classification_raised` —\nre-save to re-authorise.\n","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SQLTransformRequest"}}}},"responses":{"200":{"description":"Transform updated.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SQLTransform"}}}]}}}},"400":{"description":"Invalid payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"$ref":"#/components/responses/ManifestForbidden"},"404":{"description":"Transform not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Transform name already exists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"summary":"Delete a SQL transform","operationId":"deleteSQLTransform","tags":["Connect"],"description":"Requires engineer/admin. The transform's run history cascades.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"Transform deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"404":{"description":"Transform not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/connect/sql-transforms/{id}/active":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"summary":"Pause or resume a SQL transform","operationId":"setSQLTransformActive","tags":["Connect"],"description":"Requires engineer/admin. Pausing clears `next_run_at`, so resuming does not immediately\nfire an occurrence that came due while the transform was off — the scheduler recomputes\nthe next one from `cron_expr`.\n","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["active"],"properties":{"active":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Transform active state updated. The response carries last_run, like every other read of a transform.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SQLTransform"}}}]}}}},"400":{"description":"Body must be {\"active\": bool}. An absent `active` is refused rather than read as false.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Transform not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/connect/sql-transforms/{id}/run":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"summary":"Run a SQL transform now","operationId":"runSQLTransform","tags":["Connect"],"description":"Requires engineer/admin. Queues an unclaimed run row which the Connect service picks up\non its next cycle — the same path a triggered connector run takes. Nothing executes\ninside the request, so the 202 means \"queued\", not \"done\"; poll\nGET /connect/sql-transforms/{id}/runs for the outcome.\n\nA paused transform answers 409: the runner executes any unclaimed pending row without\nconsulting `is_active`, so \"paused\" is enforced here or nowhere.\n\n**Dataset transforms re-apply the analytics execution gate** (PII level + purpose\nauthorization) to the referenced report before anything is queued. Gating only the save\nwould leave \"run now\" as a way to launder a report execution around the gate — the\ncaller pressing it is not necessarily the author whose entitlement the transform was\nsaved under. Deleting a report CASCADES to its dataset transforms, so a transform whose\nreport is gone does not exist either: that case answers 404, not 409.\n\n`force_sweep=true` lifts the dataset sweep's 50% guard for this run only: a run that\nwould delete more than half of the records the transform owns deletes nothing unless\nit was queued with this flag. A report that reached its row limit is never swept, flag\nor not.\n","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"force_sweep","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Dataset transforms only (400 on a warehouse transform): confirm a sweep that deletes more than half of the owned records. Any value other than a boolean is a 400."}],"responses":{"202":{"description":"Run queued.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SQLTransformRun"}}}]}}}},"400":{"description":"`force_sweep` is not a boolean, or was set on a warehouse transform. Nothing was queued.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"$ref":"#/components/responses/ManifestForbidden"},"404":{"description":"Transform not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Transform is paused. Nothing was queued.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/connect/sql-transforms/{id}/runs":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"summary":"List a SQL transform's runs","operationId":"listSQLTransformRuns","tags":["Connect"],"description":"Execution history, newest first.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":50},"description":"Rows to return. A non-positive or non-numeric value is a 400; anything above 200 is CAPPED at 200 rather than refused, so a caller asking for more gets the maximum page instead of an error."}],"responses":{"200":{"description":"The transform's runs.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SQLTransformRun"}}}}]}}}},"400":{"description":"Invalid limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Transform not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/networks":{"get":{"summary":"List private networks","operationId":"listNetworks","tags":["Networks"],"description":"Private-network egress: named, tenant-owned tunnel definitions (ssh jump hosts, SOCKS5\nand HTTP CONNECT proxies, userspace WireGuard peers) through which connectors, campaign channel providers and journey webhook nodes dial customer-local\ninfrastructure. A consumer opts in via `connection.network_id`; an absent key is the\ndefault route. Credentials are write-only; responses carry `credentials_set`.\nRequires integration_editor, engineer or admin (integration_viewer is read-only).\n","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","minimum":0}},{"name":"size","in":"query","schema":{"type":"integer","minimum":1}},{"name":"sort_by","in":"query","schema":{"type":"string","enum":["name","type","enabled","status","created_at","updated_at"]}},{"name":"sort_dir","in":"query","schema":{"type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"Networks.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/NetworkResponse"}}}}]}}}}}},"post":{"summary":"Create a private network","operationId":"createNetwork","tags":["Networks"],"description":"Save-time validation is strict and per type: `config.host_key` is mandatory for ssh\n(known-hosts line or authorized-keys entry — an empty one is a rejection, not a\npermissive default), socks5/http_connect need host + port, wireguard needs\nendpoint + peer_public_key + local_address (and valid allowed_ips), credentials must\nparse, and every `allowed_cidrs` entry must be a valid CIDR (bare IPs are accepted as\n/32 or /128). Requires engineer/admin.\n","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NetworkRequest"}}}},"responses":{"201":{"description":"Network created.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/NetworkResponse"}}}]}}}},"400":{"description":"Invalid payload (unsupported type, missing host_key, bad CIDR, unparsable private key, …).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"A network with that name already exists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Encryption key not configured.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/networks/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a private network","operationId":"getNetwork","tags":["Networks"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"The network (credentials never included).","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/NetworkResponse"}}}]}}}},"404":{"description":"Network not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"put":{"summary":"Update a private network","operationId":"updateNetwork","tags":["Networks"],"description":"Omitting `credentials` keeps the stored ciphertext; an explicitly-sent empty object\nclears it (the connector convention). Editing a network bumps `updated_at`, which\nrecycles every stream connection and tunnel using it within one reconcile tick.\nChanging `type`, `config.host`, `port`, `user`, `host_key` or `endpoint` while omitting\n`credentials` is a 409 `credentials_required`: the stored secret would otherwise be\npresented to the new host. Re-send credentials (or clear them with `{}`).\nRequires engineer/admin.\n","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NetworkRequest"}}}},"responses":{"200":{"description":"Network updated.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/NetworkResponse"}}}]}}}},"400":{"description":"Invalid payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Network not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Network name already taken, OR credentials_required (the destination moved while the stored credentials would be kept).","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"$ref":"#/components/schemas/CredentialsRequiredResponse"}]}}}}}},"delete":{"summary":"Delete a private network","operationId":"deleteNetwork","tags":["Networks"],"description":"Refused with 409 while anything still references the network: a connector, a campaign\nchannel provider, or a journey whose graph carries the id on a node. The reference is\nan ordinary JSONB key in all three cases, so the check is an explicit scan, not an FK.\nRequires engineer/admin.\n","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"Network deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"404":{"description":"Network not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Network is still referenced by one or more connectors, channel providers or journeys.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/networks/{id}/test":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Test a private network","operationId":"testNetwork","tags":["Networks"],"description":"Brings the tunnel up out-of-band and probes it: the SSH handshake for ssh networks, TCP\nreachability of the proxy for socks5/http_connect, device construction for wireguard —\nplus, when `config.probe_addr` is set, a full dial of that address through the tunnel\n(the only end-to-end proof for proxy and wireguard types, which are silent until a\npacket flows). Returns latency and a structured failure reason, and persists the\noutcome to the row's `status` columns. 15-second budget. Requires engineer/admin.\n","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"Test completed (check `data.success` for outcome).","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/NetworkTestResponse"}}}]}}}},"404":{"description":"Network not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Tenant's outbound mode is `off` (Environments) — a probe is real egress; probes stay allowed in `sink` mode.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Encryption key not configured.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/networks/{id}/rotate-credentials":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Rotate a private network's credentials","operationId":"rotateNetworkCredentials","tags":["Networks"],"description":"Rotates ONLY the stored credentials (validated against the stored config, then\nencrypted at rest) — for rotating a bastion key or password without touching the\nnetwork definition. By default the sent keys are MERGED into the stored map (a key\nsent as \"\" is removed); ?replace=true stores exactly the sent map. Requires\nengineer/admin.\n","parameters":[{"name":"replace","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Store exactly the sent map instead of merging it into the stored one."}],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["credentials"],"properties":{"credentials":{"type":"object","additionalProperties":{"type":"string"}}}}}}},"responses":{"200":{"description":"Credentials rotated.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/NetworkResponse"}}}]}}}},"400":{"description":"Invalid or missing credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Network not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The stored credentials cannot be decrypted with the current key, so they cannot be merged. If a key rotation is in progress (the blob is still sealed under the previous key), run POST /connect/reencrypt first; otherwise resend the complete set with ?replace=true.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Encryption key not configured.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/edge/settings":{"get":{"summary":"Get edge tracking settings","operationId":"getEdgeSettings","tags":["Edge"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"The singleton settings row.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/EdgeSettingsResponse"}}}]}}}},"404":{"description":"Edge tracking has never been configured.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"put":{"summary":"Configure edge tracking (singleton upsert)","operationId":"putEdgeSettings","tags":["Edge"],"description":"Full replace: send the whole document (omitted fields reset to their defaults).\nValidates that the (web and, when set, mobile) entity types exist, that\nidentify_allowed_keys contains no device identifier key of either platform, that every\nidentify_allowed_attributes entry is an attribute of at least one configured tracking\nentity (purpose-tagged attributes outside collection_purposes are a structured 400 in\nenforce/strict), that consent_mode=require carries at least one required purpose, and\nthat every purpose exists (active) in the consent-purpose catalog, that no cmp_purpose_map\nentry has an empty purpose list, and that each device identifier key is a declared identifier\nof its tracking entity (checked only when the key or its entity type changes from the stored\nsettings, so an existing configuration can still be re-saved). Requires engineer/admin.\n","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EdgeSettingsRequest"}}}},"responses":{"200":{"description":"Settings saved.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/EdgeSettingsResponse"}}}]}}}},"400":{"description":"Invalid payload (unknown entity type, device identifier key not declared on its entity, device key in identify_allowed_keys, unknown purpose, empty cmp_purpose_map purpose list, …).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/edge/preview":{"post":{"summary":"Preview ad-hoc edge-dialect template text (editor live preview)","operationId":"previewEdgeTemplate","tags":["Edge"],"description":"Renders an UNSAVED edge personalization template against a\ncaller-supplied sample context — for personalized content items and\nthe onsite campaign channels' template fields, which both render in\nthis dialect at serve time (hence no content-licence gate). Nothing is\nread or written; the sample context stands in for what a device would\nresolve to. `kind` picks the serve-time renderer: `html` for\nunstructured bodies (html/template contextual escaping), `text` for\nplain-text fields, `payload` for a structured JSON document string\nwhose template-bearing values render individually (the rendered\ndocument is returned re-encoded).\n\nA broken template is the ANSWER, not a request failure: 200 with\n`ok: false` and the exact Go parse/execution error plus the line it\npoints at (0/absent = no position). Note the dialect has no helper\nfunctions and no missingkey=zero — a missing attribute renders\n`<no value>` exactly as it would at serve time.\n\nThe save-time execution-budget rules run first, so the preview\nrejects exactly what a save would ({{range}} over a numeric literal\nor constant variable, range nesting deeper than 3, recursive\n{{template}} — answered as ok=false naming the construct), and the\nrender itself runs under the serve-time budget (320 KiB of output\nand 200 ms per render call; a payload's strings share one budget).\n","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EdgePreviewRequest"}}}},"responses":{"200":{"description":"`data` is `{ok, rendered?, error?: {message, line?}}`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/EdgePreviewResponse"}}}]}}}},"400":{"description":"Malformed payload or unknown kind.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/edge/cmp/coverage":{"get":{"summary":"External CMP signal coverage, per SDK key","operationId":"getEdgeCMPCoverage","tags":["Edge"],"description":"Per-SDK-key counts of what the CMP ingest path saw over the last\n`days` days: how many tracked requests arrived while `cmp_mode` was\nactive (`total`), how many of those carried a decodable signal\n(`signal`), how many carried a TC string that would not parse\n(`unparseable`), and the granted/denied tally per mapped Optima\npurpose. `total - signal` is the share of traffic sending no signal\nat all — the number an observe-mode rollout is watching.\n\n**Approximate by construction** (`approximate` is always true). The\ncounters are best-effort counters written by the edge\nservice: writes fail open, counters expire after 35 days, and a\ncounter-store outage silently under-counts. Present them as a coverage indicator,\nnever as a consent ledger — `profile_consents` and\n`consent_receipts` are the records of what was actually decided.\n\nA key that has seen nothing is returned with zeroes rather than\nomitted, and an unreachable counter store answers 200 with zeroes\nrather than an error: \"this property is sending nothing\" is exactly\nthe answer this screen exists to give.\n","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"days","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":35,"default":7},"description":"Window in days, ending today (UTC). Clamped to 1..35 — 35 is the bucket TTL, so a longer window would report a partial answer as a full one."}],"responses":{"200":{"description":"`data` is `{days, approximate, keys[]}`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/EdgeCMPCoverageResponse"}}}]}}}}}}},"/cdp/api/v1/edge/keys":{"get":{"summary":"List SDK keys","operationId":"listEdgeSDKKeys","tags":["Edge"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"All SDK keys, newest first (tokens included — they are public by design).","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/EdgeSDKKeyResponse"}}}}]}}}}}},"post":{"summary":"Create an SDK key","operationId":"createEdgeSDKKey","tags":["Edge"],"description":"The token is server-generated ('oek_' + 32 base62 chars from crypto/rand) and returned in\nthe response (and on every later GET — no show-once ceremony, the token is public). Web\nkeys must carry at least one allowed origin, each a bare scheme://host[:port] (no paths, no\nwildcards in phase 1). Requires engineer/admin.\n","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EdgeSDKKeyRequest"}}}},"responses":{"201":{"description":"Key created.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/EdgeSDKKeyResponse"}}}]}}}},"400":{"description":"Invalid payload (missing origins on a web key, malformed origin, …).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/edge/keys/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"summary":"Get an SDK key","operationId":"getEdgeSDKKey","tags":["Edge"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"The key.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/EdgeSDKKeyResponse"}}}]}}}},"404":{"description":"Key not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"put":{"summary":"Update an SDK key","operationId":"updateEdgeSDKKey","tags":["Edge"],"description":"Updates name/platform/origins/rate limit/active. The token never changes; use rotate-by-replace (create a new key, revoke the old). Requires engineer/admin.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EdgeSDKKeyRequest"}}}},"responses":{"200":{"description":"Key updated.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/EdgeSDKKeyResponse"}}}]}}}},"400":{"description":"Invalid payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Key not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"summary":"Delete an SDK key","operationId":"deleteEdgeSDKKey","tags":["Edge"],"description":"Removes the row entirely. Prefer revoke, which keeps the audit trail. Requires engineer/admin.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"Key deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"404":{"description":"Key not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/edge/keys/{id}/revoke":{"post":{"summary":"Revoke an SDK key","operationId":"revokeEdgeSDKKey","tags":["Edge"],"description":"Sets active=false and stamps revoked_at (distinct from DELETE so the audit trail survives).\nThe gateway stops accepting the key within one config-poll interval (≤30s); hits already\nqueued are dropped on re-check. Requires engineer/admin.\n","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Key revoked.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/EdgeSDKKeyResponse"}}}]}}}},"404":{"description":"Key not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/edge/keys/{id}/identify-secret/rotate":{"post":{"summary":"Rotate the SDK key's identify signing secret","operationId":"rotateEdgeIdentifySecret","tags":["Edge"],"description":"Generates a new identify signing secret, stores it sealed and returns\nthe plaintext ONCE. The previous secret stops verifying within one edge config-poll interval\n(≤30s). Signed assertions let /edge/v1/identify and form submits link a device to the profile\nthat already owns an identifier. Requires engineer/admin/integration_editor.\n","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"New secret (shown once).","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/EdgeIdentifySecretResponse"}}}]}}}},"400":{"description":"Invalid id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Key not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Identify-secret encryption is not configured on this instance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/edge/keys/{id}/identify-secret":{"delete":{"summary":"Clear the SDK key's identify signing secret","operationId":"clearEdgeIdentifySecret","tags":["Edge"],"description":"Assertions for this key are dropped (never trusted) from the next edge config poll on.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Secret cleared.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/EdgeSDKKeyResponse"}}}]}}}},"400":{"description":"Invalid id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Key not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/edge/keys/identify-secrets/reencrypt":{"post":{"summary":"Re-encrypt every SDK key's identify secret with the current key","operationId":"reencryptEdgeIdentifySecrets","tags":["Edge"],"description":"Key rotation: identify secrets that fail to decrypt with the current identify-secret key are decrypted with the previous key and re-encrypted with the current one; already-current ones are untouched. The secrets themselves do not change. Call it once per tenant. Requires engineer/admin/integration_editor.\n","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"Result.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"identify_secrets":{"$ref":"#/components/schemas/ReencryptResult"}}}}}]}}}},"503":{"description":"Identify-secret encryption is not configured on this instance","or a key is malformed.":null,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/edge/mappings":{"get":{"summary":"List category mappings","operationId":"listEdgeMappings","tags":["Edge"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"All category mappings ordered by category.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/EdgeCategoryMappingResponse"}}}}]}}}}}},"post":{"summary":"Create a category mapping","operationId":"createEdgeMapping","tags":["Edge"],"description":"Save-time validation: the event type exists; every source token matches the\n$name | $context.<known> | $props.<key> grammar; every target is an attribute of the event\ntype (no duplicate targets); and — when edge settings declare collection purposes — those\npurposes may collect each purpose-tagged target attribute (structured 400 with\ndata.violations in enforce/strict privacy mode, logged warning otherwise). Requires\nengineer/admin.\n","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EdgeCategoryMappingRequest"}}}},"responses":{"201":{"description":"Mapping created.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/EdgeCategoryMappingResponse"}}}]}}}},"400":{"description":"Invalid payload / grammar / purpose violation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Category already mapped.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/edge/mappings/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"summary":"Get a category mapping","operationId":"getEdgeMapping","tags":["Edge"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"The mapping.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/EdgeCategoryMappingResponse"}}}]}}}},"404":{"description":"Mapping not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"put":{"summary":"Update a category mapping","operationId":"updateEdgeMapping","tags":["Edge"],"description":"Runs the same save-time validation as create. Requires engineer/admin.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EdgeCategoryMappingRequest"}}}},"responses":{"200":{"description":"Mapping updated.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/EdgeCategoryMappingResponse"}}}]}}}},"400":{"description":"Invalid payload / grammar / purpose violation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Mapping not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Category already mapped by another row.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"summary":"Delete a category mapping","operationId":"deleteEdgeMapping","tags":["Edge"],"description":"Hits of the category are dropped as unmapped from the next config poll on. Requires engineer/admin.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"Mapping deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"404":{"description":"Mapping not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/edge/trackers":{"get":{"summary":"List the tracker inventory","operationId":"listEdgeTrackers","tags":["Edge"],"description":"The consent-compliance tracker inventory: every third-party script/tracker a tenant's pages run, each\ntagged with the CDP purpose it serves. Active rows feed the public,\ndeliberately-static `GET /edge/v1/trackers` endpoint. Ordered by name.\n","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"All trackers.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/EdgeTrackerResponse"}}}}]}}}}}},"post":{"summary":"Create a tracker","operationId":"createEdgeTracker","tags":["Edge"],"description":"Save-time validation, in order: `purpose` must be\nan active purpose in the consent catalogue (the same check the settings surface's\nrequired/collection purposes use); then the per-`kind` `config`/`url_patterns`\nshape; then, for `kind=html`, the instance setting `edge_tag_html_enabled`; then\n`name` uniqueness. Requires engineer/admin.\n","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EdgeTrackerRequest"}}}},"responses":{"201":{"description":"Tracker created.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/EdgeTrackerResponse"}}}]}}}},"400":{"description":"Invalid payload / unknown or inactive purpose / invalid kind, config or url_patterns.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"kind=html while edge_tag_html_enabled is off","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"tracker name already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/edge/trackers/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"put":{"summary":"Update a tracker","operationId":"updateEdgeTracker","tags":["Edge"],"description":"Runs the same save-time validation as create (see POST above), against\nthis tracker's own name excluded from the uniqueness check.\nRequires engineer/admin.\n","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EdgeTrackerRequest"}}}},"responses":{"200":{"description":"Tracker updated.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/EdgeTrackerResponse"}}}]}}}},"400":{"description":"Invalid payload / unknown or inactive purpose / invalid kind, config or url_patterns.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"kind=html while edge_tag_html_enabled is off","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Tracker not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"tracker name already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"summary":"Delete a tracker","operationId":"deleteEdgeTracker","tags":["Edge"],"description":"Requires engineer/admin.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"Tracker deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"404":{"description":"Tracker not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/content":{"get":{"summary":"List content items","operationId":"listContentItems","tags":["Content"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"name","in":"query","required":false,"schema":{"type":"string"},"description":"Exact name match."},{"name":"folder","in":"query","required":false,"schema":{"type":"string"},"description":"Folder path. PRESENCE is the filter: `?folder=` means the root folder, omitting it means every folder."},{"name":"subtree","in":"query","required":false,"schema":{"type":"boolean"},"description":"Extend the folder filter to descendants."},{"name":"tag","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated; an item must carry ALL of them."},{"name":"status","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated: draft, pending_approval, published, rejected, archived."},{"name":"public","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"search","in":"query","required":false,"schema":{"type":"string"},"description":"Case-insensitive substring of name or description. LIKE metacharacters are escaped."},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"size","in":"query","required":false,"schema":{"type":"integer"}},{"name":"sort_by","in":"query","required":false,"schema":{"type":"string","enum":["name","status","folder","created_at","updated_at"]},"description":"Column to order by; anything else is a 400. Omitted = folder, then name. Ties break on id so pages never overlap."},{"name":"sort_dir","in":"query","required":false,"schema":{"type":"string","enum":["asc","desc"]},"description":"Defaults to asc."}],"responses":{"200":{"description":"Content items ordered by folder, then name. Each row carries its current renditions in `variants`, `original` first (an empty array when none).","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ContentItemResponse"}}}}]}}}}}},"post":{"summary":"Create a content item (draft)","operationId":"createContentItem","tags":["Content"],"description":"Creates metadata only; each rendition is uploaded separately. The public\ntoken is minted here and never changes, so a published URL stays stable\nacross every version. Requires content_editor, campaign_admin, engineer or admin.\n","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentItemRequest"}}}},"responses":{"201":{"description":"Content item created.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ContentItemResponse"}}}]}}}},"400":{"description":"Invalid payload, or `public` combined with `pii_level` > 0.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"An item with this name already exists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/content/facets":{"get":{"summary":"Content folder tree and tag vocabulary","operationId":"contentFacets","tags":["Content"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"Distinct non-empty folders and all tags.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ContentFacets"}}}]}}}}}}},"/cdp/api/v1/content/generate-image/capabilities":{"get":{"summary":"Pre-flight for the AI image dialog","operationId":"contentGenerateCapabilities","tags":["Content"],"description":"Whether generating can work right now (with the refusal sentence when\nnot — feature off, incomplete configuration, or a sandbox\nenvironment), the per-request variant ceiling\n(`llm_image_max_variants`), and what remains of today's per-tenant\nbudget. Advisory: the generate endpoint re-checks everything, so a\nstale answer can never overspend.\n","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"Current generation capabilities.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ContentGenerateCapabilities"}}}]}}}}}}},"/cdp/api/v1/content/generate-image":{"post":{"summary":"Generate images with AI (staged for save/toss)","operationId":"generateContentImage","tags":["Content"],"description":"Generates up to `n` images from the marketer's prompt (clamped to the\n`llm_image_max_variants` instance setting and to what remains of the\nper-tenant daily quota, `llm_image_daily_limit`). The prompt is\nuser-typed text only — profile data is never interpolated. Produced\nimages are STAGED server-side and previewed inline as data URIs;\nsaving one into the library is a separate promote call, tossing is\n`DELETE /content/generations/{id}`, and regenerating is simply another\ncall here. `produced` may be lower than `requested` when a\nmulti-variant generation partially failed (the successes are kept and\nstill count against the quota). Requires content_editor, campaign_admin, engineer or admin.\n","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentGenerateRequest"}}}},"responses":{"200":{"description":"Images generated and staged.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ContentGenerationResponse"}}}]}}}},"400":{"description":"Missing or over-long prompt.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The `assist_images` feature (AI package) is not licensed (reason=feature_not_licensed), or this environment's outbound mode (sandbox sink/off) refuses billable AI calls, or a delegation header the key may not use (see AIDelegationForbidden).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"The daily AI image limit is exhausted (resets at midnight UTC), or the caller's per-minute AI assist budget is spent (ai_requests_per_minute; Retry-After says when to retry).","headers":{"Retry-After":{"description":"Seconds until the per-minute window resets. Absent on the daily-limit 429.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"The image provider failed or returned no usable image.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"AI image generation is disabled (`llm_image_enabled`) or content storage is not configured.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/content/generations/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"delete":{"summary":"Toss a staged generation","operationId":"deleteContentGeneration","tags":["Content"],"description":"Deletes the staged images and the generation record fully — no audit\ncopy is kept. Already-produced images still count against the daily\nquota (they were billed). Generations abandoned without a toss are\nswept automatically after their staging TTL.\n","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"Generation tossed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"404":{"description":"Generation not found (already tossed or expired).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Failed to delete the staged images; retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/content/generations/{id}/save":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"summary":"Save a staged generated image as a new content item","operationId":"saveContentGeneration","tags":["Content"],"description":"Promotes one image of a staged generation (picked by `index`) into a\nNEW content item with an `original` rendition. The bytes are copied\nserver-side from staging into the item's namespace; AI provenance\n(prompt, provider, model, generation id, who and when) is stamped on\nthe rendition's `generated` field and survives revision snapshots and\nrestores. The item lands as an ordinary private draft — approval and\npublishing go through the normal content workflow. Saving the same\nindex twice answers 409 with the item it already became.\n","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentGenerationSaveRequest"}}}},"responses":{"201":{"description":"Content item created from the generated image.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ContentItemResponse"}}}]}}}},"400":{"description":"Invalid name/folder, or index out of range.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Generation not found (already tossed or expired).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"This image was already saved, or an item with this name exists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"The staged image could not be read or copied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/content/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"summary":"Get a content item with its current renditions","operationId":"getContentItem","tags":["Content"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"The content item.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ContentItemResponse"}}}]}}}},"404":{"description":"Content item not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"put":{"summary":"Update a content item","operationId":"updateContentItem","tags":["Content"],"description":"Editing a published item sends `status` back to `draft` and leaves the\nserving pins untouched — the approved bytes keep serving until a new\nrevision is approved. Editing an item awaiting approval also returns it\nto `draft`, so a reviewer never approves something other than what was\nsubmitted. Archived items keep their status.\n\nLowering `pii_level` requires the caller's own PII access level to\nalready clear the item's CURRENT level — the same check `/download`\napplies — so a caller cannot defeat the download gate by editing the\nlevel down to one they clear. Raising it is unrestricted.\n","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContentItemRequest"}}}},"responses":{"200":{"description":"Content item updated.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ContentItemResponse"}}}]}}}},"400":{"description":"Invalid payload, or `public` combined with `pii_level` > 0.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`pii_level` is being lowered and the caller's PII access level does not reach the item's current level.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Content item not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"summary":"Delete a content item","operationId":"deleteContentItem","tags":["Content"],"description":"Deletes the item and its renditions, then reclaims its stored objects\nbest-effort. Revisions are NOT deleted: history outlives the item it\ndescribes, so the item's trail (including the final delete entry) stays\nreadable at `/content/{id}/revisions`.\n","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"Content item deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"404":{"description":"Content item not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/content/{id}/download":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"summary":"Download a rendition (302 to a presigned URL)","operationId":"downloadContentVariant","tags":["Content"],"description":"Answers **302** to a short-lived presigned object-store URL; the CDP\nnever proxies the bytes. An unknown variant falls back to `original`.\n\nThis is the PII gate: an item with `pii_level` > 0 requires the\ncaller's `pii_access_level` to be at least that high (root bypasses).\nThe response carries `Cache-Control: no-store` — the signed URL is a\nbearer credential with a short life.\n","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"variant","in":"query","required":false,"schema":{"type":"string","default":"original"}}],"responses":{"302":{"description":"Redirect to the presigned download URL."},"403":{"description":"The callers PII access level is below the items.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Content item not found, or it has no renditions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Object storage is not configured.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/content/{id}/variants/{name}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"name","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9_-]{0,63}$"},"description":"Rendition name, e.g. original, desktop, mobile. `original` is mandatory before publication."}],"put":{"summary":"Upload a rendition","operationId":"uploadContentVariant","tags":["Content"],"description":"Multipart form field `file`. Each upload writes a NEW stored object\nrather than overwriting, so an older revision keeps referencing bytes\nthat still exist. Uploading returns the item to `draft` without\ndisturbing what the public URL is serving.\n\nBounded by the `content_upload_max_mb` instance setting (default 100).\nThere is no multipart upload: the object is buffered whole.\n","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary"}},"required":["file"]}}}},"responses":{"200":{"description":"Rendition stored; the updated item is returned.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ContentItemResponse"}}}]}}}},"400":{"description":"Missing or empty file, or an invalid variant name.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The item is archived.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"413":{"description":"The file exceeds the configured upload cap.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Object storage rejected the write.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Object storage is not configured.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"summary":"Delete a rendition","operationId":"deleteContentVariant","tags":["Content"],"description":"Removes the renditions record. The stored object is retained — an earlier revision may still reference it.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"Rendition deleted.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ContentItemResponse"}}}]}}}},"404":{"description":"Content item or rendition not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/content/{id}/variants/{name}/rename":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"name","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9_-]{0,63}$"},"description":"The rendition to rename."}],"post":{"summary":"Rename a rendition","operationId":"renameContentVariant","tags":["Content"],"description":"Moves a rendition to a different name, keeping its stored bytes: the\nrow's `object_key` is untouched (it still carries the old name as a\npath segment, which nothing resolves by parsing), so every revision\nsnapshot pointing at those bytes keeps working.\n\nLike an upload or a delete, this returns the item to `draft` and\nwithdraws a pending publication request — the draft no longer matches\nwhat was approved.\n\nReferences BY NAME do not follow the rename: a message-template\nattachment or a document layout pinned to the old name keeps resolving\nagainst the frozen `published_variants` map until the item is approved\nagain, and stops resolving after that. Renaming to the current name is\na no-op that records no revision.\n","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","pattern":"^[a-z0-9][a-z0-9_-]{0,63}$","description":"The new rendition name, lowercased.","example":"desktop"}}}}}},"responses":{"200":{"description":"Rendition renamed; the updated item is returned.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ContentItemResponse"}}}]}}}},"400":{"description":"Invalid body, or an invalid new variant name.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Content item or rendition not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The item is archived, or the new name is already taken on this item.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/content/{id}/request-publish":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"summary":"Request publication","operationId":"requestContentPublish","tags":["Content"],"description":"Moves the item to `pending_approval` and stamps the requester. Legal\nfrom `draft`, `rejected` and `published` (re-requesting is how a new\nversion goes up). Requires an `original` rendition. A previous\ndecision is cleared, so a stale rejection is not shown against a fresh\nrequest.\n","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"Publication requested.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ContentItemResponse"}}}]}}}},"400":{"description":"The item has no `original` rendition.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Illegal transition from the items current status.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/content/{id}/unpublish":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"summary":"Take an item off the air","operationId":"unpublishContentItem","tags":["Content"],"description":"Clears the serving pins and the `public` flag. The public URL stops\nanswering within one Edge config poll (≤30 s by default) — the serving\ntier reads a polled snapshot. The workflow status is left where it is:\nunpublishing is a serving decision, not an editorial one.\n","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"Content item unpublished.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ContentItemResponse"}}}]}}}},"409":{"description":"The item is not published, or the transition is illegal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/content/{id}/archive":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"summary":"Archive a content item","operationId":"archiveContentItem","tags":["Content"],"description":"Takes the item out of the library and off the air in one write — an archived item that keeps serving is the surprise archiving prevents.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"Content item archived.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ContentItemResponse"}}}]}}}},"409":{"description":"The item is already archived.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/content/{id}/unarchive":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"summary":"Return an archived item to the library","operationId":"unarchiveContentItem","tags":["Content"],"description":"Returns the item to `draft`. It does NOT go back on the air — that needs a fresh approval.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"Content item unarchived.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ContentItemResponse"}}}]}}}},"409":{"description":"The item is not archived.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/content/{id}/revisions":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"summary":"List an item's version history","operationId":"listContentRevisions","tags":["Content"],"description":"Newest first. Snapshots are elided from list rows (each carries the whole\nitem including its rendition map); fetch one revision to get its\nsnapshot. History outlives the item, so this endpoint keeps answering\nafter a delete.\n","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"actor","in":"query","required":false,"schema":{"type":"string"}},{"name":"action","in":"query","required":false,"schema":{"type":"string","enum":["create","update","upload_variant","delete_variant","rename_variant","request_publish","approve","reject","unpublish","archive","unarchive","restore","delete"]}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"size","in":"query","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Revisions, newest first.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ContentRevisionResponse"}}}}]}}}}}}},"/cdp/api/v1/content/{id}/revisions/{rev}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"rev","in":"path","required":true,"schema":{"type":"integer","minimum":1}}],"get":{"summary":"Get one revision, snapshot included","operationId":"getContentRevision","tags":["Content"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"The revision.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ContentRevisionResponse"}}}]}}}},"404":{"description":"Revision not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/content/{id}/revisions/{rev}/restore":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"rev","in":"path","required":true,"schema":{"type":"integer","minimum":1}}],"post":{"summary":"Restore an earlier revision","operationId":"restoreContentRevision","tags":["Content"],"description":"Replays the snapshot's metadata and rendition SET. Stored objects are\nuntouched — each upload wrote its own immutable key, so the snapshot's\nkeys still resolve. The item lands in `draft`, the `public` flag is\nNOT replayed (publication is a workflow decision, not a stored field),\nand the serving pins are left alone so the public URL keeps serving\nwhat was approved.\n\nRestoring a snapshot whose `pii_level` is lower than the item's\nCURRENT level is gated the same as a PUT that lowers it: the caller's\nPII access level must already clear the current level, so a stale,\nlower-level snapshot cannot be replayed as a way around the download\ngate.\n","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"Revision restored.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ContentItemResponse"}}}]}}}},"400":{"description":"The revision has no snapshot to restore (e.g. a delete entry).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The snapshot's `pii_level` is lower than the item's current level and the caller's PII access level does not reach the current level.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Content item or revision not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The item is archived.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/content-approvals":{"get":{"summary":"Content awaiting approval","operationId":"listContentApprovals","tags":["Content"],"description":"The reviewer's queue. A SIBLING prefix rather than a filter on\n`/content`, because permissions are allow-only and a grant on `/content/*` matches\neverything below it: an approve route under `/content/*` would fall\ninside every content author's grant and could never be carved back out.\nGranted to content_approver, campaign_admin, engineer and admin, and\ndeliberately NOT to content_editor.\n","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"size","in":"query","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Items in `pending_approval`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ContentItemResponse"}}}}]}}}}}}},"/cdp/api/v1/content-approvals/{id}/approve":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"summary":"Approve and publish","operationId":"approveContentItem","tags":["Content"],"description":"Records the `approve` revision, then pins it: `published_revision` and\nthe frozen rendition map are set with the status in one write, because\nserving reads only the pins.\n\n**Separation of duties, with an operator exemption.** An ordinary\nreviewer cannot approve content they requested themselves — a user may\nhold both roles, so a route permission alone cannot express it. **Root, `admin` and\n`instance_admin` may**:\nthe rule buys nothing against personas that already hold every other\ncontrol, and for a one-operator deployment it makes the workflow\nunusable through a single credential.\n\nA self-approval is therefore made visible rather than prevented. Both\nidentities are recorded on the item (`submitted_by`, `decided_by`) and\npermanently in the revision ledger, and the response carries\n`self_approved`.\n","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"Content item published.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ContentItemResponse"}}}]}}}},"400":{"description":"The item no longer has an `original` rendition.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The caller requested this publication themselves and holds none of root / admin / instance_admin.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The item is not awaiting approval.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/content-approvals/{id}/reject":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"summary":"Reject with a reason","operationId":"rejectContentItem","tags":["Content"],"description":"The reason is mandatory and shown to the author on the item — a rejection they cannot act on is not a review.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["reason"],"properties":{"reason":{"type":"string","maxLength":2000}}}}}},"responses":{"200":{"description":"Content item rejected.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ContentItemResponse"}}}]}}}},"400":{"description":"The rejection reason is missing or too long.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The item is not awaiting approval.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/edge/content":{"get":{"summary":"List content items","operationId":"listEdgeContent","tags":["Edge"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"slot","in":"query","required":false,"schema":{"type":"string"}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["draft","published","archived"]}}],"responses":{"200":{"description":"Content items ordered by slot, then priority desc, FILTERED to the item types the tenant's licence covers (a banners-only tenant sees only banner_consent items). Filtered rather than refused: one unlicensed row must not hide every licensed one.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/EdgeContentItemResponse"}}}}]}}}},"400":{"description":"Invalid status filter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a content item (draft)","operationId":"createEdgeContent","tags":["Edge"],"description":"Validates the targeting grammar and the schedule window. New items are always drafts. Requires content_editor, campaign_admin, engineer or admin, and the feature governing the item's type — \"banners\" for content_type=banner_consent, \"content\" for every other type.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EdgeContentItemRequest"}}}},"responses":{"201":{"description":"Content item created.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/EdgeContentItemResponse"}}}]}}}},"400":{"description":"Invalid payload / targeting / window.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The tenant's licence does not include the feature governing this item type (reason=feature_not_licensed; \"banners\" for banner_consent, \"content\" otherwise). On update, either the stored item's feature or the incoming type's.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/edge/content/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"summary":"Get a content item","operationId":"getEdgeContent","tags":["Edge"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"The content item.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/EdgeContentItemResponse"}}}]}}}},"403":{"description":"The tenant's licence does not include the feature governing this item type (reason=feature_not_licensed; \"banners\" for banner_consent, \"content\" otherwise).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Content item not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"put":{"summary":"Update a content item","operationId":"updateEdgeContent","tags":["Edge"],"description":"Edits slot/name/type/payload/targeting/priority/window. Status is untouched (use publish/unpublish). Requires content_editor, campaign_admin, engineer or admin, and the feature governing the item's type — \"banners\" for content_type=banner_consent, \"content\" for every other type. Because content_type is overwritten wholesale, an update needs BOTH halves: the feature of the STORED item and the feature of the incoming type, so neither licence can convert away the other's items.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EdgeContentItemRequest"}}}},"responses":{"200":{"description":"Content item updated.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/EdgeContentItemResponse"}}}]}}}},"400":{"description":"Invalid payload / targeting / window.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The tenant's licence does not include the feature governing this item type (reason=feature_not_licensed; \"banners\" for banner_consent, \"content\" otherwise). On update, either the stored item's feature or the incoming type's.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Content item not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"summary":"Delete a content item","operationId":"deleteEdgeContent","tags":["Edge"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"Content item deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"403":{"description":"The tenant's licence does not include the feature governing this item type (reason=feature_not_licensed; \"banners\" for banner_consent, \"content\" otherwise).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Content item not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/edge/content/{id}/publish":{"post":{"summary":"Publish a content item","operationId":"publishEdgeContent","tags":["Edge"],"description":"Re-validates the stored targeting grammar and schedule window (starts_at < ends_at; a\nwindow that has already ended is refused), then sets status=published and stamps\npublished_at. The gateway serves it within one config-poll interval. Requires\ncontent_editor, campaign_admin, engineer or admin.\n","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Content item published.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/EdgeContentItemResponse"}}}]}}}},"400":{"description":"Invalid targeting / window.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The tenant's licence does not include the feature governing this item type (reason=feature_not_licensed; \"banners\" for banner_consent, \"content\" otherwise).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Content item not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/edge/content/{id}/unpublish":{"post":{"summary":"Unpublish a content item","operationId":"unpublishEdgeContent","tags":["Edge"],"description":"Sets status back to draft; published_at is kept as history. Requires content_editor, campaign_admin, engineer or admin.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Content item unpublished.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/EdgeContentItemResponse"}}}]}}}},"403":{"description":"The tenant's licence does not include the feature governing this item type (reason=feature_not_licensed; \"banners\" for banner_consent, \"content\" otherwise).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Content item not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/edge/forms":{"get":{"summary":"List web forms","operationId":"listEdgeForms","tags":["Edge"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["draft","published","archived"]}}],"responses":{"200":{"description":"Forms ordered by name.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/EdgeFormResponse"}}}}]}}}},"400":{"description":"Invalid status filter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The account's licence does not include the `landing_pages` feature (Edge package).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a web form (draft)","operationId":"createEdgeForm","tags":["Edge"],"description":"Validates the slug, every field's target against the tracking\nentity's schema (or, for consent targets, against consent_purposes),\nthe consent policy reference, double-opt-in, and the page template\nwhen page_personalized is set. New forms are always drafts.\nRequires engineer/admin.\n","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EdgeFormRequest"}}}},"responses":{"201":{"description":"Form created.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/EdgeFormResponse"}}}]}}}},"400":{"description":"Invalid payload / slug / field targets / consent policy reference.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The account's licence does not include the `landing_pages` feature (Edge package).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Slug already exists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The tenant does not yet declare event type form_submitted with a string attribute form_id — create that event type before saving a form.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/edge/forms/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"summary":"Get a web form","operationId":"getEdgeForm","tags":["Edge"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"The form.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/EdgeFormResponse"}}}]}}}},"403":{"description":"The account's licence does not include the `landing_pages` feature (Edge package).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Form not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"put":{"summary":"Update a web form","operationId":"updateEdgeForm","tags":["Edge"],"description":"Replaces the form's editable columns and its whole field set. Status is untouched (use publish/unpublish). Requires engineer/admin.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EdgeFormRequest"}}}},"responses":{"200":{"description":"Form updated.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/EdgeFormResponse"}}}]}}}},"400":{"description":"Invalid payload / slug / field targets / consent policy reference.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The account's licence does not include the `landing_pages` feature (Edge package).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Form not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Slug already exists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The tenant does not yet declare event type form_submitted with a string attribute form_id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"summary":"Delete a web form","operationId":"deleteEdgeForm","tags":["Edge"],"description":"Requires engineer/admin.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"Form deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"403":{"description":"The account's licence does not include the `landing_pages` feature (Edge package).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Form not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/edge/forms/{id}/publish":{"post":{"summary":"Publish a web form","operationId":"publishEdgeForm","tags":["Edge"],"description":"Re-validates the stored form against the current configuration —\nentity type still one of the configured tracking entities, every\nfield target still valid, consent purposes and the referenced\nconsent policy still resolvable, the form_submitted event type\nstill declared with a string form_id attribute, and the page\ntemplate still parses when page_personalized is set (the row may\npredate stricter rules) — then sets status=published and stamps\npublished_at. The gateway serves it within one config-poll\ninterval. Requires engineer/admin.\n","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Form published.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/EdgeFormResponse"}}}]}}}},"400":{"description":"The stored form no longer validates against the current configuration (field target / consent purpose / consent policy).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The account's licence does not include the `landing_pages` feature (Edge package).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Form not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The tenant no longer declares event type form_submitted with a string attribute form_id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/edge/forms/{id}/unpublish":{"post":{"summary":"Unpublish a web form","operationId":"unpublishEdgeForm","tags":["Edge"],"description":"Sets status back to draft; published_at is kept as history. Requires engineer/admin.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Form unpublished.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/EdgeFormResponse"}}}]}}}},"403":{"description":"The account's licence does not include the `landing_pages` feature (Edge package).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Form not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/recommendations/catalogs":{"get":{"summary":"List recommendation catalogues","operationId":"listRecommendationCatalogs","tags":["Recommendations"],"description":"Control-plane metadata (pins a strategy to a custom dataset) — never customer data, so exempt from the X-Purpose gate. Requires the `recommendations` licence feature (Decision package).","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"Catalogues ordered by name.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/RecommendationCatalogObject"}}}}]}}}},"403":{"description":"The account's licence does not include the `recommendations` feature (Decision package).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a recommendation catalogue","operationId":"createRecommendationCatalog","tags":["Recommendations"],"description":"dataset_name must resolve to an existing custom dataset (400\notherwise). field_roles/interaction_events/business_rules are\nstrict-decoded and validated (422 on a shape/constraint violation),\nthen every field reference is cross-checked against the dataset's\nattribute_types (400 if any is absent). For an active catalogue, every\ninteraction rule's event_type must also exist with item_attribute\ndeclared as a string attribute (400 otherwise); inactive catalogues\nskip that check.\n","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecommendationCatalogRequest"}}}},"responses":{"201":{"description":"Catalogue created.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RecommendationCatalogObject"}}}]}}}},"400":{"description":"Invalid payload, unknown dataset_name, a field_roles/affinity/exclude/require field absent from the dataset's attribute_types, or (active catalogue) an interaction rule whose event_type does not exist or whose item_attribute is not a string attribute of it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The account's licence does not include the `recommendations` feature (Decision package).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Catalogue with that name already exists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"field_roles/interaction_events/business_rules failed strict decode or validation (recommend.ParseCatalog).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/recommendations/catalogs/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"summary":"Get a recommendation catalogue","operationId":"getRecommendationCatalog","tags":["Recommendations"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"The catalogue.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RecommendationCatalogObject"}}}]}}}},"400":{"description":"Invalid catalogue id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The account's licence does not include the `recommendations` feature (Decision package).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Catalogue not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"put":{"summary":"Replace a recommendation catalogue","operationId":"updateRecommendationCatalog","tags":["Recommendations"],"description":"Same validation pipeline as create. Omitting is_active preserves the stored value.","parameters":[{"name":"force","in":"query","required":false,"schema":{"type":"boolean"},"description":"Skip the catalogue-in-use check (rename or delete)."}],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecommendationCatalogRequest"}}}},"responses":{"200":{"description":"Catalogue updated.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RecommendationCatalogObject"}}}]}}}},"400":{"description":"Invalid payload, invalid catalogue id, unknown dataset_name, a field_roles/affinity/exclude/require field absent from the dataset's attribute_types, or (active catalogue) an interaction rule whose event_type does not exist or whose item_attribute is not a string attribute of it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The account's licence does not include the `recommendations` feature (Decision package).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Catalogue not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Another catalogue already has that name, or (rename) the catalogue is still referenced: data.reason is `catalog_in_use` and data.references lists `{kind, id, name, campaign_id?}` (campaign_id on journey references) for edge content items, journeys (current or live-pinned version), message templates and document templates. Pass `force=true` to rename anyway.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"field_roles/interaction_events/business_rules failed strict decode or validation (recommend.ParseCatalog).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"summary":"Delete a recommendation catalogue","operationId":"deleteRecommendationCatalog","tags":["Recommendations"],"parameters":[{"name":"force","in":"query","required":false,"schema":{"type":"boolean"},"description":"Skip the catalogue-in-use check (rename or delete)."}],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"Catalogue deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericResponse"}}}},"400":{"description":"Invalid catalogue id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The account's licence does not include the `recommendations` feature (Decision package).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Catalogue not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The catalogue is still referenced: data.reason is `catalog_in_use` and data.references lists `{kind, id, name, campaign_id?}` (campaign_id on journey references). Pass `force=true` to delete anyway.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/recommendations/{catalog}":{"post":{"summary":"Rank item-level recommendations for a profile","operationId":"recommend","tags":["Recommendations"],"description":"Customer-data read (which items rank for which profile) — gated by\nboth the X-Purpose header (purpose authorization) and the\n`recommendations` licence feature, unlike the catalogue admin CRUD above.\n\nFlow: resolve the named, active catalogue (404 otherwise) → parse\nits stored strategy config (500 on drift — it was validated at\nsave) → resolve count (default 10, clamped to the instance's\nrecommend_max_count setting) → translate/validate the request\n(400) → serve from cache when the resolved TTL\n(recommend_trending_cache_sec for strategy=trending, otherwise\nrecommend_cache_sec; 0 disables caching for that call entirely) has\na hit → otherwise rank against the catalogue's dataset and cache\nthe result. An empty `items` array is a normal 200, not an error —\nincluding when strategy=similar_to names an unknown seed_item.\n","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"catalog","in":"path","required":true,"schema":{"type":"string"},"description":"The recommendation catalogue's name."},{"name":"X-Purpose","in":"header","required":false,"schema":{"type":"string"},"description":"Comma-separated purposes; required in strict privacy mode."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecommendRequest"}}}},"responses":{"200":{"description":"Ranked items (possibly empty).","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RecommendResponse"}}}]}}}},"400":{"description":"Invalid payload, unknown filter operator, or a recommend.ValidateRequest failure (unknown strategy, count out of range, missing/misplaced seed_item, invalid blend).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The account's licence does not include the `recommendations` feature (Decision package), or the purpose gate denied the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No active recommendation catalogue by that name.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"The stored catalogue no longer parses (recommend.ParseCatalog drift) or ranking failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/agents/tools":{"get":{"summary":"List the agent tool catalogue","operationId":"listAgentTools","tags":["Agents"],"description":"Every tool an agent definition may use, with whether the calling principal can use it (licence features and the routes the tool calls). Requires the `agents_custom` licence feature. Reached by `agents_editor`, `admin`, `account_admin` and `instance_admin`, and by the generic `auditor` role, whose GET wildcard covers `/cdp/api/v1/*`.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"The catalogue.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AgentToolObject"}}}}]}}}},"403":{"description":"The licence does not include `agents_custom`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/agents/definitions":{"get":{"summary":"List agent definitions","operationId":"listAgentDefinitions","tags":["Agents"],"description":"Needs `agents_custom` or `agents_builtin`. Custom definitions are listed only with `agents_custom`, built-in ones only with `agents_builtin`, and a built-in whose tools need a feature the account lacks is left out.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"include_archived","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Include archived definitions."}],"responses":{"200":{"description":"Definitions with their current spec.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AgentDefinitionObject"}}}}]}}}},"403":{"description":"The licence includes neither `agents_custom` nor `agents_builtin`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create an agent definition","operationId":"createAgentDefinition","tags":["Agents"],"description":"Requires `agents_custom` (403 otherwise). Creates version 1. The spec is validated (422) and the caller must hold every tool it names (403 listing the denied tools).","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentDefinitionRequest"}}}},"responses":{"201":{"description":"Definition created.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AgentDefinitionObject"}}}]}}}},"400":{"description":"Malformed JSON body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The licence does not include `agents_custom`, or the caller may not use one of the spec's tools.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"A definition with that name exists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"A missing or too long `name`, or the spec failed validation (a continuous spec must satisfy the continuous rules).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"The attribute or event-type catalogue could not be read (data store unavailable), so the spec could not be checked; nothing is saved.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/agents/definitions/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"summary":"Get an agent definition with its versions","operationId":"getAgentDefinition","tags":["Agents"],"description":"Needs `agents_custom` or `agents_builtin`. A definition the licence hides answers 404, so its existence is not revealed.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"The definition, its current spec and `versions` (newest first).","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AgentDefinitionObject"}}}]}}}},"403":{"description":"The licence includes neither `agents_custom` nor `agents_builtin`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Definition not found, or hidden by the licence (its kind is not licensed, or a built-in's tools need a missing feature).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"put":{"summary":"Add a version to an agent definition","operationId":"updateAgentDefinition","tags":["Agents"],"description":"Versions are immutable: this appends a new version (and renames the definition). Running instances stay on the version they were created with. Requires `agents_custom`. A built-in definition answers 409 `builtin_immutable` (built-ins change only through Optima releases); an archived one answers 409.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentDefinitionRequest"}}}},"responses":{"200":{"description":"Version added; the definition with its new current spec.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AgentDefinitionObject"}}}]}}}},"400":{"description":"Malformed JSON body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The licence does not include `agents_custom`, or the caller may not use one of the spec's tools.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Definition not found, or hidden by the licence (its kind is not licensed, or a built-in's tools need a missing feature).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The definition is built-in (message `builtin_immutable`) or archived, or the name is taken.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"A missing or too long `name`, or the spec failed validation (a continuous spec must satisfy the continuous rules).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"The attribute or event-type catalogue could not be read (data store unavailable), so the spec could not be checked; nothing is saved.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/agents/definitions/{id}/versions/{version}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"version","in":"path","required":true,"schema":{"type":"integer","minimum":1}}],"get":{"summary":"Get one version of an agent definition","operationId":"getAgentDefinitionVersion","tags":["Agents"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"The immutable version.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AgentDefinitionVersionObject"}}}]}}}},"403":{"description":"The licence includes neither `agents_custom` nor `agents_builtin`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Definition or version not found, or the definition is hidden by the licence.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/agents/definitions/{id}/archive":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"summary":"Archive an agent definition","operationId":"archiveAgentDefinition","tags":["Agents"],"description":"Requires `agents_custom`. Archived definitions cannot get new versions or new instances. Built-in definitions cannot be archived (409 `builtin_immutable`). A definition the licence hides answers 404.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"The archived definition.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AgentDefinitionObject"}}}]}}}},"403":{"description":"The licence does not include `agents_custom`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Definition not found, or hidden by the licence (its kind is not licensed, or a built-in's tools need a missing feature).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The definition is built-in (message `builtin_immutable`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/agents/instances":{"get":{"summary":"List agent instances","operationId":"listAgentInstances","tags":["Agents"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"definition_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"state","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated states: draft, dry_run, live, stopped, cancelled."}],"responses":{"200":{"description":"Instances with budget usage.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AgentInstanceObject"}}}}]}}}},"403":{"description":"The licence includes neither `agents_custom` nor `agents_builtin`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Unknown state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create an agent instance","operationId":"createAgentInstance","tags":["Agents"],"description":"Creates an instance in `draft`; start it with POST /agents/instances/{id}/start. The caller becomes the owner, so only console users (a session) may create instances: an application key or root caller gets 403. The caller must also hold `agents_editor`, `admin`, `account_admin` or `instance_admin` in the tenant (the roles the runtime requires of an owner; a custom role that merely grants this route does not qualify), else 403, so an instance is never cancelled on its first run. Budgets are tokens only. Needs `agents_custom` or `agents_builtin`; the definition's own kind must be licensed (403 `unlicensed_kind`) and, for a built-in, so must the features of its tools (403 `unlicensed_tools`). Every event type in the definition's `actions.events` must be declared in the tenant's event schema with each property at the declared type, else 422 `event_type_not_declared`. `limits` is validated first, before the definition is looked up, and a refused create leaves no instance: 422 `limits must be an object`, `limits.\"<key>\" is not a known limit`, `limits.<key> must be an integer from <min> to <max>` (a string or a fractional value is refused too), or `limits.tool_result_bytes (<n>) must not exceed limits.run_tool_result_bytes (<m>)`.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentInstanceCreateRequest"}}}},"responses":{"201":{"description":"Instance created.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AgentInstanceObject"}}}]}}}},"400":{"description":"Invalid payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The caller is not a console user (application key or root), holds no agents-owner role (`agents_editor`, `admin`, `account_admin`, `instance_admin`) in the tenant, or the licence lacks the definition's kind (message `unlicensed_kind`) or, for a built-in, one of its tools' features (message `unlicensed_tools`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Definition not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The definition is archived.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"A field failed validation, the version or provider does not qualify, the params do not match the definition, the time zone is unknown, `limits` is invalid (message names the key), a `purpose_param` value is not an active purpose, or an event type of the definition's `actions.events` is not declared with its properties (`data.code` is `event_type_not_declared`; `data.event_type` and `data.missing_properties` name the gap).","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"$ref":"#/components/schemas/AgentEventTypeNotDeclared"}]}}}},"503":{"description":"The event-type catalogue could not be read, so the definition's event types could not be checked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/agents/instances/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"summary":"Get an agent instance","operationId":"getAgentInstance","tags":["Agents"],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"The instance with budget usage.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AgentInstanceObject"}}}]}}}},"403":{"description":"The licence includes neither `agents_custom` nor `agents_builtin`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Instance not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/agents/instances/{id}/start":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"summary":"Start an agent instance","operationId":"startAgentInstance","tags":["Agents"],"description":"Moves a `draft` or `stopped` instance to `dry_run` or `live`. The change is logged as a `started` entry that records the resulting mode in `dry_run`. Starting a continuous instance in `live` when its latest continuous run was a dry run redoes the dry-run work: the response's `continuous.restart_pending` is then true (previews do not count).","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentModeRequest"}}}},"responses":{"200":{"description":"The updated instance.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AgentInstanceObject"}}}]}}}},"400":{"description":"Invalid payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The licence includes neither `agents_custom` nor `agents_builtin`, or lacks the feature of the instance's definition kind (message `unlicensed_kind`; `unlicensed_tools` for a built-in whose tool features lapsed).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Instance not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The instance's state does not allow starting, or it changed concurrently (reload and retry). A continuous instance that has no preview yet, or whose scope grew more than 25% beyond the previewed scope, is refused with a message starting `preview_required:`; request a preview first. Changing the mode of a running instance is not gated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Unknown mode.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/agents/instances/{id}/stop":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"summary":"Stop an agent instance","operationId":"stopAgentInstance","tags":["Agents"],"description":"Moves a `dry_run` or `live` instance to `stopped`. The change is logged as a `stopped` entry.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"The updated instance.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AgentInstanceObject"}}}]}}}},"403":{"description":"The licence includes neither `agents_custom` nor `agents_builtin`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Instance not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The instance's state does not allow stopping, or it changed concurrently.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/agents/instances/{id}/mode":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"summary":"Switch a running agent instance between dry run and live","operationId":"switchAgentMode","tags":["Agents"],"description":"Only a running instance can switch. Asking for the mode it is already in is a 409. The change is logged as a `mode_switched` entry that records the resulting mode in `dry_run`. Switching a continuous instance from `dry_run` to `live` when its latest continuous run was a dry run redoes the dry-run work (`continuous.restart_pending` becomes true; the next sweep deletes the records dry-run sweeps made and processes those profiles or events again, live; work a live run did is kept); `live` to `dry_run` never resets.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentModeRequest"}}}},"responses":{"200":{"description":"The updated instance.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AgentInstanceObject"}}}]}}}},"400":{"description":"Invalid payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The licence includes neither `agents_custom` nor `agents_builtin`, or lacks the feature of the instance's definition kind (message `unlicensed_kind`; `unlicensed_tools` for a built-in whose tool features lapsed).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Instance not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Already in that mode, the state does not allow switching, or it changed concurrently.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Unknown mode.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/agents/instances/{id}/preview":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"summary":"Request a cost preview of a continuous agent instance","operationId":"previewAgentInstance","tags":["Agents"],"description":"Queues a preview that samples 20 items and estimates the tokens one item costs. The call returns at once with `202`; the runtime runs it asynchronously and the estimate appears on the instance. A preview is allowed in the `draft`, `dry_run`, `live` and `stopped` states and counts against the instance budget. While a preview is already pending or running the call changes nothing and answers `duplicate: true` with the earlier request time. A new request is logged as a `preview_requested` entry. Reached by `agents_editor` and the roles with a wildcard, not by the auditors.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"202":{"description":"The preview is queued or was already requested.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AgentPreviewAccepted"}}}]}}}},"403":{"description":"The licence includes neither `agents_custom` nor `agents_builtin`, or lacks the feature of the instance's definition kind (message `unlicensed_kind`; `unlicensed_tools` for a built-in whose tool features lapsed).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Instance not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"The instance is cancelled, or its pending queue is full.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The pinned definition has no continuous trigger.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/agents/instances/{id}/runs":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"summary":"List an agent instance's runs","operationId":"listAgentRuns","tags":["Agents"],"description":"Newest first. Page backwards with `before`, the RFC 3339 `started_at` of the last run of the previous page. Reached by `agents_auditor` and the roles with a wildcard, not by `agents_editor`.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"before","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"RFC 3339 `started_at` cursor."}],"responses":{"200":{"description":"Runs, without their log.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AgentRunObject"}}}}]}}}},"403":{"description":"The licence includes neither `agents_custom` nor `agents_builtin`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Instance not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Invalid `limit` or `before`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/agents/instances/{id}/log":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"summary":"Read an agent instance's audit log","operationId":"listAgentLog","tags":["Agents"],"description":"Newest first. Page backwards with `before`, the numeric `id` of the last entry of the previous page. Entries are masked per reader: see AgentLogEntryObject. Reached by `agents_auditor` and the roles with a wildcard, not by `agents_editor`.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"before","in":"query","required":false,"schema":{"type":"integer","format":"int64","minimum":1},"description":"Log entry id cursor."},{"name":"kind","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated kinds: created, started, stopped, mode_switched, cancelled, system_stopped, action, triggers_dropped, preview_requested, item_failed, run_summary."},{"name":"run_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"Only entries of this run."},{"name":"profile_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"Only entries that name this profile. Entries masked for the reader are omitted. The server scans up to 20 reads of 200 rows to fill the limit, so a page can be short, even empty, before the end of the log: keep paging with `before` = `page.next_before` while `page.has_more` is true. Without this filter the response carries no `next_before`/`has_more`."}],"responses":{"200":{"description":"Log entries, masked for the reader.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AgentLogEntryObject"}}}}]}}}},"403":{"description":"The licence includes neither `agents_custom` nor `agents_builtin`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Instance not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Invalid `limit`, `before` or `kind`, or a `run_id` or `profile_id` that is not a UUID.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/cdp/api/v1/agents/runs/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"summary":"Get one agent run with its log","operationId":"getAgentRun","tags":["Agents"],"description":"The run plus its log entries (up to 200), masked for the reader.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"responses":{"200":{"description":"The run with `log`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GenericResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AgentRunObject"}}}]}}}},"403":{"description":"The licence includes neither `agents_custom` nor `agents_builtin`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Run not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"tags":[{"name":"Health","description":"Liveness check"},{"name":"Auth","description":"Human-operator authentication (email + password → opaque session tokens)"},{"name":"Users","description":"User account management (admin-only; requires session token or API key with admin role)"},{"name":"Tenants","description":"Multitenancy: tenant switcher, membership\nlisting, and invite-by-email membership management. Tenant resolution on\nAPI routes: an application key is pinned to its tenant (an `X-Tenant`\nheader on a non-cross-tenant key is a 403, never silently ignored);\nusers resolve their session's active tenant, overridable per request via\n`X-Tenant` when they are a member; root keys may select any tenant via\n`X-Tenant`. `POST /tenants` creates and provisions a new tenant.\n"},{"name":"Usage","description":"Licensing and usage metering. Two independent mechanisms, deliberately not conflated:\n\n**Feature licence** — an allowlist of packages on the account, binary and\nHARD-enforced on every route (403 `feature_not_licensed`).\n\n**Usage licence** — three metered quantities (billable profiles, stored\nevents, operations) plus a separate Connect/CDC allowance, measured per\nproduction environment and rolled up to the account. **Soft-enforced\nonly**: over-limit produces a warning, a threshold email and an invoice\nline, never a block. Dropping a client's data because they exceeded a\ncount is unrecoverable, and it would happen exactly when their campaign\nis working.\n\nThe band is not negotiated in platform units: the client declares their\nown customer count and the limits are derived by per-vertical constants\n(baseline 1 customer = 4.5 billable profiles, 30 events/month at 6 months\nretention). Derived limits are then FROZEN — recomputing them on read\nwould silently re-price a live contract.\n\nThree levels: `/usage` (this environment's contribution, no limits),\n`/accounts/{id}/usage` (the licence view), `/instance/usage` (the fleet\nplus constant calibration).\n"},{"name":"Accounts","description":"Accounts group the tenants (environments) that belong to one customer and\ncarry its licence. An account administrator manages the account's members,\nsees its whole team and key inventory, and reads its own account detail;\ncreating, renaming and deleting accounts is reserved to the instance operator.\n"},{"name":"Roles","description":"Role catalog and RBAC permission management (admin-only). A role is a catalog\nrow (name + description); its permissions are route permissions\n(route pattern + action), managed together via these endpoints. Built-in\nsystem roles (such as admin, engineer, analytics_editor and data_viewer) can be edited but not deleted.\n"},{"name":"Entities","description":"Control-plane entity definitions (profile type schemas)"},{"name":"Event Types","description":"Control-plane event type definitions (event attribute schemas)"},{"name":"Profiles","description":"Data-plane profile management (identity, attributes, merging)"},{"name":"Events","description":"Data-plane event ingestion and management"},{"name":"Computed Attributes","description":"Virtual profile attributes computed on demand (segmentations & functions)"},{"name":"Data Contracts","description":"Per-entity/event-type validation and transformation rules applied at ingestion time"},{"name":"Notifications","description":"Notification subscription and template management; the notification service delivers queued messages"},{"name":"Privacy","description":"Privacy-Native Architecture — three-gate consent enforcement, erasure requests, retention policies,\nand audit log. Gate 1 checks caller purpose authorization, Gate 2 checks attribute purpose tags,\nGate 3 checks per-profile consent records. Enforcement mode is an instance setting\n(audit | enforce | strict).\n"},{"name":"Custom Datasets","description":"Operator-defined reference data tables (product catalogs, campaigns, store locations, etc.).\nEach dataset has a named schema definition and records stored using\nthe same EAV typed-column pattern as profile/event attributes. Supports M:N profile–record\nlinking with optional link_type labels. Dataset definitions require engineer/admin role;\nrecord ingest requires engineer or admin; record reads require data_viewer or a broader role.\n"},{"name":"Identity","description":"Composable Identity Graph — operator-defined matching rules\n(exact, normalized, email-domain and fuzzy comparisons) derive a\nnon-destructive identity graph. The resolver blocks candidates by normalized\nidentifier value, evaluates rules, runs connected-components (Union-Find), and\nwrites clusters to the data store; raw profiles are never mutated. Resolution runs\non demand, automatically after ingest (queued and processed in the background), and as\na bulk re-resolution per ruleset. Ruleset/rule management and bulk runs require\nengineer/admin; on-demand resolution and cluster reads are available to analytics_editor or a broader role.\n"},{"name":"Analytics","description":"Internal Analytics — a query builder over CDP data (profiles, events, custom\ndatasets). Operators save bounded JSON report definitions; the backend translates them into\nparameterised queries and returns a generic column/row result. Supports aggregate,\nfunnel (windowFunnel), and retention (cohort matrix) query types. Reports carry a computed privacy manifest\n(min_pii_level_required, required_purposes); execution is gated on the caller's PII access\nlevel and stored purpose authorizations. Report CRUD and execution require analytics_editor or a broader role; delete\nrequires engineer/admin.\n"},{"name":"Applications","description":"API key management — create, list, view, update, rotate, revoke (enable/disable), and\ndelete application API keys stored by the platform. Keys are returned\nin plaintext only once (on create and rotate); only their SHA-512 hash is persisted.\nRotation moves the current hash into `api_key_hash_old` so the previous key keeps working\nduring a grace period. These endpoints require the admin role or a root key; created keys are\nalways non-root, and root applications cannot be rotated/revoked/deleted or edited via the\nordinary management endpoints (403 through `mustGetManageableApp`). Since the access-model\nredesign the three provider-operator flags — `is_root`, `cross_tenant_allowed` and\n`delegation_allowed` — ARE settable, but only through\n`PUT /applications/{id}/instance-flags` and only by the instance persona (a root key or an\n`instance_admin` session); flipping `is_root` in either direction additionally requires\nconfirming the application's exact name. The former \"DB level only\" rule is retired.\n"},{"name":"AI","description":"LLM-backed features over an OpenAI-compatible provider (configured by host + key + model;\ndisabled unless enabled on the instance). Natural-language segment translation turns a plain-English\naudience description into a validated query-builder filter (the model emits filter JSON, which\npasses the same validation as `GET /profiles?filter=` — never raw SQL). Profile summarization\nproduces a short operator brief, gated by the privacy three-gate model plus an external-LLM PII\ncap so data above the cap never leaves the platform; each call is\naudit-logged with the `llm_summary` operation.\n"},{"name":"Connect","description":"Optima Connect — data integration layer for batch and streaming import/export. Operators\nconfigure connectors (source/sink + protocol + data type), define CSV field mappings and\nStarlark transform scripts, and schedule or manually trigger batch import runs. The\nconnector service polls for pending runs and executes them. Connectors move\nprofiles, events, consents, profile links, custom datasets and signals in or out over\nSFTP, S3, GCS, Azure Blob, SQL databases or file upload, and stream through Kafka/NATS. Credentials are AES-256-GCM encrypted at rest; GET responses never\nreturn plaintext credentials (`has_credentials` flag only). Connector management requires\nengineer/admin; run log reads are available to integration_viewer or a broader role.\n"},{"name":"Networks","description":"Private networks: named, tenant-owned tunnel definitions (SSH jump hosts,\nSOCKS5 and HTTP CONNECT proxies, WireGuard peers) through which connectors,\ncampaign channel providers and journey webhooks reach systems inside the\ncustomer's own network. Credentials are write-only.\n"},{"name":"Content","description":"Content Manager — the tenant asset library.\nMetadata is kept separately; the bytes live in S3-compatible object storage and\nnowhere else. Items carry folders + tags, manually uploaded size variants\n(`original`, `desktop`, `mobile`, …), an approval workflow and an\nappend-only revision history that can be restored from.\n\nTwo prefixes, and the split IS the approval control: `/content` is\nauthoring (content_editor, campaign_admin, engineer, admin),\n`/content-approvals` is reviewing (content_approver, campaign_admin,\nengineer, admin — deliberately not content_editor). Permissions are\nallow-only and a trailing `/*` matches everything below it, so an approve\nroute under `/content/*` would have fallen inside every author's grant.\n\n`status` describes the current DRAFT; what the public URL serves is\ndecided by the pins (`public` + `published_revision` + the frozen\nrendition map). Editing a live item therefore never takes the approved\nbytes off the air.\n\nNo `X-Purpose` header and no consent gate: content is control-plane data,\nnot customer data. The one privacy-shaped control is per-item `pii_level`,\nwhich gates DOWNLOADS against the caller's `pii_access_level`;\nPII-levelled content can never be made public. Published items are served\npublicly by Optima Edge at `/edge/v1/assets/{token}`, documented in\n`docs/oapi3_edge.yml`.\n"},{"name":"Edge","description":"Optima Edge admin API — operator-facing configuration for the public tracking + content\ngateway (Optima Edge). One singleton settings row designates the tracking entity and\ndevice identifier key and sets the collection-consent posture; SDK keys are public `oek_`\ntokens (web keys carry an origin allowlist); category mappings turn semantic SDK categories\ninto CDP event types with an allowlist attribute mapping; content items are the\nstructured-JSON payloads served by `GET /edge/v1/content`. The gateway polls this configuration read-only — this API is the only writer. Settings,\nkeys and mappings require engineer/admin; content authoring is also open to content_editor and campaign_admin;\nread-only roles can only read. The public `/edge/v1/*` surface is documented separately in\n`docs/oapi3_edge.yml` (arrives with the gateway itself).\n"},{"name":"Signals","description":"Signals: freshness-aware behavioural values per profile. `template` signals\nare computed from the built-in template library; `external` signals carry\nvalues your own models push in bulk or through a Connect feed. Also covers\nsignal cohorts and per-profile value history.\n"},{"name":"Recommendations","description":"Item-level recommendations: a catalogue pins a recommendation strategy\n(field roles, interaction weighting, business rules) to an operator-defined\ncustom dataset holding the item catalogue. The catalogue CRUD manages\ndefinitions only — never customer data, so it is exempt from the\nX-Purpose gate like custom-dataset definitions; `POST\n/recommendations/{catalog}` ranks items for one profile and does need\n`X-Purpose`. Everything here requires the `recommendations` licence\nfeature (Decision package).\n"},{"name":"Agents","description":"Optima Agents: the tool catalogue, versioned agent definitions, agent\ninstances (token budgets, dry-run and live modes) and the run and audit\nlog reads. Everything here requires the `agents_custom` licence feature.\nReached by the built-in `agents_editor` (definitions, instances and\nlifecycle, not runs or log; plus the entity, event-type, purpose and\nnotification-field catalogue reads the definition editor needs) and\n`agents_auditor` (reads, runs and log);\n`admin`, `account_admin` and `instance_admin` through their\n`/cdp/api/v1/*` wildcards; and the generic `auditor`, which reads every\nagents GET. `engineer` does not reach these routes. Not exposed as MCP\ntools.\n"}]}