openapi: 3.1.0
info:
  title: Click Render API
  version: '1.0'
  description: >-
    The Propper Click Render API serves consent and clickwrap experiences as
    JSON payloads optimized for edge caching.

    Client-side SDKs fetch rendered templates from this API to display consent
    flows to end users.


    ---


    ## Base URL


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


    ## Authentication


    OAuth 2.0 Bearer token:


    ```

    Authorization: Bearer <access_token>

    ```


    ## OAuth Scopes


    - `click:admin` — Full administrative access

    - `click:read` — Read-only access to rendered experiences


    ## Key Endpoints


    - **Render** — Fetch rendered consent experiences by deployment key


    ---


    ## 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.
  contact:
    name: Propper Support
    url: https://propper.ai
    email: support@propper.ai
tags:
  - name: Render
    description: Fetch rendered consent experiences by deployment key
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:
    ExperienceMetadataDto:
      type: object
      properties:
        requireIdentity:
          type: boolean
          description: Whether the experience requires user identity verification
          example: false
        identityMethods:
          description: List of allowed identity verification methods
          example:
            - email
            - sms
          type: array
          items:
            type: string
        displayMode:
          type: string
          description: Display mode for the experience
          example: modal
          enum:
            - modal
            - inline
            - banner
            - wall
        templateType:
          type: string
          description: Template type that determines behavior and constraints
          example: clickwrap
          enum:
            - clickwrap
            - terms
            - privacy
        allowedConsentMethods:
          description: Allowed consent methods for this template type
          example:
            - CLICK
            - CHECKBOX
          type: array
          items:
            type: string
        defaultConsentMethod:
          type: string
          description: Default consent method for this template type
          example: CLICK
        allowedRenderModes:
          description: Allowed render modes for this template type
          example:
            - inline
            - modal
            - banner
            - wall
          type: array
          items:
            type: string
        policyFlags:
          type: object
          description: Policy flags that control template behavior
          example:
            requireScroll: false
            blockUntilAssent: true
            doubleCheckbox: false
        originalDocxUrl:
          type: string
          description: URL to download original DOCX file (only present for DOCX templates)
          example: >-
            /v1/render/template-versions/123e4567-e89b-12d3-a456-426614174000/download
        format:
          type: string
          description: Original format of the template content
          example: docx
          enum:
            - html
            - docx
            - pdf
        additional:
          type: object
          description: Additional metadata fields
          example:
            customField: value
      required:
        - requireIdentity
        - identityMethods
        - displayMode
        - templateType
        - allowedConsentMethods
        - defaultConsentMethod
        - allowedRenderModes
        - policyFlags
    ExperienceDto:
      type: object
      properties:
        templateId:
          type: string
          description: Unique template identifier
          example: 123e4567-e89b-12d3-a456-426614174000
        versionId:
          type: string
          description: Template version identifier
          example: 456e7890-e89b-12d3-a456-426614174001
        deploymentId:
          type: string
          description: Deployment identifier
          example: 789e1234-e89b-12d3-a456-426614174002
        title:
          type: string
          description: Human-readable title of the experience
          example: Terms of Service
        content:
          type: string
          description: HTML content of the experience
          example: <div class="terms">...</div>
        checksum:
          type: string
          description: SHA256 checksum of the content for integrity verification
          example: a665a45920422f9d417e4867efdc4fb8a04a1f3fff1fa07e998e86f7f7a27ae3
        locale:
          type: string
          description: Locale of the content
          example: en
        variant:
          type:
            - string
            - 'null'
          description: A/B test variant identifier
          example: control
        metadata:
          description: Experience metadata
          allOf:
            - $ref: '#/components/schemas/ExperienceMetadataDto'
        cacheKey:
          type: string
          description: Cache key used for this response
          example: site123|production|example.com|/terms|en|null
      required:
        - templateId
        - versionId
        - deploymentId
        - title
        - content
        - checksum
        - locale
        - variant
        - metadata
        - cacheKey
paths:
  /v1/click/render/deployment/{id}:
    get:
      operationId: renderByDeploymentId
      summary: Render Experience JSON by Deployment ID
      description: >-
        Returns Experience JSON for a specific deployment ID with optional
        locale override
      parameters:
        - name: id
          required: true
          in: path
          description: Deployment ID
          schema:
            example: c54f4b8c-d36d-4670-855d-f454c8d3b7a8
            type: string
        - name: locale
          required: false
          in: query
          description: Locale for template resolution (overrides deployment default)
          schema:
            example: fr
            type: string
        - name: if-none-match
          required: true
          in: header
          schema:
            type: string
      responses:
        '200':
          description: Experience JSON successfully rendered
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExperienceDto'
          headers:
            X-Request-Id: &ref_0
              $ref: '#/components/headers/X-Request-Id'
            traceparent: &ref_1
              $ref: '#/components/headers/traceparent'
        '404':
          description: Deployment not found
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
      tags:
        - Render
  /v1/click/render:
    get:
      operationId: renderExperience
      summary: Render Experience JSON
      description: >-
        Returns Experience JSON with template content and metadata for the
        specified route
      parameters:
        - name: domain
          required: true
          in: query
          description: Domain to resolve template for
          schema:
            example: example.com
            type: string
        - name: path
          required: true
          in: query
          description: Path to resolve template for
          schema:
            example: /terms
            type: string
        - name: variant
          required: false
          in: query
          description: A/B testing variant identifier
          schema:
            example: control
            type: string
        - name: environment
          required: false
          in: query
          description: Deployment environment
          schema:
            enum:
              - development
              - staging
              - production
            type: string
        - name: x-site-id
          required: true
          in: header
          schema:
            type: string
        - name: if-none-match
          required: true
          in: header
          schema:
            type: string
        - name: X-Site-Id
          in: header
          description: Site identifier (optional, can be resolved from domain)
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Experience JSON successfully rendered
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExperienceDto'
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
        '400':
          description: Invalid request parameters
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
        '404':
          description: No active template found for the specified route
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
      tags:
        - Render
  /v1/click/render/template-versions/{versionId}/download:
    get:
      operationId: downloadOriginalDocx
      summary: Download Original DOCX Template
      description: Download the original DOCX file for a template version
      parameters:
        - name: versionId
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: DOCX file download
          content:
            application/vnd.openxmlformats-officedocument.wordprocessingml.document:
              schema:
                type: string
                format: binary
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
        '404':
          description: Template version not found or not a DOCX template
          headers:
            X-Request-Id: *ref_0
            traceparent: *ref_1
      tags:
        - Render
