Authentication
Create a management API key — API Keys in the organization dropdown of the breadcrumbs, see Generate API key — and send it in thex-api-key header (an
Authorization: Bearer <key> header carrying the same key is also accepted). Keys carry per-workspace
permissions — read, write or manage — and every operation states which one it needs.
x-api-key crosses the wire in cleartext
otherwise. Operations also accept a signed-in browser session, which is how the Formbricks app itself calls
them; the operation pages document the API-key contract.
Self-hosted instances
Substitute your own origin, and note that Feedback Records is the one part of v3 that needs the API gateway routed to it, because it is served by the gateway rather than the application:- Kubernetes / Helm — off by default. Set
envoy.enabled: trueandenvoy.formbricks.routes.feedbackRecords: true. Enabling the route also installs its authorization policy, so the two cannot drift apart. - One-click Docker — the installer writes the Traefik routes for you, so it works out of the box.
- Formbricks Cloud — already enabled.
GET /api/v3/feedbackRecords answers
401 when the route is live, and 404 when it is not routed and the request falls through to the application.
Feedback Records
A Feedback Record is one piece of feedback in a normalized shape, stored in a Feedback Dataset. The eight operations under/api/v3/feedbackRecords let
you list, filter, search, create, correct and delete them.
They are served by the API gateway rather than by the application routes that serve the rest of v3: the
gateway authenticates you, checks that the API key may act on the dataset, then forwards the call to the
feedback store. Three things follow from that, and they trip people up.
tenant_id is your dataset id
The wire name for the dataset is tenant_id. It is required on every collection operation — as a query
parameter on GET and DELETE /api/v3/feedbackRecords, in the JSON body on POST /api/v3/feedbackRecords and
POST /api/v3/feedbackRecords/search/semantic. Single-record operations (/{id}, /{id}/similar) do not take
it: the gateway resolves the dataset from the record.
The dataset id is not shown in the app today. Get it from the MCP server’s list_feedback_datasets tool, which
reports it as dataset_id, or ask your Formbricks contact.
Field names are snake_case
The payload is the feedback store’s own, passed through unchanged, so members and filters are snake_case
(value_text, submission_id, created_since) where the rest of v3 is camelCase. Filters on a value read off a
response use the same name as the response.
Errors come in two shapes
An unknown dataset or record id is a
403 rather than a 404, so ids cannot be probed, and any path under
/api/v3/feedbackRecords that is not one of the eight answers 400. The 404s that do exist all come from the
store: on /{id}/similar for a record that has no embedding yet, and on the single-record operations for a
record deleted in the last minute — the gateway caches the record’s dataset for 60 seconds, so during that
window the call is still authorized and reaches a store that no longer has the record.
The 413 is the one refusal the application does not write itself: the proxy in front of it stops reading the
body at 1 MiB and answers on its own, so branch on that status rather than on its body.
Permissions
An API key may update or delete only in a dataset assigned to exactly one workspace. On a shared dataset no
workspace permission can say whose records they are, so those calls answer
403; reading and creating stay
allowed. The organization must hold the Unify Feedback entitlement.
Example
next_cursor back as cursor with the same sort and order. It is
absent on the last page.