mirror/formbricks
1
0
Fork 0
mirror of https://github.com/formbricks/formbricks.git synced 2026-01-05 16:19:55 -06:00
Code Issues Packages Projects Releases 118 Wiki Activity

docs: Update docs for Private file upload and general client API (#6045)

Browse Source
This commit is contained in:
Harsh Bhat
2025-06-23 20:56:10 +05:30
committed by GitHub
parent e5fa4328e1
commit 397643330a
2 changed files with 101 additions and 99 deletions
Download Patch File Download Diff File Expand all files Collapse all files

95
apps/web/scripts/merge-client-endpoints.ts
View File

@@ -4,11 +4,19 @@ import { logger } from "@formbricks/logger";
// Define the v1 (now v2) client endpoints to be merged
const v1ClientEndpoints = {
"/responses/{responseId}": {
"/client/{environmentId}/responses/{responseId}": {
put: {
security: [],
description:
"Update an existing response for example when you want to mark a response as finished or you want to change an existing response's value.",
parameters: [
{
in: "path",
name: "environmentId",
required: true,
schema: { type: "string" },
description: "The ID of the environment.",
},
{
in: "path",
name: "responseId",
@@ -57,14 +65,15 @@ const v1ClientEndpoints = {
tags: ["Client API > Response"],
servers: [
{
url: "https://app.formbricks.com/api/v2/client",
url: "https://app.formbricks.com/api/v2",
description: "Formbricks Client",
},
],
},
},
"/{environmentId}/responses": {
"/client/{environmentId}/responses": {
post: {
security: [],
description:
"Create a response for a survey and its fields with the user's responses. The userId & meta here is optional",
requestBody: {
@@ -89,14 +98,15 @@ const v1ClientEndpoints = {
tags: ["Client API > Response"],
servers: [
{
url: "https://app.formbricks.com/api/v2/client",
url: "https://app.formbricks.com/api/v2",
description: "Formbricks Client",
},
],
},
},
"/{environmentId}/contacts/{userId}/attributes": {
"/client/{environmentId}/contacts/{userId}/attributes": {
put: {
security: [],
description:
"Update a contact's attributes in Formbricks to keep them in sync with your app or when you want to set a custom attribute in Formbricks.",
parameters: [
@@ -138,14 +148,15 @@ const v1ClientEndpoints = {
tags: ["Client API > Contacts"],
servers: [
{
url: "https://app.formbricks.com/api/v2/client",
url: "https://app.formbricks.com/api/v2",
description: "Formbricks Client",
},
],
},
},
"/{environmentId}/identify/contacts/{userId}": {
"/client/{environmentId}/identify/contacts/{userId}": {
get: {
security: [],
description:
"Retrieves a contact's state including their segments, displays, responses and other tracking information. If the contact doesn't exist, it will be created.",
parameters: [
@@ -167,14 +178,15 @@ const v1ClientEndpoints = {
tags: ["Client API > Contacts"],
servers: [
{
url: "https://app.formbricks.com/api/v2/client",
url: "https://app.formbricks.com/api/v2",
description: "Formbricks Client",
},
],
},
},
"/{environmentId}/displays": {
"/client/{environmentId}/displays": {
post: {
security: [],
description:
"Create a new display for a valid survey ID. If a userId is passed, the display is linked to the user.",
requestBody: {
@@ -199,48 +211,25 @@ const v1ClientEndpoints = {
tags: ["Client API > Display"],
servers: [
{
url: "https://app.formbricks.com/api/v2/client",
url: "https://app.formbricks.com/api/v2",
description: "Formbricks Client",
},
],
},
},
"/{environmentId}/displays/{displayId}": {
put: {
description:
"Update a Display for a user. A use case can be when a user submits a response & you want to link it to an existing display.",
parameters: [{ in: "path", name: "displayId", required: true, schema: { type: "string" } }],
requestBody: {
content: {
"application/json": {
schema: { example: { responseId: "response123" }, type: "object" },
},
},
},
responses: {
"200": {
content: {
"application/json": {
example: { displayId: "display123" },
schema: { type: "object" },
},
},
description: "OK",
},
},
summary: "Update Display",
tags: ["Client API > Display"],
servers: [
{
url: "https://app.formbricks.com/api/v2/client",
description: "Formbricks Client",
},
],
},
},
"/{environmentId}/environment": {
"/client/{environmentId}/environment": {
get: {
security: [],
description: "Retrieves the environment state to be used in Formbricks SDKs",
parameters: [
{
in: "path",
name: "environmentId",
required: true,
schema: { type: "string" },
description: "The ID of the environment.",
},
],
responses: {
"200": {
content: {
@@ -256,14 +245,15 @@ const v1ClientEndpoints = {
tags: ["Client API > Environment"],
servers: [
{
url: "https://app.formbricks.com/api/v2/client",
url: "https://app.formbricks.com/api/v2",
description: "Formbricks Client",
},
],
},
},
"/{environmentId}/user": {
"/client/{environmentId}/user": {
post: {
security: [],
description:
"Endpoint for creating or identifying a user within the specified environment. If the user already exists, this will identify them and potentially update user attributes. If they don't exist, it will create a new user.",
requestBody: {
@@ -288,14 +278,15 @@ const v1ClientEndpoints = {
tags: ["Client API > User"],
servers: [
{
url: "https://app.formbricks.com/api/v2/client",
url: "https://app.formbricks.com/api/v2",
description: "Formbricks Client",
},
],
},
},
"/{environmentId}/storage": {
"/client/{environmentId}/storage": {
post: {
security: [],
summary: "Upload Private File",
description:
"API endpoint for uploading private files. Uploaded files are kept private so that only users with access to the specified environment can retrieve them. The endpoint validates the survey ID, file name, and file type from the request body, and returns a signed URL for S3 uploads along with a local upload URL.",
@@ -442,14 +433,15 @@ const v1ClientEndpoints = {
},
servers: [
{
url: "https://app.formbricks.com/api/v2/client",
url: "https://app.formbricks.com/api/v2",
description: "Formbricks API Server",
},
],
},
},
"/{environmentId}/storage/local": {
"/client/{environmentId}/storage/local": {
post: {
security: [],
summary: "Upload Private File to Local Storage",
description:
'API endpoint for uploading private files to local storage. The request must include a valid signature, UUID, and timestamp to verify the upload. The file is provided as a Base64 encoded string in the request body. The "Content-Type" header must be set to a valid MIME type, and the file data must be a valid file object (buffer).',
@@ -478,7 +470,8 @@ const v1ClientEndpoints = {
},
fileName: {
type: "string",
description: "The URI encoded file name.",
description:
"This must be the `fileName` returned from the [Upload Private File](/api-v2-reference/client-api->-file-upload/upload-private-file) endpoint (Step 1).",
},
fileType: {
type: "string",

105
docs/api-v2-reference/openapi.yml
View File

@@ -34,11 +34,18 @@ tags:
security:
- apiKeyAuth: []
paths:
/responses/{responseId}:
/client/{environmentId}/responses/{responseId}:
put:
security: []
description: Update an existing response for example when you want to mark a
response as finished or you want to change an existing response's value.
parameters:
- in: path
name: environmentId
required: true
schema:
type: string
description: The ID of the environment.
- in: path
name: responseId
required: true
@@ -77,10 +84,11 @@ paths:
tags:
- Client API > Response
servers:
- url: https://app.formbricks.com/api/v2/client
- url: https://app.formbricks.com/api/v2
description: Formbricks Client
/{environmentId}/responses:
/client/{environmentId}/responses:
post:
security: []
description: Create a response for a survey and its fields with the user's
responses. The userId & meta here is optional
requestBody:
@@ -104,10 +112,11 @@ paths:
tags:
- Client API > Response
servers:
- url: https://app.formbricks.com/api/v2/client
- url: https://app.formbricks.com/api/v2
description: Formbricks Client
/{environmentId}/contacts/{userId}/attributes:
/client/{environmentId}/contacts/{userId}/attributes:
put:
security: []
description: Update a contact's attributes in Formbricks to keep them in sync
with your app or when you want to set a custom attribute in Formbricks.
parameters:
@@ -152,10 +161,11 @@ paths:
tags:
- Client API > Contacts
servers:
- url: https://app.formbricks.com/api/v2/client
- url: https://app.formbricks.com/api/v2
description: Formbricks Client
/{environmentId}/identify/contacts/{userId}:
/client/{environmentId}/identify/contacts/{userId}:
get:
security: []
description: Retrieves a contact's state including their segments, displays,
responses and other tracking information. If the contact doesn't exist,
it will be created.
@@ -184,10 +194,11 @@ paths:
tags:
- Client API > Contacts
servers:
- url: https://app.formbricks.com/api/v2/client
- url: https://app.formbricks.com/api/v2
description: Formbricks Client
/{environmentId}/displays:
/client/{environmentId}/displays:
post:
security: []
description: Create a new display for a valid survey ID. If a userId is passed,
the display is linked to the user.
requestBody:
@@ -211,43 +222,19 @@ paths:
tags:
- Client API > Display
servers:
- url: https://app.formbricks.com/api/v2/client
- url: https://app.formbricks.com/api/v2
description: Formbricks Client
/{environmentId}/displays/{displayId}:
put:
description: Update a Display for a user. A use case can be when a user submits
a response & you want to link it to an existing display.
/client/{environmentId}/environment:
get:
security: []
description: Retrieves the environment state to be used in Formbricks SDKs
parameters:
- in: path
name: displayId
name: environmentId
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
example:
responseId: response123
type: object
responses:
"200":
content:
application/json:
example:
displayId: display123
schema:
type: object
description: OK
summary: Update Display
tags:
- Client API > Display
servers:
- url: https://app.formbricks.com/api/v2/client
description: Formbricks Client
/{environmentId}/environment:
get:
description: Retrieves the environment state to be used in Formbricks SDKs
description: The ID of the environment.
responses:
"200":
content:
@@ -262,10 +249,11 @@ paths:
tags:
- Client API > Environment
servers:
- url: https://app.formbricks.com/api/v2/client
- url: https://app.formbricks.com/api/v2
description: Formbricks Client
/{environmentId}/user:
/client/{environmentId}/user:
post:
security: []
description: Endpoint for creating or identifying a user within the specified
environment. If the user already exists, this will identify them and
potentially update user attributes. If they don't exist, it will create
@@ -292,10 +280,11 @@ paths:
tags:
- Client API > User
servers:
- url: https://app.formbricks.com/api/v2/client
- url: https://app.formbricks.com/api/v2
description: Formbricks Client
/{environmentId}/storage:
/client/{environmentId}/storage:
post:
security: []
summary: Upload Private File
description: API endpoint for uploading private files. Uploaded files are kept
private so that only users with access to the specified environment can
@@ -402,10 +391,11 @@ paths:
example:
error: Survey survey123 not found
servers:
- url: https://app.formbricks.com/api/v2/client
- url: https://app.formbricks.com/api/v2
description: Formbricks API Server
/{environmentId}/storage/local:
/client/{environmentId}/storage/local:
post:
security: []
summary: Upload Private File to Local Storage
description: API endpoint for uploading private files to local storage. The
request must include a valid signature, UUID, and timestamp to verify
@@ -433,7 +423,9 @@ paths:
description: The ID of the survey associated with the file.
fileName:
type: string
description: The URI encoded file name.
description: This must be the `fileName` returned from the [Upload Private
File](/api-v2-reference/client-api->-file-upload/upload-private-file)
endpoint (Step 1).
fileType:
type: string
description: The MIME type of the file.
@@ -1571,7 +1563,7 @@ paths:
- value
required:
- attributes
maxItems: 1000
maxItems: 250
required:
- environmentId
- contacts
@@ -4383,6 +4375,22 @@ components:
- enabled
- message
description: Email verification configuration (deprecated)
recaptcha:
type:
- object
- "null"
properties:
enabled:
type: boolean
threshold:
type: number
multipleOf: 0.1
minimum: 0.1
maximum: 0.9
required:
- enabled
- threshold
description: Google reCAPTCHA configuration
displayPercentage:
type:
- number
@@ -4431,6 +4439,7 @@ components:
- inlineTriggers
- isBackButtonHidden
- verifyEmail
- recaptcha
- displayPercentage
- questions
webhook: