@epilot/customer-portal-client 0.44.0 → 0.46.1

package/src/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.0.3",
   "info": {
     "title": "Portal API",
-    "description": "Backend for epilot portals - End Customer Portal & Installer Portal",
+    "description": "Backend for epilot portals - End Customer Portal & Installer Portal\n",
     "version": "1.0.0"
   },
   "tags": [
@@ -281,6 +281,7 @@
             "PortalAuth": []
           }
         ],
+        "x-contact-identification-token": true,
         "responses": {
           "204": {
             "description": "Tokens is valid for the given organization."
@@ -543,10 +544,7 @@
                   },
                   "language": {
                     "type": "string",
-                    "enum": [
-                      "de",
-                      "en"
-                    ]
+                    "example": "de"
                   }
                 }
               }
@@ -962,11 +960,12 @@
                 "PT1H",
                 "P1D",
                 "P1M",
-                "P1Y"
+                "P1Y",
+                "custom"
               ]
             },
             "required": true,
-            "description": "Interval between consumption data points (e.g., PT15M for 15 minutes, PT1H for hourly). Not all intervals have to be supported."
+            "description": "Interval between consumption data points (e.g., PT15M for 15 minutes, PT1H for hourly). Not all intervals have to be supported. `custom` is period-based retrieval for sources that advertise it in their `visualizationMetadata.intervals`: the App returns one record per period it has data for within `from`..`to`, each carrying `period`, and the portal renders every record as its own bar.\n"
           },
           {
             "in": "query",
@@ -1020,6 +1019,30 @@
                               "en": "Billing period 1",
                               "de": "Abrechnungszeitraum 1"
                             }
+                          },
+                          "period": {
+                            "type": "object",
+                            "description": "The date range this value covers. Required for period-based sources (`interval=custom`), whose records don't sit on a fixed time grid: the portal renders one bar per record, orders them by `period.from`, and — unless `label` is set — labels each bar with the formatted `from` - `to` range. Ignored for interval-based retrieval.\n",
+                            "properties": {
+                              "from": {
+                                "type": "string",
+                                "format": "date-time",
+                                "description": "Start of the covered period."
+                              },
+                              "to": {
+                                "type": "string",
+                                "format": "date-time",
+                                "description": "End of the covered period. Shown as given in the fallback label, so pass the date the period visibly ends on (consecutive periods may share this boundary).\n"
+                              }
+                            },
+                            "required": [
+                              "from",
+                              "to"
+                            ],
+                            "example": {
+                              "from": "2024-01-03T00:00:00.000Z",
+                              "to": "2025-01-05T00:00:00.000Z"
+                            }
                           }
                         },
                         "required": [
@@ -2130,7 +2153,23 @@
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/PortalConfig"
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/PortalConfig"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "identity_providers": {
+                          "type": "array",
+                          "description": "SSO identity providers configured for the portal, reduced to the\nfields needed to render provider login buttons. Omitted when the\nportal has no providers.\n",
+                          "items": {
+                            "$ref": "#/components/schemas/PublicIdentityProvider"
+                          }
+                        }
+                      }
+                    }
+                  ]
                 }
               }
             }
@@ -3293,6 +3332,7 @@
         "operationId": "getSchemas",
         "summary": "getSchemas",
         "description": "Retrieves the schemas. Only schemas usable in the private part of the portal are returned.",
+        "x-contact-identification-token": true,
         "tags": [
           "ECP"
         ],
@@ -3663,6 +3703,7 @@
         "operationId": "getContact",
         "summary": "getContact",
         "description": "Retrieves the contact of the logged in user.",
+        "x-contact-identification-token": true,
         "tags": [
           "ECP"
         ],
@@ -3893,6 +3934,9 @@
           "404": {
             "$ref": "#/components/responses/NotFound"
           },
+          "429": {
+            "$ref": "#/components/responses/TooManyRequests"
+          },
           "500": {
             "$ref": "#/components/responses/InternalServerError"
           }
@@ -3979,6 +4023,78 @@
           "404": {
             "$ref": "#/components/responses/NotFound"
           },
+          "429": {
+            "$ref": "#/components/responses/TooManyRequests"
+          },
+          "500": {
+            "$ref": "#/components/responses/InternalServerError"
+          }
+        }
+      }
+    },
+    "/v3/portal/public/contact/identify": {
+      "post": {
+        "operationId": "identifyContact",
+        "summary": "identifyContact",
+        "description": "Identify a contact by the portal's configured registration identifiers and, on a match,\nissue a short-lived bearer token that acts as that contact.\n\nResolution is identical to `checkContactExistsV3`. The token does not grant a portal\nsession; it is accepted only on the operations listed in `allowed_operations`, and\nexpires at `expires_at`. Requires `surface_id` to name a surface of the portal whose\n`authentication` is `registration_identifiers`; returns 403 otherwise. The token is\nconfined to that surface's data access. Requests may be rate limited (429).\n",
+        "security": [],
+        "tags": [
+          "Public"
+        ],
+        "parameters": [
+          {
+            "in": "query",
+            "name": "portal_id",
+            "required": false,
+            "schema": {
+              "$ref": "#/components/schemas/PortalId"
+            },
+            "description": "PortalId of the portal (required if domain is not provided)"
+          },
+          {
+            "in": "query",
+            "name": "domain",
+            "required": false,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Portal domain for identification (alternative to portal_id)"
+          }
+        ],
+        "requestBody": {
+          "description": "Request payload",
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ContactIdentifyRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "The identification result. On a match, `contact_id` and `token` are present. When no\ncontact matched, only `reason` is present - the response is deliberately shaped the same\nway for every negative outcome so it cannot be used to enumerate contacts.\n",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ContactIdentifyResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/InvalidRequest"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          },
+          "429": {
+            "$ref": "#/components/responses/TooManyRequests"
+          },
           "500": {
             "$ref": "#/components/responses/InternalServerError"
           }
@@ -4053,6 +4169,9 @@
           "404": {
             "$ref": "#/components/responses/NotFound"
           },
+          "429": {
+            "$ref": "#/components/responses/TooManyRequests"
+          },
           "500": {
             "$ref": "#/components/responses/InternalServerError"
           }
@@ -7566,6 +7685,7 @@
             "PortalAuth": []
           }
         ],
+        "x-contact-identification-token": true,
         "requestBody": {
           "content": {
             "application/json": {
@@ -7606,6 +7726,7 @@
         "operationId": "searchPortalUserEntities",
         "summary": "searchPortalUserEntities",
         "description": "Search all entities of a portal user",
+        "x-contact-identification-token": true,
         "tags": [
           "ECP"
         ],
@@ -8485,6 +8606,7 @@
       "post": {
         "operationId": "getMeterReadings",
         "summary": "getMeterReadings",
+        "x-contact-identification-token": true,
         "description": "Fetches meter readings for a counter and optionally resolves Handlebars\ntemplate strings against each reading object using @epilot/variables.\n",
         "tags": [
           "ECP"
@@ -8689,6 +8811,68 @@
         }
       }
     },
+    "/v3/portal/public/sso/providers/{provider_slug}": {
+      "get": {
+        "operationId": "getPublicSSOProviderV3",
+        "summary": "getPublicSSOProviderV3",
+        "description": "Returns the public configuration of a single SSO identity provider with env var\nplaceholders (incl. secrets) already resolved against the organization's environment.\n\nPortal-scoped variant of getSSOProvider: the portal is identified by `org_id` +\n`portal_id` only, so callers without a portal domain (e.g. standalone journeys)\ncan resolve the provider.\nOnly the web OIDC configuration is returned: `mobile_oidc_config` is omitted\nentirely, and the web `client_secret` and `metadata.test_auth_*` credentials are\nnever returned — they are used server-side by the SSO callback to exchange the\nauthorization code for tokens. `oidc_config.has_client_secret` is set when either\nexists, so clients route the exchange through the callback.\n",
+        "security": [],
+        "tags": [
+          "Public"
+        ],
+        "parameters": [
+          {
+            "in": "path",
+            "name": "provider_slug",
+            "required": true,
+            "description": "Provider slug (organization-unique)",
+            "schema": {
+              "$ref": "#/components/schemas/ProviderSlug"
+            }
+          },
+          {
+            "in": "query",
+            "name": "org_id",
+            "required": true,
+            "description": "epilot organization id",
+            "schema": {
+              "type": "string",
+              "example": 123
+            }
+          },
+          {
+            "in": "query",
+            "name": "portal_id",
+            "required": true,
+            "description": "ID of the Portal",
+            "schema": {
+              "$ref": "#/components/schemas/PortalId"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Resolved public SSO provider configuration, reduced to the web OIDC flow. `mobile_oidc_config` is omitted; `oidc_config.client_secret` and the `metadata.test_auth_*` credentials are stripped (kept server-side for the token exchange).",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ProviderPublicConfigV3"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/InvalidRequest"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          },
+          "500": {
+            "$ref": "#/components/responses/InternalServerError"
+          }
+        }
+      }
+    },
     "/v2/portal/public/sso/login": {
       "post": {
         "operationId": "ssoLogin",
@@ -8834,6 +9018,11 @@
                 "properties": {
                   "provider_slug": {
                     "$ref": "#/components/schemas/ProviderSlug"
+                  },
+                  "login_only": {
+                    "type": "boolean",
+                    "default": false,
+                    "description": "Authenticate existing identities only. When no portal user and no contact matches the identity, the login fails with a 400 response carrying `reason: PORTAL_ACCOUNT_NOT_FOUND` instead of registering a new portal user. A matched contact is still provisioned a portal user; contacts and accounts are never created."
                   }
                 }
               }
@@ -8860,6 +9049,9 @@
                 }
               }
             }
+          },
+          "400": {
+            "$ref": "#/components/responses/InvalidRequest"
           }
         }
       }
@@ -9131,6 +9323,7 @@
             "EitherAuth": []
           }
         ],
+        "x-contact-identification-token": true,
         "parameters": [
           {
             "in": "query",
@@ -10595,106 +10788,50 @@
         }
       }
     },
-    "/v3/portal/configs": {
-      "get": {
-        "operationId": "listAllPortalConfigs",
-        "summary": "listAllPortalConfigs",
-        "description": "Retrieves all portal configurations.",
-        "tags": [
-          "ECP Admin"
-        ],
-        "security": [
-          {
-            "EpilotAuth": []
-          }
-        ],
-        "responses": {
-          "200": {
-            "description": "All portal configs retrieved successfully.",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "type": "object",
-                  "properties": {
-                    "data": {
-                      "type": "array",
-                      "items": {
-                        "$ref": "#/components/schemas/PortalConfigV3"
-                      }
-                    }
-                  }
-                }
-              }
-            }
-          },
-          "401": {
-            "$ref": "#/components/responses/Unauthorized"
-          },
-          "403": {
-            "$ref": "#/components/responses/Forbidden"
-          },
-          "500": {
-            "$ref": "#/components/responses/InternalServerError"
-          }
-        }
-      }
-    },
-    "/v3/portal/config/swap": {
+    "/v3/portal/config/{portal_id}/revisions": {
       "post": {
-        "operationId": "swapPortalConfig",
-        "summary": "swapPortalConfig",
-        "description": "Swaps the portal configuration of two portals.",
+        "operationId": "createPortalRevision",
+        "summary": "createPortalRevision",
+        "description": "Creates a new revision — a complete, immutable snapshot of the portal's configuration, pages and email templates. Nothing about the live portal changes; the snapshot only becomes live when it is published.\n\nThe payload must be COMPLETE. This endpoint does not merge against live or against the previous revision: publishing a revision deletes every live page the revision does not contain. The server validates structure only — `pages` present, each page carrying `id`, `slug`, `order` and `blocks`, and no two pages sharing an `id` or a `slug`. Semantic completeness of the config is a promise the caller makes, and a partial payload is honoured rather than rejected.\n\n`email_templates` is optional, and absence means \"keep the portal's current templates\", never \"no templates\". A present but partial map is taken verbatim.\n",
         "tags": [
           "ECP Admin"
         ],
-        "security": [
+        "parameters": [
           {
-            "EpilotAuth": []
+            "in": "path",
+            "name": "portal_id",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid",
+              "example": "5da0a718-c822-403d-9f5d-20d4584e0528"
+            },
+            "description": "Portal ID (readonly UUID generated on portal creation)"
           }
         ],
         "requestBody": {
-          "description": "Source and target portal IDs",
+          "description": "Complete portal configuration snapshot",
           "required": true,
           "content": {
             "application/json": {
               "schema": {
-                "type": "object",
-                "required": [
-                  "source_portal_id",
-                  "target_portal_id"
-                ],
-                "properties": {
-                  "source_portal_id": {
-                    "$ref": "#/components/schemas/PortalId"
-                  },
-                  "target_portal_id": {
-                    "$ref": "#/components/schemas/PortalId"
-                  },
-                  "items_to_swap": {
-                    "type": "array",
-                    "items": {
-                      "$ref": "#/components/schemas/SwappableConfig"
-                    },
-                    "description": "Optional, opt-in configuration items to additionally swap on top of the always-swapped pages and functional config. Defaults to an empty list (nothing extra swapped). Domain and access/security settings can never be swapped."
-                  }
-                }
+                "$ref": "#/components/schemas/PortalRevisionRequest"
               }
             }
           }
         },
+        "security": [
+          {
+            "EpilotAuth": []
+          }
+        ],
         "responses": {
-          "200": {
-            "description": "Domain and users swapped successfully.",
+          "201": {
+            "description": "Revision created successfully.",
             "content": {
               "application/json": {
                 "schema": {
-                  "type": "object",
-                  "properties": {
-                    "message": {
-                      "type": "string",
-                      "example": "Domain and users swapped successfully."
-                    }
-                  }
+                  "$ref": "#/components/schemas/PortalRevisionCreated"
                 }
               }
             }
@@ -10711,55 +10848,67 @@
           "404": {
             "$ref": "#/components/responses/NotFound"
           },
+          "409": {
+            "$ref": "#/components/responses/Conflict"
+          },
           "500": {
             "$ref": "#/components/responses/InternalServerError"
           }
         }
-      }
-    },
-    "/v3/portal/config/clone": {
-      "post": {
-        "operationId": "clonePortalConfig",
-        "summary": "clonePortalConfig",
-        "description": "Creates a new portal by cloning configuration and pages from an existing portal. The new portal gets its own domain, users, email templates, and authentication settings.",
+      },
+      "get": {
+        "operationId": "listPortalRevisions",
+        "summary": "listPortalRevisions",
+        "description": "Lists a portal's revision history, newest first. Metadata only — no config blob, no page bodies. `is_published` says whether that revision is the one currently live, which is a different question from `published_at`, which records the last time it was published.\n",
         "tags": [
           "ECP Admin"
         ],
+        "parameters": [
+          {
+            "in": "path",
+            "name": "portal_id",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid",
+              "example": "5da0a718-c822-403d-9f5d-20d4584e0528"
+            },
+            "description": "Portal ID (readonly UUID generated on portal creation)"
+          },
+          {
+            "in": "query",
+            "name": "limit",
+            "required": false,
+            "schema": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 100,
+              "default": 25
+            },
+            "description": "Maximum number of revisions to return"
+          },
+          {
+            "in": "query",
+            "name": "cursor",
+            "required": false,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Opaque pagination cursor, taken from a previous response's `next_cursor`"
+          }
+        ],
         "security": [
           {
             "EpilotAuth": []
           }
         ],
-        "requestBody": {
-          "description": "Source portal ID and optional name for the cloned portal",
-          "required": true,
-          "content": {
-            "application/json": {
-              "schema": {
-                "type": "object",
-                "required": [
-                  "source_portal_id"
-                ],
-                "properties": {
-                  "source_portal_id": {
-                    "$ref": "#/components/schemas/PortalId"
-                  },
-                  "name": {
-                    "type": "string",
-                    "description": "Name for the cloned portal. Defaults to \"Copy of <source portal name>\"."
-                  }
-                }
-              }
-            }
-          }
-        },
         "responses": {
-          "201": {
-            "description": "Portal cloned successfully.",
+          "200": {
+            "description": "Revision history retrieved successfully.",
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/PortalConfigV3"
+                  "$ref": "#/components/schemas/PortalRevisionList"
                 }
               }
             }
@@ -10782,86 +10931,49 @@
         }
       }
     },
-    "/v3/portal/partner/invite": {
-      "post": {
-        "operationId": "invitePartner",
-        "summary": "invitePartner",
-        "description": "Invites a partner to a portal",
+    "/v3/portal/config/{portal_id}/revisions/{revision_id}": {
+      "get": {
+        "operationId": "getPortalRevision",
+        "summary": "getPortalRevision",
+        "description": "Returns the full content of one revision: the snapshotted config, its pages (in the live `Page` shape), email templates and identity providers with secrets redacted.\n\nThis is a pure read. The server records nothing about it: no \"loaded\" marker, no audit entry, and no change to which revision is live. Revision content re-enters the system only as a new `POST .../revisions`.\n\nSecret-typed extension option values are removed from `config` entirely, not masked.\n\nReturns `409` when the revision exists but its stored config or email templates row cannot be read, rather than a partial snapshot. Saving again produces a complete revision.\n",
         "tags": [
-          "ECP"
+          "ECP Admin"
         ],
-        "security": [
+        "parameters": [
           {
-            "PortalAuth": []
+            "in": "path",
+            "name": "portal_id",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid",
+              "example": "5da0a718-c822-403d-9f5d-20d4584e0528"
+            },
+            "description": "Portal ID (readonly UUID generated on portal creation)"
+          },
+          {
+            "in": "path",
+            "name": "revision_id",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "example": "2026-08-25T14:03:11.482Z-a7f3c1d9"
+            },
+            "description": "Revision ID. Contains `:` characters — percent-encode it."
           }
         ],
-        "requestBody": {
-          "description": "Partner to invite",
-          "required": true,
-          "content": {
-            "application/json": {
-              "schema": {
-                "type": "object",
-                "required": [
-                  "email"
-                ],
-                "properties": {
-                  "email": {
-                    "type": "string",
-                    "description": "Email address of the partner to invite"
-                  },
-                  "contact_data": {
-                    "type": "object",
-                    "description": "Additional contact entity fields to set when creating the contact for the invited user.\nThese are mapped directly to contact entity attributes (e.g. first_name, last_name, phone).\nValues can be strings or arrays of strings (for multiselect attributes).\n",
-                    "additionalProperties": {
-                      "oneOf": [
-                        {
-                          "type": "string"
-                        },
-                        {
-                          "type": "array",
-                          "items": {
-                            "type": "string"
-                          }
-                        }
-                      ]
-                    }
-                  },
-                  "portal_user_data": {
-                    "type": "object",
-                    "description": "Additional portal user entity fields to set when creating the portal user for the invited user.\nThese are mapped directly to portal_user entity attributes.\nValues can be strings or arrays of strings (for multiselect attributes).\n",
-                    "additionalProperties": {
-                      "oneOf": [
-                        {
-                          "type": "string"
-                        },
-                        {
-                          "type": "array",
-                          "items": {
-                            "type": "string"
-                          }
-                        }
-                      ]
-                    }
-                  }
-                }
-              }
-            }
+        "security": [
+          {
+            "EpilotAuth": []
           }
-        },
+        ],
         "responses": {
           "200": {
-            "description": "User invited successfully",
+            "description": "Revision retrieved successfully.",
             "content": {
               "application/json": {
                 "schema": {
-                  "type": "object",
-                  "properties": {
-                    "message": {
-                      "type": "string",
-                      "example": "User invited successfully"
-                    }
-                  }
+                  "$ref": "#/components/schemas/PortalRevision"
                 }
               }
             }
@@ -10878,142 +10990,177 @@
           "404": {
             "$ref": "#/components/responses/NotFound"
           },
+          "409": {
+            "$ref": "#/components/responses/Conflict"
+          },
           "500": {
             "$ref": "#/components/responses/InternalServerError"
           }
         }
       }
     },
-    "/v3/portal/partner/list": {
-      "get": {
-        "operationId": "listBusinessPartners",
-        "summary": "listBusinessPartners",
-        "description": "Lists all business partners linked to the businessaccount",
+    "/v3/portal/config/{portal_id}/publish": {
+      "post": {
+        "operationId": "publishPortalRevision",
+        "summary": "publishPortalRevision",
+        "description": "Makes one revision the portal's live configuration, atomically: either everything below takes effect or nothing does. Publish is a full-snapshot replace: it writes config, every page and email templates to match the revision exactly, and deletes every live page the revision does not contain.\n\nAccepts any valid `revision_id` for the portal, old or new. There is no separate rollback endpoint and none is needed.\n\nThe same atomic publish stamps `name`, `description` and `published_at` onto the revision being published — permanently, on that revision, and not on any later one that supersedes it as live. `name` is generated server-side when the request omits it, so every published revision carries one.\n\nConflict detection covers the live config only: publish is rejected with `409` when the live config changed after publish read it. Live pages, their redirect routes and the email templates are replaced outright — a concurrent edit to a live page is not detected and is overwritten. `409` is also returned when the revision's stored config or email templates cannot be read, or when two of its pages would resolve to the same slug. A domain the revision claims that another portal already owns is a `400`.\n",
         "tags": [
-          "ECP"
+          "ECP Admin"
+        ],
+        "parameters": [
+          {
+            "in": "path",
+            "name": "portal_id",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid",
+              "example": "5da0a718-c822-403d-9f5d-20d4584e0528"
+            },
+            "description": "Portal ID (readonly UUID generated on portal creation)"
+          }
         ],
+        "requestBody": {
+          "description": "The revision to publish",
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PublishRevisionRequest"
+              }
+            }
+          }
+        },
         "security": [
           {
-            "PortalAuth": []
+            "EpilotAuth": []
           }
         ],
         "responses": {
           "200": {
-            "description": "Business partners listed successfully",
+            "description": "Revision published successfully.",
             "content": {
               "application/json": {
                 "schema": {
-                  "type": "object",
-                  "properties": {
-                    "data": {
-                      "type": "array",
-                      "items": {
-                        "$ref": "#/components/schemas/BusinessPartnerItem"
-                      }
-                    }
-                  }
+                  "$ref": "#/components/schemas/PublishResult"
                 }
               }
             }
           },
+          "400": {
+            "$ref": "#/components/responses/InvalidRequest"
+          },
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
           "403": {
             "$ref": "#/components/responses/Forbidden"
           },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          },
+          "409": {
+            "$ref": "#/components/responses/Conflict"
+          },
           "500": {
             "$ref": "#/components/responses/InternalServerError"
+          },
+          "503": {
+            "$ref": "#/components/responses/ServiceUnavailable"
           }
         }
       }
     },
-    "/v3/portal/partner/{partner_id}/resend-invitation": {
-      "post": {
-        "operationId": "resendPartnerInvitation",
-        "summary": "resendPartnerInvitation",
-        "description": "Resends an invitation email to a partner",
+    "/v3/portal/configs": {
+      "get": {
+        "operationId": "listAllPortalConfigs",
+        "summary": "listAllPortalConfigs",
+        "description": "Retrieves all portal configurations.",
         "tags": [
-          "ECP"
+          "ECP Admin"
         ],
         "security": [
           {
-            "PortalAuth": []
-          }
-        ],
-        "parameters": [
-          {
-            "name": "partner_id",
-            "in": "path",
-            "required": true,
-            "schema": {
-              "type": "string",
-              "description": "ID of the partner to resend invitation to"
-            }
+            "EpilotAuth": []
           }
         ],
         "responses": {
           "200": {
-            "description": "Partner invitation resent successfully",
+            "description": "All portal configs retrieved successfully.",
             "content": {
               "application/json": {
                 "schema": {
                   "type": "object",
                   "properties": {
-                    "message": {
-                      "type": "string",
-                      "example": "Partner invitation resent successfully"
+                    "data": {
+                      "type": "array",
+                      "items": {
+                        "$ref": "#/components/schemas/PortalConfigV3"
+                      }
                     }
                   }
                 }
               }
             }
           },
-          "400": {
-            "$ref": "#/components/responses/InvalidRequest"
-          },
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
           "403": {
             "$ref": "#/components/responses/Forbidden"
           },
-          "404": {
-            "$ref": "#/components/responses/NotFound"
-          },
           "500": {
             "$ref": "#/components/responses/InternalServerError"
           }
         }
       }
     },
-    "/v3/portal/partner/{partner_id}/revoke": {
-      "delete": {
-        "operationId": "revokePartner",
-        "summary": "revokePartner",
-        "description": "Revokes a partner from a portal",
+    "/v3/portal/config/swap": {
+      "post": {
+        "operationId": "swapPortalConfig",
+        "summary": "swapPortalConfig",
+        "description": "Swaps the portal configuration of two portals.",
         "tags": [
-          "ECP"
+          "ECP Admin"
         ],
         "security": [
           {
-            "PortalAuth": []
+            "EpilotAuth": []
           }
         ],
-        "parameters": [
-          {
-            "name": "partner_id",
-            "in": "path",
-            "required": true,
-            "schema": {
-              "type": "string",
-              "description": "ID of the partner to revoke from the portal"
+        "requestBody": {
+          "description": "Source and target portal IDs",
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": [
+                  "source_portal_id",
+                  "target_portal_id"
+                ],
+                "properties": {
+                  "source_portal_id": {
+                    "$ref": "#/components/schemas/PortalId"
+                  },
+                  "target_portal_id": {
+                    "$ref": "#/components/schemas/PortalId"
+                  },
+                  "items_to_swap": {
+                    "type": "array",
+                    "items": {
+                      "$ref": "#/components/schemas/SwappableConfig"
+                    },
+                    "description": "Optional, opt-in configuration items to additionally swap on top of the always-swapped pages and functional config. Defaults to an empty list (nothing extra swapped). Domain and access/security settings can never be swapped."
+                  }
+                }
+              }
             }
           }
-        ],
+        },
         "responses": {
           "200": {
-            "description": "Partner revoked from portal successfully",
+            "description": "Domain and users swapped successfully.",
             "content": {
               "application/json": {
                 "schema": {
@@ -11021,7 +11168,7 @@
                   "properties": {
                     "message": {
                       "type": "string",
-                      "example": "Partner revoked from portal successfully"
+                      "example": "Domain and users swapped successfully."
                     }
                   }
                 }
@@ -11046,43 +11193,49 @@
         }
       }
     },
-    "/v3/portal/partner/{partner_id}/disable": {
+    "/v3/portal/config/clone": {
       "post": {
-        "operationId": "disablePartner",
-        "summary": "disablePartner",
-        "description": "Disables a partner from a portal",
+        "operationId": "clonePortalConfig",
+        "summary": "clonePortalConfig",
+        "description": "Creates a new portal by cloning configuration and pages from an existing portal. The new portal gets its own domain, users, email templates, and authentication settings.",
         "tags": [
-          "ECP"
+          "ECP Admin"
         ],
         "security": [
           {
-            "PortalAuth": []
+            "EpilotAuth": []
           }
         ],
-        "parameters": [
-          {
-            "name": "partner_id",
-            "in": "path",
-            "required": true,
-            "schema": {
-              "type": "string",
-              "description": "ID of the partner to disable from the portal"
+        "requestBody": {
+          "description": "Source portal ID and optional name for the cloned portal",
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": [
+                  "source_portal_id"
+                ],
+                "properties": {
+                  "source_portal_id": {
+                    "$ref": "#/components/schemas/PortalId"
+                  },
+                  "name": {
+                    "type": "string",
+                    "description": "Name for the cloned portal. Defaults to \"Copy of <source portal name>\"."
+                  }
+                }
+              }
             }
           }
-        ],
+        },
         "responses": {
-          "200": {
-            "description": "Partner disabled from portal successfully",
+          "201": {
+            "description": "Portal cloned successfully.",
             "content": {
               "application/json": {
                 "schema": {
-                  "type": "object",
-                  "properties": {
-                    "message": {
-                      "type": "string",
-                      "example": "Partner disabled from portal successfully"
-                    }
-                  }
+                  "$ref": "#/components/schemas/PortalConfigV3"
                 }
               }
             }
@@ -11105,11 +11258,11 @@
         }
       }
     },
-    "/v3/portal/partner/{partner_id}/enable": {
+    "/v3/portal/partner/invite": {
       "post": {
-        "operationId": "enablePartner",
-        "summary": "enablePartner",
-        "description": "Enables a partner from a portal",
+        "operationId": "invitePartner",
+        "summary": "invitePartner",
+        "description": "Invites a partner to a portal",
         "tags": [
           "ECP"
         ],
@@ -11118,20 +11271,63 @@
             "PortalAuth": []
           }
         ],
-        "parameters": [
-          {
-            "name": "partner_id",
-            "in": "path",
-            "required": true,
-            "schema": {
-              "type": "string",
-              "description": "ID of the partner to enable from the portal"
+        "requestBody": {
+          "description": "Partner to invite",
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": [
+                  "email"
+                ],
+                "properties": {
+                  "email": {
+                    "type": "string",
+                    "description": "Email address of the partner to invite"
+                  },
+                  "contact_data": {
+                    "type": "object",
+                    "description": "Additional contact entity fields to set when creating the contact for the invited user.\nThese are mapped directly to contact entity attributes (e.g. first_name, last_name, phone).\nValues can be strings or arrays of strings (for multiselect attributes).\n",
+                    "additionalProperties": {
+                      "oneOf": [
+                        {
+                          "type": "string"
+                        },
+                        {
+                          "type": "array",
+                          "items": {
+                            "type": "string"
+                          }
+                        }
+                      ]
+                    }
+                  },
+                  "portal_user_data": {
+                    "type": "object",
+                    "description": "Additional portal user entity fields to set when creating the portal user for the invited user.\nThese are mapped directly to portal_user entity attributes.\nValues can be strings or arrays of strings (for multiselect attributes).\n",
+                    "additionalProperties": {
+                      "oneOf": [
+                        {
+                          "type": "string"
+                        },
+                        {
+                          "type": "array",
+                          "items": {
+                            "type": "string"
+                          }
+                        }
+                      ]
+                    }
+                  }
+                }
+              }
             }
           }
-        ],
+        },
         "responses": {
           "200": {
-            "description": "Partner enabled from portal successfully",
+            "description": "User invited successfully",
             "content": {
               "application/json": {
                 "schema": {
@@ -11139,7 +11335,7 @@
                   "properties": {
                     "message": {
                       "type": "string",
-                      "example": "Partner enabled from portal successfully"
+                      "example": "User invited successfully"
                     }
                   }
                 }
@@ -11164,49 +11360,32 @@
         }
       }
     },
-    "/v3/portal/verify-dns": {
-      "post": {
-        "operationId": "verifyDns",
-        "summary": "verifyDns",
-        "description": "Manually triggers DNS verification for a portal's domain setup. Runs the same verification logic as the scheduled processAllPendingNetworks lambda.",
+    "/v3/portal/partner/list": {
+      "get": {
+        "operationId": "listBusinessPartners",
+        "summary": "listBusinessPartners",
+        "description": "Lists all business partners linked to the businessaccount",
         "tags": [
-          "ECP Admin"
+          "ECP"
         ],
         "security": [
           {
-            "EpilotAuth": []
-          }
-        ],
-        "parameters": [
-          {
-            "in": "query",
-            "name": "portal_id",
-            "required": true,
-            "schema": {
-              "$ref": "#/components/schemas/PortalId"
-            },
-            "description": "PortalId of the portal"
+            "PortalAuth": []
           }
         ],
         "responses": {
           "200": {
-            "description": "DNS verification result",
+            "description": "Business partners listed successfully",
             "content": {
               "application/json": {
                 "schema": {
                   "type": "object",
                   "properties": {
-                    "domain_status": {
-                      "type": "string",
-                      "description": "The status of the custom domain verification",
-                      "enum": [
-                        "PENDING",
-                        "SUCCEED"
-                      ]
-                    },
-                    "message": {
-                      "type": "string",
-                      "description": "A message describing the result"
+                    "data": {
+                      "type": "array",
+                      "items": {
+                        "$ref": "#/components/schemas/BusinessPartnerItem"
+                      }
                     }
                   }
                 }
@@ -11225,67 +11404,41 @@
         }
       }
     },
-    "/v2/portal/proxy/execute": {
+    "/v3/portal/partner/{partner_id}/resend-invitation": {
       "post": {
-        "operationId": "portalProxyExecute",
-        "summary": "portalProxyExecute",
-        "description": "Execute an Integration Hub managed-call use case on behalf of a portal user.\nBridges PortalAuth to the Integration API by generating an internal token.\n",
+        "operationId": "resendPartnerInvitation",
+        "summary": "resendPartnerInvitation",
+        "description": "Resends an invitation email to a partner",
+        "tags": [
+          "ECP"
+        ],
         "security": [
           {
             "PortalAuth": []
           }
         ],
-        "tags": [
-          "ECP"
+        "parameters": [
+          {
+            "name": "partner_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "description": "ID of the partner to resend invitation to"
+            }
+          }
         ],
-        "requestBody": {
-          "required": true,
-          "content": {
-            "application/json": {
-              "schema": {
-                "type": "object",
-                "required": [
-                  "integration_id",
-                  "use_case_slug"
-                ],
-                "properties": {
-                  "integration_id": {
-                    "type": "string",
-                    "format": "uuid",
-                    "description": "Integration ID containing the managed-call use case"
-                  },
-                  "use_case_slug": {
-                    "type": "string",
-                    "description": "Use case slug (acts as the RPC method name)"
-                  },
-                  "payload": {
-                    "type": "object",
-                    "description": "Input data for the managed-call operation",
-                    "additionalProperties": true
-                  }
-                }
-              }
-            }
-          }
-        },
         "responses": {
           "200": {
-            "description": "Managed-call execution result envelope.",
+            "description": "Partner invitation resent successfully",
             "content": {
               "application/json": {
                 "schema": {
                   "type": "object",
-                  "required": [
-                    "success"
-                  ],
                   "properties": {
-                    "success": {
-                      "type": "boolean"
-                    },
-                    "data": {
-                      "type": "object",
-                      "additionalProperties": true,
-                      "description": "Managed-call response payload. Shape is defined by the use\ncase's JSONata response_mapping; if no mapping is\nconfigured the raw external API response is returned.\n"
+                    "message": {
+                      "type": "string",
+                      "example": "Partner invitation resent successfully"
                     }
                   }
                 }
@@ -11301,56 +11454,59 @@
           "403": {
             "$ref": "#/components/responses/Forbidden"
           },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          },
           "500": {
             "$ref": "#/components/responses/InternalServerError"
           }
         }
       }
     },
-    "/v1/portal/mobile-config": {
-      "get": {
-        "operationId": "getMobileConfig",
-        "summary": "getMobileConfig",
-        "description": "Returns the portal's mobile app configuration. By default the response is build-ready (resolved): base info (display_name from the portal name, app_host from the domain, environment) and branding (logo from the portal images, colors from the design palette) are filled in. Pass raw=true to get only the stored mobile_config without resolution.",
+    "/v3/portal/partner/{partner_id}/revoke": {
+      "delete": {
+        "operationId": "revokePartner",
+        "summary": "revokePartner",
+        "description": "Revokes a partner from a portal",
         "tags": [
-          "ECP Admin"
+          "ECP"
         ],
         "security": [
           {
-            "EpilotAuth": []
+            "PortalAuth": []
           }
         ],
         "parameters": [
           {
-            "in": "query",
-            "name": "portal_id",
+            "name": "partner_id",
+            "in": "path",
             "required": true,
             "schema": {
-              "type": "string"
-            },
-            "description": "Portal ID"
-          },
-          {
-            "in": "query",
-            "name": "raw",
-            "required": false,
-            "schema": {
-              "type": "boolean"
-            },
-            "description": "Return only the stored mobile_config without resolving base info/branding."
+              "type": "string",
+              "description": "ID of the partner to revoke from the portal"
+            }
           }
         ],
         "responses": {
           "200": {
-            "description": "Mobile config retrieved successfully.",
+            "description": "Partner revoked from portal successfully",
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/MobileConfig"
+                  "type": "object",
+                  "properties": {
+                    "message": {
+                      "type": "string",
+                      "example": "Partner revoked from portal successfully"
+                    }
+                  }
                 }
               }
             }
           },
+          "400": {
+            "$ref": "#/components/responses/InvalidRequest"
+          },
           "401": {
             "$ref": "#/components/responses/Unauthorized"
           },
@@ -11364,48 +11520,45 @@
             "$ref": "#/components/responses/InternalServerError"
           }
         }
-      },
-      "put": {
-        "operationId": "putMobileConfig",
-        "summary": "putMobileConfig",
-        "description": "Merges the provided fields into the portal's mobile app configuration\n(deep merge). Only mobile_config is modified; all other portal settings\nare left untouched.\n",
+      }
+    },
+    "/v3/portal/partner/{partner_id}/disable": {
+      "post": {
+        "operationId": "disablePartner",
+        "summary": "disablePartner",
+        "description": "Disables a partner from a portal",
         "tags": [
-          "ECP Admin"
+          "ECP"
         ],
         "security": [
           {
-            "EpilotAuth": []
+            "PortalAuth": []
           }
         ],
         "parameters": [
           {
-            "in": "query",
-            "name": "portal_id",
+            "name": "partner_id",
+            "in": "path",
             "required": true,
             "schema": {
-              "type": "string"
-            },
-            "description": "Portal ID"
-          }
-        ],
-        "requestBody": {
-          "description": "Editable mobile fields to merge into the existing mobile_config. Only mobile-relevant settings + app branding are applied; other fields are ignored.",
-          "required": true,
-          "content": {
-            "application/json": {
-              "schema": {
-                "$ref": "#/components/schemas/MobileConfigUpdate"
-              }
+              "type": "string",
+              "description": "ID of the partner to disable from the portal"
             }
           }
-        },
+        ],
         "responses": {
           "200": {
-            "description": "Mobile config updated successfully.",
+            "description": "Partner disabled from portal successfully",
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/MobileConfig"
+                  "type": "object",
+                  "properties": {
+                    "message": {
+                      "type": "string",
+                      "example": "Partner disabled from portal successfully"
+                    }
+                  }
                 }
               }
             }
@@ -11427,97 +11580,420 @@
           }
         }
       }
-    }
-  },
-  "components": {
-    "responses": {
-      "InvalidRequest": {
-        "description": "The request could not be validated",
-        "content": {
-          "application/json": {
-            "schema": {
-              "$ref": "#/components/schemas/ErrorResp"
-            }
-          }
-        }
-      },
-      "Unauthorized": {
-        "description": "Could not authenticate the user",
-        "content": {
-          "application/json": {
-            "schema": {
-              "$ref": "#/components/schemas/ErrorResp"
-            }
-          }
-        }
-      },
-      "Forbidden": {
-        "description": "The user is not allowed to access this resource",
-        "content": {
-          "application/json": {
-            "schema": {
-              "$ref": "#/components/schemas/ErrorResp"
-            }
-          }
-        }
-      },
-      "ForbiddenByRule": {
-        "description": "The user is not allowed to access this resource",
-        "content": {
-          "application/json": {
-            "schema": {
-              "oneOf": [
-                {
-                  "$ref": "#/components/schemas/ErrorResp"
-                },
-                {
-                  "$ref": "#/components/schemas/FailedRuleErrorResp"
-                }
-              ]
-            }
+    },
+    "/v3/portal/partner/{partner_id}/enable": {
+      "post": {
+        "operationId": "enablePartner",
+        "summary": "enablePartner",
+        "description": "Enables a partner from a portal",
+        "tags": [
+          "ECP"
+        ],
+        "security": [
+          {
+            "PortalAuth": []
           }
-        }
-      },
-      "Conflict": {
-        "description": "The request conflicts with the current state of the target resource.",
-        "content": {
-          "application/json": {
+        ],
+        "parameters": [
+          {
+            "name": "partner_id",
+            "in": "path",
+            "required": true,
             "schema": {
-              "$ref": "#/components/schemas/ErrorResp"
+              "type": "string",
+              "description": "ID of the partner to enable from the portal"
             }
           }
-        }
-      },
-      "ContractAssignmentConflict": {
-        "description": "Contract was found but is not assignable in its current state.",
-        "content": {
-          "application/json": {
-            "schema": {
-              "allOf": [
-                {
-                  "$ref": "#/components/schemas/ErrorResp"
-                },
-                {
+        ],
+        "responses": {
+          "200": {
+            "description": "Partner enabled from portal successfully",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
                   "properties": {
-                    "reason": {
+                    "message": {
                       "type": "string",
-                      "description": "Reason why the contract is not assignable. If the reason is \"MULTIPLE\", the contract is not assignable because multiple contracts were found and the business logic does not allow it.",
-                      "enum": [
-                        "DRAFT",
-                        "MULTIPLE"
-                      ]
+                      "example": "Partner enabled from portal successfully"
                     }
-                  },
-                  "required": [
-                    "reason"
-                  ]
+                  }
                 }
-              ]
+              }
             }
+          },
+          "400": {
+            "$ref": "#/components/responses/InvalidRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          },
+          "500": {
+            "$ref": "#/components/responses/InternalServerError"
           }
         }
-      },
-      "NotFound": {
+      }
+    },
+    "/v3/portal/verify-dns": {
+      "post": {
+        "operationId": "verifyDns",
+        "summary": "verifyDns",
+        "description": "Manually triggers DNS verification for a portal's domain setup. Runs the same verification logic as the scheduled processAllPendingNetworks lambda.",
+        "tags": [
+          "ECP Admin"
+        ],
+        "security": [
+          {
+            "EpilotAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "in": "query",
+            "name": "portal_id",
+            "required": true,
+            "schema": {
+              "$ref": "#/components/schemas/PortalId"
+            },
+            "description": "PortalId of the portal"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "DNS verification result",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "domain_status": {
+                      "type": "string",
+                      "description": "The status of the custom domain verification",
+                      "enum": [
+                        "PENDING",
+                        "SUCCEED"
+                      ]
+                    },
+                    "message": {
+                      "type": "string",
+                      "description": "A message describing the result"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "500": {
+            "$ref": "#/components/responses/InternalServerError"
+          }
+        }
+      }
+    },
+    "/v2/portal/proxy/execute": {
+      "post": {
+        "operationId": "portalProxyExecute",
+        "summary": "portalProxyExecute",
+        "description": "Execute an Integration Hub managed-call use case on behalf of a portal user.\nBridges PortalAuth to the Integration API by generating an internal token.\n",
+        "security": [
+          {
+            "PortalAuth": []
+          }
+        ],
+        "tags": [
+          "ECP"
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": [
+                  "integration_id",
+                  "use_case_slug"
+                ],
+                "properties": {
+                  "integration_id": {
+                    "type": "string",
+                    "format": "uuid",
+                    "description": "Integration ID containing the managed-call use case"
+                  },
+                  "use_case_slug": {
+                    "type": "string",
+                    "description": "Use case slug (acts as the RPC method name)"
+                  },
+                  "payload": {
+                    "type": "object",
+                    "description": "Input data for the managed-call operation",
+                    "additionalProperties": true
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Managed-call execution result envelope.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "required": [
+                    "success"
+                  ],
+                  "properties": {
+                    "success": {
+                      "type": "boolean"
+                    },
+                    "data": {
+                      "type": "object",
+                      "additionalProperties": true,
+                      "description": "Managed-call response payload. Shape is defined by the use\ncase's JSONata response_mapping; if no mapping is\nconfigured the raw external API response is returned.\n"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/InvalidRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "500": {
+            "$ref": "#/components/responses/InternalServerError"
+          }
+        }
+      }
+    },
+    "/v1/portal/mobile-config": {
+      "get": {
+        "operationId": "getMobileConfig",
+        "summary": "getMobileConfig",
+        "description": "Returns the portal's mobile app configuration. By default the response is build-ready (resolved): base info (display_name from the portal name, app_host from the domain, environment) and branding (logo from the portal images, colors from the design palette) are filled in. Pass raw=true to get only the stored mobile_config without resolution.",
+        "tags": [
+          "ECP Admin"
+        ],
+        "security": [
+          {
+            "EpilotAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "in": "query",
+            "name": "portal_id",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Portal ID"
+          },
+          {
+            "in": "query",
+            "name": "raw",
+            "required": false,
+            "schema": {
+              "type": "boolean"
+            },
+            "description": "Return only the stored mobile_config without resolving base info/branding."
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Mobile config retrieved successfully.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/MobileConfig"
+                }
+              }
+            }
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          },
+          "500": {
+            "$ref": "#/components/responses/InternalServerError"
+          }
+        }
+      },
+      "put": {
+        "operationId": "putMobileConfig",
+        "summary": "putMobileConfig",
+        "description": "Merges the provided fields into the portal's mobile app configuration\n(deep merge). Only mobile_config is modified; all other portal settings\nare left untouched.\n",
+        "tags": [
+          "ECP Admin"
+        ],
+        "security": [
+          {
+            "EpilotAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "in": "query",
+            "name": "portal_id",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Portal ID"
+          }
+        ],
+        "requestBody": {
+          "description": "Editable mobile fields to merge into the existing mobile_config. Only mobile-relevant settings + app branding are applied; other fields are ignored.",
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/MobileConfigUpdate"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Mobile config updated successfully.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/MobileConfig"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/InvalidRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          },
+          "500": {
+            "$ref": "#/components/responses/InternalServerError"
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "responses": {
+      "InvalidRequest": {
+        "description": "The request could not be validated",
+        "content": {
+          "application/json": {
+            "schema": {
+              "$ref": "#/components/schemas/ErrorResp"
+            }
+          }
+        }
+      },
+      "Unauthorized": {
+        "description": "Could not authenticate the user",
+        "content": {
+          "application/json": {
+            "schema": {
+              "$ref": "#/components/schemas/ErrorResp"
+            }
+          }
+        }
+      },
+      "Forbidden": {
+        "description": "The user is not allowed to access this resource",
+        "content": {
+          "application/json": {
+            "schema": {
+              "$ref": "#/components/schemas/ErrorResp"
+            }
+          }
+        }
+      },
+      "ForbiddenByRule": {
+        "description": "The user is not allowed to access this resource",
+        "content": {
+          "application/json": {
+            "schema": {
+              "oneOf": [
+                {
+                  "$ref": "#/components/schemas/ErrorResp"
+                },
+                {
+                  "$ref": "#/components/schemas/FailedRuleErrorResp"
+                }
+              ]
+            }
+          }
+        }
+      },
+      "Conflict": {
+        "description": "The request conflicts with the current state of the target resource.",
+        "content": {
+          "application/json": {
+            "schema": {
+              "$ref": "#/components/schemas/ErrorResp"
+            }
+          }
+        }
+      },
+      "ContractAssignmentConflict": {
+        "description": "Contract was found but is not assignable in its current state.",
+        "content": {
+          "application/json": {
+            "schema": {
+              "allOf": [
+                {
+                  "$ref": "#/components/schemas/ErrorResp"
+                },
+                {
+                  "properties": {
+                    "reason": {
+                      "type": "string",
+                      "description": "Reason why the contract is not assignable. If the reason is \"MULTIPLE\", the contract is not assignable because multiple contracts were found and the business logic does not allow it.",
+                      "enum": [
+                        "DRAFT",
+                        "MULTIPLE"
+                      ]
+                    }
+                  },
+                  "required": [
+                    "reason"
+                  ]
+                }
+              ]
+            }
+          }
+        }
+      },
+      "NotFound": {
         "description": "The specified resource was not found",
         "content": {
           "application/json": {
@@ -11537,6 +12013,46 @@
           }
         }
       },
+      "TooManyRequests": {
+        "description": "The upstream service rate-limited the request",
+        "content": {
+          "application/json": {
+            "schema": {
+              "$ref": "#/components/schemas/ErrorResp"
+            }
+          }
+        }
+      },
+      "BadGateway": {
+        "description": "The upstream service failed to process the request",
+        "content": {
+          "application/json": {
+            "schema": {
+              "$ref": "#/components/schemas/ErrorResp"
+            }
+          }
+        }
+      },
+      "ServiceUnavailable": {
+        "description": "The requested feature is not configured",
+        "content": {
+          "application/json": {
+            "schema": {
+              "$ref": "#/components/schemas/ErrorResp"
+            }
+          }
+        }
+      },
+      "GatewayTimeout": {
+        "description": "The upstream service timed out",
+        "content": {
+          "application/json": {
+            "schema": {
+              "$ref": "#/components/schemas/ErrorResp"
+            }
+          }
+        }
+      },
       "ConfirmUserInvalidRequest": {
         "description": "The request could not be validated",
         "content": {
@@ -12571,6 +13087,17 @@
               "new_design": {
                 "type": "boolean",
                 "description": "Enable or disable the new design for the portal"
+              },
+              "mcp_enabled": {
+                "type": "boolean",
+                "description": "Enable the MCP (AI agent) connector channel for this portal"
+              },
+              "mcp_grant_version": {
+                "type": "integer",
+                "minimum": 0,
+                "default": 0,
+                "readOnly": true,
+                "description": "Server-managed generation used to invalidate MCP grants after the connector is disabled or re-enabled"
               }
             }
           },
@@ -12866,6 +13393,13 @@
               }
             ]
           },
+          "surfaces": {
+            "type": "array",
+            "description": "Surfaces this portal's data is reached from besides the portal UI itself (public journeys on the website, chat). Configured under Security > Surfaces. Each surface defines how a caller authenticates and what data access applies on it; the portal UI is the implicit default surface (login, default scope) and is not listed here. A surface with `authentication: registration_identifiers` is what makes `identifyContact` issue tokens for this portal: without one, `identifyContact` returns 403.\n",
+            "items": {
+              "$ref": "#/components/schemas/PortalSurface"
+            }
+          },
           "contact_identifiers_for_account": {
             "type": "array",
             "description": "Account-mode only. Identifiers on the contact entity of the primarily\nidentified account. Used to pick an existing related contact within the\nresolved account; if none matches, the values are written onto the new\ncontact that is created and linked to the account.\n",
@@ -13015,6 +13549,12 @@
             "type": "boolean",
             "description": "Whether this is a v3 portal configuration"
           },
+          "published_revision_id": {
+            "type": "string",
+            "readOnly": true,
+            "description": "The revision currently live on this portal. Absent until the first publish.",
+            "example": "2026-08-25T14:03:11.482Z-a7f3c1d9"
+          },
           "portal_id": {
             "$ref": "#/components/schemas/PortalId"
           },
@@ -13563,6 +14103,79 @@
           }
         }
       },
+      "ContactIdentifyRequest": {
+        "description": "ContactExistsRequest plus the surface the token is requested for.\n",
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/ContactExistsRequest"
+          },
+          {
+            "type": "object",
+            "required": [
+              "surface_id"
+            ],
+            "properties": {
+              "surface_id": {
+                "type": "string",
+                "description": "Id of the portal surface (see `surfaces` on the portal config) this token is\nfor. The surface must exist and use `authentication: registration_identifiers`;\notherwise the call returns 403. The issued token is bound to this surface and\nconfined to its data access settings.\n",
+                "example": "website-journeys"
+              }
+            }
+          }
+        ]
+      },
+      "ContactIdentifyResponse": {
+        "type": "object",
+        "properties": {
+          "contact_id": {
+            "$ref": "#/components/schemas/EntityId",
+            "description": "ID of the identified contact. Present only on a match."
+          },
+          "account_id": {
+            "$ref": "#/components/schemas/EntityId",
+            "description": "ID of the resolved account when the portal is configured for account-based\nregistration. Present only on a match.\n"
+          },
+          "token": {
+            "type": "string",
+            "description": "One-time bearer token scoped to the identified contact, to be sent as\n`Authorization: Bearer <token>` against the portal APIs. Present only on a match.\n",
+            "example": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
+          },
+          "token_type": {
+            "type": "string",
+            "enum": [
+              "contact_identification"
+            ],
+            "description": "Type of the issued token, matching its own `token_type` claim and the token type in access-token-api. Present only on a match."
+          },
+          "surface_id": {
+            "type": "string",
+            "description": "The surface the token is bound to; echoes the request. Present only on a match.",
+            "example": "website-journeys"
+          },
+          "expires_at": {
+            "type": "string",
+            "format": "date-time",
+            "description": "When the issued token stops being accepted. Present only on a match.",
+            "example": "2026-08-11T10:35:00.000Z"
+          },
+          "allowed_operations": {
+            "type": "array",
+            "description": "The operationIds the issued token may call. Every other operation rejects the token\nwith 401, including read operations. Echoed so a caller does not have to infer the\nsurface from this specification, and so a change to the allowlist is visible at\nruntime. Present only on a match.\n",
+            "items": {
+              "type": "string"
+            },
+            "example": []
+          },
+          "reason": {
+            "type": "string",
+            "enum": [
+              "TIMEOUT",
+              "NOT_FOUND"
+            ],
+            "description": "Present only when no token was issued. NOT_FOUND means the given identifiers did not\nmatch any contact (definitive - the client should not retry). TIMEOUT means the contact\nwas not found within the processing window but may still be ingesting; the client may\nretry (ideally with trigger_identifiers_check=false).\n"
+          }
+        }
+      },
       "AccountExistsRequest": {
         "type": "object",
         "required": [
@@ -15048,6 +15661,94 @@
           }
         }
       },
+      "PortalSurface": {
+        "type": "object",
+        "description": "One surface a portal's data is reached from (see `surfaces` on the portal config).\n\nA surface names how callers authenticate on it and what they may reach once they\nhave. Data access is always a subset of the portal's own: a schema not in\n`allowed_portal_entities` cannot be opened up by a surface, and the portal's\ncontact-relation rules still apply underneath the surface's own.\n\nTokens minted for a surface (currently: contact identification tokens for\n`registration_identifiers` surfaces) carry the surface id. The surface's data\naccess is resolved from the portal config on every request, not baked into the\ntoken, so tightening a surface applies to tokens already in circulation.\n",
+        "required": [
+          "id",
+          "name",
+          "authentication"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 64,
+            "pattern": "^[a-z0-9][a-z0-9_-]*$",
+            "description": "Stable identifier, unique within the portal. Referenced by `identifyContact` and carried in issued tokens.",
+            "example": "website-journeys"
+          },
+          "name": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 120,
+            "example": "Website journeys"
+          },
+          "description": {
+            "type": "string",
+            "maxLength": 500,
+            "description": "Free text for the configuring user, e.g. where this surface is embedded."
+          },
+          "authentication": {
+            "type": "string",
+            "enum": [
+              "login",
+              "registration_identifiers"
+            ],
+            "description": "How a caller on this surface proves who they are.\n\n- `login`: a logged-in portal user token (the portal's own authentication).\n- `registration_identifiers`: the caller supplies the portal's\n  `registration_identifiers` to `identifyContact` and receives a short-lived\n  contact identification token. Anyone who knows or guesses those values can\n  use this surface, so its data access should be as narrow as the use case allows.\n\n`anonymous` (no proof of identity at all) is planned and not accepted yet.\n"
+          },
+          "token_ttl_seconds": {
+            "type": "integer",
+            "format": "int32",
+            "default": 300,
+            "minimum": 60,
+            "maximum": 900,
+            "description": "Lifetime of tokens minted for this surface. Only used with `registration_identifiers`."
+          },
+          "data_access": {
+            "$ref": "#/components/schemas/PortalSurfaceDataAccess"
+          }
+        }
+      },
+      "PortalSurfaceDataAccess": {
+        "type": "object",
+        "description": "What a caller on a surface may reach. Every property is optional; omitting all of them is the portal's default scope.",
+        "properties": {
+          "entities": {
+            "type": "array",
+            "description": "Schemas reachable on this surface, each with the targets that always apply to\nit. Must be a subset of the portal's `allowed_portal_entities`; anything else\nis ignored. Empty or omitted means the surface reaches nothing - data access is\nopted into per schema.\n",
+            "items": {
+              "$ref": "#/components/schemas/PortalSurfaceEntityAccess"
+            }
+          },
+          "role_id": {
+            "type": "string",
+            "description": "360 role whose grants apply on this surface (`<org_id>:<slug>`), giving\nvertical permissions - which attributes and actions are permitted. Omitted\nmeans the portal's default role.\n",
+            "example": "728:public_journeys_readonly"
+          }
+        }
+      },
+      "PortalSurfaceEntityAccess": {
+        "type": "object",
+        "description": "One schema this surface reaches, with the targets that always apply to it.",
+        "properties": {
+          "schema": {
+            "type": "string",
+            "description": "Schema slug, from the portal's `allowed_portal_entities`.",
+            "example": "contract"
+          },
+          "target_ids": {
+            "type": "array",
+            "description": "Targets (see the Targeting API) whose filters always apply to reads of this\nschema on this surface, giving horizontal permissions - which rows are\nreachable. They are applied in addition to any targets the caller passes. A\ntarget matches one schema, which is why they are configured per schema here.\n",
+            "items": {
+              "type": "string"
+            }
+          }
+        },
+        "required": [
+          "schema"
+        ]
+      },
       "Grant": {
         "type": "object",
         "properties": {
@@ -15414,15 +16115,58 @@
             "items": {
               "$ref": "#/components/schemas/PortalWorkflowTask"
             }
+          },
+          "stages": {
+            "type": "array",
+            "description": "Customer-facing stages of the execution in strict order, each with a\nprogress status derived by the Workflows API. Present only for V2 flow\nexecutions whose template defines stages and whose boundaries resolve\ncleanly; omitted otherwise, so consumers must fall back to the flat\ntask timeline.\n",
+            "items": {
+              "$ref": "#/components/schemas/PortalWorkflowStage"
+            }
+          }
+        },
+        "required": [
+          "id",
+          "name",
+          "status",
+          "version",
+          "is_path_complete",
+          "tasks"
+        ]
+      },
+      "PortalWorkflowStage": {
+        "type": "object",
+        "description": "A customer-facing stage of a flow execution, with a progress status derived\nfrom the execution's tasks by the Workflows API. Stages form a strict total\norder; the array order is the stage order.\n",
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "Stable unique identifier for the stage"
+          },
+          "name": {
+            "type": "string",
+            "description": "User-facing stage title"
+          },
+          "description": {
+            "type": "string",
+            "description": "Customer-facing description of what happens in this stage"
+          },
+          "status": {
+            "type": "string",
+            "enum": [
+              "COMPLETED",
+              "IN_PROGRESS",
+              "UPCOMING"
+            ],
+            "description": "Derived progress status:\n- COMPLETED: every task of the stage is done, and the flow has moved past it\n- IN_PROGRESS: the flow's current work is inside this stage\n- UPCOMING: the flow has not reached this stage yet\n"
+          },
+          "completed_at": {
+            "type": "string",
+            "description": "Latest completion timestamp among the stage's tasks; set only when the\nstage is COMPLETED and at least one of its tasks recorded one\n"
           }
         },
         "required": [
           "id",
           "name",
-          "status",
-          "version",
-          "is_path_complete",
-          "tasks"
+          "status"
         ]
       },
       "PortalWorkflowTask": {
@@ -15494,6 +16238,10 @@
             "type": "string",
             "description": "Name of the phase the underlying task belongs to, if any (V2 only)"
           },
+          "stage_id": {
+            "type": "string",
+            "description": "Id of the stage the underlying task belongs to, when the execution\ncarries stages (derived by the Workflows API at read time)\n"
+          },
           "completed_at": {
             "type": "string",
             "description": "Timestamp when the task was completed or skipped"
@@ -15959,7 +16707,7 @@
           },
           "q": {
             "type": "string",
-            "description": "Keyword search query",
+            "description": "Free-text keyword search. This is plain text, **not** a query language: punctuation separates words rather than carrying any special meaning, and every word has to match. Use `q_fields` to restrict which fields are searched, and `filters`/`targets` for structured filtering. Overly long input is trimmed, and input with no words in it is ignored — the remaining parameters still apply.",
             "example": "contract"
           },
           "q_fields": {
@@ -16597,7 +17345,7 @@
           },
           "intervals": {
             "type": "array",
-            "description": "Intervals supported for the current context. If omitted, all intervals are assumed supported.",
+            "description": "Intervals supported for the current context. If omitted, all intervals are assumed supported. `custom` marks a period-based consumption source: the portal requests the whole `data_range` once with `interval=custom` and renders one bar per returned record (see `period` on the consumption data point) instead of offering interval / date navigation or period comparison. When `custom` is present it takes precedence over any fixed intervals also listed.\n",
             "items": {
               "type": "string",
               "enum": [
@@ -16605,7 +17353,8 @@
                 "PT1H",
                 "P1D",
                 "P1M",
-                "P1Y"
+                "P1Y",
+                "custom"
               ]
             }
           },
@@ -18426,6 +19175,41 @@
           "display_name"
         ]
       },
+      "ProviderPublicConfigV3": {
+        "type": "object",
+        "description": "Web-only public provider configuration served by `getPublicSSOProviderV3`.\nUnlike `ProviderPublicConfig` there is no `mobile_oidc_config`, and\n`oidc_config` never carries `client_secret` or the `metadata.test_auth_*`\ncredentials — `oidc_config.has_client_secret` signals their presence so\nclients route the token exchange through the backend SSO callback.\n",
+        "properties": {
+          "slug": {
+            "$ref": "#/components/schemas/ProviderSlug"
+          },
+          "display_name": {
+            "$ref": "#/components/schemas/ProviderDisplayName"
+          },
+          "oidc_config": {
+            "$ref": "#/components/schemas/OIDCProviderConfig"
+          }
+        },
+        "required": [
+          "slug",
+          "display_name"
+        ]
+      },
+      "PublicIdentityProvider": {
+        "type": "object",
+        "description": "Minimal public identity provider info — enough to render a provider login button.",
+        "properties": {
+          "slug": {
+            "$ref": "#/components/schemas/ProviderSlug"
+          },
+          "display_name": {
+            "$ref": "#/components/schemas/ProviderDisplayName"
+          }
+        },
+        "required": [
+          "slug",
+          "display_name"
+        ]
+      },
       "AttributeMappingConfig": {
         "type": "object",
         "description": "Dictionary of epilot user attributes to claims",
@@ -19219,6 +20003,17 @@
               "new_design": {
                 "type": "boolean",
                 "description": "Enable or disable the new design for the portal"
+              },
+              "mcp_enabled": {
+                "type": "boolean",
+                "description": "Enable the MCP (AI agent) connector channel for this portal"
+              },
+              "mcp_grant_version": {
+                "type": "integer",
+                "minimum": 0,
+                "default": 0,
+                "readOnly": true,
+                "description": "Server-managed generation used to invalidate MCP grants after the connector is disabled or re-enabled"
               }
             }
           },
@@ -19514,6 +20309,13 @@
               }
             ]
           },
+          "surfaces": {
+            "type": "array",
+            "description": "Surfaces this portal's data is reached from besides the portal UI itself (public journeys on the website, chat). Configured under Security > Surfaces. Each surface defines how a caller authenticates and what data access applies on it; the portal UI is the implicit default surface (login, default scope) and is not listed here. A surface with `authentication: registration_identifiers` is what makes `identifyContact` issue tokens for this portal: without one, `identifyContact` returns 403.\n",
+            "items": {
+              "$ref": "#/components/schemas/PortalSurface"
+            }
+          },
           "contact_identifiers_for_account": {
             "type": "array",
             "description": "Account-mode only. Identifiers on the contact entity of the primarily\nidentified account. Used to pick an existing related contact within the\nresolved account; if none matches, the values are written onto the new\ncontact that is created and linked to the account.\n",
@@ -19663,6 +20465,12 @@
             "type": "boolean",
             "description": "Whether this is a v3 portal configuration"
           },
+          "published_revision_id": {
+            "type": "string",
+            "readOnly": true,
+            "description": "The revision currently live on this portal. Absent until the first publish.",
+            "example": "2026-08-25T14:03:11.482Z-a7f3c1d9"
+          },
           "portal_id": {
             "$ref": "#/components/schemas/PortalId"
           },
@@ -19750,137 +20558,414 @@
               }
             }
           },
-          "formatter": {
+          "formatter": {
+            "type": "string",
+            "enum": [
+              "text",
+              "date",
+              "money_cents",
+              "enum",
+              "address"
+            ]
+          },
+          "enum_labels": {
+            "type": "object",
+            "description": "Localized value maps for the enum formatter, keyed by language then raw value.\n",
+            "additionalProperties": {
+              "type": "object",
+              "additionalProperties": {
+                "type": "string"
+              }
+            }
+          }
+        }
+      },
+      "UpsertPortalConfigV3": {
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/UpdateOnlyPortalConfigAttributes"
+          },
+          {
+            "$ref": "#/components/schemas/CommonConfigAttributesV3"
+          },
+          {
+            "properties": {
+              "origin": {
+                "$ref": "#/components/schemas/Origin"
+              },
+              "pages": {
+                "type": "array",
+                "items": {
+                  "$ref": "#/components/schemas/PageRequest"
+                }
+              }
+            }
+          }
+        ]
+      },
+      "PortalConfigV3": {
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/UpdateOnlyPortalConfigAttributes"
+          },
+          {
+            "$ref": "#/components/schemas/CommonConfigAttributesV3"
+          },
+          {
+            "properties": {
+              "organization_id": {
+                "type": "string",
+                "example": 12345,
+                "description": "ID of the organization"
+              },
+              "org_settings": {
+                "type": "object",
+                "description": "Organization settings",
+                "properties": {
+                  "canary": {
+                    "type": "object",
+                    "description": "Canary feature flag",
+                    "properties": {
+                      "enabled": {
+                        "type": "boolean",
+                        "description": "Enable/Disable the canary feature"
+                      }
+                    }
+                  },
+                  "notracking": {
+                    "type": "object",
+                    "description": "Disable Advanced Usage Metrics",
+                    "properties": {
+                      "enabled": {
+                        "type": "boolean",
+                        "description": "Disable browser-side scripts that track advanced usage metrics"
+                      }
+                    }
+                  }
+                }
+              },
+              "feature_flags": {
+                "type": "object",
+                "description": "Feature flags for the portal",
+                "additionalProperties": {
+                  "type": "boolean"
+                }
+              },
+              "grants": {
+                "type": "array",
+                "description": "Permissions granted to a portal user while accessing entities",
+                "items": {
+                  "$ref": "#/components/schemas/Grant"
+                }
+              },
+              "identity_providers": {
+                "type": "array",
+                "items": {
+                  "$ref": "#/components/schemas/ProviderPublicConfig"
+                }
+              },
+              "pages": {
+                "type": "array",
+                "items": {
+                  "$ref": "#/components/schemas/Page"
+                }
+              }
+            }
+          }
+        ]
+      },
+      "JuiceSettings": {
+        "type": "object",
+        "properties": {
+          "is_dummy": {
+            "type": "boolean",
+            "description": "Whether the org is in dummy mode"
+          },
+          "is_canary": {
+            "type": "boolean",
+            "description": "Whether the org is in canary mode"
+          },
+          "is_legacy_design": {
+            "type": "boolean",
+            "description": "Whether the portal still runs the old design (the `new_design` feature setting is off). Legacy portals are always served the frozen legacy bundle, even when the org is in canary."
+          },
+          "redirect_to": {
+            "type": "string",
+            "description": "The URL to redirect to",
+            "example": "https://example.com"
+          }
+        }
+      },
+      "RevisionPageRequest": {
+        "type": "object",
+        "additionalProperties": true,
+        "description": "A page inside a revision snapshot. `additionalProperties` is true on purpose — a page carries fields this schema does not name and they must survive into the snapshot and back onto the live page when it is published.\n",
+        "required": [
+          "id",
+          "slug",
+          "order",
+          "blocks"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "format": "uuid",
+            "description": "Stable page identity. Required because a revision diff correlates pages by id, not by slug.\n`format: uuid` is enforced, so a non-UUID id is rejected as a `400`.\n",
+            "example": "c495fef9-eeca-4019-a989-8390dcd9825b"
+          },
+          "slug": {
+            "type": "string",
+            "example": "dashboard"
+          },
+          "order": {
+            "type": "number",
+            "example": 0
+          },
+          "blocks": {
+            "type": "object",
+            "additionalProperties": true,
+            "description": "Required on purpose. A live save preserves an omitted `blocks` from the stored page; publish replaces each live page wholesale with no such guard, so a revision snapshotted without blocks would wipe them on publish. `{}` is a valid value — the field simply has to be present.\n"
+          }
+        }
+      },
+      "PortalRevisionRequest": {
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/UpdateOnlyPortalConfigAttributes"
+          },
+          {
+            "$ref": "#/components/schemas/CommonConfigAttributesV3"
+          },
+          {
+            "type": "object",
+            "additionalProperties": true,
+            "required": [
+              "pages"
+            ],
+            "properties": {
+              "email_templates": {
+                "$ref": "#/components/schemas/EmailTemplates"
+              },
+              "identity_providers": {
+                "type": "array",
+                "items": {
+                  "$ref": "#/components/schemas/ProviderConfig"
+                }
+              },
+              "based_on_revision_id": {
+                "type": "string"
+              },
+              "pages": {
+                "type": "array",
+                "items": {
+                  "$ref": "#/components/schemas/RevisionPageRequest"
+                }
+              }
+            }
+          }
+        ]
+      },
+      "PublishRevisionRequest": {
+        "type": "object",
+        "required": [
+          "revision_id"
+        ],
+        "properties": {
+          "revision_id": {
+            "type": "string",
+            "example": "2026-08-25T14:03:11.482Z-a7f3c1d9"
+          },
+          "name": {
             "type": "string",
-            "enum": [
-              "text",
-              "date",
-              "money_cents",
-              "enum",
-              "address"
-            ]
+            "maxLength": 255,
+            "description": "Label stamped onto the revision being published, permanently and atomically with the publish itself. Optional: when omitted the revision keeps whatever name it already has, possibly none; the server never generates one. An explicit name replaces any previous one. Clients derive a display label for unnamed revisions from `published_at` / `created_at`.\n",
+            "example": "FAQ page launch"
           },
-          "enum_labels": {
-            "type": "object",
-            "description": "Localized value maps for the enum formatter, keyed by language then raw value.\n",
-            "additionalProperties": {
-              "type": "object",
-              "additionalProperties": {
-                "type": "string"
-              }
+          "description": {
+            "type": "string",
+            "maxLength": 8000,
+            "description": "Optional description stamped onto the revision at publish time"
+          }
+        }
+      },
+      "PortalRevisionSummary": {
+        "type": "object",
+        "required": [
+          "revision_id",
+          "created_at",
+          "page_count",
+          "is_published"
+        ],
+        "properties": {
+          "revision_id": {
+            "type": "string",
+            "example": "2026-08-25T14:03:11.482Z-a7f3c1d9"
+          },
+          "created_at": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "created_by": {
+            "type": "string",
+            "description": "May be absent — an internal-auth caller carries no user id."
+          },
+          "name": {
+            "type": "string",
+            "description": "Set at publish time only, and only when the publish request carried one. A revision can have been published and still have no name; `published_at` is the signal that a revision was live at some point, not this field.\n",
+            "example": "FAQ page launch"
+          },
+          "description": {
+            "type": "string"
+          },
+          "page_count": {
+            "type": "number"
+          },
+          "published_at": {
+            "type": "string",
+            "format": "date-time",
+            "description": "The last time this revision was published. NOT the same question as `is_published`: a revision that was live yesterday still carries a `published_at`.\n"
+          },
+          "published_by": {
+            "type": "string",
+            "description": "Who performed the last publish of this revision."
+          },
+          "is_published": {
+            "type": "boolean",
+            "description": "Whether this revision is the one currently live."
+          }
+        }
+      },
+      "PortalRevisionList": {
+        "type": "object",
+        "required": [
+          "results"
+        ],
+        "properties": {
+          "results": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/PortalRevisionSummary"
             }
+          },
+          "next_cursor": {
+            "type": "string",
+            "description": "Opaque cursor to pass back as `cursor` to fetch the next page. When `next_cursor` is absent, the client has reached the end of the dataset.\n"
           }
         }
       },
-      "UpsertPortalConfigV3": {
+      "PortalRevisionCreated": {
         "allOf": [
           {
-            "$ref": "#/components/schemas/UpdateOnlyPortalConfigAttributes"
-          },
-          {
-            "$ref": "#/components/schemas/CommonConfigAttributesV3"
+            "$ref": "#/components/schemas/PortalRevisionSummary"
           },
           {
+            "type": "object",
             "properties": {
-              "origin": {
-                "$ref": "#/components/schemas/Origin"
-              },
-              "pages": {
+              "identity_providers": {
                 "type": "array",
+                "description": "The SSO identity providers just captured into this revision, with `client_secret` REDACTED exactly as the admin portal-config GET redacts it. Returned only here — not on list items or elsewhere — because the caller who just submitted providers is the one reader who needs to see what got captured, e.g. to warn that the revision was saved without a client secret.\n",
                 "items": {
-                  "$ref": "#/components/schemas/PageRequest"
+                  "$ref": "#/components/schemas/ProviderConfig"
                 }
               }
             }
           }
         ]
       },
-      "PortalConfigV3": {
+      "RevisionPage": {
+        "description": "A page from a revision snapshot. Same shape as a live `Page`, without the server-managed fields (`past_routes`, `_created_at`, `_updated_at`, `is_deleted`), which publish re-derives from the live portal.\n",
         "allOf": [
           {
-            "$ref": "#/components/schemas/UpdateOnlyPortalConfigAttributes"
+            "$ref": "#/components/schemas/Page"
           },
           {
-            "$ref": "#/components/schemas/CommonConfigAttributesV3"
+            "type": "object",
+            "required": [
+              "id",
+              "blocks"
+            ],
+            "properties": {
+              "org_id": {
+                "type": "string"
+              }
+            }
+          }
+        ]
+      },
+      "PortalRevision": {
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/PortalRevisionSummary"
           },
           {
+            "type": "object",
+            "required": [
+              "config",
+              "pages"
+            ],
             "properties": {
-              "organization_id": {
-                "type": "string",
-                "example": 12345,
-                "description": "ID of the organization"
-              },
-              "org_settings": {
-                "type": "object",
-                "description": "Organization settings",
-                "properties": {
-                  "canary": {
-                    "type": "object",
-                    "description": "Canary feature flag",
-                    "properties": {
-                      "enabled": {
-                        "type": "boolean",
-                        "description": "Enable/Disable the canary feature"
-                      }
-                    }
-                  },
-                  "notracking": {
-                    "type": "object",
-                    "description": "Disable Advanced Usage Metrics",
-                    "properties": {
-                      "enabled": {
-                        "type": "boolean",
-                        "description": "Disable browser-side scripts that track advanced usage metrics"
-                      }
-                    }
-                  }
-                }
-              },
-              "feature_flags": {
+              "config": {
                 "type": "object",
-                "description": "Feature flags for the portal",
-                "additionalProperties": {
-                  "type": "boolean"
-                }
+                "additionalProperties": true,
+                "description": "The snapshotted portal configuration. Secret-typed extension option values are removed entirely — not masked — before the response is assembled.\n"
               },
-              "grants": {
+              "pages": {
                 "type": "array",
-                "description": "Permissions granted to a portal user while accessing entities",
                 "items": {
-                  "$ref": "#/components/schemas/Grant"
+                  "$ref": "#/components/schemas/RevisionPage"
                 }
               },
               "identity_providers": {
                 "type": "array",
+                "description": "The SSO identity providers captured in this revision, with `client_secret` REDACTED exactly as the admin portal-config GET redacts it (no read path returns a stored secret).\nPublishing this revision replaces every live provider on this portal's origin, not just this portal's own, with this set. Identity providers key on `IDP#{origin}#{slug}`, a partition shared by every portal on that origin, so any other portal sharing it (an ADDITIONAL_PORTAL clone, most commonly) is affected too. A client can diff this against the live providers (by `slug`, and on `oidc_config.oidc_issuer` / `oidc_config.client_id` for a changed provider) to warn that a publish would also change SSO configuration, for this portal and any others sharing its origin.\nABSENT and `[]` are different answers. `[]` means the revision has no providers and publishing it removes the live ones; absent means the revision was saved before provider versioning, carries no SSO opinion, and publishing it changes no provider.\n",
                 "items": {
-                  "$ref": "#/components/schemas/ProviderPublicConfig"
+                  "$ref": "#/components/schemas/ProviderConfig"
                 }
               },
-              "pages": {
-                "type": "array",
-                "items": {
-                  "$ref": "#/components/schemas/Page"
-                }
+              "email_templates": {
+                "$ref": "#/components/schemas/EmailTemplates"
+              },
+              "email_template_settings": {
+                "type": "object",
+                "additionalProperties": true,
+                "description": "The portal's email template settings as they were live when the revision was saved. Read-only: this field cannot be set through the revision request and is always captured from live.\n"
               }
             }
           }
         ]
       },
-      "JuiceSettings": {
+      "PublishResult": {
         "type": "object",
+        "required": [
+          "revision_id",
+          "published_at",
+          "post_publish_warnings"
+        ],
         "properties": {
-          "is_dummy": {
-            "type": "boolean",
-            "description": "Whether the org is in dummy mode"
+          "revision_id": {
+            "type": "string"
           },
-          "is_canary": {
-            "type": "boolean",
-            "description": "Whether the org is in canary mode"
+          "published_at": {
+            "type": "string",
+            "format": "date-time"
           },
-          "redirect_to": {
+          "published_by": {
+            "type": "string"
+          },
+          "name": {
             "type": "string",
-            "description": "The URL to redirect to",
-            "example": "https://example.com"
+            "description": "The name now on the revision: the one sent in the request, or the one a previous publish set when this request omitted `name`. Absent when neither exists.\n",
+            "example": "FAQ page launch"
+          },
+          "post_publish_warnings": {
+            "type": "array",
+            "description": "Stable, machine-readable codes for best-effort post-publish side effects that exhausted their retries. Publishing itself succeeded; these are not error messages and not meant for display as-is. Clients map each code to their own localized text.\nKnown codes: `allowed_entities_change` (portal entity grants and detail pages did not sync), `dns_records_clear` (the previous domain's DNS records were not cleared). New codes may be added without a client update, so treat an unrecognized code as a generic \"a follow-up step did not finish\" case rather than an error.\n",
+            "items": {
+              "type": "string"
+            },
+            "example": [
+              "allowed_entities_change"
+            ]
           }
         }
       },
@@ -19934,6 +21019,157 @@
             "example": true
           }
         }
+      },
+      "SupportReportType": {
+        "type": "string",
+        "enum": [
+          "bug",
+          "feedback"
+        ]
+      },
+      "SupportRequestAttachment": {
+        "type": "object",
+        "required": [
+          "filename",
+          "mime_type",
+          "contents"
+        ],
+        "properties": {
+          "filename": {
+            "type": "string",
+            "maxLength": 255,
+            "example": "screenshot.png"
+          },
+          "mime_type": {
+            "type": "string",
+            "example": "image/png"
+          },
+          "contents": {
+            "type": "string",
+            "description": "Base64-encoded file, optionally as a data URL"
+          }
+        }
+      },
+      "CleverPvContext": {
+        "type": "object",
+        "properties": {
+          "screen": {
+            "type": "string",
+            "maxLength": 256,
+            "description": "Current Clever PV screen identifier"
+          },
+          "version": {
+            "type": "string",
+            "maxLength": 64,
+            "description": "Clever PV application version"
+          },
+          "connection_state": {
+            "type": "string",
+            "maxLength": 64,
+            "description": "Device connectivity at the time of the report"
+          },
+          "locale": {
+            "type": "string",
+            "maxLength": 32,
+            "description": "App locale at the time of the report"
+          },
+          "timezone": {
+            "type": "string",
+            "maxLength": 64,
+            "description": "App timezone at the time of the report"
+          },
+          "firmware_version": {
+            "type": "string",
+            "maxLength": 64,
+            "description": "Device firmware version when known"
+          },
+          "build": {
+            "type": "string",
+            "maxLength": 64,
+            "description": "App build identifier when known"
+          },
+          "trace_id": {
+            "type": "string",
+            "maxLength": 128,
+            "description": "Client-generated correlation id for the report"
+          },
+          "device": {
+            "type": "object",
+            "additionalProperties": true,
+            "description": "Optional device snapshot from the portal. Attached as a JSON file on\nthe original Zendesk comment. Must include id when present. Serialized\nJSON is limited to 256 KiB.\n"
+          },
+          "vendor": {
+            "type": "object",
+            "additionalProperties": true,
+            "properties": {
+              "id": {
+                "type": "string"
+              },
+              "name": {
+                "type": "string"
+              }
+            },
+            "description": "Optional onboarding vendor id and name. Included in the Zendesk\ncomment. Not a portal entity.\n"
+          }
+        }
+      },
+      "CreateSupportRequest": {
+        "type": "object",
+        "required": [
+          "report_type",
+          "description",
+          "submission_id"
+        ],
+        "properties": {
+          "report_type": {
+            "$ref": "#/components/schemas/SupportReportType"
+          },
+          "description": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 8000
+          },
+          "submission_id": {
+            "type": "string",
+            "minLength": 8,
+            "maxLength": 128,
+            "pattern": "^[A-Za-z0-9._-]+$",
+            "description": "Client-generated id for correlating the request"
+          },
+          "site_id": {
+            "$ref": "#/components/schemas/EntityId"
+          },
+          "device_id": {
+            "$ref": "#/components/schemas/EntityId"
+          },
+          "clever_pv": {
+            "$ref": "#/components/schemas/CleverPvContext"
+          },
+          "attachments": {
+            "type": "array",
+            "maxItems": 5,
+            "items": {
+              "$ref": "#/components/schemas/SupportRequestAttachment"
+            }
+          }
+        }
+      },
+      "SupportRequestResult": {
+        "type": "object",
+        "required": [
+          "reference",
+          "status"
+        ],
+        "properties": {
+          "reference": {
+            "type": "string",
+            "example": "12345"
+          },
+          "status": {
+            "type": "string",
+            "example": "new"
+          }
+        }
       }
     }
   },