{
  "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.\nClient-side SDKs fetch rendered templates from this API to display consent flows to end users.\n\n---\n\n## Base URL\n\n`https://api.propper.ai/v1/click/render`\n\n## Authentication\n\nOAuth 2.0 Bearer token:\n\n```\nAuthorization: Bearer <access_token>\n```\n\n## OAuth Scopes\n\n- `click:admin` — Full administrative access\n- `click:read` — Read-only access to rendered experiences\n\n## Key Endpoints\n\n- **Render** — Fetch rendered consent experiences by deployment key\n\n---\n\n## Request correlation\n\nEvery 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": "#/components/headers/X-Request-Id"
              },
              "traceparent": {
                "$ref": "#/components/headers/traceparent"
              }
            }
          },
          "404": {
            "description": "Deployment not found",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              },
              "traceparent": {
                "$ref": "#/components/headers/traceparent"
              }
            }
          }
        },
        "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": "#/components/headers/X-Request-Id"
              },
              "traceparent": {
                "$ref": "#/components/headers/traceparent"
              }
            }
          },
          "400": {
            "description": "Invalid request parameters",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              },
              "traceparent": {
                "$ref": "#/components/headers/traceparent"
              }
            }
          },
          "404": {
            "description": "No active template found for the specified route",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              },
              "traceparent": {
                "$ref": "#/components/headers/traceparent"
              }
            }
          }
        },
        "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": "#/components/headers/X-Request-Id"
              },
              "traceparent": {
                "$ref": "#/components/headers/traceparent"
              }
            }
          },
          "404": {
            "description": "Template version not found or not a DOCX template",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              },
              "traceparent": {
                "$ref": "#/components/headers/traceparent"
              }
            }
          }
        },
        "tags": [
          "Render"
        ]
      }
    }
  }
}