schemas.yaml

BrandProfile:
  type: object
  description: The brand voice profile generated by the brand-profile agent. Note this schema contains a representative subset; additional fields may be added over time.
  properties:
    version:
      type: integer
      description: Incrementing version whenever the profile changes
      example: 3
    updatedAt:
      $ref: '#/DateTime'
      description: ISO timestamp for the last update
    contentHash:
      type: string
      description: Deterministic hash of the profile content used for change detection
    summary:
      type: string
      description: Short description of the profile or summary text
    discovery:
      type: object
      additionalProperties: true
      description: Discovery data such as site coverage, URL structure, analyzed sections, etc.
      example:
        url_structure:
          main_sections:
            - '/'
            - '/products'
    clustering:
      type: object
      additionalProperties: true
      description: Voice clustering output.
    competitiveContext:
      type: object
      additionalProperties: true
      description: Competitive positioning and comparative insights.
    mainProfile:
      type: object
      additionalProperties: true
      description: Primary brand voice profile (tone, vocabulary, guidelines, etc.).
    subBrands:
      type: array
      description: Optional sub-brand voice profiles.
      items:
        type: object
        additionalProperties: true
    metadata:
      type: object
      additionalProperties: true
      description: Free-form metadata bucket for future extensions.
BotBlockerResult:
  type: object
  description: Result of bot blocker detection for a site. Indicates whether the site is crawlable by bots, what type of blocking was detected (if any), and the confidence level of the detection.
  properties:
    crawlable:
      type: boolean
      description: Whether the site can be crawled by bots
      example: false
    type:
      type: string
      description: The type of bot blocker detected or infrastructure present
      enum:
        - 'cloudflare'
        - 'imperva'
        - 'akamai'
        - 'fastly'
        - 'cloudfront'
        - 'cloudflare-allowed'
        - 'imperva-allowed'
        - 'akamai-allowed'
        - 'fastly-allowed'
        - 'cloudfront-allowed'
        - 'http2-block'
        - 'none'
        - 'unknown'
      example: 'cloudflare'
    confidence:
      type: number
      format: float
      minimum: 0
      maximum: 1
      description: Confidence level of the detection (0.0 to 1.0). Values >= 0.95 indicate reliable detection. Lower values suggest uncertain situations.
      example: 0.99
    reason:
      type: string
      description: Optional reason or additional context for the detection result
      example: 'HTTP 403 Forbidden - access denied'
  required:
    - crawlable
    - type
    - confidence
Id:
  type: string
  format: uuid
  readOnly: true
  example: '123e4567-e89b-12d3-a456-426614174000'
BrandId:
  type: string
  format: urn
  readOnly: true
  example: 'urn:aaid:sc:VA6C2:e64205e7-13ca-51e8-8b83-8d8ef1ebf911'
DateTime:
  type: string
  format: date-time
  example: '2024-01-19T14:20:30Z'
DeliveryType:
  type: string
  enum:
    - 'aem_edge'
    - 'aem_cs'
    - 'other'
  example: 'aem_edge'
DeliveryConfig:
  type: object
  properties:
    programId:
      description: The program ID
      type: string
      example: '12652'
    environmentId:
      description: The environment ID
      type: string
      example: '16854'
    authorURL:
      description: The author URL
      type: string
      format: url
      example: 'https://author-p12652-e16854-cmstg.adobeaemcloud.com/'
    siteId:
      description: The site ID
      type: string
      example: '1234'
  additionalProperties: true
AuditType:
  type: string
  enum:
    - '404'
    - 'apex'
    - 'cwv'
    - 'lhs'
    - 'lhs-desktop'
    - 'lhs-mobile'
    - 'broken-backlinks'
    - 'canonical'
    - 'sitemap'
    - 'structured-data'
    - 'costs'
    - 'meta-tags'
    - 'product-metatags'
    - 'commerce-product-enrichments'
    - 'broken-internal-links'
    - 'experimentation-opportunities'
    - 'llm-error-pages'
    - 'prerender'
    - 'related-urls'
    - 'summarization'
    - 'faqs'
  example: 'cwv'
URL:
  type: string
  format: url
  example: 'https://www.example.com'
Domain:
  type: string
  format: domain
  example: 'www.example.com'
ScopeName:
  type: string
  enum:
    - 'imports.write'
    - 'imports.read'
ImsOrganizationId:
  type: string
  example: '1234567890ABCDEF12345678@AdobeOrg'
ImsUserAccessToken:
  type: string
  example: 'eyJhbGciOiJIUzI1NiJ9.eyJpZCI6IjEyMzQ1IiwidHlwZSI6ImFjY2Vzc190b2tlbiIsImNsaWVudF9pZCI6ImV4YW1wbGVfYXBwIiwidXNlcl9pZCI6Ijk4NzY1NDc4OTBBQkNERUYxMjM0NTY3OEBhYmNkZWYxMjM0NTY3ODkuZSIsImFzIjoiaW1zLW5hMSIsImFhX2lkIjoiMTIzNDU2Nzg5MEFCQ0RFRjEyMzQ1Njc4QGFkb2JlLmNvbSIsImNyZWF0ZWRfYXQiOiIxNzEwMjQ3MDAwMDAwIn0.MRDpxgxSHDj4DmA182hPnjMAnKkly-VUJ_bXpQ-J8EQ'
SlackMentionConfig:
  type: object
  properties:
    slack:
      type: array
      items:
        type: string
HandlerConfig:
  type: object
  additionalProperties: false
  properties:
    mentions:
      $ref: '#/SlackMentionConfig'
    excludedURLs:
      description: URLs to be excluded from the handler's processing
      type: array
      items:
        type: string
        format: uri
    groupedURLs:
      description: List of grouped URL patterns for categorization. Each entry should include a name and a URL pattern. If empty, previously grouped URLs will be removed
      type: array
      items:
        type: object
        properties:
          name:
            description: Name of the URL group
            type: string
          pattern:
            description: Pattern representing the URL path structure to group
            type: string
  patternProperties:
    '^(404|broken-backlinks)$':
      type: object
      properties:
        mentions:
          $ref: '#/SlackMentionConfig'
        # Define other properties specific to the alert type here
  example:
    excludedURLs:
      - 'https://www.adobe.com/excluded-page'
      - 'https://www.adobe.com/another-excluded-page'
    groupedURLs:
      - name: 'catalog'
        pattern: '/products/'
      - name: 'blog'
        pattern: '/post/'
SlackConfig:
  type: object
  additionalProperties: true
  properties:
    channel:
      description: The Slack channel ID to send notifications to
      type: string
      example: 'C1234567890'
    workspace:
      description: The Slack workspace name to send notifications to
      type: string
      example: 'example-workspace'
    invitedUserCount:
      description: The number of external users invited to the Slack channel
      type: integer
      example: 5
    channel-url:
      description: Slack URL of the channel to send notifications to
      type: string
      example: 'https://example-workspace.slack.com/archives/C1234567890'
Config:
  type: object
  additionalProperties: true
  properties:
    slack:
      description: Optional. The Slack configuration
      $ref: '#/SlackConfig'
    handlers:
      description: Optional. The Alert configuration
      $ref: '#/HandlerConfig'
    contentAiConfig:
      description: Optional. The ContentAi configuration
      $ref: '#/ContentAiConfig'
    cdnLogsConfig:
      description: Optional. The CDN logs configuration
      $ref: '#/CdnLogsConfig'
    brandProfile:
      description: Optional. The Brand Profile determined during on-boarding.
      type: object
      additionalProperties: true
    edgeOptimizeConfig:
      description: Optional. The edge optimize configuration for the site.
      $ref: '#/EdgeOptimizeConfig'
EdgeOptimizeConfig:
  type: object
  description: Edge optimize configuration for a site
  properties:
    enabled:
      description: Indicates when edge optimization was enabled for the site
      oneOf:
        - type: boolean
          deprecated: true
          example: true
          description: Deprecated. Use timestamp format instead.
        - type: number
          example: 1772531669121
          description: Timestamp (milliseconds since epoch) indicating when edge optimization was enabled for the site.
    opted:
      description: Timestamp (milliseconds since epoch) when the site opted into edge optimize
      type: number
      example: 1772531669121
    stagingDomains:
      description: Staging domains associated with this site for edge optimize
      type: array
      items:
        type: object
        required:
          - domain
          - id
        properties:
          domain:
            type: string
            description: Staging domain hostname
            example: 'staging.example.com'
          id:
            type: string
            format: uuid
            description: Spacecat site ID for the stage site
  additionalProperties: true
ContentAiConfig:
  type: object
  properties:
    index:
      description: Optional. The index name for website in the content AI service
      type: string
CdnLogsConfig:
  type: object
  properties:
    bucketName:
      description: The name of the S3 bucket to store CDN logs
      type: string
    outputLocation:
      description: The output location for sharepoint folder
      type: string
    filters:
      description: The filters for CDN logs
      type: array
      items:
        type: object
        properties:
          key:
            description: The key to filter
            type: string
          value:
            description: The value to filter
            type: array
            items:
              type: string
  example:
    bucketName: 'test-bucket'
    filters: [{ key: 'test-key', value: ['test-value'] }]
    outputLocation: 'test-output-location'
OrganizationConfig:
  allOf:
    - $ref: '#/Config'
SiteConfig:
  allOf:
    - $ref: '#/Config'
Organization:
  type: object
  properties:
    id:
      description: The organization ID in uuid format
      $ref: '#/Id'
    name:
      description: The name of the organization
      type: string
    imsOrgId:
      description: Optional. The ID of the Adobe IMS organization
      $ref: '#/ImsOrganizationId'
    config:
      description: Optional. The configuration of the organization
      $ref: '#/OrganizationConfig'
    createdAt:
      description: The date and time when the organization was created
      $ref: '#/DateTime'
    updatedAt:
      description: The date and time when the organization was last updated
      $ref: '#/DateTime'
  example:
    id: 'o1p2q3r4-s5t6-u7v8-w9x0-yz12x34y56z'
    name: 'Example Organization'
    imsOrgId: '1234567890ABCDEF12345678@AdobeOrg'
    config:
      slack:
        channel: '#example-channel'
        workspace: 'example-workspace'
        invitedUserCount: 5
      handlers:
        '404':
          byOrg: true
          mentions:
            slack:
              - '@user1'
              - '@user2'
        'cwv':
          byOrg: false
          mentions:
            slack:
              - '@user5'
              - '@user6'
      contentAiConfig:
        index: 'example-index-name'
    createdAt: '2023-12-15T09:30:00Z'
    updatedAt: '2024-01-19T11:20:00Z'
OrganizationList:
  type: array
  items:
    $ref: './schemas.yaml#/Organization'
OrganizationCreate:
  type: object
  required:
    - name
  properties:
    name:
      description: The name of the organization
      type: string
    imsOrgId:
      description: Optional. The ID of the Adobe IMS organization
      $ref: '#/ImsOrganizationId'
    config:
      description: Optional. The configuration of the organization
      $ref: '#/OrganizationConfig'
  example:
    name: 'Example Organization'
    imsOrgId: '1234567890ABCDEF12345678@AdobeOrg'
    config:
      slack:
        channel: '#example-channel'
        workspace: 'example-workspace'
      handlers:
        '404':
          mentions:
            slack:
              - '@user3'
              - '@user4'
        'cwv':
          byOrg: false
          mentions:
            slack:
              - '@user5'
              - '@user6'
      contentAiConfig:
        index: 'example-index-name'
OrganizationUpdate:
  type: object
  properties:
    name:
      description: The name of the organization
      type: string
    imsOrgId:
      description: Optional. The ID of the Adobe IMS organization
      $ref: '#/ImsOrganizationId'
    config:
      description: Optional. The configuration of the organization
      $ref: '#/OrganizationConfig'
  example:
    name: 'Example Organization'
    imsOrgId: '1234567890ABCDEF12345678@AdobeOrg'
    config:
      slack:
        channel: '#example-channel'
        workspace: 'example-workspace'
      handlers:
        '404':
          mentions:
            slack:
              - '@user3'
              - '@user4'
        'cwv':
          mentions:
            slack:
              - '@user5'
              - '@user6'
      contentAiConfig:
        index: 'example-index-name'
Project:
  type: object
  properties:
    id:
      description: The project ID in uuid format
      $ref: '#/Id'
    name:
      description: The name of the project
      type: string
    organizationId:
      description: The ID of the organization this project belongs to
      $ref: '#/Id'
    createdAt:
      description: The date and time when the project was created
      $ref: '#/DateTime'
    updatedAt:
      description: The date and time when the project was last updated
      $ref: '#/DateTime'
  example:
    id: 'p1r2o3j4-e5c6-t7i8-d9a0-b11c12d13e14'
    name: 'Example Project'
    organizationId: 'o1p2q3r4-s5t6-u7v8-w9x0-yz12x34y56z'
    createdAt: '2023-12-15T09:30:00Z'
    updatedAt: '2024-01-19T11:20:00Z'
ProjectList:
  type: array
  items:
    $ref: './schemas.yaml#/Project'
ProjectCreate:
  type: object
  required:
    - name
    - organizationId
  properties:
    name:
      description: The name of the project
      type: string
    organizationId:
      description: The ID of the organization this project belongs to
      $ref: '#/Id'
  example:
    name: 'New Project'
    organizationId: 'o1p2q3r4-s5t6-u7v8-w9x0-yz12x34y56z'
ProjectUpdate:
  type: object
  properties:
    name:
      description: The name of the project
      type: string
    organizationId:
      description: The ID of the organization this project belongs to
      $ref: '#/Id'
  example:
    name: 'Updated Project Name'
    organizationId: 'o1p2q3r4-s5t6-u7v8-w9x0-yz12x34y56z'
Site:
  type: object
  properties:
    id:
      description: The site ID in uuid format
      $ref: '#/Id'
    organizationId:
      description: The optional ID of the organization this site belongs to
      $ref: '#/Id'
    projectId:
      description: The optional ID of the project this site belongs to
      $ref: '#/Id'
    isPrimaryLocale:
      description: Whether this site is the primary locale for the project
      type: boolean
    language:
      description: The language code in ISO 639-1 format (2 lowercase letters)
      type: string
      pattern: '^[a-z]{2}$'
      example: 'en'
    region:
      description: The region code in ISO 3166-1 alpha-2 format (2 uppercase letters)
      type: string
      pattern: '^[A-Z]{2}$'
      example: 'US'
    baseURL:
      description: The base URL of the site
      $ref: '#/URL'
    name:
      description: The name of the site
      type: string
    deliveryType:
      description: The type of the delivery this site is using
      $ref: '#/DeliveryType'
    deliveryConfig:
      description: The delivery configuration of the site
      $ref: '#/DeliveryConfig'
    gitHubURL:
      description: The optional GitHub URL of the site
      $ref: '#/URL'
    goLiveDate:
      description: The date and time when the site went live on AEM Edge
      nullable: true
      $ref: '#/DateTime'
    config:
      description: Optional. The configuration of the site. May override the organization configuration.
      $ref: '#/SiteConfig'
    createdAt:
      description: The date and time when the site was created
      $ref: '#/DateTime'
    updatedAt:
      description: The date and time when the site was last updated
      $ref: '#/DateTime'
  example:
    id: 'a1b2c3d4-e5f6-7g8h-9i0j-k11l12m13n14'
    organizationId: 'o1p2q3r4-s5t6-u7v8-w9x0-yz12x34y56z'
    baseURL: 'https://example-site.com'
    name: 'Example Site'
    deliveryType: 'aem_edge'
    deliveryConfig:
      programId: '12652'
      environmentId: '16854'
      authorURL: 'https://author-p12652-e16854-cmstg.adobeaemcloud.com/'
      siteId: '1234'
    gitHubURL: 'https://github.com/example/repo'
    goLiveDate: '2024-01-20T10:00:00Z'
    config:
      slack:
        channel: 'C1234567890'
        workspace: 'example-workspace'
      handlers:
        '404':
          mentions:
            slack:
              - '@user1'
              - '@user2'
        'broken-backlinks':
          mentions:
            slack:
              - '@user5'
              - '@user6'
          excludedURLs:
            description: URLs to be excluded from the alert
            type: array
            items:
              type: string
              format: uri'
          groupedURLs:
            description: List of grouped URL patterns for categorization. Each entry should include a name and a URL pattern. If empty, previously grouped URLs will be removed
            type: array
            items:
              type: object
              properties:
                name:
                  description: Name of the URL group
                  type: string
                pattern:
                  description: Pattern representing the URL path structure to group
                  type: string
      contentAiConfig:
        index: 'example-index-name'
      cdnLogsConfig:
        bucketName: 'test-bucket'
        filters: [{ key: 'test-key', value: ['test-value'] }]
        outputLocation: 'test-output-location'
    createdAt: '2023-12-15T09:30:00Z'
    updatedAt: '2024-01-19T11:20:00Z'
SiteWithLatestAudit:
  allOf:
    - $ref: '#/Site'
    - type: object
      properties:
        audits:
          description: An array with the latest audit for the given audit type
          type: array
          items:
            $ref: '#/Audit'
  example:
    id: 'a1b2c3d4-e5f6-7g8h-9i0j-k11l12m13n14'
    organizationId: 'o1p2q3r4-s5t6-u7v8-w9x0-yz12x34y56z'
    baseURL: 'https://example-site.com'
    name: 'Example Site'
    deliveryType: 'aem_edge'
    gitHubURL: 'https://github.com/example/repo'
    goLiveDate: '2024-01-20T10:00:00Z'
    createdAt: '2023-12-15T09:30:00Z'
    updatedAt: '2024-01-19T11:20:00Z'
    audits:
      - siteId: 'a1b2c3d4-e5f6-7g8h-9i0j-k11l12m13n14'
        auditedAt: '2024-01-20T12:00:00Z'
        expiresAt: '2024-07-20T12:00:00Z'
        auditType: 'cwv'
        isError: false
        deliveryType: 'aem_edge'
        fullAuditRef: 'https://some-audit-system/full-report/1234'
        auditResult:
          someProperty: 'someValue'
        previousAuditResult:
          someProperty: 'somePreviousValue'
SiteList:
  type: array
  items:
    $ref: './schemas.yaml#/Site'
SiteWithLatestAuditList:
  type: array
  items:
    $ref: './schemas.yaml#/SiteWithLatestAudit'
SiteCreate:
  type: object
  required:
    - baseURL
    - deliveryType
  properties:
    organizationId:
      description: The optional ID of the organization this site belongs to
      default: null
      $ref: '#/Id'
    projectId:
      description: The optional ID of the project this site belongs to
      $ref: '#/Id'
    isPrimaryLocale:
      description: Whether this site is the primary locale for the project
      type: boolean
    language:
      description: The language code in ISO 639-1 format (2 lowercase letters)
      type: string
      pattern: '^[a-z]{2}$'
      example: 'en'
    region:
      description: The region code in ISO 3166-1 alpha-2 format (2 uppercase letters)
      type: string
      pattern: '^[A-Z]{2}$'
      example: 'US'
    name:
      description: The name of the site
      type: string
    baseURL:
      description: The base URL of the site
      $ref: '#/URL'
    deliveryType:
      description: The type of the delivery this site is using
      $ref: '#/DeliveryType'
    gitHubURL:
      description: The optional GitHub URL of the site
      $ref: '#/URL'
    goLiveDate:
      description: The date and time when the site went live on AEM Edge
      nullable: true
      $ref: '#/DateTime'
  example:
    organizationId: 'o1p2q3r4-s5t6-u7v8-w9x0-yz12x34y56z'
    baseURL: 'https://www.newsite.com'
    deliveryType: 'aem_cs'
    name: 'New Site'
SiteUpdate:
  type: object
  properties:
    organizationId:
      description: The optional ID of the organization this site belongs to
      $ref: '#/Id'
    projectId:
      description: The optional ID of the project this site belongs to
      $ref: '#/Id'
    isPrimaryLocale:
      description: Whether this site is the primary locale for the project
      type: boolean
    language:
      description: The language code in ISO 639-1 format (2 lowercase letters)
      type: string
      pattern: '^[a-z]{2}$'
      example: 'en'
    region:
      description: The region code in ISO 3166-1 alpha-2 format (2 uppercase letters)
      type: string
      pattern: '^[A-Z]{2}$'
      example: 'US'
    name:
      description: The name of the site
      type: string
    deliveryType:
      description: The type of the delivery this site is using
      $ref: '#/DeliveryType'
    deliveryConfig:
      description: The delivery configuration of the site
      $ref: '#/DeliveryConfig'
    goLiveDate:
      description: The date and time when the site went live on AEM Edge
      nullable: true
      $ref: '#/DateTime'
    config:
      description: Optional. The configuration of the site
      $ref: '#/SiteConfig'
  example:
    organizationId: 'u7y6t5r4-e3w2-x1z0-z9y8-x7v6w5u4t3s2'
    deliveryType: 'other'
    name: 'New Site'
    deliveryConfig:
      programId: '12652'
      environmentId: '16854'
      authorURL: 'https://author-p12652-e16854-cmstg.adobeaemcloud.com/'
      siteId: '1234'
    goLiveDate: '2024-01-20T10:00:00Z'
CdnLogsConfigUpdate:
  type: object
  required:
    - cdnLogsConfig
  properties:
    cdnLogsConfig:
      description: The CDN logs configuration to update
      $ref: '#/CdnLogsConfig'
  example:
    cdnLogsConfig:
      bucketName: 'test-bucket'
      outputLocation: 'test-output-location'
      filters: [{ key: 'test-key', value: ['test-value'] }]
UpdateHandlerTypeConfig:
  type: object
  properties:
    excludedURLs:
      description: Set of URLs to exclude. If empty, previously excluded URLs will be removed
      type: array
      items:
        type: string
    groupedURLs:
      description: List of grouped URL patterns for categorization. Each entry should include a name and a URL pattern. If empty, previously grouped URLs will be removed
      type: array
      items:
        type: object
        properties:
          name:
            description: Name of the URL group
            type: string
          pattern:
            description: Pattern representing the URL path structure to group
            type: string
  example:
    excludedURLs:
      - 'https://www.adobe.com/some-page'
      - 'https://www.adobe.com/another-page'
    groupedURLs:
      - name: 'catalog'
        pattern: '/products/'
      - name: 'blog'
        pattern: '/post/'
ConfigurationSitesAuditsUpdateResult:
  type: object
  properties:
    status:
      type: integer
      description: The HTTP status code of the operation (e.g., 200 for success)
    message:
      type: string
      description: A message indicating the result of the operation
  required:
    - status
    - message
Audit:
  type: object
  readOnly: true
  properties:
    siteId:
      description: The ID of the site this audit belongs to
      $ref: '#/Id'
    auditedAt:
      description: The date and time of the audit in ISO 8601 format
      $ref: '#/DateTime'
    expiresAt:
      description: The date and time when the audit expires in ISO 8601 format
      $ref: '#/DateTime'
    deliveryType:
      description: The type of the delivery this site is using
      $ref: '#/DeliveryType'
    fullAuditRef:
      description: |
        A reference by which the full external result of an audit can be accessed, which is dependent on the audit type.
      type: string
    auditResult:
      $ref: '#/AuditResult'
    previousAuditResult:
      $ref: '#/AuditResult'
  example:
    siteId: 'a1b2c3d4-e5f6-7g8h-9i0j-k11l12m13n14'
    auditedAt: '2024-01-20T12:00:00Z'
    expiresAt: '2024-07-20T12:00:00Z'
    auditType: 'cwv'
    isError: false
    deliveryType: 'aem_edge'
    fullAuditRef: 'https://some-audit-system/full-report/1234'
    auditResult:
      someProperty: 'someValue'
    previousAuditResult:
      someProperty: 'somePreviousValue'
AuditResult:
  description: The result of an audit, which is dependent on the audit type.
  oneOf:
    - type: object
      additionalProperties: true
    - type: object
      properties:
        experimentationOpportunities:
          type: array
          description: A list of experimentation opportunities
          items:
            $ref: './schemas.yaml#/ExperimentationOpportunity'
    - type: object
      description: |
        The result of broken-backlinks audit.
      properties:
        brokenBacklinks:
          type: array
          description: A list of broken backlinks.
          items:
            $ref: './schemas.yaml#/BrokenBacklink'
        fullAuditRef:
          description: |
            A reference by which the full external result of an audit can be accessed, which is dependent on the audit type.
          type: string
    - type: object
      description: |
        The result of broken-internal-links audit.
      properties:
        brokenInternalLinks:
          type: array
          description: A list of broken internal links.
          items:
            $ref: './schemas.yaml#/BrokenInternalLink'
        fullAuditRef:
          description: |
            A reference by which the full external result of an audit can be accessed, which is dependent on the audit type.
          type: string
        finalUrl:
          description: The final URL for the audited page.
          type: string
    - type: array
      description: Information about the provided URLs in the Google index.
      items:
        $ref: './schemas.yaml#/StructuredData'
    - type: object
      description: |
        The result of costs audit.
      properties:
        ahrefs:
          type: object
          properties:
            usedApiUnits:
              description: |
                API units used so far in the current month.
              type: integer
            limitApiUnits:
              description: |
                Limit of API units for the current month.
              type: integer
            fullAuditRef:
              description: |
                A reference by which the full external result of an audit can be accessed, which is dependent on the audit type.
              type: string
    - type: object
      description: |
        The result of a meta-tags audit.
      properties:
        auditResult:
          type: object
          properties:
            detectedTags:
              description: |
                A mapping of URLs to their detected meta-tags issues and recommendations.
              type: object
              additionalProperties:
                type: object
                properties:
                  title:
                    type: object
                    properties:
                      seoRecommendation:
                        description: |
                          SEO recommendation for the title tag.
                        type: string
                      issue:
                        description: |
                          The issue detected in the title tag.
                        type: string
                      issueDetails:
                        description: |
                          Detailed explanation of the issue detected in the title tag.
                        type: string
                      seoImpact:
                        description: |
                          The impact of the detected issue on SEO.
                        type: string
            finalUrl:
              description: |
                The final URL for the audited page.
              type: string
    - type: object
      description: |
        The result of a product-metatags audit targeting Product Detail Pages (PDP) of commerce sites.
        This audit specifically analyzes product pages for e-commerce optimization, scraping SKU,
        thumbnail images, and catalog/store view codes for later autofixing capabilities.
      properties:
        auditResult:
          type: object
          properties:
            productDetailPages:
              description: |
                A mapping of product page URLs to their analysis results, including product metadata
                and meta tag recommendations for commerce optimization.
              type: object
              additionalProperties:
                type: object
                properties:
                  productMetadata:
                    type: object
                    description: |
                      Commerce-specific metadata scraped from the product page for autofixing.
                    properties:
                      sku:
                        description: |
                          Product SKU (Stock Keeping Unit) identifier.
                        type: string
                      thumbnail:
                        description: |
                          URL to the product thumbnail image.
                        type: string
                      catalogViewCode:
                        description: |
                          Catalog view code for multi-catalog e-commerce sites.
                        type: string
                      storeViewCode:
                        description: |
                          Store view code for multi-store e-commerce sites.
                        type: string
                  metaTagAnalysis:
                    type: object
                    description: |
                      Analysis of product-specific meta tags and SEO elements.
                    additionalProperties:
                      type: object
                      properties:
                        current:
                          description: |
                            Current value of the meta tag or element.
                          type: string
                        seoRecommendation:
                          description: |
                            SEO recommendation for this product meta element.
                          type: string
                        issue:
                          description: |
                            The issue detected in the product meta element.
                          type: string
                        issueDetails:
                          description: |
                            Detailed explanation of the issue for product pages.
                          type: string
                        seoImpact:
                          description: |
                            The impact of the detected issue on product discoverability.
                          type: string
                        autofixSuggestion:
                          description: |
                            Suggested value for automated fixing of the meta element.
                          type: string
            pdpOptimizationSummary:
              type: object
              description: |
                Summary of product detail page optimization findings.
              properties:
                totalPagesAnalyzed:
                  description: |
                    Total number of product pages analyzed.
                  type: integer
                criticalIssues:
                  description: |
                    Number of critical issues found across product pages.
                  type: integer
                mediumIssues:
                  description: |
                    Number of medium-priority issues found.
                  type: integer
                autofixableItems:
                  description: |
                    Number of issues that can be automatically fixed using scraped metadata.
                  type: integer
            finalUrl:
              description: |
                The final URL for the audited commerce site.
              type: string
    - type: object
      description: The result of LLM error pages audit.
      properties:
        success:
          type: boolean
          description: Whether the audit was successful
        totalErrors:
          type: integer
          description: Total number of LLM error requests found
        periodIdentifier:
          type: string
          description: The reporting period identifier
          example: 'w01-2025'
        summary:
          type: object
          description: Summary statistics of the audit
          properties:
            uniqueUrls:
              type: integer
              description: Number of unique URLs with errors
            uniqueUserAgents:
              type: integer
              description: Number of unique LLM user agents
        errorPages:
          type: array
          description: List of LLM error page details
          items:
            type: object
            properties:
              user_agent:
                type: string
                description: The LLM user agent string
              url:
                type: string
                description: The URL that returned an error
              status:
                type: integer
                description: HTTP status code
              total_requests:
                type: integer
                description: Number of requests for this URL/user agent combination
      additionalProperties: true
    - type: object
      description: The result of CWV audit
      properties:
        cwv:
          type: array
          description: A list of CWV metrics per device type
          items:
            type: object
            properties:
              type:
                type: string
                enum: ['group', 'url']
                description: "Specifies if the metric applies to a 'group' or an individual 'url'"
              name:
                type: string
                description: "Name of the group (only applicable when type is 'group')"
                example: 'Homepage Group'
              pattern:
                type: string
                description: "URL pattern for the group (only applicable when type is 'group')"
                example: 'https://www.aem.live/home*'
              url:
                description: "URL of the page (only applicable when type is 'url')"
                $ref: '#/URL'
              pageviews:
                type: integer
                description: 'Total pageviews for this group or URL'
                example: 4620
              organic:
                type: integer
                description: 'Total organic traffic for this group or URL'
                example: 2510
              metrics:
                type: array
                description: 'Array of performance metrics by device type'
                items:
                  $ref: './schemas.yaml#/CWVMetric'
    - type: object
      description: The result of summarization audit.
      properties:
        success:
          type: boolean
          description: Whether the audit was successful
        topPages:
          type: array
          description: A list of top pages
          items:
            type: string
    - type: object
      description: The result of FAQs audit
      properties:
        success:
          type: boolean
          description: Whether the audit was successful
        promptsByUrl:
          type: array
          description: A list of prompts grouped by URL and topic
          items:
            type: object
            properties:
              url:
                type: string
                description: The URL of the page
              topic:
                type: string
                description: The topic of the prompts
              prompts:
                type: array
                description: A list of prompts for this URL and topic
                items:
                  type: string
    - type: object
      description: The result of related-urls audit (brand presence prompts by region)
      properties:
        success:
          type: boolean
          description: Whether the audit was successful
        baseURL:
          type: string
          description: Base URL of the site (present when success is true)
        fanoutCount:
          type: integer
          description: Number of URLs to fan out for related-urls processing (present when success is true)
        promptRegions:
          type: array
          description: List of prompt and region pairs used for related-urls
          items:
            type: object
            properties:
              prompt:
                type: string
                description: The brand presence prompt
              region:
                type: string
                description: Region for the prompt (e.g. GLOBAL or region code)
AuditList:
  type: array
  items:
    $ref: './schemas.yaml#/Audit'
CWVMetric:
  type: object
  properties:
    deviceType:
      type: string
      description: 'The type of device'
      enum: ['mobile', 'desktop']
      example: 'mobile'
    pageviews:
      type: integer
      description: 'Total pageviews for this device type'
      example: 2120
    lcp:
      type: number
      format: float
      description: 'Largest Contentful Paint (LCP) metric'
      example: 2099.7
    lcpCount:
      type: integer
      description: 'The count of LCP samples'
      example: 9
    cls:
      type: number
      format: float
      description: 'Cumulative Layout Shift (CLS) metric'
      example: 0.02066
    clsCount:
      type: integer
      description: 'The count of CLS samples'
      example: 7
    inp:
      type: integer
      format: float
      description: 'Interaction to Next Paint (INP) metric'
      example: 12
    inpCount:
      type: integer
      description: 'The count of INP samples'
      example: 3
    ttfb:
      type: number
      format: float
      description: 'Time to First Byte (TTFB) metric'
      example: 520.45
    ttfbCount:
      type: integer
      description: 'The count of TTFB samples'
      example: 18
ExperimentationOpportunity:
  type: object
  readOnly: true
  properties:
    type:
      type: string
      description: Type of the experimentation opportunity
      example: 'generic'
    page:
      type: string
      description: The title of the webpage
      example: 'Retirement Calculator'
    screenshot:
      type: string
      format: url
      description: A URL pointing to the screenshot of the webpage.
      example: 'https://space.cat/screenshots/some-cool-page.png'
    trackedPageKPIName:
      type: string
      description: The name of KPI tracked.
      example: 'Bounce rate'
    trackedPageKPIValue:
      type: number
      description: The value of KPI tracked for this page.
      example: 0.80
    trackedKPISiteAverage:
      type: number
      description: The average value of KPI tracked across the site.
      example: 0.45
    pageviews:
      type: integer
      description: The total number of views this webpage has received
      example: 15000
    samples:
      type: integer
      description: The total number of samples we have for this webpage in RUM
      example: 150
    activeExperiments:
      type: string
      description: The number of active experiments on the webpage, or 'none' if there are no active experiments.
      examples:
        - 'None'
        - '2 active'
    metrics:
      type: array
      description: The metrics for the experimentation opportunity
      items:
        type: object
    recommendations:
      type: array
      description: The recommendations for the experimentation opportunity
      items:
        type: object
      example:
        - type: 'guidance'
          insight: 'The main CTAs ("Buy now", "Free trial") are not prominently visible above the fold for users coming from platforms like TikTok.'
          recommendation: 'Relocate one of the primary CTAs, such as "Buy now", to a more prominent position above the fold where it is immediately visible upon landing on the page.'
        - type: 'guidance'
          insight: 'The current design and layout of the page, while visually appealing, might be overwhelming for users coming from TikTok who prefer short and concise content.'
          recommendation: 'Simplify the page by reducing the amount of text and focusing on key features with visually engaging images or short videos, particularly near the top of the page.'
StructuredData:
  type: object
  readOnly: true
  properties:
    inspectionUrl:
      type: string
      description: The URL that was inspected
    indexStatusResult:
      type: object
      description: Result of the index status analysis.
      properties:
        verdict:
          $ref: '#/Verdict'
        lastCrawlTime:
          $ref: '#/DateTime'
    richResults:
      type: object
      description: Result of the Rich Results analysis. Absent if there are no rich results found.
      properties:
        verdict:
          $ref: '#/Verdict'
        detectedItemTypes:
          type: array
          description: A list of zero or more rich result types detected on this page.
          items:
            type: string
            example: 'Product snippets'
        detectedIssues:
          type: array
          description: A list of zero or more rich results errors detected on this page.
          items:
            type: object
            properties:
              richResultType:
                type: string
                description: Rich Results type detected on this page.
                example: 'Product snippets'
              items:
                type: array
                description: List of Rich Results items that have issues.
                items:
                  type: object
                  properties:
                    name:
                      type: string
                      description: The user-provided name of this item.
                      example: 'Product name'
                    issues:
                      type: array
                      description: A list of rich result issues found for this instance.
                      items:
                        type: object
                        properties:
                          issueMessage:
                            type: string
                            description: Rich Results issue type.
                            example: 'Missing field "image"'
                          severity:
                            type: string
                            description: Severity of this issue.
                            example: 'ERROR'

Verdict:
  type: string
  description: High-level verdict about whether the URL is indexed.
  enum:
    - 'VERDICT_UNSPECIFIED'
    - 'PASS'
    - 'PARTIAL'
    - 'FAIL'
    - 'NEUTRAL'
HoolihanHeaders:
  type: object
  properties:
    x-request-id:
      description: The request ID
      type: array
      items:
        $ref: '#/Id'
    miso-trace-id:
      description: The Miso trace ID
      type: array
      items:
        type: string
    com-adobe-hoolihan-source-partition:
      description: The source partition
      type: array
      items:
        type: string
    com-adobe-hoolihan-source-offset:
      description: The source offset
      type: array
      items:
        type: string
    com-adobe-hoolihan-publish-time:
      description: The time the event was published in milliseconds since the Unix Epoch
      type: array
      items:
        type: string
        example: '1705914000000'
    x-api-key:
      description: The API key of the client which published the original event
      type: array
      items:
        type: string
    com-adobe-hoolihan-publisher:
      description: The publisher of the original event
      type: array
      items:
        type: string
    com-adobe-hoolihan-source-topic:
      description: The topic that the original event was published to
      type: array
      items:
        type: string
    com-adobe-hoolihan-on-behalf-of:
      description: The client ID(s) that the event was forwarded on behalf of
      type: array
      items:
        type: string
    Content-Type:
      description: The content type of the event value
      type: array
      items:
        type: string
        example: 'application/json'
HoolihanEventValue:
  type: object
  required:
    - content
    - headers
  properties:
    content:
      description: The JSON payload of the event, encoded as a Base64 string
      type: string
    headers:
      description: Metadata headers included by Hoolihan on each event
      $ref: '#/HoolihanHeaders'
HoolihanEvent:
  type: object
  required:
    - id
    - topic
    - value
    - partition
    - offset
  properties:
    id:
      description: The Hoolihan ID of the event
      type: string
    topic:
      description: The name of the Hoolihan topic that the event was received on
      type: string
    value:
      description: Value of the event, which contains the message payload from the publishing system
      $ref: '#/HoolihanEventValue'
    partition:
      description: The partition index that the event was received on
      type: integer
    offset:
      description: The offset of the event within the partition
      type: integer
  example:
    id: 'b7fyJDj1bu5yrt82RxLX89a98a73KSqR4ptC5MRvlEoLshbgAB3emGKdjQleAMyINZcoAkM6cB7ma2aV'
    topic: 'example_fulfillment_topic'
    partition: 0
    offset: 1234
    value:
      content: |-
        ewogICAgImV4dGVybmFsX3JlcXVlc3RfaWQiOiAiMTIzNDUiLAogICAgInJlcXVlc3Rvcl9pZCI6ICIxMjM0NTY3ODkw
        QUJDREVGMTIzNDU2NzhAYWRvYmUuY29tIiwKICAgICJvd25lcl9pZCI6ICIxMjM0NTY3ODkwQUJDREVGMTIzNDU2NzhA
        QWRvYmVPcmciLAogICAgInJlcXVlc3RfdHlwZSI6ICJSRUdVTEFSIiwKICAgICJyZXF1ZXN0b3Jfc3lzdGVtIjogIkFB
        VUkiLAogICAgImZ1bGZpbGxtZW50X2lkIjogIjEyMzQ1Njc4OTBhYmNkZWYxMjM0NTY3ODkwYWJjZGVmMTIzNDU2Nzg5
        MGFiY2RlZjEyMzQ1Njc4OTBhYmNkZWYiLAogICAgImNyZWF0ZV9kYXRlIjogIjIwMjQtMDEtMjJUMDk6MjA6MDEuMTIz
        NDVaIiwKICAgICJpdGVtcyI6IFsKICAgICAgICB7CiAgICAgICAgICAgICJleHRlcm5hbF9pdGVtX2lkIjogIjEyMzQ1
        LWFiY2QtMTIzNC0xMjM0LTEyMzQ0MzIxIiwKICAgICAgICAgICAgInF1YW50aXR5IjogIlVOTElNSVRFRCIsCiAgICAg
        ICAgICAgICJvZmZlcl9pZCI6ICIxMjM0NTY3ODkwQUJDREVGMTIzNDU2Nzg5MEFCQ0RFRiIsCiAgICAgICAgICAgICJh
        Y2NlcHRlZF90ZXJtcyI6IHsKICAgICAgICAgICAgICAgICJjb250cmFjdF9pZCI6ICIxMjM0NTY3ODkwQUJDREVGMTIz
        NCIsCiAgICAgICAgICAgICAgICAiYWNjZXB0ZWRfYWdyZWVtZW50IjogIklOSVRJQUwiCiAgICAgICAgICAgIH0sCiAg
        ICAgICAgICAgICJmdWxmaWxsYWJsZV9pdGVtc19jb21wbGV0ZWQiOiBbCiAgICAgICAgICAgICAgICB7CiAgICAgICAg
        ICAgICAgICAgICAgImlkIjogIjEyM2U0NTY3LWU4OWItMTJkMy1hNDU2LTQyNjYxNDE3NDAwMCIsCiAgICAgICAgICAg
        ICAgICAgICAgImNvZGUiOiAiZHhfZXhhbXBsZV9zb2x1dGlvbiIsCiAgICAgICAgICAgICAgICAgICAgImZ1bGZpbGxt
        ZW50X2RldGFpbHMiOiB7CiAgICAgICAgICAgICAgICAgICAgICAgICJmdWxmaWxsYWJsZV9lbnRpdHlfcmVzb3VyY2Vf
        bG9jYXRvciI6ICJodHRwczovL2V4YW1wbGUuY29tLzEyMzQ1Njc4OTBBQkNERUYxMjM0NTY3OEBBZG9iZU9yZyIsCiAg
        ICAgICAgICAgICAgICAgICAgICAgICJmdWxmaWxsYWJsZV9lbnRpdHlfcmVzb3VyY2VfbmFtZSI6ICJFeGFtcGxlIFNv
        bHV0aW9uIgogICAgICAgICAgICAgICAgICAgIH0KICAgICAgICAgICAgICAgIH0KICAgICAgICAgICAgXQogICAgICAg
        IH0KICAgIF0KfQ==
      headers:
        x-request-id:
          - '123e4567-e89b-12d3-a456-426614174000'
        miso-trace-id:
          - '12345678abcdef12:12345678abcdef12:12345678abcdef12:1'
        com-adobe-hoolihan-source-partition:
          - '0'
        com-adobe-hoolihan-source-offset:
          - '1234'
        com-adobe-hoolihan-publish-time:
          - '1705915000000'
        x-api-key:
          - 'example_publisher_client_id'
        com-adobe-hoolihan-publisher:
          - 'example_publisher_client_id'
        com-adobe-hoolihan-source-topic:
          - 'example_source_topic'
        com-adobe-hoolihan-on-behalf-of:
          - 'example_other_client_id'
        Content-Type:
          - 'application/json'
HoolihanEvents:
  type: array
  items:
    $ref: '#/HoolihanEvent'
ProcessingStatus:
  type: string
  enum:
    - 'accepted'
    - 'rejected'
  example: 'accepted'
FulfillmentProcessingResults:
  type: array
  items:
    type: object
    required:
      - status
    properties:
      status:
        description: The acceptance status (whether or not the event was accepted for processing)
        $ref: '#/ProcessingStatus'
      requestId:
        description: The request ID
        $ref: '#/Id'
  example:
    - status: 'accepted'
      requestId: '123e4567-e89b-12d3-a456-426614174000'
    - status: 'rejected'
CDNXForwardedHostAlert:
  type: object
  additionalProperties: true
  properties:
    forwardedHost:
      description: value of x-forwarded-host header in the CDN log which trggered the domain discovery alert
      type: string
      example: 'blog.adobe.com, main--blog--adobecom.hlx.live, main--blog--adobecom.hlx.live, main--blog--adobecom.hlx-fastly.page'
RUMDomainDiscoveryAlert:
  type: object
  additionalProperties: true
  properties:
    url:
      description: URL of the page which triggered the domain discovery alert
      $ref: '#/URL'
    domain:
      description: Domain of the page which triggered the domain discovery alert
      $ref: '#/Domain'
SlackInviteToChannelByUserIdRequest:
  type: object
  required:
    - imsOrgId
    - imsUserAccessToken
  properties:
    imsOrgId:
      description: The ID of the Adobe IMS organization
      $ref: '#/ImsOrganizationId'
    imsUserAccessToken:
      description: The IMS access token of the user to invite to the Slack channel
      $ref: '#/ImsUserAccessToken'
Configuration:
  type: object
  properties:
    version:
      type: string
      readOnly: true
      description: Internal version of the configuration, managed and incremented by the system. Not exposed for external control via the API.
    jobs:
      type: array
      items:
        $ref: '#/Job'
      description: A list of job configurations, detailing job type, its group, and execution interval.
    queues:
      type: object
      properties:
        audits:
          type: string
          format: url
          description: The SQS queue name for audit jobs
        imports:
          type: string
          format: url
          description: The SQS queue name for import jobs
        reports:
          type: string
          format: url
          description: The SQS queue name for report jobs
Job:
  type: object
  properties:
    group:
      type: string
      description: The group or category to which the job belongs, helping in organizing jobs by their functional area.
    interval:
      type: string
      description: Specifies how often the job should run, e.g., 'daily'. This is part of job scheduling information.
    type:
      type: string
      description: The job type, indicating the specific action or task that the job performs, such as 'rum-to-aa' indicating a data import job from RUM to AA.
AnalyticsSiteIntegration:
  type: object
  additionalProperties: true
  required:
    - siteId
    - reporting
    - dataCollection
    - dataStore
    - dataMapping
  properties:
    siteId:
      description: The site ID in uuid format
      $ref: '#/Id'
    reporting:
      description: The reporting details
      type: object
      required:
        - link
      additionalProperties: true
      properties:
        link:
          description: |
            The link to the report in the reporting tool.
            For Adobe Analytics and Customer Journey Analytics, the link to the Analysis Workspace report.
          $ref: '#/URL'
        timezone:
          description: The timezone for the data in the report
          type: string
    dataCollection:
      description: The configuration for the data collection to embed on the site.
      type: object
      required:
        - type
        - environments
      properties:
        type:
          description: The type of the data collection
          type: string
          enum:
            - 'adobe-tags'
            - 'aep-websdk'
        environments:
          description: |
            The environments for the data collection script.
            At least the script for the production environment is required.
            The keys represent the environments (development, staging, production).
            The values represent the URL or ID of the data collection script.
            For Adobe Analytics and Customer Journey Analytics, the values are either
            URL for the Adobe Launch script or the datastream ID.
          type: object
          additionalProperties:
            type: string
          required:
            - production
          properties:
            production:
              description: The URL or ID of the production data collection script
              type: string
    dataStore:
      description: The data store details
      type: object
      required:
        - id
        - type
      additionalProperties: true
      properties:
        id:
          description: The ID of the data store
          type: string
        type:
          description: The type of the data store
          type: string
          enum:
            - 'adobe-analytics'
            - 'aep'
    dataSchema:
      description: The data schema details
      type: object
      required:
        - id
      additionalProperties: true
      properties:
        id:
          description: The ID of the data schema
          type: string
    dataMapping:
      description: The data mapping details
      type: object
      required:
        - type
        - mappings
      properties:
        type:
          description: The type of the data mapping
          type: string
          enum:
            - 'adobe-analytics'
            - 'xdm'
        mappings:
          description: |
            The data mapping details. The keys represent human-friendly naming of metrics and dimensions captured by the
            instrumentation of the site. The values represent the corresponding metric and dimension names in the data store.
            For Adobe Analytics, the values are either evars or events.
            For XDM, the values are the paths in the data schema.
          type: object
          additionalProperties:
            type: string
  examples:
    - analytics-site-integration-aa-tags:
        $ref: './examples.yaml#/analytics-site-integration-aa-tags'
    - analytics-site-integration-aa-aep-websdk:
        $ref: './examples.yaml#/analytics-site-integration-aa-aep-websdk'
    - analytics-site-integration-cja-tags:
        $ref: './examples.yaml#/analytics-site-integration-cja-tags'
    - analytics-site-integration-cja-websdk:
        $ref: './examples.yaml#/analytics-site-integration-cja-websdk'
SiteTopPage:
  type: object
  required:
    - siteId
    - url
    - traffic
    - source
    - geo
    - importedAt
  properties:
    siteId:
      description: The site ID in uuid format
      $ref: '#/Id'
    url:
      description: The URL of the top page
      $ref: '#/URL'
    traffic:
      description: The traffic of the top page
      type: integer
    source:
      description: The source of the top page listing
      type: string
    geo:
      description: The geo of the top page listing, or 'global' if not specific to a geo
      type: string
    importedAt:
      description: The date and time when the top page was imported
      $ref: '#/DateTime'
  example:
    siteId: 'a1b2c3d4-e5f6-7g8h-9i0j-k11l12m13n14'
    url: 'https://example-site.com/foo/bar'
    traffic: 360420000
    source: 'seo'
    geo: 'au'
    importedAt: '2024-04-29T15:14:33.653Z'
SiteTopPageList:
  type: array
  items:
    $ref: './schemas.yaml#/SiteTopPage'
AuditUrl:
  type: object
  required:
    - siteId
    - url
    - byCustomer
    - audits
    - createdAt
    - updatedAt
    - createdBy
    - updatedBy
  description: |
    AuditUrl entity representing a URL to be audited.
    Primary key is composite: siteId + url (no separate id field).
  properties:
    siteId:
      description: Parent site identifier
      $ref: '#/Id'
    url:
      description: URL after canonicalization
      $ref: '#/URL'
    byCustomer:
      description: Whether the URL was added by a customer (true) or system (false)
      type: boolean
      default: true
      example: true
    audits:
      description: Enabled audit types
      type: array
      uniqueItems: true
      items:
        type: string
      example: ['accessibility', 'broken-backlinks']
    createdAt:
      description: ISO 8601 timestamp when created
      $ref: '#/DateTime'
    updatedAt:
      description: ISO 8601 timestamp when last modified
      $ref: '#/DateTime'
    createdBy:
      description: User/service who created this URL
      type: string
      example: user-alice
    updatedBy:
      description: Last user/service to modify this URL
      type: string
      example: user-bob
  example:
    siteId: 'a1b2c3d4-e5f6-7g8h-9i0j-k11l12m13n14'
    url: 'https://example.com/documents/report.pdf'
    byCustomer: true
    audits: ['accessibility', 'broken-backlinks']
    createdAt: '2025-10-10T12:00:00Z'
    updatedAt: '2025-10-10T15:30:00Z'
    createdBy: 'user-alice'
    updatedBy: 'user-bob'
AuditUrlInput:
  type: object
  required:
    - url
    - audits
  properties:
    url:
      description: The URL to add
      $ref: '#/URL'
    byCustomer:
      description: Whether the URL was added by a customer (true) or system (false). Defaults to true.
      type: boolean
      default: true
    audits:
      description: Enabled audit types
      type: array
      uniqueItems: true
      items:
        type: string
      example: ['accessibility', 'broken-backlinks']
  example:
    url: 'https://example.com/page1.html'
    byCustomer: true
    audits: ['accessibility', 'broken-backlinks']
AuditUrlUpdate:
  type: object
  required:
    - url
    - audits
  properties:
    url:
      description: The URL to update
      $ref: '#/URL'
    audits:
      description: Enabled audit types (overrides existing)
      type: array
      uniqueItems: true
      items:
        type: string
      example: ['accessibility']
  example:
    url: 'https://example.com/page1.html'
    audits: ['accessibility']
AuditUrlListResponse:
  type: object
  required:
    - items
    - pagination
  properties:
    items:
      type: array
      items:
        $ref: './schemas.yaml#/AuditUrl'
    pagination:
      type: object
      required:
        - limit
        - hasMore
      properties:
        limit:
          type: integer
          description: Number of items per page
        cursor:
          type: string
          description: Pagination cursor for next page (null when no more data)
        hasMore:
          type: boolean
          description: Whether more items are available
  example:
    items:
      - siteId: 'a1b2c3d4-e5f6-7g8h-9i0j-k11l12m13n14'
        url: 'https://example.com/page1.html'
        byCustomer: true
        audits: ['accessibility']
        createdAt: '2025-10-10T12:00:00Z'
        updatedAt: '2025-10-10T15:30:00Z'
        createdBy: 'user-alice'
        updatedBy: 'user-bob'
    pagination:
      limit: 100
      cursor: 'eyJsYXN0S2V5Ijp7InNpdGVJZCI6ImV4YW1wbGUtY29tIn19'
      hasMore: true
AuditUrlBulkResponse:
  type: object
  required:
    - metadata
    - failures
    - items
  properties:
    metadata:
      type: object
      required:
        - total
        - success
        - failure
      properties:
        total:
          type: integer
          description: Total number of URLs in the request
        success:
          type: integer
          description: Number of successfully processed URLs
        failure:
          type: integer
          description: Number of failed URLs
    failures:
      type: array
      items:
        type: object
        required:
          - url
          - reason
        properties:
          url:
            type: string
          reason:
            type: string
      description: Per-item error information
    items:
      type: array
      items:
        $ref: './schemas.yaml#/AuditUrl'
      description: Successfully processed URLs
  example:
    metadata:
      total: 3
      success: 2
      failure: 1
    failures:
      - url: 'https://example.com/invalid'
        reason: 'Invalid URL format'
    items:
      - siteId: 'a1b2c3d4-e5f6-7g8h-9i0j-k11l12m13n14'
        url: 'https://example.com/page1.html'
        byCustomer: true
        audits: ['accessibility']
        createdAt: '2025-10-10T12:00:00Z'
        updatedAt: '2025-10-10T15:30:00Z'
        createdBy: 'user-alice'
        updatedBy: 'user-bob'
AuditUrlDeleteResponse:
  type: object
  required:
    - metadata
    - failures
  properties:
    metadata:
      type: object
      required:
        - total
        - success
        - failure
      properties:
        total:
          type: integer
          description: Total number of URLs in the request
        success:
          type: integer
          description: Number of successfully deleted URLs
        failure:
          type: integer
          description: Number of failed deletions
    failures:
      type: array
      items:
        type: object
        required:
          - url
          - reason
        properties:
          url:
            type: string
          reason:
            type: string
      description: Per-item error information
  example:
    metadata:
      total: 3
      success: 2
      failure: 1
    failures:
      - url: 'https://example.com/from-sitemap'
        reason: 'Can only delete customer-added URLs (byCustomer: true)'
SiteExperimentVariant:
  type: object
  properties:
    name:
      description: The name of the variant
      type: string
    label:
      description: The label of the variant
      type: string
    split:
      description: The split allocation of the traffic to the variant
      type: number
    url:
      description: The url of the variant
      $ref: '#/URL'
    views:
      description: The number of views for the variant
      type: integer
    samples:
      description: The number of data points (samples) used for this variant
      type: integer
    interactionsCount:
      description: The interactions count for the variant
      type: integer
    p_value:
      description: The p-value of the variant for the configured metric or clicks
      type: number
    power:
      description: The power of the variant for the configured metric or clicks
      type: number
    statsig:
      description: The statistical significance of the variant based on the configured metric or clicks
      type: boolean
    metrics:
      description: The metrics for the variant
      type: array
      items:
        type: object
        properties:
          selector:
            description: The css selector of the element on which the interaction was performed
            type: string
          value:
            description: The value of the metric on the selector
            type: number
          samples:
            description: The number of data points (samples) used for calculating this metric object
            type: integer
          type:
            description: The type of the metric
            type: string
            enum:
              - 'click'
              - 'convert'
              - 'formsubmit'
  example:
    name: 'challenger-1'
    label: 'Challenger 1'
    split: 0.5
    url: 'https://example-site.com/foo/bar'
    views: 1000
    samples: 10
    interactionsCount: 200
    p_value: 0.04
    power: 97.6
    statsig: true
    metrics:
      - selector: '.add-to-cart'
        value: 300
        samples: 3
        type: 'click'
SiteExperiment:
  type: object
  properties:
    siteId:
      description: The site ID in uuid format
      $ref: '#/Id'
    experimentId:
      description: The ID of the experiment
      type: string
    name:
      description: The name of the experiment
      type: string
    url:
      description: The URL of the experiment
      $ref: '#/URL'
    status:
      description: The status of the experiment
      type: string
      enum:
        - 'ACTIVE'
        - 'COMPLETE'
        - 'INACTIVE'
    type:
      description: The type of the experiment
      type: string
      enum:
        - 'FULL'
        - 'AB'
        - 'MAB'
    startDate:
      description: The start date and time of the experiment
      $ref: '#/DateTime'
    endDate:
      description: The end date and time of the experiment
      $ref: '#/DateTime'
    variants:
      description: The variants of the experiment
      type: array
      items:
        $ref: './schemas.yaml#/SiteExperimentVariant'
    updatedAt:
      description: The date and time when the experiment was last updated
      $ref: '#/DateTime'
    updatedBy:
      description: The user/entity who last updated the experiment
      type: string
    conversionEventName:
      description: The name of the conversion event
      type: string
    conversionEventValue:
      description: The name of conversion event value
      type: string
  example:
    siteId: 'a1b2c3d4-e5f6-7g8h-9i0j-k11l12m13n14'
    experimentId: '1012-home-page-optimization'
    name: '1012 Home Page Optimization'
    url: 'https://example-site.com/foo/bar'
    type: 'AB'
    status: 'ACTIVE'
    startDate: '2024-04-29T15:14:33.653Z'
    endDate: '2024-05-29T15:14:33.653Z'
    variants:
      - name: 'challenger-1'
        label: 'Challenger 1'
        split: 0.5
        url: 'https://example-site.com/foo/bar'
        views: 1000
        samples: 10
        interactionsCount: 200
        p_value: 0.04
        power: 97.6
        statsig: true
        metrics:
          - selector: '.add-to-cart'
            value: 300
            samples: 3
            type: 'click'
    updatedAt: '2024-05-31T15:14:33.653Z'
    updatedBy: 'admin'
    conversionEventName: 'click'
    conversionEventValue: '.add-to-cart'
SiteExperimentList:
  type: array
  items:
    $ref: './schemas.yaml#/SiteExperiment'
SiteMetric:
  type: object
  required:
    - siteId
    - source
    - name
    - value
    - time
  properties:
    siteId:
      description: The site ID in uuid format
      $ref: '#/Id'
    source:
      description: The source for retrieving the metric value
      type: string
    name:
      description: The name of the metric
      type: string
    value:
      description: The value of the metric
      type: integer
    time:
      description: The date and time when the metric was recorded
      $ref: '#/DateTime'
  example:
    siteId: 'a1b2c3d4-e5f6-7g8h-9i0j-k11l12m13n14'
    source: 'seo'
    name: 'organic-traffic'
    value: 37900
    time: '2024-04-29T00:00:00.000Z'
PageOrganicKeywords:
  type: object
  required:
    - siteId
    - source
    - name
    - time
    - url
    - keyword
    - traffic
  properties:
    siteId:
      description: The site ID in uuid format
      $ref: '#/Id'
    source:
      description: The source for retrieving the metric value
      type: string
    name:
      description: The name of the metric
      type: string
    time:
      description: The date and time when the metric was recorded
      $ref: '#/DateTime'
    url:
      description: The URL of the page
      $ref: '#/URL'
    keyword:
      description: The keyword
      type: string
    traffic:
      description: The traffic of the keyword
      type: integer
    volume:
      description: The search volume of the keyword
      type: integer
    bestPosition:
      description: The best position of the keyword
      type: integer
    cpc:
      description: The cost per click of the keyword
      type: integer
    isBranded:
      description: Whether the keyword is branded
      type: boolean
  example:
    siteId: 'a1b2c3d4-e5f6-7g8h-9i0j-k11l12m13n14'
    source: 'seo'
    name: 'organic-keywords'
    time: '2024-04-29T00:00:00.000Z'
    url: 'https://example.com/foo/bar'
    keyword: 'foo bar example'
    traffic: 2355
    volume: 2400
    bestPosition: 1
    cpc: 89
    isBranded: true
SiteMetricList:
  type: array
  items:
    $ref: './schemas.yaml#/SiteMetric'
PageMetricList:
  type: array
  items:
    oneOf:
      - $ref: './schemas.yaml#/PageOrganicKeywords'
DocImportData:
  title: 'Doc Import'
  description: 'There are no data properties available for doc based imports.'
  properties: {}
DAImportData:
  title: 'DA Import'
  description: 'There are no data properties available for DA based imports.'
  properties: {}
XWalkImportData:
  title: 'Xwalk Import'
  properties:
    siteName:
      type: string
    assetFolder:
      type: string
  required:
    - siteName
    - assetFolder

BrowserOptions:
  description: Common browser options for page loading operations
  properties:
    pageLoadTimeout:
      description: The time in milliseconds to wait for the page to load
      type: integer
    enableJavascript:
      description: Whether to enable JavaScript on the page
      type: boolean
      default: true
  example:
    pageLoadTimeout: 200
    enableJavascript: true

ImportOptionsBase:
  description: Base options for import operations, extends BrowserOptions with import-specific features
  allOf:
    - $ref: '#/BrowserOptions'
    - type: object
      properties: {}
  example:
    pageLoadTimeout: 200
    enableJavascript: true

ImportOptions:
  allOf: #/ImportOptionsBase
    - $ref: '#/ImportOptionsBase'
  properties:
    type:
      enum: ['doc', 'xwalk', 'da']
      description: The type of import job. Valid options are 'doc', 'da' or 'xwalk'.
      type: string
      default: 'doc'
    data:
      description: Optional data to pass to the import job.
      type: object
      oneOf:
        - $ref: '#/DocImportData'
        - $ref: '#/XWalkImportData'
        - $ref: '#/DAImportData'

ImportJobRequest:
  type: object
  required:
    - urls
  properties:
    urls:
      description: The URLs to import
      type: array
      items:
        $ref: '#/URL'
    options:
      description: Optional configuration params, defined as a JSON object
      $ref: '#/ImportOptions'
    importScript:
      description: Optional import.js mapping file
      type: string
      format: binary
    customHeaders:
      description: Optional custom headers to send with each HTTP request
      type: object
  example:
    urls:
      - 'https://example.com/en/page1'
      - 'https://example.com/fr/page2'
    options:
      enableJavascript: true
    importScript: (binary data)
    customHeaders:
      example-header-name: 'example-header-value'
ImportJobStatus:
  type: object
  properties:
    id:
      description: The ID of the import job
      $ref: '#/Id'
    status:
      description: The status of the import job
      type: string
      enum:
        - 'RUNNING'
        - 'COMPLETE'
        - 'FAILED'
    startTime:
      description: The date and time when the import job started.
      $ref: '#/DateTime'
    endTime:
      description: The date and time when the import job ended, if finished.
      $ref: '#/DateTime'
    urlCount:
      description: The total number of URLs in the job.
      type: integer
    successCount:
      description: The number of URLs successfully imported.
      type: integer
    failedCount:
      description: The number of URLs that failed to import.
      type: integer
    redirectCount:
      description: The number of URLs that were redirected.
      type: integer
  example:
    id: '12d6ac8e-d5e4-4788-90eb-b69e10e745fd'
    status: 'RUNNING'
    startTime: '2024-01-19T14:20:30Z'
    urlCount: 25
    successCount: 15
    failedCount: 0
ImportJobProgress:
  type: object
  properties:
    pending:
      type: integer
      description: The number of pending url jobs still to process.
    redirect:
      type: integer
      description: The number of urls that resulted in a redirect.
    running:
      type: integer
      description: The number of url jobs that are running.
    completed:
      type: integer
      description: The number of url jobs that have completed.
    failed:
      type: integer
      description: The number of url jobs that have failed.
  example:
    pending: 0
    redirect: 0
    running: 0
    completed: 1
    failed: 0
ImportJobArchive:
  type: object
  properties:
    jobId:
      description: The ID of the import job
      $ref: '#/Id'
    downloadUrl:
      description: The pre-signed URL to download the archive of the import job
      $ref: '#/URL'
  example:
    jobId: '12d6ac8e-d5e4-4788-90eb-b69e10e745fd'
    downloadUrl: 'https://spacecat-example-bucket.s3.example-region.amazonaws.com/import/12d6ac8e-d5e4-4788-90eb-b69e10e745fd/import-result.zip?X-Amz-Algorithm=AWS...'
ScrapeOptions:
  description: Options specific to scraping operations, extends BrowserOptions with scraping-specific features
  allOf:
    - $ref: '#/BrowserOptions'
    - type: object
      properties:
        hideConsentBanners:
          description: Whether to hide consent banners on the page
          type: boolean
          default: false
        waitForSelector:
          description: The selector to wait for before considering the page loaded
          type: string
          pattern: '^[.#]?[a-zA-Z][a-zA-Z0-9_-]*(\.[a-zA-Z][a-zA-Z0-9_-]*)*$'
        sectionLoadWaitTime:
          description: The time in milliseconds to wait for the section to load
          type: integer
          minimum: 0
          maximum: 30000
          default: 2000
        screenshotTypes:
          description: The types of screenshots to take
          type: array
          minItems: 1
          maxItems: 5
          items:
            type: string
            enum:
              - 'fullPage'
              - 'thumbnail'
              - 'section'
              - 'block'
              - 'scroll'
        rejectRedirects:
          description: Whether to reject redirects
          type: boolean
          default: true
  example:
    pageLoadTimeout: 200
    enableJavascript: true
    hideConsentBanners: true
ScrapeRequest:
  type: object
  required:
    - urls
    - processingType
  properties:
    processingType:
      description: The name of the scrape handler to use.
      type: string
      default: 'default'
    maxScrapeAge:
      description: The maximum age of a scrape in hours. Providing the value of 0 will result in forcing the scrape (disabling this caching feature)
      type: integer
      minimum: 0
      default: 24
    options:
      description: Optional configuration params, defined as a JSON object
      $ref: '#/ScrapeOptions'
    customHeaders:
      description: Optional custom headers to send with each HTTP request
      type: object
    urls:
      description: The URLs to scrape. The URLs must be unique.
      type: array
      items:
        type: string
        format: url
      example:
        - 'https://example.com/en/page1'
        - 'https://example.com/fr/page2'

ScrapeResponse:
  type: object
  properties:
    id:
      description: The ID of the scrape job
      $ref: '#/Id'
    baseURL:
      description: The base URL of the scrape job
      type: string
      format: uri
    processingType:
      description: The scrape handler to use for the scrape job
      type: string
    startedAt:
      description: The date and time when the scrape job started
      type: string
      format: date-time
    endedAt:
      description: The date and time when the scrape job ended, if finished
      type: string
      format: date-time
    duration:
      description: The duration of the scrape job in milliseconds
      type: integer
      format: int32
    status:
      description: The status of the scrape job
      type: string
      enum:
        - 'IN_PROGRESS'
        - 'COMPLETE'
        - 'FAILED'
    urlCount:
      description: The total number of URLs in the job
      type: integer
    successCount:
      description: The number of URLs successfully scraped
      type: integer
    failedCount:
      description: The number of URLs that failed to scrape
      type: integer

  example:
    id: '12d6ac8e-d5e4-4788-90eb-b69e10e745fd'
    baseURL: 'https://myBaseUrl.com'
    processingType: 'default'
    options:
      enableJavascript: true
      hideConsentBanners: true
    startedAt: '2024-01-19T14:20:30Z'
    endedAt: '2024-01-19T14:20:30Z'
    duration: 33771,
    status: 'COMPLETE'
    urlCount: 10
    successCount: 9
    failedCount: 1

ScrapeJobUrlResultsResponse:
  type: object
  properties:
    jobId:
      description: The ID of the scrape job
      $ref: '#/Id'
    results:
      description: The results of the scrape job
      type: array
      items:
        $ref: '#/ScrapeResult'

ScrapeResult:
  type: object
  properties:
    url:
      description: The URL of the scraped page
      $ref: '#/URL'
    status:
      description: The status of the scrape job
      type: string
      enum:
        - 'COMPLETE'
        - 'FAILED'
        - 'PENDING'
    reason:
      description: The error message if the scrape failed
      type: string
    path:
      description: The s3 path of the scraped page if the scrape was successful
      type: string
  example:
    url: 'https://example.com/en/page1'
    status: 'COMPLETE'
    path: 'scrapes/12d6ac8e-d5e4-4788-90eb-b69e10e74abc/page1.html'

ScrapeJobsByDateRangeResponse:
  type: array
  items:
    $ref: '#/CreateAsyncJobAcceptedResponse'

ScrapeJobsByBaseURLResponse:
  type: array
  items:
    $ref: '#/CreateAsyncJobAcceptedResponse'

ScrapeUrl:
  type: object
  properties:
    url:
      description: The URL that was scraped
      type: string
    processingType:
      description: The processing type/handler used for this scrape
      type: string
    status:
      description: The status of the scrape
      type: string
      enum:
        - 'COMPLETE'
        - 'FAILED'
        - 'PENDING'
    path:
      description: The S3 path of the scraped content if the scrape was successful
      type: string
    createdAt:
      description: The timestamp when the scrape was created
      $ref: '#/DateTime'
  example:
    url: 'https://example.com/page1'
    processingType: 'form'
    status: 'COMPLETE'
    path: 'scrapes/12d6ac8e-d5e4-4788-90eb-b69e10e74abc/page1.html'
    createdAt: '2024-01-01T10:00:00.000Z'

ScrapeUrlsByProcessingTypeResponse:
  type: array
  items:
    $ref: '#/ScrapeUrl'

BrokenBacklink:
  type: object
  properties:
    url_to:
      description: The URL of the broken link.
      $ref: '#/URL'
    title:
      description: The title of the page referring to the broken link.
      type: string
    url_from:
      description: The URL of the page referring to the broken link.
      $ref: '#/URL'
    traffic_domain:
      description: The referring domain's estimated monthly organic traffic from search.
      type: number

BrokenInternalLink:
  type: object
  properties:
    urlTo:
      description: The URL of the broken internal link.
      $ref: '#/URL'
    title:
      description: The title of the internal page referring to the broken internal link.
      type: string
    urlFrom:
      description: The URL of the internal page referring to the broken link.
      $ref: '#/URL'
    trafficDomain:
      description: The referring page's estimated monthly organic traffic.
      type: number
    priority:
      description: The priority of the broken internal link
      $ref: '#/Priority'
ApiKeyRequest:
  type: object
  required:
    - name
    - features
    - domains
  properties:
    name:
      description: The name of the API key
      type: string
    features:
      description: The features the API key is for
      type: array
      items:
        type: string
    domains:
      description: The domains the API key is allowed to access
      type: array
      items:
        type: string
        $ref: '#/Domain'
  example:
    name: 'Example API Key'
    features: ['imports']
    domains:
      - 'example.com'
ApiKeyMetadataResponse:
  type: object
  properties:
    id:
      description: The ID of the API key
      $ref: '#/Id'
    name:
      description: The name of the API key
      type: string
    scopes:
      description: The scopes of the API key
      type: array
      items:
        type: object
        properties:
          name:
            description: The name of the scope
            type: string
            $ref: '#/ScopeName'
          domains:
            description: The domains the scope is allowed to access
            type: array
            items:
              $ref: '#/Domain'
    createdAt:
      description: The date and time when the API key was created
      $ref: '#/DateTime'
    expiresAt:
      description: The date and time when the API key expires
      $ref: '#/DateTime'
    deletedAt:
      description: The date and time when the API key was deleted
      $ref: '#/DateTime'
    revokedAt:
      description: The date and time when the API key was revoked
      $ref: '#/DateTime'
ApiKeyResponse:
  allOf:
    - $ref: '#/ApiKeyMetadataResponse'
    - type: object
      properties:
        apiKey:
          description: The API key
          type: string
OpportunityStatus:
  description: Status of an opportunity
  type: string
  enum:
    - 'NEW'
    - 'IN_PROGRESS'
    - 'IGNORED'
    - 'RESOLVED'
  example: 'IN_PROGRESS'
OpportunityType:
  description: Type of opportunity
  type: string
  enum:
    - 'broken-backlinks'
    - 'broken-internal-links'
    - 'info-gain'
  example: 'broken-backlinks'
OpportunityOrigin:
  description: |
    Origin of opportunity.
    - AUTOMATION: generated by automation
    - ESS_OPS: generated manually by Experience Success Engineers
    - AI: generated by AI
  type: string
  enum:
    - 'AUTOMATION'
    - 'ESS_OPS'
    - 'AI'
  example: 'ESS_OPS'
Opportunity:
  type: object
  properties:
    id:
      description: UUID of this opportunity
      $ref: '#/Id'
    siteId:
      description: UUID of the site this opportunity is for
      $ref: '#/Id'
    auditId:
      description: UUID of the audit result that triggered this opportunity
      $ref: '#/Id'
    runbook:
      description: URL to the runbook for this opportunity
      type: string
      format: url
      example: 'https://example.com/runbook/broken-backlinks'
    type:
      $ref: '#/OpportunityType'
    data:
      description: Optional map of type-specific data relevant to this opportunity
      type: object
      additionalProperties: true
      oneOf:
        - $ref: '#/BrokenBacklinksOpportunityData'
        - $ref: '#/BrokenInternalLinksOpportunityData'
        - $ref: '#/CWVOpportunityData'
    origin:
      $ref: '#/OpportunityOrigin'
    title:
      description: Title of this opportunity
      type: string
      example: 'Authoritative domains are linking to invalid SecurBank URLs. This could impact your SEO.'
    description:
      description: Description of this opportunity
      type: string
      example: 'Provide the correct target URL that each of the broken backlinks should be redirected to.'
    status:
      description: Status of this opportunity
      $ref: '#/OpportunityStatus'
    guidance:
      description: Guidance text specific to this opportunity
      type: object
      additionalProperties: true
      oneOf:
        - $ref: '#/BrokenBacklinksGuidance'
        - $ref: '#/BrokenInternalLinksGuidance'
        - $ref: '#/CWVGuidance'
    tags:
      type: array
      items:
        type: string
      description: Optional list of tags
      example:
        - 'Traffic acquisition'
    createdAt:
      description: UTC timestamp of when the opportunity was created
      $ref: '#/DateTime'
    updatedAt:
      description: UTC timestamp of when the opportunity was last updated
      $ref: '#/DateTime'
    lastAuditedAt:
      description: UTC timestamp of when the opportunity was last audited
      $ref: '#/DateTime'
  required:
    - id
    - siteId
    - auditId
    - runbook
    - type
    - origin
    - title
    - status
    - createdAt
    - updatedAt
OpportunityList:
  type: array
  items:
    $ref: '#/Opportunity'
OpportunityCreate:
  type: object
  properties:
    auditId:
      description: UUID of the audit result that triggered this opportunity
      readOnly: false
      $ref: '#/Id'
    runbook:
      description: URL to the runbook for this opportunity
      type: string
      format: url
      example: 'https://example.com/runbook/broken-backlinks'
    type:
      $ref: '#/OpportunityType'
    data:
      description: Optional map of type-specific data relevant to this opportunity
      type: object
      additionalProperties: true
      oneOf:
        - $ref: '#/BrokenBacklinksOpportunityData'
        - $ref: '#/BrokenInternalLinksOpportunityData'
    origin:
      description: Origin of opportunity
      $ref: '#/OpportunityOrigin'
    title:
      description: Title of this opportunity
      type: string
      example: 'Authoritative domains are linking to invalid SecurBank URLs. This could impact your SEO.'
    description:
      description: Description of this opportunity
      type: string
      example: 'Provide the correct target URL that each of the broken backlinks should be redirected to.'
    guidance:
      description: Guidance text specific to this opportunity
      type: object
      additionalProperties: true
      oneOf:
        - $ref: '#/BrokenBacklinksGuidance'
        - $ref: '#/BrokenInternalLinksGuidance'
    tags:
      type: array
      items:
        type: string
      description: Optional list of tags
      example:
        - 'Traffic acquisition'
  required:
    - auditId
    - runbook
    - type
    - origin
    - title
OpportunityUpdate:
  type: object
  properties:
    runbook:
      description: URL to the runbook for this opportunity
      type: string
      format: url
      example: 'https://example.com/runbook/broken-backlinks'
    data:
      description: Optional map of type-specific data relevant to this opportunity
      type: object
      additionalProperties: true
      oneOf:
        - $ref: '#/BrokenBacklinksOpportunityData'
        - $ref: '#/BrokenInternalLinksOpportunityData'
    title:
      description: Title of this opportunity
      type: string
      example: 'Authoritative domains are linking to invalid SecurBank URLs. This could impact your SEO.'
    description:
      description: Description of this opportunity
      type: string
      example: 'Provide the correct target URL that each of the broken backlinks should be redirected to.'
    status:
      description: Status of this opportunity
      $ref: '#/OpportunityStatus'
    guidance:
      description: Guidance text specific to this opportunity
      type: object
      additionalProperties: true
      oneOf:
        - $ref: '#/BrokenBacklinksGuidance'
        - $ref: '#/BrokenInternalLinksGuidance'
    tags:
      type: array
      items:
        type: string
      description: Optional list of tags
      example:
        - 'Traffic acquisition'
SuggestionStatus:
  description: Status of this suggestion; status reflects overall fix execution, flagged here for optimization
  type: string
  enum:
    - 'NEW'
    - 'APPROVED'
    - 'SKIPPED'
    - 'FIXED'
    - 'ERROR'
    - 'IN_PROGRESS'
    - 'OUTDATED'
    - 'PENDING_VALIDATION'
    - 'REJECTED'
  example: 'NEW'
SuggestionSkipReason:
  description: Reason for skipping a suggestion when status is SKIPPED
  type: string
  enum:
    - ALREADY_IMPLEMENTED
    - INACCURATE_OR_INCOMPLETE
    - TOO_RISKY
    - NO_REASON
    - OTHER
SuggestionType:
  description: |
    Type of suggestion:
    - REDIRECT_UPDATE: Add or update a redirect as suggested
    - EXPERIMENT: Run the experiment with the given suggestions
    - CONTENT_UPDATE: Update the content to the suggested
    - METADATA_UPDATE: Update the metadata to the suggested
  type: string
  enum:
    - 'REDIRECT_UPDATE'
    - 'EXPERIMENT'
    - 'CONTENT_UPDATE'
    - 'METADATA_UPDATE'
  example: 'REDIRECT_UPDATE'
Suggestion:
  type: object
  properties:
    id:
      description: UUID of this suggestion
      $ref: '#/Id'
    opportunityId:
      description: UUID of the opportunity this suggestion belongs to
      $ref: '#/Id'
    type:
      $ref: '#/SuggestionType'
    rank:
      description: Type-specific numeric rank value (e.g., "domainTraffic" for a broken-backlink) helps sorting
      type: number
      example: 45600
    data:
      description: Map containing type-specific details of what fix is suggested
      type: object
      additionalProperties: true
      oneOf:
        - $ref: '#/BrokenBacklinksRedirectData'
        - $ref: '#/BrokenInternalLinksSuggestionData'
    kpiDeltas:
      description: Map containing metrics estimated to experience lifts or losses due to the issue
      type: object
      additionalProperties: true
      oneOf:
        - $ref: '#/BrokenBacklinksKpiDeltas'
        - $ref: '#/BrokenInternalLinksKpiDeltas'
    status:
      description: Status of this suggestion; status reflects overall fix execution, flagged here for optimization
      $ref: '#/SuggestionStatus'
    skipReason:
      description: Reason for skipping when status is SKIPPED
      $ref: '#/SuggestionSkipReason'
    skipDetail:
      description: Optional detail for skip reason, max 500 characters
      type: string
      maxLength: 500
    createdAt:
      description: UTC timestamp of when the suggestion was created
      $ref: '#/DateTime'
    updatedAt:
      description: UTC timestamp of when the suggestion was last updated
      $ref: '#/DateTime'
  example:
    id: '123e4567-e89b-12d3-a456-426614174000'
    opportunityId: '123e4567-e89b-12d3-a456-426614174000'
    type: 'REDIRECT_UPDATE'
    rank: 45600
    data:
      title: 'Fix broken backlink from example.com'
      url_from: 'https://www.example.com/old-page'
      url_to: 'https://www.example.com/broken-link'
      urls_suggested:
        - 'https://www.example.com/new-page'
    kpiDeltas: {}
    status: 'NEW'
    createdAt: '2024-01-19T14:20:30Z'
    updatedAt: '2024-01-19T14:20:30Z'
  required:
    - id
    - opportunityId
    - type
    - rank
    - data
    - status
    - createdAt
    - updatedAt
SuggestionList:
  type: array
  items:
    $ref: '#/Suggestion'
SuggestionMinimal:
  type: object
  description: Minimal suggestion projection containing id, status, timestamps, and URL-related data fields for listing views
  properties:
    id:
      description: UUID of this suggestion
      $ref: '#/Id'
    status:
      description: Status of this suggestion
      $ref: '#/SuggestionStatus'
    data:
      type: object
      description: URL-related fields extracted from the full data object. Only present if any URL fields exist.
      properties:
        url:
          type: string
          example: "https://example.com/page"
        urls:
          type: array
          items:
            type: string
        urlFrom:
          type: string
          example: "https://example.com/source"
        urlTo:
          type: string
          example: "https://example.com/destination"
        url_from:
          type: string
          description: Source URL (snake_case variant for broken backlinks)
          example: "https://example.com/source"
        url_to:
          type: string
          description: Target URL (snake_case variant for broken backlinks)
          example: "https://example.com/destination"
        urlsSuggested:
          type: array
          description: Array of suggested URLs
          items:
            type: string
        sitemapUrl:
          type: string
          example: "https://example.com/sitemap.xml"
        pageUrl:
          type: string
          example: "https://example.com/page"
        pattern:
          type: string
        link:
          type: string
        path:
          type: string
        sourceUrl:
          type: string
        destinationUrl:
          type: string
        recommendations:
          type: array
          items:
            type: object
        cves:
          type: array
          items:
            type: object
        findings:
          type: array
          items:
            type: object
        form:
          type: object
        page:
          type: object
        accessibility:
          type: object
        metrics:
          type: object
          description: CWV metrics (mobileMetric, desktopMetric) for calculating totalIssues
        type:
          type: string
          description: Type indicator (e.g., 'url' vs 'group' for CWV)
        pageviews:
          type: number
          description: Page views count for display
        issues:
          type: array
          description: Issues array for Accessibility, ColorContrast, FormNonExperimental (includes occurrences field)
          items:
            type: object
    createdAt:
      description: UTC timestamp of when the suggestion was created
      $ref: '#/DateTime'
    updatedAt:
      description: UTC timestamp of when the suggestion was last updated
      $ref: '#/DateTime'
  required:
    - id
    - status
    - createdAt
    - updatedAt
SuggestionSummary:
  type: object
  description: Summary suggestion projection (superset of minimal, subset of full). Contains minimal data fields plus metadata for table displays.
  properties:
    id:
      description: UUID of this suggestion
      $ref: '#/Id'
    status:
      description: Status of this suggestion
      $ref: '#/SuggestionStatus'
    data:
      type: object
      description: URL-related fields from minimal view (same as SuggestionMinimal.data). Only present if any URL fields exist.
    opportunityId:
      description: UUID of the opportunity this suggestion belongs to
      $ref: '#/Id'
    type:
      $ref: '#/SuggestionType'
    rank:
      description: Type-specific numeric rank value (e.g., "domainTraffic" for a broken-backlink) helps sorting
      type: number
      example: 45600
    url:
      description: URL associated with the suggestion (extracted from data). May be null if no URL found.
      type: string
      example: "https://example.com/page"
    createdAt:
      description: UTC timestamp of when the suggestion was created
      $ref: '#/DateTime'
    updatedAt:
      description: UTC timestamp of when the suggestion was last updated
      $ref: '#/DateTime'
    updatedBy:
      description: Who last updated this suggestion
      type: string
      example: "user@example.com"
  required:
    - id
    - status
    - opportunityId
    - type
    - rank
PaginationMetadata:
  type: object
  description: Metadata for paginated responses
  properties:
    limit:
      description: The maximum number of items returned in this page
      type: integer
      example: 100
    cursor:
      description: The cursor to use for fetching the next page, or null if there are no more pages
      type: string
      example: "eyJzayI6IjIwMjQtMDEtMTVUMTI6MzA6MDBaIiwiaWQiOiIxMjNlNDU2Ny1lODliLTEyZDMtYTQ1Ni00MjY2MTQxNzQwMDAifQ=="
    hasMore:
      description: Indicates whether there are more pages available
      type: boolean
      example: true
  required:
    - limit
    - cursor
    - hasMore
SuggestionPagedResponse:
  type: object
  description: Paginated response for suggestions
  properties:
    suggestions:
      type: array
      items:
        $ref: '#/Suggestion'
    pagination:
      $ref: '#/PaginationMetadata'
  required:
    - suggestions
    - pagination
SuggestionCreate:
  type: object
  properties:
    type:
      $ref: '#/SuggestionType'
    rank:
      description: Type-specific numeric rank value (e.g., "domainTraffic" for a broken-backlink) helps sorting
      type: number
      example: 45600
    data:
      description: Map containing type-specific details of what fix is suggested
      type: object
      additionalProperties: true
      oneOf:
        - $ref: '#/BrokenBacklinksRedirectData'
        - $ref: '#/BrokenInternalLinksSuggestionData'
    kpiDeltas:
      description: Map containing metrics estimated to experience lifts or losses due to the issue
      type: object
      additionalProperties: true
      oneOf:
        - $ref: '#/BrokenBacklinksKpiDeltas'
        - $ref: '#/BrokenInternalLinksKpiDeltas'
  required:
    - opportunityId
    - type
    - rank
    - data
SuggestionCreateList:
  type: array
  items:
    $ref: '#/SuggestionCreate'
SuggestionOperationSuccess:
  type: object
  description: Success response for a suggestion operation
  properties:
    index:
      description: Index of this suggestion in the list from the request body, starting from 0
      type: integer
      minimum: 0
    statusCode:
      description: HTTP status code indicating the type of success
      type: integer
    suggestion:
      $ref: '#/Suggestion'
  required:
    - index
    - statusCode
    - suggestion
SuggestionCreateFailure:
  type: object
  description: Suggestion create failure response
  properties:
    index:
      description: Index of this suggestion in the list from the request body, starting from 0
      type: integer
      minimum: 0
    statusCode:
      description: HTTP status code indicating the type of failure
      type: integer
    message:
      description: Error message describing the failure
      type: string
  required:
    - index
    - statusCode
    - message
SuggestionCreateListResponse:
  type: object
  description: Suggestion create list response
  properties:
    suggestions:
      type: array
      items:
        oneOf:
          - $ref: '#/SuggestionOperationSuccess'
          - $ref: '#/SuggestionCreateFailure'
    metadata:
      type: object
      properties:
        total:
          description: Total number of suggestions in the response
          type: integer
        success:
          description: Number of suggestions successfully create
          type: integer
        failure:
          description: Number of suggestions that failed to create
          type: integer
      required:
        - total
        - success
        - failure
  required:
    - suggestions
    - metadata
SuggestionUpdate:
  type: object
  properties:
    rank:
      description: Type-specific numeric rank value (e.g., "domainTraffic" for a broken-backlink) helps sorting
      type: number
      example: 12300
    data:
      description: Map containing type-specific details of what fix is suggested
      type: object
      additionalProperties: true
      oneOf:
        - $ref: '#/BrokenBacklinksRedirectData'
        - $ref: '#/BrokenInternalLinksSuggestionData'
    kpiDeltas:
      description: Map containing metrics estimated to experience lifts or losses due to the issue
      type: object
      additionalProperties: true
      oneOf:
        - $ref: '#/BrokenBacklinksKpiDeltas'
        - $ref: '#/BrokenInternalLinksKpiDeltas'
    status:
      description: Status of this suggestion; when set to SKIPPED, skipReason and skipDetail may be provided
      $ref: '#/SuggestionStatus'
    skipReason:
      description: Reason for skipping when status is SKIPPED; required when status is SKIPPED if provided
      $ref: '#/SuggestionSkipReason'
    skipDetail:
      description: Optional detail for skip reason, max 500 characters
      type: string
      maxLength: 500
SuggestionStatusUpdate:
  type: array
  items:
    type: object
    properties:
      id:
        description: UUID of this suggestion
        readOnly: false
        $ref: '#/Id'
      status:
        description: Status of this suggestion; status reflects overall fix execution, flagged here for optimization
        $ref: '#/SuggestionStatus'
      skipReason:
        description: Reason for skipping when status is SKIPPED
        $ref: '#/SuggestionSkipReason'
      skipDetail:
        description: Optional detail for skip reason, max 500 characters
        type: string
        maxLength: 500
    required:
      - id
      - status
SuggestionUpdateFailure:
  type: object
  description: Suggestion update failure
  properties:
    id:
      description: UUID of this suggestion
      $ref: '#/Id'
    index:
      description: Index of this suggestion in the list from the request body, starting from 0
      type: integer
      minimum: 0
    statusCode:
      description: HTTP status code indicating the type of failure
      type: integer
    message:
      description: Error message describing the failure
      type: string
  required:
    - id
    - index
    - statusCode
    - message
SuggestionStatusUpdateListResponse:
  type: object
  description: Suggestions status update response
  properties:
    suggestions:
      type: array
      items:
        oneOf:
          - $ref: '#/SuggestionOperationSuccess'
          - $ref: '#/SuggestionUpdateFailure'
    metadata:
      type: object
      properties:
        total:
          description: Total number of suggestions in the response
          type: integer
        success:
          description: Number of suggestions successfully updated
          type: integer
        failure:
          description: Number of suggestions that failed to update
          type: integer
      required:
        - total
        - success
        - failure
  required:
    - suggestions
    - metadata
BrokenBacklinksRedirectData:
  description: Data specific to redirect suggestion for broken backlinks opportunity
  type: object
  additionalProperties: true
  properties:
    title:
      description: The title of the referring page
      type: string
    url_from:
      description: The URL of the referring page
      type: string
    url_to:
      description: The URL of the broken target page
      type: string
    urls_suggested:
      description: The proposed target URLs to redirect the broken backlink to
      type: array
      items:
        type: string
    manualOverrideURL:
      description: The URL to manually override the proposed target URL
      type: string
    traffic_domain:
      description: The estimated monthly organic traffic to the referring page
      type: number
    aggregationKey:
      description: |
        Computed aggregation key for grouping related suggestions.
        Format varies by issue type granularity (e.g., url|type|selector|source for individual issues).
        Used for bulk operations and tracking remediation across audit runs.
      type: string
      readOnly: true
      example: "/page.html|color-contrast|div.button|lighthouse"
BrokenInternalLinksSuggestionData:
  description: Data specific to redirect suggestion for broken internal links opportunity
  type: object
  additionalProperties: true
  properties:
    title:
      description: The title of the referring page
      type: string
    urlFrom:
      description: The URL of the referring page
      type: string
    urlTo:
      description: The URL of the broken target page
      type: string
    aiRationale:
      description: The rationale for the suggested fix
      type: string
    urlsSuggested:
      description: The proposed internal target URLs to point the broken internal link to
      type: array
      items:
        type: string
    manualOverrideURL:
      description: The URL to manually override the proposed target URL
      type: string
    trafficDomain:
      description: The estimated monthly organic traffic to the referring page
      type: number
    priority:
      description: The priority of the broken internal link
      $ref: '#/Priority'
    aggregationKey:
      description: |
        Computed aggregation key for grouping related suggestions.
        Format varies by issue type granularity (e.g., url|type|selector|source for individual issues).
        Used for bulk operations and tracking remediation across audit runs.
      type: string
      readOnly: true
      example: "/page.html|color-contrast|div.button|lighthouse"
BrokenBacklinksKpiDeltas:
  description: KPI deltas specific to redirect suggestion for broken backlinks opportunity
  type: object
  additionalProperties: true
BrokenBacklinksOpportunityData:
  description: Data specific to broken backlinks opportunity
  type: object
  additionalProperties: true
BrokenBacklinksGuidance:
  description: Guidance specific to broken backlinks opportunity
  type: object
  additionalProperties: true
  properties:
    steps:
      description: The steps to resolve the broken backlinks opportunity
      type: array
      items:
        type: string
BrokenInternalLinksKpiDeltas:
  description: KPI deltas specific to redirect suggestion for broken internal links opportunity
  type: object
  additionalProperties: true
BrokenInternalLinksOpportunityData:
  description: Data specific to broken internal links opportunity
  type: object
  properties:
    projectedTrafficLost:
      type: number
      description: Projected Traffic Lost, representing the estimated loss of organic traffic
    projectedTrafficValue:
      type: number
      description: Projected Traffic Value, calculated by multiplying the Projected Traffic Lost by the Cost Per Click (CPC) value.
  additionalProperties: true
BrokenInternalLinksGuidance:
  description: Guidance specific to broken internal links opportunity
  type: object
  additionalProperties: true
  properties:
    steps:
      description: The steps to resolve the broken internal links opportunity
      type: array
      items:
        type: string
ImportJobStopRequest:
  type: object
  properties:
    op:
      description: The operation to perform on the import job
      type: string
      enum:
        - 'replace'
    path:
      description: The path of the attribute to update
      type: string
      example: '/status'
    value:
      description: The value to set
      type: string
      enum:
        - 'STOPPED'
CWVOpportunityData:
  description: Data specific to Core Web Vitals improvements opportunity
  type: object
  properties:
    projectedTrafficLost:
      type: number
      description: Projected Traffic Lost, representing the estimated loss of organic traffic
    projectedTrafficValue:
      type: number
      description: Projected Traffic Value, calculated by multiplying the Projected Traffic Lost by the Cost Per Click (CPC) value.
  additionalProperties: true
CWVGuidance:
  description: Guidance specific to Core Web Vitals improvements opportunity
  type: object
  additionalProperties: true
  properties:
    steps:
      description: The recommended steps to resolve Core Web Vitals issues and improve site performance.
      type: array
      items:
        type: string
Priority:
  type: string
  enum:
    - 'high'
    - 'medium'
    - 'low'
  example: 'high'
Brand:
  type: object
  properties:
    id:
      description: The ID of the brand
      $ref: '#/BrandId'
    name:
      description: The name of the brand
      type: string
    baseSiteId:
      description: UUID of the brand's primary site. Immutable once set. Unique per organization.
      type: string
      format: uuid
    baseUrl:
      description: Read-only. The base URL of the primary site, resolved from baseSiteId.
      type: string
      readOnly: true
    imsOrgId:
      description: The IMS Organization ID of the brand
      $ref: '#/ImsOrganizationId'
    createdAt:
      description: The date and time when the brand was created
      $ref: '#/DateTime'
    updatedAt:
      description: The date and time when the brand was last updated
      $ref: '#/DateTime'
  example:
    id: 'urn:aaid:sc:VA6C2:e64205e7-13ca-51e8-8b83-8d8ef1ebf911'
    name: 'Brand Foo Bar Example'
    imsOrgId: '1234567890ABCDEF12345678@AdobeOrg'
    createdAt: '2025-01-01T00:00:00Z'
    updatedAt: '2025-02-01T00:00:00Z'
BrandList:
  type: array
  items:
    $ref: '#/Brand'
BrandGuideline:
  type: object
  properties:
    text:
      description: The text of the brand guideline
      type: string
BrandGuidelines:
  allOf:
    - $ref: '#/Brand'
    - type: object
      properties:
        toneOfVoice:
          description: The tone of voice of the brand
          type: array
          items:
            $ref: '#/BrandGuideline'
        coreValues:
          description: The core values of the brand
          type: array
          items:
            $ref: '#/BrandGuideline'
        guidelines:
          description: The guidelines of the brand
          type: array
          items:
            $ref: '#/BrandGuideline'
        restrictions:
          description: The restrictions of the brand
          type: array
          items:
            $ref: '#/BrandGuideline'
        additionalGuidelines:
          description: Additional guidelines of the brand
          type: array
          items:
            $ref: '#/BrandGuideline'
      example:
        toneOfVoice:
          [{ 'text': 'Encourage Action' }, { 'text': 'Be optimistic' }]
        coreValues: [{ 'text': 'Inspiring' }, { 'text': 'Human' }]
        guidelines:
          [
            {
              'text': "Use gender-neutral pronouns like 'they', 'them', 'theirs'",
            },
            { 'text': 'Always use sentence case' },
          ]
        restrictions: [{ 'text': "Don't use rhetorical questions" }]
        additionalGuidelines: [{ 'text': 'Always use sentence case' }]
AsyncJob:
  type: object
  properties:
    jobId:
      type: string
      format: uuid
    status:
      type: string
      enum: [IN_PROGRESS, COMPLETED, FAILED]
    createdAt:
      type: string
      format: date-time
    updatedAt:
      type: string
      format: date-time
    startedAt:
      type: string
      format: date-time
    endedAt:
      type: string
      format: date-time
    recordExpiresAt:
      type: integer
      format: int64
      description: Unix epoch seconds for TTL
    result:
      type: object
    error:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
        details:
          type: object
    metadata:
      type: object
      required:
        - urls
        - step
      properties:
        urls:
          type: array
          items:
            type: string
            format: uri
          description: Array of URLs to be processed by the job
          minItems: 1
        step:
          type: string
          enum: [identify, suggest]
          description: The audit step to be performed
        submittedBy:
          type: string
        tags:
          type: array
          items:
            type: string
  required:
    - jobId
    - status
    - createdAt
    - updatedAt
    - startedAt
    - metadata

CreateAsyncJobAcceptedResponse:
  properties:
    id:
      type: string
      format: uuid
      description: The ID of the newly created scrape job.
    baseURL:
      type: string
      format: uri
      description: The base URL of the scrape job
    processingType:
      type: string
      description: The scrape handler to use for the scrape job
    options:
      type: object
      description: The options used for the scrape job
    startedAt:
      type: string
      format: date-time
    status:
      type: string
      enum: [RUNNING, COMPLETE, FAILED]
    urlCount:
      type: integer
      description: The number of URLs in the scrape job
    successCount:
      type: integer
      description: The number of successful URLs in the scrape job
    failedCount:
      type: integer
      description: The number of failed URLs in the scrape job
    redirectCount:
      type: integer
      description: The number of redirected URLs in the scrape job
    customHeaders:
      type: object
      description: The custom headers used for the scrape job

ScrapedContentResponse:
  type: array
  description: Collection of scraped content files with metadata
  items:
    type: object
    properties:
      key:
        type: string
        description: Full path of the file relative to the content type root directory
      name:
        type: string
        description: Name of the file
      size:
        type:
          - integer
          - 'null'
        description: File size in bytes
      lastModified:
        type:
          - string
          - 'null'
        format: date-time
        description: Timestamp of the last file modification
  example:
    - key: 'about-us/scrape.json'
      name: 'scrape.json'
      size: 2048
      lastModified: '2025-04-11T00:44:31Z'
    - key: 'about-us/screenshot-desktop-fullpage.png'
      name: 'screenshot-desktop-fullpage.png'
      size: 123456
      lastModified: '2025-04-11T00:44:31Z'

FixStatus:
  description: |
    Fix Status
    - PENDING: the fix is pending to be deployed
    - DEPLOYED: the fix was successfully applied
    - PUBLISHED: the fix is live in production
    - FAILED: failed to apply the fix
    - ROLLED_BACK: the fix has been rolled_back
  example: 'PENDING'
  type: string
  enum:
    - 'PENDING'
    - 'DEPLOYED'
    - 'PUBLISHED'
    - 'FAILED'
    - 'ROLLED_BACK'

Fix:
  type: object
  properties:
    id:
      type: string
      format: uuid
    opportunityId:
      type: string
      format: uuid
    type:
      $ref: '#/SuggestionType'
    createdAt:
      type: string
      format: date-time
    executedBy:
      type: string
    executedAt:
      type: string
      format: date-time
    publishedAt:
      type: string
      format: date-time
    changeDetails:
      type: object
      additionalProperties: true
    status:
      $ref: '#/FixStatus'

FixList:
  type: array
  items:
    $ref: '#/Fix'

FixListResponse:
  type: object
  properties:
    data:
      type: array
      items:
        $ref: '#/Fix'

FixCreate:
  type: object
  required:
    - type
    - changeDetails
  properties:
    type:
      $ref: '#/SuggestionType'
    changeDetails:
      type: object
      additionalProperties: true
    status:
      $ref: '#/FixStatus'
    suggestionIds:
      type: array
      description: Optional array of suggestion IDs to associate with this fix
      items:
        $ref: '#/Id'

FixOperationSuccess:
  type: object
  description: Success response for a fix operation
  properties:
    index:
      description: Index of this fix in the list from the request body, starting from 0
      type: integer
      minimum: 0
    statusCode:
      description: HTTP status code indicating the type of success
      type: integer
    fix:
      $ref: '#/Fix'
  required:
    - index
    - statusCode
    - fix

FixUpdateFailure:
  type: object
  description: Fix update failure response
  properties:
    id:
      description: UUID of this fix
      $ref: '#/Id'
    index:
      description: Index of this fix in the list from the request body, starting from 0
      type: integer
      minimum: 0
    statusCode:
      description: HTTP status code indicating the type of failure
      type: integer
    message:
      description: Error message describing the failure
      type: string

FixCreateFailure:
  type: object
  description: Fix create failure response
  properties:
    index:
      description: Index of this fix in the list from the request body, starting from 0
      type: integer
      minimum: 0
    statusCode:
      description: HTTP status code indicating the type of failure
      type: integer
    message:
      description: Error message describing the failure
      type: string

FixCreateList:
  type: array
  items:
    $ref: '#/FixCreate'

FixCreateListResponse:
  type: object
  description: Fix create list response
  properties:
    fixes:
      type: array
      items:
        oneOf:
          - $ref: '#/FixOperationSuccess'
          - $ref: '#/FixCreateFailure'
    metadata:
      type: object
      properties:
        total:
          description: Total number of fixes in the response
          type: integer
        success:
          description: Number of fixes successfully created
          type: integer
        failure:
          description: Number of fixes that failed to create
          type: integer
      required:
        - total
        - success
        - failure
  required:
    - fixes
    - metadata

FixUpdate:
  type: object
  properties:
    changeDetails:
      type: object
      additionalProperties: true
    status:
      $ref: '#/FixStatus'
    suggestionIds:
      type: array
      description: Optional array of suggestion IDs to associate with this fix. Replaces existing associations.
      items:
        $ref: '#/Id'
    executedBy:
      type: string
      description: Email or identifier of who executed the fix
    executedAt:
      $ref: '#/DateTime'
      description: ISO timestamp when the fix was executed
    publishedAt:
      $ref: '#/DateTime'
      description: ISO timestamp when the fix was published
    origin:
      type: string
      description: Origin of the fix (e.g., 'manual', 'automated')

FixStatusUpdate:
  type: array
  items:
    type: object
    properties:
      id:
        description: UUID of this fix
        readOnly: false
        $ref: '#/Id'
      status:
        description: Status of this fix; status reflects overall fix execution, flagged here for optimization
        $ref: '#/SuggestionStatus'
    required:
      - id
      - status

FixStatusUpdateListResponse:
  type: object
  description: Fixes status update response
  properties:
    fixes:
      type: array
      items:
        oneOf:
          - $ref: '#/FixOperationSuccess'
          - $ref: '#/FixUpdateFailure'
    metadata:
      type: object
      properties:
        total:
          description: Total number of fixes in the response
          type: integer
        success:
          description: Number of fixes successfully updated
          type: integer
        failure:
          description: Number of fixes that failed to update
          type: integer
      required:
        - total
        - success
        - failure
  required:
    - fixes
    - metadata

FixRollbackResponse:
  type: object
  description: Response after successfully rolling back a failed fix
  properties:
    fix:
      type: object
      description: The rolled back fix with metadata
      properties:
        index:
          type: integer
          description: Index of the fix in the response
          example: 0
        uuid:
          type: string
          format: uuid
          description: UUID of the fix entity
        fix:
          $ref: '#/Fix'
          description: The updated fix entity with ROLLED_BACK status
        statusCode:
          type: integer
          description: HTTP status code for this fix operation
          example: 200
      required:
        - index
        - uuid
        - fix
        - statusCode
    suggestions:
      type: object
      description: Summary of suggestions that were updated
      properties:
        updated:
          type: array
          items:
            type: object
            properties:
              index:
                type: integer
                description: Index of the suggestion in the response array
              uuid:
                type: string
                format: uuid
                description: UUID of the suggestion entity
              suggestion:
                $ref: '#/Suggestion'
                description: The updated suggestion entity with SKIPPED status
              statusCode:
                type: integer
                description: HTTP status code for this suggestion operation
                example: 200
            required:
              - index
              - uuid
              - suggestion
              - statusCode
          description: List of suggestions that were marked as SKIPPED
      required:
        - updated
    message:
      type: string
      description: Human-readable message describing the result
      example: "Fix rolled back successfully. All 3 suggestion(s) marked as SKIPPED."
  required:
    - fix
    - suggestions
    - message

PaidSiteTopPage:
  type: object
  required:
    - url
    - ctr
    - avgClicksPerSession
    - pageViews
    - clickedSessions
    - bounceRate
    - totalNumClicks
    - source
  properties:
    url:
      type: string
      format: uri
    ctr:
      type: number
      format: float
    avgClicksPerSession:
      type: number
      format: float
    pageViews:
      type: integer
    clickedSessions:
      type: integer
    bounceRate:
      type: number
      format: float
    totalNumClicks:
      type: integer
    source:
      type: string
      description: Paid traffic source (e.g., paid:search:google)
  example:
    url: 'https://www.example.com/uk/'
    ctr: 0.015
    avgClicksPerSession: 1.82
    pageViews: 6100
    clickedSessions: 1800
    bounceRate: 0.98
    totalNumClicks: 5100
    source: 'paid:affiliate:'
PaidSiteTopPageList:
  type: array
  items:
    $ref: './schemas.yaml#/PaidSiteTopPage'

PTAWeeklySummary:
  type: object
  description: Aggregated paid traffic analysis metrics for a specific week or month
  properties:
    pageviews:
      type: string
      description: Total number of pageviews
      example: '885800'
    click_rate:
      type: string
      description: Click-through rate as a decimal value
      example: '0.40438022126890943'
    engagement_rate:
      type: string
      description: Engagement rate as a decimal value
      example: '0.4856626778053737'
    bounce_rate:
      type: string
      description: Bounce rate as a decimal value
      example: '0.5143373221946264'
    trends:
      type: object
      description: Trend analysis showing percentage changes for each metric
      properties:
        pageviews:
          type: number
          description: Percentage change in pageviews
          example: 7.084139264990329
        click_rate:
          type: number
          description: Percentage change in click rate
          example: -14.884651645383743
        engagement_rate:
          type: number
          description: Percentage change in engagement rate
          example: -9.782131803142791
        bounce_rate:
          type: number
          description: Percentage change in bounce rate
          example: 11.40608350861348

PredominantTrafficRequest:
  type: object
  required:
    - urls
  properties:
    urls:
      type: array
      description: Array of URLs to analyze for predominant traffic type
      items:
        type: string
        format: uri
      minItems: 1
      example:
        - 'https://example.com/page1'
        - 'https://example.com/page2'
        - 'https://example.com/products/item'
    predominantTrafficPct:
      type: number
      description: |
        Minimum percentage threshold for a traffic type to be considered predominant.
        If any single traffic type (paid, earned, or owned) reaches or exceeds this percentage,
        it is considered the predominant type. Otherwise, traffic is classified as "mixed".
      minimum: 0
      maximum: 100
      default: 80
      example: 80

PredominantTrafficResponse:
  type: array
  description: Array of traffic analysis results, one per URL requested
  items:
    $ref: '#/PredominantTrafficResult'

PredominantTrafficResult:
  type: object
  description: Traffic analysis result for a single URL
  required:
    - url
    - predominantTraffic
    - details
  properties:
    url:
      type: string
      format: uri
      description: The URL that was analyzed
      example: 'https://example.com/page1'
    predominantTraffic:
      type: string
      description: |
        The predominant traffic type for this URL. Can be 'paid', 'earned', 'owned',
        'mixed' (no single type reaches threshold), or 'no traffic' (no data available).
      enum:
        - paid
        - earned
        - owned
        - mixed
        - no traffic
      example: 'paid'
    details:
      type: object
      description: Detailed traffic breakdown showing percentage of traffic from each type
      required:
        - paid
        - earned
        - owned
      properties:
        paid:
          type: number
          description: Percentage of traffic from paid sources
          minimum: 0
          maximum: 100
          example: 85.5
        earned:
          type: number
          description: Percentage of traffic from earned sources
          minimum: 0
          maximum: 100
          example: 10.3
        owned:
          type: number
          description: Percentage of traffic from owned sources
          minimum: 0
          maximum: 100
          example: 4.2

LlmoQuestion:
  type: object
  required:
    - key
    - question
  properties:
    key:
      description: Unique identifier for the question
      type: string
      format: uuid
      example: '123e4567-e89b-12d3-a456-426614174000'
    question:
      description: The question text
      type: string
      example: 'What is the main value proposition of this product?'
    source:
      description: Source of the question
      type: string
      example: 'human'
    country:
      description: Country context for the question
      type: string
      example: 'US'
    product:
      description: Product context for the question
      type: string
      example: 'Adobe Creative Cloud'
    volume:
      description: Volume or traffic context
      type: string
      example: 'high'
    importTime:
      description: Time when the question was imported
      type: string
      format: date-time
      example: '2024-01-20T12:00:00Z'
    keyword:
      description: Associated keyword for the question
      type: string
      example: 'creative software'
    url:
      description: URL context for the question
      type: string
      format: uri
      example: 'https://www.adobe.com/creativecloud.html'
    tags:
      description: Array of tags associated with the question
      type: array
      items:
        type: string
      example: ['product', 'pricing', 'features']
  additionalProperties: true

LlmoQuestions:
  type: object
  description: LLMO questions configuration containing both human and AI questions
  properties:
    Human:
      description: Array of human-generated questions
      type: array
      items:
        $ref: '#/LlmoQuestion'
      example:
        - key: '123e4567-e89b-12d3-a456-426614174000'
          question: 'What is the main value proposition of this product?'
          source: 'human'
          country: 'US'
          product: 'Adobe Creative Cloud'
          volume: 'high'
          importTime: '2024-01-20T12:00:00Z'
          keyword: 'creative software'
          url: 'https://www.adobe.com/creativecloud.html'
          tags: ['product', 'pricing', 'features']
        - key: '456e7890-e89b-12d3-a456-426614174001'
          question: 'How does this service solve customer problems?'
          source: 'ai'
          country: 'US'
          product: 'Adobe Creative Cloud'
          volume: 'medium'
          importTime: '2024-01-20T12:00:00Z'
          keyword: 'customer support'
          url: 'https://www.adobe.com/support.html'
          tags: ['support', 'benefits']
    AI:
      description: Array of AI-generated questions
      type: array
      items:
        $ref: '#/LlmoQuestion'
      example:
        - key: '789e0123-e89b-12d3-a456-426614174002'
          question: 'What are the key features that differentiate this product?'
          source: 'ai'
          country: 'US'
          product: 'Adobe Creative Cloud'
          volume: 'high'
          importTime: '2024-01-20T12:00:00Z'
          keyword: 'features comparison'
          url: 'https://www.adobe.com/features.html'
          tags: ['features', 'differentiation']
        - key: '012e3456-e89b-12d3-a456-426614174003'
          question: 'How does this compare to competitors in the market?'
          source: 'ai'
          country: 'US'
          product: 'Adobe Creative Cloud'
          volume: 'medium'
          importTime: '2024-01-20T12:00:00Z'
          keyword: 'competitive analysis'
          url: 'https://www.adobe.com/competitive.html'
          tags: ['competitive', 'analysis']
  additionalProperties: false

LlmoQuestionsInput:
  type: object
  description: Input format for adding new LLMO questions
  properties:
    Human:
      description: Array of human questions to add
      type: array
      items:
        type: object
        properties:
          question:
            description: The question text
            type: string
            example: 'What is the main value proposition of this product?'
          source:
            description: Source of the question
            type: string
            example: 'human'
          country:
            description: Country context for the question
            type: string
            example: 'US'
          product:
            description: Product context for the question
            type: string
            example: 'Adobe Creative Cloud'
          volume:
            description: Volume or traffic context
            type: string
            example: 'high'
          importTime:
            description: Time when the question was imported
            type: string
            format: date-time
            example: '2024-01-20T12:00:00Z'
          keyword:
            description: Associated keyword for the question
            type: string
            example: 'creative software'
          url:
            description: URL context for the question
            type: string
            format: uri
            example: 'https://www.adobe.com/creativecloud.html'
          tags:
            description: Array of tags associated with the question
            type: array
            items:
              type: string
            example: ['product', 'pricing', 'features']
        required:
          - question
        additionalProperties: true
      example:
        - question: 'What is the main value proposition of this product?'
          source: 'human'
          country: 'US'
          product: 'Adobe Creative Cloud'
          volume: 'high'
          importTime: '2024-01-20T12:00:00Z'
          keyword: 'creative software'
          url: 'https://www.adobe.com/creativecloud.html'
          tags: ['product', 'pricing', 'features']
    AI:
      description: Array of AI questions to add
      type: array
      items:
        type: object
        properties:
          question:
            description: The question text
            type: string
            example: 'What are the key features that differentiate this product?'
          source:
            description: Source of the question
            type: string
            example: 'ai'
          country:
            description: Country context for the question
            type: string
            example: 'US'
          product:
            description: Product context for the question
            type: string
            example: 'Adobe Creative Cloud'
          volume:
            description: Volume or traffic context
            type: string
            example: 'high'
          importTime:
            description: Time when the question was imported
            type: string
            format: date-time
            example: '2024-01-20T12:00:00Z'
          keyword:
            description: Associated keyword for the question
            type: string
            example: 'features comparison'
          url:
            description: URL context for the question
            type: string
            format: uri
            example: 'https://www.adobe.com/features.html'
          tags:
            description: Array of tags associated with the question
            type: array
            items:
              type: string
            example: ['features', 'differentiation']
        required:
          - question
        additionalProperties: true
      example:
        - question: 'What are the key features that differentiate this product?'
          source: 'ai'
          country: 'US'
          product: 'Adobe Creative Cloud'
          volume: 'high'
          importTime: '2024-01-20T12:00:00Z'
          keyword: 'features comparison'
          url: 'https://www.adobe.com/features.html'
          tags: ['features', 'differentiation']
  additionalProperties: false

LlmoQuestionUpdate:
  type: object
  description: Update format for modifying an existing LLMO question
  properties:
    question:
      description: Updated question text
      type: string
      example: 'What is the updated value proposition of this product?'
    source:
      description: Updated source of the question
      type: string
      example: 'human'
    country:
      description: Updated country context for the question
      type: string
      example: 'US'
    product:
      description: Updated product context for the question
      type: string
      example: 'Adobe Creative Cloud'
    volume:
      description: Updated volume or traffic context
      type: string
      example: 'high'
    importTime:
      description: Updated import time
      type: string
      format: date-time
      example: '2024-01-20T12:00:00Z'
    keyword:
      description: Updated associated keyword for the question
      type: string
      example: 'creative software'
    url:
      description: Updated URL context for the question
      type: string
      format: uri
      example: 'https://www.adobe.com/creativecloud.html'
    tags:
      description: Updated array of tags associated with the question
      type: array
      items:
        type: string
      example: ['product', 'pricing', 'features']
  additionalProperties: true

LlmoCustomerIntentItem:
  type: object
  description: A single customer intent key-value pair
  required:
    - key
    - value
  properties:
    key:
      description: The customer intent key identifier
      type: string
      example: 'target_audience'
    value:
      description: The customer intent value
      type: string
      example: 'small business owners'
  additionalProperties: false

LlmoCustomerIntent:
  type: array
  description: Array of customer intent key-value pairs
  items:
    $ref: '#/LlmoCustomerIntentItem'
  example:
    - key: 'target_audience'
      value: 'small business owners'
    - key: 'primary_goal'
      value: 'increase conversions'
    - key: 'user_persona'
      value: 'marketing director'

LlmoCustomerIntentInput:
  type: array
  description: Input format for adding new customer intent items
  items:
    $ref: '#/LlmoCustomerIntentItem'
  example:
    - key: 'target_audience'
      value: 'small business owners'
    - key: 'primary_goal'
      value: 'increase conversions'

LlmoCustomerIntentUpdate:
  type: object
  description: Update format for modifying an existing customer intent item
  properties:
    key:
      description: Updated customer intent key
      type: string
      example: 'updated_target_audience'
    value:
      description: Updated customer intent value
      type: string
      example: 'enterprise customers'
  additionalProperties: false

LlmoCdnLogsFilter:
  type: array
  description: Array of CDN logs filter items
  items:
    type: object
    required:
      - key
      - value
    properties:
      key:
        type: string
        example: 'host'
      value:
        type: array
        items:
          type: string
        example: ['example.com', 'abc.com']
      type:
        type: string
        enum: ['include', 'exclude']
        example: 'include'
  example:
    - key: 'host'
      value: ['example.com', 'abc.com']
      type: 'include'
    - key: 'status'
      value: ['404', '500']
      type: 'exclude'

LlmoCdnBucketConfig:
  type: object
  description: CDN bucket configuration for LLMO
  properties:
    bucketName:
      description: The name of the S3 bucket for CDN logs
      type: string
      example: 'my-cdn-logs-bucket'
    orgId:
      description: The ID associated with the bucket, for adobe orgs this is the imsOrgId ID and for non-adobe orgs this is the org ID
      type: string
      example: 'org-12345'
    cdnProvider:
      description: The CDN provider (e.g., aem-cs-fastly, byocdn-fastly, etc.)
      type: string
      example: 'aem-cs-fastly'
  additionalProperties: false

LlmoConfig:
  type: object
  description: LLMO (Large Language Model Optimizer) configuration for a site
  required:
    - entities
    - categories
    - topics
    - aiTopics
    - brands
    - competitors
  properties:
    entities:
      type: object
      description: A record of entities keyed by UUID
      additionalProperties:
        $ref: '#/LlmoEntity'
      example:
        "123e4567-e89b-12d3-a456-426614174000":
          type: "category"
          name: "Technology"
    categories:
      type: object
      description: A record of categories keyed by UUID
      additionalProperties:
        $ref: '#/LlmoCategory'
      example:
        "123e4567-e89b-12d3-a456-426614174000":
          name: "Technology"
          region: "us"
          urls:
            - value: "https://example.com/tech"
              type: "url"
            - value: "https://example.com/technology/*"
              type: "prefix"
    topics:
      type: object
      description: A record of topics with nested prompts keyed by UUID
      additionalProperties:
        $ref: '#/LlmoTopic'
      example:
        "456e7890-e89b-12d3-a456-426614174001":
          name: "AI/ML"
          category: "123e4567-e89b-12d3-a456-426614174000"
          prompts:
            - prompt: "What are the latest AI trends?"
              regions: ["us"]
              origin: "human"
              source: "config"
    aiTopics:
      type: object
      description: A record of AI topics with nested AI prompts keyed by UUID
      additionalProperties:
        $ref: '#/LlmoTopic'
      example:
        "456e7890-e89b-12d3-a456-426614174001":
          name: "AI/ML"
          category: "123e4567-e89b-12d3-a456-426614174000"
          prompts:
            - prompt: "What are the latest AI trends?"
              regions: ["us"]
              origin: "ai"
              source: "config"
    brands:
      type: object
      description: Brand configuration with aliases
      required:
        - aliases
      properties:
        aliases:
          type: array
          description: Array of brand alias configurations
          items:
            $ref: '#/LlmoBrandAlias'
    competitors:
      type: object
      description: Competitor configuration
      required:
        - competitors
      properties:
        competitors:
          type: array
          description: Array of competitor configurations
          items:
            $ref: '#/LlmoCompetitor'
    deleted:
      type: object
      description: Deleted prompts configuration
      properties:
        prompts:
          type: object
          description: A record of deleted prompts keyed by UUID
          additionalProperties:
            $ref: '#/LlmoDeletedPrompt'
    ignored:
      type: object
      description: Ignored prompts configuration
      properties:
        prompts:
          type: object
          description: A record of ignored prompts keyed by UUID
          additionalProperties:
            $ref: '#/LlmoIgnoredPrompt'
  additionalProperties: true

LlmoDeletedPrompt:
  type: object
  description: A deleted prompt entry in the LLMO configuration
  required:
    - prompt
    - regions
    - origin
    - source
    - topic
    - category
  properties:
    prompt:
      type: string
      description: The prompt text
      minLength: 1
    regions:
      type: array
      description: Array of two-letter region codes
      items:
        type: string
        pattern: '^[a-z][a-z]$'
    origin:
      type: string
      description: The origin of the prompt (human, ai, or custom)
    source:
      type: string
      description: The source of the prompt (config, api, or custom)
    topic:
      type: string
      description: The topic name this prompt belonged to
      minLength: 1
    category:
      type: string
      description: The category name this prompt belonged to
      minLength: 1
    categoryId:
      type: string
      format: uuid
      description: Optional UUID of the category
    updatedBy:
      type: string
      description: The user who last updated this entry
    updatedAt:
      type: string
      description: ISO timestamp of the last update
  additionalProperties: true

LlmoIgnoredPrompt:
  type: object
  description: An ignored prompt entry in the LLMO configuration
  required:
    - prompt
    - region
    - source
  properties:
    prompt:
      type: string
      description: The prompt text
      minLength: 1
    region:
      type: string
      pattern: '^[a-z][a-z]$'
      description: Two-letter region code
    source:
      type: string
      description: The source of the prompt (gsc or custom)
    updatedBy:
      type: string
      description: The user who last updated this entry
    updatedAt:
      type: string
      description: ISO timestamp of the last update
  additionalProperties: true

LlmoEntity:
  type: object
  description: An entity in the LLMO configuration
  required:
    - type
  properties:
    type:
      type: string
      description: The type of entity (category, topic, or custom type)
      example: "category"
    name:
      type: string
      description: The name of the entity (required for category and topic types)
      minLength: 1
      example: "Technology"
  additionalProperties: true

LlmoCategory:
  type: object
  description: A category in the LLMO configuration
  required:
    - name
    - region
  properties:
    name:
      type: string
      description: The name of the category
      minLength: 1
      example: "Technology"
    region:
      oneOf:
        - type: string
          pattern: '^[a-z][a-z]$'
          description: Two-letter region code
          example: "us"
        - type: array
          items:
            type: string
            pattern: '^[a-z][a-z]$'
          description: Array of two-letter region codes
          example: ["us", "eu"]
    urls:
      type: array
      description: Optional array of URLs associated with this category
      items:
        $ref: '#/LlmoCategoryUrl'
      example:
        - value: "https://example.com/tech"
          type: "url"
        - value: "https://example.com/news/*"
          type: "prefix"
  additionalProperties: true

LlmoCategoryUrl:
  type: object
  description: A URL configuration for a category
  required:
    - value
    - type
  properties:
    value:
      type: string
      description: The URL value - can be a complete URL or a URL prefix
      minLength: 1
      example: "https://example.com/tech"
    type:
      type: string
      enum: ["url", "prefix"]
      description: The type of URL - 'url' for exact URLs, 'prefix' for URL prefixes (ending with /*)
      example: "url"
  additionalProperties: false

LlmoTopic:
  type: object
  description: A topic in the LLMO configuration with nested prompts
  required:
    - name
    - prompts
    - category
  properties:
    name:
      type: string
      description: The name of the topic
      minLength: 1
      example: "AI/ML"
    prompts:
      type: array
      description: Array of prompts for this topic
      minItems: 1
      items:
        $ref: '#/LlmoPrompt'
    category:
      oneOf:
        - type: string
          format: uuid
          description: UUID reference to a category
          example: "123e4567-e89b-12d3-a456-426614174000"
        - type: string
          description: Category name as string
          minLength: 1
          example: "Technology"
  additionalProperties: true

LlmoPrompt:
  type: object
  description: A prompt configuration within a topic
  required:
    - prompt
    - regions
    - origin
    - source
  properties:
    prompt:
      type: string
      description: The prompt text
      minLength: 1
      example: "What are the latest AI trends?"
    regions:
      type: array
      description: Array of two-letter region codes
      items:
        type: string
        pattern: '^[a-z][a-z]$'
      example: ["us", "eu"]
    origin:
      oneOf:
        - type: string
          enum: ["human", "ai"]
          description: Standard origin types
        - type: string
          description: Custom origin type
          minLength: 1
      example: "human"
    source:
      oneOf:
        - type: string
          enum: ["config", "api"]
          description: Standard source types
        - type: string
          description: Custom source type
          minLength: 1
      example: "config"
  additionalProperties: true

LlmoBrandAlias:
  type: object
  description: A brand alias configuration
  required:
    - aliases
    - category
    - region
  properties:
    aliases:
      type: array
      description: Array of brand alias strings
      items:
        type: string
        minLength: 1
      example: ["Adobe", "Adobe Inc"]
    category:
      type: string
      format: uuid
      description: UUID reference to a category entity
      example: "123e4567-e89b-12d3-a456-426614174000"
    region:
      oneOf:
        - type: string
          pattern: '^[a-z][a-z]$'
          description: Two-letter region code
          example: "us"
        - type: array
          items:
            type: string
            pattern: '^[a-z][a-z]$'
          description: Array of two-letter region codes
          example: ["us", "eu"]

LlmoCompetitor:
  type: object
  description: A competitor configuration
  required:
    - category
    - region
    - name
    - aliases
  properties:
    category:
      type: string
      format: uuid
      description: UUID reference to a category entity
      example: "123e4567-e89b-12d3-a456-426614174000"
    region:
      oneOf:
        - type: string
          pattern: '^[a-z][a-z]$'
          description: Two-letter region code
          example: "us"
        - type: array
          items:
            type: string
            pattern: '^[a-z][a-z]$'
          description: Array of two-letter region codes
          example: ["us", "eu"]
    name:
      type: string
      description: The competitor name
      minLength: 1
      example: "Microsoft"
    aliases:
      type: array
      description: Array of competitor alias strings
      items:
        type: string
        minLength: 1
      example: ["MS", "Microsoft Corp"]
    urls:
      type: array
      description: Array of competitor URLs (optional)
      items:
        type: string
        format: uri
      example: ["https://microsoft.com", "https://office.com"]

LlmoSheetDataQuery:
  type: object
  description: Query parameters for LLMO sheet data
  properties:
    sheets:
      description: Sheets to include from the data
      type: object
      additionalProperties: true
    filters:
      description: Filters to apply to the data
      type: object
    include:
      description: Fields to include from the data
      type: array
      additionalProperties: true
    exclude:
      description: Fields to exclude from the data
      type: array
      items:
        type: string
    groupBy:
      description: Fields to group the data by
      type: array
      items:
        type: string
  additionalProperties: false

# New schemas for entitlements, trial users, and site enrollments APIs
Entitlement:
  type: object
  description: An entitlement represents product access and quotas for an organization

  properties:
    id:
      description: Unique identifier for the entitlement
      $ref: '#/Id'
    organizationId:
      description: Reference to the organization this entitlement belongs to
      $ref: '#/Id'
    productCode:
      description: The product code this entitlement provides access to
      type: string
      enum: [LLMO, ASO, ACO]
    tier:
      description: The tier level of the entitlement
      type: string
      enum: [FREE_TRIAL, PAID]
    quotas:
      description: Usage quotas and limits for the entitlement
      type: object
      properties:
        llmo_trial_prompts:
          type: number
          description: Number of LLMO trial prompts available
    createdAt:
      description: When the entitlement was created
      $ref: '#/DateTime'
    updatedAt:
      description: When the entitlement was last updated
      $ref: '#/DateTime'
    updatedBy:
      description: Who last updated the entitlement
      $ref: '#/Id'

  example:
    id: "123e4567-e89b-12d3-a456-426614174000"
    organizationId: "987fcdeb-51a2-43d7-9876-543210987654"
    productCode: "LLMO"
    tier: "FREE_TRIAL"
    quotas:
      llmo_trial_prompts: 100
    createdAt: "2024-01-15T10:30:00Z"
    updatedAt: "2024-01-15T10:30:00Z"
    updatedBy: "system"

FeatureFlagProduct:
  type: string
  description: Product surface for org-scoped feature flags (matches mysticat enum)
  enum: [ASO, LLMO]

FeatureFlag:
  type: object
  description: Org-scoped boolean feature flag (mysticat `feature_flags`)
  properties:
    id:
      description: Row id (UUIDv7)
      $ref: '#/Id'
    organizationId:
      description: Organization id (SpaceCat / mysticat `organizations.id`)
      $ref: '#/Id'
    product:
      $ref: '#/FeatureFlagProduct'
    flagName:
      description: Stable flag key
      type: string
    flagValue:
      description: Whether the flag is enabled
      type: boolean
    createdAt:
      $ref: '#/DateTime'
    updatedAt:
      $ref: '#/DateTime'
    updatedBy:
      description: IMS user id, service id, or similar; who last changed the row
      oneOf:
        - type: string
        - type: 'null'

FeatureFlagList:
  type: array
  items:
    $ref: '#/FeatureFlag'

AgenticTrafficGlobalWeek:
  type: object
  description: Weekly aggregate global agentic traffic row from mysticat `agentic_traffic_global`
  properties:
    id:
      $ref: '#/Id'
    year:
      type: integer
      minimum: 2000
      maximum: 9999
    week:
      type: integer
      minimum: 1
      maximum: 53
    hits:
      type: integer
      minimum: 0
    createdAt:
      $ref: '#/DateTime'
    updatedAt:
      $ref: '#/DateTime'
    updatedBy:
      oneOf:
        - type: string
        - type: 'null'
  required:
    - id
    - year
    - week
    - hits
    - createdAt
    - updatedAt

AgenticTrafficGlobalWeekList:
  type: array
  items:
    $ref: '#/AgenticTrafficGlobalWeek'

AgenticTrafficGlobalWeekUpsert:
  type: object
  properties:
    year:
      type: integer
      minimum: 2000
      maximum: 9999
    week:
      type: integer
      minimum: 1
      maximum: 53
    hits:
      type: integer
      minimum: 0
  required:
    - year
    - week
    - hits

SiteEnrollment:
  type: object
  description: A site enrollment represents a site's participation in a product or service

  properties:
    id:
      description: Unique identifier for the site enrollment
      $ref: '#/Id'
    siteId:
      description: Reference to the site this enrollment belongs to
      $ref: '#/Id'
    entitlementId:
      description: Reference to the entitlement this enrollment is based on
      $ref: '#/Id'
    createdAt:
      description: When the site enrollment was created
      $ref: '#/DateTime'
    updatedAt:
      description: When the site enrollment was last updated
      $ref: '#/DateTime'
    updatedBy:
      description: Who last updated the site enrollment
      $ref: '#/Id'
  example:
    id: "123e4567-e89b-12d3-a456-426614174000"
    siteId: "987fcdeb-51a2-43d7-9876-543210987654"
    entitlementId: "456e4567-e89b-12d3-a456-426614174000"
    createdAt: "2024-01-15T10:30:00Z"
    updatedAt: "2024-01-15T10:30:00Z"
    updatedBy: "system"

TrialUser:
  type: object
  description: A trial user represents a user participating in a trial program

  properties:
    id:
      description: Unique identifier for the trial user
      $ref: '#/Id'
    organizationId:
      description: Reference to the organization this trial user belongs to
      $ref: '#/Id'
    emailId:
      description: Email ID of the trial user
      type: string
      format: email
      example: 'user123@adobe.com'
    firstName:
      description: First name of the trial user
      type: string
      example: 'John'
    lastName:
      description: Last name of the trial user
      type: string
      example: 'Doe'
    externalUserId:
      description: External user ID from the identity provider
      type: string
      example: '1234567890'
    provider:
      description: The identity provider (IMS, Microsoft, Google, etc.)
      type: string
      example: 'IMS'
    status:
      description: Current status of the trial user
      type: string
      enum: [INVITED, REGISTERED, BLOCKED, DELETED]
    lastSeenAt:
      description: When the trial user was last seen/active
      $ref: '#/DateTime'
    metadata:
      description: Additional metadata for the trial user
      type: object
      properties:
        origin:
          description: Origin information for the trial user (e.g., "INVITED", "SELF_SIGNUP", "PARTNER")
          type: string
          example: "INVITED"
      additionalProperties: true
    createdAt:
      description: When the trial user was created
      $ref: '#/DateTime'
    updatedAt:
      description: When the trial user was last updated
      $ref: '#/DateTime'
    updatedBy:
      description: Who last updated the trial user
      $ref: '#/Id'
  example:
    id: "123e4567-e89b-12d3-a456-426614174000"
    organizationId: "987fcdeb-51a2-43d7-9876-543210987654"
    emailId: "user123@adobe.com"
    firstName: "John"
    lastName: "Doe"
    externalUserId: "1234567890"
    provider: "IMS"
    status: "INVITED"
    lastSeenAt: "2024-01-15T10:30:00Z"
    metadata:
      origin: "INVITED"
    createdAt: "2024-01-15T10:30:00Z"
    updatedAt: "2024-01-15T10:30:00Z"
    updatedBy: "system"

TrialUserActivity:
  type: object
  description: A trial user activity represents an action performed by a trial user

  properties:
    id:
      description: Unique identifier for the trial user activity
      $ref: '#/Id'
    siteId:
      description: Reference to the site where the activity occurred
      $ref: '#/Id'
    trialUserId:
      description: Reference to the trial user who performed the activity
      $ref: '#/Id'
    entitlementId:
      description: Reference to the entitlement associated with this activity
      $ref: '#/Id'
    type:
      description: The type of activity performed
      type: string
      enum: [SIGN_UP, SIGN_IN, CREATE_SITE, RUN_AUDIT, PROMPT_RUN, DOWNLOAD]
      example: 'SIGN_IN'
    details:
      description: Additional details about the activity
      type: object
      additionalProperties: true
      example:
        browser: 'Chrome'
        ip: '192.168.1.1'
    productCode:
      description: The product code associated with the activity
      type: string
      enum: [LLMO, ASO, ACO]
      example: 'LLMO'
    createdAt:
      description: When the activity was recorded
      $ref: '#/DateTime'
    updatedAt:
      description: When the activity was last updated
      $ref: '#/DateTime'
    updatedBy:
      description: Who last updated the activity
      $ref: '#/Id'
  example:
    id: "123e4567-e89b-12d3-a456-426614174000"
    siteId: "987fcdeb-51a2-43d7-9876-543210987654"
    trialUserId: "456e4567-e89b-12d3-a456-426614174000"
    entitlementId: "789e4567-e89b-12d3-a456-426614174000"
    type: "SIGN_IN"
    details:
      browser: "Chrome"
      ip: "192.168.1.1"
    productCode: "LLMO"
    createdAt: "2024-01-15T10:30:00Z"
    updatedAt: "2024-01-15T10:30:00Z"
    updatedBy: "system"

OrganizationIdentityProvider:
  type: object
  description: An organization identity provider represents the mapping between an organization and an identity provider

  properties:
    id:
      description: Unique identifier for the organization identity provider
      $ref: '#/Id'
    organizationId:
      description: Reference to the organization this mapping belongs to
      $ref: '#/Id'
    provider:
      description: The identity provider (IMS, Microsoft, Google, etc.)
      type: string
      example: 'IMS'
    externalId:
      description: External ID from the identity provider
      type: string
      example: 'org123@adobe.com'
    metadata:
      description: Additional metadata for the organization identity provider
      type: object
      properties:
        domain:
          description: Domain associated with the identity provider
          type: string
          example: "adobe.com"
        ssoEnabled:
          description: Whether SSO is enabled for this provider
          type: boolean
          example: true
      additionalProperties: true
    createdAt:
      description: When the identity provider mapping was created
      $ref: '#/DateTime'
    updatedAt:
      description: When the identity provider mapping was last updated
      $ref: '#/DateTime'
    updatedBy:
      description: Who last updated the identity provider mapping
      $ref: '#/Id'
  example:
    id: "123e4567-e89b-12d3-a456-426614174000"
    organizationId: "987fcdeb-51a2-43d7-9876-543210987654"
    provider: "IMS"
    externalId: "org123@adobe.com"
    metadata:
      domain: "adobe.com"
      ssoEnabled: true
    createdAt: "2024-01-15T10:30:00Z"
    updatedAt: "2024-01-15T10:30:00Z"
    updatedBy: "system"

# Sandbox Audit API Schemas
SandboxAuditType:
  type: string
  description: |
    Supported audit types for sandbox environments:
    - meta-tags: General meta tag analysis for all page types
    - product-metatags: Specialized audit for Product Detail Pages (PDP) of commerce sites,
      analyzing product-specific meta tags and scraping SKU, thumbnail, and catalog/store view codes for autofixing
    - commerce-product-enrichments: Commerce page enrichment audit for analyzing and enriching commerce pages
    - alt-text: Alternative text analysis for images
  enum:
    - 'meta-tags'
    - 'product-metatags'
    - 'commerce-product-enrichments'
    - 'alt-text'
  example: 'meta-tags'

SandboxAuditResult:
  type: object
  description: |
    Result of a single sandbox audit. Fields present depend on status:
    - triggered: only auditType and status
    - skipped: includes nextAllowedAt and minutesRemaining
    - failed: includes error message
  required:
    - auditType
    - status
  properties:
    auditType:
      $ref: '#/SandboxAuditType'
    status:
      type: string
      description: Status of the audit
      enum:
        - 'triggered'
        - 'skipped'
        - 'failed'
      example: "triggered"
    nextAllowedAt:
      type: string
      format: date-time
      description: When the audit can be run again (present when status is "skipped")
      example: "2025-08-15T15:37:48.419Z"
    minutesRemaining:
      type: integer
      description: Minutes until the audit can be run again (present when status is "skipped")
      example: 45
    error:
      type: string
      description: Error message (present when status is "failed")
      example: "Failed to enqueue audit job"

SandboxAuditResponse:
  type: object
  description: Response for sandbox audit trigger operation. Same schema used for both success (200) and rate limit (429) responses.
  required:
    - message
    - siteId
    - baseURL
    - results
  properties:
    message:
      type: string
      description: Human-readable summary of operation
      example: "Triggered 2 of 3 audits for https://sandbox.example.com"
    siteId:
      description: The site ID that was audited
      $ref: '#/Id'
    baseURL:
      description: The base URL of the site
      $ref: '#/URL'
    results:
      type: array
      description: Array of audit results
      items:
        $ref: '#/SandboxAuditResult'

Report:
  type: object
  properties:
    id:
      $ref: '#/Id'
      description: Unique identifier for the report
    siteId:
      $ref: '#/Id'
      description: The site ID this report belongs to
    reportType:
      type: string
      enum: [performance, accessibility, seo, security, conversion, cwv, optimization]
      description: The type of report generated
      example: 'performance'
    status:
      type: string
      enum: [processing, success, failed]
      description: Current status of the report
      example: 'success'
    reportPeriod:
      type: object
      properties:
        startDate:
          type: string
          format: date
          description: Start date for the report period
          example: '2024-01-01'
        endDate:
          type: string
          format: date
          description: End date for the report period
          example: '2024-01-31'
      required: [startDate, endDate]
    comparisonPeriod:
      type: object
      properties:
        startDate:
          type: string
          format: date
          description: Start date for comparison period
          example: '2023-12-01'
        endDate:
          type: string
          format: date
          description: End date for comparison period
          example: '2023-12-31'
      required: [startDate, endDate]
    storagePath:
      type: string
      description: Storage path for the report files
      example: 'reports/550e8400-e29b-41d4-a716-446655440000/performance/550e8400-e29b-41d4-a716-446655440001/'
    createdAt:
      $ref: '#/DateTime'
      description: When the report was initially created
    updatedAt:
      $ref: '#/DateTime'
      description: When the report was last updated
    updatedBy:
      type: string
      description: User or system that last updated the report
      example: 'user@adobe.com'
    data:
      type: object
      description: Optional data containing presigned URLs for downloading reports (only present for successful reports)
      properties:
        rawPresignedUrl:
          type: string
          format: uri
          description: Presigned URL for downloading the raw report data
          example: 'https://s3.amazonaws.com/bucket/reports/raw/report.json?signature=...'
        rawPresignedUrlExpiresAt:
          type: string
          format: date-time
          description: Expiration time for the raw report presigned URL
          example: '2024-01-22T10:30:00Z'
        mystiquePresignedUrl:
          type: string
          format: uri
          description: Presigned URL for downloading the enhanced report with AI insights
          example: 'https://s3.amazonaws.com/bucket/reports/mystique/report.json?signature=...'
        mystiquePresignedUrlExpiresAt:
          type: string
          format: date-time
          description: Expiration time for the enhanced report presigned URL
          example: '2024-01-22T10:30:00Z'
      additionalProperties: false
  required: [id, siteId, reportType, status, reportPeriod, createdAt, updatedAt]
  additionalProperties: false

CreatePreflightJobResponse:
  type: object
  properties:
    createdAt:
      type: string
      format: date-time
    jobId:
      type: string
      format: uuid
      description: The ID of the newly created preflight job.
    pollUrl:
      type: string
      format: uri
      description: The URL to poll for the status of the preflight job
    status:
      type: string
      enum: [IN_PROGRESS, COMPLETED, FAILED, CANCELLED]
    error:
      type: object
      description: The error of the preflight job if it failed

PreflightJobResponse:
  type: object
  properties:
    createdAt:
      type: string
      format: date-time
    jobId:
      type: string
      format: uuid
      description: The ID of the preflight job.
    metadata:
      type: object
      description: The metadata of the preflight job
      properties:
        jobType:
          type: string
          enum: [preflight]
        payload:
          type: object
          description: The payload of the preflight job
          properties:
            checks:
              type: array
              items:
                type: string
            siteId:
              type: string
              format: uuid
            step:
              type: string
              enum: [identify, suggest]
            urls:
              type: array
              items:
                type: string
                format: uri
            enableAuthentication:
              type: boolean
        tags:
          type: array
          items:
            type: string
    recordExpiresAt:
      type: integer
      format: int64
      description: Unix epoch seconds for TTL in the database
    startedAt:
      type: string
      format: date-time
    status:
      type: string
      enum: [IN_PROGRESS, COMPLETED, FAILED, CANCELLED]
    updatedAt:
      type: string
      format: date-time
    result:
      type: array
      description: The result of the preflight job if it completed successfully
      items:
        $ref: '#/PreflightResultItem'
    error:
      type: object
      description: The error of the preflight job if it failed

PreflightOpportunityElementSelector:
  type: object
  description: DOM element selector for locating the issue on the page (e.g. for link audits). CSS selector for use with document.querySelector.
  properties:
    selector:
      type: string
      description: CSS selector string (e.g. body > a, cq[data-path="..."], or data-aue-resource for Universal Editor).
  required: [selector]

PreflightOpportunityIssueItem:
  type: object
  description: |
    A single occurrence when the opportunity groups multiple items. Used when opportunity.issue is an array.
    - Links audit (broken-internal-links, broken-external-links): url, issue, seoImpact, seoRecommendation, elements, aiSuggestion, aiRationale.
    - Alt-text audit: src, alt, issue, seoImpact, seoRecommendation.
    All properties are optional; presence depends on audit type.
  properties:
    url:
      type: string
      description: Affected URL (e.g. broken link target). Used by links audit.
    issue:
      type: string
      description: Human-readable description for this occurrence (e.g. "Status 404" for links, or alt-text issue message).
    seoImpact:
      type: string
      description: SEO impact of this occurrence.
    seoRecommendation:
      type: string
      description: Recommendation to fix this occurrence.
    src:
      type: string
      description: Image source URL. Used by alt-text audit.
    alt:
      type: string
      description: Current alt attribute value. Used by alt-text audit.
    elements:
      type: array
      description: DOM element selectors for this occurrence. Used by links audit; format matches PreflightOpportunityElementSelector.
      items:
        $ref: '#/PreflightOpportunityElementSelector'
    aiSuggestion:
      type: string
      description: AI-generated suggestion for this occurrence (e.g. suggested fix URL from suggest step). Used by links audit.
    aiRationale:
      type: string
      description: AI rationale for the suggestion. Used by links audit.

PreflightResultItem:
  type: object
  description: One page's preflight result; each item in the job result array corresponds to one audited page URL.
  properties:
    audits:
      type: array
      description: Audits run for this page (e.g. links, alt-text, metatags, body-size, h1-count).
      items:
        type: object
        properties:
          name:
            type: string
            description: The name of the audit (e.g. links, alt-text, metatags).
          opportunities:
            type: array
            description: Findings for this audit. Each opportunity has a check and an issue (string or array of issue items).
            items:
              type: object
              description: |
                One finding. issue is either a single string (single-summary audits like body-size, lorem-ipsum, h1-count)
                or an array of PreflightOpportunityIssueItem (links, alt-text) with per-item url/issue, and for links
                optionally elements, aiSuggestion, aiRationale.
              properties:
                check:
                  type: string
                  description: The title of the opportunity (e.g. broken-internal-links, missing-alt, meta-description).
                issue:
                  oneOf:
                    - type: string
                      description: |
                        Single issue description. Used when the opportunity has one summary (e.g. body-size,
                        lorem-ipsum, h1-count, headings, metatags).
                    - type: array
                      description: |
                        List of structured issue occurrences. Used by links audit (broken-internal-links,
                        broken-external-links) and alt-text audit; each item is a PreflightOpportunityIssueItem
                        with url/issue/elements/aiSuggestion/aiRationale for links or src/alt/issue for alt-text.
                      items:
                        $ref: '#/PreflightOpportunityIssueItem'
                seoImpact:
                  type: string
                  description: SEO impact of the opportunity (when issue is a string).
                seoRecommendation:
                  type: string
                  description: SEO recommendation for the opportunity (when issue is a string).
                aiSuggestion:
                  type: string
                  description: AI suggestion at opportunity level (when issue is a string).
                aiRationale:
                  type: string
                  description: AI rationale at opportunity level (when issue is a string).
          type:
            type: string
            description: The type/category of the audit (e.g. seo, accessibility).
    pageUrl:
      type: string
      format: uri
      description: The URL of the page that was audited
    profiling:
      type: object
      description: The profiling information of the audit
      properties:
        startTime:
          type: string
          format: date-time
          description: The start time of the audit
        endTime:
          type: string
          format: date-time
          description: The end time of the audit
        total:
          type: string
          description: The total time taken for the audit in seconds
        breakdown:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
                description: The name of the check
              startTime:
                type: string
                format: date-time
                description: The start time of the check
              endTime:
                type: string
                format: date-time
                description: The end time of the check
              duration:
                type: string
                description: The duration of the check in seconds
    step:
      type: string
      enum: [identify, suggest]
# Customer Configuration schemas for brand management
CustomerConfigCategory:
  type: object
  description: A content category (top-level collection)
  required:
    - id
    - name
    - status
  properties:
    id:
      type: string
      description: Unique identifier for the category
      example: "photoshop-photo-editing"
    name:
      type: string
      description: Name of the category
      example: "Photo Editing"
    status:
      type: string
      description: Status of the category
      enum: ["active", "deleted"]
      example: "active"
    origin:
      type: string
      enum: ["ai", "human"]
      description: Source of the category
    updatedAt:
      $ref: '#/DateTime'
      description: When the category was last updated
    updatedBy:
      type: string
      description: Who last updated the category
      example: "system"
CustomerConfigTopic:
  type: object
  description: A topic within a category (top-level collection)
  required:
    - id
    - name
    - status
    - categoryId
  properties:
    id:
      type: string
      description: Unique identifier for the topic
      example: "photoshop-topic-1"
    name:
      type: string
      description: Name of the topic
      example: "Photo Retouching"
    status:
      type: string
      description: Status of the topic
      enum: [active, deleted]
      example: "active"
    categoryId:
      type: string
      description: ID of the category this topic belongs to
      example: "photoshop-photo-editing"
V2PromptListResponse:
  type: object
  description: Paginated list of prompts for a brand
  required:
    - items
    - total
    - limit
    - page
  properties:
    items:
      type: array
      items:
        $ref: '#/V2Prompt'
    total:
      type: integer
      description: Total number of prompts matching the filter
    limit:
      type: integer
      description: Page size (items per page)
    page:
      type: integer
      description: Current page number (1-based)

V2Prompt:
  type: object
  description: A prompt with brand, category, and topic enrichment
  properties:
    id:
      type: string
      description: Business key (prompt_id)
      example: "photoshop-prompt-1"
    uuid:
      type: string
      format: uuid
      description: UUID primary key (prompts.id)
    prompt:
      type: string
      description: The search query prompt text
    name:
      type: string
      description: Display name
    regions:
      type: array
      items:
        type: string
      description: Regions where this prompt is applicable
    categoryId:
      type: string
      description: Category business key
    topicId:
      type: string
      description: Topic business key
    status:
      type: string
      enum: [active, pending, deleted]
      default: active
    origin:
      type: string
      enum: [ai, human]
      default: human
    source:
      type: string
      description: The source system or process that created the prompt
      example: "config"
      default: "config"
    updatedAt:
      $ref: '#/DateTime'
    updatedBy:
      type: string
    brandId:
      type: string
      format: uuid
      description: brands.id (uuid)
    brandName:
      type: string
    category:
      type: object
      properties:
        id:
          type: string
          description: Business key (category_id)
        uuid:
          type: string
          format: uuid
          description: UUID primary key (categories.id)
        name:
          type: string
        origin:
          type: string
    topic:
      type: object
      properties:
        id:
          type: string
          description: Business key (topic_id)
        uuid:
          type: string
          format: uuid
          description: UUID primary key (topics.id)
        name:
          type: string
        categoryId:
          type: string

V2PromptInput:
  type: object
  description: Input for creating/updating a prompt
  required:
    - prompt
  properties:
    id:
      type: string
      description: Optional business key; auto-generated if omitted
    prompt:
      type: string
      description: The search query prompt text
    name:
      type: string
      description: Display name (defaults to prompt slice)
    regions:
      type: array
      items:
        type: string
      default: []
    categoryId:
      type: string
    topicId:
      type: string
    status:
      type: string
      enum: [active, pending, deleted]
      default: active
    origin:
      type: string
      enum: [ai, human]
      default: human
    source:
      type: string
      description: The source system or process that created the prompt
      default: "config"

V2PromptBulkDeleteRequest:
  type: object
  description: Request body for bulk-deleting prompts
  required:
    - promptIds
  properties:
    promptIds:
      type: array
      items:
        type: string
      minItems: 1
      maxItems: 100
      description: Array of prompt business keys to soft-delete

V2PromptBulkDeleteResponse:
  type: object
  description: Response from bulk-deleting prompts
  properties:
    metadata:
      type: object
      properties:
        total:
          type: integer
          description: Total number of prompt IDs in request
        success:
          type: integer
          description: Number of successfully deleted prompts
        failure:
          type: integer
          description: Number of failed deletions
    failures:
      type: array
      items:
        type: object
        properties:
          promptId:
            type: string
          reason:
            type: string

CustomerConfigPrompt:
  type: object
  description: A search prompt with category and topic ID references
  required:
    - id
    - prompt
    - regions
    - categoryId
    - topicId
  properties:
    id:
      type: string
      description: Unique identifier for the prompt
      example: "photoshop-prompt-1"
    prompt:
      type: string
      description: The search query prompt
      example: "What is the best photo editing software for portraits?"
    status:
      type: string
      enum: ["active", "pending", "deleted"]
      description: Status of the prompt
      default: "active"
    regions:
      type: array
      items:
        type: string
      description: Regions where this prompt is applicable
      example: ["us", "gb"]
    origin:
      type: string
      enum: ["ai", "human"]
      description: Source of the prompt (AI-generated or human-created)
      default: "human"
    source:
      type: string
      description: The source system or process that created the prompt
      example: "api"
      default: "config"
    updatedAt:
      $ref: '#/DateTime'
      description: When the prompt was last updated
    updatedBy:
      type: string
      description: Who last updated the prompt
      example: "system"
      default: "system"
    categoryId:
      type: string
      description: ID of the category this prompt belongs to
      example: "photoshop-photo-editing"
    topicId:
      type: string
      description: ID of the topic this prompt belongs to
      example: "photoshop-topic-1"
CustomerConfigUrl:
  type: object
  description: A URL associated with a brand
  required:
    - value
  properties:
    value:
      type: string
      format: uri
      description: The URL
      example: "https://www.adobe.com/products/photoshop.html"
    siteId:
      type: string
      description: Site ID for this URL (used for backwards compatibility with V1)
      example: "a1b2c3d4-5678-90ab-cdef-1234567890ab"
    type:
      type: string
      description: Type of URL
      example: "url"
    regions:
      type: array
      items:
        type: string
      description: Regions where this URL is applicable
      example: ["GL", "US", "GB"]
CustomerConfigSocialAccount:
  type: object
  description: A social media account for a brand
  required:
    - platform
    - url
    - regions
  properties:
    platform:
      type: string
      description: Social media platform name
      example: "twitter"
    url:
      type: string
      format: uri
      description: URL to the social media account
      example: "https://x.com/Photoshop"
    regions:
      type: array
      items:
        type: string
      description: Regions where this account is relevant
      example: ["GL"]
CustomerConfigBrandAlias:
  type: object
  description: An alternative name for a brand
  required:
    - name
    - regions
  properties:
    name:
      type: string
      description: Alternative brand name
      example: "PS"
    regions:
      type: array
      items:
        type: string
      description: Regions where this alias is used
      example: ["US", "GB"]
CustomerConfigCompetitor:
  type: object
  description: A competitor brand
  required:
    - name
    - url
    - regions
  properties:
    name:
      type: string
      description: Competitor brand name
      example: "Affinity Photo"
    url:
      type: string
      format: uri
      description: Competitor website URL
      example: "https://affinity.serif.com/photo"
    regions:
      type: array
      items:
        type: string
      description: Regions where this competitor is relevant
      example: ["US", "GB"]
CustomerConfigRelatedBrand:
  type: object
  description: A related brand (partner, sister brand, etc.)
  required:
    - name
    - url
    - regions
  properties:
    name:
      type: string
      description: Related brand name
      example: "Wacom"
    url:
      type: string
      format: uri
      description: Related brand website URL
      example: "https://www.wacom.com"
    regions:
      type: array
      items:
        type: string
      description: Regions where this relationship is relevant
      example: ["GL"]
CustomerConfigEarnedContent:
  type: object
  description: Earned media content source
  required:
    - name
    - type
    - coverage_scope
    - url
    - regions
  properties:
    name:
      type: string
      description: Name of the media source
      example: "Wikipedia"
    type:
      type: string
      description: Type of media source
      example: "encyclopedia"
    coverage_scope:
      type: string
      description: Description of what this source covers
      example: "product history and feature overview"
    url:
      type: string
      format: uri
      description: URL to the media source
      example: "https://en.wikipedia.org/wiki/Adobe_Photoshop"
    regions:
      type: array
      items:
        type: string
      description: Regions where this source is relevant
      example: ["GL"]
CustomerConfigBrand:
  type: object
  description: A brand configuration with all associated metadata
  required:
    - id
    - name
    - status
    - region
  properties:
    id:
      type: string
      description: Unique identifier for the brand
      example: "pending-adobe-photoshop"
    v1SiteId:
      type: string
      description: Legacy V1 site ID for backwards compatibility
      example: "a1b2c3d4-5678-90ab-cdef-1234567890ab"
    name:
      type: string
      description: Brand name
      example: "Adobe Photoshop"
    status:
      type: string
      enum: ["active", "pending", "deleted"]
      description: Current status of the brand
    origin:
      type: string
      enum: ["ai", "human"]
      description: How the brand was created
    region:
      type: array
      items:
        type: string
      description: Regions where this brand operates
      example: ["GL", "US", "GB"]
    description:
      type: string
      description: Detailed description of the brand
      example: "Adobe's flagship image editing software"
    updatedAt:
      $ref: '#/DateTime'
      description: When the brand was last updated
    updatedBy:
      type: string
      description: Who last updated the brand
      example: "system"
    vertical:
      type: string
      description: Industry vertical for the brand
      example: "Software & Technology"
    urls:
      type: array
      items:
        $ref: '#/CustomerConfigUrl'
      description: URLs associated with the brand
    socialAccounts:
      type: array
      items:
        $ref: '#/CustomerConfigSocialAccount'
      description: Social media accounts for the brand
    brandAliases:
      type: array
      items:
        $ref: '#/CustomerConfigBrandAlias'
      description: Alternative names for the brand
    competitors:
      type: array
      items:
        $ref: '#/CustomerConfigCompetitor'
      description: Competitor brands
    relatedBrands:
      type: array
      items:
        $ref: '#/CustomerConfigRelatedBrand'
      description: Related brands
    earnedContent:
      type: array
      items:
        $ref: '#/CustomerConfigEarnedContent'
      description: Earned media sources
    prompts:
      type: array
      items:
        $ref: '#/CustomerConfigPrompt'
      description: Flat list of all prompts for this brand with category/topic facets
CustomerConfigCustomer:
  type: object
  description: Complete customer configuration including brands and verticals
  required:
    - customerName
    - imsOrgID
    - brands
  properties:
    customerName:
      type: string
      description: Name of the customer organization
      example: "Adobe"
    imsOrgID:
      type: string
      description: Adobe IMS Organization ID
      example: "1234567890ABCDEF@AdobeOrg"
    categories:
      type: array
      items:
        $ref: '#/CustomerConfigCategory'
      description: Top-level collection of categories
    topics:
      type: array
      items:
        $ref: '#/CustomerConfigTopic'
      description: Top-level collection of topics
    brands:
      type: array
      items:
        $ref: '#/CustomerConfigBrand'
      description: List of brands for this customer
    availableVerticals:
      type: array
      items:
        type: string
      description: List of available industry verticals
      example: ["Software & Technology", "Professional Services"]
CustomerConfig:
  type: object
  description: Top-level customer configuration response
  required:
    - customer
  properties:
    customer:
      $ref: '#/CustomerConfigCustomer'
      description: The step of the preflight job when this result was generated

# =============================================================================
# Sentiment Guidelines Schemas
# =============================================================================

SentimentTopic:
  type: object
  description: A sentiment analysis topic defining a subject of interest
  properties:
    siteId:
      type: string
      format: uuid
      description: Parent site identifier
    topicId:
      type: string
      format: uuid
      description: Unique topic identifier
    name:
      type: string
      description: Topic name/subject to analyze
      example: "2026 Corvette Stingray"
    description:
      type: string
      description: Optional description for context
    urls:
      type: array
      description: URLs associated with this topic, each with citation data and sub-prompts
      default: []
      items:
        type: object
        required:
          - url
          - timesCited
        properties:
          url:
            type: string
            description: The URL where the topic was cited
            example: "https://en.wikipedia.org/wiki/BMW_XM"
          timesCited:
            type: integer
            description: Number of times cited on this URL
            example: 12
          category:
            type: string
            description: Classification category for this URL
            example: "automotive"
          subPrompts:
            type: array
            items:
              type: string
            description: Sub-prompts specific to this URL
            default: []
            example: ["What do people say about performance?"]
    enabled:
      type: boolean
      description: Whether topic is active
      default: true
    createdAt:
      type: string
      format: date-time
    updatedAt:
      type: string
      format: date-time
    createdBy:
      type: string
      description: User/service who created
    updatedBy:
      type: string
      description: Last user/service to modify

SentimentTopicInput:
  type: object
  required:
    - name
  properties:
    name:
      type: string
      description: Topic name/subject to analyze
      example: "2026 Corvette Stingray"
    description:
      type: string
      description: Optional description for context
      example: "Track sentiment about the latest Corvette model"
    urls:
      type: array
      description: URLs associated with this topic
      default: []
      items:
        type: object
        required:
          - url
          - timesCited
        properties:
          url:
            type: string
            example: "https://en.wikipedia.org/wiki/BMW_XM"
          timesCited:
            type: integer
            example: 0
          category:
            type: string
            example: "automotive"
          subPrompts:
            type: array
            items:
              type: string
            example: ["What do people say about performance?"]
    enabled:
      type: boolean
      default: true
      example: true

SentimentTopicUpdate:
  type: object
  properties:
    name:
      type: string
    description:
      type: string
    urls:
      type: array
      items:
        type: object
        required:
          - url
          - timesCited
        properties:
          url:
            type: string
          timesCited:
            type: integer
          category:
            type: string
          subPrompts:
            type: array
            items:
              type: string
    enabled:
      type: boolean

SentimentTopicListResponse:
  type: object
  properties:
    items:
      type: array
      items:
        $ref: '#/SentimentTopic'
    pagination:
      type: object
      properties:
        limit:
          type: integer
        cursor:
          type: string
          description: Pagination cursor (absent when no more pages)
        hasMore:
          type: boolean

SentimentTopicBulkResponse:
  type: object
  properties:
    metadata:
      type: object
      properties:
        total:
          type: integer
          description: Total number of items in request
        success:
          type: integer
          description: Number of successfully processed items
        failure:
          type: integer
          description: Number of failed items
    failures:
      type: array
      items:
        type: object
        properties:
          name:
            type: string
          reason:
            type: string
    items:
      type: array
      items:
        $ref: '#/SentimentTopic'

SentimentGuideline:
  type: object
  description: A sentiment analysis guideline defining how to analyze topics
  properties:
    siteId:
      type: string
      format: uuid
      description: Parent site identifier
    guidelineId:
      type: string
      format: uuid
      description: Unique guideline identifier
    name:
      type: string
      description: Display name
      example: "Product Quality Focus"
    instruction:
      type: string
      description: The actual guideline instruction
      example: "Focus on sentiment related to product quality, durability, and craftsmanship."
    audits:
      type: array
      items:
        type: string
      description: Enabled audit types
      example: ["wikipedia-analysis", "reddit-analysis", "youtube-analysis", "cited-analysis"]
    enabled:
      type: boolean
      description: Whether guideline is active
      default: true
    createdAt:
      type: string
      format: date-time
    updatedAt:
      type: string
      format: date-time
    createdBy:
      type: string
      description: User/service who created
    updatedBy:
      type: string
      description: Last user/service to modify

SentimentGuidelineInput:
  type: object
  required:
    - name
    - instruction
  properties:
    name:
      type: string
      description: Display name
      example: "Product Quality Focus"
    instruction:
      type: string
      description: The actual guideline instruction
      example: "Focus on sentiment related to product quality, durability, and craftsmanship."
    audits:
      type: array
      items:
        type: string
      description: Audit types to associate
      example: ["wikipedia-analysis", "reddit-analysis", "youtube-analysis", "cited-analysis"]
    enabled:
      type: boolean
      default: true
      example: true

SentimentGuidelineUpdate:
  type: object
  properties:
    name:
      type: string
    instruction:
      type: string
    audits:
      type: array
      items:
        type: string
    enabled:
      type: boolean

SentimentGuidelineListResponse:
  type: object
  properties:
    items:
      type: array
      items:
        $ref: '#/SentimentGuideline'
    pagination:
      type: object
      properties:
        limit:
          type: integer
        cursor:
          type: string
          description: Pagination cursor (absent when no more pages)
        hasMore:
          type: boolean

SentimentGuidelineBulkResponse:
  type: object
  properties:
    metadata:
      type: object
      properties:
        total:
          type: integer
          description: Total number of items in request
        success:
          type: integer
          description: Number of successfully processed items
        failure:
          type: integer
          description: Number of failed items
    failures:
      type: array
      items:
        type: object
        properties:
          name:
            type: string
          reason:
            type: string
    items:
      type: array
      items:
        $ref: '#/SentimentGuideline'

SentimentConfig:
  type: object
  description: Combined sentiment configuration with topics and guidelines
  properties:
    topics:
      type: array
      items:
        $ref: '#/SentimentTopic'
      description: All enabled topics
    guidelines:
      type: array
      items:
        $ref: '#/SentimentGuideline'
      description: Guidelines (optionally filtered by audit type)

StageDomainsRequest:
  type: object
  description: Request body for adding staging domains to a prod LLMO site
  required:
    - stagingDomains
  properties:
    stagingDomains:
      type: array
      items:
        type: string
        description: Staging domain (hostname, e.g. staging.lovesac.com)
      minItems: 1
      example: ['staging.lovesac.com', 'stage1.lovesac.com']

StageConfigItem:
  type: object
  description: Full edge optimize metaconfig for one stage site (domain plus metaconfig fields)
  required:
    - domain
    - siteId
  properties:
    domain:
      type: string
      description: Staging domain (e.g. staging.lovesac.com)
      example: 'staging.lovesac.com'
    siteId:
      type: string
      format: uuid
      description: Spacecat site ID for the stage site
    apiKeys:
      type: array
      items:
        type: string
      description: API keys for the stage site
    tokowakaEnabled:
      type: boolean
  additionalProperties: true

StageConfigsResponse:
  type: array
  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.
  properties:
    id:
      $ref: '#/Id'
    imsOrgId:
      $ref: '#/ImsOrganizationId'
    domain:
      type: string
      description: The domain being onboarded
      example: "example.com"
    baseURL:
      type: string
      format: uri
      description: The composed base URL for the domain
      example: "https://www.example.com"
    status:
      type: string
      description: Current onboarding status
      enum:
        - PRE_ONBOARDING
        - IN_PROGRESS
        - ONBOARDED
        - ERROR
        - WAITING_FOR_IP_ALLOWLISTING
        - WAITLISTED
        - INACTIVE
      example: "ONBOARDED"
    siteId:
      $ref: '#/Id'
    organizationId:
      $ref: '#/Id'
    steps:
      type: object
      description: Progress tracking for individual onboarding steps
      properties:
        orgResolved:
          type: boolean
          description: Whether the organization was resolved or created
        rumVerified:
          type: boolean
          description: Whether RUM domain key was verified
        siteCreated:
          type: boolean
          description: Whether a new site was created
        siteResolved:
          type: boolean
          description: Whether the site was resolved (created or found)
        configUpdated:
          type: boolean
          description: Whether site configuration was updated
        auditsEnabled:
          type: boolean
          description: Whether audits were enabled for the site
        entitlementCreated:
          type: boolean
          description: Whether the ASO entitlement was provisioned
      additionalProperties: false
      example:
        orgResolved: true
        rumVerified: true
        siteCreated: true
        siteResolved: true
        configUpdated: true
        auditsEnabled: true
        entitlementCreated: true
    error:
      type:
        - object
        - 'null'
      description: Error details if status is ERROR
      properties:
        message:
          type: string
          description: Error message
      example: null
    botBlocker:
      type:
        - object
        - 'null'
      description: Bot blocker details if the site blocks crawling
      properties:
        type:
          type: string
          description: Type of bot blocker detected
        ipsToAllowlist:
          type: array
          items:
            type: string
          description: IPs that need to be allowlisted
        userAgent:
          type: string
          description: User agent string to allowlist
      example: null
    waitlistReason:
      type:
        - string
        - 'null'
      description: Reason for waitlisting, if applicable
      example: null
    reviews:
      type:
        - array
        - 'null'
      description: Array of ESE review decisions for waitlisted onboardings
      items:
        type: object
        properties:
          reason:
            type: string
            description: The waitlist reason at the time of review
          decision:
            type: string
            enum:
              - BYPASSED
              - UPHELD
            description: "BYPASSED: skip check and resume. UPHELD: block stands."
          reviewedBy:
            type: string
            description: Email of the ESE who made the decision
          reviewedAt:
            type: string
            format: date-time
            description: Timestamp of the review
          justification:
            type: string
            description: ESE's reason for the decision
      example: null
    completedAt:
      $ref: '#/DateTime'
    createdAt:
      $ref: '#/DateTime'
    updatedAt:
      $ref: '#/DateTime'

Token:
  type: object
  description: A token allocation for a site within a billing cycle
  properties:
    id:
      $ref: '#/Id'
    siteId:
      $ref: '#/Id'
    tokenType:
      type: string
      description: Token type key, e.g. `grant_cwv`, `grant_broken_backlinks`
      example: grant_cwv
    cycle:
      type: string
      description: Billing cycle identifier, e.g. `2025-03`
      example: '2025-03'
    total:
      type: integer
      description: Total tokens allocated for this cycle
      example: 3
    used:
      type: integer
      description: Tokens consumed so far in this cycle
      example: 1
    remaining:
      type: integer
      description: Tokens remaining (total - used)
      example: 2
    createdAt:
      $ref: '#/DateTime'
    updatedAt:
      $ref: '#/DateTime'
  required:
    - id
    - siteId
    - tokenType
    - cycle
    - total
    - used
    - remaining
    - createdAt
    - updatedAt

PresignedUrlResponse:
  type: object
  description: A short-lived presigned S3 URL and its expiry time
  properties:
    presignedUrl:
      type: string
      format: uri
      description: Presigned S3 URL to download the resource
    expiresAt:
      type: string
      format: date-time
      description: ISO 8601 timestamp when the presigned URL expires
      example: '2026-06-15T12:00:00.000Z'
  required:
    - presignedUrl
    - expiresAt
  additionalProperties: false

# ── V2 Brand schemas (PostgREST-backed, /v2/orgs/{spaceCatId}/brands) ──

V2BrandUrl:
  type: object
  properties:
    value:
      type: string
      description: Full URL (base URL + optional path)
      example: 'https://www.example.com/products'
  required:
    - value

V2BrandSocialAccount:
  type: object
  properties:
    url:
      type: string
      description: Social media account URL
      example: 'https://twitter.com/example'
    regions:
      type: array
      items:
        type: string
      description: ISO-3166 country codes this account targets
      example: ['US', 'DE']

V2BrandEarnedContent:
  type: object
  properties:
    name:
      type: string
      description: Name of the earned content source
      example: 'TechCrunch'
    url:
      type: string
      description: URL of the earned content source
      example: 'https://techcrunch.com/example'
    regions:
      type: array
      items:
        type: string
      description: ISO-3166 country codes
      example: ['US']

V2BrandAlias:
  type: object
  properties:
    name:
      type: string
      description: Alias name for the brand
      example: 'Example Corp'
    regions:
      type: array
      items:
        type: string
      description: ISO-3166 country codes
      example: ['US']

V2BrandCompetitor:
  type: object
  properties:
    name:
      type: string
      description: Competitor name
      example: 'Acme Inc'
    url:
      type:
        - string
        - 'null'
      description: Competitor URL
      example: 'https://www.acme.com'
    regions:
      type: array
      items:
        type: string
      description: ISO-3166 country codes
      example: ['US']

V2Brand:
  type: object
  description: A brand managed via the v2 PostgREST-backed API
  properties:
    id:
      type: string
      format: uuid
      description: Brand UUID
    name:
      type: string
      description: Brand name (unique per organization)
    status:
      type: string
      enum: [active, pending, deleted]
      description: Brand status
      default: active
    origin:
      type: string
      enum: [human, ai]
      description: How the brand was created
      default: human
    description:
      type:
        - string
        - 'null'
      description: Brand description
    vertical:
      type:
        - string
        - 'null'
      description: Industry vertical
    region:
      type: array
      items:
        type: string
      description: ISO-3166 country codes the brand targets
    urls:
      type: array
      items:
        $ref: '#/V2BrandUrl'
      description: Brand site URLs (derived from brand_sites)
    socialAccounts:
      type: array
      items:
        $ref: '#/V2BrandSocialAccount'
    earnedContent:
      type: array
      items:
        $ref: '#/V2BrandEarnedContent'
    brandAliases:
      type: array
      items:
        $ref: '#/V2BrandAlias'
    competitors:
      type: array
      items:
        $ref: '#/V2BrandCompetitor'
    siteIds:
      type: array
      items:
        type: string
        format: uuid
      description: IDs of sites linked to this brand (read-only, derived from brand_sites)
    updatedAt:
      $ref: '#/DateTime'
    updatedBy:
      type:
        - string
        - 'null'
      description: Email of the user who last modified the brand
  required:
    - id
    - name
    - status
    - origin
    - region
    - urls
    - socialAccounts
    - earnedContent
    - brandAliases
    - competitors
    - siteIds
    - updatedAt
  example:
    id: 'a1b2c3d4-5678-90ab-cdef-1234567890ab'
    name: 'Example Brand'
    status: 'active'
    origin: 'human'
    description: 'An example brand'
    vertical: 'technology'
    region: ['US', 'DE']
    urls:
      - value: 'https://www.example.com'
      - value: 'https://www.example.com/products'
    socialAccounts:
      - url: 'https://twitter.com/example'
        regions: ['US']
    earnedContent:
      - name: 'TechCrunch'
        url: 'https://techcrunch.com/example'
        regions: ['US']
    brandAliases:
      - name: 'Example Corp'
        regions: ['US']
    competitors:
      - name: 'Acme Inc'
        url: 'https://www.acme.com'
        regions: ['US']
    siteIds: ['b2c3d4e5-6789-01ab-cdef-2345678901ab']
    updatedAt: '2026-03-15T10:30:00Z'
    updatedBy: 'user@adobe.com'

V2BrandInput:
  type: object
  description: Request body for creating a brand. Upserts on conflict (organization_id, name).
  required:
    - name
  properties:
    name:
      type: string
      description: Brand name (unique per organization, used as upsert key)
    status:
      type: string
      enum: [active, pending]
      default: active
    origin:
      type: string
      enum: [human, ai]
      default: human
    description:
      type: string
    vertical:
      type: string
    region:
      type: array
      items:
        type: string
    urls:
      type: array
      items:
        $ref: '#/V2BrandUrl'
    socialAccounts:
      type: array
      items:
        $ref: '#/V2BrandSocialAccount'
    earnedContent:
      type: array
      items:
        $ref: '#/V2BrandEarnedContent'
    brandAliases:
      type: array
      items:
        $ref: '#/V2BrandAlias'
    competitors:
      type: array
      items:
        $ref: '#/V2BrandCompetitor'

V2BrandUpdateInput:
  type: object
  description: Request body for updating a brand. All fields are optional.
  properties:
    name:
      type: string
    status:
      type: string
      enum: [active, pending]
    origin:
      type: string
      enum: [human, ai]
    description:
      type: string
    vertical:
      type: string
    region:
      type: array
      items:
        type: string
    urls:
      type: array
      items:
        $ref: '#/V2BrandUrl'
    socialAccounts:
      type: array
      items:
        $ref: '#/V2BrandSocialAccount'
    earnedContent:
      type: array
      items:
        $ref: '#/V2BrandEarnedContent'
    brandAliases:
      type: array
      items:
        $ref: '#/V2BrandAlias'
    competitors:
      type: array
      items:
        $ref: '#/V2BrandCompetitor'

V2BrandListResponse:
  type: object
  description: Response envelope for listing brands
  required:
    - brands
  properties:
    brands:
      type: array
      items:
        $ref: '#/V2Brand'

V2Topic:
  type: object
  description: A topic in the normalized topics table
  required:
    - id
    - uuid
    - name
    - status
  properties:
    id:
      type: string
      description: Topic business key (topic_id)
      example: 'baseurl-discovery-research-topic'
    uuid:
      type: string
      format: uuid
      description: UUID primary key (topics.id)
    name:
      type: string
      description: Human-readable topic name
      example: 'Discovery & Research'
    description:
      type:
        - string
        - 'null'
      description: Optional topic description
    status:
      type: string
      enum: [active, pending, deleted, ignored]
      description: Topic status
      example: 'active'
    brandId:
      type:
        - string
        - 'null'
      format: uuid
      description: Optional brand UUID this topic belongs to
    updatedAt:
      type: string
      format: date-time
      description: Last update timestamp
    updatedBy:
      type: string
      description: User or system that last updated the topic

V2TopicInput:
  type: object
  description: Request body for creating a topic
  required:
    - name
  properties:
    id:
      type: string
      description: Topic business key. Auto-generated from name if omitted.
      example: 'baseurl-discovery-research-topic'
    name:
      type: string
      description: Human-readable topic name
      example: 'Discovery & Research'
    description:
      type: string
      description: Optional topic description
    brandId:
      type: string
      format: uuid
      description: Optional brand UUID this topic belongs to
    status:
      type: string
      enum: [active, pending, ignored]
      default: 'active'

V2TopicUpdateInput:
  type: object
  description: Request body for updating a topic (partial update)
  properties:
    name:
      type: string
      description: Human-readable topic name
    description:
      type: string
      description: Optional topic description
    status:
      type: string
      enum: [active, pending, deleted, ignored]
    brandId:
      type: string
      format: uuid
      description: Optional brand UUID

V2TopicListResponse:
  type: object
  description: Response envelope for listing topics
  required:
    - topics
  properties:
    topics:
      type: array
      items:
        $ref: '#/V2Topic'

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'