Skip to main content

​
Overview

Themes control the visual appearance of your quiz videos — colors, fonts, backgrounds, particles, transitions, and more. Every quiz can have one theme assigned. You can use built-in public themes or create your own.

​
Create a Theme

curl -X POST https://app.quiz-quail.com/api/v1/themes \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Brand Blue",
    "primaryColor": "#2563EB",
    "secondaryColor": "#3B82F6",
    "backgroundColor": "#0F172A",
    "textColor": "#F8FAFC",
    "accentColor": "#38BDF8",
    "fontFamily": "Montserrat"
  }'

​
Core Fields

FieldTypeDefaultDescription
namestringRequiredTheme name (1-100 characters)
primaryColorhex string#3B82F6Primary emphasis color
secondaryColorhex string#6366F1Secondary color
backgroundColorhex string#0A0F1CBackground color
textColorhex string#F1F5F9Text color
accentColorhex string#38BDF8Accent color for highlights
fontFamilystringInterFont family (see supported fonts below)
backgroundImageUrlurl | nullnullCustom background image URL
isPublicbooleanfalseMake this theme available to all users
soundPack"default" | "none""default"Audio sound pack

​
Supported Fonts

The video renderer supports 16 Google Fonts: Inter, Montserrat, Poppins, Roboto, Oswald, Playfair Display, Lato, Raleway, Open Sans, Nunito, Merriweather, Work Sans, Quicksand, Rubik, Barlow, Cabin

​
Visual Effects

Themes support an optional effects object with 42 configurable fields for fine-grained visual control. All effects have sensible defaults, so you only need to set the ones you want to change. 
curl -X POST https://app.quiz-quail.com/api/v1/themes \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Neon Night",
    "primaryColor": "#A855F7",
    "secondaryColor": "#EC4899",
    "backgroundColor": "#09090B",
    "textColor": "#FAFAFA",
    "accentColor": "#22D3EE",
    "fontFamily": "Montserrat",
    "effects": {
      "backgroundStyle": "aurora",
      "particleStyle": "fireflies",
      "particleDensity": 0.4,
      "titleTextStyle": "glow",
      "frameStyle": "neon",
      "celebrationStyle": "flash",
      "transitionStyle": "flash",
      "optionCardVariant": "glass"
    }
  }'
Background effects:
FieldOptionsDefault
backgroundStyleblobs, aurora, gradient_mesh, solid, noiseblobs
backgroundPatternnone, dots, grid, diagonal, hexagons, topographic, circuitnone
particleStylenone, bokeh, dust, stars, bubbles, fireflies, snow, confettinone
Typography effects:
FieldOptionsDefault
textStylesolid, outline, gradient, glow, shadowsolid
titleTextStylesolid, outline, gradient, glow, shadowsolid
textShadowStylenone, subtle, dramatic, glowsubtle
Frames and transitions:
FieldOptionsDefault
frameStylenone, neon, corners, scanlines, gradient_bordernone
transitionStylefade, slide, wipe, zoom, iris, flashfade
optionCardVariantstandard, glass, tilestandard
Celebrations and urgency:
FieldOptionsDefault
celebrationStylenone, pulse, confetti, burst, shimmer, flashpulse
urgencyStylenone, vignette, pulse, shake, border_pulsevignette
grainOverlaynone, subtle, medium, heavynone
For the full list of 42 effect fields and their ranges, see the API Reference.

​
List Themes

curl "https://app.quiz-quail.com/api/v1/themes?limit=20&includePublic=true" \
  -H "Authorization: Bearer YOUR_API_KEY"
By default, the list includes both your own themes and public themes. Set includePublic=false to see only your own. Supports cursor-based pagination.

​
Get a Theme

curl https://app.quiz-quail.com/api/v1/themes/theme-001 \
  -H "Authorization: Bearer YOUR_API_KEY"
You can retrieve any theme you own, or any public theme.

​
Update a Theme

curl -X PATCH https://app.quiz-quail.com/api/v1/themes/theme-001 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "primaryColor": "#DC2626",
    "fontFamily": "Oswald"
  }'
All fields are optional on update. You can only update themes you own.

​
Delete a Theme

curl -X DELETE https://app.quiz-quail.com/api/v1/themes/theme-001 \
  -H "Authorization: Bearer YOUR_API_KEY"
Returns 204 No Content. You can only delete themes you own.

​
Assign a Theme to a Quiz

Theme assignment is managed through the Quiz Quail dashboard. Open a quiz in the editor, select the theme panel, and choose the theme you want to apply. You can assign any theme you own or any public community theme.

​
Example: Create a Branded Theme

Create a theme matching your brand colors: 
curl -X POST https://app.quiz-quail.com/api/v1/themes \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "primaryColor": "#FF6600",
    "secondaryColor": "#FF8533",
    "backgroundColor": "#1A1A2E",
    "textColor": "#FFFFFF",
    "accentColor": "#FFD700",
    "fontFamily": "Poppins",
    "effects": {
      "backgroundStyle": "gradient_mesh",
      "particleStyle": "bokeh",
      "particleDensity": 0.2,
      "optionCardVariant": "glass",
      "celebrationStyle": "confetti"
    }
  }'
Once created, assign the theme to a quiz through the dashboard editor.