{
  "openapi": "3.0.0",
  "info": {
    "title": "AI Presentations API",
    "version": "1.0.0",
    "description": "REST API for AI Presentations \u2014 an AI-powered presentation platform with narrated slides, live Q&A, and deck management.\n\n**Authentication**: Most endpoints require a session cookie obtained from `POST /api/auth/login`. Presentation playback endpoints (`/api/qa`, `/api/narration/*`) also accept a `presentationId` for unauthenticated viewer access.",
    "contact": {
      "name": "Demand IQ",
      "url": "https://demand-iq.com"
    }
  },
  "servers": [
    {
      "url": "https://app.demand-iq.com",
      "description": "Production"
    },
    {
      "url": "http://localhost:3000",
      "description": "Local development"
    }
  ],
  "tags": [
    {
      "name": "Decks",
      "description": "Manage presentation decks"
    },
    {
      "name": "Slides",
      "description": "Manage slides within a deck"
    },
    {
      "name": "FAQs",
      "description": "Manage pre-built Q&A pairs"
    },
    {
      "name": "Branding",
      "description": "Colors, logo, and call-to-action configuration"
    },
    {
      "name": "Q&A",
      "description": "Live question answering and Q&A settings"
    },
    {
      "name": "Narration",
      "description": "Text-to-speech synthesis"
    },
    {
      "name": "Presentations",
      "description": "Create and manage personalized presentation instances"
    },
    {
      "name": "Generation",
      "description": "AI-powered content generation from slide images"
    },
    {
      "name": "Images",
      "description": "Image upload and management"
    },
    {
      "name": "Voices",
      "description": "Available TTS voices"
    },
    {
      "name": "Utility",
      "description": "Health check and diagnostics"
    },
    {
      "name": "Authentication",
      "description": "Session-based login, logout, and identity"
    },
    {
      "name": "Company",
      "description": "Organization contact info and knowledge base"
    },
    {
      "name": "Notifications",
      "description": "Event subscriptions and delivery log"
    },
    {
      "name": "Contracts",
      "description": "Contract template import and e-signature"
    },
    {
      "name": "Fonts",
      "description": "Available Google Fonts for branding"
    },
    {
      "name": "Roof Measurements",
      "description": "Request and track automated roof measurements"
    },
    {
      "name": "Actions",
      "description": "Voice/text command detection for presentation control"
    },
    {
      "name": "Appointments",
      "description": "Appointment scheduling for presentation viewers"
    },
    {
      "name": "Activity",
      "description": "Recent presentation activity feed"
    },
    {
      "name": "Engagement",
      "description": "Presentation engagement analytics"
    },
    {
      "name": "Onboarding",
      "description": "Per-user product onboarding milestones (ENG-641). Milestone endpoints are idempotent and are called by the app UI \u2014 they should not be treated as tenant-integration surface."
    }
  ],
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "A Demand IQ API key or service token, passed in the `Authorization: Bearer` header."
      },
      "sessionCookie": {
        "type": "apiKey",
        "in": "cookie",
        "name": "session",
        "description": "Session cookie obtained from `POST /api/auth/login`."
      },
      "presentationToken": {
        "type": "apiKey",
        "in": "header",
        "name": "x-presentation-token",
        "description": "HMAC-signed token scoped to a specific presentation. Obtained from `POST /api/presentations/{presentationId}/events-token`."
      }
    },
    "schemas": {
      "ActivityEvent": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "eventType": {
            "type": "string",
            "description": "Event type, e.g. presentation.opened, slide.viewed, contract.signed"
          },
          "payload": {
            "type": "object",
            "nullable": true,
            "description": "Event-specific data"
          },
          "occurredAt": {
            "type": "string",
            "format": "date-time"
          },
          "presentationId": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "presentationName": {
            "type": "string",
            "description": "Homeowner full name derived from presentation data"
          },
          "address": {
            "type": "string",
            "nullable": true,
            "description": "Homeowner address (street, city, state)"
          },
          "deckId": {
            "type": "string",
            "format": "uuid",
            "nullable": true,
            "description": "Template ID for deep-linking to the template editor"
          }
        },
        "required": [
          "id",
          "eventType",
          "occurredAt",
          "presentationName"
        ]
      },
      "WordTiming": {
        "type": "object",
        "properties": {
          "word": {
            "type": "string"
          },
          "startTime": {
            "type": "number",
            "description": "Start time in milliseconds"
          },
          "endTime": {
            "type": "number",
            "description": "End time in milliseconds"
          }
        },
        "required": [
          "word",
          "startTime",
          "endTime"
        ]
      },
      "Deck": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string",
            "nullable": true
          },
          "type": {
            "type": "string",
            "enum": [
              "structured",
              "image-based"
            ]
          },
          "isActive": {
            "type": "boolean"
          },
          "metadata": {
            "type": "object",
            "nullable": true,
            "properties": {
              "deckContext": {
                "type": "string",
                "description": "Background info used to guide AI narration generation"
              },
              "voiceProvider": {
                "type": "string",
                "enum": [
                  "elevenlabs",
                  "openai"
                ]
              }
            }
          },
          "createdBy": {
            "type": "string",
            "format": "uuid",
            "nullable": true,
            "description": "ID of the user who created the deck. Null for decks created before creator tracking was added."
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "name",
          "type",
          "isActive",
          "createdAt",
          "updatedAt"
        ]
      },
      "DeckSummary": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string",
            "nullable": true
          },
          "type": {
            "type": "string",
            "enum": [
              "structured",
              "image-based"
            ]
          },
          "isActive": {
            "type": "boolean"
          },
          "previewImageUrl": {
            "type": "string",
            "format": "uri",
            "nullable": true,
            "description": "Presigned URL for the first slide image"
          },
          "previewImageThumbUrl": {
            "type": "string",
            "format": "uri",
            "nullable": true,
            "description": "Presigned URL for the 480px WebP thumbnail rendition of the first slide, sized for deck and template preview cards. Falls back to the full image URL when no thumbnail exists."
          },
          "generation": {
            "$ref": "#/components/schemas/GenerationStatus",
            "nullable": true,
            "description": "The latest unsettled generation job (pending, processing, or failed); null once it completed or if the deck was never generated"
          },
          "firstSlideType": {
            "type": "string",
            "enum": [
              "standard",
              "product_pricing_v1"
            ],
            "nullable": true,
            "description": "Slide type of the deck's first slide, or `null` if the deck has no slides. Used by clients to decide whether to render a product tier-card preview instead of the hero image."
          },
          "firstSlideProductData": {
            "allOf": [
              {
                "$ref": "#/components/schemas/ProductSlideData"
              }
            ],
            "nullable": true,
            "description": "Product slide configuration for the deck's first slide when `firstSlideType` is `product_pricing_v1`. `null` otherwise."
          },
          "brandingColors": {
            "type": "object",
            "nullable": true,
            "description": "Subset of the deck's branding palette used to render product slide previews. `null` if the deck has no branding configured.",
            "properties": {
              "primary": {
                "type": "string",
                "nullable": true,
                "example": "#1a73e8"
              },
              "neutral": {
                "type": "string",
                "nullable": true,
                "example": "#5f6368"
              }
            }
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Free-form labels stored on the deck metadata. Defaults to an empty array.",
            "default": []
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "name",
          "type",
          "isActive",
          "tags",
          "createdAt",
          "updatedAt"
        ]
      },
      "Slide": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "slideId": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "bullets": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "narration_script": {
            "type": "string"
          },
          "slide_context": {
            "type": "string",
            "nullable": true
          },
          "audio_url": {
            "type": "string",
            "nullable": true,
            "description": "S3 key for the slide audio file"
          },
          "hero_img": {
            "type": "string",
            "nullable": true,
            "description": "S3 key for the slide image"
          },
          "hero_img_thumb": {
            "type": "string",
            "nullable": true,
            "description": "Presigned URL for the 480px WebP thumbnail rendition of the hero image, sized for editor rails and library grid tiles. Falls back to the full image URL when no thumbnail exists (legacy uploads, SVGs, and images already at or below 480px). Present on deck read endpoints only; omitted from slide create/update responses."
          },
          "wordTimings": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/WordTiming"
            },
            "nullable": true
          },
          "orderIndex": {
            "type": "integer"
          },
          "slideType": {
            "type": "string",
            "enum": [
              "standard",
              "product_pricing_v1",
              "video"
            ]
          },
          "video_url": {
            "type": "string",
            "nullable": true,
            "description": "Canonical YouTube watch link (`https://www.youtube.com/watch?v=<id>`) on a `video` slide. `null` on other slide types."
          }
        },
        "required": [
          "id",
          "slideId",
          "title",
          "bullets",
          "narration_script",
          "orderIndex",
          "slideType"
        ]
      },
      "BrandingPalette": {
        "type": "object",
        "properties": {
          "primary": {
            "type": "string",
            "example": "#1a73e8"
          },
          "primaryLight": {
            "type": "string",
            "example": "#4a9af5"
          },
          "accent": {
            "type": "string",
            "example": "#fbbc04"
          },
          "neutral": {
            "type": "string",
            "example": "#5f6368"
          },
          "text": {
            "type": "string",
            "example": "#202124"
          },
          "userMessage": {
            "type": "string",
            "nullable": true,
            "description": "Background color for homeowner chat message bubbles. Falls back to primary color if not set.",
            "example": "#1a73e8"
          },
          "assistantMessage": {
            "type": "string",
            "nullable": true,
            "description": "Background color for AI assistant chat message bubbles.",
            "example": "#f1f3f4"
          }
        },
        "required": [
          "primary",
          "primaryLight",
          "accent",
          "neutral",
          "text"
        ]
      },
      "BrandingCta": {
        "type": "object",
        "properties": {
          "headline": {
            "type": "string"
          },
          "body": {
            "type": "string"
          },
          "buttonText": {
            "type": "string"
          },
          "buttonUrl": {
            "type": "string",
            "format": "uri"
          }
        },
        "required": [
          "headline",
          "body",
          "buttonText"
        ]
      },
      "Branding": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "deckId": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string",
            "nullable": true
          },
          "logo": {
            "type": "string",
            "nullable": true,
            "description": "S3 key for logo image"
          },
          "avatar": {
            "type": "string",
            "nullable": true,
            "description": "S3 key for rep avatar image"
          },
          "chatName": {
            "type": "string",
            "nullable": true
          },
          "chatGreeting": {
            "type": "string",
            "nullable": true
          },
          "palette": {
            "$ref": "#/components/schemas/BrandingPalette"
          },
          "cta": {
            "$ref": "#/components/schemas/BrandingCta"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "deckId",
          "palette",
          "cta",
          "createdAt",
          "updatedAt"
        ]
      },
      "Faq": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "deckId": {
            "type": "string",
            "format": "uuid"
          },
          "userQuestion": {
            "type": "string"
          },
          "cannedAnswer": {
            "type": "string"
          },
          "relatedSlideId": {
            "type": "string",
            "nullable": true
          },
          "audioUrl": {
            "type": "string",
            "nullable": true,
            "description": "S3 key for the pre-generated answer audio"
          },
          "wordTimings": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/WordTiming"
            },
            "nullable": true
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "deckId",
          "userQuestion",
          "cannedAnswer",
          "createdAt",
          "updatedAt"
        ]
      },
      "QaSettings": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "deckId": {
            "type": "string",
            "format": "uuid"
          },
          "resumePromptText": {
            "type": "string",
            "description": "Spoken prompt asking if the viewer wants to continue the presentation"
          },
          "resumeAudioUrl": {
            "type": "string",
            "nullable": true
          },
          "resumeVoiceId": {
            "type": "string",
            "nullable": true
          },
          "transitionPromptText": {
            "type": "string",
            "description": "Spoken bridge from Q&A back into the presentation"
          },
          "transitionAudioUrl": {
            "type": "string",
            "nullable": true
          },
          "transitionVoiceId": {
            "type": "string",
            "nullable": true
          }
        },
        "required": [
          "id",
          "deckId",
          "resumePromptText",
          "transitionPromptText"
        ]
      },
      "HomeownerData": {
        "type": "object",
        "properties": {
          "first_name": {
            "type": "string"
          },
          "last_name": {
            "type": "string"
          },
          "address": {
            "type": "string"
          },
          "city": {
            "type": "string"
          },
          "state": {
            "type": "string"
          },
          "zip": {
            "type": "string"
          },
          "country": {
            "type": "string",
            "minLength": 2,
            "maxLength": 2,
            "description": "ISO 3166-1 alpha-2 country code",
            "example": "US"
          },
          "email": {
            "type": "string",
            "format": "email"
          },
          "phone": {
            "type": "string"
          }
        },
        "required": [
          "first_name",
          "address",
          "city",
          "country"
        ]
      },
      "Presentation": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "deckId": {
            "type": "string",
            "format": "uuid"
          },
          "companyId": {
            "type": "string",
            "format": "uuid"
          },
          "status": {
            "type": "string",
            "enum": [
              "not_started",
              "pending",
              "processing",
              "ready",
              "failed"
            ]
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "The link the homeowner receives. This is the short link (`https://mypresi.co/<slug>`) when one exists. Otherwise it is the `/p/{presentationId}` URL with the same query parameters the delivery email uses."
          },
          "homeownerData": {
            "$ref": "#/components/schemas/HomeownerData"
          },
          "voiceSettings": {
            "type": "object",
            "nullable": true
          },
          "languageSettings": {
            "type": "object",
            "nullable": true
          },
          "createdBy": {
            "type": "string",
            "format": "uuid",
            "nullable": true,
            "description": "ID of the user who created the presentation. Null for presentations created by an automated integration rather than a user, and for presentations created before creator tracking was added."
          },
          "leadSource": {
            "type": "string",
            "nullable": true,
            "maxLength": 100,
            "description": "Origin of the lead this presentation was created for, captured once at creation time. The value names the Demand IQ application that recorded the prospect's first touch, such as `hero`, `web-lead`, `stella`, or `webhook`. `unknown` means the prospect exists but has no recorded first touch. Null for presentations created before lead source tracking was added, and for presentations where the origin could not be determined."
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          },
          "sentAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Earliest accepted delivery attempt (`status = 'sent'`), aggregated across every attempt on the presentation. Skipped and failed attempts do not count as sends. `null` when no attempt has been accepted, including for presentations shared by a rep rather than emailed. Delivery half of the status ladder Created \u2192 Sent \u2192 Email Opened \u2192 Viewed (the badge shows the furthest rung reached)."
          },
          "emailOpenedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Earliest SendGrid `open` event across every delivery attempt on the presentation, machine opens included. Apple Mail Privacy Protection prefetches the tracking pixel, and for an MPP recipient the machine open is often the only open SendGrid ever reports, so it counts toward the badge. The activity log marks machine opens separately on the `email.opened` entry (see `EventLogEntry.machineOpen`)."
          },
          "firstViewedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "When the presentation link was first requested. Stamped server-side on the document request for `/p/{presentationId}`, before any client JS runs. This is what flips the badge to Viewed. `null` until the link has been opened at least once."
          },
          "deletedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        },
        "required": [
          "id",
          "deckId",
          "companyId",
          "status",
          "url",
          "createdAt",
          "updatedAt"
        ]
      },
      "PresentationSlide": {
        "type": "object",
        "description": "A slide as served to the presentation viewer. Media URLs are presigned and expire, so responses containing this schema must not be cached.",
        "properties": {
          "id": {
            "type": "string"
          },
          "deckSlideId": {
            "type": "string",
            "format": "uuid"
          },
          "slideId": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "bullets": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "narrationScript": {
            "type": "string"
          },
          "audioUrl": {
            "type": "string",
            "description": "Presigned URL for the slide's narration audio. Expires after a short window."
          },
          "heroImg": {
            "type": "string",
            "description": "Presigned URL for the slide image. Expires after a short window."
          },
          "wordTimings": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/WordTiming"
            }
          },
          "position": {
            "type": "integer"
          },
          "slideType": {
            "type": "string",
            "enum": [
              "standard",
              "product_pricing_v1"
            ],
            "description": "Defaults to `standard` when omitted."
          },
          "productData": {
            "$ref": "#/components/schemas/ProductSlideData"
          }
        },
        "required": [
          "id",
          "slideId",
          "title",
          "bullets",
          "narrationScript",
          "position"
        ]
      },
      "PresentationQaSettings": {
        "type": "object",
        "description": "Q&A prompt configuration as served to the presentation viewer, with presigned audio URLs.",
        "properties": {
          "resumePromptText": {
            "type": "string",
            "description": "Spoken prompt asking if the viewer wants to continue the presentation"
          },
          "resumePromptAudioUrl": {
            "type": "string",
            "nullable": true,
            "description": "Presigned URL for the resume prompt audio"
          },
          "resumePromptWordTimings": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/WordTiming"
            },
            "nullable": true
          },
          "resumePromptVoiceId": {
            "type": "string",
            "nullable": true
          },
          "transitionPromptText": {
            "type": "string",
            "description": "Spoken bridge from Q&A back into the presentation"
          },
          "transitionPromptAudioUrl": {
            "type": "string",
            "nullable": true,
            "description": "Presigned URL for the transition prompt audio"
          },
          "transitionPromptWordTimings": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/WordTiming"
            },
            "nullable": true
          },
          "transitionPromptVoiceId": {
            "type": "string",
            "nullable": true
          }
        },
        "required": [
          "resumePromptText",
          "transitionPromptText"
        ]
      },
      "NarrationResponse": {
        "type": "object",
        "properties": {
          "slideId": {
            "type": "string"
          },
          "script": {
            "type": "string"
          },
          "audioUrl": {
            "type": "string",
            "description": "Accessible URL for the synthesized audio"
          },
          "wordTimings": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/WordTiming"
            }
          },
          "source": {
            "type": "string",
            "enum": [
              "elevenlabs",
              "openai",
              "fallback"
            ]
          }
        },
        "required": [
          "slideId",
          "script",
          "audioUrl",
          "source"
        ]
      },
      "QaResponse": {
        "type": "object",
        "properties": {
          "answer": {
            "type": "string"
          },
          "audioUrl": {
            "type": "string",
            "description": "URL for the spoken audio of the answer. Either an accessible stored file, or a relative `/api/qa/audio?t=\u2026` URL that synthesizes the audio on request when `audioStreamed` is `true`."
          },
          "audioStreamed": {
            "type": "boolean",
            "description": "`true` when `audioUrl` streams the audio as it is synthesized. Streamed audio can't be seeked while it plays."
          },
          "wordTimings": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/WordTiming"
            }
          },
          "source": {
            "type": "string",
            "enum": [
              "faq",
              "cached",
              "openai",
              "fallback"
            ]
          },
          "relatedSlideId": {
            "type": "string",
            "nullable": true
          }
        },
        "required": [
          "answer",
          "audioUrl",
          "source"
        ]
      },
      "GenerationStatus": {
        "type": "object",
        "description": "A deck generation job. The single-job endpoint (`GET /api/decks/{deckId}/generate/status`) adds the row counts and timestamps; the deck list and the per-organization poll carry only the fields common to both.",
        "properties": {
          "jobId": {
            "type": "string",
            "format": "uuid"
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "processing",
              "completed",
              "failed"
            ]
          },
          "currentSlide": {
            "type": "integer",
            "nullable": true,
            "description": "The slide that most recently STARTED processing; completed work is currentSlide \u2212 1"
          },
          "totalSlides": {
            "type": "integer",
            "nullable": true,
            "description": "0 until the job flips to processing"
          },
          "progress": {
            "type": "integer",
            "description": "0-100, derived from completed slides / totalSlides; 100 once settled"
          },
          "error": {
            "type": "string",
            "nullable": true
          },
          "slidesCreated": {
            "type": "integer",
            "description": "Slide rows that exist for the deck right now. This is the signal to refresh on: currentSlide marks a slide's start, and the row lands a full slide's work later. Single-job endpoint only."
          },
          "faqsCreated": {
            "type": "integer",
            "description": "FAQ rows that exist right now. The job tracks no FAQ state; they are written in one batch after the last slide. Single-job endpoint only."
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "Single-job endpoint only"
          },
          "completedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Single-job endpoint only"
          }
        },
        "required": [
          "jobId",
          "status",
          "currentSlide",
          "totalSlides",
          "progress"
        ]
      },
      "Image": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "organizationId": {
            "type": "string",
            "format": "uuid"
          },
          "filename": {
            "type": "string"
          },
          "s3Key": {
            "type": "string"
          },
          "mimeType": {
            "type": "string"
          },
          "size": {
            "type": "integer",
            "description": "File size in bytes"
          },
          "width": {
            "type": "integer",
            "nullable": true
          },
          "height": {
            "type": "integer",
            "nullable": true
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "Presigned URL for the image"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "organizationId",
          "filename",
          "s3Key",
          "mimeType",
          "size",
          "url",
          "createdAt"
        ]
      },
      "Voice": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "gender": {
            "type": "string"
          },
          "accent": {
            "type": "string"
          },
          "age": {
            "type": "string"
          },
          "useCase": {
            "type": "string"
          },
          "previewUrl": {
            "type": "string",
            "format": "uri"
          },
          "isDefault": {
            "type": "boolean"
          }
        },
        "required": [
          "id",
          "name",
          "isDefault"
        ]
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          }
        },
        "required": [
          "error"
        ]
      },
      "User": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "email": {
            "type": "string",
            "format": "email"
          },
          "name": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "email",
          "name"
        ]
      },
      "Organization": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "isLibraryAuthor": {
            "type": "boolean",
            "description": "Whether this organization can publish shared library templates."
          },
          "welcomeSeenAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Timestamp when the org first exited the welcome wizard (saved or skipped the confirm-info step). `null` for organizations that have never completed the wizard."
          }
        },
        "required": [
          "id",
          "name"
        ]
      },
      "CompanyContact": {
        "type": "object",
        "properties": {
          "phone": {
            "type": "string",
            "nullable": true
          },
          "email": {
            "type": "string",
            "format": "email",
            "nullable": true
          },
          "address": {
            "type": "string",
            "nullable": true
          },
          "city": {
            "type": "string",
            "nullable": true
          },
          "state": {
            "type": "string",
            "nullable": true
          },
          "zip": {
            "type": "string",
            "nullable": true
          },
          "licenseNumber": {
            "type": "string",
            "nullable": true
          },
          "timezone": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "KbProfile": {
        "type": "object",
        "properties": {
          "tenantId": {
            "type": "string",
            "format": "uuid"
          },
          "tagline": {
            "type": "string",
            "nullable": true
          },
          "about": {
            "type": "string",
            "nullable": true
          },
          "trustSignals": {
            "type": "string",
            "nullable": true
          },
          "serviceCoverage": {
            "type": "string",
            "nullable": true
          },
          "answerStyle": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "KbDocument": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "tenantId": {
            "type": "string",
            "format": "uuid"
          },
          "filename": {
            "type": "string"
          },
          "displayName": {
            "type": "string",
            "nullable": true
          },
          "contentType": {
            "type": "string"
          },
          "sizeBytes": {
            "type": "integer"
          },
          "status": {
            "type": "string",
            "enum": [
              "uploading",
              "pending",
              "processing",
              "ready",
              "failed"
            ]
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "tenantId",
          "filename",
          "contentType",
          "sizeBytes",
          "status",
          "createdAt"
        ]
      },
      "ActionConfig": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "deckId": {
            "type": "string",
            "format": "uuid"
          },
          "actionType": {
            "type": "string"
          },
          "templateMarkdown": {
            "type": "string"
          },
          "disclosuresMarkdown": {
            "type": "string",
            "nullable": true
          },
          "requirementsJson": {
            "type": "object",
            "nullable": true
          },
          "repName": {
            "type": "string",
            "nullable": true
          },
          "status": {
            "type": "string",
            "enum": [
              "draft",
              "published"
            ]
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "deckId",
          "actionType",
          "templateMarkdown",
          "status",
          "createdAt",
          "updatedAt"
        ]
      },
      "IntroConfig": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "deckId": {
            "type": "string",
            "format": "uuid"
          },
          "backgroundImage": {
            "type": "string",
            "description": "S3 key or URL for intro background image"
          },
          "headline": {
            "type": "string"
          },
          "subtitle": {
            "type": "string",
            "nullable": true
          },
          "ctaButtonLabel": {
            "type": "string",
            "nullable": true
          },
          "homePhotoEnabled": {
            "type": "boolean",
            "description": "Whether the intro page shows a photo of the homeowner's home above the headline."
          }
        },
        "required": [
          "id",
          "deckId",
          "backgroundImage",
          "headline"
        ]
      },
      "NotificationSubscription": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "organizationId": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "eventType": {
            "type": "string"
          },
          "channel": {
            "type": "string",
            "enum": [
              "webhook",
              "email",
              "console"
            ]
          },
          "channelConfig": {
            "type": "object",
            "description": "Channel-specific configuration (e.g. URL for webhook, toEmails for email)"
          },
          "deckId": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "isActive": {
            "type": "boolean"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "organizationId",
          "name",
          "eventType",
          "channel",
          "channelConfig",
          "isActive",
          "createdAt",
          "updatedAt"
        ]
      },
      "EventLogEntry": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "eventType": {
            "type": "string"
          },
          "aggregateType": {
            "type": "string"
          },
          "aggregateId": {
            "type": "string"
          },
          "payload": {
            "type": "object",
            "description": "Event payload. Carries identifiers (e.g. `presentationId`, `deliveryId`), never contact details such as email addresses. On entries with `archivedAt` set, the payload is reduced to identifier and classification fields; question and answer text is removed."
          },
          "recipientEmail": {
            "type": "string",
            "nullable": true,
            "description": "Present on `email.sent` entries only. The recipient of that delivery, resolved from the delivery attempt referenced by the payload's `deliveryId`. `null` when the delivery attempt has no recipient on record."
          },
          "skipReason": {
            "type": "string",
            "nullable": true,
            "enum": [
              "no_email",
              "suppressed",
              "presentation_parked",
              "presentation_failed",
              "no_initial_send",
              "reminder_disabled",
              "opened",
              "viewed",
              null
            ],
            "description": "Present on `email.sent` entries only. Why the delivery attempt was skipped, resolved from the delivery attempt referenced by the payload's `deliveryId`. `no_email` means the homeowner had no email address. `suppressed` means a recipient previously hard-bounced, reported spam, or unsubscribed within the last 90 days, so AI Presentations sent nothing. The remaining values apply to reminder attempts (`variant` is `reminder`): `opened` means the homeowner already opened the first email, `viewed` means the homeowner already viewed the presentation, `no_initial_send` means the first email was never sent, `reminder_disabled` means reminders are off for the deck's template, and `presentation_parked` or `presentation_failed` means the presentation isn't ready. `null` when the attempt was not skipped."
          },
          "variant": {
            "type": "string",
            "nullable": true,
            "enum": [
              "initial",
              "reminder",
              null
            ],
            "description": "Present on `email.sent` entries only. Which send the delivery attempt represents, resolved from the delivery attempt referenced by the payload's `deliveryId`. `initial` is the first presentation email. `reminder` is the follow-up sent to a homeowner who never opened the first email. `null` when no matching delivery attempt was found. The activity log labels reminder entries as `Reminder Sent`, `Reminder Failed`, `Reminder Not Needed` (skipped because of `opened` or `viewed`), or `Reminder Not Sent` (any other skip reason, including `reminder_disabled`)."
          },
          "machineOpen": {
            "type": "boolean",
            "description": "Present on `email.opened` entries only. `true` when every open SendGrid reported for the delivery attempt was a machine open (for example, an Apple Mail Privacy Protection prefetch of the tracking pixel). `false` when at least one human open has been recorded, or when no matching delivery attempt was found. Render machine opens as `Email Opened (automatic)` to distinguish them from a real read."
          },
          "occurredAt": {
            "type": "string",
            "format": "date-time"
          },
          "archivedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Set when the entry has aged past the 90-day retention window. The entry stays in the log, but its payload keeps identifier and classification fields only. For `question.asked` and `question.escalated`, the question and answer text is removed. `null` for entries still inside the window."
          }
        },
        "required": [
          "id",
          "eventType",
          "aggregateType",
          "aggregateId",
          "occurredAt"
        ]
      },
      "ProductSlideData": {
        "type": "object",
        "description": "Good/better/best product pricing tiers for a product pricing slide.",
        "properties": {
          "good": {
            "type": "object",
            "nullable": true
          },
          "better": {
            "type": "object",
            "nullable": true
          },
          "best": {
            "type": "object",
            "nullable": true
          },
          "subtitle": {
            "type": "string",
            "nullable": true
          },
          "brandLogo": {
            "type": "string",
            "nullable": true,
            "deprecated": true,
            "description": "Deprecated. The product pricing slide always renders the deck's branding logo (set via `PUT /api/decks/{deckId}/branding`). This field is still accepted and stored, but the viewer and editor ignore it."
          },
          "disclaimer": {
            "type": "string",
            "nullable": true
          },
          "defaultSelectedTier": {
            "type": "string",
            "enum": [
              "good",
              "better",
              "best"
            ],
            "nullable": true
          }
        }
      },
      "Font": {
        "type": "object",
        "properties": {
          "family": {
            "type": "string",
            "example": "Inter"
          },
          "variants": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "category": {
            "type": "string",
            "example": "sans-serif"
          }
        },
        "required": [
          "family",
          "variants",
          "category"
        ]
      },
      "TourState": {
        "type": "object",
        "description": "Per-user state for the presentations onboarding modal (ENG-641; versioned in ENG-636). The modal shows at most once per user across devices per content version. The show/hide decision keys on `tourVersion`: whenever it is less than the current content version, the modal is shown. `tourCompletedAt` means the user clicked the \"Get Started\" button on the single-screen video modal; `tourDismissedAt` covers every other close (X, Esc, navigation, or a silent legacy backfill from the old per-browser `localStorage` flag). Both timestamps are written once and never cleared, so they preserve the first-ever moment even after later content versions are acknowledged.",
        "properties": {
          "tourCompletedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Timestamp of the first-ever completion. `null` until the user clicks \"Get Started\" for the first time. Never overwritten by a later version acknowledgement."
          },
          "tourDismissedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Timestamp of the first-ever dismissal. `null` until dismissed. Never overwritten by a later version acknowledgement."
          },
          "tourVersion": {
            "type": "integer",
            "description": "Highest onboarding content version the user has acknowledged. `0` = never onboarded, `1` = illustrated multi-step tour (ENG-641), `2` = Wistia explainer video (ENG-636). The modal shows whenever this is below the current content version. Bumping the current version re-shows the modal to every user exactly once."
          }
        },
        "required": [
          "tourCompletedAt",
          "tourDismissedAt",
          "tourVersion"
        ]
      },
      "EngagementRate": {
        "type": "object",
        "description": "A rate returned as its raw numerator and denominator rather than a pre-computed percentage, so you can hide rates whose denominator is too small to be meaningful. `unknown` counts items whose underlying data is no longer available, which is distinct from a real 0.",
        "properties": {
          "numerator": {
            "type": "integer",
            "example": 42
          },
          "denominator": {
            "type": "integer",
            "example": 120
          },
          "unknown": {
            "type": "integer",
            "example": 0
          }
        },
        "required": [
          "numerator",
          "denominator",
          "unknown"
        ]
      },
      "EngagementRateMetric": {
        "type": "object",
        "properties": {
          "rate": {
            "$ref": "#/components/schemas/EngagementRate"
          },
          "percentChange": {
            "type": "number",
            "nullable": true,
            "example": 0.15,
            "description": "Relative change in the ratio (numerator / denominator) compared with the equal-length window immediately before the requested one. `0.15` means +15%. `null` when the prior window could not be loaded because it exceeded the size limit, when either window has a denominator of 0, or when the prior ratio was 0 and the current one is not. A prior ratio of 0 and a current ratio of 0 returns `0`."
          },
          "directional": {
            "type": "boolean",
            "example": true,
            "description": "`true` when the metric varies too much between companies at current volume to trend reliably. Display it as a directional indicator rather than a trend."
          }
        },
        "required": [
          "rate",
          "percentChange",
          "directional"
        ]
      },
      "EngagementCountMetric": {
        "type": "object",
        "properties": {
          "count": {
            "type": "integer",
            "example": 120
          },
          "percentChange": {
            "type": "number",
            "nullable": true,
            "example": -0.08,
            "description": "Relative change compared with the equal-length window immediately before the requested one. `0.15` means +15%. `null` when the prior window could not be loaded because it exceeded the size limit, or when the prior count was 0 and the current count is not. A prior count of 0 and a current count of 0 returns `0`."
          }
        },
        "required": [
          "count",
          "percentChange"
        ]
      },
      "EngagementFunnelStep": {
        "type": "object",
        "description": "One step of the engagement funnel.",
        "properties": {
          "count": {
            "type": "integer",
            "example": 96,
            "description": "Presentations created in the window that reached this step."
          },
          "overPrevious": {
            "allOf": [
              {
                "$ref": "#/components/schemas/EngagementRate"
              }
            ],
            "description": "Presentations that reached both this step and the previous one, over the presentations that reached the previous step. Because both steps are required, this rate never exceeds 100%."
          },
          "overCreated": {
            "allOf": [
              {
                "$ref": "#/components/schemas/EngagementRate"
              }
            ],
            "description": "Presentations that reached this step, over the presentations created in the window."
          }
        },
        "required": [
          "count",
          "overPrevious",
          "overCreated"
        ]
      },
      "EngagementFunnel": {
        "type": "object",
        "description": "The Created \u2192 Sent \u2192 Opened \u2192 Started \u2192 Completed funnel for presentations created in the window. Each step reports a count, a rate over the previous step, and a rate over Created. `completed.overCreated` is the headline conversion rate.",
        "properties": {
          "created": {
            "type": "integer",
            "example": 120,
            "description": "Presentations created in the window."
          },
          "sent": {
            "allOf": [
              {
                "$ref": "#/components/schemas/EngagementFunnelStep"
              }
            ],
            "description": "Presentations with at least one accepted email send. `overPrevious` is over Created."
          },
          "opened": {
            "allOf": [
              {
                "$ref": "#/components/schemas/EngagementFunnelStep"
              }
            ],
            "description": "Presentations whose viewer page loaded at least once. A presentation opened from a copied link counts toward `count` but not toward `overPrevious`, which is over Sent."
          },
          "started": {
            "allOf": [
              {
                "$ref": "#/components/schemas/EngagementFunnelStep"
              }
            ],
            "description": "Presentations where the viewer pressed Start on the intro screen. Only presentations opened on an intro count. `overPrevious` is over opened presentations that showed an intro. An opened presentation with no recorded start that was first viewed before AI Presentations began recording starts counts as `unknown`."
          },
          "completed": {
            "allOf": [
              {
                "$ref": "#/components/schemas/EngagementFunnelStep"
              }
            ],
            "description": "Presentations whose viewer reached the last slide. `overPrevious` is over Started."
          },
          "noStartStep": {
            "type": "integer",
            "example": 14,
            "description": "Opened presentations that had no intro screen, so the viewer had no Start to press. These are left out of `started` rather than counted as a 0% start rate."
          }
        },
        "required": [
          "created",
          "sent",
          "opened",
          "started",
          "completed",
          "noStartStep"
        ]
      },
      "EngagementSummary": {
        "type": "object",
        "description": "The seven engagement metrics for your organization over the requested window, plus the engagement funnel, visits per opened presentation, and delivery path counts.",
        "properties": {
          "window": {
            "type": "object",
            "description": "The window the metrics cover: the requested `since`/`until`, or the last 30 days ending at request time.",
            "properties": {
              "from": {
                "type": "string",
                "format": "date-time",
                "example": "2026-09-01T00:00:00.000Z"
              },
              "until": {
                "type": "string",
                "format": "date-time",
                "example": "2026-10-01T00:00:00.000Z"
              }
            },
            "required": [
              "from",
              "until"
            ]
          },
          "deckId": {
            "type": "string",
            "format": "uuid",
            "nullable": true,
            "description": "The template filter applied, or `null` when the summary covers all templates."
          },
          "presentationsSent": {
            "allOf": [
              {
                "$ref": "#/components/schemas/EngagementCountMetric"
              }
            ],
            "description": "Presentations successfully sent in the window."
          },
          "opened": {
            "allOf": [
              {
                "$ref": "#/components/schemas/EngagementRateMetric"
              }
            ],
            "description": "Presentations whose viewer page was loaded at least once. This is not the email-open signal. Includes opens by a signed-in member of your organization, so previewing your own presentation link counts as an open. `rate.denominator` is the number of presentations created in the window."
          },
          "avgConsumption": {
            "allOf": [
              {
                "$ref": "#/components/schemas/EngagementRateMetric"
              }
            ],
            "description": "Slides consumed out of the total slides in opened presentations created in the window. Unopened presentations are excluded, so this reflects viewing behavior rather than open rate. Slides viewed by a signed-in member of your organization are excluded."
          },
          "ctaClicks": {
            "allOf": [
              {
                "$ref": "#/components/schemas/EngagementRateMetric"
              }
            ],
            "description": "Call-to-action clicks. `rate.denominator` excludes presentations from templates with no call to action configured. Clicks by a signed-in member of your organization are excluded."
          },
          "questionsAsked": {
            "type": "object",
            "description": "Questions viewers asked during presentations. Questions asked by a signed-in member of your organization are excluded.",
            "properties": {
              "count": {
                "type": "integer",
                "example": 37
              },
              "percentChange": {
                "type": "number",
                "nullable": true,
                "example": 0.12,
                "description": "Relative change in `count` compared with the prior window. Follows the same rules as `EngagementCountMetric.percentChange`."
              },
              "escalated": {
                "type": "integer",
                "example": 4,
                "description": "Questions the AI could not answer or answered with low confidence. A breakdown of `count`, so it has no `percentChange` of its own."
              }
            },
            "required": [
              "count",
              "percentChange",
              "escalated"
            ]
          },
          "appointmentsBooked": {
            "allOf": [
              {
                "$ref": "#/components/schemas/EngagementCountMetric"
              }
            ],
            "description": "Appointments booked from presentations."
          },
          "contractsSigned": {
            "allOf": [
              {
                "$ref": "#/components/schemas/EngagementCountMetric"
              }
            ],
            "description": "Contracts signed from presentations."
          },
          "funnel": {
            "allOf": [
              {
                "$ref": "#/components/schemas/EngagementFunnel"
              }
            ],
            "description": "The Created \u2192 Completed funnel for presentations created in the window."
          },
          "visits": {
            "type": "object",
            "description": "Visits per opened presentation. AI Presentations splits a presentation's opens into separate visits wherever 30 minutes pass between opens. Each opened presentation counts as at least one visit. Treat these values as a lower bound, because opens are rate-limited.",
            "properties": {
              "opened": {
                "type": "integer",
                "example": 82,
                "description": "Opened presentations the averages are computed over."
              },
              "avg": {
                "type": "number",
                "nullable": true,
                "example": 1.6,
                "description": "Mean visits per opened presentation. `null` when `opened` is 0."
              },
              "median": {
                "type": "number",
                "nullable": true,
                "example": 1,
                "description": "Median visits per opened presentation. `null` when `opened` is 0."
              }
            },
            "required": [
              "opened",
              "avg",
              "median"
            ]
          },
          "deliveryPath": {
            "type": "object",
            "description": "How opened presentations reached the viewer.",
            "properties": {
              "viewedWithoutEmailOpen": {
                "type": "integer",
                "example": 11,
                "description": "Opened presentations that were sent and delivered by email, with no email open by a person recorded."
              },
              "viewedWithoutSend": {
                "type": "integer",
                "example": 7,
                "description": "Opened presentations that were never sent by email, for example because the link was copied and shared directly."
              },
              "byOpenSource": {
                "type": "object",
                "additionalProperties": {
                  "type": "integer"
                },
                "example": {
                  "email": 42,
                  "journeys": 9,
                  "none": 15
                },
                "description": "Opened presentations counted by the `utm_source` on the link of their first homeowner open. `email` means AI Presentations sent the link. Any other key is the value the system that shared the link declared. `none` counts opens with no source, including every open recorded before this breakdown was added."
              }
            },
            "required": [
              "viewedWithoutEmailOpen",
              "viewedWithoutSend",
              "byOpenSource"
            ]
          }
        },
        "required": [
          "window",
          "deckId",
          "presentationsSent",
          "opened",
          "avgConsumption",
          "ctaClicks",
          "questionsAsked",
          "appointmentsBooked",
          "contractsSigned",
          "funnel",
          "visits",
          "deliveryPath"
        ]
      },
      "TemplateVersionPerformance": {
        "type": "object",
        "description": "Email performance for one email template version, counted on first sends to a recipient outside Demand IQ and your organization's own users.",
        "properties": {
          "templateVersionId": {
            "type": "string",
            "format": "uuid",
            "nullable": true,
            "example": "3f1c9a2e-7b4d-4e8a-9c21-5d6f0a8b1e47",
            "description": "The email template version. `null` marks the \"Unknown version\" row, which holds first sends made before AI Presentations recorded template versions. These sends are never assigned to your current copy."
          },
          "copy": {
            "type": "object",
            "nullable": true,
            "description": "The version's email copy before tokens are filled in. `null` on the unknown version row.",
            "properties": {
              "subject": {
                "type": "string",
                "example": "{{homeowner.first_name}}, your roof presentation is ready"
              },
              "preheader": {
                "type": "string",
                "example": "Watch a 3-minute walkthrough of your quote"
              },
              "bodyTemplate": {
                "type": "string",
                "example": "Hi {{homeowner.first_name}},\n\nYour personalized roof presentation is ready. Watch it any time.",
                "description": "The email body."
              },
              "ctaLabel": {
                "type": "string",
                "example": "Watch your presentation"
              },
              "fromName": {
                "type": "string",
                "nullable": true,
                "example": "Summit Roofing",
                "description": "The sender name. `null` means your organization's name."
              },
              "createdAt": {
                "type": "string",
                "format": "date-time",
                "example": "2026-09-14T16:02:11.000Z",
                "description": "When AI Presentations first recorded this copy, on a save or a send by any template. Use `firstSavedAt` and `firstSentAt` to date a version on one template's list."
              }
            },
            "required": [
              "subject",
              "preheader",
              "bodyTemplate",
              "ctaLabel",
              "fromName",
              "createdAt"
            ]
          },
          "kind": {
            "type": "string",
            "enum": [
              "deck",
              "default",
              "previous_default",
              "unknown"
            ],
            "example": "deck",
            "description": "Where the version's copy came from. `deck` is copy saved on a template. `default` is the current Demand IQ default copy. `previous_default` is an earlier Demand IQ default. `unknown` is the row for sends made before AI Presentations recorded template versions."
          },
          "current": {
            "type": "boolean",
            "example": true,
            "description": "`true` for the template's active version: the copy it sends now. Always `false` when you omit `deckId`."
          },
          "sent": {
            "type": "integer",
            "example": 148,
            "description": "Presentations whose first send to the homeowner used this version. In the organization-wide view, only first sends in the window count."
          },
          "delivered": {
            "allOf": [
              {
                "$ref": "#/components/schemas/EngagementRate"
              }
            ],
            "description": "Delivered first sends over first sends whose delivery outcome is known. `unknown` counts sends whose outcome is no longer available."
          },
          "emailOpened": {
            "allOf": [
              {
                "$ref": "#/components/schemas/EngagementRate"
              }
            ],
            "description": "First sends a person opened over delivered first sends. Automatic opens, such as Apple Mail Privacy Protection prefetches, are excluded. Compare versions on this rate."
          },
          "started": {
            "allOf": [
              {
                "$ref": "#/components/schemas/EngagementRate"
              }
            ],
            "description": "Homeowners who started the presentation after the first send over first sends a person opened. A start is the first time the viewer showed slides to a homeowner. Visits by your own team, rep-mode visits, and link scanners don't count. Opened sends from before AI Presentations began recording starts count as `unknown`."
          },
          "reportable": {
            "type": "boolean",
            "example": true,
            "description": "`false` when fewer first sends were delivered than `minimumDelivered`. Treat the rates as directional only."
          },
          "fallbackSent": {
            "type": "integer",
            "example": 3,
            "description": "First sends whose subject or preview text fell back to the default because a token rendered empty. The homeowner never saw this version's copy, so these sends are left out of `sent` and every rate."
          }
        },
        "required": [
          "templateVersionId",
          "copy",
          "kind",
          "current",
          "sent",
          "delivered",
          "emailOpened",
          "started",
          "reportable",
          "fallbackSent"
        ]
      },
      "TemplatePerformance": {
        "type": "object",
        "description": "Email performance per email template version for your organization over the requested window.",
        "properties": {
          "window": {
            "type": "object",
            "description": "The window the first sends fall in: the requested `since`/`until`, or the last 30 days ending at request time.",
            "properties": {
              "from": {
                "type": "string",
                "format": "date-time",
                "example": "2026-09-01T00:00:00.000Z"
              },
              "until": {
                "type": "string",
                "format": "date-time",
                "example": "2026-10-01T00:00:00.000Z"
              }
            },
            "required": [
              "from",
              "until"
            ]
          },
          "deckId": {
            "type": "string",
            "format": "uuid",
            "nullable": true,
            "description": "Always `null`. A request with `deckId` returns `DeckTemplateList` instead."
          },
          "minimumDelivered": {
            "type": "integer",
            "example": 10,
            "description": "The smallest number of delivered first sends at which a version's rates are `reportable`."
          },
          "versions": {
            "type": "array",
            "description": "One entry per email template version, newest first. The unknown version row, if present, is last.",
            "items": {
              "$ref": "#/components/schemas/TemplateVersionPerformance"
            }
          }
        },
        "required": [
          "window",
          "deckId",
          "minimumDelivered",
          "versions"
        ]
      },
      "DeckTemplate": {
        "description": "One version on a template's version list, with all-time counts.",
        "allOf": [
          {
            "$ref": "#/components/schemas/TemplateVersionPerformance"
          },
          {
            "type": "object",
            "properties": {
              "firstSavedAt": {
                "type": "string",
                "format": "date-time",
                "nullable": true,
                "example": "2026-09-14T16:02:11.000Z",
                "description": "When this template first saved this version. `null` for a version that was only ever sent."
              },
              "firstSentAt": {
                "type": "string",
                "format": "date-time",
                "nullable": true,
                "example": "2026-09-15T13:40:02.000Z",
                "description": "This template's earliest counted first send of this version. `null` when it has none."
              }
            },
            "required": [
              "firstSavedAt",
              "firstSentAt"
            ]
          }
        ]
      },
      "DeckTemplateList": {
        "type": "object",
        "description": "Every version of a template's email copy, with all-time counts.",
        "properties": {
          "deckId": {
            "type": "string",
            "format": "uuid",
            "example": "8b2e4f10-3c6a-4d9e-a1f7-62c0b5d9e384"
          },
          "minimumDelivered": {
            "type": "integer",
            "example": 10,
            "description": "The smallest number of delivered first sends at which a version's rates are `reportable`."
          },
          "versions": {
            "type": "array",
            "description": "Every version the template has had, all-time, with removed versions left out. The active version comes first, then the newest by `firstSavedAt` or else `firstSentAt`. The unknown version row, if present, is last. The active version is always present. Its `templateVersionId` is `null` when its copy was never saved or sent.",
            "items": {
              "$ref": "#/components/schemas/DeckTemplate"
            }
          }
        },
        "required": [
          "deckId",
          "minimumDelivered",
          "versions"
        ]
      },
      "QuestionOutcomeCounts": {
        "type": "object",
        "description": "Question counts by outcome.",
        "properties": {
          "asked": {
            "type": "integer",
            "example": 48,
            "description": "Total questions asked."
          },
          "answered": {
            "type": "integer",
            "example": 39
          },
          "low_confidence": {
            "type": "integer",
            "example": 4,
            "description": "Answered with low confidence."
          },
          "deflected": {
            "type": "integer",
            "example": 3,
            "description": "Not answered because the FAQs, slides, and knowledge base had no answer."
          },
          "degraded": {
            "type": "integer",
            "example": 2,
            "description": "Not answered because of a service failure. Not a content gap."
          }
        },
        "required": [
          "asked",
          "answered",
          "low_confidence",
          "deflected",
          "degraded"
        ]
      },
      "HomeownerQuestion": {
        "type": "object",
        "description": "One question a homeowner asked in a presentation.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "askedAt": {
            "type": "string",
            "format": "date-time",
            "example": "2026-10-14T17:32:08.000Z"
          },
          "presentationId": {
            "type": "string",
            "format": "uuid"
          },
          "deck": {
            "type": "object",
            "description": "The template the presentation was created from.",
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid",
                "nullable": true
              },
              "name": {
                "type": "string",
                "nullable": true,
                "example": "Residential Solar Proposal"
              }
            },
            "required": [
              "id",
              "name"
            ]
          },
          "slide": {
            "type": "object",
            "description": "The slide the homeowner was on. All fields are `null` on older questions recorded before slide tracking was available.",
            "properties": {
              "deckSlideId": {
                "type": "string",
                "format": "uuid",
                "nullable": true
              },
              "title": {
                "type": "string",
                "nullable": true,
                "example": "Your estimated savings"
              },
              "index": {
                "type": "integer",
                "nullable": true,
                "example": 3,
                "description": "0-based position of the slide in the presentation."
              }
            },
            "required": [
              "deckSlideId",
              "title",
              "index"
            ]
          },
          "modality": {
            "type": "string",
            "enum": [
              "voice",
              "text",
              "unknown"
            ],
            "description": "Whether the homeowner asked by voice or by typing."
          },
          "outcome": {
            "type": "string",
            "enum": [
              "answered",
              "low_confidence",
              "deflected",
              "degraded"
            ]
          },
          "text": {
            "type": "object",
            "description": "`available`: the question and answer text are included. `redacted`: the question is older than 90 days, so its text was removed. Its outcome is still counted. `not_recorded`: no text was recorded for the question.",
            "properties": {
              "status": {
                "type": "string",
                "enum": [
                  "available",
                  "redacted",
                  "not_recorded"
                ]
              },
              "question": {
                "type": "string",
                "nullable": true,
                "example": "Does the warranty cover the inverter?"
              },
              "answer": {
                "type": "string",
                "nullable": true,
                "example": "Yes. The inverter is covered by a 25-year manufacturer warranty."
              }
            },
            "required": [
              "status",
              "question",
              "answer"
            ]
          },
          "category": {
            "type": "object",
            "description": "Where the answer came from and which knowledge sources had nothing.",
            "properties": {
              "answerSource": {
                "type": "string",
                "nullable": true,
                "example": "generated",
                "description": "One of `faq_exact`, `faq_semantic`, `generated`, `fallback`, or `greeting`."
              },
              "contentSource": {
                "type": "string",
                "nullable": true,
                "example": "slide",
                "description": "For generated answers: `slide`, `kb`, `both`, or `unknown`."
              },
              "emptySources": {
                "type": "array",
                "description": "Knowledge sources that were checked and had no answer.",
                "items": {
                  "type": "string",
                  "enum": [
                    "faq",
                    "slides",
                    "kb"
                  ]
                }
              },
              "degradedReason": {
                "type": "string",
                "nullable": true,
                "description": "Why the answer was degraded, when `outcome` is `degraded`."
              }
            },
            "required": [
              "answerSource",
              "contentSource",
              "emptySources",
              "degradedReason"
            ]
          }
        },
        "required": [
          "id",
          "askedAt",
          "presentationId",
          "deck",
          "slide",
          "modality",
          "outcome",
          "text",
          "category"
        ]
      },
      "QuestionReport": {
        "type": "object",
        "description": "Homeowner questions for your organization over the requested window, grouped by ISO week.",
        "properties": {
          "window": {
            "type": "object",
            "description": "The window the questions were asked in: the requested `since`/`until`, or the last 30 days ending at request time.",
            "properties": {
              "from": {
                "type": "string",
                "format": "date-time",
                "example": "2026-10-12T00:00:00.000Z"
              },
              "until": {
                "type": "string",
                "format": "date-time",
                "example": "2026-10-19T00:00:00.000Z"
              }
            },
            "required": [
              "from",
              "until"
            ]
          },
          "deckId": {
            "type": "string",
            "format": "uuid",
            "nullable": true,
            "description": "The template filter applied, or `null` when the list covers all templates."
          },
          "counts": {
            "$ref": "#/components/schemas/QuestionOutcomeCounts"
          },
          "unansweredRate": {
            "$ref": "#/components/schemas/EngagementRate"
          },
          "weeks": {
            "type": "array",
            "description": "ISO weeks (UTC), oldest first. Questions within a week are newest first.",
            "items": {
              "type": "object",
              "properties": {
                "isoWeek": {
                  "type": "string",
                  "example": "2026-W42"
                },
                "counts": {
                  "$ref": "#/components/schemas/QuestionOutcomeCounts"
                },
                "unansweredRate": {
                  "$ref": "#/components/schemas/EngagementRate"
                },
                "questions": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/HomeownerQuestion"
                  }
                }
              },
              "required": [
                "isoWeek",
                "counts",
                "unansweredRate",
                "questions"
              ]
            }
          }
        },
        "required": [
          "window",
          "deckId",
          "counts",
          "unansweredRate",
          "weeks"
        ]
      }
    }
  },
  "paths": {
    "/api/activity": {
      "get": {
        "tags": [
          "Activity"
        ],
        "summary": "List recent activity",
        "description": "Returns the 10 most recent presentation events for your organization, enriched with the homeowner name, address, and template ID for deep-linking. Events for presentations that have been deleted are excluded.",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "List of recent activity events",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "events": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ActivityEvent"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Not authenticated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/decks": {
      "get": {
        "tags": [
          "Decks"
        ],
        "summary": "List decks",
        "description": "Returns all decks for the authenticated organization, ordered by most recently created. A Demand IQ API key lists the decks of its own company. Service tokens are rejected with `401`.",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "sessionCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "List of decks",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "decks": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/DeckSummary"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Upstream service is unreachable while validating the API key. Retry with backoff",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Decks"
        ],
        "summary": "Create a deck",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name"
                ],
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "description": {
                    "type": "string"
                  },
                  "type": {
                    "type": "string",
                    "enum": [
                      "structured",
                      "image-based"
                    ],
                    "default": "structured"
                  },
                  "deckContext": {
                    "type": "string",
                    "description": "Background information to guide AI narration generation (e.g. audience, purpose)"
                  },
                  "voiceProvider": {
                    "type": "string",
                    "enum": [
                      "elevenlabs",
                      "openai"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Deck created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "deck": {
                      "$ref": "#/components/schemas/Deck"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/decks/generation-status": {
      "get": {
        "tags": [
          "Generation"
        ],
        "summary": "Poll generation status for every deck",
        "description": "The latest unsettled generation job for every deck in the organization, keyed by deck id. Completed jobs are omitted, so a deck absent from the map has nothing running. Cheap enough to poll while a template is being built \u2014 unlike `GET /api/decks`, it carries no preview URLs.",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "Unsettled jobs keyed by deck id",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "statuses": {
                      "type": "object",
                      "additionalProperties": {
                        "$ref": "#/components/schemas/GenerationStatus"
                      }
                    }
                  },
                  "required": [
                    "statuses"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/decks/import": {
      "post": {
        "tags": [
          "Decks"
        ],
        "summary": "Import a presentation as a deck",
        "description": "Imports a slide presentation and creates a fully persisted image-based deck from it. Each slide is rendered to a WebP image with a matching WebP thumbnail, and speaker notes become the editable narration script for that slide (the original notes are retained separately). The rendered slide images and thumbnails are stored alongside the deck and removed when the deck is deleted. The uploaded source file is not retained on a successful import; it is only kept for failed imports, to diagnose the failure.\n\nThe `source` query parameter selects the import format. `pptx` (PowerPoint) is currently the only supported source. PowerPoint files are limited to 25 MB and 50 slides, and the request body as a whole is limited to 30 MB.\n\nImports are atomic: if any step fails, no deck or slides are created and any stored files are cleaned up. Non-fatal issues (for example, a slide with no speaker notes) are reported in the `import.warnings` array of the response.",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "name": "source",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "pptx"
              ]
            },
            "description": "Slide import source format. Only `pptx` is currently supported."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": [
                  "name",
                  "file"
                ],
                "properties": {
                  "name": {
                    "type": "string",
                    "maxLength": 255,
                    "description": "Name for the new deck.",
                    "example": "Spring Roofing Pitch"
                  },
                  "description": {
                    "type": "string",
                    "maxLength": 10000,
                    "description": "Optional deck description."
                  },
                  "file": {
                    "type": "string",
                    "format": "binary",
                    "description": "The presentation file. For `source=pptx`, exactly one `.pptx` file up to 25 MB with at most 50 slides."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Deck created from the imported presentation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "deck",
                    "import"
                  ],
                  "properties": {
                    "deck": {
                      "$ref": "#/components/schemas/Deck"
                    },
                    "import": {
                      "type": "object",
                      "required": [
                        "id",
                        "source",
                        "status",
                        "warnings"
                      ],
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid",
                          "description": "Identifier of the import record."
                        },
                        "source": {
                          "type": "string",
                          "example": "pptx"
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "succeeded"
                          ],
                          "description": "Always `succeeded` in a 201 response. Failed imports return an error status code instead."
                        },
                        "warnings": {
                          "type": "array",
                          "description": "Non-fatal issues encountered during the import.",
                          "items": {
                            "type": "object",
                            "required": [
                              "code",
                              "message"
                            ],
                            "properties": {
                              "code": {
                                "type": "string",
                                "example": "missing_speaker_notes"
                              },
                              "message": {
                                "type": "string"
                              },
                              "slideIndex": {
                                "type": "integer",
                                "description": "Zero-based index of the affected slide, when the warning applies to a single slide."
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request. The `code` field identifies the problem: `source_required` (missing `source` query parameter), `unsupported_source` (the response also includes a `supportedSources` array), `invalid_form_data`, `invalid_metadata`, or `invalid_pptx` (wrong extension, media type, or unreadable file).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "Request too large. The request body exceeds 30 MB (`request_too_large`) or the PowerPoint file exceeds 25 MB.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "The presentation could not be converted into a deck. The `code` field identifies why: `rendering_failed` (the file could not be converted; re-saving from PowerPoint typically resolves this), `rendering_timeout` (the file took too long to convert; try a smaller deck), `rendered_output_too_large` (the rendered output exceeds the internal size limit; try a smaller deck), `empty_import` (the presentation contains no slides), `rendered_slide_count_mismatch` (the number of rendered slides did not match the source), or `invalid_rendered_slide` / `invalid_rendered_slide_thumbnail` / `invalid_slide_order` (a slide could not be prepared for storage). The `message` field is safe to show to end users.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error (`deck_import_failed`). No deck is created and uploaded files are cleaned up.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/decks/{deckId}": {
      "get": {
        "tags": [
          "Decks"
        ],
        "summary": "Get a deck",
        "description": "Returns the full deck including slides, FAQs, branding, and Q&A settings.",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "deckId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "UUID of the deck"
          }
        ],
        "responses": {
          "200": {
            "description": "Full deck data",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "deck": {
                      "$ref": "#/components/schemas/Deck"
                    },
                    "slides": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Slide"
                      }
                    },
                    "faqs": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Faq"
                      }
                    },
                    "branding": {
                      "nullable": true,
                      "$ref": "#/components/schemas/Branding"
                    },
                    "qaSettings": {
                      "nullable": true,
                      "$ref": "#/components/schemas/QaSettings"
                    },
                    "presentationsCount": {
                      "type": "integer"
                    },
                    "generation": {
                      "$ref": "#/components/schemas/GenerationStatus",
                      "nullable": true,
                      "description": "The latest unsettled generation job; null once it completed or if the deck was never generated"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "put": {
        "tags": [
          "Decks"
        ],
        "summary": "Update a deck",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "deckId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "UUID of the deck"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "description": {
                    "type": "string",
                    "nullable": true
                  },
                  "type": {
                    "type": "string",
                    "enum": [
                      "structured",
                      "image-based"
                    ]
                  },
                  "isActive": {
                    "type": "boolean"
                  },
                  "deckContext": {
                    "type": "string",
                    "nullable": true
                  },
                  "tags": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "nullable": true,
                    "description": "Replaces the deck's tag list. Pass an empty array or `null` to clear all tags. Falsy entries are filtered out."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated deck",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "deck": {
                      "$ref": "#/components/schemas/Deck"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Decks"
        ],
        "summary": "Delete a deck",
        "description": "Permanently deletes a deck and all associated slides, FAQs, and branding. For decks created via `POST /api/decks/import`, the rendered slide images and thumbnails stored with the deck are removed as well.",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "deckId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "UUID of the deck"
          }
        ],
        "responses": {
          "200": {
            "description": "Deck deleted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/decks/{deckId}/slides": {
      "get": {
        "tags": [
          "Slides"
        ],
        "summary": "List slides",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "deckId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "UUID of the deck"
          }
        ],
        "responses": {
          "200": {
            "description": "Ordered list of slides",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "slides": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Slide"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Slides"
        ],
        "summary": "Create a slide",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "deckId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "UUID of the deck"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "slideId",
                  "title",
                  "narrationScript"
                ],
                "properties": {
                  "slideId": {
                    "type": "string",
                    "description": "Human-readable identifier (e.g. \"slide-1\")"
                  },
                  "title": {
                    "type": "string"
                  },
                  "bullets": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "narrationScript": {
                    "type": "string"
                  },
                  "slideContext": {
                    "type": "string",
                    "nullable": true
                  },
                  "audioUrl": {
                    "type": "string",
                    "description": "S3 key for pre-recorded audio"
                  },
                  "heroImg": {
                    "type": "string",
                    "nullable": true,
                    "description": "S3 key for slide image"
                  },
                  "orderIndex": {
                    "type": "integer"
                  },
                  "slideType": {
                    "type": "string",
                    "enum": [
                      "standard",
                      "product_pricing_v1",
                      "video"
                    ],
                    "default": "standard"
                  },
                  "videoUrl": {
                    "type": "string",
                    "description": "YouTube link for the video. Allowed only when `slideType` is `video`. Accepts youtube.com, youtu.be, embed, Shorts and live links. AI Presentations stores it in canonical `https://www.youtube.com/watch?v=<id>` form. Returns `400` for playlist links, non-YouTube links, or links without a video ID."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Slide created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "slide": {
                      "$ref": "#/components/schemas/Slide"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/decks/{deckId}/slides/reorder": {
      "put": {
        "tags": [
          "Slides"
        ],
        "summary": "Reorder slides",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "deckId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "UUID of the deck"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "slideIds"
                ],
                "properties": {
                  "slideIds": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "description": "Full ordered array of slide UUIDs. Position in array becomes the new orderIndex."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Slides reordered",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/slides/{slideId}": {
      "put": {
        "tags": [
          "Slides"
        ],
        "summary": "Update a slide",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "slideId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "UUID of the slide"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "title": {
                    "type": "string"
                  },
                  "bullets": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "narrationScript": {
                    "type": "string"
                  },
                  "slideContext": {
                    "type": "string",
                    "nullable": true
                  },
                  "audioUrl": {
                    "type": "string"
                  },
                  "heroImg": {
                    "type": "string",
                    "nullable": true
                  },
                  "orderIndex": {
                    "type": "integer"
                  },
                  "videoUrl": {
                    "type": "string",
                    "nullable": true,
                    "description": "YouTube link for the video. Allowed only on `video` slides; other slide types return `400`. Stored in canonical `https://www.youtube.com/watch?v=<id>` form. Send `null` or an empty string to clear it."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated slide",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "slide": {
                      "$ref": "#/components/schemas/Slide"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Slides"
        ],
        "summary": "Delete a slide",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "slideId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "UUID of the slide"
          }
        ],
        "responses": {
          "200": {
            "description": "Slide deleted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/decks/{deckId}/faqs": {
      "get": {
        "tags": [
          "FAQs"
        ],
        "summary": "List FAQs",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "deckId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "UUID of the deck"
          }
        ],
        "responses": {
          "200": {
            "description": "FAQs with pre-generated audio",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "faqs": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Faq"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "FAQs"
        ],
        "summary": "Create a FAQ",
        "description": "Creates a FAQ and automatically generates TTS audio for the answer.",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "deckId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "UUID of the deck"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "userQuestion",
                  "cannedAnswer"
                ],
                "properties": {
                  "userQuestion": {
                    "type": "string"
                  },
                  "cannedAnswer": {
                    "type": "string"
                  },
                  "relatedSlideId": {
                    "type": "string",
                    "format": "uuid",
                    "nullable": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "FAQ created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "faq": {
                      "$ref": "#/components/schemas/Faq"
                    },
                    "warning": {
                      "type": "string",
                      "description": "Present if audio generation failed (FAQ is still saved)"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/faqs/{faqId}": {
      "put": {
        "tags": [
          "FAQs"
        ],
        "summary": "Update a FAQ",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "faqId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "UUID of the FAQ"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "userQuestion": {
                    "type": "string"
                  },
                  "cannedAnswer": {
                    "type": "string"
                  },
                  "relatedSlideId": {
                    "type": "string",
                    "format": "uuid",
                    "nullable": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated FAQ",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "faq": {
                      "$ref": "#/components/schemas/Faq"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "FAQs"
        ],
        "summary": "Delete a FAQ",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "faqId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "UUID of the FAQ"
          }
        ],
        "responses": {
          "200": {
            "description": "FAQ deleted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/decks/{deckId}/branding": {
      "get": {
        "tags": [
          "Branding"
        ],
        "summary": "Get branding",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "deckId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "UUID of the deck"
          }
        ],
        "responses": {
          "200": {
            "description": "Branding configuration, or null if not yet set",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "branding": {
                      "nullable": true,
                      "$ref": "#/components/schemas/Branding"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "put": {
        "tags": [
          "Branding"
        ],
        "summary": "Upsert branding",
        "description": "Creates or replaces the branding configuration for a deck.",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "deckId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "UUID of the deck"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "palette",
                  "cta"
                ],
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "logo": {
                    "type": "string",
                    "nullable": true,
                    "description": "S3 key for logo image"
                  },
                  "avatar": {
                    "type": "string",
                    "nullable": true,
                    "description": "S3 key for rep avatar image"
                  },
                  "chatName": {
                    "type": "string",
                    "nullable": true
                  },
                  "chatGreeting": {
                    "type": "string",
                    "nullable": true
                  },
                  "palette": {
                    "$ref": "#/components/schemas/BrandingPalette"
                  },
                  "cta": {
                    "$ref": "#/components/schemas/BrandingCta"
                  },
                  "fonts": {
                    "type": "object"
                  },
                  "contact": {
                    "type": "object",
                    "properties": {
                      "phone": {
                        "type": "string"
                      },
                      "email": {
                        "type": "string",
                        "format": "email"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Saved branding",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "branding": {
                      "$ref": "#/components/schemas/Branding"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/decks/{deckId}/qa-settings": {
      "get": {
        "tags": [
          "Q&A"
        ],
        "summary": "Get Q&A settings",
        "description": "Returns the customizable resume and transition prompts for the deck's Q&A experience.",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "deckId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "UUID of the deck"
          }
        ],
        "responses": {
          "200": {
            "description": "Q&A settings",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "qaSettings": {
                      "nullable": true,
                      "$ref": "#/components/schemas/QaSettings"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "put": {
        "tags": [
          "Q&A"
        ],
        "summary": "Update Q&A settings",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "deckId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "UUID of the deck"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "resumePromptText": {
                    "type": "string"
                  },
                  "resumeVoiceId": {
                    "type": "string"
                  },
                  "transitionPromptText": {
                    "type": "string"
                  },
                  "transitionVoiceId": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated Q&A settings",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "qaSettings": {
                      "$ref": "#/components/schemas/QaSettings"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/decks/{deckId}/generate": {
      "post": {
        "tags": [
          "Generation"
        ],
        "summary": "Start AI generation from images",
        "description": "Accepts uploaded slide images, runs them through GPT-4o Vision to extract content, generates narration scripts, and synthesizes audio. Returns a job ID \u2014 poll `/api/decks/{deckId}/generate/status` for progress.",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "deckId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "UUID of the deck"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": [
                  "images"
                ],
                "properties": {
                  "images": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "format": "binary"
                    },
                    "description": "Slide images (PNG, JPG, or WebP; max 10 MB each)"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Job accepted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "jobId": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/decks/{deckId}/generate/status": {
      "get": {
        "tags": [
          "Generation"
        ],
        "summary": "Poll generation status",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "deckId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "UUID of the deck"
          }
        ],
        "responses": {
          "200": {
            "description": "Current job status",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GenerationStatus"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/decks/{deckId}/presentations": {
      "get": {
        "tags": [
          "Presentations"
        ],
        "summary": "List presentations",
        "description": "Returns all non-deleted presentations created from this deck. Each row carries the four status-ladder timestamps (`sentAt`, `emailOpenedAt`, `firstViewedAt`, plus `createdAt`); the badge shows the furthest rung reached along Created \u2192 Sent \u2192 Email Opened \u2192 Viewed. Any of the three delivery-side timestamps is `null` when that rung has not been reached \u2014 for example, a rep-shared link that was opened without ever being emailed carries `sentAt: null`, `emailOpenedAt: null`, and a non-null `firstViewedAt`.",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "deckId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "UUID of the deck"
          }
        ],
        "responses": {
          "200": {
            "description": "List of presentations",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "presentations": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Presentation"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Presentations"
        ],
        "summary": "Create a presentation",
        "description": "Creates a personalized presentation. Provide `homeowner`, `prospect_id`, or both \u2014 at least one is required. With only `homeowner`, a new prospect is created from it. With only `prospect_id`, homeowner data is fetched from that prospect's journey. With both, the supplied homeowner data is used as-is and the existing prospect is attached (it must be visible to your credential \u2014 otherwise 422 `PROSPECT_NOT_FOUND`). The address is validated via Google Geocoding. Returns a shareable URL immediately; audio generation may continue in the background.\n\nPrice inputs are optional. If a product pricing slide uses formula variables that are not supplied, the price is deferred \u2014 the slide displays a placeholder instead of failing. Deferred prices can be resolved later when the missing values become available (e.g., after roof measurements). AI Presentations defers a measurement-backed variable only when a formula on one of the deck's product-pricing slides references it. Price variables left in the deck's settings after their product slide was removed, or after its formula stopped referencing them, are ignored. While the deck itself is still being generated, the request is refused with 409 `DECK_GENERATING`: a presentation is a permanent snapshot of the deck at creation time, so one taken mid-generation would be permanently missing slides. Retry once the generation job completes.",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "deckId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "UUID of the deck"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "homeowner": {
                    "$ref": "#/components/schemas/HomeownerData"
                  },
                  "prospect_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Prospect to attach the presentation to. Alone, homeowner data is fetched from the prospect's journey; with `homeowner`, the prospect is attached and the supplied data is used as-is. Must be visible to your credential."
                  },
                  "voice_settings": {
                    "type": "object"
                  },
                  "language_settings": {
                    "type": "object"
                  },
                  "price_inputs": {
                    "type": "object",
                    "additionalProperties": {
                      "type": "number"
                    },
                    "description": "Values for deck-level price variables (used to evaluate formulas). Optional \u2014 omitted variables result in deferred pricing rather than an error."
                  },
                  "measurement_strategy": {
                    "type": "string",
                    "enum": [
                      "manual",
                      "auto"
                    ],
                    "default": "manual",
                    "description": "Set to `auto` to resolve measurement-backed price variables from automated roof measurements instead of supplying them in `price_inputs`. Only variables referenced by a formula on the deck's product-pricing slides are deferred to measurements."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Presentation created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "deck_presentation_id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "url": {
                      "type": "string",
                      "format": "uri",
                      "description": "Shareable presentation URL: the homeowner short link (`https://mypresi.co/<slug>`) where the short-link host is configured, else the `/p/` URL"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "not_started",
                        "pending",
                        "processing",
                        "ready",
                        "failed"
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request \u2014 malformed input, or the deck has no slides (`\"Deck has no slides\"`). A presentation cannot be created from an empty deck.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Conflict: `DECK_GENERATING` \u2014 the deck is still being generated. This check runs before the empty-deck check, so a job that has not written its first slide yet returns 409, not 400. Transient; retry once the job settles.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string",
                      "enum": [
                        "DECK_GENERATING"
                      ]
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "Unprocessable: `INVALID_ADDRESS` (address could not be verified), `PROSPECT_NOT_FOUND` (prospect_id does not exist or belongs to another organization \u2014 permanent, do not retry), or `PROSPECT_CREATE_FAILED` (prospect data was rejected upstream)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string",
                      "enum": [
                        "INVALID_ADDRESS",
                        "PROSPECT_NOT_FOUND",
                        "PROSPECT_CREATE_FAILED"
                      ]
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Upstream service is unreachable \u2014 retry with backoff",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/presentations/send": {
      "post": {
        "tags": [
          "Presentations"
        ],
        "summary": "Send a follow-up email for an ingested presentation",
        "description": "Sends a follow-up email, such as a reminder, for a presentation that `POST /api/decks/{deckId}/ingest` created. Name the presentation with `presentation_id`, or with the `deck_id` and `source_event_id` you passed to ingest. Server-to-server callers authenticate with a Bearer token. A company credential only reaches its own company's presentations.\n\nEvery decided outcome returns `200`: `sent`, `skipped` with a `reason`, or `failed`. AI Presentations records each outcome as one delivery attempt per `idempotency_key`. A repeated key returns the original result without sending again. The safety checks (suppressed address, parked or failed presentation, no first email sent, reminders turned off for the deck) always run. `skip_if` only adds conditions.\n\n`409` with code `SEND_IN_PROGRESS` means another call with the same key hasn't finished. Retry it with the same key. `5xx` responses are also safe to retry with the same key.",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "sessionCookie": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "idempotency_key",
                  "subject_variant"
                ],
                "description": "Name the presentation with `presentation_id`, or with `deck_id` and `source_event_id` together. A request that includes both shapes returns `400`.",
                "properties": {
                  "presentation_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "The presentation to send, as returned by ingest",
                    "example": "7c2e5f8b-1a4d-4e6f-9b3c-8d0e2f4a6b1c"
                  },
                  "deck_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "With `source_event_id`, identifies the presentation ingest created",
                    "example": "3f6c2a1e-8b4d-4c7a-9e2f-1d5b7a9c0e4f"
                  },
                  "source_event_id": {
                    "type": "string",
                    "minLength": 1,
                    "description": "The `source_event_id` you passed to the ingest endpoint",
                    "example": "journey-complete-48213"
                  },
                  "idempotency_key": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 64,
                    "description": "One send per key. Reuse the same key when you retry.",
                    "example": "reminder-48213-1"
                  },
                  "skip_if": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": [
                        "opened",
                        "viewed"
                      ]
                    },
                    "default": [],
                    "description": "Extra conditions that skip the send. `opened`: the homeowner opened an earlier email (machine opens don't count). `viewed`: the homeowner viewed the presentation."
                  },
                  "subject_variant": {
                    "type": "string",
                    "enum": [
                      "reminder"
                    ],
                    "description": "Which email to send. The first email is sent by ingest, so `initial` is not accepted."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The outcome",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "send_status"
                  ],
                  "properties": {
                    "send_status": {
                      "type": "string",
                      "enum": [
                        "sent",
                        "skipped",
                        "failed"
                      ]
                    },
                    "reason": {
                      "type": "string",
                      "description": "Set when skipped: `no_presentation`, `no_email`, `suppressed`, `presentation_parked`, `presentation_failed`, `no_initial_send`, `reminder_disabled`, `opened`, or `viewed`. Set when failed: the error message."
                    },
                    "presentation_id": {
                      "type": "string",
                      "format": "uuid",
                      "description": "Absent for `no_presentation`"
                    },
                    "delivery_id": {
                      "type": "string",
                      "format": "uuid",
                      "description": "The delivery attempt ID. Absent for `no_presentation`."
                    }
                  }
                },
                "example": {
                  "send_status": "sent",
                  "presentation_id": "7c2e5f8b-1a4d-4e6f-9b3c-8d0e2f4a6b1c",
                  "delivery_id": "b1e4d7a2-5c3f-4a8e-9d6b-2f0c8e1a7b35"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "A send with this `idempotency_key` is still in progress. Retry with the same key.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string",
                      "enum": [
                        "SEND_IN_PROGRESS"
                      ]
                    }
                  },
                  "required": [
                    "error",
                    "code"
                  ]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Service unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/presentations/{presentationId}": {
      "patch": {
        "tags": [
          "Presentations"
        ],
        "summary": "Update a presentation",
        "description": "Partial update for homeowner data, voice settings, language, or price inputs.",
        "parameters": [
          {
            "in": "path",
            "name": "presentationId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "UUID of the presentation"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "voiceSettings": {
                    "type": "object",
                    "nullable": true
                  },
                  "languageSettings": {
                    "type": "object",
                    "nullable": true
                  },
                  "priceInputs": {
                    "type": "object",
                    "additionalProperties": {
                      "type": "number"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Presentation updated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string"
                    },
                    "presentationId": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Presentations"
        ],
        "summary": "Delete a presentation",
        "description": "Soft-deletes a presentation (sets `deletedAt`). The shareable URL stops working immediately.",
        "parameters": [
          {
            "in": "path",
            "name": "presentationId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "UUID of the presentation"
          }
        ],
        "responses": {
          "200": {
            "description": "Presentation deleted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string"
                    },
                    "presentationId": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/presentations/{presentationId}/status": {
      "get": {
        "tags": [
          "Presentations"
        ],
        "summary": "Get presentation status",
        "description": "Returns the current generation status, phase, and the slide generation is working on. `current_slide` counts from 1 and can jump, since slides with nothing to personalize are skipped.",
        "parameters": [
          {
            "in": "path",
            "name": "presentationId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "UUID of the presentation"
          }
        ],
        "responses": {
          "200": {
            "description": "Presentation status",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "not_started",
                        "pending",
                        "generating",
                        "ready",
                        "failed",
                        "missing_data"
                      ]
                    },
                    "phase": {
                      "type": "string",
                      "enum": [
                        "measuring",
                        "analyzing",
                        "generating",
                        "preparing"
                      ],
                      "description": "What generation is doing right now. `measuring` means AI Presentations is fetching roof measurements; no slide count is reported during this phase."
                    },
                    "current_slide": {
                      "type": "integer",
                      "description": "The slide generation is currently personalizing, counting from 1. Can jump, since slides with nothing to personalize are skipped. Omitted until generation reports slide progress."
                    },
                    "total_slides": {
                      "type": "integer",
                      "description": "Total number of slides being generated. Omitted until generation reports slide progress."
                    },
                    "deck_id": {
                      "type": "string",
                      "format": "uuid",
                      "nullable": true
                    },
                    "created_at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "updated_at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "generation_started_at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "measurement_status": {
                      "type": "string"
                    },
                    "measurement_request_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "410": {
            "description": "Presentation has been deleted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/qa": {
      "post": {
        "tags": [
          "Q&A"
        ],
        "summary": "Answer a question",
        "description": "Answers a viewer question. Checks FAQs first (exact then semantic match at >= 0.6 confidence), falls back to GPT-4o with slide context. Returns the answer text plus an audio URL. For ElevenLabs voices, `audioUrl` usually points to `GET /api/qa/audio`, which streams the audio as it is synthesized.\n\n`deckId` and `presentationId` must be valid UUIDs; other values are rejected with a 400. When a `presentationId` is provided, the answer is drawn from the deck that presentation belongs to; the body's `deckId` is used only as a fallback when that deck has been deleted. If `slideId` doesn't match a slide in the deck, the question is answered without slide context instead of failing.\n\nWhen a `presentationId` is provided, the question is recorded against the organization that owns the presentation, even when the caller is signed in to a different organization. A question asked from a signed-in browser is excluded from engagement metrics.\n\nWhen a signed-in caller sends `deckId` without a `presentationId`, the deck must belong to the caller's current organization. Otherwise the request is rejected with a 404 `Deck not found`. A missing deck and a deck owned by another organization return the same 404. Deck previews use this path. An unauthenticated request with `deckId` and no `presentationId` is rejected with a 400.\n\n**Authentication**: Accepts either a session cookie (admin) or a `presentationId` (public viewer).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "question",
                  "slideId"
                ],
                "properties": {
                  "question": {
                    "type": "string",
                    "minLength": 3
                  },
                  "slideId": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 100,
                    "description": "Current slide ID for context. Accepts a slide UUID or a legacy semantic ID such as `slide-1`."
                  },
                  "deckId": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Deck to answer from. Ignored when `presentationId` is provided \u2014 the deck is resolved from the presentation, and this value is used only as a fallback if that deck has been deleted. Without a `presentationId`, a session is required and the deck must belong to the caller's current organization."
                  },
                  "presentationId": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Required for unauthenticated viewer access"
                  },
                  "history": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "required": [
                        "role",
                        "content"
                      ],
                      "properties": {
                        "role": {
                          "type": "string",
                          "enum": [
                            "user",
                            "assistant"
                          ]
                        },
                        "content": {
                          "type": "string"
                        }
                      }
                    }
                  },
                  "voiceId": {
                    "type": "string"
                  },
                  "language": {
                    "type": "string",
                    "example": "en",
                    "description": "BCP-47 language tag"
                  },
                  "repMode": {
                    "type": "boolean",
                    "description": "Set by the viewer when a sales rep is driving the presentation rather than a homeowner. Optional. Omit the field when the client cannot determine it. An absent value is read as unknown, not as `false`."
                  },
                  "firstScreen": {
                    "type": "string",
                    "enum": [
                      "intro",
                      "loading",
                      "slides",
                      "pending_data"
                    ],
                    "example": "intro",
                    "description": "The first screen the viewer showed on this visit. Optional. Omit the field when the client cannot determine it. Any value outside the enum is rejected with a 400."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Answer with audio",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/QaResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/qa/audio": {
      "get": {
        "tags": [
          "Q&A"
        ],
        "summary": "Stream the spoken audio for an answer",
        "description": "Synthesizes an answer that `POST /api/qa` already produced and streams MP3 audio as it is generated, so playback can start before the clip is complete. The response doesn't support byte ranges.\n\nOnce the clip has been stored for a cached answer, the same token redirects to the stored file. If synthesis can't start, the endpoint redirects to the default answer clip.\n\nYou don't build this URL yourself. Use the `audioUrl` returned by `POST /api/qa` when `audioStreamed` is `true`.\n\n**Authentication**: The sealed token in the `t` query parameter of `QaResponse.audioUrl`. Tokens expire after 6 hours.",
        "security": [],
        "parameters": [
          {
            "in": "query",
            "name": "t",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Sealed answer-audio token from `QaResponse.audioUrl`"
          }
        ],
        "responses": {
          "200": {
            "description": "MP3 audio, streamed",
            "content": {
              "audio/mpeg": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "302": {
            "description": "Redirect to the stored clip for a cached answer, or to `/audio/answer-default.mp3` when synthesis can't start"
          },
          "401": {
            "description": "Missing, tampered, or expired token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/narration/single": {
      "post": {
        "tags": [
          "Narration"
        ],
        "summary": "Synthesize narration for one slide",
        "description": "Generates TTS audio for a slide script. Results are cached per session.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "sessionId",
                  "slideId",
                  "script"
                ],
                "properties": {
                  "sessionId": {
                    "type": "string",
                    "description": "Unique session identifier for caching"
                  },
                  "slideId": {
                    "type": "string"
                  },
                  "script": {
                    "type": "string",
                    "minLength": 1
                  },
                  "voiceId": {
                    "type": "string"
                  },
                  "presentationId": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Required for unauthenticated viewer access"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Audio URL and word timings",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NarrationResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/narration/batch": {
      "post": {
        "tags": [
          "Narration"
        ],
        "summary": "Synthesize narration for multiple slides",
        "description": "Batch TTS generation. Per-slide failures return a fallback audio URL rather than failing the whole batch.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "sessionId",
                  "slides"
                ],
                "properties": {
                  "sessionId": {
                    "type": "string"
                  },
                  "slides": {
                    "type": "array",
                    "minItems": 1,
                    "items": {
                      "type": "object",
                      "required": [
                        "slideId",
                        "script"
                      ],
                      "properties": {
                        "slideId": {
                          "type": "string"
                        },
                        "script": {
                          "type": "string",
                          "minLength": 1
                        },
                        "voiceId": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Narration responses for each slide",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "cachedIds": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "responses": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/NarrationResponse"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/narration/resume": {
      "post": {
        "tags": [
          "Narration"
        ],
        "summary": "Synthesize resume narration",
        "description": "Generates the spoken bridge from Q&A back into the presentation, using the deck's configured transition prompt.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "deckId": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "presentationId": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "voiceId": {
                    "type": "string"
                  },
                  "language": {
                    "type": "string",
                    "example": "en"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Resume narration audio",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NarrationResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/images": {
      "get": {
        "tags": [
          "Images"
        ],
        "summary": "List images",
        "description": "Returns all uploaded images for the authenticated organization.",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "List of images",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "images": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Image"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/images/upload": {
      "post": {
        "tags": [
          "Images"
        ],
        "summary": "Upload an image",
        "description": "Uploads and optimizes an image (Sharp: max 1920px width; JPEG quality 85, or WebP quality 80 when `format=webp`). Returns the S3 key and a presigned URL.",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": [
                  "file"
                ],
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary",
                    "description": "Image file (PNG, JPG, WebP, or SVG; max 10 MB)"
                  },
                  "format": {
                    "type": "string",
                    "enum": [
                      "webp"
                    ],
                    "description": "Opt into WebP output, for slide imagery. Omit for anything that may be embedded in an email \u2014 Outlook desktop cannot render WebP. Default output is JPEG, or PNG when the source has transparency."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Uploaded image metadata",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "image": {
                      "$ref": "#/components/schemas/Image"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/images/{imageId}": {
      "delete": {
        "tags": [
          "Images"
        ],
        "summary": "Delete an image",
        "description": "Permanently removes the image, its thumbnail rendition and its database row. Refused with 409 while any deck or presentation still references the key; clear the reference first.",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "imageId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "UUID of the image"
          }
        ],
        "responses": {
          "200": {
            "description": "Image deleted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Image is still in use; nothing was deleted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "usage": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "kind": {
                            "type": "string",
                            "enum": [
                              "deck_logo",
                              "deck_avatar",
                              "deck_intro_background",
                              "slide_hero",
                              "product_slide_logo",
                              "product_card_image",
                              "presentation_slide"
                            ]
                          },
                          "deckName": {
                            "type": "string",
                            "nullable": true
                          },
                          "count": {
                            "type": "integer"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/voices/list": {
      "get": {
        "tags": [
          "Voices"
        ],
        "summary": "List narrator voices",
        "description": "Returns the narrator voices a template can use, including the default voice, with preview clips and gender, accent and age labels.",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "Voice list with preview URLs",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "voices": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Voice"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Voice service unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/decks/{deckId}/voice": {
      "put": {
        "tags": [
          "Voices"
        ],
        "summary": "Set the deck's narrator voice",
        "description": "Sets the voice that narrates every presentation from this deck. Send `null` to use the default voice. A change clears the deck's slide, FAQ, cached-answer and Q&A prompt audio and regenerates it in the background. Presentations already generated keep their audio.",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "deckId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "UUID of the deck"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "voiceId": {
                    "type": "string",
                    "nullable": true,
                    "description": "An `id` from `GET /api/voices/list`, or `null` for the default voice."
                  }
                },
                "required": [
                  "voiceId"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated deck",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "deck": {
                      "$ref": "#/components/schemas/Deck"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Voice service unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/engagement/summary": {
      "get": {
        "tags": [
          "Engagement"
        ],
        "summary": "Get engagement summary",
        "description": "Returns seven engagement metrics for your organization: presentations sent, opened, average consumption, CTA clicks, questions asked, appointments booked, and contracts signed. Each metric includes a `percentChange` compared with the equal-length window immediately before the requested one, and every rate includes a `directional` flag.\n\nThe response also includes three breakdowns for the requested window, without a `percentChange`: `funnel` (Created \u2192 Sent \u2192 Opened \u2192 Started \u2192 Completed for presentations created in the window), `visits` (visits per opened presentation), and `deliveryPath` (opened presentations that arrived without an email open or without an email send, plus opened presentations counted by the `utm_source` their link was shared with).\n\nProvide `since` and `until` together for a custom window, or omit both for the last 30 days ending now. If the window contains too many presentations, AI Presentations returns `422`. Narrow the window and retry. If only the prior comparison window is too large, the request still succeeds and every `percentChange` is `null`.\n\nActivity from a browser signed in to AI Presentations is left out of average consumption, CTA clicks, and questions asked, so previewing your own presentation link doesn't inflate them. That activity still counts toward `opened`. A teammate viewing a link on a device where they never signed in is counted as a prospect. Activity recorded before this exclusion shipped is counted as prospect activity.\n\nPass `deckId` to limit the summary to one template. A `deckId` that doesn't belong to your organization returns a zero-valued summary rather than `404`.",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "in": "query",
            "name": "since",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "example": "2026-09-01T00:00:00Z",
            "description": "Start of the window (inclusive), as an RFC 3339 timestamp. Timezone offsets are accepted. Provide with `until`, or omit both for the last 30 days."
          },
          {
            "in": "query",
            "name": "until",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "example": "2026-10-01T00:00:00Z",
            "description": "End of the window (exclusive), as an RFC 3339 timestamp. Must be after `since`. Provide with `since`, or omit both for the last 30 days."
          },
          {
            "in": "query",
            "name": "deckId",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Limit the summary to one template. An empty value is treated as absent."
          }
        ],
        "responses": {
          "200": {
            "description": "Engagement summary",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EngagementSummary"
                }
              }
            }
          },
          "400": {
            "description": "Invalid query parameters, `since` or `until` provided without the other, or `since` not before `until`",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Not authenticated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "The window contains too many presentations. Narrow the window and retry.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/delivery/template-performance": {
      "get": {
        "tags": [
          "Engagement"
        ],
        "summary": "Get email template performance",
        "description": "Returns sent, delivered, opened, and started counts for each version of your email template copy, so you can compare subject lines, preview text, body copy, and CTA labels. Each presentation counts once, under the template version of its first email to a recipient outside Demand IQ and your organization's own users, using that email's own delivery and open outcomes. Manual sends from the **Send** dialog count. An open of a later reminder doesn't count toward any version.\n\nAI Presentations leaves out sends only to Demand IQ staff (`@demand-iq.com`) addresses, sends only to your organization's own users, deleted presentations, and automatic opens. Delivered and opened counts come only from events for recipients outside Demand IQ.\n\nPass `deckId` to get one template's version list (`DeckTemplateList`). It includes every version the template has had, with all-time counts, from the moment the version is saved. Versions you removed are left out. The template's active version is always listed first, even before its first send. `since` and `until` are ignored when you pass `deckId`. A `deckId` that doesn't belong to your organization returns an empty `versions` list rather than `404`.\n\nOmit `deckId` for the organization-wide view (`TemplatePerformance`). Provide `since` and `until` together to bound when the first send happened, or omit both for the last 30 days ending now.\n\nReturns `404` when email template performance isn't enabled for your organization.",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "in": "query",
            "name": "since",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "example": "2026-09-01T00:00:00Z",
            "description": "Organization-wide view only. Ignored when you pass `deckId`. Start of the window for the first send (inclusive), as an RFC 3339 timestamp. Timezone offsets are accepted. Provide with `until`, or omit both for the last 30 days."
          },
          {
            "in": "query",
            "name": "until",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "example": "2026-10-01T00:00:00Z",
            "description": "Organization-wide view only. Ignored when you pass `deckId`. End of the window for the first send (exclusive), as an RFC 3339 timestamp. Must be after `since`. Provide with `since`, or omit both for the last 30 days."
          },
          {
            "in": "query",
            "name": "deckId",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Return this template's all-time version list instead of the organization-wide view. An empty value is treated as absent.",
            "example": "8b2e4f10-3c6a-4d9e-a1f7-62c0b5d9e384"
          }
        ],
        "responses": {
          "200": {
            "description": "The template's version list when you pass `deckId`, otherwise email performance per template version for your organization",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/DeckTemplateList"
                    },
                    {
                      "$ref": "#/components/schemas/TemplatePerformance"
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid query parameters, `since` or `until` provided without the other, or `since` not before `until` (organization-wide view only)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Not authenticated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Email template performance isn't enabled for your organization",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/delivery/template-performance/{versionId}": {
      "delete": {
        "tags": [
          "Engagement"
        ],
        "summary": "Remove an earlier email template version",
        "description": "Removes a version from one template's version list for good. The version's sends are kept in your organization-wide counts, but the template never lists or activates it again. Saving identical copy later creates a new version with zero counts.\n\nPass `untracked` as `versionId` to remove the row for sends made before AI Presentations recorded template versions. Removing the Demand IQ default copy affects only this template.\n\nYou can't remove the template's active version. Doing so returns `409`. Returns `404` when email template performance isn't enabled for your organization, or the template or version isn't on the list, including a template that belongs to another organization.",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "versionId",
            "required": true,
            "schema": {
              "oneOf": [
                {
                  "type": "string",
                  "format": "uuid"
                },
                {
                  "type": "string",
                  "enum": [
                    "untracked"
                  ]
                }
              ]
            },
            "example": "3f1c9a2e-7b4d-4e8a-9c21-5d6f0a8b1e47",
            "description": "The template version ID, or `untracked` for the row of sends made before AI Presentations recorded template versions."
          },
          {
            "in": "query",
            "name": "deckId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "example": "8b2e4f10-3c6a-4d9e-a1f7-62c0b5d9e384",
            "description": "The template whose version list to remove the version from."
          }
        ],
        "responses": {
          "204": {
            "description": "The version was removed from the template's list"
          },
          "400": {
            "description": "Invalid `versionId` or `deckId`",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Not authenticated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Email template performance isn't enabled for your organization, or the template or version isn't on the list",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "The version is the template's active version and can't be removed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/delivery/template-performance/{versionId}/activate": {
      "post": {
        "tags": [
          "Engagement"
        ],
        "summary": "Activate an earlier email template version",
        "description": "Makes an earlier version the template's active version. AI Presentations writes the version's subject, preview text, body, CTA label, and sender name to the template's saved email copy and marks the version active in one step. The next email uses this version under the same ID, so its counts continue.\n\nA version that used the default subject or preview text saves that field empty. Activating the version that's already active returns `204` with no change.\n\nReturns `400` when the version's copy is longer than the template's email copy limits, with an `error` such as `\"Subject line must be 255 characters or fewer\"`. Returns `404` when email template performance isn't enabled for your organization, the template belongs to another organization, or the version isn't on the template's list, including a removed version.",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "versionId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "example": "3f1c9a2e-7b4d-4e8a-9c21-5d6f0a8b1e47",
            "description": "The template version ID."
          },
          {
            "in": "query",
            "name": "deckId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "example": "8b2e4f10-3c6a-4d9e-a1f7-62c0b5d9e384",
            "description": "The template to activate the version on."
          }
        ],
        "responses": {
          "204": {
            "description": "The version is the template's active version"
          },
          "400": {
            "description": "Invalid `versionId` or `deckId`, or the version's copy exceeds the template's email copy limits",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Not authenticated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Email template performance isn't enabled for your organization, or the template or version isn't on the list",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/engagement/questions": {
      "get": {
        "tags": [
          "Engagement"
        ],
        "summary": "List homeowner questions",
        "description": "Returns every question homeowners asked in your presentations during the requested window, grouped by ISO week (UTC). Each question includes its template, slide, modality, outcome, question and answer text, and the knowledge sources involved.\n\nAI Presentations classifies each question with one outcome, checked in this order:\n\n- `degraded`: AI Presentations couldn't answer because of a service failure. This isn't a content gap.\n- `deflected`: the FAQs, slides, and knowledge base had no answer.\n- `low_confidence`: AI Presentations answered with low confidence.\n- `answered`: every other question.\n\nThe response includes counts per week and for the whole window, plus an `unansweredRate`: deflected questions divided by asked questions minus degraded ones.\n\nThe window applies to when each question was asked, so back-to-back windows list each question exactly once. The counts match `questionsAsked` from `GET /api/engagement/summary` only when every presentation in the window was also created inside it, because the summary counts questions on presentations created in the window.\n\nQuestions from browsers signed in to AI Presentations and from the template editor preview are left out. Question and answer text is removed after 90 days. Those questions keep their outcome and count, and show `text.status` as `redacted`.\n\nProvide `since` and `until` together for a custom window, or omit both for the last 30 days ending now. If the window contains more than 5,000 questions, AI Presentations returns `422`. Narrow the window and retry.\n\nPass `deckId` to limit the list to one template. A `deckId` that doesn't belong to your organization returns an empty list rather than `404`.",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "in": "query",
            "name": "since",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "example": "2026-10-12T00:00:00Z",
            "description": "Start of the window for when questions were asked (inclusive), as an RFC 3339 timestamp. Timezone offsets are accepted. Provide with `until`, or omit both for the last 30 days."
          },
          {
            "in": "query",
            "name": "until",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "example": "2026-10-19T00:00:00Z",
            "description": "End of the window for when questions were asked (exclusive), as an RFC 3339 timestamp. Must be after `since`. Provide with `since`, or omit both for the last 30 days."
          },
          {
            "in": "query",
            "name": "deckId",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Limit the list to one template. An empty value is treated as absent."
          }
        ],
        "responses": {
          "200": {
            "description": "Homeowner questions by ISO week, with outcome counts",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/QuestionReport"
                }
              }
            }
          },
          "400": {
            "description": "Invalid query parameters, `since` or `until` provided without the other, or `since` not before `until`",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Not authenticated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "The window contains more than 5,000 questions. Narrow the window and retry.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/health": {
      "get": {
        "tags": [
          "Utility"
        ],
        "summary": "Health check",
        "description": "Returns `{ ok: true }` if the service is running.",
        "responses": {
          "200": {
            "description": "Service is healthy",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/auth/login": {
      "post": {
        "tags": [
          "Authentication"
        ],
        "summary": "Log in",
        "description": "Authenticates with email and password. Returns user and organization info and sets a session cookie. Rate-limited to prevent brute-force attacks.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "email",
                  "password"
                ],
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email",
                    "example": "rep@acmesolar.com"
                  },
                  "password": {
                    "type": "string",
                    "format": "password"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Login successful. A `session` cookie is set on the response.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "user": {
                      "$ref": "#/components/schemas/User"
                    },
                    "organization": {
                      "$ref": "#/components/schemas/Organization"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing email or password, a request body that is not valid JSON, or a body that is valid JSON but not an object. The `error` field distinguishes the cases: `Request body must be valid JSON`, `Request body must be a JSON object`, or a message naming the missing field.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Invalid credentials",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Only failed credential attempts count toward the limit; requests rejected with a 400 for a malformed body do not.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/auth/logout": {
      "post": {
        "tags": [
          "Authentication"
        ],
        "summary": "Log out",
        "description": "Revokes the current session and clears the session cookie.",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "Logged out",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/auth/me": {
      "get": {
        "tags": [
          "Authentication"
        ],
        "summary": "Get current user",
        "description": "Returns the authenticated user's identity and organization.",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "Current user",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "user": {
                      "$ref": "#/components/schemas/User"
                    },
                    "organization": {
                      "$ref": "#/components/schemas/Organization"
                    },
                    "onboarding": {
                      "allOf": [
                        {
                          "$ref": "#/components/schemas/TourState"
                        }
                      ],
                      "description": "Per-user onboarding tour state. Omitted when the lookup fails \u2014 clients should treat a missing field as \"do not show the tour\" (fail-closed)."
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/auth/sso": {
      "get": {
        "tags": [
          "Authentication"
        ],
        "summary": "Portal SSO via auth code exchange",
        "description": "Exchanges a short-lived authorization code for an access token via the Core API, creates a new session, and redirects to the requested path. Used by the portal to embed AI Presentations in an iframe.\n\nFlow:\n1. Exchange `code` via Core API `POST /auth/code/exchange` (Basic auth with SSO client credentials)\n2. Validate the returned access token via `/user/me` to get user/org info\n3. Create a new session (always \u2014 never reuses an existing one)\n4. Set session cookie (plus embedded cookie if `embedded=1`)\n5. Revoke any prior session (best-effort)\n6. Redirect to a clean URL (no `code` param in the final location)\n\nRedirect URLs use the `APP_URL` environment variable as the canonical base origin when set. This is required for production deployments behind a load balancer where the internal hostname differs from the public URL.",
        "parameters": [
          {
            "in": "query",
            "name": "code",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Short-lived authorization code issued by the portal"
          },
          {
            "in": "query",
            "name": "redirect",
            "required": false,
            "schema": {
              "type": "string",
              "default": "/decks"
            },
            "description": "Internal path to redirect to after successful authentication"
          },
          {
            "in": "query",
            "name": "embedded",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "0",
                "1"
              ],
              "default": "0"
            },
            "description": "Set to `1` when running inside a portal iframe. Enables embedded mode cookies and error handling."
          },
          {
            "in": "query",
            "name": "theme",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "light",
                "dark"
              ]
            },
            "description": "Portal theme preference. When set, a theme cookie is stored so the initial render matches the portal appearance without a flash."
          }
        ],
        "responses": {
          "302": {
            "description": "Redirects to the `redirect` path on success, or to `/login?error=sso_failed` (standalone) / `/embedded-auth-error` (embedded) on failure. Returns a redirect on missing or invalid code, or Core API rejection."
          }
        }
      }
    },
    "/api/auth/sso/exchange": {
      "post": {
        "tags": [
          "Authentication"
        ],
        "summary": "Portal SSO token-bearer exchange",
        "description": "Token-bearer variant of the SSO flow for cross-origin clients (for example, the portal calling AI Presentations APIs from the browser).\n\nDiffers from `GET /api/auth/sso` in four ways:\n- Accepts the SSO code in a JSON body, not a query parameter\n- Returns the session token in the response body instead of setting a cookie\n- Emits CORS headers so the portal origin can read the response\n- Does not set the embedded or theme cookies (those are iframe-only concerns)\n\nThe returned `token` is the same opaque session ID that backs the cookie flow. Clients send it as `Authorization: Bearer <token>` on subsequent requests.\n\nUnlike the GET SSO flow, this endpoint does not revoke prior sessions for the user.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "code"
                ],
                "properties": {
                  "code": {
                    "type": "string",
                    "description": "Short-lived authorization code issued by the portal"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Session minted. The `token` is the bearer session ID; send it as `Authorization: Bearer <token>` on subsequent requests.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "token",
                    "expiresAt",
                    "idleTimeoutSeconds",
                    "absoluteMaxAgeSeconds",
                    "user",
                    "organization"
                  ],
                  "properties": {
                    "token": {
                      "type": "string",
                      "description": "Opaque session ID"
                    },
                    "expiresAt": {
                      "type": "string",
                      "format": "date-time",
                      "description": "Session deadline at mint time. Rolling: it moves forward on every successful renewal (`POST /api/auth/session/renew`), so a live client's real expiry drifts past this value. Never a hard cap."
                    },
                    "idleTimeoutSeconds": {
                      "type": "integer",
                      "description": "Sliding idle window measured against the session's last activity. Default `25200` (7h). Independent of `absoluteMaxAgeSeconds` \u2014 either can force re-auth first."
                    },
                    "absoluteMaxAgeSeconds": {
                      "type": "integer",
                      "description": "Rolling session lifetime in seconds (`SESSION_LIFETIME`, default `86400`). Re-set at creation and on every renewal, so this is the size of the rolling window, not an absolute cap. The wire key stays `absoluteMaxAgeSeconds` for portal compatibility."
                    },
                    "user": {
                      "type": "object",
                      "required": [
                        "id",
                        "email"
                      ],
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "email": {
                          "type": "string"
                        },
                        "name": {
                          "type": "string",
                          "nullable": true
                        }
                      }
                    },
                    "organization": {
                      "type": "object",
                      "description": "Organization associated with the session.",
                      "required": [
                        "id",
                        "name"
                      ],
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "name": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing or invalid `code`, or non-JSON body. Error codes: `invalid_body`, `invalid_request`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "SSO code expired or invalid. Error code: `invalid_code`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Request origin not allowed or authenticating user has no associated company (`invalid_user`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Unexpected server error. Error code: `internal_error`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Core authentication service unavailable. Error code: `core_api_unavailable`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "options": {
        "tags": [
          "Authentication"
        ],
        "summary": "CORS preflight for the SSO exchange",
        "description": "Returns `204 No Content` with CORS headers when the `Origin` is allowed, or `403 Forbidden` when it is not.",
        "responses": {
          "204": {
            "description": "Preflight accepted"
          },
          "403": {
            "description": "Origin not allowed"
          }
        }
      }
    },
    "/api/company/contact": {
      "get": {
        "tags": [
          "Company"
        ],
        "summary": "Get company contact info",
        "description": "Returns the organization's contact details used in contracts and branding.",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "Company contact",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "contact": {
                      "$ref": "#/components/schemas/CompanyContact"
                    },
                    "organizationName": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "put": {
        "tags": [
          "Company"
        ],
        "summary": "Update company contact info",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CompanyContact"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated contact",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "contact": {
                      "$ref": "#/components/schemas/CompanyContact"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/company/welcome-seen": {
      "post": {
        "tags": [
          "Company"
        ],
        "summary": "Mark the welcome wizard as seen",
        "description": "Records that this organization deliberately exited the first-time welcome wizard by saving or explicitly skipping the confirm-info step. Idempotent \u2014 the timestamp is written only on the first successful call (subsequent calls preserve the original value via `COALESCE`). Merely viewing the welcome screen does not count; the client should call this only after a user action that ends the wizard.",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "Welcome-seen timestamp for the organization",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "welcomeSeenAt": {
                      "type": "string",
                      "format": "date-time",
                      "nullable": true
                    }
                  },
                  "required": [
                    "welcomeSeenAt"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Organization not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/company/kb/profile": {
      "get": {
        "tags": [
          "Company"
        ],
        "summary": "Get knowledge base profile",
        "description": "Returns the company's knowledge base profile that guides how the AI answers customer questions.",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "KB profile",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "profile": {
                      "$ref": "#/components/schemas/KbProfile"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "put": {
        "tags": [
          "Company"
        ],
        "summary": "Update knowledge base profile",
        "description": "Updates the company tagline, about text, trust signals, service coverage, and answer style used by the AI.",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "tagline": {
                    "type": "string"
                  },
                  "about": {
                    "type": "string"
                  },
                  "trustSignals": {
                    "type": "string"
                  },
                  "serviceCoverage": {
                    "type": "string"
                  },
                  "answerStyle": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated profile",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "profile": {
                      "$ref": "#/components/schemas/KbProfile"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/company/kb/documents": {
      "get": {
        "tags": [
          "Company"
        ],
        "summary": "List knowledge base documents",
        "description": "Returns all uploaded knowledge base documents for the organization, with usage metadata.",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "KB documents",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "documents": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/KbDocument"
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "count": {
                          "type": "integer"
                        },
                        "limit": {
                          "type": "integer"
                        },
                        "remaining": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/company/kb/documents/upload-init": {
      "post": {
        "tags": [
          "Company"
        ],
        "summary": "Initiate document upload",
        "description": "Validates the file and returns a presigned S3 URL for direct upload. Call `/api/company/kb/documents/complete` after the upload finishes.",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "filename",
                  "contentType",
                  "sizeBytes"
                ],
                "properties": {
                  "filename": {
                    "type": "string",
                    "example": "product-guide.pdf"
                  },
                  "contentType": {
                    "type": "string",
                    "example": "application/pdf"
                  },
                  "sizeBytes": {
                    "type": "integer",
                    "example": 1048576
                  },
                  "displayName": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Upload initiated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "documentId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "uploadUrl": {
                      "type": "string",
                      "format": "uri",
                      "description": "Presigned S3 URL for PUT upload"
                    },
                    "storageKey": {
                      "type": "string"
                    },
                    "expiresIn": {
                      "type": "integer",
                      "description": "URL expiry in seconds"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request (invalid file type, size, or document limit reached)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/company/kb/documents/complete": {
      "post": {
        "tags": [
          "Company"
        ],
        "summary": "Complete document upload",
        "description": "Marks a document as uploaded after the client finishes uploading to S3. Triggers background processing (text extraction, chunking, and embedding).",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "documentId"
                ],
                "properties": {
                  "documentId": {
                    "type": "string",
                    "format": "uuid"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Upload marked as complete",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "pending"
                    },
                    "documentId": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Document not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/company/kb/documents/{documentId}": {
      "get": {
        "tags": [
          "Company"
        ],
        "summary": "Get a knowledge base document",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "documentId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Document details",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "document": {
                      "$ref": "#/components/schemas/KbDocument"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Company"
        ],
        "summary": "Delete a knowledge base document",
        "description": "Removes the document from S3 and the database. Associated chunks are deleted automatically.",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "documentId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Document deleted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/contracts/import": {
      "post": {
        "tags": [
          "Contracts"
        ],
        "summary": "Import a contract document",
        "description": "Uploads a contract document (PDF or Word) and uses AI to analyze the full document for template conversion. Legacy Word files (.doc) are converted to .docx automatically before analysis. Returns a markdown template with variable placeholders, the list of detected variables, and a one-sentence summary of the contract.",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": [
                  "file"
                ],
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary",
                    "description": "Contract file (PDF or Word .docx/.doc, max 10 MB)"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Analyzed contract",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "markdownTemplate",
                    "detectedVariables",
                    "summary"
                  ],
                  "properties": {
                    "markdownTemplate": {
                      "type": "string",
                      "description": "The complete contract converted to Markdown, with detected values replaced by {{variable}} placeholders.",
                      "example": "# Solar Installation Agreement\n\nThis agreement is between {{full_name}} of {{address}} and {{company_name}}..."
                    },
                    "detectedVariables": {
                      "type": "array",
                      "description": "Variables detected in the document and replaced in the template.",
                      "items": {
                        "type": "object",
                        "required": [
                          "originalText",
                          "suggestedVariable",
                          "confidence",
                          "context"
                        ],
                        "properties": {
                          "originalText": {
                            "type": "string",
                            "description": "The exact text that was replaced.",
                            "example": "John Doe"
                          },
                          "suggestedVariable": {
                            "type": "string",
                            "description": "The variable name used in the template.",
                            "example": "full_name"
                          },
                          "confidence": {
                            "type": "number",
                            "minimum": 0,
                            "maximum": 1,
                            "description": "Detection confidence between 0 and 1.",
                            "example": 0.95
                          },
                          "context": {
                            "type": "string",
                            "description": "Where this value appears in the contract.",
                            "example": "Customer name in the agreement header"
                          }
                        }
                      }
                    },
                    "summary": {
                      "type": "string",
                      "description": "One sentence describing the contract type.",
                      "example": "A residential solar installation agreement."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request (unsupported file type, file too large, or the document could not be processed)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error (including when .doc conversion is unavailable in the current environment)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/decks/{deckId}/action-configs": {
      "get": {
        "tags": [
          "Contracts"
        ],
        "summary": "List action configs",
        "description": "Returns all action configurations (contract templates) for a deck.",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "deckId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Action configs",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/ActionConfig"
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Contracts"
        ],
        "summary": "Create an action config",
        "description": "Creates a new contract template or action configuration for a deck.",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "deckId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "actionType",
                  "templateMarkdown"
                ],
                "properties": {
                  "actionType": {
                    "type": "string",
                    "example": "loi"
                  },
                  "templateMarkdown": {
                    "type": "string"
                  },
                  "disclosuresMarkdown": {
                    "type": "string"
                  },
                  "requirementsJson": {
                    "type": "object"
                  },
                  "repName": {
                    "type": "string"
                  },
                  "status": {
                    "type": "string",
                    "enum": [
                      "draft",
                      "published"
                    ],
                    "default": "draft"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Action config created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ActionConfig"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/decks/{deckId}/action-configs/{configId}": {
      "get": {
        "tags": [
          "Contracts"
        ],
        "summary": "Get an action config",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "deckId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "in": "path",
            "name": "configId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Action config",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ActionConfig"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "put": {
        "tags": [
          "Contracts"
        ],
        "summary": "Update an action config",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "deckId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "in": "path",
            "name": "configId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "templateMarkdown": {
                    "type": "string"
                  },
                  "disclosuresMarkdown": {
                    "type": "string"
                  },
                  "requirementsJson": {
                    "type": "object"
                  },
                  "repName": {
                    "type": "string"
                  },
                  "status": {
                    "type": "string",
                    "enum": [
                      "draft",
                      "published"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated action config",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ActionConfig"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Contracts"
        ],
        "summary": "Delete an action config",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "deckId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "in": "path",
            "name": "configId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Action config deleted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/decks/{deckId}/intro": {
      "get": {
        "tags": [
          "Decks"
        ],
        "summary": "Get intro page config",
        "description": "Returns the intro page configuration for a deck, including the background image, headline, CTA button label, and home photo setting.",
        "parameters": [
          {
            "in": "path",
            "name": "deckId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Intro configuration, or null if not set",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "intro": {
                      "nullable": true,
                      "$ref": "#/components/schemas/IntroConfig"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "put": {
        "tags": [
          "Decks"
        ],
        "summary": "Upsert intro page config",
        "description": "Creates or updates the intro page for a deck. Enabling an intro page switches the deck to lazy generation mode.\n\nThe `headline`, `subtitle`, and `ctaButtonLabel` fields may include homeowner tokens from the intro allowlist: `{{first_name}}`, `{{last_name}}`, `{{address}}`, `{{city}}`, `{{state}}`, `{{zip}}`, `{{email}}`, `{{phone}}`, `{{average_utility_bill}}`, and `{{journey_name}}`. Both `{{field}}` and `{{homeowner.field}}` forms are accepted. Any other token (roof or cost fields, product or datetime tokens, or a typo like `{{firstname}}`) is rejected with `400`, and the error message names the offending token. A field is only re-validated when this request changes its current value, so decks that already hold a legacy token can save unrelated fields without editing the legacy copy first.\n\nWhen changed, `subtitle` must be 120 characters or fewer and `ctaButtonLabel` must be 30 characters or fewer, counted before tokens expand. Longer values are rejected with `400`. Existing over-length values are grandfathered the same way as legacy tokens.",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "deckId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "backgroundImage",
                  "headline"
                ],
                "properties": {
                  "backgroundImage": {
                    "type": "string",
                    "description": "S3 key for the intro background image"
                  },
                  "headline": {
                    "type": "string",
                    "example": "Your Custom Solar Proposal"
                  },
                  "subtitle": {
                    "type": "string",
                    "maxLength": 120,
                    "description": "Supporting line below the headline. Maximum 120 characters, counted before tokens expand."
                  },
                  "ctaButtonLabel": {
                    "type": "string",
                    "maxLength": 30,
                    "description": "Get Started button text. Maximum 30 characters.",
                    "example": "View My Proposal"
                  },
                  "homePhotoEnabled": {
                    "type": "boolean",
                    "description": "Show a photo of the homeowner's home above the headline. Must be `true` or `false`; any other value returns `400`. Omit to keep the stored value. New intro pages start with it off."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Saved intro config",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "intro": {
                      "$ref": "#/components/schemas/IntroConfig"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Decks"
        ],
        "summary": "Delete intro page config",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "deckId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Intro deleted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/slides/{slideId}/product-data": {
      "get": {
        "tags": [
          "Slides"
        ],
        "summary": "Get product pricing data",
        "description": "Returns the good/better/best product pricing tiers for a product pricing slide.",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "slideId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Product data",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "productData": {
                      "$ref": "#/components/schemas/ProductSlideData"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "put": {
        "tags": [
          "Slides"
        ],
        "summary": "Upsert product pricing data",
        "description": "Sets product pricing tiers for a slide. The slide type is automatically set to `product_pricing_v1`.",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "slideId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "productData"
                ],
                "properties": {
                  "productData": {
                    "$ref": "#/components/schemas/ProductSlideData"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Product data saved",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Slides"
        ],
        "summary": "Remove product pricing data",
        "description": "Removes product data and resets the slide type to `standard`.",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "slideId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Product data removed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/notifications/subscriptions": {
      "get": {
        "tags": [
          "Notifications"
        ],
        "summary": "List notification subscriptions",
        "description": "Returns all notification subscriptions for the organization.",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "responses": {
          "200": {
            "description": "Subscriptions",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/NotificationSubscription"
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Notifications"
        ],
        "summary": "Create a notification subscription",
        "description": "Subscribes to an event type via a delivery channel (webhook, email, or console).",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name",
                  "eventType",
                  "channel",
                  "channelConfig"
                ],
                "properties": {
                  "name": {
                    "type": "string",
                    "example": "Slack \u2014 new presentation"
                  },
                  "eventType": {
                    "type": "string",
                    "example": "presentation.opened"
                  },
                  "channel": {
                    "type": "string",
                    "enum": [
                      "webhook",
                      "email",
                      "console"
                    ]
                  },
                  "channelConfig": {
                    "type": "object",
                    "description": "Channel-specific config. Webhook: `{ url }`. Email: `{ toEmails: [\"a@b.com\"] }`."
                  },
                  "deckId": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Scope to a specific deck (optional)"
                  },
                  "isActive": {
                    "type": "boolean",
                    "default": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Subscription created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NotificationSubscription"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/notifications/subscriptions/{subscriptionId}": {
      "get": {
        "tags": [
          "Notifications"
        ],
        "summary": "Get a notification subscription",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "subscriptionId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Subscription",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NotificationSubscription"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "put": {
        "tags": [
          "Notifications"
        ],
        "summary": "Update a notification subscription",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "subscriptionId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "eventType": {
                    "type": "string"
                  },
                  "channel": {
                    "type": "string",
                    "enum": [
                      "webhook",
                      "email",
                      "console"
                    ]
                  },
                  "channelConfig": {
                    "type": "object"
                  },
                  "deckId": {
                    "type": "string",
                    "format": "uuid",
                    "nullable": true
                  },
                  "isActive": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated subscription",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NotificationSubscription"
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Notifications"
        ],
        "summary": "Delete a notification subscription",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "subscriptionId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Subscription deleted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/notifications/events": {
      "get": {
        "tags": [
          "Notifications"
        ],
        "summary": "List event log",
        "description": "Returns a keyset-paginated, filterable log of all events for the organization, ordered by `occurredAt` descending with `id` as the tiebreaker. Page forward by passing the previous response's `page.nextCursor` as `cursor`; poll for new activity with `recent=1`. Unknown query parameters (including the removed `offset`) are rejected with a `400`. `email.sent` entries include top-level `recipientEmail`, `skipReason`, and `variant` fields resolved from the delivery attempt; event payloads themselves carry identifiers only, never email addresses. `email.opened` entries include a top-level `machineOpen` flag: `true` when every open SendGrid reported for the delivery was automatic (for example, an Apple Mail Privacy Protection prefetch), so the UI can label them as `Email Opened (automatic)`. Entries older than 90 days stay in the log with `archivedAt` set and their payloads reduced to identifier and classification fields; question and answer text is removed at that point.\n\nWhen `aggregateId` is set to a presentation UUID, the response may include a derived `presentation.link_opened` entry synthesized from `firstViewedAt`. It rides along as an extra row rather than taking a page slot, so it never displaces a stored row and never becomes a `nextCursor`. Its `id` is `presentation.link_opened:{presentationId}` and its payload is `{ presentationId }`. Every presentation that has been opened at least once carries this line, including presentations opened before the derivation shipped.",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "in": "query",
            "name": "eventType",
            "schema": {
              "type": "string"
            },
            "description": "Filter by event type"
          },
          {
            "in": "query",
            "name": "excludeEventTypes",
            "schema": {
              "type": "string",
              "maxLength": 500
            },
            "description": "Comma-separated list of event types to omit. Use this to hide a high-volume type (for example, `narration.played`) from an activity feed rather than allowlisting every other type."
          },
          {
            "in": "query",
            "name": "aggregateType",
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "aggregateId",
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "since",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "in": "query",
            "name": "until",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25
            },
            "description": "Page size. Rejected with 400 if above the cap; never clamped."
          },
          {
            "in": "query",
            "name": "cursor",
            "schema": {
              "type": "string",
              "maxLength": 512
            },
            "description": "Opaque, server-authored keyset cursor from a previous response's `page.nextCursor`. Returns rows strictly older than the anchor row. Mutually exclusive with `recent`."
          },
          {
            "in": "query",
            "name": "recent",
            "schema": {
              "type": "string",
              "enum": [
                "1"
              ]
            },
            "description": "Poll mode. Returns only rows from the last 90 seconds on the server clock. Mutually exclusive with `cursor`."
          }
        ],
        "responses": {
          "200": {
            "description": "Event log",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "events": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/EventLogEntry"
                      }
                    },
                    "page": {
                      "type": "object",
                      "properties": {
                        "limit": {
                          "type": "integer"
                        },
                        "hasMore": {
                          "type": "boolean"
                        },
                        "nextCursor": {
                          "type": "string",
                          "nullable": true,
                          "description": "Opaque cursor for the next older page. `null` whenever `hasMore` is false."
                        }
                      },
                      "required": [
                        "limit",
                        "hasMore",
                        "nextCursor"
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/presentations/{presentationId}/start": {
      "post": {
        "tags": [
          "Presentations"
        ],
        "summary": "Start a presentation",
        "description": "Triggers lazy generation when a viewer clicks the CTA on the intro page. Safe to call multiple times \u2014 duplicate generation requests are ignored.",
        "parameters": [
          {
            "in": "path",
            "name": "presentationId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Presentation status",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "ready",
                        "generating"
                      ]
                    },
                    "phase": {
                      "type": "string",
                      "nullable": true
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "410": {
            "description": "Presentation deleted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/presentations/{presentationId}/content": {
      "get": {
        "tags": [
          "Presentations"
        ],
        "summary": "Get presentation slides and Q&A settings",
        "description": "Returns the slide payload and Q&A settings for a presentation. The presentation viewer fetches this behind the intro or loading screen so the initial page load stays small. Requires an `x-presentation-token` scoped to this presentation. Expired tokens are rejected with `401` \u2014 reload the presentation page to obtain a fresh one. Audio and image URLs in the response are freshly signed on every call and expire, so the response is marked `Cache-Control: private, no-store` and must not be cached.",
        "security": [
          {
            "presentationToken": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "presentationId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Presentation content",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "not_started",
                        "pending",
                        "generating",
                        "ready",
                        "failed"
                      ]
                    },
                    "slides": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/PresentationSlide"
                      }
                    },
                    "qaSettings": {
                      "$ref": "#/components/schemas/PresentationQaSettings"
                    }
                  },
                  "required": [
                    "id",
                    "status",
                    "slides"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, or expired presentation token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "410": {
            "description": "Presentation no longer available",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/presentations/{presentationId}/product-selection": {
      "get": {
        "tags": [
          "Presentations"
        ],
        "summary": "Get product selections",
        "description": "Returns all product tier selections the viewer has made during the presentation.",
        "parameters": [
          {
            "in": "path",
            "name": "presentationId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Product selections keyed by slide ID",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "selectedProducts": {
                      "type": "object",
                      "additionalProperties": {
                        "type": "object"
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "put": {
        "tags": [
          "Presentations"
        ],
        "summary": "Save a product selection",
        "description": "Saves a product tier selection for a specific slide during the presentation.",
        "parameters": [
          {
            "in": "path",
            "name": "presentationId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "slideId",
                  "tier",
                  "productName",
                  "price"
                ],
                "properties": {
                  "slideId": {
                    "type": "string"
                  },
                  "tier": {
                    "type": "string",
                    "enum": [
                      "good",
                      "better",
                      "best"
                    ]
                  },
                  "productName": {
                    "type": "string"
                  },
                  "price": {
                    "type": "string"
                  },
                  "priceSuffix": {
                    "type": "string"
                  },
                  "productImage": {
                    "type": "string"
                  },
                  "highlights": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Selection saved",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "selection": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request (validation error, or a request body that is not valid JSON or not a JSON object)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/presentations/{presentationId}/sign-contract": {
      "get": {
        "tags": [
          "Contracts"
        ],
        "summary": "Get contract for signing",
        "description": "Returns the contract template, company branding, and product data needed to render the signing view. Requires an `x-presentation-token` scoped to this presentation, matching the sibling `events` and `appointment` routes. Obtain the token from `POST /api/presentations/{presentationId}/events-token`.",
        "security": [
          {
            "presentationToken": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "presentationId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "in": "query",
            "name": "configId",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Action config to use (uses published config if omitted)"
          }
        ],
        "responses": {
          "200": {
            "description": "Contract data for rendering",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "template": {
                      "type": "string"
                    },
                    "requirements": {
                      "type": "object",
                      "nullable": true
                    },
                    "repName": {
                      "type": "string",
                      "nullable": true
                    },
                    "companyName": {
                      "type": "string"
                    },
                    "companyLogo": {
                      "type": "string",
                      "nullable": true
                    },
                    "companyDetails": {
                      "type": "object"
                    },
                    "branding": {
                      "type": "object",
                      "nullable": true
                    },
                    "products": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, or wrong-presentation `x-presentation-token`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Contracts"
        ],
        "summary": "Sign a contract",
        "description": "Submits a contract signature. Validates the typed signature against the customer name, resolves the template with variables, and creates an audit-trailed signed document. Requires an `x-presentation-token` scoped to this presentation, matching the sibling `events` and `appointment` routes. Obtain the token from `POST /api/presentations/{presentationId}/events-token`. Soft-deleted presentations are refused with `404` even when the caller holds a still-valid token minted before the delete. Client-supplied `variables` are filtered through an allow-list before storage. Non-whitelisted keys are dropped rather than persisted to `resolvedVariables`.",
        "security": [
          {
            "presentationToken": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "presentationId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "variables",
                  "signature"
                ],
                "properties": {
                  "configId": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "variables": {
                    "type": "object",
                    "description": "Variable values substituted into the template. Keys outside the server-side allow-list are dropped before storage. The allow-list covers customer fields (`first_name`, `last_name`, `full_name`, `address`, `city`, `state`, `zip`, `email`, `phone`), company fields (`company_name`, `company_address`, `company_city`, `company_state`, `company_zip`, `company_phone`, `company_email`, `license_number`, `rep_name`), and date fields (`today`, `month`, `year`, `date`, `signature_timestamp`). Non-string values are also dropped.",
                    "required": [
                      "full_name"
                    ],
                    "properties": {
                      "full_name": {
                        "type": "string"
                      },
                      "first_name": {
                        "type": "string"
                      },
                      "last_name": {
                        "type": "string"
                      }
                    },
                    "additionalProperties": {
                      "type": "string"
                    }
                  },
                  "signature": {
                    "type": "string",
                    "description": "Typed signature (must match the customer name)"
                  },
                  "agreedToTerms": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Contract signed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "documentId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "signedAt": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request (signature mismatch, validation error, or a request body that is not valid JSON or not a JSON object)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, malformed, or wrong-presentation `x-presentation-token`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Presentation not found, presentation soft-deleted, deck missing, or contract template not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/presentations/{presentationId}/events": {
      "post": {
        "tags": [
          "Presentations"
        ],
        "summary": "Record a presentation event",
        "description": "Ingests interaction events from the presentation viewer (opens, presses of the intro Start button, the first time slides are shown, slide views, narration playback, video slide playback, CTA clicks, last-slide arrivals, and per-session summaries). Authenticated via an HMAC token in the request body. Every slide exit is recorded: `slide_viewed` accepts an optional `skipped` flag for views under the 2-second skip threshold, and `slide_viewed_batch` submits up to 25 slide views in one request. Narration playback outcomes are always batched via `narration_played_batch` (up to 25 outcomes per request); each outcome reports whether narration actually started, whether it completed, and seconds played vs. seconds available. `last_slide_reached` is sent once per page load when the viewer arrives on the last slide. AI Presentations records `presentation.completed` only when that slide is the presentation's last slide and the presentation is ready. It records a completion for every visit, including reloads on the last slide. `session_summary` and `narration_session_summary` are cumulative, monotone, page-exit mirrors written to PostHog only. Each request costs 1 against the per-IP rate limit of 60 requests per minute, including `narration_played_batch` requests. Every view in a batch after the first costs 1 more. For `slide_viewed_batch`, that extra cost counts against the same per-IP limit. For `narration_played_batch`, it counts against a separate narration bucket. The limit returns `429` when exceeded. The `action_detection` and `action_execution` types, and untyped Q&A interaction bodies, are acknowledged with `200` for backward compatibility but are no longer stored.",
        "parameters": [
          {
            "in": "path",
            "name": "presentationId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "_token",
                  "type"
                ],
                "properties": {
                  "_token": {
                    "type": "string",
                    "description": "HMAC authentication token"
                  },
                  "type": {
                    "type": "string",
                    "enum": [
                      "presentation_opened",
                      "presentation_started",
                      "slides_shown",
                      "slide_viewed",
                      "slide_viewed_batch",
                      "narration_played_batch",
                      "video_played",
                      "cta_clicked",
                      "last_slide_reached",
                      "session_summary",
                      "narration_session_summary",
                      "action_detection",
                      "action_execution"
                    ],
                    "description": "Event type. `presentation_started` is sent when the viewer presses Start on the intro screen, and records a `presentation.started` event. `slides_shown` is sent once per visit, the first time the viewer shows slides. AI Presentations records the first time slides are shown to a homeowner as the presentation's start, once, and later visits never change it. Visits by Demand IQ staff, by signed-in members of your organization, in rep mode, or from presentations whose opened emails all went to Demand IQ staff or your organization's own users don't record a start. Visits from link scanners, such as Microsoft Safe Links, are ignored. `action_detection` and `action_execution` are deprecated: they are acknowledged but not stored. `video_played` is sent once per video slide whose video the viewer was offered, and records a `video.played` event."
                  },
                  "pointerCoarse": {
                    "type": "boolean",
                    "description": "Whether the viewer's primary pointer is coarse, as reported by the `(pointer: coarse)` media query. Optional. Applies to `presentation_opened`. AI Presentations combines it with the request's user agent to classify the device as mobile, tablet, or desktop."
                  },
                  "introShown": {
                    "type": "boolean",
                    "description": "Whether this visit opened on the intro screen, so the viewer had a Start button to press. Optional. Applies to `presentation_opened`."
                  },
                  "openSource": {
                    "type": "string",
                    "description": "The `utm_source` value from the presentation link. Optional. Applies to `presentation_opened`. AI Presentations lower-cases it and keeps it only when it is 1 to 40 characters of `a-z`, `0-9`, `_`, or `-`. Any other value is dropped."
                  },
                  "viewId": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Per-visit ID generated by the viewer. Optional. AI Presentations stores one `slide.viewed` event per `viewId`. A later report with the same `viewId` updates that event's `durationMs` and `skipped` instead of adding a new event, as long as its `durationMs` is not lower. Omit it to record a new event for every report."
                  },
                  "slideId": {
                    "type": "string",
                    "description": "Slide ID. Required for `slide_viewed`, `video_played`, and `last_slide_reached`. For `last_slide_reached`, send the presentation snapshot slide ID (the `deck_presentation_slides` row ID), not the deck slide ID. AI Presentations ignores any other ID and does not record `presentation.completed`. IDs longer than 100 characters are rejected with `400`."
                  },
                  "slideIndex": {
                    "type": "integer"
                  },
                  "durationMs": {
                    "type": "integer"
                  },
                  "skipped": {
                    "type": "boolean",
                    "description": "Whether the viewer left the slide in under 2 seconds. A flag, not a filter: fast flips are still recorded as `slide.viewed` events, not as a separate skip event."
                  },
                  "views": {
                    "type": "array",
                    "maxItems": 25,
                    "description": "Batched entries. Required when `type` is `slide_viewed_batch` or `narration_played_batch`. Each entry counts against the rate limit individually. For `slide_viewed_batch`, each item is a slide view (`slideId`, `slideIndex`, optional `viewId`, `durationMs`, and `skipped`). For `narration_played_batch`, each item is a narration outcome (`slideId`, `slideIndex`, `narrationStarted`, `narrationCompleted`, `secondsPlayed`, and `secondsAvailable`, which is `null` when the audio duration was never known).",
                    "items": {
                      "type": "object",
                      "required": [
                        "slideId",
                        "slideIndex"
                      ],
                      "properties": {
                        "viewId": {
                          "type": "string",
                          "format": "uuid",
                          "description": "Per-visit ID for `slide_viewed_batch` items. Reports with the same `viewId` update one `slide.viewed` event."
                        },
                        "slideId": {
                          "type": "string"
                        },
                        "slideIndex": {
                          "type": "integer"
                        },
                        "durationMs": {
                          "type": "integer"
                        },
                        "skipped": {
                          "type": "boolean"
                        },
                        "narrationStarted": {
                          "type": "boolean",
                          "description": "Whether `play()` actually resolved for this slide's narration. Autoplay-policy failures are never counted as started."
                        },
                        "narrationCompleted": {
                          "type": "boolean",
                          "description": "Whether the narration audio played to the end for this slide."
                        },
                        "secondsPlayed": {
                          "type": "number",
                          "minimum": 0,
                          "description": "Seconds of narration audio that actually played on this slide. Resumed or retried attempts credit only the remaining clip duration, so the total can never exceed `secondsAvailable`."
                        },
                        "secondsAvailable": {
                          "type": "number",
                          "minimum": 0,
                          "nullable": true,
                          "description": "Duration of the narration audio for this slide, in seconds. `null` when the audio duration was never known (for example, playback failed before metadata loaded)."
                        }
                      }
                    }
                  },
                  "ctaType": {
                    "type": "string"
                  },
                  "ctaLabel": {
                    "type": "string"
                  },
                  "ctaUrl": {
                    "type": "string",
                    "description": "Destination URL of an `external_link` CTA. Send it only on `cta_clicked` events for that CTA type."
                  },
                  "repMode": {
                    "type": "boolean",
                    "description": "Whether a sales rep is driving the presentation. Client-supplied; the server cannot resolve it. Applies to `cta_clicked`, `slides_shown`, `last_slide_reached`, `session_summary`, and `narration_session_summary`."
                  },
                  "firstScreen": {
                    "type": "string",
                    "enum": [
                      "intro",
                      "loading",
                      "slides",
                      "pending_data"
                    ],
                    "example": "intro",
                    "description": "The first screen the viewer showed on this visit. Client-supplied and optional. Applies to `cta_clicked` and `session_summary`. Any value outside the enum is rejected with `400`."
                  },
                  "conversationId": {
                    "type": "string",
                    "format": "uuid",
                    "description": "UUID that persists for the lifetime of the viewer's tab. Applies to `session_summary` and `narration_session_summary`."
                  },
                  "slidesViewed": {
                    "type": "integer",
                    "minimum": 0,
                    "description": "Session-to-date count of distinct slides viewed. `session_summary` only."
                  },
                  "slidesTotal": {
                    "type": "integer",
                    "minimum": 0,
                    "description": "Total number of slides in the presentation. `session_summary` only."
                  },
                  "furthestSlideIndex": {
                    "type": "integer",
                    "minimum": 0,
                    "description": "Highest 0-based slide index reached in this session. `session_summary` only."
                  },
                  "totalDwellMs": {
                    "type": "integer",
                    "minimum": 0,
                    "description": "Session-to-date wall-clock dwell across all slides, in milliseconds. `session_summary` only."
                  },
                  "ctaConfigured": {
                    "type": "boolean",
                    "description": "Whether the presentation has a CTA configured. `session_summary` only."
                  },
                  "slidesNarrationStarted": {
                    "type": "integer",
                    "minimum": 0,
                    "description": "Session-to-date count of slides on which narration playback actually started. `narration_session_summary` only. `> 0` is the derived read for \"audio enabled\"."
                  },
                  "slidesNarrationCompleted": {
                    "type": "integer",
                    "minimum": 0,
                    "description": "Session-to-date count of slides on which narration played to the end. `narration_session_summary` only."
                  },
                  "totalSecondsPlayed": {
                    "type": "number",
                    "minimum": 0,
                    "description": "Session-to-date sum of `secondsPlayed` across all slides. `narration_session_summary` only."
                  },
                  "totalSecondsAvailable": {
                    "type": "number",
                    "minimum": 0,
                    "description": "Session-to-date sum of `secondsAvailable` across all slides for which narration was attempted. `narration_session_summary` only."
                  },
                  "qaVoiceAudioStarted": {
                    "type": "integer",
                    "minimum": 0,
                    "description": "Session-to-date count of Q&A answer audio plays that actually started, where the question was asked by voice. `narration_session_summary` only."
                  },
                  "qaVoiceAudioCompleted": {
                    "type": "integer",
                    "minimum": 0,
                    "description": "Session-to-date count of Q&A answer audio plays that finished, where the question was asked by voice. Skips, errors, and rejected plays do not count. `narration_session_summary` only."
                  },
                  "qaChatAudioStarted": {
                    "type": "integer",
                    "minimum": 0,
                    "description": "Session-to-date count of Q&A answer audio plays that actually started, where the question was typed. `narration_session_summary` only."
                  },
                  "qaChatAudioCompleted": {
                    "type": "integer",
                    "minimum": 0,
                    "description": "Session-to-date count of Q&A answer audio plays that finished, where the question was typed. Skips, errors, and rejected plays do not count. `narration_session_summary` only."
                  },
                  "videoStarted": {
                    "type": "boolean",
                    "description": "Whether the YouTube video started playing. Required for `video_played`."
                  },
                  "completed": {
                    "type": "boolean",
                    "description": "Whether the video played to the end. Required for `video_played`."
                  },
                  "secondsWatched": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 86400,
                    "description": "Seconds of the video the viewer watched. Required for `video_played`."
                  },
                  "videoDurationSeconds": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 86400,
                    "nullable": true,
                    "description": "Length of the video in seconds, or `null` when the player never loaded far enough to know it. Required for `video_played`."
                  },
                  "outcome": {
                    "type": "string",
                    "enum": [
                      "ended",
                      "left",
                      "failed"
                    ],
                    "description": "How the video slide ended: `ended` when the video finished, `left` when the viewer moved on or left the page, `failed` when the video could not load. Required for `video_played`."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Event recorded",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Invalid token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/address/validate": {
      "post": {
        "tags": [
          "Utility"
        ],
        "summary": "Validate an address",
        "description": "Validates a physical address using geocoding. Returns formatted address, coordinates, and normalized components.",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "address",
                  "city",
                  "country"
                ],
                "properties": {
                  "address": {
                    "type": "string",
                    "example": "123 Main St"
                  },
                  "city": {
                    "type": "string",
                    "example": "Phoenix"
                  },
                  "state": {
                    "type": "string",
                    "example": "AZ"
                  },
                  "zip": {
                    "type": "string",
                    "example": "85001"
                  },
                  "country": {
                    "type": "string",
                    "minLength": 2,
                    "maxLength": 2,
                    "example": "US",
                    "description": "ISO 3166-1 alpha-2 country code"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Validation result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "valid": {
                      "type": "boolean"
                    },
                    "formattedAddress": {
                      "type": "string"
                    },
                    "coordinates": {
                      "type": "object",
                      "properties": {
                        "lat": {
                          "type": "number"
                        },
                        "lng": {
                          "type": "number"
                        }
                      }
                    },
                    "normalized": {
                      "type": "object"
                    },
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Validation service not configured",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/fonts": {
      "get": {
        "tags": [
          "Fonts"
        ],
        "summary": "List available fonts",
        "description": "Returns a list of available Google Fonts for use in deck branding. Results are cached for 24 hours.",
        "responses": {
          "200": {
            "description": "Font list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "fonts": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Font"
                      }
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/narration": {
      "post": {
        "tags": [
          "Narration"
        ],
        "summary": "Synthesize narration for a slide",
        "description": "Generates TTS audio for a single slide script. Requires an authenticated session. Use `/api/narration/single` for session-based caching or `/api/narration/batch` for multiple slides.",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "slideId",
                  "script"
                ],
                "properties": {
                  "slideId": {
                    "type": "string",
                    "minLength": 1
                  },
                  "script": {
                    "type": "string",
                    "minLength": 3
                  },
                  "voiceId": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Synthesized audio",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "slideId": {
                      "type": "string"
                    },
                    "audioUrl": {
                      "type": "string",
                      "format": "uri"
                    },
                    "script": {
                      "type": "string"
                    },
                    "source": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/narration/qa-audio": {
      "post": {
        "tags": [
          "Narration"
        ],
        "summary": "Synthesize Q&A prompt audio",
        "description": "Generates TTS audio for Q&A transition or resume prompts. Uses the deck's configured voice and prompt settings.",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "deckId",
                  "text"
                ],
                "properties": {
                  "deckId": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "text": {
                    "type": "string",
                    "minLength": 1
                  },
                  "voiceId": {
                    "type": "string"
                  },
                  "promptType": {
                    "type": "string",
                    "enum": [
                      "resume",
                      "transition"
                    ],
                    "default": "resume"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Generated audio with word timings",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "audioUrl": {
                      "type": "string",
                      "format": "uri"
                    },
                    "wordTimings": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/WordTiming"
                      }
                    },
                    "promptType": {
                      "type": "string",
                      "enum": [
                        "resume",
                        "transition"
                      ]
                    },
                    "voiceId": {
                      "type": "string",
                      "nullable": true
                    },
                    "source": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Deck not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/narration/generate-prompt": {
      "post": {
        "tags": [
          "Narration"
        ],
        "summary": "Generate a Q&A resume prompt",
        "description": "Returns the configured resume prompt text for a deck, along with pre-generated audio if available. Falls back to a default prompt when no deck-specific settings exist.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "deckId": {
                    "type": "string",
                    "format": "uuid"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Resume prompt with optional audio",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "prompt": {
                      "type": "string"
                    },
                    "audioUrl": {
                      "type": "string",
                      "format": "uri"
                    },
                    "wordTimings": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/WordTiming"
                      }
                    }
                  },
                  "required": [
                    "prompt"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/slides/analyze-and-generate": {
      "post": {
        "tags": [
          "Generation"
        ],
        "summary": "Analyze a slide image and generate content",
        "description": "Uses AI vision to analyze a slide image and generate a narration script with key points. Optionally uses deck context and slide-specific context to improve the output.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "imageUrl"
                ],
                "properties": {
                  "imageUrl": {
                    "type": "string",
                    "format": "uri",
                    "description": "URL of the slide image to analyze"
                  },
                  "deckId": {
                    "type": "string",
                    "description": "Deck ID for additional context"
                  },
                  "slideId": {
                    "type": "string",
                    "description": "Slide ID (used for intro slide detection)"
                  },
                  "slideContext": {
                    "type": "string",
                    "description": "Slide-specific context to guide generation"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Generated content",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "script": {
                      "type": "string",
                      "description": "Generated narration script"
                    },
                    "analysis": {
                      "type": "object",
                      "properties": {
                        "title": {
                          "type": "string"
                        },
                        "keyPoints": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/decks/{deckId}/generate-preview": {
      "post": {
        "tags": [
          "Generation"
        ],
        "summary": "Generate preview audio",
        "description": "Generates preview audio for all slides in a deck that have narration scripts but no audio yet. Useful for previewing a deck before sending presentations.",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "deckId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Preview generation started",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "generatedCount": {
                      "type": "integer",
                      "description": "Number of slides for which preview audio was generated"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/decks/{deckId}/preview-status": {
      "get": {
        "tags": [
          "Generation"
        ],
        "summary": "Check preview audio status",
        "description": "Returns the current preview audio generation status for a deck, including how many slides need preview generation.",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "deckId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Preview status",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "needsPreviewGeneration": {
                      "type": "boolean"
                    },
                    "slidesNeedingPreview": {
                      "type": "integer"
                    },
                    "slidesWithTokens": {
                      "type": "integer"
                    },
                    "totalSlides": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/presentations/{presentationId}/events-token": {
      "post": {
        "tags": [
          "Presentations"
        ],
        "summary": "Refresh an events token",
        "description": "Exchanges an existing presentation token (which may be expired up to 7 days) for a fresh HMAC token. Used by the presentation viewer to maintain event tracking authentication. Rate-limited to 10 requests per minute per presentation.",
        "parameters": [
          {
            "in": "path",
            "name": "presentationId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "_token"
                ],
                "properties": {
                  "_token": {
                    "type": "string",
                    "description": "Existing presentation token (may be expired up to 7 days)"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "New token issued",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "token": {
                      "type": "string"
                    },
                    "expiresAt": {
                      "type": "integer",
                      "description": "Unix timestamp when the token expires"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/presentations/{presentationId}/appointment": {
      "get": {
        "tags": [
          "Appointments"
        ],
        "summary": "Get available appointment slots",
        "description": "Returns available appointment time slots grouped by date, along with any existing appointment for the presentation. Authenticated via a presentation token. Rate-limited to 30 requests per minute.",
        "security": [
          {
            "presentationToken": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "presentationId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Available slots and existing appointment",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "slotsByDate": {
                      "type": "object",
                      "additionalProperties": {
                        "type": "array",
                        "items": {
                          "type": "object",
                          "properties": {
                            "start": {
                              "type": "string",
                              "format": "date-time"
                            },
                            "end": {
                              "type": "string",
                              "format": "date-time"
                            }
                          }
                        }
                      },
                      "description": "Time slots keyed by date (YYYY-MM-DD)"
                    },
                    "appointmentLength": {
                      "type": "integer",
                      "description": "Duration in minutes"
                    },
                    "timezone": {
                      "type": "string",
                      "description": "Timezone offset"
                    },
                    "existingAppointment": {
                      "type": "object",
                      "nullable": true
                    },
                    "prospectEmail": {
                      "type": "string",
                      "nullable": true
                    },
                    "prospectPhone": {
                      "type": "string",
                      "nullable": true
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Scheduling unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Appointments"
        ],
        "summary": "Book an appointment",
        "description": "Books an appointment for a presentation viewer. Validates the time slot is still available and creates the appointment. Rate-limited to 10 requests per minute.",
        "security": [
          {
            "presentationToken": []
          }
        ],
        "parameters": [
          {
            "in": "path",
            "name": "presentationId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "startTime",
                  "endTime",
                  "attendeeTZ"
                ],
                "properties": {
                  "startTime": {
                    "type": "string",
                    "format": "date-time"
                  },
                  "endTime": {
                    "type": "string",
                    "format": "date-time"
                  },
                  "attendeeTZ": {
                    "type": "string",
                    "description": "Attendee's IANA timezone"
                  },
                  "email": {
                    "type": "string",
                    "format": "email"
                  },
                  "phone": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Appointment booked",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "startTime": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "endTime": {
                      "type": "string",
                      "format": "date-time"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Conflict (slot already booked or appointment already exists)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Scheduling unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/roof-measurements": {
      "post": {
        "tags": [
          "Roof Measurements"
        ],
        "summary": "Request roof measurements",
        "description": "Initiates an automated roof measurement request for a homeowner address. The address is validated before submission. Poll `/api/roof-measurements/{requestId}/status` for results.",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "deckId",
                  "homeowner"
                ],
                "properties": {
                  "deckId": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "homeowner": {
                    "type": "object",
                    "required": [
                      "first_name",
                      "address",
                      "city",
                      "country"
                    ],
                    "properties": {
                      "first_name": {
                        "type": "string"
                      },
                      "last_name": {
                        "type": "string"
                      },
                      "address": {
                        "type": "string"
                      },
                      "city": {
                        "type": "string"
                      },
                      "state": {
                        "type": "string"
                      },
                      "zip": {
                        "type": "string"
                      },
                      "country": {
                        "type": "string",
                        "minLength": 2,
                        "maxLength": 2,
                        "description": "ISO 3166-1 alpha-2 country code"
                      },
                      "phone": {
                        "type": "string"
                      },
                      "email": {
                        "type": "string",
                        "format": "email"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Measurement request created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "requestId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "status": {
                      "type": "string",
                      "example": "pending"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Deck not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Address could not be verified",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Roof measurement service not configured",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/roof-measurements/{requestId}/status": {
      "get": {
        "tags": [
          "Roof Measurements"
        ],
        "summary": "Get roof measurement status",
        "description": "Returns the current status and results of a roof measurement request. Poll this endpoint until the status reaches a terminal state (`completed`, `failed`, `timed_out`, `cancelled`, or `skipped`).\n\nA request moves through `pending` \u2192 `creating_prospect` \u2192 `requesting_ev` \u2192 `polling_ev` \u2192 `completed`. If the EagleView request fails (for example, when the address is unserviceable or the upstream API rejects it), the status transitions to `fetching_fallback` and the system attempts a calculated roof measurement before failing. When fallback succeeds, the result's `source` is `calc` instead of `ev`; the `error` field retains the original EagleView error message for debugging.",
        "parameters": [
          {
            "in": "path",
            "name": "requestId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "UUID of the measurement request"
          }
        ],
        "responses": {
          "200": {
            "description": "Measurement status",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "requestId": {
                      "type": "string"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "pending",
                        "creating_prospect",
                        "requesting_ev",
                        "polling_ev",
                        "fetching_fallback",
                        "completed",
                        "failed",
                        "timed_out",
                        "cancelled",
                        "skipped"
                      ]
                    },
                    "result": {
                      "type": "object",
                      "nullable": true,
                      "properties": {
                        "squares": {
                          "type": "number",
                          "description": "Roof area in squares"
                        },
                        "source": {
                          "type": "string",
                          "enum": [
                            "ev",
                            "calc"
                          ],
                          "description": "Measurement source (EagleView or calculated)"
                        }
                      }
                    },
                    "error": {
                      "type": "string",
                      "nullable": true
                    },
                    "attemptCount": {
                      "type": "integer"
                    },
                    "elapsedSeconds": {
                      "type": "number"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Request not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/roof-measurements/{requestId}/cancel": {
      "post": {
        "tags": [
          "Roof Measurements"
        ],
        "summary": "Cancel a roof measurement request",
        "description": "Cancels or skips an in-progress roof measurement request. Use `cancel` to abort entirely or `skip` to mark it as skipped and proceed without measurements.",
        "parameters": [
          {
            "in": "path",
            "name": "requestId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "UUID of the measurement request"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "action"
                ],
                "properties": {
                  "action": {
                    "type": "string",
                    "enum": [
                      "cancel",
                      "skip"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Request cancelled or skipped",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "status": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/intent/continue": {
      "post": {
        "tags": [
          "Q&A"
        ],
        "summary": "Classify viewer intent after Q&A",
        "description": "Uses AI (with regex fallback) to classify a viewer's natural-language response during a Q&A pause. Returns whether the viewer wants to continue the presentation, go back to the previous slide, or ask another question.\n\nWhen the viewer was navigated to a different slide to answer a question, the classification includes a `go_back` option so they can return to where they were.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "userResponse",
                  "promptText"
                ],
                "properties": {
                  "userResponse": {
                    "type": "string",
                    "minLength": 1,
                    "description": "The viewer's spoken or typed response"
                  },
                  "promptText": {
                    "type": "string",
                    "minLength": 1,
                    "description": "The prompt that was shown to the viewer (e.g. \"Would you like to continue?\")"
                  },
                  "didNavigateToNewSlide": {
                    "type": "boolean",
                    "default": false,
                    "description": "Whether the viewer was navigated to a different slide to answer their question"
                  },
                  "currentSlideTitle": {
                    "type": "string",
                    "description": "Title of the slide currently displayed (used for context when classifying)"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Classification result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "intent": {
                      "type": "string",
                      "enum": [
                        "continue",
                        "go_back",
                        "question"
                      ],
                      "description": "`continue` \u2014 resume the presentation from the current slide. `go_back` \u2014 return to the slide before the Q&A detour (only when `didNavigateToNewSlide` is true). `question` \u2014 the viewer has a new question."
                    },
                    "shouldContinue": {
                      "type": "boolean",
                      "description": "`true` when intent is `continue` or `go_back`, `false` when `question`"
                    }
                  },
                  "required": [
                    "intent",
                    "shouldContinue"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/actions": {
      "post": {
        "tags": [
          "Actions"
        ],
        "summary": "Detect a voice or text command",
        "description": "Parses natural-language input (from voice or text) to detect presentation control commands such as navigation, audio control, and CTA actions. Rate-limited to 10 requests per minute per IP and presentation.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "input"
                ],
                "properties": {
                  "input": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 500,
                    "description": "Voice transcript or text input"
                  },
                  "presentationId": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "context": {
                    "type": "object",
                    "properties": {
                      "currentSlide": {
                        "type": "integer",
                        "minimum": 1
                      },
                      "totalSlides": {
                        "type": "integer",
                        "minimum": 1
                      },
                      "isPlaying": {
                        "type": "boolean"
                      },
                      "volume": {
                        "type": "number",
                        "minimum": 0,
                        "maximum": 100
                      },
                      "awaitingResume": {
                        "type": "boolean"
                      },
                      "didNavigateToNewSlide": {
                        "type": "boolean"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Detection result",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "type": "object",
                      "description": "Action detected",
                      "properties": {
                        "type": {
                          "type": "string",
                          "enum": [
                            "action"
                          ]
                        },
                        "action": {
                          "type": "object",
                          "properties": {
                            "category": {
                              "type": "string",
                              "enum": [
                                "navigation",
                                "audio",
                                "cta",
                                "continuation"
                              ]
                            },
                            "action": {
                              "type": "string",
                              "description": "Specific action (e.g. next, pause, open_cta, resume_here)"
                            },
                            "slideNumber": {
                              "type": "integer",
                              "description": "Target slide (for goto action)"
                            },
                            "step": {
                              "type": "integer",
                              "description": "Volume step (for volume_up/down)"
                            },
                            "value": {
                              "type": "integer",
                              "description": "Volume value (for set_volume)"
                            }
                          }
                        },
                        "confidence": {
                          "type": "number"
                        }
                      }
                    },
                    {
                      "type": "object",
                      "description": "No action detected",
                      "properties": {
                        "type": {
                          "type": "string",
                          "enum": [
                            "no_action"
                          ]
                        },
                        "rateLimited": {
                          "type": "boolean"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "type": {
                      "type": "string"
                    },
                    "rateLimited": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/onboarding/tour": {
      "post": {
        "tags": [
          "Onboarding"
        ],
        "summary": "Record a presentations onboarding completion or dismissal",
        "description": "Records that the current user completed or dismissed the presentations onboarding modal (ENG-641; versioned in ENG-636). The server records the acknowledged content version (`CURRENT_ONBOARDING_VERSION`, currently `2`) on the user's row and returns the full updated `TourState` so callers can write it straight into the shared `/api/auth/me` cache. Idempotent per `(organization, user, version)`: the underlying upsert only fires when the stored `tourVersion` is behind the incoming version, so a repeat call at the same version is a no-op and never overwrites `tourCompletedAt` or `tourDismissedAt`. A PostHog `onboarding_milestone` event (`tour_completed` or `tour_dismissed`, keyed on organization ID, carrying a `tour_version` property) is captured only on the first transition to a new version; subsequent calls emit no analytics. Pass `legacy: true` (only valid with `action: \"dismissed\"`) to silently backfill users carrying the old per-browser `templates_onboarding_seen_v1` localStorage flag: the row is written at `LEGACY_TOUR_VERSION` (`1`) so the user stays eligible for newer content, and no event fires.",
        "security": [
          {
            "sessionCookie": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "action": {
                    "type": "string",
                    "enum": [
                      "completed",
                      "dismissed"
                    ],
                    "description": "`completed` \u2014 user clicked the \"Get Started\" button on the onboarding modal. `dismissed` \u2014 any other close (X, Esc, or navigation). Overlay clicks do not dismiss the modal."
                  },
                  "source": {
                    "type": "string",
                    "enum": [
                      "templates",
                      "my_presentations"
                    ],
                    "description": "Which page the tour was shown on. Used for analytics attribution only; it does not affect persistence."
                  },
                  "legacy": {
                    "type": "boolean",
                    "description": "Set to `true` to backfill a user with the deprecated per-browser localStorage flag. Silent \u2014 no PostHog event is emitted. Only valid when `action` is `dismissed`."
                  }
                },
                "required": [
                  "action",
                  "source"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated tour state for the current user",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TourState"
                }
              }
            }
          },
          "400": {
            "description": "Invalid JSON body, unknown `action`/`source`, or `legacy: true` combined with `action: \"completed\"`",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  }
}
