feat: Support for MSM and lang copies - page-relationship api

docs/openapi/api.yaml

@@ -214,6 +214,8 @@ paths:
     $ref: './sites-api.yaml#/site-brand-profile'
   /sites/{siteId}/config/cdn-logs:
     $ref: './site-api.yaml#/site-cdn-logs-config'
+  /sites/{siteId}/page-relationships/search:
+    $ref: './site-api.yaml#/site-page-relationships-search'
   /sites/{siteId}/opportunities:
     $ref: './site-opportunities.yaml#/site-opportunities'
   /sites/{siteId}/opportunities/by-status/{status}:

docs/openapi/examples.yaml

@@ -652,4 +652,85 @@ customer-config-v2-patch:
               origin: "manual"
               source: "api"
               categoryId: "859b91c5-0420-4f3b-a464-8d6f6ac34f64"
-              topicId: "topic-acrobat-features"
+              topicId: "topic-acrobat-features"
+
+page-relationships-search-request:
+  description: Example request body for on-demand page relationship search
+  value:
+    pages:
+      - key: "row-1"
+        pageUrl: "/de/de/adventures"
+        suggestionType: "Missing Title"
+      - key: "row-2"
+        pageUrl: "/us/en/adventures/camping"
+        suggestionType: "Missing Description"
+
+page-relationships-search-response:
+  description: Relationship lookup response with resolved relationships
+  value:
+    supported: true
+    relationships:
+      "row-1":
+        pagePath: "/de/de/adventures"
+        pageId: "123e4567-e89b-12d3-a456-426614174000"
+        chain:
+          - pageId: "123e4567-e89b-12d3-a456-426614174010"
+            pagePath: "/content/site/language-masters/de/adventures"
+            metadata:
+              sourceType: "liveCopyOf"
+          - pageId: "123e4567-e89b-12d3-a456-426614174011"
+            pagePath: "/content/site/language-masters/en/adventures"
+            metadata:
+              sourceType: "langCopyOf"
+      "row-2":
+        pagePath: "/us/en/adventures/camping"
+        pageId: "123e4567-e89b-12d3-a456-426614174001"
+        chain:
+          - pageId: "123e4567-e89b-12d3-a456-426614174012"
+            pagePath: "/content/site/us/adventures"
+            metadata:
+              sourceType: "liveCopyOf"
+          - pageId: "123e4567-e89b-12d3-a456-426614174013"
+            pagePath: "/content/site/global/adventures"
+            metadata:
+              sourceType: "langCopyOf"
+    errors: {}
+
+page-relationships-search-no-relationship-response:
+  description: Relationship lookup response where no source relationship is detected for a page
+  value:
+    supported: true
+    relationships:
+      "row-1":
+        pagePath: "/de/de/adventures"
+        pageId: "123e4567-e89b-12d3-a456-426614174000"
+        chain: []
+    errors: {}
+
+page-relationships-search-partial-response:
+  description: Relationship lookup response with partial per-page failures
+  value:
+    supported: true
+    relationships:
+      "row-2":
+        pagePath: "/us/en/adventures/camping"
+        pageId: "123e4567-e89b-12d3-a456-426614174002"
+        chain:
+          - pageId: "123e4567-e89b-12d3-a456-426614174020"
+            pagePath: "/content/site/language-masters/de/adventures"
+            metadata:
+              sourceType: "langCopyOf"
+          - pageId: "123e4567-e89b-12d3-a456-426614174021"
+            pagePath: "/content/site/language-masters/en/adventures"
+            metadata:
+              sourceType: "langCopyOf"
+    errors:
+      "row-1":
+        error: "Could not determine page ID"
+
+page-relationships-search-unsupported-response:
+  description: Response when page relationships are not supported for a site
+  value:
+    supported: false
+    relationships: {}
+    errors: {}

docs/openapi/schemas.yaml

@@ -6472,7 +6472,6 @@ StageConfigsResponse:
   description: Response is the array of stage configs (one per staging domain). Each item is domain plus full edge optimize metaconfig for that stage site.
   items:
     $ref: '#/StageConfigItem'
-
 PlgOnboarding:
   type: object
   description: A PLG ASO onboarding record tracking the lifecycle of a domain onboarding.
@@ -6579,3 +6578,140 @@ PlgOnboarding:
       $ref: '#/DateTime'
     updatedAt:
       $ref: '#/DateTime'
+
+PageRelationshipsSearchPage:
+  x-experimental: true
+  type: object
+  required:
+    - pageUrl
+    - key
+  properties:
+    pageUrl:
+      type: string
+      description: Page path or absolute URL to resolve.
+      example: '/us/en/products'
+    suggestionType:
+      type: string
+      description: Suggestion/issue classifier used by the backend to apply relationship checks.
+      example: 'Missing Title'
+    key:
+      type: string
+      description: Caller-provided key used in relationships/errors maps.
+      example: 'row-1'
+
+PageRelationshipChainItem:
+  x-experimental: true
+  type: object
+  description: |
+    A single step in the relationship lineage.
+    Chain items are ordered from the requested page's immediate parent upward through ancestors.
+  required:
+    - pageId
+    - pagePath
+  properties:
+    pageId:
+      type: string
+      description: page identifier for this chain.
+      example: '123e4567-e89b-12d3-a456-426614174000'
+    pagePath:
+      type: string
+      description: Page path for this chain hop.
+      example: '/language-masters/en/adventures'
+    metadata:
+      $ref: '#/PageRelationshipMetadata'
+
+PageRelationshipMetadata:
+  x-experimental: true
+  type: object
+  additionalProperties: true
+  properties:
+    sourceType:
+      oneOf:
+        - type: string
+        - type: "null"
+      description: |
+        Source classification for this chain entry from the relationship provider.
+        Value is provider-defined and intentionally not constrained.
+
+PageRelationship:
+  x-experimental: true
+  type: object
+  required:
+    - pagePath
+    - pageId
+    - chain
+  properties:
+    pagePath:
+      type: string
+      description: Normalized page path or absolute URL for the requested page.
+      example: '/us/en/adventures'
+    pageId:
+      type: string
+      description: Resolved page identifier used by downstream fix operations.
+      example: 'pg-123'
+    chain:
+      type: array
+      description: |
+        Ordered relationship lineage returned by content API.
+        Sequence starts with the immediate parent of the requested page,
+        then grandparent, and so on.
+      items:
+        $ref: '#/PageRelationshipChainItem'
+
+PageRelationshipError:
+  x-experimental: true
+  type: object
+  required:
+    - error
+  properties:
+    error:
+      type: string
+      example: 'Could not determine page ID'
+    detail:
+      type: string
+      example: 'HTTP 404'
+
+PageRelationshipsMapping:
+  x-experimental: true
+  type: object
+  additionalProperties:
+    $ref: '#/PageRelationship'
+
+PageRelationshipsErrorMapping:
+  x-experimental: true
+  type: object
+  additionalProperties:
+    $ref: '#/PageRelationshipError'
+
+PageRelationshipsSearchRequest:
+  x-experimental: true
+  type: object
+  description: |
+    Experimental request schema for the page-relationships proxy endpoint.
+    Used by UI-facing, on-demand relationship lookups backed by AEM Content API.
+  required:
+    - pages
+  properties:
+    pages:
+      type: array
+      items:
+        $ref: '#/PageRelationshipsSearchPage'
+
+PageRelationshipsSearchResponse:
+  x-experimental: true
+  type: object
+  description: |
+    Experimental response schema for the page-relationships proxy endpoint.
+    Returned by the API proxy over AEM Content API relationship lookup results.
+  required:
+    - supported
+    - relationships
+    - errors
+  properties:
+    supported:
+      type: boolean
+      example: true
+    relationships:
+      $ref: '#/PageRelationshipsMapping'
+    errors:
+      $ref: '#/PageRelationshipsErrorMapping'

docs/openapi/site-api.yaml

@@ -150,6 +150,63 @@ site-cdn-logs-config:
       '500':
         $ref: './responses.yaml#/500'
 
+site-page-relationships-search:
+  parameters:
+    - $ref: './parameters.yaml#/siteId'
+  post:
+    x-experimental: true
+    tags:
+      - site
+    summary: Search page relationships for caller-provided pages
+    description: |
+      Experimental endpoint.
+
+      Resolves page relationship context for the provided set of page paths/URLs.
+      This endpoint is intended for on-demand UI flows (for example, fix-confirmation popups),
+      where only specific pages need relationship context at request time.
+
+      Supported only for AEM-authored sites with Content API support.
+      The returned `relationships[*].chain` is ordered from the immediate parent
+      of the requested page to grandparent, and so on toward the root.
+    operationId: searchSitePageRelationships
+    security:
+      - ims_key: [ ]
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: './schemas.yaml#/PageRelationshipsSearchRequest'
+          examples:
+            page-relationships-search-request:
+              $ref: './examples.yaml#/page-relationships-search-request'
+    responses:
+      '200':
+        description: Relationship lookup completed
+        content:
+          application/json:
+            schema:
+              $ref: './schemas.yaml#/PageRelationshipsSearchResponse'
+            examples:
+              page-relationships-search-response:
+                $ref: './examples.yaml#/page-relationships-search-response'
+              page-relationships-search-no-relationship-response:
+                $ref: './examples.yaml#/page-relationships-search-no-relationship-response'
+              page-relationships-search-partial-response:
+                $ref: './examples.yaml#/page-relationships-search-partial-response'
+              page-relationships-search-unsupported-response:
+                $ref: './examples.yaml#/page-relationships-search-unsupported-response'
+      '400':
+        $ref: './responses.yaml#/400'
+      '401':
+        $ref: './responses.yaml#/401'
+      '403':
+        $ref: './responses.yaml#/403-site-access-forbidden'
+      '404':
+        $ref: './responses.yaml#/404-site-not-found-with-id'
+      '500':
+        $ref: './responses.yaml#/500'
+
 site-reports:
   parameters:
     - $ref: './parameters.yaml#/siteId'

docs/openapi/site-opportunities.yaml

@@ -594,6 +594,82 @@ site-opportunity-suggestions-auto-fix:
                       description: |
                         Optional. Meaningful for action assess or assess-urls. When true, worker
                         runs only no-AEM checks; for assess, promise token is not required.
+                    fixTargetGroups:
+                      type: array
+                      x-experimental: true
+                      description: |
+                        Experimental (meta-tags only). Optional override for fix-target grouping.
+                        When provided, suggestions
+                        are grouped by the given relationshipContext.fixTargetPageId instead of
+                        by each suggestion's detected page URL. The worker applies the fix to
+                        the specified page directly. Typically populated by the UI when the
+                        page-relationship dialog resolves a source (blueprint/language-master)
+                        page.
+
+                        Effective only for AEM CS meta-tags autofix on the Content API path.
+                        If meta-tags are routed to PSS (for example, disableContentApiForMetaTags=true),
+                        this field is accepted but ignored.
+
+                        When absent, the API falls back to grouping by suggestion URL.
+                      minItems: 1
+                      items:
+                        type: object
+                        required:
+                          - suggestionIds
+                          - relationshipContext
+                        properties:
+                          suggestionIds:
+                            type: array
+                            minItems: 1
+                            items:
+                              $ref: './schemas.yaml#/Id'
+                          relationshipContext:
+                            type: object
+                            x-experimental: true
+                            description: |
+                              Experimental relationship metadata forwarded to the autofix worker.
+                              Required for relationship-aware grouping.
+                              When fixTargetMode is source, appliedOnPagePath should be provided.
+                              Effective only on the AEM CS Content API path for meta-tags;
+                              ignored when meta-tags are handled via PSS.
+                            additionalProperties: false
+                            required:
+                              - fixTargetPageId
+                            properties:
+                              fixTargetPageId:
+                                type: string
+                                minLength: 1
+                                description: |
+                                  Page identifier to apply this group to. For relationship-source
+                                  flows this is typically the source page ID resolved by the UI.
+                                  Used only on Content API meta-tags execution path.
+                                example: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890'
+                              fixTargetMode:
+                                type: string
+                                enum: [source, local]
+                                description: |
+                                  Whether this group is being fixed at source or locally.
+                                  Used for Content API relationship-aware meta-tags flow.
+                              cancelInheritance:
+                                type: boolean
+                                description: |
+                                  Experimental. Optional. When true, indicates the fix is intentionally
+                                  applied at a local inheriting page and inheritance should remain cancelled.
+                                  Currently applied for Content API title/description flows only.
+                              appliedOnPagePath:
+                                type: string
+                                minLength: 1
+                                description: |
+                                  Source page path where the fix is applied for source-targeted groups.
+                                  Used for relationship context and downstream reporting.
+                        example:
+                          suggestionIds:
+                            - '2eb0ae0d-baa8-4668-abf5-8b22ef75b95f'
+                            - '85d87ee0-5818-419a-863f-dcb90630ba11'
+                          relationshipContext:
+                            fixTargetPageId: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890'
+                            fixTargetMode: source
+                            appliedOnPagePath: /content/wknd/language-masters/en/adventures/bali-surf-camp
                     customData:
                       description: Additional custom data to forward to the autofix worker