> ## Documentation Index
> Fetch the complete documentation index at: https://formbricks.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Archive a creative

> Sets a creative aside: it never shows, it no longer blocks changes to its survey, it leaves the default list, and it becomes read-only until restored. Its status and counts are kept while it is archived; restoring it brings it back as a draft. Archiving an archived creative changes nothing. Read/write access to its workspace; an unknown or inaccessible `creativeId` answers **403**. Archiving the last creative that opens a live app survey with no actions of its own succeeds; that survey then shows nowhere until a creative or an action opens it again.



## OpenAPI

````yaml /api-v3-reference/openapi.yml post /api/v3/creatives/{creativeId}/archive
openapi: 3.1.1
info:
  title: Formbricks API v3
  description: >
    **Surveys**: **GET /api/v3/surveys**, **POST /api/v3/surveys**, **POST
    /api/v3/surveys/generate**, **POST /api/v3/surveys/validate**, **GET
    /api/v3/surveys/{surveyId}**, **PATCH /api/v3/surveys/{surveyId}**, **PATCH
    /api/v3/surveys/{surveyId}/blocks**, **PUT
    /api/v3/surveys/{surveyId}/blocks/order**, and **DELETE
    /api/v3/surveys/{surveyId}**.


    **Custom CSS**: survey CSS through `customCss` on **POST /api/v3/surveys**,
    **GET** and **PATCH /api/v3/surveys/{surveyId}**, workspace CSS through
    **GET** and **PATCH /api/v3/workspaces/{workspaceId}/custom-css**, and
    previews through `operation: customCss` on **POST
    /api/v3/surveys/validate**. Writes take and reads return source only; the
    server compiles it, returns removed constructs as top-level `warnings`, and
    never accepts compiled output.


    **Responses**: **GET /api/v3/responses**, **GET /api/v3/responses/count**,
    **POST /api/v3/responses/validate**, **POST
    /api/v3/responses/batch-delete**, **POST /api/v3/responses/batch-outcome**,
    **GET /api/v3/responses/{responseId}**, **POST /api/v3/responses**, **PATCH
    /api/v3/responses/{responseId}**, and **DELETE
    /api/v3/responses/{responseId}**.


    **Creatives**: **GET /api/v3/creatives**, **POST /api/v3/creatives**,
    **GET**, **PATCH** and **DELETE /api/v3/creatives/{creativeId}**, **POST
    /api/v3/creatives/{creativeId}/archive**, **/restore** and **/duplicate**,
    **GET /api/v3/creatives/{creativeId}/stats**, and **POST
    /api/v3/creatives/pause**, which pauses every creative that opens a survey.
    A creative is a feedback button or a banner the web SDK renders on the
    customer's site; pressing it opens its Destination, a survey or a link.
    Writes set the author's `status`; reads add the derived `displayStatus`;
    `stats` returns its daily Impressions and Clicks.


    Creatives needs a self-hosted license that includes it; Formbricks Cloud
    does not offer it. With one, every operation is available. Without one, a
    workspace that still has creatives is in **wind-down**: its creatives are no
    longer shown on sites, and they can only be listed, read (stats included),
    paused (a PATCH that sets nothing but `status`, or **POST
    /api/v3/creatives/pause**), closed (the same PATCH) or deleted. A workspace
    with no creatives has no access at all. Anything not allowed answers **403**
    `creatives_not_entitled`.


    **Workflows extension**: **GET /api/v3/workflows**, **POST
    /api/v3/workflows**, **GET /api/v3/workflows/{workflowId}**, **PATCH
    /api/v3/workflows/{workflowId}**, **DELETE /api/v3/workflows/{workflowId}**,
    **POST /api/v3/workflows/{workflowId}/duplicate**, **POST
    /api/v3/workflows/{workflowId}/enable**, **POST
    /api/v3/workflows/{workflowId}/disable**, **POST
    /api/v3/workflows/{workflowId}/archive**, **POST
    /api/v3/workflows/{workflowId}/unarchive**, **POST
    /api/v3/workflows/{workflowId}/test**, **GET /api/v3/workflows/runs**, and
    **GET /api/v3/workflows/runs/{runId}**.


    **Charts and dashboards**: charts on a Feedback Dataset (**GET**, **POST
    /api/v3/charts**; **GET**, **PATCH**, **DELETE /api/v3/charts/{chartId}**;
    **POST /api/v3/charts/{chartId}/duplicate**), their numbers (**GET
    /api/v3/charts/{chartId}/data**, **POST /api/v3/charts/preview**), the field
    catalog (**GET /api/v3/charts/fields**, **GET
    /api/v3/charts/fields/{field}/values**), and dashboards (**GET**, **POST
    /api/v3/dashboards**; **GET**, **PATCH**, **PUT**, **DELETE
    /api/v3/dashboards/{dashboardId}**; **POST
    /api/v3/dashboards/{dashboardId}/duplicate**; **POST
    /api/v3/dashboards/{dashboardId}/widgets**; **GET**, **PATCH**, **DELETE
    /api/v3/dashboards/{dashboardId}/widgets/{widgetId}**; a widget's numbers
    through its dashboard, **GET
    /api/v3/dashboards/{dashboardId}/charts/{chartId}/data**; a dashboard
    filter's values, **GET
    /api/v3/dashboards/{dashboardId}/filters/{filterId}/values**; the
    embedded-data fields its filters can use, **GET
    /api/v3/dashboards/{dashboardId}/filter-fields**).

    - **Field catalog.** A chart query names fields exactly as `GET
    /api/v3/charts/fields` lists
      them; the validator refuses anything else, and Cube options (`timezone`, `segments`, `ungrouped`,
      …), with **422** naming each problem. Counts, filter depth, `limit` and `offset` are bounded.
    - **Date ranges.** A preset from the catalog's `datePresets`, `all-time`, or
    two ISO dates, both
      inclusive, read in the organization's time zone. On the data operations a requested range
      replaces the chart's own range on `collectedAt`, the way a dashboard's date filter does.
    - **Dashboard filters.** A person filters a dashboard by any dimension of
    its charts' datasets or
      embedded-data field, up to 10 at once: each `filter[<id>]=<operator>:<field>`, with its values
      in `picks[<id>]`, is ANDed onto every chart's saved query on the dashboard-bound operations,
      never replacing a saved rule. The dashboard keeps no list of them.
    - **Data needs the dataset.** Reading a chart's rows, previewing one and
    looking up field values
      need read access to its Feedback Dataset as well as the workspace. They share one budget of
      **600 per minute** per user or key, sized for dashboards that load one query per widget, and at
      most **20 run at once** (429 with `Retry-After: 1` past that).
    - **Plan.** Every operation answers **403 `dashboards_plan_required`** for
    an organization without
      the Dashboards feature, after authorization.
    - **Shared charts.** A chart can sit on several dashboards; each chart says
    which in `dashboards`.
      Editing it changes all of them — duplicate it and repoint one dashboard's widget to change it
      there only. A chart still on a dashboard cannot be deleted: **409 `chart_in_use`** lists them in
      `details.dashboards`.
    - **Grid.** Widgets sit on a 12-column grid in whole units (`1 ≤ w ≤ 12`, `x
    + w ≤ 12`,
      `1 ≤ h ≤ 8`, `0 ≤ y ≤ 1000`). Gaps are allowed, overlaps answer **422** naming the widget, and a
      chart appears at most once per dashboard (**409**). A widget added without a layout takes the
      first open slot at its chart type's default size.
    - **Stale-check.** `PUT /api/v3/dashboards/{dashboardId}` saves the name and
    every widget at once
      and removes widgets left out. Send the `updatedAt` you read: if the dashboard changed since,
      nothing is saved and **409** carries `expectedUpdatedAt` and `currentUpdatedAt` in `details`.
      Every widget change moves `updatedAt`.


    Authenticate all management endpoints with **session cookie** or
    **`x-api-key`** (management key with access to the workspace).


    **Spec location:** source of truth is the multi-file tree at
    `docs/api-v3-reference/src/` (root `openapi.yml` plus one file per path and
    component); `docs/api-v3-reference/openapi.yml` is the generated single-file
    bundle (alongside v2 at `docs/api-v2-reference/openapi.yml`).


    **workspaceId**

    `workspaceId` is the canonical container identifier for this API. It is a
    **required query parameter on collection read endpoints** (`GET
    /api/v3/surveys`, `GET /api/v3/action-classes`, `GET
    /api/v3/contact-attribute-keys`, `GET /api/v3/contacts`, `GET
    /api/v3/segments`) because those operate within a workspace. **`POST
    /api/v3/surveys` instead requires `workspaceId` in the request body**, not
    as a query parameter. Single-resource endpoints (`GET`/`PATCH`/`DELETE
    /api/v3/surveys/{surveyId}`) locate the resource by its globally-unique id
    and resolve the workspace from it, so they do **not** accept a `workspaceId`
    query parameter — sending one returns **400** with an `invalid_params` entry
    naming the key itself (`name: "workspaceId"`, `reason: "Unsupported field
    'workspaceId'"`), rather than one naming the body.


    **Auth**

    Authenticate with either a session cookie or **`x-api-key`**. In dual-auth
    mode, V3 checks the API key first when the header is present, otherwise it
    uses the session path. Unauthenticated callers get **401** before query
    validation.


    **Pagination**

    Cursor-based pagination with **limit** + opaque **cursor** token. Responses
    return `meta.nextCursor`; pass that value back as `cursor` to fetch the next
    page. Survey, contact and segment list responses also include
    `meta.totalCount`, the total number of items matching the current filters
    across all pages (`null` when `includeTotalCount=false`). The
    contact-attribute-key and workflow lists report it only when asked with
    `includeTotalCount=true`. There is no `offset` in this contract.

    The page-size **maximum is 250** for responses, surveys, action classes,
    contact attribute keys, contacts and segments; only the *default* varies by
    resource (20 for surveys, 50 for the workspace reference lists). **The
    workflows and workflow-run lists remain at 100** — their bound lives in the
    `packages/workflows` contracts and moves with that package, so each
    documents the value it actually enforces. A `limit` above an endpoint's
    maximum is rejected with **400** rather than silently reduced, consistent
    with v3 rejecting unrecognized query parameters instead of ignoring them.
    Callers should not infer the end of a collection from a page shorter than
    `limit`; `meta.nextCursor` of `null` is the only end-of-collection signal.
    Note that array-valued *input* bounds are a separate concern and stay at 100
    — `filter[id][in]` and the batch-delete id list are bounded by write and
    payload risk, not by page cost.


    **Strictness**

    A query parameter that an operation does not declare returns **400**, with
    the offending key reported in `invalid_params[].name` — including on
    operations that declare no query parameters at all. Unknown parameters are
    rejected rather than ignored on purpose: a silently-dropped filter returns
    *more* data than the caller believes they asked for, and a typo in a filter
    name is indistinguishable from no filter at all. The same applies to request
    bodies, where unsupported fields are rejected instead of stripped.

    Unrecognized **headers** are tolerated, as gateways and proxies legitimately
    add them; strictness is about parameters and body fields, not transport
    metadata.

    This is the rule for the surveys, responses, tags and workspace
    reference-list operations. The workflows family does not enforce it today,
    so treat parameter strictness there as unspecified rather than guaranteed.

    **Request limits**

    A request body may be at most **2 MB**; a larger one is refused with **413**
    before it is read. Inside a body, **no array may hold more than 1 000 items,
    and all arrays together may hold at most 50 000 elements**, at any depth — a
    body that exceeds either bound is refused with **400** and a single
    `invalid_params` entry naming the offending array, before any field is
    validated. The same holds for nesting: a body may nest at most **256**
    levels of objects and arrays, counted from the root, and a deeper one is
    refused the same way, naming where it went too deep. Fields with a tighter
    bound document it as `maxItems` on the field (a survey's `blocks`,
    `endings`, `variables`, `languages`, `hiddenFields.fieldIds` and
    `distribution.triggers` since 0.2.0). A 400 or 422 lists at most **50**
    `invalid_params` entries; when there are more, the last entry says how many
    were left out. Since 0.2.0.

    **Filtering**

    Filters use explicit operator-style query parameters under the
    **`filter[...]` family**. The survey list supports `filter[name][contains]`,
    `filter[status][in]`, and `filter[type][in]`. The workflow list supports
    `filter[name][contains]` and `filter[status][in]`; the workflow run list
    supports `filter[status][in]` and `filter[isDryRun][eq]`. Resource-scoping
    identifiers (`workspaceId`, `workflowId`, `responseId`) stay plain query
    parameters. Multi-value filters use repeated keys or comma-separated values
    (e.g. `filter[status][in]=draft&filter[status][in]=inProgress` or
    `filter[status][in]=draft,inProgress`). Sorting remains a flat `sortBy`
    query parameter.


    **Responses**

    The response resource is **self-describing**. Answers come back as a typed
    `answers[]` array in which each entry carries the element's id, label, type
    and value, rather than as a map keyed by element id — so a consumer holding
    only a response can read it without fetching the survey and joining. Hidden
    fields, survey variables and auto-captured context are one `embeddedData[]`
    collection rather than three parallel concepts, each entry declaring a
    `kind` and a `type`. Data whose element has since been deleted is reported
    in `unresolved[]` instead of being dropped silently. Labels are resolved at
    read time against the current survey definition, and the `resolution` object
    discloses that policy along with the survey's `updatedAt` so a consumer can
    detect wording drift.

    Writes take answers in the **stored map form** (`data`) while reads return
    the typed array. Resolving ids into labelled answers is unambiguous; the
    reverse would mean matching caller-supplied labels back onto option ids, so
    the write side keeps the stored shape. To stop that costing
    round-trippability, the **detailed read returns `data` unchanged** — so a
    single-response read can be edited and sent back as `PATCH { "data": … }`,
    and the typed `answers[]` array is an addition rather than a replacement.


    One case where that round trip does not close: a write bound applies to
    `data` on the way in (`ResponseDataMapInput`) and none applies to the stored
    map, because v1 and v2 wrote it without one. A response carrying more answer
    keys than the write accepts therefore cannot be corrected through `PATCH` at
    all — the whole map is rejected, and sending a smaller one is not a
    workaround, because `data` is replaced wholesale and every key left out is
    deleted. Correct those through the v1/v2 management API or the dashboard.
    This is reachable only on surveys with more elements than the bound allows.

    Embedded Data is the exception, and it is symmetric rather than
    round-tripped: hidden fields and variables are read and written through
    `embeddedData`, addressed by **name** in both directions. No raw map of them
    is echoed, because a name is already what a write accepts — publishing the
    storage keys underneath (a variable's is its cuid) would expose a layout the
    caller has no use for. `data` therefore carries element answers only.

    Of those two, only `data` carries no `readOnly`, because it is the same map
    on the way in and on the way out. Embedded Data is writable through the
    **request's own** `embeddedData` map, not through the response field of that
    name — so `embeddedData[]`, like every other derived view on the resource,
    is marked `readOnly`, per its meaning of server-managed. `ResponseResource`
    lists them all. The list view omits `data`, since a bulk reader is not
    editing. `POST /api/v3/responses/validate` exists so a caller can see what a
    map would produce, and what a write would do, before committing to it.

    `createdAt` and `updatedAt` are **server-owned** on this resource: they
    cannot be supplied on create or changed by a patch. Response metering counts
    rows by `(surveyId, createdAt)`, and a client-chosen `createdAt` also lets
    rows be inserted into the middle of another consumer's already-paginated
    stream. Backdating stays available on v2 until a dedicated import path
    exists. The respondent's IP address and the `contactAttributes` snapshot
    that v1/v2 expose are not part of this resource in any view; that snapshot
    is copied from the contact at submission time and never refreshed, so it is
    stale PII by construction.

    Response filtering is allow-listed and index-backed:
    `filter[createdAt][gte|gt|lte|lt]` (at most one lower and one upper bound —
    `gte` xor `gt`, `lte` xor `lt`), `filter[finished][eq]`,
    `filter[language][in]` and `filter[id][in]`. `filter[finished][eq]` and
    `filter[language][in]` require `surveyId` or `contactId` as well, because
    both are heap residuals bounded only by an anchored index range. Per-answer,
    hidden-field, submission-metadata, contact-attribute, quota and tag filters
    are **not** offered; each is a JSON path or an unindexed join on the largest
    table in the product. The in-app dashboard does offer them, so this API is
    knowingly behind the dashboard here — closing the gap requires index work
    and is tracked separately rather than quietly omitted.

    `GET /api/v3/responses/count` answers "how many match?" directly. The list
    endpoint's `meta.totalCount` covers a caller that is already paging and is
    **opt-in** via `includeTotalCount` (default `false`, unlike the survey list)
    because responses are the highest-cardinality table in the product. Both
    response counts are **capped at 10 000** and carry an exactness flag —
    `meta.totalCountRelation` on the list, `data.relation` on `/count` — reading
    `eq` when the figure is exact and `gte` when the cap was reached and it is a
    lower bound. An exact count over this table grows superlinearly with the
    data while a capped one stays flat, so an uncapped total would be the only
    part of a response whose cost is unbounded. `/count` accepts
    `precision=exact` for the cases that genuinely need a precise figure,
    documented as the deliberate slow path. The survey list's `totalCount` stays
    exact and uncapped: surveys are low-cardinality and that count has a
    covering index built for it.

    Bulk deletion is `POST /api/v3/responses/batch-delete`, a custom method
    rather than a collection-level `DELETE`, so a call that loses its filters
    cannot degrade into erasing everything in scope. It scope-filters rather
    than rejecting: foreign and already-deleted ids are ignored and the call
    reports how many rows it removed, which keeps it both leak-free and safe to
    retry.

    **Security**

    Missing/forbidden workspace returns **403** with a generic message (not
    **404**) so resource existence is not leaked. Workflow and workflow-run
    detail endpoints also return **403** for unknown IDs or inaccessible IDs to
    avoid IDOR leaks. List responses use `private, no-store`.


    **AI survey creation**

    `POST /api/v3/surveys/generate` returns a draft `POST /api/v3/surveys`
    payload plus validation metadata. It does not create a survey. It generates
    survey content for both `link` and `app` surveys; for `app` it seeds a
    default `distribution` (display once, no triggers, no targeting) that you
    finish configuring before publishing.

    Prompt text is sent to the configured AI provider for generation, but it is
    not stored by this endpoint, not logged by default, and not included in
    audit data.


    **Feedback Records** `/api/v3/feedbackRecords` is served by the **API
    gateway** (Envoy on Formbricks Cloud, Traefik in the one-click Docker
    install), which authorizes each call against the dataset and forwards it to
    the feedback store — not by the application routes that serve the rest of
    v3. Three consequences: the payload is the store's own, so members and
    filters are **`snake_case`** (`tenant_id`, `value_text`) rather than v3's
    camelCase; the dataset is named **`tenant_id`** on the wire and is required
    on every collection operation (it is the feedback dataset id, which the MCP
    `list_feedback_datasets` tool reports as `dataset_id`); and errors come in
    two shapes — gateway refusals (**400**, **401**, **403**, **413**, **503**)
    are `text/plain`, while the store's own problems are
    `application/problem+json` with a stable `code`. These eight operations are
    the whole of the gateway-served surface; any other path it receives under
    the prefix answers **400**. Authenticate with **`x-api-key`**: the key needs
    a permission on a workspace the dataset is assigned to — `read` to list, get
    and search, `write` to create and update, `manage` to delete — and may
    update or delete only in a dataset assigned to exactly one workspace.

    **OpenAPI**

    This spec is **not** produced by `pnpm generate-api-specs` (that script only
    builds v2 → `docs/api-v2-reference/openapi.yml`). When the route contract
    changes, edit the files under `docs/api-v3-reference/src/`, then run `pnpm
    api:v3:bundle` to regenerate the committed single-file bundle. `pnpm
    api:v3:lint` lints the source tree; `pnpm api:v3:check` (CI) fails when the
    bundle is stale.


    **Workflows Scope 1**

    Workflows are a follow-up extension of the existing v3 Survey API work. The
    Survey API establishes API-first survey authoring; Workflows build on that
    same v3 style to automate actions around survey responses through
    workspace-scoped JSON definitions. Scope 1 models the existing Follow-ups
    capability as workflows: one `response.completed` trigger with an optional
    `endingCardIds` filter, and `send_email` actions with Follow-up email field
    parity. The definition and run shapes mirror the shared Zod schemas in
    `packages/workflows` (ENG-1100), which are the implementation source of
    truth for this contract.


    Workflows use `draft`, `enabled`, and `disabled` lifecycle states plus an
    `archived` soft-delete state. Status only changes through the lifecycle
    endpoints (`enable`, `disable`, `archive`, `unarchive`); it is not writable
    via `POST` or `PATCH`. Enabling validates that the definition is executable
    and snapshots an immutable workflow version; runs reference that snapshot
    via `workflowVersionId`. `POST .../test` is a dry run: it validates the
    definition and resolves the trigger's references synchronously, creating no
    run and sending no email, and returns `{ workflowId, ok, problems }`
    directly. Real runs execute asynchronously and are polled via `GET
    /api/v3/workflows/runs/{runId}`.


    **Overview migration note**

    The v3-backed survey overview page intentionally removes actions that are
    not yet exposed by this contract: `Created by` filtering, `Duplicate`,
    `Copy...`, `Preview`, and `Copy link`.


    **Next steps (out of scope for this spec)**

    Optional ETag/304, field selection, translation-specific writes, and survey
    version history.
  version: 0.2.0
  x-implementation-notes:
    route: apps/web/app/api/v3/surveys/route.ts
    generate-route: apps/web/app/api/v3/surveys/generate/route.ts
    query-parser: apps/web/app/api/v3/surveys/parse-v3-surveys-list-query.ts
    auth: apps/web/app/api/v3/lib/auth.ts
    workspace-resolution: apps/web/app/api/v3/lib/workspace-context.ts
    workflow-contract-ticket: ENG-1101
    workflow-shared-schemas: packages/workflows/src/types (feat/workflows-types)
    workflow-prisma-schema: packages/database/schema/workflows.prisma (feat/workflows-prisma-schema)
    openapi-generated: false
    spec-source: docs/api-v3-reference/src (regenerate bundle with `pnpm api:v3:bundle`)
    responses-contract-ticket: ENG-2868
    responses-rfc: v3 Responses API RFC sections 2b (resource) and 2c (endpoints)
    responses-stored-shape: packages/types/responses.ts (ZResponse, ZResponseData, ZResponseInput)
    responses-prisma-model: packages/database/schema/main.prisma (model Response)
    pagination-model: cursor
    cursor-pagination: supported
servers:
  - url: https://app.formbricks.com
    description: >-
      Formbricks Cloud. Paths in this spec already include the `/api/v3` prefix;
      self-hosted instances substitute their own origin.
security:
  - apiKeyAuth: []
  - bearerAuth: []
  - sessionAuth: []
paths:
  /api/v3/creatives/{creativeId}/archive:
    post:
      tags:
        - V3 Creatives
      summary: Archive a creative
      description: >-
        Sets a creative aside: it never shows, it no longer blocks changes to
        its survey, it leaves the default list, and it becomes read-only until
        restored. Its status and counts are kept while it is archived; restoring
        it brings it back as a draft. Archiving an archived creative changes
        nothing. Read/write access to its workspace; an unknown or inaccessible
        `creativeId` answers **403**. Archiving the last creative that opens a
        live app survey with no actions of its own succeeds; that survey then
        shows nowhere until a creative or an action opens it again.
      operationId: archiveCreativeV3
      parameters:
        - $ref: '#/components/parameters/CreativeIdPath'
      responses:
        '200':
          description: Creative archived
          headers:
            X-Request-Id:
              schema:
                type: string
              description: Request correlation ID
            Cache-Control:
              schema:
                type: string
              example: private, no-store
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    $ref: '#/components/schemas/CreativeResource'
        '400':
          $ref: '#/components/responses/V3BadRequest'
        '401':
          $ref: '#/components/responses/V3Unauthorized'
        '403':
          $ref: '#/components/responses/V3CreativesForbidden'
        '429':
          $ref: '#/components/responses/V3TooManyRequests'
        '500':
          $ref: '#/components/responses/V3InternalServerError'
      security:
        - sessionAuth: []
        - apiKeyAuth: []
        - bearerAuth: []
components:
  parameters:
    CreativeIdPath:
      in: path
      name: creativeId
      required: true
      schema:
        type: string
        format: cuid2
      description: Creative identifier.
  schemas:
    CreativeResource:
      oneOf:
        - $ref: '#/components/schemas/FeedbackButtonCreative'
        - $ref: '#/components/schemas/BannerCreative'
      discriminator:
        propertyName: type
        mapping:
          feedbackButton: '#/components/schemas/FeedbackButtonCreative'
          banner: '#/components/schemas/BannerCreative'
      description: >
        A creative: a page element the web SDK renders on the customer's site
        next to surveys, with its own content, look, display rules and schedule.
        `type` selects the `content` and `styling` shape: switch on it.


        The writable groups are `name`, `status`, `defaultLanguage` with
        `languages`, `autoSelectLanguage`, `content`, `styling`, `destination`,
        `distribution` and `schedule`; a `PATCH` replaces each group it sends as
        a whole. `displayStatus`, `displayStatusReason`, `warnings`, the
        timestamps, `creator` and `destination.opensAs` are read-only.
    FeedbackButtonCreative:
      allOf:
        - $ref: '#/components/schemas/CreativeResourceBase'
        - type: object
          required:
            - content
            - styling
          properties:
            type:
              type: string
              enum:
                - feedbackButton
            content:
              $ref: '#/components/schemas/FeedbackButtonContent'
            styling:
              $ref: '#/components/schemas/FeedbackButtonStyling'
      unevaluatedProperties: false
      description: A feedback button.
    BannerCreative:
      allOf:
        - $ref: '#/components/schemas/CreativeResourceBase'
        - type: object
          required:
            - content
            - styling
          properties:
            type:
              type: string
              enum:
                - banner
            content:
              $ref: '#/components/schemas/BannerContent'
            styling:
              $ref: '#/components/schemas/BannerStyling'
      unevaluatedProperties: false
      description: A banner.
    Problem:
      type: object
      description: >-
        RFC 9457 Problem Details for HTTP APIs (`application/problem+json`).
        Responses typically include a machine-readable `code` field alongside
        `title`, `status`, `detail`, and `requestId`.


        Branch on `code`, not on `detail` or `title`: `code` is stable and
        locale-independent, whereas `detail` is prose that may be reworded. No
        problem sets `type`, so per RFC 9457 §4.2.1 `title` is always the HTTP
        reason phrase for `status` and carries no information of its own.


        Member naming is frozen as published, mixed conventions included
        (`requestId` alongside `invalid_params` and `details.resource_type`):
        renaming any of them would break every client that reads them.
      required:
        - title
        - status
        - detail
        - requestId
      properties:
        type:
          type: string
          format: uri
        title:
          type: string
        status:
          type: integer
        detail:
          type: string
        instance:
          type: string
        code:
          type: string
          enum:
            - ai_features_not_enabled
            - ai_generated_payload_invalid
            - ai_instance_not_configured
            - ai_output_too_long
            - ai_provider_auth_failed
            - ai_smart_tools_disabled
            - bad_gateway
            - bad_request
            - chart_in_use
            - conflict
            - creatives_not_entitled
            - custom_css_plan_required
            - dashboards_plan_required
            - forbidden
            - internal_server_error
            - invalid_workflow_state
            - not_authenticated
            - not_found
            - payload_too_large
            - projection_pending
            - service_unavailable
            - stored_survey_invalid
            - survey_has_linked_creatives
            - survey_not_workspace_visible
            - too_many_requests
            - unprocessable_content
            - visibility_blocked_by_connections
            - visibility_change_not_allowed
            - visibility_not_enabled
            - workflow_not_executable
            - workspace_survey_limit_reached
        requestId:
          type: string
        details:
          type: object
        invalid_params:
          type: array
          items:
            $ref: '#/components/schemas/InvalidParam'
    CreativeResourceBase:
      type: object
      description: >-
        Fields every creative carries, whatever its type. `type` selects the
        `content` and `styling` shape; see `CreativeResource`.
      required:
        - id
        - workspaceId
        - name
        - type
        - status
        - displayStatus
        - displayStatusReason
        - createdAt
        - updatedAt
        - publishedAt
        - archivedAt
        - creator
        - defaultLanguage
        - languages
        - autoSelectLanguage
        - destination
        - distribution
        - schedule
        - warnings
      properties:
        id:
          type: string
          format: cuid2
        workspaceId:
          type: string
          format: cuid2
        name:
          type: string
          description: >-
            Internal name, shown to authors only. Never shown or announced to
            visitors.
        type:
          $ref: '#/components/schemas/CreativeType'
        status:
          $ref: '#/components/schemas/CreativeStatus'
        displayStatus:
          $ref: '#/components/schemas/CreativeDisplayStatus'
          readOnly: true
        displayStatusReason:
          $ref: '#/components/schemas/CreativeDisplayStatusReason'
          readOnly: true
        createdAt:
          type: string
          format: date-time
          readOnly: true
        updatedAt:
          type: string
          format: date-time
          readOnly: true
        publishedAt:
          type:
            - string
            - 'null'
          format: date-time
          readOnly: true
          description: >-
            When the creative was first published; `null` while it has never
            been.
        archivedAt:
          type:
            - string
            - 'null'
          format: date-time
          readOnly: true
          description: When the creative was archived; `null` unless it is archived.
        creator:
          type:
            - object
            - 'null'
          readOnly: true
          description: >-
            The user who created the creative, or `null` for one created with an
            API key.
          required:
            - name
          properties:
            name:
              type: string
          additionalProperties: false
        defaultLanguage:
          $ref: '#/components/schemas/LocaleCode'
        languages:
          type: array
          items:
            $ref: '#/components/schemas/CreativeLanguage'
          description: Every language the texts are written in, the default first.
        autoSelectLanguage:
          type:
            - boolean
            - 'null'
          description: >-
            Show the texts in the visitor's browser language when the site sets
            none with `setLanguage` and it matches the default or an enabled
            language; otherwise the default language is used. `null` (never
            chosen) and `false` both mean off.
        destination:
          anyOf:
            - $ref: '#/components/schemas/CreativeDestination'
            - type: 'null'
          description: >-
            What pressing the creative opens, or `null` when it opens nothing (a
            banner without a button, or a draft whose Destination isn't chosen
            yet).
        distribution:
          $ref: '#/components/schemas/CreativeDistribution'
        schedule:
          $ref: '#/components/schemas/CreativeSchedule'
        warnings:
          type: array
          readOnly: true
          items:
            $ref: '#/components/schemas/CreativeWarning'
    FeedbackButtonContent:
      type: object
      description: What a feedback button shows.
      required:
        - label
        - icon
      properties:
        label:
          $ref: '#/components/schemas/CreativeText'
          description: >-
            The button's text. Publishing needs a non-empty default-language
            label.
        icon:
          type:
            - string
            - 'null'
          enum:
            - messageSquare
            - messageCircle
            - megaphone
            - sparkles
            - null
          description: An icon before the label, or `null` for none.
      additionalProperties: false
    FeedbackButtonStyling:
      type: object
      description: >-
        A feedback button's position and custom styles. The position applies
        whether or not custom styles are on.
      required:
        - position
        - theme
      properties:
        position:
          type: object
          required:
            - desktop
            - phone
          properties:
            desktop:
              $ref: '#/components/schemas/FeedbackButtonPlacement'
            phone:
              anyOf:
                - $ref: '#/components/schemas/FeedbackButtonPlacement'
                - type: 'null'
              description: >-
                Applies below 768 px viewport width. `null` uses the desktop
                position.
          additionalProperties: false
        theme:
          $ref: '#/components/schemas/FeedbackButtonTheme'
      additionalProperties: false
      example:
        position:
          desktop:
            edge: right
            offset: 50
          phone: null
        theme:
          customStyles: false
          backgroundColor: null
          textColor: null
          borderColor: null
          borderRadius: null
          fontWeight: null
          fontSize:
            desktop: null
            phone: null
          paddingX:
            desktop: null
            phone: null
          paddingY:
            desktop: null
            phone: null
    BannerContent:
      type: object
      description: What a banner shows.
      required:
        - message
        - button
        - dismissible
        - accessibleName
      properties:
        message:
          $ref: '#/components/schemas/CreativeRichText'
          description: >-
            The banner text: bold, italic, underline and links; no images.
            Publishing needs a non-empty default-language message.
        button:
          anyOf:
            - $ref: '#/components/schemas/BannerButton'
            - type: 'null'
          description: >-
            An optional button. A banner with a button needs a `destination` to
            publish; a banner without one is a notice only and can't have a
            `destination`.
        dismissible:
          type: boolean
          description: >-
            Whether visitors can close the banner. A dismissed banner stays
            closed for the rest of the visit, in that browser tab; a new tab
            shows it again.
        accessibleName:
          anyOf:
            - $ref: '#/components/schemas/CreativeText'
            - type: 'null'
          description: >-
            The name screen readers announce for the banner region. `null` uses
            "Site notice" in the visitor's language. The creative's `name` is
            never announced.
      additionalProperties: false
    BannerStyling:
      type: object
      description: >-
        A banner's position and custom styles. The position applies whether or
        not custom styles are on.
      required:
        - position
        - theme
      properties:
        position:
          type: object
          required:
            - desktop
            - phone
          properties:
            desktop:
              $ref: '#/components/schemas/BannerPlacement'
            phone:
              anyOf:
                - $ref: '#/components/schemas/BannerPlacement'
                - type: 'null'
              description: >-
                Applies below 768 px viewport width. `null` uses the desktop
                position.
          additionalProperties: false
        theme:
          $ref: '#/components/schemas/BannerTheme'
      additionalProperties: false
      example:
        position:
          desktop:
            placement: top
            layout: inPage
          phone: null
        theme:
          customStyles: false
          backgroundColor: null
          textColor: null
          borderColor: null
          fontWeight: null
          fontSize:
            desktop: null
            phone: null
          paddingX:
            desktop: null
            phone: null
          paddingY:
            desktop: null
            phone: null
    InvalidParam:
      type: object
      description: >
        Field-level validation error. `name` and `reason` are always intended
        for humans.

        Optional machine-readable fields are included when the API can identify
        the semantic error,

        especially for survey locale, identifier, and reference validation used
        by MCP and agent clients.
      required:
        - name
        - reason
      properties:
        name:
          type: string
          description: Dot-path to the invalid request field.
        reason:
          type: string
          description: Human-readable repair guidance.
        code:
          type: string
          enum:
            - dangling_reference
            - document_limit_exceeded
            - duplicate_identifier
            - duplicate_locale
            - file_limit_exceeded
            - file_type_unsupported
            - file_unreadable
            - forbidden_identifier
            - immutable_answer_code
            - immutable_identifier
            - immutable_option_deletion
            - immutable_option_text
            - immutable_question_code
            - immutable_question_type
            - invalid_locale
            - invalid_reference
            - limit_exceeded
            - missing_required_field
            - misordered_reference
            - missing_translation
            - qsf_limit_exceeded
            - qsf_not_recognized
            - read_only_field
            - unsupported_field
            - unsupported_locale
          description: >
            Machine-readable validation category, when available.


            This is the shared error shape every v3 operation returns, so it
            lists what the API can emit today and nothing more —
            `INVALID_PARAM_CODES` in `app/api/v3/lib/response.ts` is the
            registry, and a code absent from it is dropped before the response
            is built. Categories for operations that do not exist yet are added
            with the code that emits them, not ahead of it.


            `immutable_question_code`, `immutable_answer_code`,
            `immutable_question_type`, `immutable_option_text` and
            `immutable_option_deletion` come from the published-survey lock:
            once a survey has left `draft` (`inProgress`, `paused` or
            `completed`; a scheduled survey is `paused`), question codes, answer
            codes, question types and option text in every language are locked,
            and an option, matrix row or matrix column that existed when the
            survey was published cannot be deleted. `name` points at the
            offending field (at the option list for a deletion) and `identifier`
            is the option id, or the element id when the option is not the
            subject. Adding questions and options is still allowed.


            `limit_exceeded`: the field is well formed but past a limit the
            operation states, which `reason` names together with what to change.
            Chart queries use it for a date range that spans more time buckets
            than its granularity allows.


            `qsf_not_recognized` and `qsf_limit_exceeded` come from the
            Qualtrics import (an internal, session-only route sharing this
            shape): the file is not a Qualtrics export it can read, or it is one
            past an import limit, which `identifier` names.


            `file_type_unsupported`, `file_limit_exceeded` and `file_unreadable`
            come from the survey import too, about the uploaded file whatever
            its type: the import does not read this kind of file (`identifier`
            names what it recognized, if anything), the file is past an upload
            limit, which `identifier` names, or it is broken. A JSON file that
            does not parse has `identifier` `json_syntax`, and the problem's
            `details` give the `line` and `column` where it stops, when the
            parser says.


            `document_limit_exceeded` comes from the survey import of a
            questionnaire (Word, Excel or CSV): the document is past one of the
            import's limits, which `identifier` names.
        identifier:
          type: string
          description: >-
            Identifier involved in the validation failure, when available. For
            language errors, this can be the normalized language code.
        referenceType:
          type: string
          enum:
            - block
            - element
            - ending
            - hiddenField
            - language
            - variable
            - variableName
            - recall
          description: >-
            Identifier namespace involved in the validation failure. Same rule
            as `code`: these are the namespaces the API emits today, and more
            arrive with the operations that emit them.
        missingId:
          type: string
          description: Referenced id that does not exist in the submitted survey document.
        firstUsedAt:
          type: string
          description: Dot-path where a duplicate identifier was first used.
        conflictsWith:
          type: string
          description: Dot-path to the existing identifier that conflicts with this field.
      additionalProperties: false
    CreativeType:
      type: string
      enum:
        - feedbackButton
        - banner
      description: >-
        The kind of creative, which fixes its `content` and `styling` shape. A
        `feedbackButton` is a tab on an edge of the page that always opens its
        Destination; a `banner` is a bar across the top or bottom of the page
        with a message and an optional button. Fixed at creation: it can never
        change.
    CreativeStatus:
      type: string
      enum:
        - draft
        - inProgress
        - paused
        - completed
      description: >
        The author's intent, and the only status a write sets: `draft` (never
        published), `inProgress` (published), `paused` (paused by its author) or
        `completed` (closed by its author). The same values as a survey's
        `status`.


        What visitors get is `displayStatus`, which the server derives from this
        value, `archivedAt`, the schedule and the Destination survey. Nothing
        writes `status` on its own: a schedule ending or a survey pausing
        changes `displayStatus` only.
    CreativeDisplayStatus:
      type: string
      enum:
        - draft
        - scheduled
        - active
        - paused
        - closed
        - archived
      description: >
        What the creative is doing now, derived in this order: `archived` when
        archived; `draft` and `closed` (status `completed`) when the author said
        so; `closed` when the schedule's `endAt` has passed; `paused` when the
        author paused it; `scheduled` before the schedule's `startAt`; `paused`
        when its Destination survey isn't active (not `inProgress`, or
        archived); otherwise `active`.
    CreativeDisplayStatusReason:
      type:
        - string
        - 'null'
      enum:
        - surveyNotActive
        - scheduleEnded
        - destinationMissing
        - actionMissing
        - null
      description: >
        Why `displayStatus` differs from what `status` alone would give:
        `surveyNotActive` on a `paused` creative whose Destination survey isn't
        active ("Paused with its survey": it comes back by itself when the
        survey is active again), `scheduleEnded` on a `closed` creative whose
        `endAt` has passed, `destinationMissing` on a `paused` creative that
        needs a Destination (a feedback button, or a banner with a button) and
        has none, and `actionMissing` on a `paused` creative that shows on an
        action and has none. Sites never show a creative paused for either of
        the last two until it gets what it lacks (see `warnings`). `null`
        otherwise. New values may be added.
    LocaleCode:
      type: string
      pattern: ^[a-z]{2}(?:-[A-Z][a-z]{3})?-[A-Z]{2}$
      description: >-
        Canonical locale code accepted by v3 survey APIs, for example `en-US`,
        `de-DE`, or `zh-Hans-CN`.
      example: en-US
    CreativeLanguage:
      type: object
      description: A language the creative's texts are written in.
      required:
        - code
        - default
        - enabled
      properties:
        code:
          $ref: '#/components/schemas/LocaleCode'
        default:
          type: boolean
          description: Whether this is `defaultLanguage`. Exactly one entry is the default.
        enabled:
          type: boolean
          description: >-
            Whether visitors in this language see this translation. The default
            language is always enabled; a disabled or missing translation falls
            back to the default language.
      additionalProperties: false
    CreativeDestination:
      oneOf:
        - $ref: '#/components/schemas/CreativeSurveyDestination'
        - $ref: '#/components/schemas/CreativeLinkDestination'
      discriminator:
        propertyName: type
        mapping:
          survey: '#/components/schemas/CreativeSurveyDestination'
          link: '#/components/schemas/CreativeLinkDestination'
      description: >-
        What the creative opens when pressed, with the read-only `opensAs`. A
        write takes `CreativeDestinationInput`, which carries neither `opensAs`
        nor `surveyName`.
    CreativeDistribution:
      type: object
      description: >
        When the creative shows. `showOn: pageView` shows it on every page view;
        `showOn: action` only when one of `triggers` fires, and publishing needs
        at least one. `triggers` must be empty with `pageView`. A creative never
        falls back to every page view. `conditions` (Show when) narrows either,
        and `displayPercentage` (Share of visitors) shows it to that share of
        visitors, each decided once and kept on every page; `null` means
        everyone.
      required:
        - showOn
        - triggers
        - conditions
        - displayPercentage
      properties:
        showOn:
          type: string
          enum:
            - pageView
            - action
        triggers:
          type: array
          maxItems: 20
          items:
            $ref: '#/components/schemas/CreativeTrigger'
          description: >-
            Each id must name an action class in the creative's workspace, at
            most once; an unknown or repeated id answers **422**.
        conditions:
          anyOf:
            - $ref: '#/components/schemas/ShowConditionGroup'
            - type: 'null'
          description: Show when. `null` means no conditions.
        displayPercentage:
          type:
            - number
            - 'null'
          minimum: 0.01
          maximum: 100
      additionalProperties: false
      example:
        showOn: pageView
        triggers: []
        conditions: null
        displayPercentage: null
    CreativeSchedule:
      type: object
      description: >-
        When a published creative shows, to the minute. Before `startAt` it is
        `scheduled`; from `endAt` on it is `closed`. `null` leaves that side
        open. `endAt` must be after `startAt`, or the write answers **422**.
      required:
        - startAt
        - endAt
      properties:
        startAt:
          type:
            - string
            - 'null'
          format: date-time
        endAt:
          type:
            - string
            - 'null'
          format: date-time
      additionalProperties: false
      example:
        startAt: '2026-11-01T02:00:00.000Z'
        endAt: '2026-11-01T04:00:00.000Z'
    CreativeWarning:
      type: object
      description: >
        Something about the creative that needs attention; the list marks such
        rows with a warning icon. `destinationMissing`: it needs a Destination
        (a feedback button, or a banner with a button) and has none, for example
        after its survey was unlinked. `destinationNotAllowed`: its survey can
        no longer be a Destination (it became Restricted, single-use or
        PIN-protected), so pressing it would fail. `actionMissing`: it shows on
        an action but has none, so it never shows. New codes may be added.
      required:
        - code
        - message
      properties:
        code:
          type: string
          enum:
            - destinationMissing
            - destinationNotAllowed
            - actionMissing
        message:
          type: string
          description: The same warning in English, for people.
      additionalProperties: false
    CreativeText:
      type: object
      description: >-
        Plain text per language, keyed by locale code. Must hold
        `defaultLanguage`; every other key must be declared in `languages`. A
        visitor whose language is missing sees the default language.
      propertyNames:
        type: string
        description: A locale code, `defaultLanguage` or one declared in `languages`.
      additionalProperties:
        type: string
        maxLength: 200
      examples:
        - en-US: Feedback
          de-DE: Feedback geben
    FeedbackButtonPlacement:
      type: object
      description: >-
        Where a feedback button sits: an edge of the page plus an offset along
        it, in percent, that places the button's centre. On the left and right
        edges the offset runs from the top; on the bottom edge, from the left.
        50 centres the button on its edge. Near either end the button stops at
        the end of the edge instead, so it stays fully on screen: 0 puts its top
        (or left) end at the start of the edge and 100 its bottom (or right) end
        at the end.
      required:
        - edge
        - offset
      properties:
        edge:
          type: string
          enum:
            - left
            - right
            - bottom
        offset:
          type: integer
          minimum: 0
          maximum: 100
      additionalProperties: false
    FeedbackButtonTheme:
      type: object
      description: >
        The feedback button's custom styles. With `customStyles` off the button
        follows the workspace Look & Feel (the survey button) and the values
        below are kept but not applied. With it on, each value overrides the
        workspace one; `null` keeps the workspace value. A colour has a `light`
        value and an optional `dark` one for the visitor's dark appearance.
        Without a `dark` value: when the background or the text colour is set,
        both keep their light values in dark appearance so their contrast holds,
        a background set without a text colour gets readable text (`#0f172a` or
        `#ffffff`) in each appearance, and a border keeps its light value.
        Colours left to the workspace follow its dark palette when the visitor's
        appearance is dark. Sizes and the position apply in both appearances.
      required:
        - customStyles
        - backgroundColor
        - textColor
        - borderColor
        - borderRadius
        - fontWeight
        - fontSize
        - paddingX
        - paddingY
      properties:
        customStyles:
          type: boolean
          description: The "Add custom styles" switch.
        backgroundColor:
          anyOf:
            - $ref: '#/components/schemas/CreativeColor'
            - type: 'null'
        textColor:
          anyOf:
            - $ref: '#/components/schemas/CreativeColor'
            - type: 'null'
        borderColor:
          anyOf:
            - $ref: '#/components/schemas/CreativeColor'
            - type: 'null'
        borderRadius:
          type:
            - integer
            - 'null'
          minimum: 0
          maximum: 100
          description: Corner radius in px.
        fontWeight:
          type:
            - integer
            - 'null'
          enum:
            - 400
            - 500
            - 600
            - 700
            - null
        fontSize:
          $ref: '#/components/schemas/CreativeFontSize'
        paddingX:
          $ref: '#/components/schemas/CreativePadding'
        paddingY:
          $ref: '#/components/schemas/CreativePadding'
        pageFont:
          type:
            - boolean
            - 'null'
          description: >-
            Page font: `true` renders in the host page's font, `false` in the
            survey font, `null` (or absent) follows the workspace's Page font
            setting. Applies only with `customStyles` on.
        customCss:
          anyOf:
            - $ref: '#/components/schemas/CustomCssInput'
            - type: 'null'
          description: >-
            The creative's own Custom CSS **source**, `null` (or absent) when it
            has none. It applies only with `customStyles` on, only to this
            creative, and is scoped to its element `.fb-creative-button` inside
            the creative's shadow root; the workspace Custom CSS never reaches a
            creative. The server processes it on every write that adds or edits
            it, silently removing `@import`, `@font-face` and external `url()`.
            Adding or editing it needs the Scale plan on Formbricks Cloud (403
            `custom_css_plan_required`); CSS that cannot be processed is a 422
            naming `styling.theme.customCss`. Removing it, or sending it back
            unchanged, needs no plan. Limited to 20 000 UTF-8 bytes.
      additionalProperties: false
    CreativeRichText:
      type: object
      description: >-
        Formatted text per language, keyed by locale code: each value is the
        text as a list of runs. Must hold `defaultLanguage`; every other key
        must be declared in `languages`.
      propertyNames:
        type: string
        description: A locale code, `defaultLanguage` or one declared in `languages`.
      additionalProperties:
        type: array
        maxItems: 100
        items:
          $ref: '#/components/schemas/CreativeTextRun'
      examples:
        - en-US:
            - text: 'Scheduled maintenance tonight from 02:00 to 04:00. '
            - text: Details
              href: /maintenance
              underline: true
    BannerButton:
      type: object
      description: >-
        The button inside a banner. Pressing it opens the creative's
        Destination.
      required:
        - label
      properties:
        label:
          $ref: '#/components/schemas/CreativeText'
          description: >-
            The button's text. Publishing needs a non-empty default-language
            label.
      additionalProperties: false
    BannerPlacement:
      oneOf:
        - $ref: '#/components/schemas/BannerTopPlacement'
        - $ref: '#/components/schemas/BannerBottomPlacement'
      discriminator:
        propertyName: placement
        mapping:
          top: '#/components/schemas/BannerTopPlacement'
          bottom: '#/components/schemas/BannerBottomPlacement'
      description: >-
        Where a banner sits and how it lays out. A bottom banner is always an
        overlay.
    BannerTheme:
      type: object
      description: >
        The banner's custom styles. With `customStyles` off the banner follows
        the workspace Look & Feel (the survey card, with the survey button
        inside) and the values below are kept but not applied. With it on, each
        value overrides the workspace one; `null` keeps the workspace value. A
        colour has a `light` value and an optional `dark` one for the visitor's
        dark appearance. Without a `dark` value: when the background or the text
        colour is set, both keep their light values in dark appearance so their
        contrast holds, a background set without a text colour gets readable
        text (`#0f172a` or `#ffffff`) in each appearance, and a border keeps its
        light value. Colours left to the workspace follow its dark palette when
        the visitor's appearance is dark. Sizes and the position apply in both
        appearances. The banner's button always looks like the survey button.
      required:
        - customStyles
        - backgroundColor
        - textColor
        - borderColor
        - fontWeight
        - fontSize
        - paddingX
        - paddingY
      properties:
        customStyles:
          type: boolean
          description: The "Add custom styles" switch.
        backgroundColor:
          anyOf:
            - $ref: '#/components/schemas/CreativeColor'
            - type: 'null'
        textColor:
          anyOf:
            - $ref: '#/components/schemas/CreativeColor'
            - type: 'null'
        borderColor:
          anyOf:
            - $ref: '#/components/schemas/CreativeColor'
            - type: 'null'
        fontWeight:
          type:
            - integer
            - 'null'
          enum:
            - 400
            - 500
            - 600
            - 700
            - null
        fontSize:
          $ref: '#/components/schemas/CreativeFontSize'
        paddingX:
          $ref: '#/components/schemas/CreativePadding'
        paddingY:
          $ref: '#/components/schemas/CreativePadding'
        pageFont:
          type:
            - boolean
            - 'null'
          description: >-
            Page font: `true` renders in the host page's font, `false` in the
            survey font, `null` (or absent) follows the workspace's Page font
            setting. Applies only with `customStyles` on.
        customCss:
          anyOf:
            - $ref: '#/components/schemas/CustomCssInput'
            - type: 'null'
          description: >-
            The creative's own Custom CSS **source**, `null` (or absent) when it
            has none. It applies only with `customStyles` on, only to this
            creative, and is scoped to its element `.fb-creative-banner` inside
            the creative's shadow root; the workspace Custom CSS never reaches a
            creative. The server processes it on every write that adds or edits
            it, silently removing `@import`, `@font-face` and external `url()`.
            Adding or editing it needs the Scale plan on Formbricks Cloud (403
            `custom_css_plan_required`); CSS that cannot be processed is a 422
            naming `styling.theme.customCss`. Removing it, or sending it back
            unchanged, needs no plan. Limited to 20 000 UTF-8 bytes.
      additionalProperties: false
    CreativeSurveyDestination:
      type: object
      description: The survey the creative opens.
      required:
        - type
        - surveyId
        - surveyName
        - opensAs
      properties:
        type:
          type: string
          enum:
            - survey
        surveyId:
          type: string
          format: cuid2
        surveyName:
          type: string
          readOnly: true
        opensAs:
          type: string
          enum:
            - popup
            - newTab
          readOnly: true
          description: >-
            Follows the survey's type: an app survey opens as a popup in its own
            placement, a link survey in a new tab.
      additionalProperties: false
    CreativeLinkDestination:
      type: object
      description: The link the creative opens.
      required:
        - type
        - url
        - opensAs
      properties:
        type:
          type: string
          enum:
            - link
        url:
          type: string
        opensAs:
          type: string
          enum:
            - newTab
          readOnly: true
          description: A link always opens in a new tab.
      additionalProperties: false
    CreativeTrigger:
      type: object
      description: >-
        An action that shows the creative when it fires. Discover action-class
        ids with `GET /api/v3/action-classes`.
      required:
        - actionClassId
      properties:
        actionClassId:
          type: string
          format: cuid2
          description: Id of an action class in the creative's workspace.
      additionalProperties: false
    ShowConditionGroup:
      type: object
      description: >
        Show when: the page, visit and device conditions that must hold, joined
        by `connector`. The same conditions surveys use. At most 20 conditions
        in all, groups nested at most two levels deep, and 10 240 characters of
        JSON; a set beyond those answers **400**. Empty groups are dropped on
        write, and a top-level group left empty is stored as `null` (always
        show).
      required:
        - id
        - connector
        - conditions
      properties:
        id:
          type: string
          format: cuid2
        connector:
          type: string
          enum:
            - and
            - or
        conditions:
          type: array
          maxItems: 20
          items:
            oneOf:
              - $ref: '#/components/schemas/ShowCondition'
              - $ref: '#/components/schemas/ShowConditionSubgroup'
      additionalProperties: false
      example:
        id: k3m9q2w7e5r1t8y4u6i0o2p5
        connector: and
        conditions:
          - id: x8c2v6b4n1m7q9w3e5r0t2y6
            leftOperand:
              type: page
              value: currentUrl
            operator: startsWith
            rightOperand:
              type: static
              value: https://www.medicare.gov/
          - id: z5x1c9v3b7n2m6q0w4e8r2t6
            leftOperand:
              type: device
              value: deviceType
            operator: doesNotEqual
            rightOperand:
              type: static
              value: phone
    CreativeColor:
      type: object
      description: >-
        A custom colour per appearance, `#rrggbb`, as the survey styling stores
        its colours. `light` applies in light appearance. `dark` applies when
        the visitor's appearance is dark; `null` (or absent) derives it as the
        theme describes.
      required:
        - light
      properties:
        light:
          type: string
          pattern: ^#[0-9a-fA-F]{6}$
        dark:
          type:
            - string
            - 'null'
          pattern: ^#[0-9a-fA-F]{6}$
      additionalProperties: false
    CreativeFontSize:
      type: object
      description: >-
        Font size in px, per device. `phone` applies below 768 px viewport
        width; `null` there uses the `desktop` value, and `null` on `desktop`
        uses the workspace Look & Feel.
      required:
        - desktop
        - phone
      properties:
        desktop:
          type:
            - integer
            - 'null'
          minimum: 8
          maximum: 72
        phone:
          type:
            - integer
            - 'null'
          minimum: 8
          maximum: 72
      additionalProperties: false
    CreativePadding:
      type: object
      description: >-
        Padding in px, per device. `phone` applies below 768 px viewport width;
        `null` there uses the `desktop` value, and `null` on `desktop` uses the
        workspace Look & Feel.
      required:
        - desktop
        - phone
      properties:
        desktop:
          type:
            - integer
            - 'null'
          minimum: 0
          maximum: 64
        phone:
          type:
            - integer
            - 'null'
          minimum: 0
          maximum: 64
      additionalProperties: false
    CustomCssInput:
      type: object
      description: >-
        Custom CSS **source** as a caller writes it (ENG-3641). Both keys are
        required. `light` is base CSS that applies in both appearances; `dark`
        adds overrides on top of it when the survey renders dark. `null`, an
        empty string or whitespace means "no CSS" for that field. Source only:
        compiled output and the processor version are computed by the server on
        every write, and a request that supplies either is rejected. The
        combined source is limited to 100 000 UTF-8 bytes for a workspace and 20
        000 for a survey; larger CSS is a **422** with error code
        `source_too_large`.
      required:
        - light
        - dark
      properties:
        light:
          type:
            - string
            - 'null'
          description: Base CSS, applied in light and dark appearance.
        dark:
          type:
            - string
            - 'null'
          description: Additional CSS applied only in dark appearance.
      additionalProperties: false
    CreativeTextRun:
      type: object
      description: >
        One stretch of banner text with the same formatting. Banner text is
        stored and delivered as runs, never as HTML, so it can't carry markup,
        scripts or images.


        `href` makes the run a link. Allowed: `https://` and `http://` URLs with
        a real host (the same rule as a link Destination's `url`, so
        `https://example.` is refused), `mailto:` and `tel:` links, and
        root-relative paths (`/open-enrollment`), which resolve on whichever
        site shows the banner.
      required:
        - text
      properties:
        text:
          type: string
          minLength: 1
          maxLength: 2000
        bold:
          type: boolean
        italic:
          type: boolean
        underline:
          type: boolean
        href:
          type: string
          maxLength: 2048
          pattern: >-
            ^(?:https?://(?:[^\s/?#@]+@)?(?:localhost|\d{1,3}(?:\.\d{1,3}){3}|\[[0-9A-Fa-f:.]+\]|(?:[^\s/\\?#@:.\[\]]+\.)+[^\s/\\?#@:.\[\]\d][^\s/\\?#@:.\[\]]+)(?::\d{1,5})?(?:[/?#]\S*)?|(?:mailto:|tel:|/(?!/))\S*)$
      additionalProperties: false
    BannerTopPlacement:
      type: object
      description: >-
        A banner at the top of the page, either `inPage` (in the page flow,
        scrolling away with it) or `overlay` (fixed and always visible).
      required:
        - placement
        - layout
      properties:
        placement:
          type: string
          enum:
            - top
        layout:
          type: string
          enum:
            - inPage
            - overlay
      additionalProperties: false
    BannerBottomPlacement:
      type: object
      description: A banner at the bottom of the page, which is always `overlay`.
      required:
        - placement
        - layout
      properties:
        placement:
          type: string
          enum:
            - bottom
        layout:
          type: string
          enum:
            - overlay
      additionalProperties: false
    ShowCondition:
      type: object
      description: >
        One condition on the page, the visit or the device: `leftOperand`
        `operator` `rightOperand`. The operand names its family in
        `leftOperand.type` (`page`: `currentUrl`, `pageReferrer`,
        `entryReferrer`, `queryParam`; `visit`: `pagesViewed`,
        `uniquePagesViewed`, `timeOnSite`, `visitedUrls`; `device`:
        `deviceType`, `browser`, `screenWidth`), and each operand accepts only
        its own operators. `queryParam` names its parameter in
        `leftOperand.meta.key`. `isSet` and `isNotSet` take no `rightOperand`;
        list operators (`containsAnyOf`, `containsNoneOf`, and the
        `currentUrl`-only `pathIsAnyOf`, `pathIsNoneOf`, which compare exact
        page paths) take a non-empty list; numeric operands take a number of 0
        or more (`uniquePagesViewed` at most 200); `deviceType` takes `phone`,
        `tablet` or `desktop`. A condition that breaks one of these rules
        answers **400**. Matching is case-insensitive.
      required:
        - id
        - leftOperand
        - operator
      properties:
        id:
          type: string
          format: cuid2
        leftOperand:
          type: object
          required:
            - type
            - value
          properties:
            type:
              type: string
              enum:
                - page
                - visit
                - device
            value:
              type: string
              enum:
                - currentUrl
                - pageReferrer
                - entryReferrer
                - queryParam
                - pagesViewed
                - uniquePagesViewed
                - timeOnSite
                - visitedUrls
                - deviceType
                - browser
                - screenWidth
            meta:
              type: object
              required:
                - key
              properties:
                key:
                  type: string
                  minLength: 1
                  maxLength: 200
              additionalProperties: false
          additionalProperties: false
        operator:
          type: string
          enum:
            - equals
            - doesNotEqual
            - contains
            - doesNotContain
            - startsWith
            - endsWith
            - containsAnyOf
            - containsNoneOf
            - pathIsAnyOf
            - pathIsNoneOf
            - isGreaterThan
            - isLessThan
            - isGreaterThanOrEqual
            - isLessThanOrEqual
            - includes
            - doesNotInclude
            - isSet
            - isNotSet
        rightOperand:
          type: object
          required:
            - type
            - value
          properties:
            type:
              type: string
              enum:
                - static
            value:
              oneOf:
                - type: string
                  maxLength: 2048
                - type: number
                - type: array
                  maxItems: 200
                  items:
                    type: string
                    maxLength: 2048
          additionalProperties: false
      additionalProperties: false
    ShowConditionSubgroup:
      type: object
      description: >-
        A group of conditions inside the top-level group. Groups nest at most
        two levels deep.
      required:
        - id
        - connector
        - conditions
      properties:
        id:
          type: string
          format: cuid2
        connector:
          type: string
          enum:
            - and
            - or
        conditions:
          type: array
          maxItems: 20
          items:
            $ref: '#/components/schemas/ShowCondition'
      additionalProperties: false
  responses:
    V3BadRequest:
      description: >-
        Bad Request — malformed JSON, invalid query/body/params, duplicate name,
        or unsupported field.
      headers:
        X-Request-Id:
          schema:
            type: string
          description: Request correlation ID
        Cache-Control:
          schema:
            type: string
          example: private, no-store
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    V3Unauthorized:
      description: Not authenticated (no valid session or API key).
      headers:
        WWW-Authenticate:
          schema:
            type: string
          example: Bearer realm="formbricks"
          description: >-
            Authentication scheme challenge. RFC 9110 §15.5.2 asks a 401 for a
            challenge "applicable to the target resource", and Bearer is
            applicable here because these operations accept the API key as
            `Authorization: Bearer <key>` as well as `x-api-key`.
            Session-cookie-only operations send no challenge — see
            `V3UnauthorizedSession`. The MCP endpoints send a richer OAuth
            challenge carrying `resource_metadata` and `scope`.
        X-Request-Id:
          schema:
            type: string
          description: Request correlation ID
        Cache-Control:
          schema:
            type: string
          example: private, no-store
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    V3CreativesForbidden:
      description: >-
        Forbidden, one of two codes. `forbidden`: the caller lacks the workspace
        access the operation needs, or the creative does not exist (404 is not
        used, so creative ids cannot be probed for existence).
        `creatives_not_entitled`: Creatives is not available on this instance
        (Formbricks Cloud, or a self-hosted license that does not include it).
        It is checked only after the caller's own access, so it says nothing
        about a workspace the caller cannot see. A workspace that still has
        creatives is in wind-down: listing, reading, stats, a PATCH that sets
        nothing but `status` to `paused` or `completed`, pausing a survey's
        creatives (`POST /api/v3/creatives/pause`), and DELETE keep working, and
        everything else answers this. A workspace without creatives answers it
        on every operation.
      headers:
        X-Request-Id:
          schema:
            type: string
          description: Request correlation ID
        Cache-Control:
          schema:
            type: string
          example: private, no-store
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          examples:
            notAllowed:
              summary: No access to the workspace, or an unknown creative
              value:
                title: Forbidden
                status: 403
                detail: You are not authorized to access this resource
                code: forbidden
                requestId: req_01j8z3
            notEntitled:
              summary: >-
                Creatives is not available (Cloud, or no license with Creatives
                and no creatives)
              value:
                title: Forbidden
                status: 403
                detail: Creatives is not available on this instance
                code: creatives_not_entitled
                requestId: req_01j8z4
            windDown:
              summary: >-
                The license does not include Creatives, and the operation is not
                one wind-down allows
              value:
                title: Forbidden
                status: 403
                detail: >-
                  Creatives is not included in this instance's license: existing
                  creatives can only be listed, read, paused, closed or deleted
                code: creatives_not_entitled
                requestId: req_01j8z5
    V3TooManyRequests:
      description: Rate limit exceeded.
      headers:
        X-Request-Id:
          schema:
            type: string
          description: Request correlation ID
        Cache-Control:
          schema:
            type: string
          example: private, no-store
        Retry-After:
          schema:
            type: integer
          description: Seconds until the current rate-limit window resets.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    V3InternalServerError:
      description: Internal Server Error.
      headers:
        X-Request-Id:
          schema:
            type: string
          description: Request correlation ID
        Cache-Control:
          schema:
            type: string
          example: private, no-store
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >
        Management API key; must include **workspaceId** as an allowed workspace
        with read, write, or manage permission.
    bearerAuth:
      type: http
      scheme: bearer
      description: >
        The same management API key, presented as `Authorization: Bearer <key>`
        instead of `x-api-key`. Equivalent in every way — same key, same
        workspace permissions — and offered because it is what most HTTP clients
        and SDK generators reach for by default.

        A **401** from any operation that accepts it carries `WWW-Authenticate:
        Bearer realm="formbricks"`. Session-only operations accept neither this
        nor `x-api-key`.
    sessionAuth:
      type: apiKey
      in: cookie
      name: next-auth.session-token
      description: >
        NextAuth session JWT cookie. **Development:** often
        `next-auth.session-token`.

        **Production (HTTPS):** often `__Secure-next-auth.session-token`. Send
        the cookie your browser receives after sign-in.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.