openapi: 3.1.0
paths:
  /v1/click/sessions:
    post:
      operationId: createSession
      summary: Create a click session
      parameters: []
      responses:
        '201':
          description: Session created successfully
          headers:
            X-Request-Id: &ref_0
              $ref: '#/components/headers/X-Request-Id'
            traceparent: &ref_1
              $ref: '#/components/headers/traceparent'
        '404':
          description: Template not found
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
      tags:
        - Click
      security:
        - bearer:
            - click:write
  /v1/click/sessions/{id}:
    get:
      operationId: getSession
      summary: Get a click session
      parameters:
        - name: id
          required: true
          in: path
          description: Session ID
          schema:
            type: string
      responses:
        '200':
          description: Session details
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
        '404':
          description: Session not found
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
      tags:
        - Click
      security:
        - bearer:
            - click:read
  /v1/click/sessions/{id}/complete:
    post:
      operationId: completeSession
      summary: Complete a click session
      parameters:
        - name: id
          required: true
          in: path
          description: Session ID
          schema:
            type: string
      responses:
        '200':
          description: Session completed successfully
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
        '404':
          description: Session not found
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
      tags:
        - Click
      security:
        - bearer:
            - click:write
  /v1/click/evidence/{sessionId}:
    get:
      operationId: getClickEvidenceBundle
      summary: Get evidence bundle for a session
      parameters:
        - name: sessionId
          required: true
          in: path
          description: Session ID
          schema:
            type: string
      responses:
        '200':
          description: Evidence bundle details
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
        '404':
          description: Evidence not found
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
      tags:
        - Click
      security:
        - bearer:
            - click:read
  /v1/click/consent/{userRef}:
    get:
      operationId: getUserConsentState
      summary: Get user consent state
      parameters:
        - name: userRef
          required: true
          in: path
          description: User reference
          schema:
            type: string
      responses:
        '200':
          description: Current consent state
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
      tags:
        - Click
      security:
        - bearer:
            - click:read
    post:
      operationId: updateUserConsentState
      summary: Update user consent state
      parameters:
        - name: userRef
          required: true
          in: path
          description: User reference
          schema:
            type: string
      responses:
        '200':
          description: Consent updated successfully
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
      tags:
        - Click
      security:
        - bearer:
            - click:write
  /v1/click/templates:
    get:
      operationId: findAllTemplates
      summary: List all templates
      parameters:
        - name: includeVersions
          required: false
          in: query
          schema:
            type: boolean
      responses:
        '200':
          description: Templates retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TemplateResponseDto'
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
      tags:
        - Templates
      security:
        - bearer:
            - click:read
    post:
      operationId: createTemplate
      summary: Create a new template
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTemplateDto'
      responses:
        '201':
          description: Template created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplateResponseDto'
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
        '409':
          description: Template slug already exists
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
      tags:
        - Templates
      security:
        - bearer:
            - click:write
  /v1/click/templates/{id}:
    get:
      operationId: findOneTemplate
      summary: Get a specific template
      parameters:
        - name: id
          required: true
          in: path
          description: Template ID
          schema:
            type: string
        - name: includeVersions
          required: false
          in: query
          schema:
            type: boolean
      responses:
        '200':
          description: Template retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplateResponseDto'
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
        '404':
          description: Template not found
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
      tags:
        - Templates
      security:
        - bearer:
            - click:read
    patch:
      operationId: updateTemplate
      summary: Update a template
      parameters:
        - name: id
          required: true
          in: path
          description: Template ID
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateTemplateDto'
      responses:
        '200':
          description: Template updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplateResponseDto'
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
        '404':
          description: Template not found
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
        '409':
          description: Template slug already exists
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
      tags:
        - Templates
      security:
        - bearer:
            - click:write
    delete:
      operationId: removeTemplate
      summary: Delete a template
      parameters:
        - name: id
          required: true
          in: path
          description: Template ID
          schema:
            type: string
      responses:
        '204':
          description: Template deleted successfully
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
        '400':
          description: Cannot delete template with active deployments
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
        '404':
          description: Template not found
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
      tags:
        - Templates
      security:
        - bearer:
            - click:admin
  /v1/click/templates/{id}/stats:
    get:
      operationId: getTemplateStats
      summary: Get template statistics
      parameters:
        - name: id
          required: true
          in: path
          description: Template ID
          schema:
            type: string
      responses:
        '200':
          description: Template statistics retrieved successfully
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
        '404':
          description: Template not found
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
      tags:
        - Templates
      security:
        - bearer:
            - click:read
  /v1/click/templates/{templateId}/versions:
    get:
      operationId: findAllVersions
      summary: List all versions for a template
      parameters:
        - name: templateId
          required: true
          in: path
          description: Template ID
          schema:
            type: string
        - name: includeTemplate
          required: false
          in: query
          schema:
            type: boolean
        - name: includeDeployments
          required: false
          in: query
          schema:
            type: boolean
      responses:
        '200':
          description: Template versions retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TemplateVersionResponseDto'
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
        '404':
          description: Template not found
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
      tags:
        - Templates
      security:
        - bearer:
            - click:read
    post:
      operationId: createVersion
      summary: Create a new template version
      parameters:
        - name: templateId
          required: true
          in: path
          description: Template ID
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTemplateVersionDto'
      responses:
        '201':
          description: Template version created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplateVersionResponseDto'
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
        '404':
          description: Template not found
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
        '409':
          description: Version already exists for this locale
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
      tags:
        - Templates
      security:
        - bearer:
            - click:write
  /v1/click/templates/{templateId}/versions/published:
    get:
      operationId: findPublishedVersions
      summary: List published versions for a template
      parameters:
        - name: templateId
          required: true
          in: path
          description: Template ID
          schema:
            type: string
      responses:
        '200':
          description: Published template versions retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TemplateVersionResponseDto'
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
        '404':
          description: Template not found
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
      tags:
        - Templates
      security:
        - bearer:
            - click:read
  /v1/click/templates/{templateId}/versions/{versionId}:
    get:
      operationId: findOneVersion
      summary: Get a specific template version
      parameters:
        - name: templateId
          required: true
          in: path
          description: Template ID
          schema:
            type: string
        - name: versionId
          required: true
          in: path
          description: Version ID
          schema:
            type: string
        - name: includeTemplate
          required: false
          in: query
          schema:
            type: boolean
        - name: includeDeployments
          required: false
          in: query
          schema:
            type: boolean
      responses:
        '200':
          description: Template version retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplateVersionResponseDto'
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
        '404':
          description: Template or version not found
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
      tags:
        - Templates
      security:
        - bearer:
            - click:read
    patch:
      operationId: updateVersion
      summary: Update a template version
      parameters:
        - name: templateId
          required: true
          in: path
          description: Template ID
          schema:
            type: string
        - name: versionId
          required: true
          in: path
          description: Version ID
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateTemplateVersionDto'
      responses:
        '200':
          description: Template version updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplateVersionResponseDto'
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
        '400':
          description: Cannot modify published versions
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
        '404':
          description: Template or version not found
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
        '409':
          description: Version already exists for this locale
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
      tags:
        - Templates
      security:
        - bearer:
            - click:write
  /v1/click/templates/{templateId}/versions/{versionId}/publish:
    post:
      operationId: publishVersion
      summary: Publish or unpublish a template version
      parameters:
        - name: templateId
          required: true
          in: path
          description: Template ID
          schema:
            type: string
        - name: versionId
          required: true
          in: path
          description: Version ID
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublishTemplateVersionDto'
      responses:
        '200':
          description: Template version published successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplateVersionResponseDto'
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
        '400':
          description: Cannot publish archived versions
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
        '404':
          description: Template or version not found
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
      tags:
        - Templates
      security:
        - bearer:
            - click:write
  /v1/click/templates/{templateId}/versions/{versionId}/archive:
    post:
      operationId: archiveVersion
      summary: Archive a template version
      parameters:
        - name: templateId
          required: true
          in: path
          description: Template ID
          schema:
            type: string
        - name: versionId
          required: true
          in: path
          description: Version ID
          schema:
            type: string
      responses:
        '200':
          description: Template version archived successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplateVersionResponseDto'
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
        '400':
          description: Cannot archive version with active deployments
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
        '404':
          description: Template or version not found
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
      tags:
        - Templates
      security:
        - bearer:
            - click:admin
  /v1/click/templates/types:
    get:
      operationId: getTemplateTypes
      summary: Get available template types
      description: Returns all available template types with their configurations
      parameters: []
      responses:
        '200':
          description: List of template types with configurations
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
      tags:
        - Templates
      security:
        - bearer:
            - click:read
  /v1/click/templates/{id}/configuration:
    get:
      operationId: getTemplateConfiguration
      summary: Get template configuration
      description: Returns template configuration including type config and policy flags
      parameters:
        - name: id
          required: true
          in: path
          description: Template ID
          schema:
            type: string
      responses:
        '200':
          description: Template configuration details
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
      tags:
        - Templates
      security:
        - bearer:
            - click:read
  /v1/click/templates/{id}/policy-flags:
    post:
      operationId: applyPolicyFlags
      summary: Apply policy flags to template
      description: Updates template policy flags with validation
      parameters:
        - name: id
          required: true
          in: path
          description: Template ID
          schema:
            type: string
      responses:
        '200':
          description: Policy flags applied successfully
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
      tags:
        - Templates
      security:
        - bearer:
            - click:write
  /v1/click/templates/{id}/verification-requirements:
    get:
      operationId: getVerificationRequirements
      summary: Get template verification requirements
      description: Returns what verification methods are required for this template
      parameters:
        - name: id
          required: true
          in: path
          description: Template ID
          schema:
            type: string
      responses:
        '200':
          description: Verification requirements
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
      tags:
        - Templates
      security:
        - bearer:
            - click:read
  /v1/click/templates/validate-content:
    post:
      operationId: validateContent
      summary: Validate template content
      description: >-
        Validates template content against type-specific rules. `type` is
        REQUIRED and identifies which validation ruleset to apply.
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - type
                - content
              properties:
                type:
                  type: string
                  enum:
                    - STATIC
                    - GENERATED
                    - CONSENT
                  description: Template type to validate against
                content:
                  type: string
                  description: The template content to validate
                format:
                  type: string
                  description: Content format (defaults to `html`)
                  default: html
      responses:
        '200':
          description: Validation result (`{ valid, errors }`)
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
        '400':
          description: Missing required body fields (e.g. `type`)
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
      tags:
        - Templates
      security:
        - bearer:
            - click:read
  /v1/click/templates/bulk/archive:
    post:
      operationId: bulkArchiveTemplates
      summary: Bulk archive templates
      description: >-
        Marks every listed template as `ARCHIVED`. Partial-success: foreign-org
        IDs and templates with active deployments are returned in `skipped[]`
        rather than failing the whole batch. Foreign-org IDs are reported as
        `not_found` — the response never confirms cross-tenant existence.
        Requires the `click:admin` scope.
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - templateIds
              properties:
                templateIds:
                  type: array
                  description: Template UUIDs to archive (1–100).
                  minItems: 1
                  maxItems: 100
                  items:
                    type: string
                    format: uuid
      responses:
        '200':
          description: Archive summary
          content:
            application/json:
              schema:
                type: object
                required:
                  - archived
                  - skipped
                properties:
                  archived:
                    type: integer
                    description: Number of templates whose status flipped to ARCHIVED.
                  skipped:
                    type: array
                    description: Templates that were not archived, with reason per entry.
                    items:
                      type: object
                      required:
                        - id
                        - reason
                      properties:
                        id:
                          type: string
                          format: uuid
                        reason:
                          type: string
                          enum:
                            - not_found
                            - has_active_deployments
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
        '400':
          description: Invalid payload (e.g. malformed UUID, count out of range)
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
        '401':
          description: Missing or invalid authentication
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
        '403':
          description: Authenticated principal does not satisfy the `click:admin` scope
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
      tags:
        - Templates
      security:
        - bearer:
            - click:admin
  /v1/click/templates/bulk/duplicate:
    post:
      operationId: bulkDuplicateTemplates
      summary: Bulk duplicate templates
      description: >-
        Shallow-clones each listed template as a new `DRAFT`. Optional
        `namePattern` uses the `{name}` placeholder — defaults to `"{name}
        (copy)"`. Each duplicate starts a fresh version chain and inherits no
        audit identity from the source. Foreign-org IDs are reported as
        `not_found`. Requires the `click:admin` scope.
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - templateIds
              properties:
                templateIds:
                  type: array
                  description: Source template UUIDs to duplicate (1–50).
                  minItems: 1
                  maxItems: 50
                  items:
                    type: string
                    format: uuid
                namePattern:
                  type: string
                  description: >-
                    Optional naming template. Use `{name}` as the placeholder
                    for the source template name (e.g. `"EU - {name}"`).
                    Defaults to `"{name} (copy)"`.
                  maxLength: 255
      responses:
        '200':
          description: Duplicate summary
          content:
            application/json:
              schema:
                type: object
                required:
                  - duplicates
                  - skipped
                properties:
                  duplicates:
                    type: array
                    description: Successfully created duplicates.
                    items:
                      type: object
                      required:
                        - sourceId
                        - newId
                        - name
                      properties:
                        sourceId:
                          type: string
                          format: uuid
                        newId:
                          type: string
                          format: uuid
                        name:
                          type: string
                  skipped:
                    type: array
                    description: Source IDs that were not duplicated.
                    items:
                      type: object
                      required:
                        - id
                        - reason
                      properties:
                        id:
                          type: string
                          format: uuid
                        reason:
                          type: string
                          enum:
                            - not_found
                            - slug_conflict
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
        '400':
          description: Invalid payload
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
        '401':
          description: Missing or invalid authentication
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
        '403':
          description: Authenticated principal does not satisfy the `click:admin` scope
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
      tags:
        - Templates
      security:
        - bearer:
            - click:admin
  /v1/click/templates/{templateId}/versions/{versionAId}/diff/{versionBId}:
    get:
      operationId: compareTemplateVersions
      summary: Compare two template versions
      description: >-
        Returns a structured field-level diff between two versions of the same
        template. Useful for review UIs surfacing what changed between drafts or
        between a draft and its published counterpart. Body changes are reported
        as line-level adds/removes; metadata changes are reported as key sets.
      parameters:
        - name: templateId
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: versionAId
          in: path
          required: true
          schema:
            type: string
        - name: versionBId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Version diff
          content:
            application/json:
              schema:
                type: object
                required:
                  - versionA
                  - versionB
                  - anyChanges
                  - title
                  - format
                  - published
                  - checksum
                  - content
                  - metadata
                properties:
                  versionA:
                    type: object
                    required:
                      - id
                      - version
                      - locale
                      - title
                      - format
                      - published
                      - checksum
                      - updatedAt
                    properties:
                      id:
                        type: string
                      version:
                        type: string
                      locale:
                        type: string
                      title:
                        type: string
                      format:
                        type: string
                      published:
                        type: boolean
                      checksum:
                        type: string
                      updatedAt:
                        type: string
                        format: date-time
                  versionB:
                    type: object
                    required:
                      - id
                      - version
                      - locale
                      - title
                      - format
                      - published
                      - checksum
                      - updatedAt
                    properties:
                      id:
                        type: string
                      version:
                        type: string
                      locale:
                        type: string
                      title:
                        type: string
                      format:
                        type: string
                      published:
                        type: boolean
                      checksum:
                        type: string
                      updatedAt:
                        type: string
                        format: date-time
                  anyChanges:
                    type: boolean
                  title:
                    type: object
                    required:
                      - changed
                    properties:
                      changed:
                        type: boolean
                      a:
                        type: string
                      b:
                        type: string
                  format:
                    type: object
                    required:
                      - changed
                    properties:
                      changed:
                        type: boolean
                      a:
                        type: string
                      b:
                        type: string
                  published:
                    type: object
                    required:
                      - changed
                    properties:
                      changed:
                        type: boolean
                      a:
                        type: boolean
                      b:
                        type: boolean
                  checksum:
                    type: object
                    required:
                      - changed
                    properties:
                      changed:
                        type: boolean
                      a:
                        type: string
                      b:
                        type: string
                  content:
                    type: object
                    required:
                      - changed
                      - addedLines
                      - removedLines
                    properties:
                      changed:
                        type: boolean
                      addedLines:
                        type: array
                        items:
                          type: string
                      removedLines:
                        type: array
                        items:
                          type: string
                  metadata:
                    type: object
                    required:
                      - changed
                      - addedKeys
                      - removedKeys
                      - changedKeys
                    properties:
                      changed:
                        type: boolean
                      addedKeys:
                        type: array
                        items:
                          type: string
                      removedKeys:
                        type: array
                        items:
                          type: string
                      changedKeys:
                        type: array
                        items:
                          type: string
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
        '404':
          description: Template or one of the versions was not found
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
      tags:
        - Templates
      security:
        - bearer:
            - click:read
  /v1/click/deployments:
    get:
      operationId: findAllDeployments
      summary: List all deployments
      parameters:
        - name: siteId
          required: false
          in: query
          description: Filter by site ID
          schema:
            type: string
        - name: environment
          required: false
          in: query
          description: Filter by environment
          schema:
            type: string
        - name: active
          required: false
          in: query
          description: Filter by active status
          schema:
            type: boolean
        - name: includeSite
          required: false
          in: query
          description: Include site details
          schema:
            type: boolean
        - name: includeTemplateVersion
          required: false
          in: query
          description: Include template version details
          schema:
            type: boolean
      responses:
        '200':
          description: Deployments retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DeploymentResponseDto'
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
      tags:
        - Deployments
      security:
        - bearer:
            - click:read
    post:
      operationId: createDeployment
      summary: Create a new deployment
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDeploymentDto'
      responses:
        '201':
          description: Deployment created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeploymentResponseDto'
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
        '400':
          description: Invalid deployment data
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
        '404':
          description: Site or template version not found
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
        '409':
          description: Deployment already exists for this combination
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
      tags:
        - Deployments
      security:
        - bearer:
            - click:write
  /v1/click/deployments/domain/{domain}/active:
    get:
      operationId: findActiveByDomain
      summary: Get active deployments for a domain
      parameters:
        - name: domain
          required: true
          in: path
          description: Domain
          schema:
            type: string
        - name: environment
          required: false
          in: query
          description: Filter by environment
          schema:
            type: string
      responses:
        '200':
          description: Active deployments retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DeploymentResponseDto'
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
      tags:
        - Deployments
      security:
        - bearer:
            - click:read
  /v1/click/deployments/{id}:
    get:
      operationId: findOneDeployment
      summary: Get a specific deployment
      parameters:
        - name: id
          required: true
          in: path
          description: Deployment ID
          schema:
            type: string
        - name: includeSite
          required: false
          in: query
          description: Include site details
          schema:
            type: boolean
        - name: includeTemplateVersion
          required: false
          in: query
          description: Include template version details
          schema:
            type: boolean
      responses:
        '200':
          description: Deployment retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeploymentResponseDto'
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
        '404':
          description: Deployment not found
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
      tags:
        - Deployments
      security:
        - bearer:
            - click:read
    patch:
      operationId: updateDeployment
      summary: Update a deployment
      parameters:
        - name: id
          required: true
          in: path
          description: Deployment ID
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateDeploymentDto'
      responses:
        '200':
          description: Deployment updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeploymentResponseDto'
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
        '400':
          description: Invalid deployment data
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
        '404':
          description: Deployment not found
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
        '409':
          description: Deployment already exists for this combination
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
      tags:
        - Deployments
      security:
        - bearer:
            - click:write
    delete:
      operationId: removeDeployment
      summary: Delete a deployment
      parameters:
        - name: id
          required: true
          in: path
          description: Deployment ID
          schema:
            type: string
      responses:
        '204':
          description: Deployment deleted successfully
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
        '404':
          description: Deployment not found
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
      tags:
        - Deployments
      security:
        - bearer:
            - click:admin
  /v1/click/deployments/domain/{domain}/deactivate:
    post:
      operationId: deactivateByPath
      summary: Deactivate deployments by path
      parameters:
        - name: domain
          required: true
          in: path
          description: Domain
          schema:
            type: string
        - name: environment
          required: true
          in: query
          description: Environment
          schema:
            type: string
        - name: path
          required: true
          in: query
          description: Path to deactivate
          schema:
            type: string
      responses:
        '200':
          description: Deployments deactivated successfully
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
      tags:
        - Deployments
      security:
        - bearer:
            - click:admin
  /v1/click/analytics/dashboard:
    get:
      operationId: getDashboardMetrics
      summary: Get dashboard analytics and metrics
      parameters: []
      responses:
        '200':
          description: Dashboard metrics retrieved successfully
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
      tags:
        - Analytics
      security:
        - bearer:
            - click:read
  /v1/click/analytics/acceptance:
    get:
      operationId: getAcceptanceAnalytics
      summary: Get acceptance analytics
      parameters:
        - name: templateId
          required: true
          in: query
          schema:
            type: string
        - name: from
          required: true
          in: query
          schema:
            type: string
        - name: to
          required: true
          in: query
          schema:
            type: string
        - name: groupBy
          required: true
          in: query
          schema:
            type: string
        - name: timeRange
          required: true
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Acceptance analytics retrieved successfully
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
      tags:
        - Analytics
      security:
        - bearer:
            - click:read
  /v1/click/acceptances:
    get:
      operationId: getAcceptances
      parameters: []
      responses:
        '200':
          description: ''
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
      security:
        - bearer:
            - click:read
      tags:
        - Acceptances
  /v1/click/acceptances/{id}:
    get:
      operationId: getAcceptance
      parameters:
        - name: id
          required: true
          in: path
          schema:
            type: string
        - name: includeEvidence
          required: true
          in: query
          schema:
            type: string
        - name: includeReceipt
          required: true
          in: query
          schema:
            type: string
      responses:
        '200':
          description: ''
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
      security:
        - bearer:
            - click:read
      tags:
        - Acceptances
  /v1/click/acceptances/{id}/evidence:
    get:
      operationId: getEvidenceBundle
      parameters:
        - name: id
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: ''
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
      security:
        - bearer:
            - click:read
      tags:
        - Acceptances
  /v1/click/receipts/{receiptId}:
    get:
      operationId: getReceipt
      parameters:
        - name: receiptId
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: ''
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
      security:
        - bearer:
            - click:read
      tags:
        - Acceptances
  /v1/click/evidence/retention/status:
    get:
      operationId: getRetentionStatus
      parameters: []
      responses:
        '200':
          description: ''
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
      security:
        - bearer:
            - click:read
      tags:
        - Acceptances
  /v1/click/acceptances/{id}/screenshot:
    get:
      operationId: getScreenshot
      parameters:
        - name: id
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: ''
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
      security:
        - bearer:
            - click:read
      tags:
        - Acceptances
  /v1/click/organization/settings:
    get:
      operationId: getSettings
      summary: Get organization settings
      description: >-
        Retrieve organization settings including retention policies, PII mode,
        and default policy flags
      parameters: []
      responses:
        '200':
          description: Organization settings retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationSettingsDto'
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
        '404':
          description: Organization not found
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
      tags:
        - Organization
      security:
        - bearer:
            - click:read
    patch:
      operationId: updateSettings
      summary: Update organization settings
      description: >-
        Update organization settings such as retention policies, PII mode, and
        default policy flags
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateOrganizationSettingsDto'
      responses:
        '200':
          description: Organization settings updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationSettingsDto'
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
        '400':
          description: Invalid input data
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
        '404':
          description: Organization not found
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
      tags:
        - Organization
      security:
        - bearer:
            - click:write
  /v1/click/validate/receipt:
    post:
      operationId: validateReceiptJson
      summary: Validate a cryptographic receipt
      description: Upload and verify the authenticity of a cryptographic receipt JSON file
      parameters: []
      responses:
        '200':
          description: Receipt validation completed
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
        '400':
          description: Invalid receipt format
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
      tags:
        - Validation
      security:
        - bearer:
            - click:read
  /v1/click/validate/receipt/upload:
    post:
      operationId: validateReceiptFile
      summary: Validate a receipt file upload
      description: Upload a receipt.json file for verification
      parameters: []
      responses:
        '200':
          description: Receipt file validation completed
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
        '400':
          description: Invalid file or format
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
      tags:
        - Validation
      security:
        - bearer:
            - click:read
  /v1/click/validate/certificate:
    post:
      operationId: generateCertificate
      summary: Generate verification certificate
      description: Generate a printable verification certificate from validation results
      parameters: []
      responses:
        '201':
          description: Certificate generated successfully
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
        '400':
          description: Invalid validation result
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
      tags:
        - Validation
      security:
        - bearer:
            - click:read
  /v1/click/validate/certificate/{certificateId}:
    get:
      operationId: getCertificate
      summary: Retrieve verification certificate
      description: Get a previously generated verification certificate by ID
      parameters:
        - name: certificateId
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: Certificate retrieved successfully
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
        '404':
          description: Certificate not found
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
      tags:
        - Validation
      security:
        - bearer:
            - click:read
  /v1/click/validate/certificate/{certificateId}/download:
    get:
      operationId: downloadCertificate
      summary: Download verification certificate as PDF
      description: Download a verification certificate in PDF format
      parameters:
        - name: certificateId
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: Certificate PDF downloaded
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
        '404':
          description: Certificate not found
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
      tags:
        - Validation
      security:
        - bearer:
            - click:read
  /v1/click/validate/validate-and-certify:
    post:
      operationId: validateAndCertify
      summary: Validate receipt and generate certificate in one step
      description: >-
        Convenience endpoint that validates a receipt and generates a
        certificate
      parameters: []
      responses:
        '200':
          description: Receipt validated and certificate generated
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
        '400':
          description: Invalid receipt
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
      tags:
        - Validation
      security:
        - bearer:
            - click:read
  /v1/click/verification/email/send:
    post:
      operationId: sendEmailVerification
      summary: Send email verification code
      parameters: []
      responses:
        '200':
          description: Verification code sent
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
        '400':
          description: Invalid email
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
      tags:
        - Verification
      security:
        - bearer:
            - click:write
  /v1/click/verification/email/verify:
    post:
      operationId: verifyEmailCode
      summary: Verify email code
      parameters: []
      responses:
        '200':
          description: Email verified
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
        '400':
          description: Invalid code
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
      tags:
        - Verification
      security:
        - bearer:
            - click:write
  /v1/click/verification/sms/send:
    post:
      operationId: sendSMSVerification
      summary: Send SMS verification code
      parameters: []
      responses:
        '200':
          description: ''
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
      tags:
        - Verification
      security:
        - bearer:
            - click:write
  /v1/click/verification/sms/verify:
    post:
      operationId: verifySMSCode
      summary: Verify SMS code
      parameters: []
      responses:
        '200':
          description: ''
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
      tags:
        - Verification
      security:
        - bearer:
            - click:write
  /v1/click/config/click-defaults:
    get:
      operationId: getClickDefaults
      summary: Get Click default settings
      description: Retrieve platform-wide default settings for Click experiences
      parameters: []
      responses:
        '200':
          description: Click default settings retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClickDefaultSettingsDto'
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
      tags:
        - Config
      security:
        - bearer:
            - click:read
    put:
      operationId: updateClickDefaults
      summary: Update Click default settings
      description: Update platform-wide default settings for Click experiences (admin only)
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClickDefaultSettingsDto'
      responses:
        '200':
          description: Click default settings updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClickDefaultSettingsDto'
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
        '400':
          description: Invalid input data
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
        '403':
          description: Forbidden - Admin access required
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
      tags:
        - Config
      security:
        - bearer:
            - click:write
info:
  title: Click Management API
  description: >-
    The Propper Click API provides consent and clickwrap management for websites
    and applications.

    Create templates, publish versioned policies, deploy them to domains, and
    collect legally-binding acceptance records with full evidence bundles.


    ---


    ## Base URL


    `https://api.propper.ai/v1/click`


    ## Authentication


    OAuth 2.0 Bearer token:


    ```

    Authorization: Bearer <access_token>

    ```


    ## OAuth Scopes


    - `click:admin` — Full administrative access (create, update, delete)

    - `click:read` — Read-only access to templates, deployments, and acceptances


    ## Key Endpoints


    - **Templates** — Create and manage consent/clickwrap templates

    - **Template Versions** — Publish, archive, and manage versioned content

    - **Deployments** — Deploy templates to domains and control activation

    - **Acceptances** — View acceptance records and evidence bundles


    ---


    ## Request correlation


    Every response (success and error) includes an `x-request-id` header (a
    UUID) and a `traceparent` header (W3C Trace Context). Error bodies also
    carry the same id as `requestId`. Quote `x-request-id` when contacting
    support to pinpoint the exact request, and use it to correlate the API with
    your own logs. Send your own `traceparent` to tie a multi-call workflow
    under one trace.
  version: '1.0'
  contact:
    name: Propper Support
    url: https://propper.ai
    email: support@propper.ai
tags:
  - name: Templates
    description: Create and manage consent/clickwrap templates
  - name: Deployments
    description: Deploy templates to domains and manage activation
  - name: Click
    description: Legacy click session and consent management
  - name: Acceptances
    description: View acceptance records and evidence bundles
  - name: Analytics
    description: Dashboard metrics and acceptance analytics
  - name: Config
    description: Administrative default settings
  - name: Organization
    description: Organization settings management
  - name: Validation
    description: Receipt validation and certificate generation
  - name: Verification
    description: Email and SMS verification
servers:
  - url: https://api.propper.ai
    description: Production server
security:
  - bearer: []
components:
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: JWT
      type: http
      description: OAuth 2.0 Bearer token
  headers:
    X-Request-Id:
      schema:
        type: string
        format: uuid
      description: >-
        Correlation id for this request, returned on every response (success and
        error). Quote it when contacting support to pinpoint the exact request,
        and use it to correlate your own logs. It is the same 128-bit id as the
        trace-id segment of the `traceparent` header.
    traceparent:
      schema:
        type: string
      description: >-
        W3C Trace Context identifier for this request, returned on every
        response. Send your own `traceparent` on a request to have it adopted,
        so a multi-call workflow shares one trace. Format: `00-<32-hex
        trace-id>-<16-hex span-id>-<2-hex flags>`.
  schemas:
    CreateTemplateDto:
      type: object
      properties:
        name:
          type: string
          description: Template name
          example: Terms of Service
          minLength: 1
          maxLength: 255
        slug:
          type: string
          description: Template slug (URL-friendly identifier)
          example: terms-of-service
          pattern: ^[a-z0-9-]+$
        type:
          type: string
          description: Template type
          enum:
            - STATIC
            - GENERATED
            - CONSENT
          default: STATIC
        retentionDays:
          type: number
          description: Data retention period in days
          minimum: 30
          maximum: 3650
          default: 2555
        consentVersion:
          type: string
          description: Consent version
          default: '1.0'
        contentVersion:
          type: string
          description: >-
            Semantic content version override. If omitted, the patch component
            auto-bumps on every content change.
          pattern: ^\d+\.\d+\.\d+$
          example: 2.0.0
        description:
          type: string
          description: Template description
        content:
          type: object
          description: Initial content for the template
        metadata:
          type: object
          description: Template metadata
        settings:
          type: object
          description: Additional template settings
      required:
        - name
        - slug
    TemplateResponseDto:
      type: object
      properties:
        id:
          type: string
          description: Template ID
        orgId:
          type: string
          description: Organization ID
        name:
          type: string
          description: Template name
        slug:
          type: string
          description: Template slug
        type:
          type: string
          description: Template type
        retentionDays:
          type: number
          description: Data retention period in days
        consentVersion:
          type: string
          description: Consent version
        settings:
          type: object
          description: Template settings
        createdAt:
          format: date-time
          type: string
          description: Creation timestamp
        updatedAt:
          format: date-time
          type: string
          description: Last update timestamp
        versions:
          type: array
          description: Template versions (only included when explicitly requested)
          items:
            type: object
      required:
        - id
        - orgId
        - name
        - slug
        - type
        - retentionDays
        - consentVersion
        - settings
        - createdAt
        - updatedAt
    UpdateTemplateDto:
      type: object
      properties:
        name:
          type: string
          description: Template name
          example: Terms of Service
          minLength: 1
          maxLength: 255
        slug:
          type: string
          description: Template slug (URL-friendly identifier)
          example: terms-of-service
          pattern: ^[a-z0-9-]+$
        type:
          type: string
          description: Template type
          enum:
            - STATIC
            - GENERATED
            - CONSENT
          default: STATIC
        retentionDays:
          type: number
          description: Data retention period in days
          minimum: 30
          maximum: 3650
          default: 2555
        consentVersion:
          type: string
          description: Consent version
          default: '1.0'
        contentVersion:
          type: string
          description: >-
            Semantic content version override. If omitted, the patch component
            auto-bumps on every content change.
          pattern: ^\d+\.\d+\.\d+$
          example: 2.0.0
        description:
          type: string
          description: Template description
        content:
          type: object
          description: Initial content for the template
        metadata:
          type: object
          description: Template metadata
        settings:
          type: object
          description: Additional template settings
    TemplateVersionResponseDto:
      type: object
      properties:
        id:
          type: string
          description: Version ID
        templateId:
          type: string
          description: Template ID
        version:
          type: string
          description: Semantic version number
        title:
          type: string
          description: Version title
        content:
          type: string
          description: Template content
        locale:
          type: string
          description: Content locale
        format:
          type: string
          description: Content format
        checksum:
          type: string
          description: Content checksum
        metadata:
          type: object
          description: Additional metadata
        published:
          type: boolean
          description: Whether version is published
        archivedAt:
          format: date-time
          type: string
          description: Archive timestamp
        createdAt:
          format: date-time
          type: string
          description: Creation timestamp
        updatedAt:
          format: date-time
          type: string
          description: Last update timestamp
        template:
          type: object
          description: Template details (only included when explicitly requested)
        deployments:
          type: array
          description: >-
            Deployments using this version (only included when explicitly
            requested)
          items:
            type: object
      required:
        - id
        - templateId
        - version
        - title
        - content
        - locale
        - format
        - checksum
        - metadata
        - published
        - createdAt
        - updatedAt
    CreateTemplateVersionDto:
      type: object
      properties:
        version:
          type: string
          description: Semantic version number
          example: 1.0.0
          default: 1.0.0
        title:
          type: string
          description: Version title
          example: Terms of Service v1.0
          minLength: 1
          maxLength: 255
        content:
          type: string
          description: Template content
          example: <h1>Terms of Service</h1><p>These terms govern...</p>
        locale:
          type: string
          description: Content locale
          example: en
          default: en
        format:
          type: string
          description: Content format
          enum:
            - html
            - markdown
            - pdf
            - docx
            - pdf_url
          default: html
        metadata:
          type: object
          description: Additional metadata
        published:
          type: boolean
          description: Whether to publish immediately
          default: false
      required:
        - title
        - content
    UpdateTemplateVersionDto:
      type: object
      properties:
        version:
          type: string
          description: Semantic version number
          example: 1.0.0
          default: 1.0.0
        title:
          type: string
          description: Version title
          example: Terms of Service v1.0
          minLength: 1
          maxLength: 255
        content:
          type: string
          description: Template content
          example: <h1>Terms of Service</h1><p>These terms govern...</p>
        locale:
          type: string
          description: Content locale
          example: en
          default: en
        format:
          type: string
          description: Content format
          enum:
            - html
            - markdown
            - pdf
            - docx
            - pdf_url
          default: html
        metadata:
          type: object
          description: Additional metadata
        published:
          type: boolean
          description: Whether to publish immediately
          default: false
    PublishTemplateVersionDto:
      type: object
      properties:
        published:
          type: boolean
          description: Whether to publish the version
          default: true
    DeploymentResponseDto:
      type: object
      properties:
        id:
          type: string
          description: Deployment ID
        domain:
          type: string
          description: Domain
        templateVersionId:
          type: string
          description: Template version ID
        environment:
          type: string
          description: Deployment environment
        path:
          type: string
          description: URL path
        variant:
          type: string
          description: A/B test variant
        active:
          type: boolean
          description: Whether deployment is active
        priority:
          type: number
          description: Deployment priority
        startAt:
          format: date-time
          type: string
          description: Start timestamp
        endAt:
          format: date-time
          type: string
          description: End timestamp
        policyFlags:
          type: object
          description: Policy flags override
        settings:
          type: object
          description: Deployment-specific settings
        createdAt:
          format: date-time
          type: string
          description: Creation timestamp
        updatedAt:
          format: date-time
          type: string
          description: Last update timestamp
        templateVersion:
          type: object
          description: Template version details (only included when explicitly requested)
      required:
        - id
        - domain
        - templateVersionId
        - environment
        - path
        - active
        - priority
        - startAt
        - createdAt
        - updatedAt
    CreateDeploymentDto:
      type: object
      properties:
        domain:
          type: string
          description: Domain where template will be deployed
          example: example.com
        templateVersionId:
          type: string
          description: Template version ID to deploy
          format: uuid
        version:
          type: string
          description: >-
            Semantic version override. Defaults to the template's
            contentVersion.
          pattern: ^\d+\.\d+\.\d+$
          example: 1.2.0
        environment:
          type: string
          description: Deployment environment
          enum:
            - production
            - staging
            - development
          default: production
        path:
          type: string
          description: URL path where template will be active
          example: /
          default: /
        variant:
          type: string
          description: A/B test variant identifier
          example: variant-a
        active:
          type: boolean
          description: Whether deployment is active
          default: true
        priority:
          type: number
          description: Deployment priority (higher numbers take precedence)
          minimum: 0
          maximum: 1000
          default: 0
        startAt:
          type: string
          description: When deployment becomes active (ISO 8601 date)
          example: '2024-01-15T10:00:00.000Z'
        endAt:
          type: string
          description: When deployment expires (ISO 8601 date)
          example: '2024-12-31T23:59:59.999Z'
        policyFlags:
          type: object
          description: Policy flags override for this deployment
          properties:
            requireScroll:
              type: boolean
              description: Require user to scroll through content
            blockUntilAssent:
              type: boolean
              description: Block interaction until consent is given
            doubleCheckbox:
              type: boolean
              description: Require double checkbox confirmation
        settings:
          type: object
          description: Deployment-specific settings and overrides
      required:
        - domain
        - templateVersionId
    UpdateDeploymentDto:
      type: object
      properties:
        domain:
          type: string
          description: Domain where template will be deployed
          example: example.com
        templateVersionId:
          type: string
          description: Template version ID to deploy
          format: uuid
        version:
          type: string
          description: >-
            Semantic version override. Defaults to the template's
            contentVersion.
          pattern: ^\d+\.\d+\.\d+$
          example: 1.2.0
        environment:
          type: string
          description: Deployment environment
          enum:
            - production
            - staging
            - development
          default: production
        path:
          type: string
          description: URL path where template will be active
          example: /
          default: /
        variant:
          type: string
          description: A/B test variant identifier
          example: variant-a
        active:
          type: boolean
          description: Whether deployment is active
          default: true
        priority:
          type: number
          description: Deployment priority (higher numbers take precedence)
          minimum: 0
          maximum: 1000
          default: 0
        startAt:
          type: string
          description: When deployment becomes active (ISO 8601 date)
          example: '2024-01-15T10:00:00.000Z'
        endAt:
          type: string
          description: When deployment expires (ISO 8601 date)
          example: '2024-12-31T23:59:59.999Z'
        policyFlags:
          type: object
          description: Policy flags override for this deployment
          properties:
            requireScroll:
              type: boolean
              description: Require user to scroll through content
            blockUntilAssent:
              type: boolean
              description: Block interaction until consent is given
            doubleCheckbox:
              type: boolean
              description: Require double checkbox confirmation
        settings:
          type: object
          description: Deployment-specific settings and overrides
    PolicyFlagsDto:
      type: object
      properties:
        requireScroll:
          type: boolean
          description: Require users to scroll before accepting
        blockUntilAssent:
          type: boolean
          description: Block UI until agreement is accepted
        doubleCheckbox:
          type: boolean
          description: Require two separate checkbox confirmations
        showAcceptanceDate:
          type: boolean
          description: Show acceptance date in UI
        allowDecline:
          type: boolean
          description: Allow users to decline
        requireExplicitConsent:
          type: boolean
          description: Require explicit consent confirmation
      required:
        - requireScroll
        - blockUntilAssent
        - doubleCheckbox
        - showAcceptanceDate
        - allowDecline
        - requireExplicitConsent
    TemplateSettingsDto:
      type: object
      properties:
        defaultConsentMethod:
          type: string
          description: Default consent method
          enum:
            - CHECKBOX
            - CLICK
            - SCROLL
            - SIGNIN_WRAP
        allowedConsentMethods:
          description: Allowed consent methods
          type: array
          items:
            type: string
        displayMode:
          type: string
          description: Display mode
          enum:
            - modal
            - inline
            - banner
            - wall
        allowedRenderModes:
          description: Allowed render modes
          type: array
          items:
            type: string
        requireIdentity:
          type: boolean
          description: Whether identity is required
        identityMethods:
          description: Available identity methods
          type: array
          items:
            type: string
        minimumAge:
          type: number
          description: Minimum age requirement
        policyFlags:
          description: Policy flags configuration
          allOf:
            - $ref: '#/components/schemas/PolicyFlagsDto'
        customCss:
          type: string
          description: Custom CSS styles
        customJavascript:
          type: string
          description: Custom JavaScript code
        metadata:
          type: object
          description: Additional metadata
      required:
        - defaultConsentMethod
        - allowedConsentMethods
        - displayMode
        - allowedRenderModes
        - requireIdentity
        - identityMethods
        - policyFlags
    DefaultTemplateSettingsDto:
      type: object
      properties:
        clickwrap:
          description: Default settings for clickwrap templates
          allOf:
            - $ref: '#/components/schemas/TemplateSettingsDto'
        terms:
          description: Default settings for terms templates
          allOf:
            - $ref: '#/components/schemas/TemplateSettingsDto'
        privacy:
          description: Default settings for privacy templates
          allOf:
            - $ref: '#/components/schemas/TemplateSettingsDto'
      required:
        - clickwrap
        - terms
        - privacy
    FeatureFlagsDto:
      type: object
      properties:
        webhooks:
          type: boolean
          description: Enable webhook functionality
        multiLocale:
          type: boolean
          description: Enable multi-locale support
        abTesting:
          type: boolean
          description: Enable A/B testing features
      required:
        - webhooks
        - multiLocale
        - abTesting
    ComplianceSettingsDto:
      type: object
      properties:
        evidenceRetentionDays:
          type: number
          description: Evidence retention period in days
        immutableStorage:
          type: boolean
          description: Enable immutable storage (WORM)
        auditLogRetentionDays:
          type: number
          description: Audit log retention period in days
        requireApprovalWorkflow:
          type: boolean
          description: Require approval workflow for publishing
      required:
        - evidenceRetentionDays
        - immutableStorage
        - auditLogRetentionDays
        - requireApprovalWorkflow
    OrganizationSettingsDto:
      type: object
      properties:
        id:
          type: string
          description: Organization ID
        name:
          type: string
          description: Organization name
        createdAt:
          format: date-time
          type: string
          description: Creation timestamp
        defaultRetentionDays:
          type: number
          description: Default evidence retention period in days
          example: 2555
        piiMode:
          type: string
          description: PII collection mode
          enum:
            - Minimal
            - Balanced
            - Full
          example: Balanced
        defaultTemplateSettings:
          description: Default template settings by type
          allOf:
            - $ref: '#/components/schemas/DefaultTemplateSettingsDto'
        features:
          description: Feature flags configuration
          allOf:
            - $ref: '#/components/schemas/FeatureFlagsDto'
        complianceSettings:
          description: Compliance and governance settings
          allOf:
            - $ref: '#/components/schemas/ComplianceSettingsDto'
      required:
        - id
        - name
        - createdAt
        - defaultRetentionDays
        - piiMode
        - defaultTemplateSettings
        - features
        - complianceSettings
    UpdatePolicyFlagsDto:
      type: object
      properties:
        requireScroll:
          type: boolean
          description: Require users to scroll before accepting
        blockUntilAssent:
          type: boolean
          description: Block UI until agreement is accepted
        doubleCheckbox:
          type: boolean
          description: Require two separate checkbox confirmations
        showAcceptanceDate:
          type: boolean
          description: Show acceptance date in UI
        allowDecline:
          type: boolean
          description: Allow users to decline
        requireExplicitConsent:
          type: boolean
          description: Require explicit consent confirmation
    UpdateTemplateSettingsDto:
      type: object
      properties:
        defaultConsentMethod:
          type: string
          description: Default consent method
          enum:
            - CHECKBOX
            - CLICK
            - SCROLL
            - SIGNIN_WRAP
        allowedConsentMethods:
          description: Allowed consent methods
          type: array
          items:
            type: string
        displayMode:
          type: string
          description: Display mode
          enum:
            - modal
            - inline
            - banner
            - wall
        allowedRenderModes:
          description: Allowed render modes
          type: array
          items:
            type: string
        requireIdentity:
          type: boolean
          description: Whether identity is required
        identityMethods:
          description: Available identity methods
          type: array
          items:
            type: string
        minimumAge:
          type: number
          description: Minimum age requirement
        policyFlags:
          description: Policy flags configuration
          allOf:
            - $ref: '#/components/schemas/UpdatePolicyFlagsDto'
        customCss:
          type: string
          description: Custom CSS styles
        customJavascript:
          type: string
          description: Custom JavaScript code
        metadata:
          type: object
          description: Additional metadata
    UpdateDefaultTemplateSettingsDto:
      type: object
      properties:
        clickwrap:
          description: Default settings for clickwrap templates
          allOf:
            - $ref: '#/components/schemas/UpdateTemplateSettingsDto'
        terms:
          description: Default settings for terms templates
          allOf:
            - $ref: '#/components/schemas/UpdateTemplateSettingsDto'
        privacy:
          description: Default settings for privacy templates
          allOf:
            - $ref: '#/components/schemas/UpdateTemplateSettingsDto'
    UpdateOrganizationSettingsDto:
      type: object
      properties:
        name:
          type: string
          description: Organization name
        defaultRetentionDays:
          type: number
          description: Default evidence retention period in days
          minimum: 365
          maximum: 3650
        piiMode:
          type: string
          description: PII collection mode
          enum:
            - Minimal
            - Balanced
            - Full
        defaultTemplateSettings:
          description: Default template settings by type
          allOf:
            - $ref: '#/components/schemas/UpdateDefaultTemplateSettingsDto'
        features:
          description: Feature flags configuration
          allOf:
            - $ref: '#/components/schemas/FeatureFlagsDto'
        complianceSettings:
          description: Compliance and governance settings
          allOf:
            - $ref: '#/components/schemas/ComplianceSettingsDto'
    ClickDefaultSettingsDto:
      type: object
      properties:
        policyFlags:
          type: object
          description: Policy flags for Click experiences
          example:
            requireScroll: false
            blockUntilAssent: true
            doubleCheckbox: false
            showAcceptanceDate: true
            allowDecline: true
            requireExplicitConsent: true
        defaultConsentMethod:
          type: string
          description: Default consent method
          example: CLICK
        allowedConsentMethods:
          description: Allowed consent methods
          example:
            - CLICK
            - CHECKBOX
          type: array
          items:
            type: string
        displayMode:
          type: string
          description: Display mode for Click experiences
          example: modal
        requireIdentity:
          type: boolean
          description: Whether to require identity verification
          example: false
        identityMethods:
          description: Available identity verification methods
          example: []
          type: array
          items:
            type: string
        acceptButtonText:
          type: string
          description: Text for accept button
          example: I Accept
        declineButtonText:
          type: string
          description: Text for decline button
          example: I Decline
        scrollPercentage:
          type: number
          description: Required scroll percentage before enabling accept
          example: 80
        timeout:
          type: number
          description: Session timeout in seconds
          example: 300
        showProgressBar:
          type: boolean
          description: Whether to show progress bar
          example: true
        enableAnalytics:
          type: boolean
          description: Whether to enable analytics tracking
          example: true
      required:
        - policyFlags
        - defaultConsentMethod
        - allowedConsentMethods
        - displayMode
        - requireIdentity
        - identityMethods
        - acceptButtonText
        - declineButtonText
        - scrollPercentage
        - timeout
        - showProgressBar
        - enableAnalytics
