{ "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": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } }, "404": { "description": "Template not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } } }, "tags": [ "Click" ], "security": [ { "bearer": [] } ] } }, "/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": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } }, "404": { "description": "Session not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } } }, "tags": [ "Click" ], "security": [ { "bearer": [] } ] } }, "/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": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } }, "404": { "description": "Session not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } } }, "tags": [ "Click" ], "security": [ { "bearer": [] } ] } }, "/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": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } }, "404": { "description": "Evidence not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } } }, "tags": [ "Click" ], "security": [ { "bearer": [] } ] } }, "/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": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } } }, "tags": [ "Click" ], "security": [ { "bearer": [] } ] }, "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": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } } }, "tags": [ "Click" ], "security": [ { "bearer": [] } ] } }, "/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": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } } }, "tags": [ "Templates" ], "security": [ { "basic": [] } ] }, "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": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } }, "409": { "description": "Template slug already exists", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } } }, "tags": [ "Templates" ], "security": [ { "basic": [] } ] } }, "/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": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } }, "404": { "description": "Template not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } } }, "tags": [ "Templates" ], "security": [ { "basic": [] } ] }, "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": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } }, "404": { "description": "Template not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } }, "409": { "description": "Template slug already exists", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } } }, "tags": [ "Templates" ], "security": [ { "basic": [] } ] }, "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": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } }, "400": { "description": "Cannot delete template with active deployments", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } }, "404": { "description": "Template not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } } }, "tags": [ "Templates" ], "security": [ { "basic": [] } ] } }, "/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": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } }, "404": { "description": "Template not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } } }, "tags": [ "Templates" ], "security": [ { "basic": [] } ] } }, "/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": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } }, "404": { "description": "Template not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } } }, "tags": [ "Templates" ], "security": [ { "basic": [] } ] }, "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": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } }, "404": { "description": "Template not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } }, "409": { "description": "Version already exists for this locale", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } } }, "tags": [ "Templates" ], "security": [ { "basic": [] } ] } }, "/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": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } }, "404": { "description": "Template not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } } }, "tags": [ "Templates" ], "security": [ { "basic": [] } ] } }, "/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": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } }, "404": { "description": "Template or version not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } } }, "tags": [ "Templates" ], "security": [ { "basic": [] } ] }, "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": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } }, "400": { "description": "Cannot modify published versions", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } }, "404": { "description": "Template or version not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } }, "409": { "description": "Version already exists for this locale", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } } }, "tags": [ "Templates" ], "security": [ { "basic": [] } ] } }, "/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": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } }, "400": { "description": "Cannot publish archived versions", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } }, "404": { "description": "Template or version not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } } }, "tags": [ "Templates" ], "security": [ { "basic": [] } ] } }, "/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": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } }, "400": { "description": "Cannot archive version with active deployments", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } }, "404": { "description": "Template or version not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } } }, "tags": [ "Templates" ], "security": [ { "basic": [] } ] } }, "/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": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } } }, "tags": [ "Templates" ], "security": [ { "basic": [] } ] } }, "/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": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } } }, "tags": [ "Templates" ], "security": [ { "basic": [] } ] } }, "/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": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } } }, "tags": [ "Templates" ], "security": [ { "basic": [] } ] } }, "/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": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } } }, "tags": [ "Templates" ], "security": [ { "basic": [] } ] } }, "/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": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } }, "400": { "description": "Missing required body fields (e.g. `type`)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } } }, "tags": [ "Templates" ], "security": [ { "basic": [] } ] } }, "/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 (OAuth Bearer); API-key / Basic-auth principals are rejected with 403.", "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": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } }, "400": { "description": "Invalid payload (e.g. malformed UUID, count out of range)", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } }, "401": { "description": "Missing or invalid authentication", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } }, "403": { "description": "Authenticated principal does not satisfy the `click:admin` scope", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } } }, "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": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } }, "400": { "description": "Invalid payload", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } }, "401": { "description": "Missing or invalid authentication", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } }, "403": { "description": "Authenticated principal does not satisfy the `click:admin` scope", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } } }, "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": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } }, "404": { "description": "Template or one of the versions was not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } } }, "tags": [ "Templates" ], "security": [ { "bearer": [ "click:admin" ] } ] } }, "/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": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } } }, "tags": [ "Deployments" ], "security": [ { "basic": [] } ] }, "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": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } }, "400": { "description": "Invalid deployment data", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } }, "404": { "description": "Site or template version not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } }, "409": { "description": "Deployment already exists for this combination", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } } }, "tags": [ "Deployments" ], "security": [ { "basic": [] } ] } }, "/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": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } } }, "tags": [ "Deployments" ], "security": [ { "basic": [] } ] } }, "/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": "#/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": [ "Deployments" ], "security": [ { "basic": [] } ] }, "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": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } }, "400": { "description": "Invalid deployment data", "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" } } }, "409": { "description": "Deployment already exists for this combination", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } } }, "tags": [ "Deployments" ], "security": [ { "basic": [] } ] }, "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": "#/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": [ "Deployments" ], "security": [ { "basic": [] } ] } }, "/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": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } } }, "tags": [ "Deployments" ], "security": [ { "basic": [] } ] } }, "/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": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } } }, "tags": [ "Analytics" ], "security": [ { "basic": [] } ] } }, "/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": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } } }, "tags": [ "Analytics" ], "security": [ { "basic": [] } ] } }, "/v1/click/acceptances": { "get": { "operationId": "getAcceptances", "parameters": [], "responses": { "200": { "description": "", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } } }, "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": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } } }, "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": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } } }, "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": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } } }, "tags": [ "Acceptances" ] } }, "/v1/click/evidence/retention/status": { "get": { "operationId": "getRetentionStatus", "parameters": [], "responses": { "200": { "description": "", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } } }, "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": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } } }, "tags": [ "Acceptances" ] } }, "/v1/click/organization/settings": { "get": { "operationId": "getSettings", "summary": "Get organization settings", "description": "Retrieve organization settings including retention policies, PII mode, webhook configuration, 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": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } }, "404": { "description": "Organization not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } } }, "tags": [ "Organization" ], "security": [ { "basic": [] } ] }, "patch": { "operationId": "updateSettings", "summary": "Update organization settings", "description": "Update organization settings such as retention policies, PII mode, webhook configuration, 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": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } }, "400": { "description": "Invalid input data", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } }, "404": { "description": "Organization not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } } }, "tags": [ "Organization" ], "security": [ { "basic": [] } ] } }, "/v1/click/users/organization/members": { "get": { "operationId": "getOrganizationMembers", "summary": "Get organization members and invitations", "parameters": [], "responses": { "200": { "description": "Organization members retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationMembersResponseDto" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } } }, "tags": [ "Users" ], "security": [ { "bearer": [] } ] } }, "/v1/click/users/organization/invite": { "post": { "operationId": "inviteUser", "summary": "Invite a user to the organization", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteUserDto" } } } }, "responses": { "201": { "description": "Invitation sent successfully", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } }, "409": { "description": "User already exists or has pending invitation", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } } }, "tags": [ "Users" ], "security": [ { "bearer": [] } ] } }, "/v1/click/users/organization/members/{userId}": { "put": { "operationId": "updateMembership", "summary": "Update organization membership", "parameters": [ { "name": "userId", "required": true, "in": "path", "description": "User ID to update", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMembershipDto" } } } }, "responses": { "200": { "description": "Membership updated successfully", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } }, "404": { "description": "Membership not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } } }, "tags": [ "Users" ], "security": [ { "bearer": [] } ] }, "delete": { "operationId": "removeMember", "summary": "Remove user from organization", "parameters": [ { "name": "userId", "required": true, "in": "path", "description": "User ID to remove", "schema": { "type": "string" } } ], "responses": { "200": { "description": "User removed successfully", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } }, "400": { "description": "Cannot remove last organization admin", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } }, "404": { "description": "Membership not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } } }, "tags": [ "Users" ], "security": [ { "bearer": [] } ] } }, "/v1/click/users/accept-invitation": { "post": { "operationId": "acceptInvitation", "summary": "Accept organization invitation", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcceptInvitationDto" } } } }, "responses": { "200": { "description": "Invitation accepted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserDto" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } }, "404": { "description": "Invalid or expired invitation", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } } }, "tags": [ "Users" ], "security": [ { "bearer": [] } ] } }, "/v1/click/users/organization/invitations/{invitationId}": { "delete": { "operationId": "cancelInvitation", "summary": "Cancel pending invitation", "parameters": [ { "name": "invitationId", "required": true, "in": "path", "description": "Invitation ID to cancel", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Invitation cancelled successfully", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } }, "404": { "description": "Invitation not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } } }, "tags": [ "Users" ], "security": [ { "bearer": [] } ] } }, "/v1/click/users/organization/members/{userId}/capabilities": { "get": { "operationId": "getUserCapabilities", "summary": "Get user capabilities in organization", "parameters": [ { "name": "userId", "required": true, "in": "path", "description": "User ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "User capabilities retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "capabilities": { "type": "array", "items": { "type": "string" } } } } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } } }, "tags": [ "Users" ], "security": [ { "bearer": [] } ] } }, "/v1/click/users/roles": { "get": { "operationId": "getRoles", "summary": "Get available RBAC roles and their capabilities", "parameters": [], "responses": { "200": { "description": "RBAC roles retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "roles": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "capabilities": { "type": "array", "items": { "type": "string" } } } } } } } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } } }, "tags": [ "Users" ], "security": [ { "bearer": [] } ] } }, "/v1/click/users/{userId}/settings": { "get": { "operationId": "getUserSettings", "summary": "Get user settings", "parameters": [ { "name": "userId", "required": true, "in": "path", "description": "User ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "User settings retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserSettingsDto" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } }, "404": { "description": "User not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } } }, "tags": [ "Users" ], "security": [ { "bearer": [] } ] }, "put": { "operationId": "updateUserSettings", "summary": "Update user settings", "parameters": [ { "name": "userId", "required": true, "in": "path", "description": "User ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateUserSettingsDto" } } } }, "responses": { "200": { "description": "User settings updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserSettingsDto" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } }, "404": { "description": "User not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } } }, "tags": [ "Users" ], "security": [ { "bearer": [] } ] } }, "/v1/click/users/{userId}/api-key/generate": { "post": { "operationId": "generatePersonalApiKey", "summary": "Generate personal API key for user", "parameters": [ { "name": "userId", "required": true, "in": "path", "description": "User ID", "schema": { "type": "string" } } ], "responses": { "201": { "description": "Personal API key generated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonalApiKeyDto" } } }, "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } }, "404": { "description": "User not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } } }, "tags": [ "Users" ], "security": [ { "bearer": [] } ] } }, "/v1/click/users/{userId}/api-key": { "delete": { "operationId": "revokePersonalApiKey", "summary": "Revoke personal API key for user", "parameters": [ { "name": "userId", "required": true, "in": "path", "description": "User ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Personal API key revoked successfully", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } }, "404": { "description": "User not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } } }, "tags": [ "Users" ], "security": [ { "bearer": [] } ] } }, "/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": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } }, "400": { "description": "Invalid receipt format", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } } }, "tags": [ "Validation" ], "security": [ { "bearer": [] } ] } }, "/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": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } }, "400": { "description": "Invalid file or format", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } } }, "tags": [ "Validation" ], "security": [ { "bearer": [] } ] } }, "/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": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } }, "400": { "description": "Invalid validation result", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } } }, "tags": [ "Validation" ], "security": [ { "bearer": [] } ] } }, "/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": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } }, "404": { "description": "Certificate not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } } }, "tags": [ "Validation" ], "security": [ { "bearer": [] } ] } }, "/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": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } }, "404": { "description": "Certificate not found", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } } }, "tags": [ "Validation" ], "security": [ { "bearer": [] } ] } }, "/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": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } }, "400": { "description": "Invalid receipt", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } } }, "tags": [ "Validation" ], "security": [ { "bearer": [] } ] } }, "/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": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } }, "400": { "description": "Invalid email", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } } }, "tags": [ "Verification" ], "security": [ { "bearer": [] } ] } }, "/v1/click/verification/email/verify": { "post": { "operationId": "verifyEmailCode", "summary": "Verify email code", "parameters": [], "responses": { "200": { "description": "Email verified", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } }, "400": { "description": "Invalid code", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } } }, "tags": [ "Verification" ], "security": [ { "bearer": [] } ] } }, "/v1/click/verification/sms/send": { "post": { "operationId": "sendSMSVerification", "summary": "Send SMS verification code", "parameters": [], "responses": { "200": { "description": "", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } } }, "tags": [ "Verification" ], "security": [ { "bearer": [] } ] } }, "/v1/click/verification/sms/verify": { "post": { "operationId": "verifySMSCode", "summary": "Verify SMS code", "parameters": [], "responses": { "200": { "description": "", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } } }, "tags": [ "Verification" ], "security": [ { "bearer": [] } ] } }, "/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": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } } }, "tags": [ "Config" ], "security": [ { "basic": [] } ] }, "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": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } }, "400": { "description": "Invalid input data", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } }, "403": { "description": "Forbidden - Admin access required", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "traceparent": { "$ref": "#/components/headers/traceparent" } } } }, "tags": [ "Config" ], "security": [ { "basic": [] } ] } } }, "info": { "title": "Click Management API", "description": "The Propper Click API provides consent and clickwrap management for websites and applications.\nCreate templates, publish versioned policies, deploy them to domains, and collect legally-binding acceptance records with full evidence bundles.\n\n---\n\n## Base URL\n\n`https://api.propper.ai/v1/click`\n\n## Authentication\n\nOAuth 2.0 Bearer token:\n\n```\nAuthorization: Bearer \n```\n\n## OAuth Scopes\n\n- `click:admin` — Full administrative access (create, update, delete)\n- `click:read` — Read-only access to templates, deployments, and acceptances\n\n## Key Endpoints\n\n- **Templates** — Create and manage consent/clickwrap templates\n- **Template Versions** — Publish, archive, and manage versioned content\n- **Deployments** — Deploy templates to domains and control activation\n- **Acceptances** — View acceptance records and evidence bundles\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.", "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": "Users", "description": "User and member management, API keys" }, { "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" }, "basic": { "scheme": "basic", "type": "http", "description": "HTTP Basic authentication using an organization API key as the username (legacy SDK compatibility)." } }, "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": "

Terms of Service

These terms govern...

" }, "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": "

Terms of Service

These terms govern...

" }, "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" ] }, "WebhookSettingsDto": { "type": "object", "properties": { "events": { "description": "Webhook event types to send", "type": "array", "items": { "type": "string" } } }, "required": [ "events" ] }, "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" }, "webhookUrl": { "type": "string", "description": "Webhook URL for notifications" }, "webhookSecretLast4": { "type": [ "string", "null" ], "description": "Last 4 characters of the configured webhook signing secret. The full secret is never returned by this endpoint — rotate it via the admin rotate flow to obtain a new value.", "example": "a1b2" }, "webhookEnabled": { "type": "boolean", "description": "Whether webhooks are enabled", "example": false }, "defaultTemplateSettings": { "description": "Default template settings by type", "allOf": [ { "$ref": "#/components/schemas/DefaultTemplateSettingsDto" } ] }, "features": { "description": "Feature flags configuration", "allOf": [ { "$ref": "#/components/schemas/FeatureFlagsDto" } ] }, "webhookSettings": { "description": "Webhook configuration", "allOf": [ { "$ref": "#/components/schemas/WebhookSettingsDto" } ] }, "complianceSettings": { "description": "Compliance and governance settings", "allOf": [ { "$ref": "#/components/schemas/ComplianceSettingsDto" } ] } }, "required": [ "id", "name", "createdAt", "defaultRetentionDays", "piiMode", "webhookEnabled", "defaultTemplateSettings", "features", "webhookSettings", "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" ] }, "webhookUrl": { "type": "string", "description": "Webhook URL for notifications" }, "webhookSecret": { "type": "string", "description": "Webhook signing secret" }, "webhookEnabled": { "type": "boolean", "description": "Whether webhooks are enabled" }, "defaultTemplateSettings": { "description": "Default template settings by type", "allOf": [ { "$ref": "#/components/schemas/UpdateDefaultTemplateSettingsDto" } ] }, "features": { "description": "Feature flags configuration", "allOf": [ { "$ref": "#/components/schemas/FeatureFlagsDto" } ] }, "webhookSettings": { "description": "Webhook configuration", "allOf": [ { "$ref": "#/components/schemas/WebhookSettingsDto" } ] }, "complianceSettings": { "description": "Compliance and governance settings", "allOf": [ { "$ref": "#/components/schemas/ComplianceSettingsDto" } ] } } }, "AccessScopeDto": { "type": "object", "properties": { "environments": { "type": "array", "description": "Environments user can access", "items": { "type": "string", "enum": [ "PROD", "STAGE", "DEV" ] } }, "sites": { "description": "Site IDs user can access", "type": "array", "items": { "type": "string" } }, "resources": { "description": "Resource-specific access", "type": "array", "items": { "type": "string" } } } }, "OrganizationMembershipDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Membership ID" }, "orgId": { "type": "string", "description": "Organization ID" }, "userId": { "type": "string", "description": "User ID" }, "role": { "type": "string", "description": "User role in the organization", "enum": [ "ORG_ADMIN", "LEGAL_AUTHOR", "COMPLIANCE_APPROVER", "PUBLISHER", "SECURITY_ADMIN", "DEVELOPER_INTEGRATION", "ANALYST", "SUPPORT_AUDITOR", "BILLING_ADMIN" ] }, "scope": { "description": "Access scope restrictions", "allOf": [ { "$ref": "#/components/schemas/AccessScopeDto" } ] }, "status": { "type": "string", "description": "Membership status", "enum": [ "ACTIVE", "INVITED", "SUSPENDED" ] }, "joinedAt": { "format": "date-time", "type": "string", "description": "Date when user joined" }, "expiresAt": { "format": "date-time", "type": "string", "description": "Date when membership expires" }, "invitedBy": { "type": "string", "description": "ID of user who invited this member" }, "invitedAt": { "format": "date-time", "type": "string", "description": "Date when user was invited" }, "createdAt": { "format": "date-time", "type": "string", "description": "Date when membership was created" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Date when membership was last updated" } }, "required": [ "id", "orgId", "userId", "role", "scope", "status", "joinedAt", "createdAt", "updatedAt" ] }, "UserDto": { "type": "object", "properties": { "id": { "type": "string", "description": "User ID" }, "email": { "type": "string", "description": "User email address" }, "name": { "type": "string", "description": "User full name" }, "isActive": { "type": "boolean", "description": "Whether user account is active" }, "lastLoginAt": { "format": "date-time", "type": "string", "description": "Last login timestamp" }, "createdAt": { "format": "date-time", "type": "string", "description": "User creation timestamp" }, "updatedAt": { "format": "date-time", "type": "string", "description": "User last update timestamp" }, "memberships": { "description": "User organization memberships", "type": "array", "items": { "$ref": "#/components/schemas/OrganizationMembershipDto" } } }, "required": [ "id", "email", "name", "isActive", "createdAt", "updatedAt", "memberships" ] }, "UserInvitationDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Invitation ID" }, "email": { "type": "string", "description": "Invited email address" }, "orgId": { "type": "string", "description": "Organization ID" }, "role": { "type": "string", "description": "Role for the invited user", "enum": [ "ORG_ADMIN", "LEGAL_AUTHOR", "COMPLIANCE_APPROVER", "PUBLISHER", "SECURITY_ADMIN", "DEVELOPER_INTEGRATION", "ANALYST", "SUPPORT_AUDITOR", "BILLING_ADMIN" ] }, "invitedBy": { "type": "string", "description": "ID of user who sent the invitation" }, "scope": { "description": "Access scope for the invited user", "allOf": [ { "$ref": "#/components/schemas/AccessScopeDto" } ] }, "token": { "type": "string", "description": "Invitation token" }, "status": { "type": "string", "description": "Invitation status" }, "expiresAt": { "format": "date-time", "type": "string", "description": "Date when invitation expires" }, "acceptedAt": { "format": "date-time", "type": "string", "description": "Date when invitation was accepted" }, "createdAt": { "format": "date-time", "type": "string", "description": "Date when invitation was created" } }, "required": [ "id", "email", "orgId", "role", "invitedBy", "scope", "token", "status", "expiresAt", "createdAt" ] }, "OrganizationMembersResponseDto": { "type": "object", "properties": { "members": { "description": "List of organization members", "type": "array", "items": { "$ref": "#/components/schemas/UserDto" } }, "invitations": { "description": "List of pending invitations", "type": "array", "items": { "$ref": "#/components/schemas/UserInvitationDto" } }, "total": { "type": "number", "description": "Total count of members" }, "activeMembers": { "type": "number", "description": "Count of active members" }, "pendingInvitations": { "type": "number", "description": "Count of pending invitations" } }, "required": [ "members", "invitations", "total", "activeMembers", "pendingInvitations" ] }, "InviteUserDto": { "type": "object", "properties": { "email": { "type": "string", "description": "Email address to invite" }, "role": { "type": "string", "description": "Role to assign to the invited user", "enum": [ "ORG_ADMIN", "LEGAL_AUTHOR", "COMPLIANCE_APPROVER", "PUBLISHER", "SECURITY_ADMIN", "DEVELOPER_INTEGRATION", "ANALYST", "SUPPORT_AUDITOR", "BILLING_ADMIN" ] }, "scope": { "description": "Access scope for the invited user", "allOf": [ { "$ref": "#/components/schemas/AccessScopeDto" } ] }, "expiresAt": { "format": "date-time", "type": "string", "description": "Expiration date for time-bounded access" } }, "required": [ "email", "role" ] }, "UpdateMembershipDto": { "type": "object", "properties": { "role": { "type": "string", "description": "New role for the user", "enum": [ "ORG_ADMIN", "LEGAL_AUTHOR", "COMPLIANCE_APPROVER", "PUBLISHER", "SECURITY_ADMIN", "DEVELOPER_INTEGRATION", "ANALYST", "SUPPORT_AUDITOR", "BILLING_ADMIN" ] }, "scope": { "description": "New access scope", "allOf": [ { "$ref": "#/components/schemas/AccessScopeDto" } ] }, "status": { "type": "string", "description": "New membership status", "enum": [ "ACTIVE", "INVITED", "SUSPENDED" ] }, "expiresAt": { "format": "date-time", "type": "string", "description": "New expiration date" } } }, "AcceptInvitationDto": { "type": "object", "properties": { "token": { "type": "string", "description": "Invitation token" }, "name": { "type": "string", "description": "User full name" }, "password": { "type": "string", "description": "User password (if not using SSO)" } }, "required": [ "token", "name" ] }, "EmailNotificationsDto": { "type": "object", "properties": { "acceptances": { "type": "boolean", "description": "Receive notifications for acceptances" }, "deployments": { "type": "boolean", "description": "Receive notifications for deployments" }, "systemUpdates": { "type": "boolean", "description": "Receive system update notifications" }, "weeklyReports": { "type": "boolean", "description": "Receive weekly reports" } }, "required": [ "acceptances", "deployments", "systemUpdates", "weeklyReports" ] }, "UserSettingsDto": { "type": "object", "properties": { "userId": { "type": "string", "description": "User ID" }, "timezone": { "type": "string", "description": "User timezone", "example": "UTC" }, "language": { "type": "string", "description": "User language preference", "example": "en" }, "theme": { "type": "string", "description": "UI theme preference", "enum": [ "light", "dark", "system" ] }, "emailNotifications": { "description": "Email notification preferences", "allOf": [ { "$ref": "#/components/schemas/EmailNotificationsDto" } ] }, "defaultDashboardView": { "type": "string", "description": "Default dashboard view", "enum": [ "overview", "templates", "evidence", "analytics" ] }, "itemsPerPage": { "type": "number", "description": "Items per page in lists", "example": 25 }, "twoFactorEnabled": { "type": "boolean", "description": "Whether two-factor authentication is enabled" }, "sessionTimeout": { "type": "number", "description": "Session timeout in minutes", "example": 480 }, "personalApiKey": { "type": "string", "description": "Personal API key (masked)" }, "personalApiKeyId": { "type": "string", "description": "Personal API key ID" }, "apiKeyCreatedAt": { "format": "date-time", "type": "string", "description": "API key creation timestamp" }, "apiKeyExpiresAt": { "format": "date-time", "type": "string", "description": "API key expiration timestamp" }, "createdAt": { "format": "date-time", "type": "string", "description": "Settings creation timestamp" }, "updatedAt": { "format": "date-time", "type": "string", "description": "Settings last update timestamp" } }, "required": [ "userId", "timezone", "language", "theme", "emailNotifications", "defaultDashboardView", "itemsPerPage", "twoFactorEnabled", "sessionTimeout", "createdAt", "updatedAt" ] }, "UpdateUserSettingsDto": { "type": "object", "properties": { "timezone": { "type": "string", "description": "User timezone" }, "language": { "type": "string", "description": "User language preference" }, "theme": { "type": "string", "description": "UI theme preference", "enum": [ "light", "dark", "system" ] }, "emailNotifications": { "description": "Email notification preferences", "allOf": [ { "$ref": "#/components/schemas/EmailNotificationsDto" } ] }, "defaultDashboardView": { "type": "string", "description": "Default dashboard view", "enum": [ "overview", "templates", "evidence", "analytics" ] }, "itemsPerPage": { "type": "number", "description": "Items per page in lists" }, "twoFactorEnabled": { "type": "boolean", "description": "Whether two-factor authentication is enabled" }, "sessionTimeout": { "type": "number", "description": "Session timeout in minutes" } } }, "PersonalApiKeyDto": { "type": "object", "properties": { "apiKey": { "type": "string", "description": "Generated API key" }, "keyId": { "type": "string", "description": "API key ID for reference" }, "createdAt": { "format": "date-time", "type": "string", "description": "Key creation timestamp" }, "expiresAt": { "format": "date-time", "type": "string", "description": "Key expiration timestamp" } }, "required": [ "apiKey", "keyId", "createdAt" ] }, "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" ] } } } }