Skip to main content
PUT
/
api
/
v1
/
forms
/
{form_token}
/
theme
Update the form theme
curl --request PUT \
  --url https://formhug.ai/api/v1/forms/{form_token}/theme \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "header": {
    "images": [
      {
        "id": "<string>",
        "image_url": "<string>"
      }
    ],
    "image_keywords": "<string>"
  },
  "wallpaper": {
    "color": "<string>"
  },
  "primary_color": "<string>",
  "submit_button": {
    "style": {
      "background_color": "<string>",
      "color": "<string>"
    }
  },
  "typography": {
    "form_header": {
      "color": "<string>"
    },
    "field_label": {
      "color": "<string>"
    },
    "choice_style": {
      "color": "<string>"
    }
  },
  "general_button": {
    "color": "<string>",
    "border_color": "<string>"
  },
  "form_container": {
    "style": {
      "background_color": "<string>"
    }
  }
}
'
{
  "data": {
    "header": {
      "images": [
        {
          "url": "<string>",
          "id": "<string>"
        }
      ]
    },
    "wallpaper": {
      "color": "<string>"
    },
    "primary_color": "<string>",
    "submit_button": {
      "style": {
        "background_color": "<string>",
        "color": "<string>"
      }
    },
    "typography": {
      "form_header": {
        "color": "<string>"
      },
      "field_label": {
        "color": "<string>"
      },
      "choice_style": {
        "color": "<string>"
      }
    },
    "general_button": {
      "color": "<string>",
      "border_color": "<string>"
    },
    "form_container": {
      "style": {
        "background_color": "<string>"
      }
    }
  }
}

Documentation Index

Fetch the complete documentation index at: https://formhug.ai/docs/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

​
Authorization
string
header
required

Personal Access Token prefixed with fh_. Sent as Authorization: Bearer fh_xxx. The scope required by each endpoint is listed in that endpoint's description.

Path Parameters

​
form_token
string
required

Form token

Body

application/json

All fields optional; partial-merge semantics. Keys present in the body are written; keys absent are left unchanged. Explicit null clears that value. Header image(s) are set by providing either header.images (HTTPS URLs, with SSRF safety checks) or header.image_keywords (Unsplash search). Pass header.images: [] to remove all header images. A single-entry array configures a single header image; multiple entries configure a carousel.

primary_color is an alias for submit_button.style.background_color; the two fields share storage and reject conflicting values.

Palette derivation. When the header image actually changes — meaning the first image's attachment id differs from what was previously bound to the theme, or fresh bytes were downloaded — the server runs a palette derivation against the first image and applies the derived values (wallpaper.color, submit_button.style.background_color, submit_button.style.color, typography.field_label.color, typography.choice_style.color, general_button.color, form_container.style.background_color, plus the read-only dominant_color) to the theme.

Each derived value overwrites the theme's current value unless the same PUT request explicitly sets that field — in which case the user's value wins (even when that value is null). For carousel headers (multiple images), only the first image is used as the derivation source; reordering or swapping later carousel items without changing the first image does not retrigger derivation. Pure id-reuse where the first image's id is unchanged triggers no recompute. dominant_color is always overwritten on image change; it cannot be set directly via PUT.

The same derivation runs whether the new header image came from header.images[].image_url, header.image_keywords (Unsplash), or a switched-to existing attachment id — Unsplash photos are downloaded for analysis even though the served URL hotlinks the Unsplash CDN. dominant_color is always the locally-computed value from the downloaded bytes.

​
header
object
​
wallpaper
object
​
primary_color
string | null

Theme primary color. Alias for submit_button.style.background_color — reading either returns the same value, and writing to either updates the same underlying field. If both primary_color and submit_button.style.background_color are present in one request with different values, the request is rejected with 422. Equal values are accepted (idempotent).

​
submit_button
object
​
typography
object
​
general_button
object
​
form_container
object

Form container styling. Only accepted when the form layout is classic.

Response

Null clears form_container.style.background_color

​
data
object
required
Last modified on May 21, 2026