Themes
Manage survey design themes in your workspace
Workspace themes
Design themes let you define color schemes, fonts, backgrounds and button styles for surveys. Each theme is tied to a workspace and can be applied to multiple surveys at once.
Base URL for all requests in this section: /api/v3/service/workspace/{id}/themes, where {id} — is the workspace ID.
Download the markdown version of the "Workspace themes" section for use in ChatGPT / other LLMs:
AI Markdown
/static/api/themes.md
AI Markdown
List workspace themes GET /api/v3/service/workspace/{id}/themes
Returns a paginated list of design themes for the specified workspace.
Query parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
| page | integer | 1 | Page number |
| per_page | integer | 20 | Themes per page |
GET /api/v3/service/workspace/{id}/themes
curl -X GET "https://api.surveyninja.io/api/v3/service/workspace/1/themes?page=1&per_page=20" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Accept: application/json"Get theme GET /api/v3/service/workspace/{id}/themes/{theme_id}
Returns complete data for a specific theme, including all color, style fields and metadata.
Main response fields
| Field | Type | Description |
|---|---|---|
| id | integer | Theme ID |
| name | string | Theme name |
| header_color | string | Header color (HEX) |
| buttons_color | string | Button color (HEX) |
| bg_color | string | Background color (HEX) |
| widget_active_color | string | Active widget color (HEX) |
| base_font_id | integer | Font ID (see reference below) |
| base_font_title | string | Font name |
| sort | integer | Sort order |
| created_at | string | Created at (ISO 8601) |
| updated_at | string | Updated at (ISO 8601) |
GET /api/v3/service/workspace/{id}/themes/{theme_id}
curl -X GET "https://api.surveyninja.io/api/v3/service/workspace/1/themes/42" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Accept: application/json"Create theme POST /api/v3/service/workspace/{id}/themes
Creates a new theme in the workspace. The parameter quiz_id is required — the theme is created based on the settings of the specified survey. All other fields are optional and override values from the survey.
Request body (JSON)
| Parameter | Req. | Description |
|---|---|---|
| quiz_id | Yes | Survey UUID to base the theme on |
| name | No | Theme name |
| header_color | No | Header color (HEX) |
| buttons_color | No | Button color (HEX) |
| bg_color | No | Background color (HEX) |
| base_font_id | No | Font ID (see reference below) |
POST /api/v3/service/workspace/{id}/themes
curl -X POST "https://api.surveyninja.io/api/v3/service/workspace/1/themes" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "quiz_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "My Theme", "buttons_color": "#3B82F6", "bg_color": "#F9FAFB" }'Update theme POST /api/v3/service/workspace/{id}/themes/{theme_id}
Partial theme update — pass only the fields to change. All parameters are optional.
Request body parameters
| Parameter | Type | Description |
|---|---|---|
| name | string | Theme name |
| header_color | string | Header color (HEX) |
| buttons_color | string | Button color (HEX) |
| bg_color | string | Background color (HEX) |
| widget_active_color | string | Active widget color (HEX) |
| base_font_id | integer | Font ID (see reference) |
| buttons_type_id | integer | 1 — filled, 2 — outlined |
| buttons_radius | integer | Button border radius (px) |
| answer_options_radius | integer | Answer options border radius (px) |
| answer_border | boolean | Show border on answer options |
| background_type_id | integer | 1 — color/image, 2 — gradient |
| background_opacity | integer | Background opacity (0–100) |
| background_lightness | integer | Background image brightness |
| background_saturate | integer | Background image saturation |
| background_contrast | integer | Background image contrast |
| bg_gradient_start | string | Gradient start color (HEX) |
| bg_gradient_end | string | Gradient end color (HEX) |
| bg_gradient_vector | integer | Gradient direction (degrees, 0–360) |
| bg_image_file_id | integer | Background image file ID |
| background_position_id | integer | Background position (see reference) |
| background_placement_id | integer | Background placement: 1 stretch, 2 drawin, 3 cover |
| bg_logo_file_id | integer | Background logo file ID |
| bg_logo_position_id | integer | Background logo position (see reference) |
| bg_logo_size_id | integer | Background logo size |
POST /api/v3/service/workspace/{id}/themes/{theme_id}
curl -X POST "https://api.surveyninja.io/api/v3/service/workspace/1/themes/42" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Updated theme", "buttons_color": "#10B981", "buttons_radius": 8 }'Copy theme POST /api/v3/service/workspace/{id}/themes/{theme_id}/copy
Creates a full copy of the theme in the same workspace. No request body required. Response is the new theme object.
POST /api/v3/service/workspace/{id}/themes/{theme_id}/copy
curl -X POST "https://api.surveyninja.io/api/v3/service/workspace/1/themes/42/copy" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Accept: application/json"Delete theme DELETE /api/v3/service/workspace/{id}/themes/{theme_id}
Deletes a workspace theme. All surveys using this theme are automatically switched to the default theme.
DELETE /api/v3/service/workspace/{id}/themes/{theme_id}
curl -X DELETE "https://api.surveyninja.io/api/v3/service/workspace/1/themes/42" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Accept: application/json"Reference tables
Fonts (base_font_id)
| ID | Font | ID | Font |
|---|---|---|---|
| 1 | Native (system) | 23 | Nunito |
| 2 | Roboto | 24 | Oswald |
| 3 | Open Sans | 25 | Playfair Display |
| 4 | Lato | 26 | PT Sans |
| 5 | Montserrat | 27 | PT Serif |
| 6 | Raleway | 28 | Rubik |
| 7 | Source Sans Pro | 29 | Ubuntu |
| 8 | Roboto Condensed | 30 | Manrope |
| 9 | Roboto Mono | 31 | Inter |
| 10 | Roboto Slab | 32 | Mulish |
| 11 | Noto Sans | 33 | Poppins |
| 12 | Noto Serif | 34 | Quicksand |
| 13 | Merriweather | 35 | Comfortaa |
| 14 | Libre Baskerville | 36 | Exo 2 |
| 15 | Lobster | 37 | Fira Sans |
| 16 | Pacifico | 38 | Cabin |
| 17 | Dancing Script | 39 | Nunito Sans |
| 18 | Caveat | 40 | Jost |
| 19 | Permanent Marker | 41 | Unbounded |
| 20 | Indie Flower | 42 | Wix Madefor Display |
| 21 | Abril Fatface | 43 | Onest |
| 22 | Fjalla One | 44 | Golos Text |
Button type (buttons_type_id)
| ID | Style |
|---|---|
| 1 | background (filled) |
| 2 | border (outlined) |
Background type (background_type_id)
| ID | Type |
|---|---|
| 1 | color_image (color or image) |
| 2 | gradient (gradient) |
Background placement (background_placement_id)
| ID | Mode |
|---|---|
| 1 | stretch |
| 2 | drawin (original size) |
| 3 | cover |
Background position (background_position_id)
| ID | Position |
|---|---|
| 1 | center center |
| 2 | left center |
| 3 | right center |
| 4 | center top |
| 5 | center bottom |
| 6 | left top |
| 7 | right top |
| 8 | left bottom |
| 9 | right bottom |