feat: page relationships api in case of MSM and lang copies

Author: Sagar Miglani

docs/openapi/api.yaml

@@ -212,6 +212,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

@@ -631,4 +631,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

@@ -6129,3 +6129,125 @@ SentimentConfig:
       items:
         $ref: '#/SentimentGuideline'
       description: Guidelines (optionally filtered by audit type)
+
+PageRelationshipsSearchPage:
+  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:
+  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:
+  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:
+  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:
+  type: object
+  required:
+    - error
+  properties:
+    error:
+      type: string
+      example: 'Could not determine page ID'
+    detail:
+      type: string
+      example: 'HTTP 404'
+
+PageRelationshipsMapping:
+  type: object
+  additionalProperties:
+    $ref: '#/PageRelationship'
+
+PageRelationshipsErrorMapping:
+  type: object
+  additionalProperties:
+    $ref: '#/PageRelationshipError'
+
+PageRelationshipsSearchRequest:
+  type: object
+  required:
+    - pages
+  properties:
+    pages:
+      type: array
+      items:
+        $ref: '#/PageRelationshipsSearchPage'
+
+PageRelationshipsSearchResponse:
+  type: object
+  required:
+    - supported
+    - relationships
+    - errors
+  properties:
+    supported:
+      type: boolean
+      example: true
+    relationships:
+      $ref: '#/PageRelationshipsMapping'
+    errors:
+      $ref: '#/PageRelationshipsErrorMapping'

docs/openapi/site-api.yaml

@@ -150,6 +150,58 @@ site-cdn-logs-config:
       '500':
         $ref: './responses.yaml#/500'
 
+site-page-relationships-search:
+  parameters:
+    - $ref: './parameters.yaml#/siteId'
+  post:
+    tags:
+      - site
+    summary: Search page relationships for caller-provided pages
+    description: |
+      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.
+      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'