> ## 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.

# Get a widget

> Returns one widget on a dashboard with its full chart: the resource an add's `Location` names.
Needs read access to the dashboard's workspace; a widget that is not on the dashboard, or a
dashboard the caller cannot see, answers 403.




## OpenAPI

````yaml /api-v3-reference/openapi.yml get /api/v3/dashboards/{dashboardId}/widgets/{widgetId}
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/dashboards/{dashboardId}/widgets/{widgetId}:
    get:
      tags:
        - V3 Dashboards
      summary: Get a widget
      description: >
        Returns one widget on a dashboard with its full chart: the resource an
        add's `Location` names.

        Needs read access to the dashboard's workspace; a widget that is not on
        the dashboard, or a

        dashboard the caller cannot see, answers 403.
      operationId: getDashboardWidgetV3
      parameters:
        - $ref: '#/components/parameters/DashboardIdPath'
        - $ref: '#/components/parameters/WidgetIdPath'
      responses:
        '200':
          description: The widget
          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/DashboardWidget'
        '400':
          $ref: '#/components/responses/V3BadRequest'
        '401':
          $ref: '#/components/responses/V3Unauthorized'
        '403':
          $ref: '#/components/responses/V3DashboardsForbidden'
        '429':
          $ref: '#/components/responses/V3TooManyRequests'
        '500':
          $ref: '#/components/responses/V3InternalServerError'
      security:
        - sessionAuth: []
        - apiKeyAuth: []
        - bearerAuth: []
components:
  parameters:
    DashboardIdPath:
      in: path
      name: dashboardId
      required: true
      schema:
        type: string
        format: cuid2
      description: Dashboard identifier.
    WidgetIdPath:
      in: path
      name: widgetId
      required: true
      schema:
        type: string
        format: cuid2
      description: The widget's id, from the dashboard's `widgets`.
  schemas:
    DashboardWidget:
      type: object
      description: >-
        One chart's placement on the dashboard. `chart` is exactly what reading
        the chart returns.
      required:
        - id
        - chartId
        - layout
        - order
        - chart
      properties:
        id:
          type: string
          format: cuid2
        chartId:
          type: string
          format: cuid2
        layout:
          $ref: '#/components/schemas/WidgetLayout'
        order:
          type: integer
          minimum: 0
        chart:
          $ref: '#/components/schemas/ChartResource'
      additionalProperties: false
    WidgetLayout:
      type: object
      description: >-
        A widget's position and size on the dashboard's 12-column grid, in whole
        grid units: `1 ≤ w ≤ 12`, `x + w ≤ 12`, `1 ≤ h ≤ 8`, `0 ≤ y ≤ 1000`.
        Widgets may not overlap; gaps are allowed and close upward when the
        dashboard is drawn.
      required:
        - x
        - 'y'
        - w
        - h
      properties:
        x:
          type: integer
          minimum: 0
          maximum: 11
        'y':
          type: integer
          minimum: 0
          maximum: 1000
        w:
          type: integer
          minimum: 1
          maximum: 12
        h:
          type: integer
          minimum: 1
          maximum: 8
      additionalProperties: false
    ChartResource:
      type: object
      description: >-
        A chart: one saved visualisation of one Feedback Dataset. It belongs to
        a workspace and can sit on any number of dashboards — `dashboards` lists
        them, so a caller can see what an edit or a delete would affect.
      required:
        - id
        - workspaceId
        - datasetId
        - name
        - type
        - query
        - config
        - creator
        - dashboards
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          format: cuid2
        workspaceId:
          type: string
          format: cuid2
        datasetId:
          type: string
          format: cuid2
          description: >-
            The Feedback Dataset the chart reads. Fixed when the chart is
            created.
        name:
          type: string
          description: Unique within the workspace.
        type:
          type: string
          enum:
            - area
            - bar
            - pie
            - big_number
            - matrix
        query:
          $ref: '#/components/schemas/ChartQuery'
        config:
          $ref: '#/components/schemas/ChartConfig'
        creator:
          description: >-
            Who created the chart, for display only; `null` once that user is
            gone.
          oneOf:
            - type: object
              required:
                - name
              properties:
                name:
                  type: string
              additionalProperties: false
            - type: 'null'
        dashboards:
          type: array
          description: The dashboards that hold the chart, by name.
          items:
            type: object
            required:
              - id
              - name
            properties:
              id:
                type: string
                format: cuid2
              name:
                type: string
            additionalProperties: false
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      additionalProperties: false
    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'
    ChartQuery:
      type: object
      description: >-
        What a chart computes, in Cube's query format (ADR 0001): measures,
        dimensions, time dimensions, filters, order and limit over its Feedback
        Dataset's fields. Every field must come from the field catalog (`GET
        /api/v3/charts/fields`), named with its data-source prefix. Display
        settings are separate (`config`).


        Refused with **422** (`invalid_params` names each problem): a field that
        is not in the catalog; Cube options the app does not use (`ungrouped`,
        `segments`, `renewQuery`, `joinHints`, `total`, `compareDateRange`); a
        `timezone` (every range is read in the organization's display time
        zone); more than 15 fields across `measures`, `dimensions` and
        `timeDimensions`; more than 25 filter conditions or filters nested
        deeper than three levels; a date range that is not a preset, `all-time`
        or two ISO calendar dates; on a chart grouped by time alone, a date
        range that spans more than 10,000 buckets of its `granularity` (code
        `limit_exceeded`).
      properties:
        measures:
          type: array
          maxItems: 10
          items:
            type: string
            description: A field of kind `measure`.
          example:
            - FeedbackRecords.npsScore
        dimensions:
          type: array
          maxItems: 5
          items:
            type: string
            description: A field of kind `dimension` or `timeDimension`.
          example:
            - FeedbackRecords.sourceName
        timeDimensions:
          type: array
          maxItems: 2
          items:
            type: object
            required:
              - dimension
            properties:
              dimension:
                type: string
                description: A field of kind `timeDimension`.
                example: FeedbackRecords.collectedAt
              granularity:
                type: string
                enum:
                  - hour
                  - day
                  - week
                  - month
                  - quarter
                  - year
              dateRange:
                $ref: '#/components/schemas/ChartDateRange'
            additionalProperties: false
        filters:
          type: array
          maxItems: 25
          items:
            $ref: '#/components/schemas/ChartQueryFilter'
        order:
          description: >-
            Sort order: `[field, direction]` pairs, or an object mapping a field
            to its direction. At most 10 entries.
          oneOf:
            - type: array
              maxItems: 10
              items:
                type: array
                minItems: 2
                maxItems: 2
                prefixItems:
                  - type: string
                  - type: string
                    enum:
                      - asc
                      - desc
            - type: object
              maxProperties: 10
              additionalProperties:
                type: string
                enum:
                  - asc
                  - desc
        limit:
          type: integer
          minimum: 1
          maximum: 5000
        offset:
          type: integer
          minimum: 0
          maximum: 10000
      additionalProperties: false
    ChartConfig:
      type: object
      description: >-
        Display settings, kept apart from the chart query. Every key is
        optional; each applies to the chart types named in its description and
        is ignored by the others.
      properties:
        barOrientation:
          type: string
          enum:
            - vertical
            - horizontal
          description: Bar charts. Defaults to `vertical`.
        pieDisplay:
          type: string
          enum:
            - pie
            - breakdown
          description: Pie charts. Defaults to `pie`.
        areaDisplay:
          type: string
          enum:
            - filled
            - line
          description: Area charts. Defaults to `filled`.
        matrixCellValue:
          type: string
          enum:
            - percent
            - count
            - both
          description: Matrix charts. Defaults to `percent`.
        matrixColorScale:
          type: boolean
          description: Matrix charts. Defaults to `true`.
        matrixShowTotals:
          type: boolean
          description: Matrix charts. Defaults to `false`.
        matrixTranspose:
          type: boolean
          description: >-
            Matrix charts. Swaps rows and columns on screen; the query is
            unchanged.
        colors:
          type: array
          maxItems: 50
          items:
            type: string
            maxLength: 64
        xAxisLabel:
          type: string
          maxLength: 255
        yAxisLabel:
          type: string
          maxLength: 255
        showLegend:
          type: boolean
        legendPosition:
          type: string
          enum:
            - top
            - bottom
            - left
            - right
        stacked:
          type: boolean
        showGrid:
          type: boolean
        showValues:
          type: boolean
        numberFormat:
          type: string
          maxLength: 64
        dateFormat:
          type: string
          maxLength: 64
        prefix:
          type: string
          maxLength: 32
        suffix:
          type: string
          maxLength: 32
      additionalProperties: false
    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
    ChartDateRange:
      description: >-
        A date range on a time dimension: a named preset from the field
        catalog's `datePresets` (`last 7 days`, `this month`, …), `all-time` (no
        range), or a pair of ISO calendar dates `[from, to]`, both inclusive,
        `from` not after `to`. Every range is read in the organization's display
        time zone; a `timezone` cannot be supplied.


        Charts saved before ranges were limited to presets may hold a relative
        range Cube reads itself (`last 3 months`, `this week`). Such a chart
        still renders and can be previewed, within the bucket limit below, and
        can be saved with that same range kept; a new chart, or an update to
        another range, must use a preset or a pair.


        A chart grouped by time alone (one time dimension with a `granularity`,
        no other dimensions) gets one row per bucket in its range, empty or not,
        so its range may span at most 10,000 buckets: about 13 months by the
        hour, or 27 years by the day. A wider range is refused with **422**
        `limit_exceeded`; use a coarser granularity or a shorter range. An older
        chart's relative range is measured back from now (`last 999 years` spans
        999 years). Every preset fits at every granularity, and a chart with
        other dimensions returns only its real rows, so it is not limited.
      oneOf:
        - type: string
          description: A preset name from `datePresets`, or `all-time`.
          example: last 30 days
        - type: array
          minItems: 2
          maxItems: 2
          items:
            type: string
            format: date
          example:
            - '2026-01-01'
            - '2026-03-31'
    ChartQueryFilter:
      description: >-
        A filter: either one condition on a field, or an `and` / `or` group of
        filters. Filters nest at most three levels: a group, a group inside it,
        and conditions inside that. A chart query holds at most 25 conditions in
        all.
      oneOf:
        - type: object
          title: Condition
          required:
            - member
            - operator
          properties:
            member:
              type: string
              description: A field name from the field catalog.
              example: FeedbackRecords.sourceType
            operator:
              type: string
              description: One of the field's `filterOperators` in the catalog.
              enum:
                - equals
                - notEquals
                - contains
                - notContains
                - set
                - notSet
                - gt
                - gte
                - lt
                - lte
            values:
              type: array
              description: >-
                The values to compare against. Required by every operator except
                `set` and `notSet`, which take none.
              maxItems: 100
              items:
                type: string
                maxLength: 1000
          additionalProperties: false
        - type: object
          title: And group
          required:
            - and
          properties:
            and:
              type: array
              minItems: 1
              items:
                $ref: '#/components/schemas/ChartQueryFilter'
          additionalProperties: false
        - type: object
          title: Or group
          required:
            - or
          properties:
            or:
              type: array
              minItems: 1
              items:
                $ref: '#/components/schemas/ChartQueryFilter'
          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'
    V3DashboardsForbidden:
      description: >-
        Forbidden. `code: forbidden` when the caller has no access to the
        workspace, the Feedback Dataset or the resource (which may also not
        exist; 404 is not used, to avoid leaking existence). `code:
        dashboards_plan_required` when the caller is authorized but the
        organization does not have the Dashboards add-on or a license that
        includes it — checked after authorization, so a caller without access
        never learns the organization's plan.
      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'
    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.