chore: v3 api post survey

chore: update openapi example
chore: always use language maps, allow filtering multiple languages
2026-05-21 03:31:20 -05:00 · 2026-05-20 16:33:33 +00:00 · 2026-05-18 17:08:53 +00:00 · 2026-05-18 17:05:44 +00:00 · 2026-05-18 16:53:47 +00:00 · 2026-05-18 16:43:07 +00:00
56 changed files with 6055 additions and 1040 deletions
@@ -11,7 +11,7 @@ const mocks = vi.hoisted(() => ({
  loggerError: vi.fn(),
  sendToPipeline: vi.fn(),
  updateResponseWithQuotaEvaluation: vi.fn(),
-  validateClientFileUploads: vi.fn(),
+  validateFileUploads: vi.fn(),
  validateOtherOptionLengthForMultipleChoice: vi.fn(),
  validateResponseData: vi.fn(),
 }));
@@ -44,7 +44,7 @@ vi.mock("@/modules/api/v2/lib/element", () => ({
 }));

 vi.mock("@/modules/storage/utils", () => ({
-  validateClientFileUploads: mocks.validateClientFileUploads,
+  validateFileUploads: mocks.validateFileUploads,
 }));

 vi.mock("./response", () => ({
@@ -124,7 +124,7 @@ describe("putResponseHandler", () => {
    mocks.getResponse.mockResolvedValue(getBaseExistingResponse());
    mocks.getSurvey.mockResolvedValue(getBaseSurvey());
    mocks.updateResponseWithQuotaEvaluation.mockResolvedValue(getBaseUpdatedResponse());
-    mocks.validateClientFileUploads.mockReturnValue(true);
+    mocks.validateFileUploads.mockReturnValue(true);
    mocks.validateOtherOptionLengthForMultipleChoice.mockReturnValue(null);
    mocks.validateResponseData.mockReturnValue(null);
  });
@@ -278,7 +278,7 @@ describe("putResponseHandler", () => {
  });

  test("rejects invalid file upload updates", async () => {
-    mocks.validateClientFileUploads.mockReturnValue(false);
+    mocks.validateFileUploads.mockReturnValue(false);

    const result = await putResponseHandler(createHandlerParams());

@@ -11,7 +11,7 @@ import { getSurvey } from "@/lib/survey/service";
 import { formatValidationErrorsForV1Api, validateResponseData } from "@/modules/api/lib/validation";
 import { validateOtherOptionLengthForMultipleChoice } from "@/modules/api/v2/lib/element";
 import { createQuotaFullObject } from "@/modules/ee/quotas/lib/helpers";
-import { validateClientFileUploads } from "@/modules/storage/utils";
+import { validateFileUploads } from "@/modules/storage/utils";
 import { updateResponseWithQuotaEvaluation } from "./response";
 import { getValidatedResponseUpdateInput } from "./validated-response-update-input";

@@ -126,8 +126,7 @@ const getSurveyForResponse = async (
 const validateUpdateRequest = (
  existingResponse: TResponse,
  survey: TSurvey,
-  responseUpdateInput: TResponseUpdateInput,
-  workspaceId: string
+  responseUpdateInput: TResponseUpdateInput
 ): TRouteResult | undefined => {
  if (existingResponse.finished) {
    return {
@@ -135,15 +134,7 @@ const validateUpdateRequest = (
    };
  }

-  if (
-    !validateClientFileUploads({
-      data: responseUpdateInput.data,
-      workspaceId,
-      surveyId: survey.id,
-      blocks: survey.blocks,
-      questions: survey.questions,
-    })
-  ) {
+  if (!validateFileUploads(responseUpdateInput.data, survey.questions)) {
    return {
      response: responses.badRequestResponse("Invalid file upload response", undefined, true),
    };
@@ -250,7 +241,7 @@ export const putResponseHandler = async ({
    };
  }

-  const validationResult = validateUpdateRequest(existingResponse, survey, responseUpdateInput, workspaceId);
+  const validationResult = validateUpdateRequest(existingResponse, survey, responseUpdateInput);
  if (validationResult) {
    return validationResult;
  }
@@ -17,7 +17,7 @@ import { resolveClientApiIds } from "@/lib/utils/resolve-client-id";
 import { formatValidationErrorsForV1Api, validateResponseData } from "@/modules/api/lib/validation";
 import { getIsContactsEnabled } from "@/modules/ee/license-check/lib/utils";
 import { createQuotaFullObject } from "@/modules/ee/quotas/lib/helpers";
-import { validateClientFileUploads } from "@/modules/storage/utils";
+import { validateFileUploads } from "@/modules/storage/utils";
 import { createResponseWithQuotaEvaluation } from "./lib/response";

 export const OPTIONS = async (): Promise<Response> => {
@@ -147,15 +147,7 @@ export const POST = withV1ApiWrapper({
      responseInputData.singleUseId = singleUseValidationResult.singleUseId;
    }

-    if (
-      !validateClientFileUploads({
-        data: responseInputData.data,
-        workspaceId,
-        surveyId: survey.id,
-        blocks: survey.blocks,
-        questions: survey.questions,
-      })
-    ) {
+    if (!validateFileUploads(responseInputData.data, survey.questions)) {
      return {
        response: responses.badRequestResponse("Invalid file upload response"),
      };
@@ -66,7 +66,7 @@ export const POST = withV1ApiWrapper({
      };
    }

-    const { fileName, fileType, surveyId, questionId } = parsedInputResult.data;
+    const { fileName, fileType, surveyId } = parsedInputResult.data;

    const [survey, organizationId] = await Promise.all([
      getSurvey(surveyId),
@@ -109,7 +109,6 @@ export const POST = withV1ApiWrapper({

    const fileUploadPermission = validateSurveyAllowsFileUpload({
      fileName,
-      questionId,
      blocks: survey.blocks,
      questions: survey.questions,
    });
@@ -119,9 +118,7 @@ export const POST = withV1ApiWrapper({
        response: responses.badRequestResponse(
          fileUploadPermission.reason === "no_file_upload_question"
            ? "Survey does not allow file uploads"
-            : fileUploadPermission.reason === "file_upload_question_not_found"
-              ? "Question does not allow file uploads"
-              : "File extension is not allowed for this question",
+            : "File extension is not allowed for this survey",
          undefined
        ),
      };
@@ -137,8 +134,7 @@ export const POST = withV1ApiWrapper({
      workspaceId,
      fileType,
      "private",
-      maxFileUploadSize,
-      ["surveys", surveyId, "questions", questionId]
+      maxFileUploadSize
    );

    if (!signedUrlResponse.ok) {
@@ -15,7 +15,6 @@ import { formatValidationErrorsForV1Api, validateResponseData } from "@/modules/
 import { validateOtherOptionLengthForMultipleChoice } from "@/modules/api/v2/lib/element";
 import { getIsContactsEnabled } from "@/modules/ee/license-check/lib/utils";
 import { createQuotaFullObject } from "@/modules/ee/quotas/lib/helpers";
-import { validateClientFileUploads } from "@/modules/storage/utils";
 import { createResponseWithQuotaEvaluation } from "./lib/response";
 import { TResponseInputV2, ZResponseInputV2 } from "./types/response";

@@ -90,18 +89,6 @@ const validateResponseSubmission = async (
    return surveyCheckResult;
  }

-  if (
-    !validateClientFileUploads({
-      data: responseInputData.data,
-      workspaceId,
-      surveyId: survey.id,
-      blocks: survey.blocks,
-      questions: survey.questions,
-    })
-  ) {
-    return responses.badRequestResponse("Invalid file upload response", undefined, true);
-  }
-
  const otherResponseInvalidQuestionId = validateOtherOptionLengthForMultipleChoice({
    responseData: responseInputData.data,
    surveyQuestions: getElementsFromBlocks(survey.blocks),
@@ -135,7 +135,7 @@ describe("withV3ApiWrapper", () => {
      apiKeyId: "key_1",
      organizationId: "org_1",
      organizationAccess: { accessControl: { read: true, write: true } },
-      environmentPermissions: [],
+      workspacePermissions: [],
    });

    const wrapped = withV3ApiWrapper({
@@ -3,7 +3,7 @@ import { beforeEach, describe, expect, test, vi } from "vitest";
 import { AuthorizationError } from "@formbricks/types/errors";
 import { checkAuthorizationUpdated } from "@/lib/utils/action-client/action-client-middleware";
 import { getOrganizationIdFromWorkspaceId } from "@/lib/utils/helper";
-import { findWorkspaceByIdOrLegacyEnvId } from "@/lib/utils/resolve-client-id";
+import { getWorkspace } from "@/lib/workspace/service";
 import { requireSessionWorkspaceAccess, requireV3WorkspaceAccess } from "./auth";

 vi.mock("@formbricks/logger", () => ({
@@ -19,8 +19,8 @@ vi.mock("@/lib/utils/helper", () => ({
  getOrganizationIdFromWorkspaceId: vi.fn(),
 }));

-vi.mock("@/lib/utils/resolve-client-id", () => ({
-  findWorkspaceByIdOrLegacyEnvId: vi.fn(),
+vi.mock("@/lib/workspace/service", () => ({
+  getWorkspace: vi.fn(),
 }));

 vi.mock("@/lib/utils/action-client/action-client-middleware", () => ({
@@ -39,7 +39,7 @@ describe("requireSessionWorkspaceAccess", () => {
    expect(body.requestId).toBe(requestId);
    expect(body.status).toBe(401);
    expect(body.code).toBe("not_authenticated");
-    expect(findWorkspaceByIdOrLegacyEnvId).not.toHaveBeenCalled();
+    expect(getWorkspace).not.toHaveBeenCalled();
    expect(checkAuthorizationUpdated).not.toHaveBeenCalled();
  });

@@ -55,11 +55,11 @@ describe("requireSessionWorkspaceAccess", () => {
    const body = await (result as Response).json();
    expect(body.requestId).toBe(requestId);
    expect(body.code).toBe("not_authenticated");
-    expect(findWorkspaceByIdOrLegacyEnvId).not.toHaveBeenCalled();
+    expect(getWorkspace).not.toHaveBeenCalled();
  });

  test("returns 403 when workspace is not found (avoid leaking existence)", async () => {
-    vi.mocked(findWorkspaceByIdOrLegacyEnvId).mockResolvedValueOnce(null);
+    vi.mocked(getWorkspace).mockResolvedValueOnce(null);
    const result = await requireSessionWorkspaceAccess(
      { user: { id: "user_1" }, expires: "" } as any,
      "ws_nonexistent",
@@ -72,12 +72,12 @@ describe("requireSessionWorkspaceAccess", () => {
    const body = await (result as Response).json();
    expect(body.requestId).toBe(requestId);
    expect(body.code).toBe("forbidden");
-    expect(findWorkspaceByIdOrLegacyEnvId).toHaveBeenCalledWith("ws_nonexistent");
+    expect(getWorkspace).toHaveBeenCalledWith("ws_nonexistent");
    expect(checkAuthorizationUpdated).not.toHaveBeenCalled();
  });

  test("returns 403 when user has no access to workspace", async () => {
-    vi.mocked(findWorkspaceByIdOrLegacyEnvId).mockResolvedValueOnce({ id: "proj_abc" });
+    vi.mocked(getWorkspace).mockResolvedValueOnce({ id: "proj_abc" } as any);
    vi.mocked(getOrganizationIdFromWorkspaceId).mockResolvedValueOnce("org_1");
    vi.mocked(checkAuthorizationUpdated).mockRejectedValueOnce(new AuthorizationError("Not authorized"));
    const result = await requireSessionWorkspaceAccess(
@@ -102,7 +102,7 @@ describe("requireSessionWorkspaceAccess", () => {
  });

  test("returns workspace context when session is valid and user has access", async () => {
-    vi.mocked(findWorkspaceByIdOrLegacyEnvId).mockResolvedValueOnce({ id: "proj_abc" });
+    vi.mocked(getWorkspace).mockResolvedValueOnce({ id: "proj_abc" } as any);
    vi.mocked(getOrganizationIdFromWorkspaceId).mockResolvedValueOnce("org_1");
    vi.mocked(checkAuthorizationUpdated).mockResolvedValueOnce(undefined as any);
    const result = await requireSessionWorkspaceAccess(
@@ -144,7 +144,7 @@ function wsPerm(workspaceId: string, permission: ApiKeyPermission = ApiKeyPermis

 describe("requireV3WorkspaceAccess", () => {
  beforeEach(() => {
-    vi.mocked(findWorkspaceByIdOrLegacyEnvId).mockResolvedValue({ id: "proj_k" });
+    vi.mocked(getWorkspace).mockResolvedValue({ id: "proj_k" } as any);
    vi.mocked(getOrganizationIdFromWorkspaceId).mockResolvedValue("org_k");
  });

@@ -154,7 +154,7 @@ describe("requireV3WorkspaceAccess", () => {
  });

  test("delegates to session flow when user is present", async () => {
-    vi.mocked(findWorkspaceByIdOrLegacyEnvId).mockResolvedValueOnce({ id: "proj_s" });
+    vi.mocked(getWorkspace).mockResolvedValueOnce({ id: "proj_s" } as any);
    vi.mocked(getOrganizationIdFromWorkspaceId).mockResolvedValueOnce("org_s");
    vi.mocked(checkAuthorizationUpdated).mockResolvedValueOnce(undefined as any);
    const r = await requireV3WorkspaceAccess(
@@ -179,7 +179,7 @@ describe("requireV3WorkspaceAccess", () => {
      workspaceId: "proj_k",
      organizationId: "org_k",
    });
-    expect(findWorkspaceByIdOrLegacyEnvId).toHaveBeenCalledWith("proj_k");
+    expect(getWorkspace).toHaveBeenCalledWith("proj_k");
  });

  test("returns context for API key with write on workspace", async () => {
@@ -239,7 +239,7 @@ describe("requireV3WorkspaceAccess", () => {
  });

  test("returns 403 when the workspace cannot be resolved for an API key", async () => {
-    vi.mocked(findWorkspaceByIdOrLegacyEnvId).mockResolvedValueOnce(null);
+    vi.mocked(getWorkspace).mockResolvedValueOnce(null);
    const auth = {
      ...keyBase,
      workspacePermissions: [wsPerm("proj_k", ApiKeyPermission.manage)],
@@ -1,5 +1,7 @@
 import { describe, expect, test } from "vitest";
 import {
+  createdResponse,
+  noContentResponse,
  problemBadRequest,
  problemForbidden,
  problemInternalError,
@@ -118,3 +120,34 @@ describe("successResponse", () => {
    expect(res.headers.get("Cache-Control")).toBe("private, max-age=60");
  });
 });
+
+describe("createdResponse", () => {
+  test("returns 201 with Location, request id, and data envelope", async () => {
+    const res = createdResponse(
+      { id: "survey_1" },
+      {
+        location: "/api/v3/surveys/survey_1",
+        requestId: "req-created",
+      }
+    );
+
+    expect(res.status).toBe(201);
+    expect(res.headers.get("Location")).toBe("/api/v3/surveys/survey_1");
+    expect(res.headers.get("X-Request-Id")).toBe("req-created");
+    expect(res.headers.get("Content-Type")).toBe("application/json");
+    expect(res.headers.get("Cache-Control")).toContain("no-store");
+    expect(await res.json()).toEqual({
+      data: { id: "survey_1" },
+    });
+  });
+});
+
+describe("noContentResponse", () => {
+  test("returns 204 without a body", async () => {
+    const res = noContentResponse({ requestId: "req-empty" });
+    expect(res.status).toBe(204);
+    expect(res.headers.get("X-Request-Id")).toBe("req-empty");
+    expect(res.headers.get("Cache-Control")).toContain("no-store");
+    expect(await res.text()).toBe("");
+  });
+});
@@ -171,3 +171,43 @@ export function successResponse<T>(
    }
  );
 }
+
+export function createdResponse<T>(
+  data: T,
+  options: { location: string; requestId?: string; cache?: string }
+): Response {
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+    "Cache-Control": options.cache ?? CACHE_NO_STORE,
+    Location: options.location,
+  };
+
+  if (options.requestId) {
+    headers["X-Request-Id"] = options.requestId;
+  }
+
+  return Response.json(
+    {
+      data,
+    },
+    {
+      status: 201,
+      headers,
+    }
+  );
+}
+
+export function noContentResponse(options?: { requestId?: string; cache?: string }): Response {
+  const headers: Record<string, string> = {
+    "Cache-Control": options?.cache ?? CACHE_NO_STORE,
+  };
+
+  if (options?.requestId) {
+    headers["X-Request-Id"] = options.requestId;
+  }
+
+  return new Response(null, {
+    status: 204,
+    headers,
+  });
+}
@@ -1,45 +1,34 @@
 import { describe, expect, test, vi } from "vitest";
 import { ResourceNotFoundError } from "@formbricks/types/errors";
 import { getOrganizationIdFromWorkspaceId } from "@/lib/utils/helper";
-import { findWorkspaceByIdOrLegacyEnvId } from "@/lib/utils/resolve-client-id";
+import { getWorkspace } from "@/lib/workspace/service";
 import { resolveV3WorkspaceContext } from "./workspace-context";

+vi.mock("@/lib/workspace/service", () => ({
+  getWorkspace: vi.fn(),
+}));
+
 vi.mock("@/lib/utils/helper", () => ({
  getOrganizationIdFromWorkspaceId: vi.fn(),
 }));

-vi.mock("@/lib/utils/resolve-client-id", () => ({
-  findWorkspaceByIdOrLegacyEnvId: vi.fn(),
-}));
-
 describe("resolveV3WorkspaceContext", () => {
  test("returns workspaceId and organizationId when workspace exists", async () => {
-    vi.mocked(findWorkspaceByIdOrLegacyEnvId).mockResolvedValueOnce({ id: "ws_abc" });
+    vi.mocked(getWorkspace).mockResolvedValueOnce({ id: "ws_abc" });
    vi.mocked(getOrganizationIdFromWorkspaceId).mockResolvedValueOnce("org_123");
    const result = await resolveV3WorkspaceContext("ws_abc");
    expect(result).toEqual({
      workspaceId: "ws_abc",
      organizationId: "org_123",
    });
-    expect(findWorkspaceByIdOrLegacyEnvId).toHaveBeenCalledWith("ws_abc");
+    expect(getWorkspace).toHaveBeenCalledWith("ws_abc");
    expect(getOrganizationIdFromWorkspaceId).toHaveBeenCalledWith("ws_abc");
  });

-  test("resolves legacy environmentId to canonical workspaceId", async () => {
-    vi.mocked(findWorkspaceByIdOrLegacyEnvId).mockResolvedValueOnce({ id: "ws_canonical" });
-    vi.mocked(getOrganizationIdFromWorkspaceId).mockResolvedValueOnce("org_456");
-    const result = await resolveV3WorkspaceContext("env_legacy");
-    expect(result).toEqual({
-      workspaceId: "ws_canonical",
-      organizationId: "org_456",
-    });
-    expect(getOrganizationIdFromWorkspaceId).toHaveBeenCalledWith("ws_canonical");
-  });
-
  test("throws when workspace does not exist", async () => {
-    vi.mocked(findWorkspaceByIdOrLegacyEnvId).mockResolvedValueOnce(null);
+    vi.mocked(getWorkspace).mockResolvedValueOnce(null);
    await expect(resolveV3WorkspaceContext("ws_nonexistent")).rejects.toThrow(ResourceNotFoundError);
-    expect(findWorkspaceByIdOrLegacyEnvId).toHaveBeenCalledWith("ws_nonexistent");
+    expect(getWorkspace).toHaveBeenCalledWith("ws_nonexistent");
    expect(getOrganizationIdFromWorkspaceId).not.toHaveBeenCalled();
  });
 });
@@ -6,7 +6,7 @@
 */
 import { ResourceNotFoundError } from "@formbricks/types/errors";
 import { getOrganizationIdFromWorkspaceId } from "@/lib/utils/helper";
-import { findWorkspaceByIdOrLegacyEnvId } from "@/lib/utils/resolve-client-id";
+import { getWorkspace } from "@/lib/workspace/service";

 /**
 * Internal IDs derived from a V3 workspace identifier.
@@ -19,21 +19,20 @@ export type V3WorkspaceContext = {
 };

 /**
- * Resolves a V3 API workspaceId (or legacy environmentId) to internal workspaceId and organizationId.
+ * Resolves a V3 API workspaceId to internal workspaceId and organizationId.
 *
 * @throws ResourceNotFoundError if the workspace does not exist.
 */
 export async function resolveV3WorkspaceContext(workspaceId: string): Promise<V3WorkspaceContext> {
-  const workspace = await findWorkspaceByIdOrLegacyEnvId(workspaceId);
+  const workspace = await getWorkspace(workspaceId);
  if (!workspace) {
    throw new ResourceNotFoundError("workspace", workspaceId);
  }

-  const canonicalId = workspace.id;
-  const organizationId = await getOrganizationIdFromWorkspaceId(canonicalId);
+  const organizationId = await getOrganizationIdFromWorkspaceId(workspace.id);

  return {
-    workspaceId: canonicalId,
+    workspaceId: workspace.id,
    organizationId,
  };
 }
@@ -1,318 +0,0 @@
-import { ApiKeyPermission } from "@prisma/client";
-import { NextRequest } from "next/server";
-import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
-import { DatabaseError, ResourceNotFoundError } from "@formbricks/types/errors";
-import { requireV3WorkspaceAccess } from "@/app/api/v3/lib/auth";
-import { getSurvey } from "@/lib/survey/service";
-import { deleteSurvey } from "@/modules/survey/lib/surveys";
-import { DELETE } from "./route";
-
-const { mockAuthenticateRequest } = vi.hoisted(() => ({
-  mockAuthenticateRequest: vi.fn(),
-}));
-
-const { mockQueueAuditEvent, mockBuildAuditLogBaseObject } = vi.hoisted(() => ({
-  mockQueueAuditEvent: vi.fn().mockImplementation(async () => undefined),
-  mockBuildAuditLogBaseObject: vi.fn((action: string, targetType: string, apiUrl: string) => ({
-    action,
-    targetType,
-    userId: "unknown",
-    targetId: "unknown",
-    organizationId: "unknown",
-    status: "failure",
-    oldObject: undefined,
-    newObject: undefined,
-    userType: "api",
-    apiUrl,
-  })),
-}));
-
-vi.mock("next-auth", () => ({
-  getServerSession: vi.fn(),
-}));
-
-vi.mock("@/app/api/v1/auth", async (importOriginal) => {
-  const actual = await importOriginal<typeof import("@/app/api/v1/auth")>();
-  return { ...actual, authenticateRequest: mockAuthenticateRequest };
-});
-
-vi.mock("@/modules/core/rate-limit/helpers", () => ({
-  applyRateLimit: vi.fn().mockResolvedValue(undefined),
-  applyIPRateLimit: vi.fn().mockResolvedValue(undefined),
-}));
-
-vi.mock("@/lib/constants", async (importOriginal) => {
-  const actual = await importOriginal<typeof import("@/lib/constants")>();
-  return { ...actual, AUDIT_LOG_ENABLED: false };
-});
-
-vi.mock("@/app/api/v3/lib/auth", () => ({
-  requireV3WorkspaceAccess: vi.fn(),
-}));
-
-vi.mock("@/lib/survey/service", () => ({
-  getSurvey: vi.fn(),
-}));
-
-vi.mock("@/modules/survey/lib/surveys", () => ({
-  deleteSurvey: vi.fn(),
-}));
-
-vi.mock("@/modules/ee/audit-logs/lib/handler", () => ({
-  queueAuditEvent: mockQueueAuditEvent,
-}));
-
-vi.mock("@/app/lib/api/with-api-logging", () => ({
-  buildAuditLogBaseObject: mockBuildAuditLogBaseObject,
-}));
-
-vi.mock("@formbricks/logger", () => ({
-  logger: {
-    withContext: vi.fn(() => ({
-      warn: vi.fn(),
-      error: vi.fn(),
-    })),
-  },
-}));
-
-const getServerSession = vi.mocked((await import("next-auth")).getServerSession);
-const queueAuditEvent = vi.mocked((await import("@/modules/ee/audit-logs/lib/handler")).queueAuditEvent);
-
-const surveyId = "clxx1234567890123456789012";
-const workspaceId = "clzz9876543210987654321098";
-
-function createRequest(url: string, requestId?: string, extraHeaders?: Record<string, string>): NextRequest {
-  const headers: Record<string, string> = { ...extraHeaders };
-  if (requestId) {
-    headers["x-request-id"] = requestId;
-  }
-
-  return new NextRequest(url, {
-    method: "DELETE",
-    headers,
-  });
-}
-
-const apiKeyAuth = {
-  type: "apiKey" as const,
-  apiKeyId: "key_1",
-  organizationId: "org_1",
-  organizationAccess: {
-    accessControl: { read: true, write: true },
-  },
-  workspacePermissions: [
-    {
-      workspaceId,
-      workspaceName: "W",
-      permission: ApiKeyPermission.write,
-    },
-  ],
-};
-
-describe("DELETE /api/v3/surveys/[surveyId]", () => {
-  beforeEach(() => {
-    vi.resetAllMocks();
-    getServerSession.mockResolvedValue({
-      user: { id: "user_1", name: "User", email: "u@example.com" },
-      expires: "2026-01-01",
-    } as any);
-    mockAuthenticateRequest.mockResolvedValue(null);
-    vi.mocked(getSurvey).mockResolvedValue({
-      id: surveyId,
-      name: "Delete me",
-      workspaceId: workspaceId,
-      type: "link",
-      status: "draft",
-      createdAt: new Date("2026-04-15T10:00:00.000Z"),
-      updatedAt: new Date("2026-04-15T10:00:00.000Z"),
-      responseCount: 0,
-      creator: { name: "User" },
-      singleUse: null,
-    } as any);
-    vi.mocked(deleteSurvey).mockResolvedValue({
-      id: surveyId,
-      workspaceId,
-      type: "link",
-      segment: null,
-      triggers: [],
-    } as any);
-    vi.mocked(requireV3WorkspaceAccess).mockResolvedValue({
-      workspaceId,
-      organizationId: "org_1",
-    });
-  });
-
-  afterEach(() => {
-    vi.clearAllMocks();
-  });
-
-  test("returns 401 when no session and no API key", async () => {
-    getServerSession.mockResolvedValue(null);
-    mockAuthenticateRequest.mockResolvedValue(null);
-
-    const res = await DELETE(createRequest(`http://localhost/api/v3/surveys/${surveyId}`), {
-      params: Promise.resolve({ surveyId }),
-    } as never);
-
-    expect(res.status).toBe(401);
-    expect(vi.mocked(getSurvey)).not.toHaveBeenCalled();
-  });
-
-  test("returns 200 with session auth and deletes the survey", async () => {
-    const res = await DELETE(createRequest(`http://localhost/api/v3/surveys/${surveyId}`, "req-delete"), {
-      params: Promise.resolve({ surveyId }),
-    } as never);
-
-    expect(res.status).toBe(200);
-    expect(requireV3WorkspaceAccess).toHaveBeenCalledWith(
-      expect.objectContaining({ user: expect.any(Object) }),
-      workspaceId,
-      "readWrite",
-      "req-delete",
-      `/api/v3/surveys/${surveyId}`
-    );
-    expect(deleteSurvey).toHaveBeenCalledWith(surveyId);
-    expect(await res.json()).toEqual({
-      data: {
-        id: surveyId,
-      },
-    });
-  });
-
-  test("returns 200 with x-api-key when the key can delete in the survey workspace", async () => {
-    getServerSession.mockResolvedValue(null);
-    mockAuthenticateRequest.mockResolvedValue(apiKeyAuth as any);
-
-    const res = await DELETE(
-      createRequest(`http://localhost/api/v3/surveys/${surveyId}`, "req-api-key", {
-        "x-api-key": "fbk_test",
-      }),
-      {
-        params: Promise.resolve({ surveyId }),
-      } as never
-    );
-
-    expect(res.status).toBe(200);
-    expect(requireV3WorkspaceAccess).toHaveBeenCalledWith(
-      expect.objectContaining({ apiKeyId: "key_1" }),
-      workspaceId,
-      "readWrite",
-      "req-api-key",
-      `/api/v3/surveys/${surveyId}`
-    );
-  });
-
-  test("returns 400 when surveyId is invalid", async () => {
-    const res = await DELETE(createRequest("http://localhost/api/v3/surveys/not-a-cuid"), {
-      params: Promise.resolve({ surveyId: "not-a-cuid" }),
-    } as never);
-
-    expect(res.status).toBe(400);
-    expect(vi.mocked(getSurvey)).not.toHaveBeenCalled();
-  });
-
-  test("returns 403 when the survey does not exist", async () => {
-    vi.mocked(getSurvey).mockResolvedValueOnce(null);
-
-    const res = await DELETE(createRequest(`http://localhost/api/v3/surveys/${surveyId}`), {
-      params: Promise.resolve({ surveyId }),
-    } as never);
-
-    expect(res.status).toBe(403);
-    expect(deleteSurvey).not.toHaveBeenCalled();
-  });
-
-  test("returns 403 when the user lacks readWrite workspace access", async () => {
-    vi.mocked(requireV3WorkspaceAccess).mockResolvedValueOnce(
-      new Response(
-        JSON.stringify({
-          title: "Forbidden",
-          status: 403,
-          detail: "You are not authorized to access this resource",
-          requestId: "req-forbidden",
-        }),
-        { status: 403, headers: { "Content-Type": "application/problem+json" } }
-      )
-    );
-
-    const res = await DELETE(createRequest(`http://localhost/api/v3/surveys/${surveyId}`, "req-forbidden"), {
-      params: Promise.resolve({ surveyId }),
-    } as never);
-
-    expect(res.status).toBe(403);
-    expect(deleteSurvey).not.toHaveBeenCalled();
-    expect(queueAuditEvent).toHaveBeenCalledWith(
-      expect.objectContaining({
-        action: "deleted",
-        targetType: "survey",
-        targetId: "unknown",
-        organizationId: "unknown",
-        userId: "user_1",
-        userType: "user",
-        status: "failure",
-        oldObject: undefined,
-      })
-    );
-  });
-
-  test("returns 500 when survey deletion fails", async () => {
-    vi.mocked(deleteSurvey).mockRejectedValueOnce(new DatabaseError("db down"));
-
-    const res = await DELETE(createRequest(`http://localhost/api/v3/surveys/${surveyId}`, "req-db"), {
-      params: Promise.resolve({ surveyId }),
-    } as never);
-
-    expect(res.status).toBe(500);
-    const body = await res.json();
-    expect(body.code).toBe("internal_server_error");
-  });
-
-  test("returns 403 when the survey is deleted after authorization succeeds", async () => {
-    vi.mocked(deleteSurvey).mockRejectedValueOnce(new ResourceNotFoundError("Survey", surveyId));
-
-    const res = await DELETE(createRequest(`http://localhost/api/v3/surveys/${surveyId}`, "req-race"), {
-      params: Promise.resolve({ surveyId }),
-    } as never);
-
-    expect(res.status).toBe(403);
-    const body = await res.json();
-    expect(body.code).toBe("forbidden");
-    expect(queueAuditEvent).toHaveBeenCalledWith(
-      expect.objectContaining({
-        action: "deleted",
-        targetType: "survey",
-        targetId: surveyId,
-        organizationId: "org_1",
-        userId: "user_1",
-        userType: "user",
-        status: "failure",
-        oldObject: expect.objectContaining({
-          id: surveyId,
-          workspaceId: workspaceId,
-        }),
-      })
-    );
-  });
-
-  test("queues an audit log with target, actor, organization, and old object", async () => {
-    await DELETE(createRequest(`http://localhost/api/v3/surveys/${surveyId}`, "req-audit"), {
-      params: Promise.resolve({ surveyId }),
-    } as never);
-
-    expect(queueAuditEvent).toHaveBeenCalledWith(
-      expect.objectContaining({
-        action: "deleted",
-        targetType: "survey",
-        targetId: surveyId,
-        organizationId: "org_1",
-        userId: "user_1",
-        userType: "user",
-        status: "success",
-        oldObject: expect.objectContaining({
-          id: surveyId,
-          workspaceId: workspaceId,
-        }),
-      })
-    );
-  });
-});
@@ -2,42 +2,140 @@ import { z } from "zod";
 import { logger } from "@formbricks/logger";
 import { DatabaseError, ResourceNotFoundError } from "@formbricks/types/errors";
 import { withV3ApiWrapper } from "@/app/api/v3/lib/api-wrapper";
-import { requireV3WorkspaceAccess } from "@/app/api/v3/lib/auth";
-import { problemForbidden, problemInternalError, successResponse } from "@/app/api/v3/lib/response";
-import { getSurvey } from "@/lib/survey/service";
+import {
+  noContentResponse,
+  problemBadRequest,
+  problemForbidden,
+  problemInternalError,
+  successResponse,
+} from "@/app/api/v3/lib/response";
+import {
+  V3SurveyLanguageError,
+  V3SurveyUnsupportedShapeError,
+  serializeV3SurveyResource,
+} from "@/app/api/v3/surveys/serializers";
 import { deleteSurvey } from "@/modules/survey/lib/surveys";
+import { getAuthorizedV3Survey } from "../authorization";
+import { parseV3SurveyLanguageQuery } from "../language";
+
+const surveyParamsSchema = z.object({
+  surveyId: z.cuid2(),
+});
+
+const surveyQuerySchema = z
+  .object({
+    lang: z
+      .union([z.string(), z.array(z.string())])
+      .transform((value, ctx) => {
+        const parsedLanguageQuery = parseV3SurveyLanguageQuery(value);
+
+        if (!parsedLanguageQuery.ok) {
+          ctx.addIssue({
+            code: "custom",
+            message: parsedLanguageQuery.message,
+          });
+          return z.NEVER;
+        }
+
+        return parsedLanguageQuery.languages;
+      })
+      .optional(),
+  })
+  .strict();
+
+export const GET = withV3ApiWrapper({
+  auth: "both",
+  schemas: {
+    params: surveyParamsSchema,
+    query: surveyQuerySchema,
+  },
+  handler: async ({ parsedInput, authentication, requestId, instance }) => {
+    const surveyId = parsedInput.params.surveyId;
+    const log = logger.withContext({ requestId, surveyId });
+
+    try {
+      const { survey, response } = await getAuthorizedV3Survey({
+        surveyId,
+        authentication,
+        access: "read",
+        requestId,
+        instance,
+      });
+
+      if (response) {
+        log.warn({ statusCode: response.status }, "Survey not found or not accessible");
+        return response;
+      }
+
+      try {
+        return successResponse(serializeV3SurveyResource(survey, { lang: parsedInput.query.lang }), {
+          requestId,
+          cache: "private, no-store",
+        });
+      } catch (error) {
+        if (error instanceof V3SurveyLanguageError) {
+          log.warn({ statusCode: 400, lang: parsedInput.query.lang }, "Invalid survey language selector");
+          return problemBadRequest(requestId, error.message, {
+            instance,
+            invalid_params: [
+              {
+                name: "lang",
+                reason: error.message,
+              },
+            ],
+          });
+        }
+
+        if (error instanceof V3SurveyUnsupportedShapeError) {
+          log.warn({ statusCode: 400 }, "Unsupported v3 survey shape");
+          return problemBadRequest(requestId, error.message, {
+            instance,
+            invalid_params: [
+              {
+                name: "survey",
+                reason: error.message,
+              },
+            ],
+          });
+        }
+
+        throw error;
+      }
+    } catch (error) {
+      if (error instanceof DatabaseError) {
+        log.error({ error, statusCode: 500 }, "Database error");
+        return problemInternalError(requestId, "An unexpected error occurred.", instance);
+      }
+
+      log.error({ error, statusCode: 500 }, "V3 survey get unexpected error");
+      return problemInternalError(requestId, "An unexpected error occurred.", instance);
+    }
+  },
+});

 export const DELETE = withV3ApiWrapper({
  auth: "both",
  action: "deleted",
  targetType: "survey",
  schemas: {
-    params: z.object({
-      surveyId: z.cuid2(),
-    }),
+    params: surveyParamsSchema,
  },
  handler: async ({ parsedInput, authentication, requestId, instance, auditLog }) => {
    const surveyId = parsedInput.params.surveyId;
    const log = logger.withContext({ requestId, surveyId });

    try {
-      const survey = await getSurvey(surveyId);
-
-      if (!survey) {
-        log.warn({ statusCode: 403 }, "Survey not found or not accessible");
-        return problemForbidden(requestId, "You are not authorized to access this resource", instance);
-      }
-
-      const authResult = await requireV3WorkspaceAccess(
+      const { survey, authResult, response } = await getAuthorizedV3Survey({
+        surveyId,
        authentication,
-        survey.workspaceId,
-        "readWrite",
+        access: "readWrite",
        requestId,
-        instance
-      );
+        instance,
+      });

-      if (authResult instanceof Response) {
-        return authResult;
+      if (response) {
+        log.warn({ statusCode: 403 }, "Survey not found or not accessible");
+        return response;
      }

      if (auditLog) {
@@ -46,14 +144,9 @@ export const DELETE = withV3ApiWrapper({
        auditLog.oldObject = survey;
      }

-      const deletedSurvey = await deleteSurvey(surveyId);
+      await deleteSurvey(surveyId);

-      return successResponse(
-        {
-          id: deletedSurvey.id,
-        },
-        { requestId }
-      );
+      return noContentResponse({ requestId });
    } catch (error) {
      if (error instanceof ResourceNotFoundError) {
        log.warn({ errorCode: error.name, statusCode: 403 }, "Survey not found or not accessible");
@@ -0,0 +1,71 @@
+import { describe, expect, test, vi } from "vitest";
+import { requireV3WorkspaceAccess } from "@/app/api/v3/lib/auth";
+import { getSurvey } from "@/lib/survey/service";
+import { getAuthorizedV3Survey } from "./authorization";
+
+vi.mock("@/app/api/v3/lib/auth", () => ({
+  requireV3WorkspaceAccess: vi.fn(),
+}));
+
+vi.mock("@/lib/survey/service", () => ({
+  getSurvey: vi.fn(),
+}));
+
+const survey = {
+  id: "clsv1234567890123456789012",
+  workspaceId: "clxx1234567890123456789012",
+};
+const surveyRecord = survey as unknown as NonNullable<Awaited<ReturnType<typeof getSurvey>>>;
+
+describe("getAuthorizedV3Survey", () => {
+  test("returns a generic forbidden response when the survey does not exist", async () => {
+    vi.mocked(getSurvey).mockResolvedValue(null);
+
+    const result = await getAuthorizedV3Survey({
+      surveyId: survey.id,
+      authentication: null,
+      access: "read",
+      requestId: "req_1",
+      instance: "/api/v3/surveys/clsv1234567890123456789012",
+    });
+
+    expect(result.response?.status).toBe(403);
+    expect(requireV3WorkspaceAccess).not.toHaveBeenCalled();
+  });
+
+  test("returns the authorization response when workspace access is denied", async () => {
+    const forbiddenResponse = new Response(null, { status: 403 });
+    vi.mocked(getSurvey).mockResolvedValue(surveyRecord);
+    vi.mocked(requireV3WorkspaceAccess).mockResolvedValue(forbiddenResponse);
+
+    const result = await getAuthorizedV3Survey({
+      surveyId: survey.id,
+      authentication: null,
+      access: "readWrite",
+      requestId: "req_2",
+      instance: "/api/v3/surveys/clsv1234567890123456789012",
+    });
+
+    expect(result.response).toBe(forbiddenResponse);
+  });
+
+  test("returns the survey and authorization context when access is allowed", async () => {
+    const authResult = { workspaceId: survey.workspaceId, organizationId: "org_1" };
+    vi.mocked(getSurvey).mockResolvedValue(surveyRecord);
+    vi.mocked(requireV3WorkspaceAccess).mockResolvedValue(authResult);
+
+    const result = await getAuthorizedV3Survey({
+      surveyId: survey.id,
+      authentication: null,
+      access: "read",
+      requestId: "req_3",
+      instance: "/api/v3/surveys/clsv1234567890123456789012",
+    });
+
+    expect(result).toEqual({
+      survey,
+      authResult,
+      response: null,
+    });
+  });
+});
@@ -0,0 +1,37 @@
+import { requireV3WorkspaceAccess } from "@/app/api/v3/lib/auth";
+import { problemForbidden } from "@/app/api/v3/lib/response";
+import type { TV3Authentication } from "@/app/api/v3/lib/types";
+import { getSurvey } from "@/lib/survey/service";
+
+export async function getAuthorizedV3Survey(params: {
+  surveyId: string;
+  authentication: TV3Authentication;
+  access: "read" | "readWrite";
+  requestId: string;
+  instance: string;
+}) {
+  const { surveyId, authentication, access, requestId, instance } = params;
+  const survey = await getSurvey(surveyId);
+
+  if (!survey) {
+    return {
+      survey: null,
+      authResult: null,
+      response: problemForbidden(requestId, "You are not authorized to access this resource", instance),
+    };
+  }
+
+  const authResult = await requireV3WorkspaceAccess(
+    authentication,
+    survey.workspaceId,
+    access,
+    requestId,
+    instance
+  );
+
+  if (authResult instanceof Response) {
+    return { survey: null, authResult: null, response: authResult };
+  }
+
+  return { survey, authResult, response: null };
+}
@@ -0,0 +1,241 @@
+import { beforeEach, describe, expect, test, vi } from "vitest";
+import { prisma } from "@formbricks/database";
+import type { TSurvey } from "@formbricks/types/surveys/types";
+import { getOrganizationByWorkspaceId } from "@/lib/organization/service";
+import { createSurvey } from "@/lib/survey/service";
+import { getExternalUrlsPermission } from "@/modules/survey/lib/permission";
+import { V3SurveyCreatePermissionError, createV3Survey } from "./create";
+import { ZV3CreateSurveyBody } from "./schemas";
+
+vi.mock("server-only", () => ({}));
+
+vi.mock("@formbricks/database", () => ({
+  prisma: {
+    language: {
+      upsert: vi.fn(),
+    },
+  },
+}));
+
+vi.mock("@/lib/survey/service", () => ({
+  createSurvey: vi.fn(),
+}));
+
+vi.mock("@/lib/organization/service", () => ({
+  getOrganizationByWorkspaceId: vi.fn(),
+}));
+
+vi.mock("@/modules/survey/lib/permission", () => ({
+  getExternalUrlsPermission: vi.fn(),
+}));
+
+vi.mock("@formbricks/logger", () => ({
+  logger: {
+    withContext: vi.fn(() => ({
+      error: vi.fn(),
+      warn: vi.fn(),
+    })),
+  },
+}));
+
+const workspaceId = "clxx1234567890123456789012";
+
+const rawCreateBody = {
+  workspaceId,
+  name: "Product Feedback",
+  defaultLanguage: "en-US",
+  metadata: {
+    cx_operation: "enterprise_onboarding",
+    title: { "en-US": "Product Feedback", "de-DE": "Produktfeedback" },
+  },
+  blocks: [
+    {
+      id: "clbk1234567890123456789012",
+      name: "Main Block",
+      elements: [
+        {
+          id: "satisfaction",
+          type: "openText",
+          headline: {
+            "en-US": "What should we improve?",
+            "de-DE": "Was sollen wir verbessern?",
+          },
+          required: true,
+        },
+      ],
+    },
+  ],
+};
+
+const createBody = ZV3CreateSurveyBody.parse(rawCreateBody);
+
+const createdSurvey = {
+  id: "clsv1234567890123456789012",
+  workspaceId,
+  createdAt: new Date("2026-04-21T10:00:00.000Z"),
+  updatedAt: new Date("2026-04-21T10:00:00.000Z"),
+  name: "Product Feedback",
+  type: "link",
+  status: "draft",
+  metadata: {},
+  languages: [],
+  questions: [],
+  welcomeCard: { enabled: false },
+  blocks: createBody.blocks,
+  endings: [],
+  hiddenFields: { enabled: false },
+  variables: [],
+} as unknown as TSurvey;
+
+type TLanguageUpsertArgs = Parameters<typeof prisma.language.upsert>[0];
+type TLanguageUpsertReturn = ReturnType<typeof prisma.language.upsert>;
+
+describe("createV3Survey", () => {
+  beforeEach(() => {
+    vi.resetAllMocks();
+    vi.mocked(prisma.language.upsert).mockImplementation(
+      (args: TLanguageUpsertArgs): TLanguageUpsertReturn => {
+        const workspaceIdCode = args.where.workspaceId_code;
+        if (!workspaceIdCode) {
+          throw new Error("Expected workspaceId_code upsert selector");
+        }
+
+        return Promise.resolve({
+          id: `cllang${workspaceIdCode.code.toLowerCase().replaceAll("-", "")}`,
+          code: workspaceIdCode.code,
+          alias: null,
+          workspaceId: workspaceIdCode.workspaceId,
+          createdAt: new Date("2026-04-21T10:00:00.000Z"),
+          updatedAt: new Date("2026-04-21T10:00:00.000Z"),
+        }) as TLanguageUpsertReturn;
+      }
+    );
+    vi.mocked(createSurvey).mockResolvedValue(createdSurvey);
+    vi.mocked(getOrganizationByWorkspaceId).mockResolvedValue({
+      id: "org_1",
+      name: "Organization",
+      createdAt: new Date(),
+      updatedAt: new Date(),
+      billing: {
+        limits: { monthly: { responses: 1000 }, workspaces: 1 },
+        stripeCustomerId: null,
+        usageCycleAnchor: null,
+      },
+      isAISmartToolsEnabled: false,
+      isAIDataAnalysisEnabled: false,
+      whitelabel: undefined,
+    });
+    vi.mocked(getExternalUrlsPermission).mockResolvedValue(true);
+  });
+
+  test("maps the public v3 body to the internal create payload", async () => {
+    await createV3Survey(
+      createBody,
+      {
+        user: { id: "user_1", email: "user@example.com", name: "User" },
+        expires: "2026-05-01",
+      },
+      "req_1"
+    );
+
+    expect(prisma.language.upsert).toHaveBeenCalledWith(
+      expect.objectContaining({
+        where: { workspaceId_code: { workspaceId, code: "en-US" } },
+        create: { workspaceId, code: "en-US", alias: null },
+      })
+    );
+    expect(prisma.language.upsert).toHaveBeenCalledWith(
+      expect.objectContaining({
+        where: { workspaceId_code: { workspaceId, code: "de-DE" } },
+        create: { workspaceId, code: "de-DE", alias: null },
+      })
+    );
+    expect(createSurvey).toHaveBeenCalledWith(
+      workspaceId,
+      expect.objectContaining({
+        name: "Product Feedback",
+        type: "link",
+        status: "draft",
+        createdBy: "user_1",
+        questions: [],
+        metadata: expect.objectContaining({
+          cx_operation: "enterprise_onboarding",
+          title: { default: "Product Feedback", "de-DE": "Produktfeedback" },
+        }),
+        blocks: [
+          expect.objectContaining({
+            elements: [
+              expect.objectContaining({
+                headline: {
+                  default: "What should we improve?",
+                  "de-DE": "Was sollen wir verbessern?",
+                },
+              }),
+            ],
+          }),
+        ],
+        languages: [
+          expect.objectContaining({ default: true, enabled: true }),
+          expect.objectContaining({ default: false, enabled: true }),
+        ],
+      })
+    );
+    expect(getOrganizationByWorkspaceId).not.toHaveBeenCalled();
+    expect(getExternalUrlsPermission).not.toHaveBeenCalled();
+  });
+
+  test("keeps createdBy null for API key calls and honors explicit disabled languages", async () => {
+    const body = ZV3CreateSurveyBody.parse({
+      ...rawCreateBody,
+      languages: [{ code: "fr-FR", enabled: false }],
+    });
+
+    await createV3Survey(
+      body,
+      {
+        type: "apiKey",
+        apiKeyId: "key_1",
+        organizationId: "org_1",
+        organizationAccess: { accessControl: { read: true, write: true } },
+        workspacePermissions: [],
+      },
+      "req_2"
+    );
+
+    expect(createSurvey).toHaveBeenCalledWith(
+      workspaceId,
+      expect.objectContaining({
+        createdBy: null,
+        languages: expect.arrayContaining([
+          expect.objectContaining({ language: expect.objectContaining({ code: "fr-FR" }), enabled: false }),
+        ]),
+      })
+    );
+  });
+
+  test("rejects external CTA buttons when the organization does not have external URL permission", async () => {
+    vi.mocked(getExternalUrlsPermission).mockResolvedValue(false);
+    const body = ZV3CreateSurveyBody.parse({
+      ...rawCreateBody,
+      blocks: [
+        {
+          ...rawCreateBody.blocks[0],
+          elements: [
+            {
+              id: "external_cta",
+              type: "cta",
+              headline: { "en-US": "Continue" },
+              required: false,
+              buttonExternal: true,
+              buttonUrl: "https://example.com",
+              ctaButtonLabel: { "en-US": "Open" },
+            },
+          ],
+        },
+      ],
+    });
+
+    await expect(createV3Survey(body, null, "req_3")).rejects.toThrow(V3SurveyCreatePermissionError);
+    expect(createSurvey).not.toHaveBeenCalled();
+  });
+});
@@ -0,0 +1,106 @@
+import "server-only";
+import type { TSurveyCreateInput } from "@formbricks/types/surveys/types";
+import type { TV3Authentication } from "@/app/api/v3/lib/types";
+import { getOrganizationByWorkspaceId } from "@/lib/organization/service";
+import { createSurvey } from "@/lib/survey/service";
+import { getElementsFromBlocks } from "@/lib/survey/utils";
+import { getExternalUrlsPermission } from "@/modules/survey/lib/permission";
+import { type TV3SurveyLanguageRequest, ensureV3WorkspaceLanguages } from "./languages";
+import { prepareV3SurveyCreate } from "./prepare";
+import { V3SurveyReferenceValidationError } from "./reference-validation";
+import type { TV3CreateSurveyBody } from "./schemas";
+
+export class V3SurveyCreatePermissionError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "V3SurveyCreatePermissionError";
+  }
+}
+
+function getCreatedBy(authentication: TV3Authentication): string | null {
+  if (authentication && "user" in authentication && authentication.user?.id) {
+    return authentication.user.id;
+  }
+
+  return null;
+}
+
+function hasExternalUrlReferences(input: TV3CreateSurveyBody): boolean {
+  const hasExternalEndingLink = input.endings.some(
+    (ending) => ending.type === "endScreen" && Boolean(ending.buttonLink)
+  );
+  const hasExternalCtaButton = getElementsFromBlocks(input.blocks).some(
+    (element) => element.type === "cta" && element.buttonExternal
+  );
+
+  return hasExternalEndingLink || hasExternalCtaButton;
+}
+
+async function assertV3SurveyCreatePermissions(
+  input: TV3CreateSurveyBody,
+  organizationId?: string
+): Promise<void> {
+  if (!hasExternalUrlReferences(input)) {
+    return;
+  }
+
+  const resolvedOrganizationId =
+    organizationId ?? (await getOrganizationByWorkspaceId(input.workspaceId))?.id ?? null;
+  if (!resolvedOrganizationId) {
+    return;
+  }
+
+  const isExternalUrlsAllowed = await getExternalUrlsPermission(resolvedOrganizationId);
+  if (!isExternalUrlsAllowed) {
+    throw new V3SurveyCreatePermissionError(
+      "External URLs are not enabled for this organization. Upgrade to use external survey links."
+    );
+  }
+}
+
+export async function executeV3SurveyCreate(params: {
+  input: TV3CreateSurveyBody;
+  authentication: TV3Authentication;
+  languageRequests: TV3SurveyLanguageRequest[];
+  requestId?: string;
+}) {
+  const { input, authentication, languageRequests, requestId } = params;
+  const languages = await ensureV3WorkspaceLanguages(input.workspaceId, languageRequests, requestId);
+  const surveyCreateInput: TSurveyCreateInput = {
+    name: input.name,
+    type: "link",
+    status: input.status,
+    metadata: input.metadata,
+    welcomeCard: input.welcomeCard,
+    blocks: input.blocks,
+    endings: input.endings,
+    hiddenFields: input.hiddenFields,
+    variables: input.variables,
+    languages,
+    questions: [],
+    createdBy: getCreatedBy(authentication),
+  };
+
+  return await createSurvey(input.workspaceId, surveyCreateInput);
+}
+
+export async function createV3Survey(
+  input: TV3CreateSurveyBody,
+  authentication: TV3Authentication,
+  requestId?: string,
+  organizationId?: string
+) {
+  const preparation = prepareV3SurveyCreate(input);
+  if (!preparation.ok) {
+    throw new V3SurveyReferenceValidationError(preparation.validation.invalidParams);
+  }
+
+  await assertV3SurveyCreatePermissions(input, organizationId);
+
+  return await executeV3SurveyCreate({
+    input: preparation.document,
+    authentication,
+    languageRequests: preparation.languageRequests,
+    requestId,
+  });
+}
@@ -0,0 +1,106 @@
+import { describe, expect, test } from "vitest";
+import {
+  normalizeV3SurveyLanguageTag,
+  parseV3SurveyLanguageQuery,
+  resolveV3SurveyLanguageCode,
+} from "./language";
+
+const languages = [
+  { code: "en-US", enabled: true },
+  { code: "de-DE", enabled: true },
+  { code: "fr-FR", enabled: false },
+];
+
+describe("normalizeV3SurveyLanguageTag", () => {
+  test.each([
+    ["EN_us", "en-US"],
+    ["en-us", "en-US"],
+    ["de", "de"],
+    ["zh_hans_cn", "zh-Hans-CN"],
+  ])("normalizes %s to %s", (input, expected) => {
+    expect(normalizeV3SurveyLanguageTag(input)).toBe(expected);
+  });
+
+  test("returns null for invalid language tags", () => {
+    expect(normalizeV3SurveyLanguageTag("not a locale")).toBeNull();
+  });
+});
+
+describe("parseV3SurveyLanguageQuery", () => {
+  test("parses comma-separated language selectors", () => {
+    expect(parseV3SurveyLanguageQuery("de-DE, pt_PT, EN_us")).toEqual({
+      ok: true,
+      languages: ["de-DE", "pt-PT", "en-US"],
+    });
+  });
+
+  test("parses repeated language selectors", () => {
+    expect(parseV3SurveyLanguageQuery(["de-DE", "pt_PT,en_us"])).toEqual({
+      ok: true,
+      languages: ["de-DE", "pt-PT", "en-US"],
+    });
+  });
+
+  test("deduplicates language selectors case-insensitively", () => {
+    expect(parseV3SurveyLanguageQuery("de-DE,DE_de")).toEqual({
+      ok: true,
+      languages: ["de-DE"],
+    });
+  });
+
+  test("rejects empty language selectors", () => {
+    expect(parseV3SurveyLanguageQuery("de-DE,")).toEqual({
+      ok: false,
+      message: "Language selector must contain valid comma-separated locale codes",
+    });
+  });
+
+  test("rejects invalid language selectors", () => {
+    expect(parseV3SurveyLanguageQuery("not a locale")).toEqual({
+      ok: false,
+      message: "Language 'not a locale' is not a valid locale code",
+    });
+  });
+});
+
+describe("resolveV3SurveyLanguageCode", () => {
+  test("matches configured languages case-insensitively and normalizes underscores", () => {
+    expect(resolveV3SurveyLanguageCode("DE_de", languages)).toEqual({ ok: true, code: "de-DE" });
+  });
+
+  test("resolves language-only tags when exactly one configured language matches", () => {
+    expect(resolveV3SurveyLanguageCode("de", languages)).toEqual({ ok: true, code: "de-DE" });
+  });
+
+  test("resolves disabled configured languages for management reads", () => {
+    expect(resolveV3SurveyLanguageCode("fr", languages)).toEqual({ ok: true, code: "fr-FR" });
+  });
+
+  test("returns ambiguous when language-only tags match multiple configured languages", () => {
+    expect(
+      resolveV3SurveyLanguageCode("pt", [
+        { code: "pt-BR", enabled: true },
+        { code: "pt-PT", enabled: true },
+      ])
+    ).toEqual({
+      ok: false,
+      reason: "ambiguous",
+      message: "Language 'pt' is ambiguous for this survey; use one of pt-BR, pt-PT",
+    });
+  });
+
+  test("returns unknown for languages not configured on the survey", () => {
+    expect(resolveV3SurveyLanguageCode("es-ES", languages)).toEqual({
+      ok: false,
+      reason: "unknown",
+      message: "Language 'es-ES' is not configured for this survey",
+    });
+  });
+
+  test("resolves the implicit default language for surveys without configured languages", () => {
+    expect(resolveV3SurveyLanguageCode("en", [{ code: "en-US", enabled: true }])).toEqual({
+      ok: true,
+      code: "en-US",
+    });
+  });
+});
@@ -0,0 +1,149 @@
+import type { TSurvey as TInternalSurvey } from "@formbricks/types/surveys/types";
+
+type TV3SurveyLanguageInput = {
+  code: string;
+  enabled: boolean;
+};
+
+export type TV3SurveyLanguage = {
+  code: string;
+  default: boolean;
+  enabled: boolean;
+};
+
+type TV3SurveyLanguageQueryInput = string | string[];
+
+type TResolveV3SurveyLanguageCodeResult =
+  | { ok: true; code: string }
+  | { ok: false; reason: "invalid" | "unknown" | "ambiguous"; message: string };
+
+type TParseV3SurveyLanguageQueryResult = { ok: true; languages: string[] } | { ok: false; message: string };
+
+export function normalizeV3SurveyLanguageTag(value: string): string | null {
+  const normalizedSeparators = value.trim().replaceAll("_", "-");
+
+  try {
+    return Intl.getCanonicalLocales(normalizedSeparators)[0] ?? null;
+  } catch {
+    return null;
+  }
+}
+
+export function parseV3SurveyLanguageQuery(
+  value: TV3SurveyLanguageQueryInput
+): TParseV3SurveyLanguageQueryResult {
+  const requestedLanguages = (Array.isArray(value) ? value : [value])
+    .flatMap((entry) => entry.split(","))
+    .map((entry) => entry.trim());
+
+  if (requestedLanguages.some((entry) => entry.length === 0)) {
+    return {
+      ok: false,
+      message: "Language selector must contain valid comma-separated locale codes",
+    };
+  }
+
+  const normalizedLanguages: string[] = [];
+
+  for (const language of requestedLanguages) {
+    const normalizedLanguage = normalizeV3SurveyLanguageTag(language);
+
+    if (!normalizedLanguage) {
+      return {
+        ok: false,
+        message: `Language '${language}' is not a valid locale code`,
+      };
+    }
+
+    if (!normalizedLanguages.some((entry) => entry.toLowerCase() === normalizedLanguage.toLowerCase())) {
+      normalizedLanguages.push(normalizedLanguage);
+    }
+  }
+
+  return { ok: true, languages: normalizedLanguages };
+}
+
+function getLanguageSubtag(languageTag: string): string {
+  return languageTag.split("-")[0]?.toLowerCase() ?? languageTag.toLowerCase();
+}
+
+export function resolveV3SurveyLanguageCode(
+  requestedLanguage: string,
+  languages: TV3SurveyLanguageInput[]
+): TResolveV3SurveyLanguageCodeResult {
+  const normalizedRequestedLanguage = normalizeV3SurveyLanguageTag(requestedLanguage);
+
+  if (!normalizedRequestedLanguage) {
+    return {
+      ok: false,
+      reason: "invalid",
+      message: `Language '${requestedLanguage}' is not a valid locale code`,
+    };
+  }
+
+  const normalizedLanguages = languages.map((language) => ({
+    ...language,
+    code: normalizeV3SurveyLanguageTag(language.code) ?? language.code,
+  }));
+  const exactMatch = normalizedLanguages.find(
+    (language) => language.code.toLowerCase() === normalizedRequestedLanguage.toLowerCase()
+  );
+
+  if (exactMatch) {
+    return { ok: true, code: exactMatch.code };
+  }
+
+  const requestedSubtag = getLanguageSubtag(normalizedRequestedLanguage);
+  const hasRegionOrScript = normalizedRequestedLanguage.includes("-");
+  const matchingLanguages = hasRegionOrScript
+    ? []
+    : normalizedLanguages.filter((language) => getLanguageSubtag(language.code) === requestedSubtag);
+
+  if (matchingLanguages.length > 1) {
+    return {
+      ok: false,
+      reason: "ambiguous",
+      message: `Language '${normalizedRequestedLanguage}' is ambiguous for this survey; use one of ${matchingLanguages.map((language) => language.code).join(", ")}`,
+    };
+  }
+
+  const languageMatch = matchingLanguages[0];
+  if (languageMatch) {
+    return { ok: true, code: languageMatch.code };
+  }
+
+  return {
+    ok: false,
+    reason: "unknown",
+    message: `Language '${normalizedRequestedLanguage}' is not configured for this survey`,
+  };
+}
+
+export function getV3SurveyLanguages(
+  survey: Pick<TInternalSurvey, "languages">,
+  fallbackLanguage: string
+): TV3SurveyLanguage[] {
+  const languages = (survey.languages ?? []).map((surveyLanguage) => ({
+    code: normalizeV3SurveyLanguageTag(surveyLanguage.language.code) ?? surveyLanguage.language.code,
+    default: surveyLanguage.default,
+    enabled: surveyLanguage.enabled,
+  }));
+
+  if (languages.length === 0) {
+    return [{ code: fallbackLanguage, default: true, enabled: true }];
+  }
+
+  return languages;
+}
+
+export function getV3SurveyDefaultLanguage(
+  survey: Pick<TInternalSurvey, "languages">,
+  fallbackLanguage: string
+): string {
+  const defaultLanguageCode = survey.languages?.find((surveyLanguage) => surveyLanguage.default)?.language
+    .code;
+
+  return defaultLanguageCode
+    ? (normalizeV3SurveyLanguageTag(defaultLanguageCode) ?? defaultLanguageCode)
+    : fallbackLanguage;
+}
@@ -0,0 +1,150 @@
+import "server-only";
+import { Prisma } from "@prisma/client";
+import { prisma } from "@formbricks/database";
+import { logger } from "@formbricks/logger";
+import { DatabaseError } from "@formbricks/types/errors";
+import type { TI18nString } from "@formbricks/types/i18n";
+import type { TSurveyLanguage } from "@formbricks/types/surveys/types";
+import type { TLanguage } from "@formbricks/types/workspace";
+import { normalizeV3SurveyLanguageTag } from "./language";
+import type { TV3SurveyDocument } from "./schemas";
+
+export type TV3SurveyLanguageRequest = {
+  code: string;
+  default: boolean;
+  enabled: boolean;
+};
+
+const languageSelect = {
+  id: true,
+  code: true,
+  alias: true,
+  workspaceId: true,
+  createdAt: true,
+  updatedAt: true,
+} satisfies Prisma.LanguageSelect;
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isInternalI18nString(value: unknown): value is TI18nString {
+  return (
+    isPlainObject(value) &&
+    typeof value.default === "string" &&
+    Object.values(value).every((entry) => typeof entry === "string")
+  );
+}
+
+function collectI18nLanguageCodes(value: unknown, languageCodes: Set<string>): void {
+  if (Array.isArray(value)) {
+    value.forEach((entry) => collectI18nLanguageCodes(entry, languageCodes));
+    return;
+  }
+
+  if (!isPlainObject(value)) {
+    return;
+  }
+
+  if (isInternalI18nString(value)) {
+    Object.keys(value).forEach((languageCode) => {
+      if (languageCode !== "default") {
+        const normalizedLanguageCode = normalizeV3SurveyLanguageTag(languageCode);
+        if (normalizedLanguageCode) {
+          languageCodes.add(normalizedLanguageCode);
+        }
+      }
+    });
+    return;
+  }
+
+  Object.values(value).forEach((entry) => collectI18nLanguageCodes(entry, languageCodes));
+}
+
+export function deriveV3SurveyLanguageRequests(input: TV3SurveyDocument): TV3SurveyLanguageRequest[] {
+  const requestedLanguages = new Map<string, TV3SurveyLanguageRequest>();
+  const addLanguage = (code: string, enabled = true): void => {
+    requestedLanguages.set(code, {
+      code,
+      default: code.toLowerCase() === input.defaultLanguage.toLowerCase(),
+      enabled: code.toLowerCase() === input.defaultLanguage.toLowerCase() ? true : enabled,
+    });
+  };
+
+  addLanguage(input.defaultLanguage);
+
+  input.languages.forEach((language) => {
+    addLanguage(language.code, language.enabled);
+  });
+
+  const contentLanguageCodes = new Set<string>();
+  collectI18nLanguageCodes(input.welcomeCard, contentLanguageCodes);
+  collectI18nLanguageCodes(input.blocks, contentLanguageCodes);
+  collectI18nLanguageCodes(input.endings, contentLanguageCodes);
+  collectI18nLanguageCodes(input.metadata, contentLanguageCodes);
+  contentLanguageCodes.forEach((languageCode) => {
+    if (!requestedLanguages.has(languageCode)) {
+      addLanguage(languageCode);
+    }
+  });
+
+  return Array.from(requestedLanguages.values()).sort((left, right) => {
+    if (left.default) return -1;
+    if (right.default) return 1;
+    return left.code.localeCompare(right.code);
+  });
+}
+
+export async function ensureV3WorkspaceLanguages(
+  workspaceId: string,
+  languageRequests: TV3SurveyLanguageRequest[],
+  requestId?: string
+): Promise<TSurveyLanguage[]> {
+  const log = logger.withContext({ requestId, workspaceId });
+
+  try {
+    const languages = await Promise.all(
+      languageRequests.map((languageRequest) =>
+        prisma.language.upsert({
+          where: {
+            workspaceId_code: {
+              workspaceId,
+              code: languageRequest.code,
+            },
+          },
+          update: {},
+          create: {
+            workspaceId,
+            code: languageRequest.code,
+            alias: null,
+          },
+          select: languageSelect,
+        })
+      )
+    );
+    const languageByCode = new Map(
+      languages.map((language) => [language.code.toLowerCase(), language as TLanguage])
+    );
+
+    return languageRequests.map((languageRequest) => {
+      const language = languageByCode.get(languageRequest.code.toLowerCase());
+
+      if (!language) {
+        throw new DatabaseError(`Failed to resolve language '${languageRequest.code}'`);
+      }
+
+      return {
+        language,
+        default: languageRequest.default,
+        enabled: languageRequest.enabled,
+      };
+    });
+  } catch (error) {
+    if (error instanceof Prisma.PrismaClientKnownRequestError) {
+      log.error({ error }, "Error creating workspace languages for v3 survey write");
+      throw new DatabaseError(error.message);
+    }
+
+    throw error;
+  }
+}
@@ -0,0 +1,165 @@
+import { describe, expect, test, vi } from "vitest";
+import type { TSurvey } from "@formbricks/types/surveys/types";
+import { prepareV3SurveyCreate, prepareV3SurveyCreateInput, prepareV3SurveyPatchInput } from "./prepare";
+import { ZV3CreateSurveyBody } from "./schemas";
+
+vi.mock("server-only", () => ({}));
+
+const workspaceId = "clxx1234567890123456789012";
+
+const rawCreateBody = {
+  workspaceId,
+  name: "Product Feedback",
+  defaultLanguage: "en-US",
+  blocks: [
+    {
+      id: "clbk1234567890123456789012",
+      name: "Main Block",
+      elements: [
+        {
+          id: "satisfaction",
+          type: "openText",
+          headline: { "en-US": "What should we improve?", "de-DE": "Was sollen wir verbessern?" },
+          required: true,
+        },
+      ],
+    },
+  ],
+};
+
+const createBody = ZV3CreateSurveyBody.parse(rawCreateBody);
+
+const survey = {
+  id: "clsv1234567890123456789012",
+  workspaceId,
+  createdAt: new Date("2026-04-21T10:00:00.000Z"),
+  updatedAt: new Date("2026-04-21T10:00:00.000Z"),
+  name: "Product Feedback",
+  type: "link",
+  status: "draft",
+  metadata: {},
+  languages: [
+    {
+      language: {
+        id: "cllangenus000000000000000",
+        code: "en-US",
+        alias: null,
+        workspaceId,
+        createdAt: new Date("2026-04-21T10:00:00.000Z"),
+        updatedAt: new Date("2026-04-21T10:00:00.000Z"),
+      },
+      default: true,
+      enabled: true,
+    },
+  ],
+  questions: [],
+  welcomeCard: { enabled: false },
+  blocks: createBody.blocks,
+  endings: [],
+  hiddenFields: { enabled: false },
+  variables: [],
+} as unknown as TSurvey;
+
+describe("v3 survey preparation", () => {
+  test("prepares a valid create document and derives language side effects", () => {
+    const preparation = prepareV3SurveyCreate(createBody);
+
+    expect(preparation.ok).toBe(true);
+    if (!preparation.ok) {
+      throw new Error("Expected create preparation to succeed");
+    }
+    expect(preparation.languageRequests).toEqual([
+      { code: "en-US", default: true, enabled: true },
+      { code: "de-DE", default: false, enabled: true },
+    ]);
+  });
+
+  test("returns validation results instead of throwing for invalid create input", () => {
+    const preparation = prepareV3SurveyCreateInput({
+      ...rawCreateBody,
+      blocks: [
+        {
+          ...rawCreateBody.blocks[0],
+          elements: [
+            {
+              ...rawCreateBody.blocks[0].elements[0],
+              buttonUrl: "https://example.com",
+            },
+          ],
+        },
+      ],
+    });
+
+    expect(preparation.ok).toBe(false);
+    if (!preparation.ok) {
+      expect(preparation.validation.invalidParams).toEqual(
+        expect.arrayContaining([expect.objectContaining({ name: "blocks.0.elements.0.buttonUrl" })])
+      );
+    }
+  });
+
+  test("applies a patch over the current document before validating references", () => {
+    const preparation = prepareV3SurveyPatchInput(survey, {
+      blocks: [
+        {
+          ...rawCreateBody.blocks[0],
+          logicFallback: "clmiss12345678901234567890",
+        },
+      ],
+    });
+
+    expect(preparation.ok).toBe(false);
+    if (!preparation.ok) {
+      expect(preparation.validation.invalidParams).toEqual(
+        expect.arrayContaining([expect.objectContaining({ name: "blocks.0.logicFallback" })])
+      );
+    }
+  });
+
+  test("rejects patch input with immutable fields as validation results", () => {
+    const preparation = prepareV3SurveyPatchInput(survey, {
+      workspaceId,
+    });
+
+    expect(preparation.ok).toBe(false);
+    if (!preparation.ok) {
+      expect(preparation.validation.invalidParams).toEqual(
+        expect.arrayContaining([expect.objectContaining({ name: "workspaceId" })])
+      );
+    }
+  });
+
+  test("rejects non-draft element id changes on non-draft surveys", () => {
+    const preparation = prepareV3SurveyPatchInput(
+      {
+        ...survey,
+        status: "inProgress",
+      } as TSurvey,
+      {
+        blocks: [
+          {
+            ...rawCreateBody.blocks[0],
+            elements: [
+              {
+                ...rawCreateBody.blocks[0].elements[0],
+                id: "renamed_satisfaction",
+              },
+            ],
+          },
+        ],
+      }
+    );
+
+    expect(preparation.ok).toBe(false);
+    if (!preparation.ok) {
+      expect(preparation.validation.invalidParams).toEqual(
+        expect.arrayContaining([
+          expect.objectContaining({
+            name: "blocks.0.elements.0.id",
+            reason: expect.stringContaining("cannot be changed"),
+          }),
+        ])
+      );
+    }
+  });
+});
@@ -0,0 +1,178 @@
+import type { TSurvey as TInternalSurvey } from "@formbricks/types/surveys/types";
+import type { InvalidParam } from "@/app/api/v3/lib/response";
+import { getV3SurveyDefaultLanguage, getV3SurveyLanguages } from "./language";
+import { type TV3SurveyLanguageRequest, deriveV3SurveyLanguageRequests } from "./languages";
+import {
+  DEFAULT_V3_SURVEY_LANGUAGE,
+  type TV3CreateSurveyBody,
+  type TV3PatchSurveyBody,
+  type TV3SurveyDocument,
+  ZV3CreateSurveyBody,
+  ZV3SurveyDocumentBase,
+  createZV3PatchSurveyBodySchema,
+  formatV3ZodInvalidParams,
+} from "./schemas";
+import { type TV3SurveyDocumentValidationResult, validateV3SurveyDocument } from "./validation";
+
+type TV3SurveyPrepareSuccess<TDocument> = {
+  ok: true;
+  document: TDocument;
+  validation: Extract<TV3SurveyDocumentValidationResult, { valid: true }>;
+  languageRequests: TV3SurveyLanguageRequest[];
+};
+
+type TV3SurveyPrepareFailure = {
+  ok: false;
+  validation: Extract<TV3SurveyDocumentValidationResult, { valid: false }>;
+};
+
+export type TV3SurveyPrepareResult<TDocument> = TV3SurveyPrepareSuccess<TDocument> | TV3SurveyPrepareFailure;
+
+function invalidPreparation(invalidParams: InvalidParam[]): TV3SurveyPrepareFailure {
+  return {
+    ok: false,
+    validation: {
+      valid: false,
+      invalidParams,
+    },
+  };
+}
+
+function validPreparation<TDocument extends TV3SurveyDocument>(
+  document: TDocument
+): TV3SurveyPrepareResult<TDocument> {
+  const validation = validateV3SurveyDocument(document);
+
+  if (!validation.valid) {
+    return invalidPreparation(validation.invalidParams);
+  }
+
+  return {
+    ok: true,
+    document,
+    validation,
+    languageRequests: deriveV3SurveyLanguageRequests(document),
+  };
+}
+
+function buildDocumentFromSurvey(survey: TInternalSurvey): TV3SurveyPrepareResult<TV3SurveyDocument> {
+  if (Array.isArray(survey.questions) && survey.questions.length > 0) {
+    return invalidPreparation([
+      {
+        name: "survey",
+        reason: "Legacy question-based surveys are not supported by the v3 survey management API",
+      },
+    ]);
+  }
+
+  const documentResult = ZV3SurveyDocumentBase.safeParse({
+    name: survey.name,
+    status: survey.status,
+    metadata: survey.metadata ?? {},
+    defaultLanguage: getV3SurveyDefaultLanguage(survey, DEFAULT_V3_SURVEY_LANGUAGE),
+    languages: getV3SurveyLanguages(survey, DEFAULT_V3_SURVEY_LANGUAGE),
+    welcomeCard: survey.welcomeCard,
+    blocks: survey.blocks,
+    endings: survey.endings,
+    hiddenFields: survey.hiddenFields,
+    variables: survey.variables,
+  });
+
+  if (!documentResult.success) {
+    return invalidPreparation(formatV3ZodInvalidParams(documentResult.error, "survey"));
+  }
+
+  return validPreparation(documentResult.data);
+}
+
+function mergeV3SurveyPatch(document: TV3SurveyDocument, patch: TV3PatchSurveyBody): TV3SurveyDocument {
+  return {
+    ...document,
+    ...Object.fromEntries(Object.entries(patch).filter(([, value]) => value !== undefined)),
+  };
+}
+
+function getElementIds(document: TV3SurveyDocument): Set<string> {
+  return new Set(document.blocks.flatMap((block) => block.elements.map((element) => element.id)));
+}
+
+function getImmutableElementIdIssues(
+  currentDocument: TV3SurveyDocument,
+  patchedDocument: TV3SurveyDocument
+): InvalidParam[] {
+  if (currentDocument.status === "draft") {
+    return [];
+  }
+
+  const patchedElementIds = getElementIds(patchedDocument);
+  const issues: InvalidParam[] = [];
+
+  currentDocument.blocks.forEach((currentBlock) => {
+    const patchedBlockIndex = patchedDocument.blocks.findIndex((block) => block.id === currentBlock.id);
+    if (patchedBlockIndex === -1) {
+      return;
+    }
+
+    const patchedBlock = patchedDocument.blocks[patchedBlockIndex];
+    currentBlock.elements.forEach((currentElement, elementIndex) => {
+      if (currentElement.isDraft || patchedElementIds.has(currentElement.id)) {
+        return;
+      }
+
+      const patchedElement = patchedBlock.elements[elementIndex];
+      if (!patchedElement || patchedElement.id === currentElement.id) {
+        return;
+      }
+
+      issues.push({
+        name: `blocks.${patchedBlockIndex}.elements.${elementIndex}.id`,
+        reason: `Element id '${currentElement.id}' cannot be changed because the survey and element are no longer drafts`,
+      });
+    });
+  });
+
+  return issues;
+}
+
+export function prepareV3SurveyCreate(
+  document: TV3CreateSurveyBody
+): TV3SurveyPrepareResult<TV3CreateSurveyBody> {
+  return validPreparation(document);
+}
+
+export function prepareV3SurveyCreateInput(input: unknown): TV3SurveyPrepareResult<TV3CreateSurveyBody> {
+  const parsed = ZV3CreateSurveyBody.safeParse(input);
+
+  if (!parsed.success) {
+    return invalidPreparation(formatV3ZodInvalidParams(parsed.error, "data"));
+  }
+
+  return prepareV3SurveyCreate(parsed.data);
+}
+
+export function prepareV3SurveyPatchInput(
+  survey: TInternalSurvey,
+  input: unknown
+): TV3SurveyPrepareResult<TV3SurveyDocument> {
+  const currentDocument = buildDocumentFromSurvey(survey);
+
+  if (!currentDocument.ok) {
+    return currentDocument;
+  }
+
+  const parsedPatch = createZV3PatchSurveyBodySchema(currentDocument.document.defaultLanguage).safeParse(
+    input
+  );
+
+  if (!parsedPatch.success) {
+    return invalidPreparation(formatV3ZodInvalidParams(parsedPatch.error, "data"));
+  }
+
+  const patchedDocument = mergeV3SurveyPatch(currentDocument.document, parsedPatch.data);
+  const immutableElementIdIssues = getImmutableElementIdIssues(currentDocument.document, patchedDocument);
+  if (immutableElementIdIssues.length > 0) {
+    return invalidPreparation(immutableElementIdIssues);
+  }
+
+  return validPreparation(patchedDocument);
+}
@@ -0,0 +1,269 @@
+import { describe, expect, test } from "vitest";
+import { validateV3SurveyReferences } from "./reference-validation";
+import { ZV3CreateSurveyBody } from "./schemas";
+
+const validSurvey = ZV3CreateSurveyBody.parse({
+  workspaceId: "clxx1234567890123456789012",
+  name: "Product Feedback",
+  hiddenFields: {
+    enabled: true,
+    fieldIds: ["account_id"],
+  },
+  variables: [
+    {
+      id: "clvar123456789012345678901",
+      name: "score",
+      type: "number",
+      value: 0,
+    },
+  ],
+  endings: [
+    {
+      id: "clend123456789012345678901",
+      type: "endScreen",
+      headline: { "en-US": "Thanks" },
+    },
+  ],
+  blocks: [
+    {
+      id: "clbk1234567890123456789012",
+      name: "Main Block",
+      logicFallback: "clend123456789012345678901",
+      elements: [
+        {
+          id: "satisfaction",
+          type: "openText",
+          headline: { "en-US": "What should we improve?" },
+          required: true,
+        },
+      ],
+      logic: [
+        {
+          id: "cllog123456789012345678901",
+          conditions: {
+            id: "clgrp123456789012345678901",
+            connector: "and",
+            conditions: [
+              {
+                id: "clcon123456789012345678901",
+                leftOperand: { type: "element", value: "satisfaction" },
+                operator: "isSubmitted",
+              },
+            ],
+          },
+          actions: [
+            {
+              id: "clact123456789012345678901",
+              objective: "calculate",
+              variableId: "clvar123456789012345678901",
+              operator: "add",
+              value: { type: "static", value: 1 },
+            },
+          ],
+        },
+      ],
+    },
+  ],
+});
+
+describe("validateV3SurveyReferences", () => {
+  test("accepts a survey with consistent stable identifiers", () => {
+    expect(
+      validateV3SurveyReferences({
+        blocks: validSurvey.blocks,
+        endings: validSurvey.endings,
+        hiddenFields: validSurvey.hiddenFields,
+        variables: validSurvey.variables,
+      })
+    ).toEqual({ ok: true, invalidParams: [] });
+  });
+
+  test("rejects duplicate block, element, variable, and hidden field identifiers", () => {
+    const survey = {
+      ...validSurvey,
+      hiddenFields: { enabled: true, fieldIds: ["account_id", "account_id"] },
+      variables: [
+        ...validSurvey.variables,
+        {
+          id: "clvar123456789012345678901",
+          name: "score",
+          type: "number" as const,
+          value: 0,
+        },
+      ],
+      blocks: [
+        ...validSurvey.blocks,
+        {
+          ...validSurvey.blocks[0],
+          elements: [{ ...validSurvey.blocks[0].elements[0] }],
+        },
+      ],
+    };
+
+    const result = validateV3SurveyReferences({
+      blocks: survey.blocks,
+      endings: survey.endings,
+      hiddenFields: survey.hiddenFields,
+      variables: survey.variables,
+    });
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.invalidParams).toEqual(
+        expect.arrayContaining([
+          expect.objectContaining({ name: "blocks.1.id" }),
+          expect.objectContaining({ name: "blocks.1.elements.0.id" }),
+          expect.objectContaining({ name: "variables.1.id" }),
+          expect.objectContaining({ name: "hiddenFields.fieldIds.1" }),
+        ])
+      );
+    }
+  });
+
+  test("rejects cross-namespace identifier collisions", () => {
+    const result = validateV3SurveyReferences({
+      blocks: validSurvey.blocks,
+      endings: validSurvey.endings,
+      hiddenFields: { enabled: true, fieldIds: ["account_id", "satisfaction"] },
+      variables: [
+        {
+          id: "satisfaction",
+          name: "account_id",
+          type: "number",
+          value: 0,
+        },
+      ],
+    });
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.invalidParams).toEqual(
+        expect.arrayContaining([
+          expect.objectContaining({ name: "hiddenFields.fieldIds.1" }),
+          expect.objectContaining({ name: "variables.0.id" }),
+          expect.objectContaining({ name: "variables.0.name" }),
+        ])
+      );
+    }
+  });
+
+  test("reports dangling logic references with actionable paths", () => {
+    const survey = {
+      ...validSurvey,
+      blocks: [
+        {
+          ...validSurvey.blocks[0],
+          logicFallback: "clmiss12345678901234567890",
+          logic: [
+            {
+              ...validSurvey.blocks[0].logic![0],
+              actions: [
+                {
+                  ...validSurvey.blocks[0].logic![0].actions[0],
+                  variableId: "clmiss12345678901234567890",
+                },
+                {
+                  id: "cljmp123456789012345678901",
+                  objective: "jumpToBlock" as const,
+                  target: "clmiss12345678901234567890",
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    };
+
+    const result = validateV3SurveyReferences({
+      blocks: survey.blocks,
+      endings: survey.endings,
+      hiddenFields: survey.hiddenFields,
+      variables: survey.variables,
+    });
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.invalidParams).toEqual(
+        expect.arrayContaining([
+          expect.objectContaining({ name: "blocks.0.logicFallback" }),
+          expect.objectContaining({ name: "blocks.0.logic.0.actions.0.variableId" }),
+          expect.objectContaining({ name: "blocks.0.logic.0.actions.1.target" }),
+        ])
+      );
+    }
+  });
+
+  test("reports dangling recall references with actionable paths", () => {
+    const survey = {
+      ...validSurvey,
+      blocks: [
+        {
+          ...validSurvey.blocks[0],
+          elements: [
+            {
+              ...validSurvey.blocks[0].elements[0],
+              headline: {
+                default: "Please explain #recall:missing_id/fallback:your answer#",
+              },
+            },
+          ],
+        },
+      ],
+    };
+
+    const result = validateV3SurveyReferences({
+      blocks: survey.blocks,
+      endings: survey.endings,
+      hiddenFields: survey.hiddenFields,
+      variables: survey.variables,
+    });
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.invalidParams).toEqual(
+        expect.arrayContaining([
+          expect.objectContaining({
+            name: "blocks.0.elements.0.headline.default",
+            reason: expect.stringContaining("missing_id"),
+          }),
+        ])
+      );
+    }
+  });
+
+  test("reports dangling recall references in survey-level translatable fields", () => {
+    const result = validateV3SurveyReferences({
+      blocks: validSurvey.blocks,
+      endings: validSurvey.endings,
+      hiddenFields: validSurvey.hiddenFields,
+      metadata: {
+        title: {
+          default: "Metadata #recall:missing_metadata_reference/fallback:value#",
+        },
+      },
+      variables: validSurvey.variables,
+      welcomeCard: {
+        enabled: true,
+        headline: {
+          default: "Welcome #recall:missing_welcome_reference/fallback:there#",
+        },
+      },
+    });
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.invalidParams).toEqual(
+        expect.arrayContaining([
+          expect.objectContaining({
+            name: "welcomeCard.headline.default",
+            reason: expect.stringContaining("missing_welcome_reference"),
+          }),
+          expect.objectContaining({
+            name: "metadata.title.default",
+            reason: expect.stringContaining("missing_metadata_reference"),
+          }),
+        ])
+      );
+    }
+  });
+});
@@ -0,0 +1,342 @@
+import type { TSurveyBlocks } from "@formbricks/types/surveys/blocks";
+import type { TConditionGroup, TDynamicLogicFieldValue } from "@formbricks/types/surveys/logic";
+import type { TSurveyEndings, TSurveyHiddenFields, TSurveyVariables } from "@formbricks/types/surveys/types";
+import type { InvalidParam } from "@/app/api/v3/lib/response";
+
+type TReferenceValidationInput = {
+  blocks: TSurveyBlocks;
+  endings: TSurveyEndings;
+  hiddenFields: TSurveyHiddenFields;
+  metadata?: unknown;
+  variables: TSurveyVariables;
+  welcomeCard?: unknown;
+};
+
+type TNamedReference = {
+  id: string;
+  path: string;
+  namespace: "block" | "element" | "ending" | "hiddenField" | "variable" | "variableName";
+};
+
+export class V3SurveyReferenceValidationError extends Error {
+  invalidParams: InvalidParam[];
+
+  constructor(invalidParams: InvalidParam[]) {
+    super("Survey contains invalid references");
+    this.name = "V3SurveyReferenceValidationError";
+    this.invalidParams = invalidParams;
+  }
+}
+
+export type TV3SurveyReferenceValidationResult =
+  | { ok: true; invalidParams: [] }
+  | { ok: false; invalidParams: InvalidParam[] };
+
+function addDuplicateIdIssues(
+  entries: { id: string; path: string }[],
+  label: string,
+  issues: InvalidParam[]
+): void {
+  const firstPathById = new Map<string, string>();
+
+  entries.forEach(({ id, path }) => {
+    const firstPath = firstPathById.get(id);
+    if (firstPath !== undefined) {
+      issues.push({
+        name: path,
+        reason: `${label} id '${id}' is duplicated; first used at ${firstPath}`,
+      });
+      return;
+    }
+
+    firstPathById.set(id, path);
+  });
+}
+
+function addDuplicateValueIssues(
+  values: string[],
+  pathForIndex: (index: number) => string,
+  label: string,
+  issues: InvalidParam[]
+): void {
+  const firstIndexByValue = new Map<string, number>();
+
+  values.forEach((value, index) => {
+    const firstIndex = firstIndexByValue.get(value);
+    if (firstIndex !== undefined) {
+      issues.push({
+        name: pathForIndex(index),
+        reason: `${label} '${value}' is duplicated; first used at ${pathForIndex(firstIndex)}`,
+      });
+      return;
+    }
+
+    firstIndexByValue.set(value, index);
+  });
+}
+
+function addCrossNamespaceCollisionIssues(entries: TNamedReference[], issues: InvalidParam[]): void {
+  const firstEntryById = new Map<string, TNamedReference>();
+
+  entries.forEach((entry) => {
+    const lookupId = entry.id.toLowerCase();
+    const firstEntry = firstEntryById.get(lookupId);
+
+    if (!firstEntry) {
+      firstEntryById.set(lookupId, entry);
+      return;
+    }
+
+    if (firstEntry.namespace === entry.namespace) {
+      return;
+    }
+
+    issues.push({
+      name: entry.path,
+      reason: `${entry.namespace} identifier '${entry.id}' conflicts with ${firstEntry.namespace} identifier at ${firstEntry.path}`,
+    });
+  });
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function addRecallReferenceIssues(
+  value: unknown,
+  path: string,
+  references: {
+    elementIds: Set<string>;
+    variableIds: Set<string>;
+    hiddenFieldIds: Set<string>;
+  },
+  issues: InvalidParam[]
+): void {
+  if (typeof value === "string") {
+    const recallPattern = /#recall:([A-Za-z0-9_-]+)/g;
+
+    for (const match of value.matchAll(recallPattern)) {
+      const recallId = match[1];
+      const isKnownReference =
+        references.elementIds.has(recallId) ||
+        references.variableIds.has(recallId) ||
+        references.hiddenFieldIds.has(recallId);
+
+      if (!isKnownReference) {
+        issues.push({
+          name: path,
+          reason: `Recall reference '${recallId}' is not defined in blocks, variables, or hiddenFields.fieldIds`,
+        });
+      }
+    }
+
+    return;
+  }
+
+  if (Array.isArray(value)) {
+    value.forEach((entry, index) => addRecallReferenceIssues(entry, `${path}.${index}`, references, issues));
+    return;
+  }
+
+  if (!isPlainObject(value)) {
+    return;
+  }
+
+  Object.entries(value).forEach(([key, entry]) => {
+    addRecallReferenceIssues(entry, path ? `${path}.${key}` : key, references, issues);
+  });
+}
+
+function validateDynamicOperand(
+  operand: TDynamicLogicFieldValue,
+  path: string,
+  references: {
+    elementIds: Set<string>;
+    variableIds: Set<string>;
+    hiddenFieldIds: Set<string>;
+  },
+  issues: InvalidParam[]
+): void {
+  if (operand.type === "element" && !references.elementIds.has(operand.value)) {
+    issues.push({
+      name: `${path}.value`,
+      reason: `Element id '${operand.value}' is not defined in blocks`,
+    });
+  }
+
+  if (operand.type === "variable" && !references.variableIds.has(operand.value)) {
+    issues.push({
+      name: `${path}.value`,
+      reason: `Variable id '${operand.value}' is not defined in variables`,
+    });
+  }
+
+  if (operand.type === "hiddenField" && !references.hiddenFieldIds.has(operand.value)) {
+    issues.push({
+      name: `${path}.value`,
+      reason: `Hidden field id '${operand.value}' is not defined in hiddenFields.fieldIds`,
+    });
+  }
+}
+
+function validateConditionGroup(
+  conditionGroup: TConditionGroup,
+  path: string,
+  references: {
+    elementIds: Set<string>;
+    variableIds: Set<string>;
+    hiddenFieldIds: Set<string>;
+  },
+  issues: InvalidParam[]
+): void {
+  conditionGroup.conditions.forEach((condition, index) => {
+    const conditionPath = `${path}.conditions.${index}`;
+
+    if ("conditions" in condition) {
+      validateConditionGroup(condition, conditionPath, references, issues);
+      return;
+    }
+
+    validateDynamicOperand(condition.leftOperand, `${conditionPath}.leftOperand`, references, issues);
+
+    if (condition.rightOperand?.type && condition.rightOperand.type !== "static") {
+      validateDynamicOperand(condition.rightOperand, `${conditionPath}.rightOperand`, references, issues);
+    }
+  });
+}
+
+export function getV3SurveyReferenceInvalidParams(input: TReferenceValidationInput): InvalidParam[] {
+  const issues: InvalidParam[] = [];
+  const blockIds = input.blocks.map((block) => block.id);
+  const blockEntries = input.blocks.map((block, index) => ({
+    id: block.id,
+    path: `blocks.${index}.id`,
+  }));
+  const endingIds = input.endings.map((ending) => ending.id);
+  const endingEntries = input.endings.map((ending, index) => ({
+    id: ending.id,
+    path: `endings.${index}.id`,
+  }));
+  const elementEntries = input.blocks.flatMap((block, blockIndex) =>
+    block.elements.map((element, elementIndex) => ({
+      id: element.id,
+      path: `blocks.${blockIndex}.elements.${elementIndex}.id`,
+    }))
+  );
+  const elementIds = elementEntries.map((element) => element.id);
+  const hiddenFieldIds = input.hiddenFields.fieldIds ?? [];
+  const hiddenFieldEntries = hiddenFieldIds.map((id, index) => ({
+    id,
+    path: `hiddenFields.fieldIds.${index}`,
+  }));
+  const variableIds = input.variables.map((variable) => variable.id);
+  const variableIdEntries = variableIds.map((id, index) => ({
+    id,
+    path: `variables.${index}.id`,
+  }));
+  const variableNames = input.variables.map((variable) => variable.name);
+  const variableNameEntries = variableNames.map((id, index) => ({
+    id,
+    path: `variables.${index}.name`,
+  }));
+  const navigationTargetIds = new Set([...blockIds, ...endingIds]);
+  const references = {
+    elementIds: new Set(elementIds),
+    variableIds: new Set(variableIds),
+    hiddenFieldIds: new Set(hiddenFieldIds),
+  };
+
+  addDuplicateIdIssues(blockEntries, "Block", issues);
+  addDuplicateIdIssues(elementEntries, "Element", issues);
+  addDuplicateIdIssues(variableIdEntries, "Variable", issues);
+  addDuplicateValueIssues(
+    hiddenFieldIds,
+    (index) => `hiddenFields.fieldIds.${index}`,
+    "Hidden field id",
+    issues
+  );
+  addDuplicateValueIssues(variableNames, (index) => `variables.${index}.name`, "Variable name", issues);
+  addCrossNamespaceCollisionIssues(
+    [
+      ...blockEntries.map((entry) => ({ ...entry, namespace: "block" as const })),
+      ...elementEntries.map((entry) => ({ ...entry, namespace: "element" as const })),
+      ...endingEntries.map((entry) => ({ ...entry, namespace: "ending" as const })),
+      ...hiddenFieldEntries.map((entry) => ({ ...entry, namespace: "hiddenField" as const })),
+      ...variableIdEntries.map((entry) => ({ ...entry, namespace: "variable" as const })),
+      ...variableNameEntries.map((entry) => ({ ...entry, namespace: "variableName" as const })),
+    ],
+    issues
+  );
+
+  input.blocks.forEach((block, blockIndex) => {
+    if (block.logicFallback && !navigationTargetIds.has(block.logicFallback)) {
+      issues.push({
+        name: `blocks.${blockIndex}.logicFallback`,
+        reason: `Logic fallback target '${block.logicFallback}' is not defined in blocks or endings`,
+      });
+    }
+
+    block.logic?.forEach((logic, logicIndex) => {
+      const logicPath = `blocks.${blockIndex}.logic.${logicIndex}`;
+      validateConditionGroup(logic.conditions, `${logicPath}.conditions`, references, issues);
+
+      logic.actions.forEach((action, actionIndex) => {
+        const actionPath = `${logicPath}.actions.${actionIndex}`;
+
+        if (action.objective === "calculate") {
+          if (!references.variableIds.has(action.variableId)) {
+            issues.push({
+              name: `${actionPath}.variableId`,
+              reason: `Variable id '${action.variableId}' is not defined in variables`,
+            });
+          }
+
+          if (action.value.type !== "static") {
+            validateDynamicOperand(action.value, `${actionPath}.value`, references, issues);
+          }
+        }
+
+        if (action.objective === "requireAnswer" && !references.elementIds.has(action.target)) {
+          issues.push({
+            name: `${actionPath}.target`,
+            reason: `Element id '${action.target}' is not defined in blocks`,
+          });
+        }
+
+        if (action.objective === "jumpToBlock" && !navigationTargetIds.has(action.target)) {
+          issues.push({
+            name: `${actionPath}.target`,
+            reason: `Jump target '${action.target}' is not defined in blocks or endings`,
+          });
+        }
+      });
+    });
+  });
+
+  addRecallReferenceIssues(input.blocks, "blocks", references, issues);
+  addRecallReferenceIssues(input.endings, "endings", references, issues);
+  addRecallReferenceIssues(input.welcomeCard, "welcomeCard", references, issues);
+  addRecallReferenceIssues(input.metadata, "metadata", references, issues);
+
+  return issues;
+}
+
+export function validateV3SurveyReferences(
+  input: TReferenceValidationInput
+): TV3SurveyReferenceValidationResult {
+  const invalidParams = getV3SurveyReferenceInvalidParams(input);
+
+  if (invalidParams.length > 0) {
+    return { ok: false, invalidParams };
+  }
+
+  return { ok: true, invalidParams: [] };
+}
+
+export function assertValidV3SurveyReferences(input: TReferenceValidationInput): void {
+  const result = validateV3SurveyReferences(input);
+
+  if (!result.ok) {
+    throw new V3SurveyReferenceValidationError(result.invalidParams);
+  }
+}
@@ -50,6 +50,10 @@ vi.mock("@/modules/survey/list/lib/survey", async (importOriginal) => {
  };
 });

+vi.mock("./create", () => ({
+  createV3Survey: vi.fn(),
+}));
+
 vi.mock("@formbricks/logger", () => ({
  logger: {
    withContext: vi.fn(() => ({
@@ -1,5 +1,5 @@
 /**
- * GET /api/v3/surveys — list surveys for a workspace.
+ * /api/v3/surveys — list and create block-based survey management resources.
 * Session cookie or x-api-key; scope by workspaceId only.
 */
 import { logger } from "@formbricks/logger";
@@ -7,6 +7,7 @@ import { DatabaseError, ResourceNotFoundError } from "@formbricks/types/errors";
 import { withV3ApiWrapper } from "@/app/api/v3/lib/api-wrapper";
 import { requireV3WorkspaceAccess } from "@/app/api/v3/lib/auth";
 import {
+  createdResponse,
  problemBadRequest,
  problemForbidden,
  problemInternalError,
@@ -14,8 +15,15 @@ import {
 } from "@/app/api/v3/lib/response";
 import { getSurveyCount } from "@/modules/survey/list/lib/survey";
 import { getSurveyListPage } from "@/modules/survey/list/lib/survey-page";
+import { V3SurveyCreatePermissionError, createV3Survey } from "./create";
 import { parseV3SurveysListQuery } from "./parse-v3-surveys-list-query";
-import { serializeV3SurveyListItem } from "./serializers";
+import { V3SurveyReferenceValidationError } from "./reference-validation";
+import { ZV3CreateSurveyBody } from "./schemas";
+import {
+  V3SurveyUnsupportedShapeError,
+  serializeV3SurveyListItem,
+  serializeV3SurveyResource,
+} from "./serializers";

 export const GET = withV3ApiWrapper({
  auth: "both",
@@ -80,3 +88,81 @@ export const GET = withV3ApiWrapper({
    }
  },
 });
+
+export const POST = withV3ApiWrapper({
+  auth: "both",
+  schemas: {
+    body: ZV3CreateSurveyBody,
+  },
+  action: "created",
+  targetType: "survey",
+  handler: async ({ authentication, auditLog, parsedInput, requestId, instance }) => {
+    const { body } = parsedInput;
+    const log = logger.withContext({ requestId, workspaceId: body.workspaceId });
+
+    try {
+      const authResult = await requireV3WorkspaceAccess(
+        authentication,
+        body.workspaceId,
+        "readWrite",
+        requestId,
+        instance
+      );
+      if (authResult instanceof Response) {
+        return authResult;
+      }
+
+      const survey = await createV3Survey(
+        {
+          ...body,
+          workspaceId: authResult.workspaceId,
+        },
+        authentication,
+        requestId,
+        authResult.organizationId
+      );
+      const resource = serializeV3SurveyResource(survey);
+
+      if (auditLog) {
+        auditLog.organizationId = authResult.organizationId;
+        auditLog.targetId = survey.id;
+        auditLog.newObject = resource;
+      }
+
+      return createdResponse(resource, {
+        requestId,
+        location: `/api/v3/surveys/${survey.id}`,
+      });
+    } catch (err) {
+      if (err instanceof V3SurveyReferenceValidationError) {
+        log.warn({ statusCode: 400, invalidParams: err.invalidParams }, "Survey reference validation failed");
+        return problemBadRequest(requestId, "Invalid survey references", {
+          invalid_params: err.invalidParams,
+          instance,
+        });
+      }
+      if (err instanceof V3SurveyUnsupportedShapeError) {
+        log.warn({ statusCode: 400, errorCode: err.name }, "Unsupported survey shape");
+        return problemBadRequest(requestId, err.message, {
+          invalid_params: [{ name: "body", reason: err.message }],
+          instance,
+        });
+      }
+      if (err instanceof V3SurveyCreatePermissionError) {
+        log.warn({ statusCode: 403, errorCode: err.name }, "Survey create permission check failed");
+        return problemForbidden(requestId, err.message, instance);
+      }
+      if (err instanceof ResourceNotFoundError) {
+        log.warn({ statusCode: 403, errorCode: err.name }, "Resource not found");
+        return problemForbidden(requestId, "You are not authorized to access this resource", instance);
+      }
+      if (err instanceof DatabaseError) {
+        log.error({ error: err, statusCode: 500 }, "Database error");
+        return problemInternalError(requestId, "An unexpected error occurred.", instance);
+      }
+
+      log.error({ error: err, statusCode: 500 }, "V3 survey create unexpected error");
+      return problemInternalError(requestId, "An unexpected error occurred.", instance);
+    }
+  },
+});
@@ -0,0 +1,403 @@
+import { describe, expect, test } from "vitest";
+import { ZV3CreateSurveyBody, ZV3PatchSurveyBody, createZV3PatchSurveyBodySchema } from "./schemas";
+
+const validCreateBody = {
+  workspaceId: "clxx1234567890123456789012",
+  name: "Product Feedback",
+  blocks: [
+    {
+      id: "clbk1234567890123456789012",
+      name: "Main Block",
+      elements: [
+        {
+          id: "satisfaction",
+          type: "openText",
+          headline: { "en-US": "What should we improve?" },
+          required: true,
+        },
+      ],
+    },
+  ],
+};
+
+describe("ZV3CreateSurveyBody", () => {
+  test("accepts a valid block-based create body and applies public defaults", () => {
+    const parsed = ZV3CreateSurveyBody.parse(validCreateBody);
+
+    expect(parsed).toMatchObject({
+      workspaceId: validCreateBody.workspaceId,
+      name: "Product Feedback",
+      type: "link",
+      status: "draft",
+      metadata: {},
+      defaultLanguage: "en-US",
+      languages: [],
+      welcomeCard: { enabled: false },
+      endings: [],
+      hiddenFields: { enabled: false },
+      variables: [],
+    });
+    expect(parsed.blocks[0].elements[0]).toMatchObject({
+      headline: { default: "What should we improve?" },
+    });
+  });
+
+  test("normalizes locale maps and language codes before shared survey validation", () => {
+    const parsed = ZV3CreateSurveyBody.parse({
+      ...validCreateBody,
+      defaultLanguage: "en_us",
+      languages: [{ code: "de_de" }],
+      welcomeCard: {
+        enabled: true,
+        headline: { en_us: "Welcome", de_de: "Willkommen" },
+      },
+      blocks: [
+        {
+          ...validCreateBody.blocks[0],
+          elements: [
+            {
+              ...validCreateBody.blocks[0].elements[0],
+              headline: { en_us: "Hello", de_de: "Hallo" },
+            },
+          ],
+        },
+      ],
+    });
+
+    expect(parsed.defaultLanguage).toBe("en-US");
+    expect(parsed.languages).toEqual([{ code: "de-DE", enabled: true }]);
+    expect(parsed.welcomeCard).toMatchObject({
+      headline: { default: "Welcome", "de-DE": "Willkommen" },
+    });
+    expect(parsed.blocks[0].elements[0]).toMatchObject({
+      headline: { default: "Hello", "de-DE": "Hallo" },
+    });
+  });
+
+  test("rejects an invalid defaultLanguage instead of silently defaulting", () => {
+    const result = ZV3CreateSurveyBody.safeParse({
+      ...validCreateBody,
+      defaultLanguage: "not a locale",
+    });
+
+    expect(result.success).toBe(false);
+    expect(result.error?.issues.map((issue) => issue.path.join("."))).toContain("defaultLanguage");
+  });
+
+  test("rejects duplicate locale keys after normalization", () => {
+    const result = ZV3CreateSurveyBody.safeParse({
+      ...validCreateBody,
+      blocks: [
+        {
+          ...validCreateBody.blocks[0],
+          elements: [
+            {
+              ...validCreateBody.blocks[0].elements[0],
+              headline: { "en-US": "Hello", en_us: "Duplicate" },
+            },
+          ],
+        },
+      ],
+    });
+
+    expect(result.success).toBe(false);
+    expect(result.error?.issues.map((issue) => issue.path.join("."))).toContain(
+      "blocks.0.elements.0.headline.en_us"
+    );
+  });
+
+  test("rejects unsupported top-level fields instead of silently ignoring them", () => {
+    const result = ZV3CreateSurveyBody.safeParse({
+      ...validCreateBody,
+      questions: [],
+      styling: {},
+      createdBy: "user_1",
+    });
+
+    expect(result.success).toBe(false);
+    expect(result.error?.issues.map((issue) => issue.path.join("."))).toEqual(
+      expect.arrayContaining(["questions", "styling", "createdBy"])
+    );
+  });
+
+  test("rejects unsupported nested fields instead of stripping them", () => {
+    const result = ZV3CreateSurveyBody.safeParse({
+      ...validCreateBody,
+      blocks: [
+        {
+          ...validCreateBody.blocks[0],
+          targeting: {},
+          elements: [
+            {
+              ...validCreateBody.blocks[0].elements[0],
+              analytics: {},
+            },
+          ],
+        },
+      ],
+    });
+
+    expect(result.success).toBe(false);
+    expect(result.error?.issues.map((issue) => issue.path.join("."))).toEqual(
+      expect.arrayContaining(["blocks.0.targeting", "blocks.0.elements.0.analytics"])
+    );
+  });
+
+  test("rejects element fields that do not belong to the selected element type", () => {
+    const result = ZV3CreateSurveyBody.safeParse({
+      ...validCreateBody,
+      blocks: [
+        {
+          ...validCreateBody.blocks[0],
+          elements: [
+            {
+              ...validCreateBody.blocks[0].elements[0],
+              buttonUrl: "https://example.com",
+              scale: "star",
+            },
+          ],
+        },
+      ],
+    });
+
+    expect(result.success).toBe(false);
+    expect(result.error?.issues.map((issue) => issue.path.join("."))).toContain(
+      "blocks.0.elements.0.buttonUrl"
+    );
+    expect(result.error?.issues.map((issue) => issue.path.join("."))).toContain("blocks.0.elements.0.scale");
+    expect(
+      result.error?.issues.find((issue) => issue.path.join(".") === "blocks.0.elements.0.buttonUrl")
+    ).toMatchObject({
+      message: expect.stringContaining("element type 'openText'"),
+    });
+  });
+
+  test("rejects choice fields that do not belong to the selected element type", () => {
+    const result = ZV3CreateSurveyBody.safeParse({
+      ...validCreateBody,
+      blocks: [
+        {
+          ...validCreateBody.blocks[0],
+          elements: [
+            {
+              id: "choices",
+              type: "multipleChoiceSingle",
+              headline: { "en-US": "Pick one" },
+              required: true,
+              choices: [
+                { id: "choice_1", label: { "en-US": "A" }, imageUrl: "https://example.com/a.png" },
+                { id: "choice_2", label: { "en-US": "B" } },
+              ],
+            },
+          ],
+        },
+      ],
+    });
+
+    expect(result.success).toBe(false);
+    expect(result.error?.issues.map((issue) => issue.path.join("."))).toContain(
+      "blocks.0.elements.0.choices.0.imageUrl"
+    );
+    expect(
+      result.error?.issues.find((issue) => issue.path.join(".") === "blocks.0.elements.0.choices.0.imageUrl")
+    ).toMatchObject({
+      message: expect.stringContaining("Allowed fields: id, label"),
+    });
+  });
+
+  test("does not rewrite locale-shaped objects in logic metadata", () => {
+    const result = ZV3CreateSurveyBody.safeParse({
+      ...validCreateBody,
+      blocks: [
+        {
+          ...validCreateBody.blocks[0],
+          elements: [
+            {
+              ...validCreateBody.blocks[0].elements[0],
+            },
+          ],
+          logic: [
+            {
+              id: "cllog123456789012345678901",
+              conditions: {
+                id: "clgrp123456789012345678901",
+                connector: "and",
+                conditions: [
+                  {
+                    id: "clcon123456789012345678901",
+                    leftOperand: {
+                      type: "element",
+                      value: "satisfaction",
+                      meta: { "en-US": "metadata" },
+                    },
+                    operator: "isSubmitted",
+                  },
+                ],
+              },
+              actions: [
+                {
+                  id: "clact123456789012345678901",
+                  objective: "requireAnswer",
+                  target: "satisfaction",
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    });
+
+    expect(result.success).toBe(true);
+    if (!result.success) {
+      throw new Error("Expected schema validation to pass");
+    }
+    expect(result.data.blocks[0].logic?.[0].conditions.conditions[0]).toMatchObject({
+      leftOperand: {
+        meta: { "en-US": "metadata" },
+      },
+    });
+  });
+
+  test("rejects the internal default translation key in public v3 input", () => {
+    const result = ZV3CreateSurveyBody.safeParse({
+      ...validCreateBody,
+      blocks: [
+        {
+          ...validCreateBody.blocks[0],
+          elements: [
+            {
+              ...validCreateBody.blocks[0].elements[0],
+              headline: { default: "Internal key should not be public" },
+            },
+          ],
+        },
+      ],
+    });
+
+    expect(result.success).toBe(false);
+    expect(result.error?.issues[0].path.join(".")).toBe("blocks.0.elements.0.headline.default");
+  });
+
+  test("preserves arbitrary metadata while normalizing known translatable metadata fields", () => {
+    const parsed = ZV3CreateSurveyBody.parse({
+      ...validCreateBody,
+      metadata: {
+        cx_context: {
+          "de-DE": "This is arbitrary customer metadata, not translation content",
+        },
+        title: {
+          "en-US": "Feedback Survey",
+          "de-DE": "Feedback-Umfrage",
+        },
+      },
+    });
+
+    expect(parsed.metadata).toMatchObject({
+      cx_context: {
+        "de-DE": "This is arbitrary customer metadata, not translation content",
+      },
+      title: {
+        default: "Feedback Survey",
+        "de-DE": "Feedback-Umfrage",
+      },
+    });
+  });
+
+  test("rejects non-link survey types for this survey-template endpoint", () => {
+    const result = ZV3CreateSurveyBody.safeParse({
+      ...validCreateBody,
+      type: "app",
+    });
+
+    expect(result.success).toBe(false);
+    expect(result.error?.issues[0].path).toEqual(["type"]);
+  });
+
+  test("rejects malformed locale maps that do not include the default language", () => {
+    const result = ZV3CreateSurveyBody.safeParse({
+      ...validCreateBody,
+      blocks: [
+        {
+          ...validCreateBody.blocks[0],
+          elements: [
+            {
+              ...validCreateBody.blocks[0].elements[0],
+              headline: { "not a locale": "Hello" },
+            },
+          ],
+        },
+      ],
+    });
+
+    expect(result.success).toBe(false);
+  });
+
+  test("rejects duplicate language entries and disabled default language", () => {
+    const result = ZV3CreateSurveyBody.safeParse({
+      ...validCreateBody,
+      languages: [{ code: "en-US", enabled: false }, { code: "en_us" }],
+    });
+
+    expect(result.success).toBe(false);
+    expect(result.error?.issues.map((issue) => issue.path.join("."))).toEqual(
+      expect.arrayContaining(["languages.0.enabled", "languages.1.code"])
+    );
+  });
+});
+
+describe("ZV3PatchSurveyBody", () => {
+  test("accepts a strict top-level partial and preserves omitted defaults", () => {
+    const parsed = ZV3PatchSurveyBody.parse({
+      name: "Updated survey",
+    });
+
+    expect(parsed).toEqual({ name: "Updated survey" });
+  });
+
+  test("rejects an empty patch body", () => {
+    const result = ZV3PatchSurveyBody.safeParse({});
+
+    expect(result.success).toBe(false);
+    expect(result.error?.issues[0]).toMatchObject({
+      message: "Request body must include at least one updatable field",
+    });
+  });
+
+  test("rejects immutable and out-of-scope fields", () => {
+    const result = ZV3PatchSurveyBody.safeParse({
+      id: "clsv1234567890123456789012",
+      workspaceId: "clxx1234567890123456789012",
+      type: "link",
+      questions: [],
+    });
+
+    expect(result.success).toBe(false);
+    expect(result.error?.issues.map((issue) => issue.path.join("."))).toEqual(
+      expect.arrayContaining(["id", "workspaceId", "type", "questions"])
+    );
+  });
+
+  test("normalizes patch translation maps using the current default language", () => {
+    const parsed = createZV3PatchSurveyBodySchema("de-DE").parse({
+      blocks: [
+        {
+          id: "clbk1234567890123456789012",
+          name: "Main Block",
+          elements: [
+            {
+              id: "satisfaction",
+              type: "openText",
+              headline: { de_de: "Hallo", en_us: "Hello" },
+              required: true,
+            },
+          ],
+        },
+      ],
+    });
+
+    expect(parsed.blocks?.[0].elements[0]).toMatchObject({
+      headline: { default: "Hallo", "en-US": "Hello" },
+    });
+    expect(parsed).not.toHaveProperty("defaultLanguage");
+  });
+});
@@ -0,0 +1,274 @@
+import { describe, expect, test } from "vitest";
+import type { TSurvey } from "@formbricks/types/surveys/types";
+import { V3SurveyUnsupportedShapeError, serializeV3SurveyResource } from "./serializers";
+
+const baseSurvey = {
+  id: "survey_1",
+  workspaceId: "workspace_1",
+  createdAt: new Date("2026-04-21T10:00:00.000Z"),
+  updatedAt: new Date("2026-04-21T11:00:00.000Z"),
+  name: "Product Feedback",
+  type: "link",
+  status: "draft",
+  metadata: { cx: "enterprise" },
+  languages: [
+    {
+      default: true,
+      enabled: true,
+      language: { id: "lang_1", code: "en-US", alias: "en", createdAt: new Date(), updatedAt: new Date() },
+    },
+    {
+      default: false,
+      enabled: true,
+      language: { id: "lang_2", code: "de-DE", alias: "de", createdAt: new Date(), updatedAt: new Date() },
+    },
+    {
+      default: false,
+      enabled: false,
+      language: { id: "lang_3", code: "fr-FR", alias: "fr", createdAt: new Date(), updatedAt: new Date() },
+    },
+  ],
+  questions: [],
+  welcomeCard: {
+    enabled: true,
+    headline: { default: "Welcome", "de-DE": "Willkommen", "fr-FR": "Bienvenue" },
+  },
+  blocks: [
+    {
+      id: "block_1",
+      name: "Intro",
+      elements: [
+        {
+          id: "satisfaction",
+          type: "openText",
+          headline: { default: "What should we improve?", "de-DE": "Was sollen wir verbessern?" },
+          subheader: { default: "Tell us more" },
+          required: true,
+        },
+      ],
+    },
+  ],
+  endings: [],
+  hiddenFields: { enabled: false, fieldIds: [] },
+  variables: [],
+} as unknown as TSurvey;
+
+describe("serializeV3SurveyResource", () => {
+  test("returns canonical multilingual fields using real locale codes", () => {
+    const resource = serializeV3SurveyResource(baseSurvey);
+
+    expect(resource.defaultLanguage).toBe("en-US");
+    expect(resource).not.toHaveProperty("language");
+    expect(resource.languages).toEqual([
+      { code: "en-US", default: true, enabled: true },
+      { code: "de-DE", default: false, enabled: true },
+      { code: "fr-FR", default: false, enabled: false },
+    ]);
+    expect(resource).toMatchObject({
+      welcomeCard: {
+        headline: {
+          "en-US": "Welcome",
+          "de-DE": "Willkommen",
+          "fr-FR": "Bienvenue",
+        },
+      },
+    });
+    expect(resource).toMatchObject({
+      blocks: [
+        {
+          elements: [
+            {
+              headline: {
+                "en-US": "What should we improve?",
+                "de-DE": "Was sollen wir verbessern?",
+              },
+            },
+          ],
+        },
+      ],
+    });
+  });
+
+  test("does not expose the internal default pseudo-locale for surveys without configured languages", () => {
+    const survey = {
+      ...baseSurvey,
+      languages: [],
+      welcomeCard: {
+        enabled: true,
+        headline: { default: "Welcome" },
+      },
+      blocks: [
+        {
+          id: "block_1",
+          name: "Intro",
+          elements: [
+            {
+              id: "satisfaction",
+              type: "openText",
+              headline: { default: "What should we improve?" },
+              required: true,
+            },
+          ],
+        },
+      ],
+    } as unknown as TSurvey;
+
+    const resource = serializeV3SurveyResource(survey);
+
+    expect(resource.defaultLanguage).toBe("en-US");
+    expect(resource.languages).toEqual([{ code: "en-US", default: true, enabled: true }]);
+    expect(resource).toMatchObject({
+      welcomeCard: { headline: { "en-US": "Welcome" } },
+      blocks: [
+        {
+          elements: [
+            {
+              headline: { "en-US": "What should we improve?" },
+            },
+          ],
+        },
+      ],
+    });
+  });
+
+  test("filters the implicit default language for surveys without configured languages", () => {
+    const survey = {
+      ...baseSurvey,
+      languages: [],
+      welcomeCard: {
+        enabled: true,
+        headline: { default: "Welcome" },
+      },
+    } as unknown as TSurvey;
+
+    const resource = serializeV3SurveyResource(survey, { lang: ["en"] });
+
+    expect(resource).not.toHaveProperty("language");
+    expect(resource).toMatchObject({ welcomeCard: { headline: { "en-US": "Welcome" } } });
+  });
+
+  test("preserves stored locale variants when their keys use non-canonical casing or separators", () => {
+    const survey = {
+      ...baseSurvey,
+      welcomeCard: {
+        enabled: true,
+        headline: { default: "Welcome", de_de: "Willkommen" },
+      },
+    } as unknown as TSurvey;
+
+    const resource = serializeV3SurveyResource(survey);
+
+    expect(resource).toMatchObject({
+      welcomeCard: {
+        headline: {
+          "en-US": "Welcome",
+          "de-DE": "Willkommen",
+        },
+      },
+    });
+  });
+
+  test("filters fields for case-insensitive underscore language selectors while preserving maps", () => {
+    const resource = serializeV3SurveyResource(baseSurvey, { lang: ["DE_de"] });
+
+    expect(resource).not.toHaveProperty("language");
+    expect(resource).toMatchObject({
+      welcomeCard: { headline: { "de-DE": "Willkommen" } },
+      blocks: [
+        {
+          elements: [
+            {
+              headline: { "de-DE": "Was sollen wir verbessern?" },
+              subheader: { "de-DE": "Tell us more" },
+            },
+          ],
+        },
+      ],
+    });
+  });
+
+  test("resolves language-only selectors against configured survey languages", () => {
+    const resource = serializeV3SurveyResource(baseSurvey, { lang: ["de"] });
+
+    expect(resource).toMatchObject({ welcomeCard: { headline: { "de-DE": "Willkommen" } } });
+  });
+
+  test("filters disabled configured languages for management reads", () => {
+    const resource = serializeV3SurveyResource(baseSurvey, { lang: ["fr"] });
+
+    expect(resource).toMatchObject({ welcomeCard: { headline: { "fr-FR": "Bienvenue" } } });
+  });
+
+  test("filters multiple requested languages while preserving maps", () => {
+    const resource = serializeV3SurveyResource(baseSurvey, { lang: ["en-US", "de"] });
+
+    expect(resource).not.toHaveProperty("language");
+    expect(resource).toMatchObject({
+      welcomeCard: {
+        headline: {
+          "en-US": "Welcome",
+          "de-DE": "Willkommen",
+        },
+      },
+      blocks: [
+        {
+          elements: [
+            {
+              headline: {
+                "en-US": "What should we improve?",
+                "de-DE": "Was sollen wir verbessern?",
+              },
+            },
+          ],
+        },
+      ],
+    });
+  });
+
+  test("rejects ambiguous language-only selectors", () => {
+    const survey = {
+      ...baseSurvey,
+      languages: [
+        {
+          default: true,
+          enabled: true,
+          language: {
+            id: "lang_1",
+            code: "pt-BR",
+            alias: "br",
+            createdAt: new Date(),
+            updatedAt: new Date(),
+          },
+        },
+        {
+          default: false,
+          enabled: true,
+          language: {
+            id: "lang_2",
+            code: "pt-PT",
+            alias: "pt",
+            createdAt: new Date(),
+            updatedAt: new Date(),
+          },
+        },
+      ],
+    } as unknown as TSurvey;
+
+    expect(() => serializeV3SurveyResource(survey, { lang: ["pt"] })).toThrow(
+      "Language 'pt' is ambiguous for this survey; use one of pt-BR, pt-PT"
+    );
+  });
+
+  test("rejects legacy question-based survey shapes instead of returning an incomplete block resource", () => {
+    const survey = {
+      ...baseSurvey,
+      questions: [{ id: "legacy_question", type: "openText", headline: { default: "Legacy question" } }],
+      blocks: [],
+    } as unknown as TSurvey;
+
+    expect(() => serializeV3SurveyResource(survey)).toThrow(V3SurveyUnsupportedShapeError);
+    expect(() => serializeV3SurveyResource(survey)).toThrow(
+      "Legacy question-based surveys are not supported by the v3 survey management API"
+    );
+  });
+});
@@ -1,13 +1,170 @@
-import type { TSurvey } from "@/modules/survey/list/types/surveys";
+import type { TSurvey as TInternalSurvey } from "@formbricks/types/surveys/types";
+import type { TSurvey as TSurveyListRecord } from "@/modules/survey/list/types/surveys";
+import {
+  type TV3SurveyLanguage,
+  getV3SurveyDefaultLanguage,
+  getV3SurveyLanguages,
+  normalizeV3SurveyLanguageTag,
+  resolveV3SurveyLanguageCode,
+} from "./language";

-export type TV3SurveyListItem = Omit<TSurvey, "singleUse">;
+export type TV3SurveyListItem = Omit<TSurveyListRecord, "singleUse">;
+const DEFAULT_V3_SURVEY_LANGUAGE = "en-US";
+
+type TSerializedValue =
+  | string
+  | number
+  | boolean
+  | null
+  | TSerializedValue[]
+  | { [key: string]: TSerializedValue };
+
+export class V3SurveyLanguageError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "V3SurveyLanguageError";
+  }
+}
+
+export class V3SurveyUnsupportedShapeError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "V3SurveyUnsupportedShapeError";
+  }
+}

 /**
 * Keep the v3 API contract isolated from internal persistence naming.
 * Surveys are scoped by workspaceId.
 */
-export function serializeV3SurveyListItem(survey: TSurvey): TV3SurveyListItem {
+export function serializeV3SurveyListItem(survey: TSurveyListRecord): TV3SurveyListItem {
  const { singleUse: _omitSingleUse, ...rest } = survey;

  return rest;
 }
+
+function toIsoString(value: Date | string): string {
+  return value instanceof Date ? value.toISOString() : new Date(value).toISOString();
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isI18nString(value: unknown): value is Record<string, string> {
+  return (
+    isPlainObject(value) &&
+    typeof value.default === "string" &&
+    Object.values(value).every((entry) => typeof entry === "string")
+  );
+}
+
+function getI18nValueForLanguage(value: Record<string, string>, languageCode: string): string | undefined {
+  if (typeof value[languageCode] === "string") {
+    return value[languageCode];
+  }
+
+  const matchingKey = Object.keys(value).find(
+    (key) => normalizeV3SurveyLanguageTag(key)?.toLowerCase() === languageCode.toLowerCase()
+  );
+  return matchingKey ? value[matchingKey] : undefined;
+}
+
+function serializeCanonicalValue(
+  value: unknown,
+  defaultLanguage: string,
+  languageCodes: Set<string>,
+  options?: { fallbackMissingTranslations?: boolean }
+): TSerializedValue {
+  if (isI18nString(value)) {
+    const result: Record<string, string> = {
+      [defaultLanguage]: value.default,
+    };
+
+    for (const languageCode of languageCodes) {
+      const translatedValue = getI18nValueForLanguage(value, languageCode);
+      if (languageCode !== defaultLanguage) {
+        if (translatedValue !== undefined) {
+          result[languageCode] = translatedValue;
+        } else if (options?.fallbackMissingTranslations) {
+          result[languageCode] = value.default;
+        }
+      }
+    }
+
+    if (!languageCodes.has(defaultLanguage)) {
+      delete result[defaultLanguage];
+    }
+
+    return result;
+  }
+
+  if (Array.isArray(value)) {
+    return value.map((entry) => serializeCanonicalValue(entry, defaultLanguage, languageCodes, options));
+  }
+
+  if (isPlainObject(value)) {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, entry]) => [
+        key,
+        serializeCanonicalValue(entry, defaultLanguage, languageCodes, options),
+      ])
+    );
+  }
+
+  return value as TSerializedValue;
+}
+
+function resolveRequestedLanguage(languages: TV3SurveyLanguage[], language: string): string {
+  const result = resolveV3SurveyLanguageCode(language, languages);
+
+  if (!result.ok) {
+    throw new V3SurveyLanguageError(result.message);
+  }
+
+  return result.code;
+}
+
+function resolveRequestedLanguages(languages: TV3SurveyLanguage[], requestedLanguages?: string[]): string[] {
+  if (!requestedLanguages) {
+    return [];
+  }
+
+  return requestedLanguages.map((language) => resolveRequestedLanguage(languages, language));
+}
+
+export function serializeV3SurveyResource(survey: TInternalSurvey, options?: { lang?: string[] }) {
+  if (Array.isArray(survey.questions) && survey.questions.length > 0) {
+    throw new V3SurveyUnsupportedShapeError(
+      "Legacy question-based surveys are not supported by the v3 survey management API"
+    );
+  }
+
+  const defaultLanguage = getV3SurveyDefaultLanguage(survey, DEFAULT_V3_SURVEY_LANGUAGE);
+  const languages = getV3SurveyLanguages(survey, DEFAULT_V3_SURVEY_LANGUAGE);
+  const configuredLanguageCodes = new Set(languages.map((language) => language.code));
+  const requestedLanguages = resolveRequestedLanguages(languages, options?.lang);
+  const languageCodes = requestedLanguages.length > 0 ? new Set(requestedLanguages) : configuredLanguageCodes;
+  const serializeValue = (value: unknown) =>
+    serializeCanonicalValue(value, defaultLanguage, languageCodes, {
+      fallbackMissingTranslations: requestedLanguages.length > 0,
+    });
+
+  return {
+    id: survey.id,
+    workspaceId: survey.workspaceId,
+    createdAt: toIsoString(survey.createdAt),
+    updatedAt: toIsoString(survey.updatedAt),
+    name: survey.name,
+    type: survey.type,
+    status: survey.status,
+    metadata: survey.metadata,
+    defaultLanguage,
+    languages,
+    welcomeCard: serializeValue(survey.welcomeCard),
+    blocks: serializeValue(survey.blocks),
+    endings: serializeValue(survey.endings),
+    hiddenFields: survey.hiddenFields,
+    variables: survey.variables,
+  };
+}
@@ -0,0 +1,108 @@
+import { z } from "zod";
+import { logger } from "@formbricks/logger";
+import { DatabaseError } from "@formbricks/types/errors";
+import { withV3ApiWrapper } from "@/app/api/v3/lib/api-wrapper";
+import { requireV3WorkspaceAccess } from "@/app/api/v3/lib/auth";
+import { problemInternalError, successResponse } from "@/app/api/v3/lib/response";
+import { getAuthorizedV3Survey } from "../authorization";
+import {
+  type TV3SurveyPrepareResult,
+  prepareV3SurveyCreateInput,
+  prepareV3SurveyPatchInput,
+} from "../prepare";
+import { type TV3SurveyDocument, ZV3EmptyQuery, ZV3SurveyValidationRequestBody } from "../schemas";
+
+const createWorkspaceSchema = z.object({
+  workspaceId: z.cuid2(),
+});
+
+function serializeValidationResult<TDocument extends TV3SurveyDocument>(
+  operation: "create" | "patch",
+  preparation: TV3SurveyPrepareResult<TDocument>
+) {
+  if (!preparation.ok) {
+    return {
+      valid: false,
+      operation,
+      invalid_params: preparation.validation.invalidParams,
+    };
+  }
+
+  return {
+    valid: true,
+    operation,
+    invalid_params: [],
+    languages: preparation.languageRequests.map((languageRequest) => ({
+      ...languageRequest,
+      writeBehavior: "connect_or_create" as const,
+    })),
+  };
+}
+
+export const POST = withV3ApiWrapper({
+  auth: "both",
+  schemas: {
+    body: ZV3SurveyValidationRequestBody,
+    query: ZV3EmptyQuery,
+  },
+  handler: async ({ parsedInput, authentication, requestId, instance }) => {
+    const { body } = parsedInput;
+    const log = logger.withContext({ requestId, operation: body.operation });
+
+    try {
+      if (body.operation === "create") {
+        const workspaceResult = createWorkspaceSchema.safeParse(body.data);
+        if (workspaceResult.success) {
+          const authResult = await requireV3WorkspaceAccess(
+            authentication,
+            workspaceResult.data.workspaceId,
+            "readWrite",
+            requestId,
+            instance
+          );
+
+          if (authResult instanceof Response) {
+            return authResult;
+          }
+        }
+
+        return successResponse(serializeValidationResult("create", prepareV3SurveyCreateInput(body.data)), {
+          requestId,
+          cache: "private, no-store",
+        });
+      }
+
+      const { survey, response } = await getAuthorizedV3Survey({
+        surveyId: body.surveyId,
+        authentication,
+        access: "readWrite",
+        requestId,
+        instance,
+      });
+
+      if (response) {
+        log.warn(
+          { statusCode: response.status, surveyId: body.surveyId },
+          "Survey not found or not accessible"
+        );
+        return response;
+      }
+
+      return successResponse(
+        serializeValidationResult("patch", prepareV3SurveyPatchInput(survey, body.data)),
+        {
+          requestId,
+          cache: "private, no-store",
+        }
+      );
+    } catch (error) {
+      if (error instanceof DatabaseError) {
+        log.error({ error, statusCode: 500 }, "Database error");
+        return problemInternalError(requestId, "An unexpected error occurred.", instance);
+      }
+
+      log.error({ error, statusCode: 500 }, "V3 survey validation unexpected error");
+      return problemInternalError(requestId, "An unexpected error occurred.", instance);
+    }
+  },
+});
@@ -0,0 +1,27 @@
+import type { InvalidParam } from "@/app/api/v3/lib/response";
+import { validateV3SurveyReferences } from "./reference-validation";
+import type { TV3SurveyDocument } from "./schemas";
+
+export type TV3SurveyDocumentValidationResult =
+  | { valid: true; invalidParams: [] }
+  | { valid: false; invalidParams: InvalidParam[] };
+
+export function validateV3SurveyDocument(document: TV3SurveyDocument): TV3SurveyDocumentValidationResult {
+  const referenceValidation = validateV3SurveyReferences({
+    blocks: document.blocks,
+    endings: document.endings,
+    hiddenFields: document.hiddenFields,
+    metadata: document.metadata,
+    variables: document.variables,
+    welcomeCard: document.welcomeCard,
+  });
+
+  if (!referenceValidation.ok) {
+    return {
+      valid: false,
+      invalidParams: referenceValidation.invalidParams,
+    };
+  }
+
+  return { valid: true, invalidParams: [] };
+}
@@ -4,7 +4,7 @@ import { logger } from "@formbricks/logger";
 import { ZDeleteFileRequest, ZDownloadFileRequest } from "@formbricks/types/storage";
 import { responses } from "@/app/lib/api/response";
 import { transformErrorToDetails } from "@/app/lib/api/validator";
-import { authorizePrivateDownload } from "@/app/storage/[workspaceId]/[accessType]/[...filePath]/lib/auth";
+import { authorizePrivateDownload } from "@/app/storage/[workspaceId]/[accessType]/[fileName]/lib/auth";
 import { resolveClientApiIds } from "@/lib/utils/resolve-client-id";
 import { authOptions } from "@/modules/auth/lib/authOptions";
 import { applyRateLimit } from "@/modules/core/rate-limit/helpers";
@@ -15,14 +15,10 @@ import { logFileDeletion } from "./lib/audit-logs";

 export const GET = async (
  request: NextRequest,
-  props: { params: Promise<{ workspaceId: string; accessType: string; filePath: string[] }> }
+  props: { params: Promise<{ workspaceId: string; accessType: string; fileName: string }> }
 ): Promise<Response> => {
  const params = await props.params;
-  const fileName = params.filePath.join("/");
-  const paramValidation = ZDownloadFileRequest.safeParse({
-    accessType: params.accessType,
-    fileName,
-  });
+  const paramValidation = ZDownloadFileRequest.safeParse(params);

  if (!paramValidation.success) {
    return responses.badRequestResponse(
@@ -32,7 +28,7 @@ export const GET = async (
    );
  }

-  const { accessType } = paramValidation.data;
+  const { accessType, fileName } = paramValidation.data;
  const idParam = params.workspaceId;

  // Resolve: the URL param may be an environmentId (old uploads) or workspaceId (new uploads)
@@ -76,14 +72,10 @@ export const GET = async (

 export const DELETE = async (
  request: NextRequest,
-  props: { params: Promise<{ workspaceId: string; accessType: string; filePath: string[] }> }
+  props: { params: Promise<{ workspaceId: string; accessType: string; fileName: string }> }
 ): Promise<Response> => {
  const params = await props.params;
-  const fileName = params.filePath.join("/");
-  const paramValidation = ZDeleteFileRequest.safeParse({
-    accessType: params.accessType,
-    fileName,
-  });
+  const paramValidation = ZDeleteFileRequest.safeParse(params);
  if (!paramValidation.success) {
    const errorDetails = transformErrorToDetails(paramValidation.error);

@@ -96,7 +88,7 @@ export const DELETE = async (
    return responses.badRequestResponse("Fields are missing or incorrectly formatted", errorDetails, true);
  }

-  const { accessType } = paramValidation.data;
+  const { accessType, fileName } = paramValidation.data;
  const idParam = params.workspaceId;

  // Resolve: the URL param may be an environmentId (old uploads) or workspaceId (new uploads)
@@ -148,20 +140,6 @@ export const DELETE = async (
  );

  if (!deleteResult.ok) {
-    if (!("error" in deleteResult)) {
-      logger.error({ deleteResult }, "Unknown delete failure result shape");
-
-      await logFileDeletion({
-        failureReason: "unknown_delete_failure",
-        accessType,
-        userId: session?.user?.id,
-        workspaceId: resolved.workspaceId,
-        apiUrl: request.url,
-      });
-
-      return responses.internalServerErrorResponse("Failed to delete file", true);
-    }
-
    const { error } = deleteResult;

    logger.error({ error }, "Error deleting file");
@@ -22,7 +22,7 @@ import { getElementsFromBlocks } from "@/lib/survey/utils";
 import { getIsQuotasEnabled } from "@/modules/ee/license-check/lib/utils";
 import { reduceQuotaLimits } from "@/modules/ee/quotas/lib/quotas";
 import { deleteFile } from "@/modules/storage/service";
-import { parseStorageFileUrl, resolveStorageUrlsInObject } from "@/modules/storage/utils";
+import { resolveStorageUrlsInObject } from "@/modules/storage/utils";
 import { getOrganizationIdFromWorkspaceId } from "@/modules/survey/lib/organization";
 import { getOrganizationBilling } from "@/modules/survey/lib/survey";
 import { ITEMS_PER_PAGE } from "../constants";
@@ -589,18 +589,14 @@ const findAndDeleteUploadedFilesInResponse = async (response: TResponse, survey:

  const deletionPromises = fileUrls.map(async (fileUrl) => {
    try {
-      const storageFile = parseStorageFileUrl(fileUrl);
+      const { pathname } = new URL(fileUrl);
+      const [, storageId, accessType, fileName] = pathname.split("/").filter(Boolean);

-      if (!storageFile) {
-        throw new Error(`Invalid storage file URL: ${fileUrl}`);
+      if (!storageId || !accessType || !fileName) {
+        throw new Error(`Invalid file path: ${pathname}`);
      }

-      return deleteFile(
-        storageFile.storageId,
-        storageFile.accessType,
-        storageFile.fileName,
-        survey.workspaceId
-      );
+      return deleteFile(storageId, accessType as "private" | "public", fileName, survey.workspaceId);
    } catch (error) {
      logger.error(error, `Failed to delete file ${fileUrl}`);
    }
@@ -733,6 +733,85 @@ describe("Tests for createSurvey", () => {
        })
      );
    });
+
+    test("creates survey languages from validated language inputs", async () => {
+      vi.mocked(getOrganizationByWorkspaceId).mockResolvedValueOnce(mockOrganizationOutput);
+      prisma.survey.create.mockResolvedValueOnce({
+        ...mockSurveyOutput,
+      });
+
+      await createSurvey(mockWorkspaceId, {
+        ...mockCreateSurveyInput,
+        languages: [
+          {
+            default: true,
+            enabled: true,
+            language: {
+              id: "cllang12345678901234567890",
+              code: "en-US",
+              alias: null,
+              workspaceId: mockWorkspaceId,
+              createdAt: new Date(),
+              updatedAt: new Date(),
+            },
+          },
+        ],
+      });
+
+      expect(prisma.survey.create).toHaveBeenCalledWith(
+        expect.objectContaining({
+          data: expect.objectContaining({
+            languages: {
+              create: [
+                {
+                  language: {
+                    connect: {
+                      id: "cllang12345678901234567890",
+                    },
+                  },
+                  default: true,
+                  enabled: true,
+                },
+              ],
+            },
+          }),
+        })
+      );
+    });
+
+    test("preserves an explicitly provided segment relation for existing callers", async () => {
+      vi.mocked(getOrganizationByWorkspaceId).mockResolvedValueOnce(mockOrganizationOutput);
+      prisma.survey.create.mockResolvedValueOnce({
+        ...mockSurveyOutput,
+      });
+
+      await createSurvey(mockWorkspaceId, {
+        ...mockCreateSurveyInput,
+        segment: {
+          id: "clseg123456789012345678901",
+          title: "Segment",
+          description: null,
+          isPrivate: false,
+          filters: [],
+          workspaceId: mockWorkspaceId,
+          surveys: [],
+          createdAt: new Date(),
+          updatedAt: new Date(),
+        },
+      });
+
+      expect(prisma.survey.create).toHaveBeenCalledWith(
+        expect.objectContaining({
+          data: expect.objectContaining({
+            segment: {
+              connect: {
+                id: "clseg123456789012345678901",
+              },
+            },
+          }),
+        })
+      );
+    });
  });

  describe("Sad Path", () => {
@@ -628,9 +628,23 @@ export const createSurvey = async (workspaceId: string, surveyBody: TSurveyCreat
  );

  try {
-    const { createdBy, languages, ...restSurveyBody } = parsedSurveyBody;
+    const { createdBy, languages, segment, followUps, ...restSurveyBody } = parsedSurveyBody;
    const normalizedCloseOn = restSurveyBody.closeOn instanceof Date ? restSurveyBody.closeOn : null;
    const normalizedPublishOn = restSurveyBody.publishOn instanceof Date ? restSurveyBody.publishOn : null;
+    const surveyLanguagesCreateData: Prisma.SurveyLanguageCreateNestedManyWithoutSurveyInput | undefined =
+      languages?.length
+        ? {
+            create: languages.map((surveyLanguage) => ({
+              language: {
+                connect: {
+                  id: surveyLanguage.language.id,
+                },
+              },
+              default: surveyLanguage.default,
+              enabled: surveyLanguage.enabled,
+            })),
+          }
+        : undefined;

    const actionClasses = await getActionClasses(parsedWorkspaceId);

@@ -641,18 +655,15 @@ export const createSurvey = async (workspaceId: string, surveyBody: TSurveyCreat
        publishOn: normalizedPublishOn,
        status: restSurveyBody.status ?? "draft",
      }),
-      // @ts-expect-error - languages would be undefined in case of empty array
-      languages: languages?.length ? languages : undefined,
+      languages: surveyLanguagesCreateData,
+      segment: segment?.id ? { connect: { id: segment.id } } : undefined,
      triggers: restSurveyBody.triggers
        ? handleTriggerUpdates(restSurveyBody.triggers, [], actionClasses)
        : undefined,
      attributeFilters: undefined,
    };
    const data = validateSurveyCreateDataMedia(
-      attachSurveyFollowUpsToCreateData(
-        attachSurveyCreatorToCreateData(baseData, createdBy),
-        restSurveyBody.followUps
-      )
+      attachSurveyFollowUpsToCreateData(attachSurveyCreatorToCreateData(baseData, createdBy), followUps)
    );

    const organization = await getOrganizationByWorkspaceId(parsedWorkspaceId);
@@ -26,7 +26,7 @@ export const fileUploadQuestion: Survey["questions"][number] = {
 export const responseData: Response["data"] = {
  [openTextQuestion.id]: "Open Text Answer",
  [fileUploadQuestion.id]: [
-    `https://example.com/storage/${workspaceId}/private/file1.png`,
-    `https://example.com/storage/${workspaceId}/private/file2.pdf`,
+    `https://example.com/dummy/${workspaceId}/private/file1.png`,
+    `https://example.com/dummy/${workspaceId}/private/file2.pdf`,
  ],
 };
@@ -4,7 +4,6 @@ import { Result, okVoid } from "@formbricks/types/error-handlers";
 import { TSurveyQuestionTypeEnum } from "@formbricks/types/surveys/types";
 import { ApiErrorResponseV2 } from "@/modules/api/v2/types/api-error";
 import { deleteFile } from "@/modules/storage/service";
-import { parseStorageFileUrl } from "@/modules/storage/utils";

 export const findAndDeleteUploadedFilesInResponse = async (
  responseData: Response["data"],
@@ -25,12 +24,13 @@ export const findAndDeleteUploadedFilesInResponse = async (

  const deletionPromises = fileUrls.map(async (fileUrl) => {
    try {
-      const storageFile = parseStorageFileUrl(fileUrl);
+      const { pathname } = new URL(fileUrl);
+      const [, storageId, accessType, fileName] = pathname.split("/").filter(Boolean);

-      if (!storageFile) {
-        throw new Error(`Invalid storage file URL: ${fileUrl}`);
+      if (!storageId || !accessType || !fileName) {
+        throw new Error(`Invalid file path: ${pathname}`);
      }
-      return deleteFile(storageFile.storageId, storageFile.accessType, storageFile.fileName, workspaceId);
+      return deleteFile(storageId, accessType as "private" | "public", fileName, workspaceId);
    } catch (error) {
      logger.error({ error, fileUrl }, "Failed to delete file");
    }
@@ -117,61 +117,6 @@ describe("storage service", () => {
      }
    });

-    test("should generate scoped private upload URL when path segments are provided", async () => {
-      const mockSignedUrlResponse = {
-        ok: true,
-        data: {
-          signedUrl: "https://s3.example.com/upload",
-          presignedFields: { key: "value" },
-        },
-      } as MockedSignedUploadReturn;
-
-      vi.mocked(getSignedUploadUrl).mockResolvedValue(mockSignedUrlResponse);
-
-      const result = await getSignedUrlForUpload(
-        "test-doc.pdf",
-        "ws-123",
-        "application/pdf",
-        "private" as TAccessType,
-        1024 * 1024 * 10,
-        ["surveys", "survey-123", "questions", "question-123"]
-      );
-
-      expect(result.ok).toBe(true);
-      if (result.ok) {
-        expect(result.data.fileUrl).toBe(
-          `/storage/ws-123/private/surveys/survey-123/questions/question-123/test-doc--fid--${mockUUID}.pdf`
-        );
-      }
-
-      expect(getSignedUploadUrl).toHaveBeenCalledWith(
-        `test-doc--fid--${mockUUID}.pdf`,
-        "application/pdf",
-        "ws-123/private/surveys/survey-123/questions/question-123",
-        1024 * 1024 * 10
-      );
-    });
-
-    test.each(["", ".", "..", "bad segment", "bad/segment", "bad\\segment", "bad?segment", "bad#segment"])(
-      "should reject unsafe scoped private upload path segment %s",
-      async (unsafeSegment) => {
-        const result = await getSignedUrlForUpload(
-          "test-doc.pdf",
-          "ws-123",
-          "application/pdf",
-          "private" as TAccessType,
-          1024 * 1024 * 10,
-          ["surveys", unsafeSegment]
-        );
-
-        expect(result.ok).toBe(false);
-        if (!result.ok) {
-          expect(result.error.code).toBe(StorageErrorCode.InvalidInput);
-        }
-        expect(getSignedUploadUrl).not.toHaveBeenCalled();
-      }
-    );
-
    test("should properly sanitize filenames with special characters like # in URL", async () => {
      const mockSignedUrlResponse = {
        ok: true,
@@ -10,18 +10,15 @@ import {
  getSignedUploadUrl,
 } from "@formbricks/storage";
 import { Result, err, ok } from "@formbricks/types/error-handlers";
-import { type TAccessType } from "@formbricks/types/storage";
+import { TAccessType } from "@formbricks/types/storage";
 import { sanitizeFileName } from "./utils";

-const SAFE_FILE_PATH_SEGMENT = /^[A-Za-z0-9_-]+$/;
-
 export const getSignedUrlForUpload = async (
  fileName: string,
  workspaceId: string,
  fileType: string,
  accessType: TAccessType,
-  maxFileUploadSize: number = 1024 * 1024 * 10, // 10MB
-  filePathSegments: string[] = []
+  maxFileUploadSize: number = 1024 * 1024 * 10 // 10MB
 ): Promise<
  Result<
    {
@@ -37,19 +34,17 @@ export const getSignedUrlForUpload = async (
    if (!safeFileName) {
      return err({ code: StorageErrorCode.InvalidInput });
    }
-
-    if (filePathSegments.some((segment) => !SAFE_FILE_PATH_SEGMENT.test(segment))) {
-      return err({ code: StorageErrorCode.InvalidInput });
-    }
-
-    const encodedFilePathSegments = filePathSegments.map((segment) => encodeURIComponent(segment));
    const fileNameWithoutExtension = safeFileName.split(".").slice(0, -1).join(".");
    const fileExtension = safeFileName.split(".").pop();

    const updatedFileName = `${fileNameWithoutExtension}--fid--${randomUUID()}.${fileExtension}`;
-    const filePath = [workspaceId, accessType, ...filePathSegments].join("/");

-    const signedUrlResult = await getSignedUploadUrl(updatedFileName, fileType, filePath, maxFileUploadSize);
+    const signedUrlResult = await getSignedUploadUrl(
+      updatedFileName,
+      fileType,
+      `${workspaceId}/${accessType}`,
+      maxFileUploadSize
+    );

    if (!signedUrlResult.ok) {
      return signedUrlResult;
@@ -59,10 +54,7 @@ export const getSignedUrlForUpload = async (
    return ok({
      signedUrl: signedUrlResult.data.signedUrl,
      presignedFields: signedUrlResult.data.presignedFields,
-      fileUrl: `/storage/${workspaceId}/${accessType}/${[
-        ...encodedFilePathSegments,
-        encodeURIComponent(updatedFileName),
-      ].join("/")}`,
+      fileUrl: `/storage/${workspaceId}/${accessType}/${encodeURIComponent(updatedFileName)}`,
    });
  } catch (error) {
    logger.error({ error }, "Error getting signed url for upload");
@@ -7,12 +7,10 @@ import { TSurveyQuestion } from "@formbricks/types/surveys/types";
 import {
  isAllowedFileExtension,
  isValidImageFile,
-  parseStorageFileUrl,
  resolveStorageUrl,
  resolveStorageUrlAuto,
  resolveStorageUrlsInObject,
  sanitizeFileName,
-  validateClientFileUploads,
  validateFileUploads,
  validateSingleFile,
  validateSurveyAllowsFileUpload,
@@ -371,11 +369,7 @@ describe("storage utils", () => {
        },
      ] as unknown as TSurveyBlock[];

-      expect(
-        validateSurveyAllowsFileUpload({ fileName: "report.pdf", questionId: "element1", blocks })
-      ).toEqual({
-        ok: true,
-      });
+      expect(validateSurveyAllowsFileUpload({ fileName: "report.pdf", blocks })).toEqual({ ok: true });
    });

    test("should allow a matching extension from a legacy file upload question", () => {
@@ -387,9 +381,7 @@ describe("storage utils", () => {
        },
      ] as TSurveyQuestion[];

-      expect(
-        validateSurveyAllowsFileUpload({ fileName: "image.png", questionId: "question1", questions })
-      ).toEqual({ ok: true });
+      expect(validateSurveyAllowsFileUpload({ fileName: "image.png", questions })).toEqual({ ok: true });
    });

    test("should allow any globally safe extension when a file upload has no survey restriction", () => {
@@ -406,11 +398,7 @@ describe("storage utils", () => {
        },
      ] as unknown as TSurveyBlock[];

-      expect(
-        validateSurveyAllowsFileUpload({ fileName: "report.pdf", questionId: "element1", blocks })
-      ).toEqual({
-        ok: true,
-      });
+      expect(validateSurveyAllowsFileUpload({ fileName: "report.pdf", blocks })).toEqual({ ok: true });
    });

    test("should reject surveys without file upload blocks or questions", () => {
@@ -433,9 +421,7 @@ describe("storage utils", () => {
        },
      ] as TSurveyQuestion[];

-      expect(
-        validateSurveyAllowsFileUpload({ fileName: "report.pdf", questionId: "question1", blocks, questions })
-      ).toEqual({
+      expect(validateSurveyAllowsFileUpload({ fileName: "report.pdf", blocks, questions })).toEqual({
        ok: false,
        reason: "no_file_upload_question",
      });
@@ -461,9 +447,7 @@ describe("storage utils", () => {
        },
      ] as unknown as TSurveyBlock[];

-      expect(
-        validateSurveyAllowsFileUpload({ fileName: "report.pdf", questionId: "element2", blocks })
-      ).toEqual({
+      expect(validateSurveyAllowsFileUpload({ fileName: "report.pdf", blocks })).toEqual({
        ok: false,
        reason: "file_extension_not_allowed",
      });
@@ -489,11 +473,7 @@ describe("storage utils", () => {
        },
      ] as unknown as TSurveyBlock[];

-      expect(
-        validateSurveyAllowsFileUpload({ fileName: "report.pdf", questionId: "element2", blocks })
-      ).toEqual({
-        ok: true,
-      });
+      expect(validateSurveyAllowsFileUpload({ fileName: "report.pdf", blocks })).toEqual({ ok: true });
    });

    test("should reject files without a globally safe extension even when the survey has an unrestricted upload", () => {
@@ -504,148 +484,15 @@ describe("storage utils", () => {
        },
      ] as TSurveyQuestion[];

-      expect(
-        validateSurveyAllowsFileUpload({ fileName: "report", questionId: "question1", questions })
-      ).toEqual({
+      expect(validateSurveyAllowsFileUpload({ fileName: "report", questions })).toEqual({
        ok: false,
        reason: "file_extension_not_allowed",
      });
-      expect(
-        validateSurveyAllowsFileUpload({ fileName: "malware.exe", questionId: "question1", questions })
-      ).toEqual({
+      expect(validateSurveyAllowsFileUpload({ fileName: "malware.exe", questions })).toEqual({
        ok: false,
        reason: "file_extension_not_allowed",
      });
    });
-
-    test("should reject a question id that is not the file upload element", () => {
-      const blocks = [
-        {
-          id: "block1",
-          name: "Block 1",
-          elements: [
-            {
-              id: "element1",
-              type: "fileUpload" as const,
-              allowedFileExtensions: ["pdf"],
-            },
-          ],
-        },
-      ] as unknown as TSurveyBlock[];
-
-      expect(
-        validateSurveyAllowsFileUpload({ fileName: "report.pdf", questionId: "element2", blocks })
-      ).toEqual({
-        ok: false,
-        reason: "file_upload_question_not_found",
-      });
-    });
-  });
-
-  describe("validateClientFileUploads", () => {
-    const workspaceId = "clxworkspace123";
-    const surveyId = "clxsurvey123";
-    const questionId = "file_question";
-    const blocks = [
-      {
-        id: "block1",
-        name: "Block 1",
-        elements: [
-          {
-            id: questionId,
-            type: "fileUpload" as const,
-            allowedFileExtensions: ["pdf"],
-          },
-        ],
-      },
-    ] as unknown as TSurveyBlock[];
-
-    test("should accept scoped private storage URLs for the matching survey and question", () => {
-      const responseData = {
-        [questionId]: [
-          `/storage/${workspaceId}/private/surveys/${surveyId}/questions/${questionId}/report--fid--abc.pdf`,
-        ],
-      };
-
-      expect(validateClientFileUploads({ data: responseData, workspaceId, surveyId, blocks })).toBe(true);
-    });
-
-    test("should reject unscoped legacy storage URLs for new client submissions", () => {
-      const responseData = {
-        [questionId]: [`/storage/${workspaceId}/private/report--fid--abc.pdf`],
-      };
-
-      expect(validateClientFileUploads({ data: responseData, workspaceId, surveyId, blocks })).toBe(false);
-    });
-
-    test("should reject scoped URLs for a different survey", () => {
-      const responseData = {
-        [questionId]: [
-          `/storage/${workspaceId}/private/surveys/otherSurvey/questions/${questionId}/report--fid--abc.pdf`,
-        ],
-      };
-
-      expect(validateClientFileUploads({ data: responseData, workspaceId, surveyId, blocks })).toBe(false);
-    });
-
-    test("should reject scoped URLs for a different question", () => {
-      const responseData = {
-        [questionId]: [
-          `/storage/${workspaceId}/private/surveys/${surveyId}/questions/otherQuestion/report--fid--abc.pdf`,
-        ],
-      };
-
-      expect(validateClientFileUploads({ data: responseData, workspaceId, surveyId, blocks })).toBe(false);
-    });
-
-    test("should reject external URLs", () => {
-      const responseData = {
-        [questionId]: ["https://example.com/report--fid--abc.pdf"],
-      };
-
-      expect(validateClientFileUploads({ data: responseData, workspaceId, surveyId, blocks })).toBe(false);
-    });
-
-    test("should reject file extensions not allowed by the matching upload question", () => {
-      const responseData = {
-        [questionId]: [
-          `/storage/${workspaceId}/private/surveys/${surveyId}/questions/${questionId}/image--fid--abc.png`,
-        ],
-      };
-
-      expect(validateClientFileUploads({ data: responseData, workspaceId, surveyId, blocks })).toBe(false);
-    });
-  });
-
-  describe("parseStorageFileUrl", () => {
-    test("should parse nested relative storage URLs", () => {
-      expect(
-        parseStorageFileUrl(
-          "/storage/workspace-123/private/surveys/survey-123/questions/question-123/report.pdf"
-        )
-      ).toEqual({
-        storageId: "workspace-123",
-        accessType: "private",
-        fileName: "surveys/survey-123/questions/question-123/report.pdf",
-      });
-    });
-
-    test("should parse absolute storage URLs", () => {
-      expect(parseStorageFileUrl("https://example.com/storage/workspace-123/public/report.pdf")).toEqual({
-        storageId: "workspace-123",
-        accessType: "public",
-        fileName: "report.pdf",
-      });
-    });
-
-    test.each([
-      "https://example.com/not-storage/workspace-123/private/report.pdf",
-      "/storage/workspace-123/internal/report.pdf",
-      "/storage/workspace-123/private",
-      "not a url",
-    ])("should reject invalid storage URL %s", (fileUrl) => {
-      expect(parseStorageFileUrl(fileUrl)).toBeNull();
-    });
  });

  describe("isValidImageFile", () => {
@@ -1,11 +1,7 @@
 import "server-only";
 import { type StorageError, StorageErrorCode } from "@formbricks/storage";
 import { TResponseData } from "@formbricks/types/responses";
-import {
-  type TAccessType,
-  type TAllowedFileExtension,
-  ZAllowedFileExtension,
-} from "@formbricks/types/storage";
+import { TAllowedFileExtension, ZAllowedFileExtension } from "@formbricks/types/storage";
 import { TSurveyBlock } from "@formbricks/types/surveys/blocks";
 import { TSurveyElementTypeEnum, TSurveyFileUploadElement } from "@formbricks/types/surveys/elements";
 import { TSurveyQuestion, TSurveyQuestionTypeEnum } from "@formbricks/types/surveys/types";
@@ -124,7 +120,7 @@ export type TSurveyFileUploadPermissionResult =
    }
  | {
      ok: false;
-      reason: "no_file_upload_question" | "file_upload_question_not_found" | "file_extension_not_allowed";
+      reason: "no_file_upload_question" | "file_extension_not_allowed";
    };

 const getAllowedFileExtensionFromFileName = (fileName: string): TAllowedFileExtension | null => {
@@ -136,33 +132,21 @@ const getAllowedFileExtensionFromFileName = (fileName: string): TAllowedFileExte
  return extensionValidation.success ? extensionValidation.data : null;
 };

-const getSurveyFileUploadConfigs = ({
+export const validateSurveyAllowsFileUpload = ({
+  fileName,
  blocks,
  questions,
 }: {
+  fileName: string;
  blocks?: TSurveyBlock[] | null;
  questions?: TSurveyQuestion[] | null;
-}): TSurveyFileUploadElement[] => {
-  return [
+}): TSurveyFileUploadPermissionResult => {
+  const fileUploadConfigs = [
    ...(blocks ?? [])
      .flatMap((block) => block.elements)
      .filter((element) => element.type === TSurveyElementTypeEnum.FileUpload),
    ...(questions ?? []).filter((question) => question.type === TSurveyQuestionTypeEnum.FileUpload),
  ] as TSurveyFileUploadElement[];
-};
-
-export const validateSurveyAllowsFileUpload = ({
-  fileName,
-  questionId,
-  blocks,
-  questions,
-}: {
-  fileName: string;
-  questionId: string;
-  blocks?: TSurveyBlock[] | null;
-  questions?: TSurveyQuestion[] | null;
-}): TSurveyFileUploadPermissionResult => {
-  const fileUploadConfigs = getSurveyFileUploadConfigs({ blocks, questions });

  if (fileUploadConfigs.length === 0) {
    return {
@@ -171,15 +155,6 @@ export const validateSurveyAllowsFileUpload = ({
    };
  }

-  const fileUploadConfig = fileUploadConfigs.find((config) => config.id === questionId);
-
-  if (!fileUploadConfig) {
-    return {
-      ok: false,
-      reason: "file_upload_question_not_found",
-    };
-  }
-
  const fileExtension = getAllowedFileExtensionFromFileName(fileName);

  if (!fileExtension) {
@@ -189,9 +164,11 @@ export const validateSurveyAllowsFileUpload = ({
    };
  }

-  const { allowedFileExtensions } = fileUploadConfig;
-  const isFileExtensionAllowed =
-    allowedFileExtensions === undefined || allowedFileExtensions.includes(fileExtension);
+  const isFileExtensionAllowed = fileUploadConfigs.some((fileUploadConfig) => {
+    const { allowedFileExtensions } = fileUploadConfig;
+
+    return allowedFileExtensions === undefined || allowedFileExtensions.includes(fileExtension);
+  });

  return isFileExtensionAllowed
    ? { ok: true }
@@ -201,127 +178,6 @@ export const validateSurveyAllowsFileUpload = ({
      };
 };

-const getStorageUrlPathSegments = (fileUrl: string): string[] | null => {
-  if (!fileUrl.startsWith("/storage/")) return null;
-
-  const pathWithoutSearch = fileUrl.split(/[?#]/)[0];
-  return pathWithoutSearch.split("/").filter(Boolean);
-};
-
-type TParsedStorageFileUrl = {
-  storageId: string;
-  accessType: TAccessType;
-  fileName: string;
-};
-
-export const parseStorageFileUrl = (fileUrl: string): TParsedStorageFileUrl | null => {
-  let pathname: string;
-
-  try {
-    pathname = fileUrl.startsWith("/storage/") ? fileUrl : new URL(fileUrl).pathname;
-  } catch {
-    return null;
-  }
-
-  const pathWithoutSearch = pathname.split(/[?#]/)[0];
-  if (!pathWithoutSearch.startsWith("/storage/")) return null;
-
-  const [storageSegment, storageId, accessType, ...fileNameSegments] = pathWithoutSearch
-    .split("/")
-    .filter(Boolean);
-  const fileName = fileNameSegments.join("/");
-
-  if (
-    storageSegment !== "storage" ||
-    !storageId ||
-    !fileName ||
-    (accessType !== "private" && accessType !== "public")
-  ) {
-    return null;
-  }
-
-  return { storageId, accessType, fileName };
-};
-
-const isScopedPrivateUploadUrl = ({
-  fileUrl,
-  workspaceId,
-  surveyId,
-  questionId,
-}: {
-  fileUrl: string;
-  workspaceId: string;
-  surveyId: string;
-  questionId: string;
-}): boolean => {
-  const segments = getStorageUrlPathSegments(fileUrl);
-
-  if (!segments || segments.length !== 8) return false;
-
-  const [
-    storageSegment,
-    storageWorkspaceId,
-    accessType,
-    surveysSegment,
-    storageSurveyId,
-    questionsSegment,
-    storageQuestionId,
-    fileName,
-  ] = segments;
-
-  return (
-    storageSegment === "storage" &&
-    storageWorkspaceId === workspaceId &&
-    accessType === "private" &&
-    surveysSegment === "surveys" &&
-    storageSurveyId === surveyId &&
-    questionsSegment === "questions" &&
-    storageQuestionId === questionId &&
-    Boolean(fileName)
-  );
-};
-
-export const validateClientFileUploads = ({
-  data,
-  workspaceId,
-  surveyId,
-  blocks,
-  questions,
-}: {
-  data?: TResponseData;
-  workspaceId: string;
-  surveyId: string;
-  blocks?: TSurveyBlock[] | null;
-  questions?: TSurveyQuestion[] | null;
-}): boolean => {
-  if (!data) return true;
-
-  const fileUploadConfigs = getSurveyFileUploadConfigs({ blocks, questions });
-
-  for (const fileUploadConfig of fileUploadConfigs) {
-    const fileUrls = data[fileUploadConfig.id];
-
-    if (fileUrls === undefined) continue;
-    if (!Array.isArray(fileUrls) || !fileUrls.every((url) => typeof url === "string")) return false;
-
-    for (const fileUrl of fileUrls) {
-      if (!validateSingleFile(fileUrl, fileUploadConfig.allowedFileExtensions)) return false;
-      if (
-        !isScopedPrivateUploadUrl({
-          fileUrl,
-          workspaceId,
-          surveyId,
-          questionId: fileUploadConfig.id,
-        })
-      ) {
-        return false;
-      }
-    }
-  }
-
-  return true;
-};
-
 export const isValidImageFile = (fileUrl: string): boolean => {
  const fileName = getOriginalFileNameFromUrl(fileUrl);
  if (!fileName || fileName.endsWith(".")) return false;
@@ -99,12 +99,7 @@ describe("useDeleteSurvey", () => {
      0
    );

-    resolveFetch?.(
-      new Response(JSON.stringify({ data: { id: "survey_1" } }), {
-        status: 200,
-        headers: { "Content-Type": "application/json" },
-      })
-    );
+    resolveFetch?.(new Response(null, { status: 204 }));

    await waitFor(() => expect(result.current.isSuccess).toBe(true));
    expect(invalidateQueriesSpy).toHaveBeenCalledWith({ queryKey: surveyKeys.lists() });
@@ -1,5 +1,10 @@
-import { describe, expect, test } from "vitest";
-import { buildSurveyListSearchParams } from "./v3-surveys-client";
+import { afterEach, describe, expect, test, vi } from "vitest";
+import type { V3ApiError } from "@/modules/api/lib/v3-client";
+import { buildSurveyListSearchParams, deleteSurvey } from "./v3-surveys-client";
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});

 describe("buildSurveyListSearchParams", () => {
  test("emits only supported v3 params using normalized filter values", () => {
@@ -39,3 +44,39 @@ describe("buildSurveyListSearchParams", () => {
    );
  });
 });
+
+describe("deleteSurvey", () => {
+  test("treats 204 No Content as a successful delete", async () => {
+    const fetchMock = vi.fn().mockResolvedValue(new Response(null, { status: 204 }));
+    vi.stubGlobal("fetch", fetchMock);
+
+    await expect(deleteSurvey("survey_1")).resolves.toBeUndefined();
+
+    expect(fetchMock).toHaveBeenCalledWith("/api/v3/surveys/survey_1", {
+      method: "DELETE",
+      cache: "no-store",
+    });
+  });
+
+  test("maps v3 problem responses to V3ApiError", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue(
+        Response.json(
+          {
+            status: 403,
+            detail: "You are not authorized to access this resource",
+            code: "forbidden",
+          },
+          { status: 403 }
+        )
+      )
+    );
+
+    await expect(deleteSurvey("survey_1")).rejects.toMatchObject<V3ApiError>({
+      status: 403,
+      detail: "You are not authorized to access this resource",
+      code: "forbidden",
+    });
+  });
+});
@@ -13,12 +13,6 @@ type TV3SurveyListResponse = {
  meta: TSurveyListPage["meta"];
 };

-type TV3DeleteSurveyResponse = {
-  data: {
-    id: string;
-  };
-};
-
 export type TSurveyListPage = {
  data: TSurveyListItem[];
  meta: {
@@ -122,7 +116,7 @@ export async function listSurveys({
  };
 }

-export async function deleteSurvey(surveyId: string): Promise<{ id: string }> {
+export async function deleteSurvey(surveyId: string): Promise<void> {
  const response = await fetch(`/api/v3/surveys/${surveyId}`, {
    method: "DELETE",
    cache: "no-store",
@@ -131,7 +125,4 @@ export async function deleteSurvey(surveyId: string): Promise<{ id: string }> {
  if (!response.ok) {
    throw await parseV3ApiError(response);
  }
-
-  const body = (await response.json()) as TV3DeleteSurveyResponse;
-  return body.data;
 }
@@ -7,6 +7,7 @@ import { TWorkspaceConfigChannel } from "@formbricks/types/workspace";
 import { CreateSurveyParams, CreateSurveyWithLogicParams } from "@/playwright/utils/mock";

 const MOCK_STORAGE_UPLOAD_PATH = "/__playwright__/mock-storage-upload";
+const MOCK_STORAGE_FILE_PATH = "/storage/playwright-mock";

 type MockStorageFileFixture = {
  name: string;
@@ -43,19 +44,11 @@ const DEFAULT_MOCK_STORAGE_FILE_FIXTURE: MockStorageFileFixture = {
  ),
 };

-const getMockStorageFileUrl = ({
-  appOrigin,
-  fileName,
-  accessType,
-  storageId = "playwright-mock",
-  filePathSegments = [],
-}: {
-  appOrigin: string;
-  fileName: string;
-  accessType: "public" | "private";
-  storageId?: string;
-  filePathSegments?: string[];
-}): string => {
+const getMockStorageFileUrl = (
+  appOrigin: string,
+  fileName: string,
+  accessType: "public" | "private"
+): string => {
  if (accessType === "public") {
    const fixture = PLAYWRIGHT_STORAGE_FILE_FIXTURES.get(fileName);

@@ -64,7 +57,7 @@ const getMockStorageFileUrl = ({
    }
  }

-  return `/storage/${storageId}/${accessType}/${[...filePathSegments, encodeURIComponent(fileName)].join("/")}`;
+  return `${MOCK_STORAGE_FILE_PATH}/${accessType}/${encodeURIComponent(fileName)}`;
 };

 /**
@@ -93,7 +86,7 @@ export const mockStorageUploads = async (page: Page): Promise<void> => {
          presignedFields: {
            key: fileName,
          },
-          fileUrl: getMockStorageFileUrl({ appOrigin, fileName, accessType: "public" }),
+          fileUrl: getMockStorageFileUrl(appOrigin, fileName, "public"),
          signingData: null,
          updatedFileName: fileName,
        },
@@ -120,17 +113,9 @@ export const mockStorageUploads = async (page: Page): Promise<void> => {
        return;
      }

-      const payload = route.request().postDataJSON() as
-        | { fileName?: string; surveyId?: string; questionId?: string }
-        | undefined;
+      const payload = route.request().postDataJSON() as { fileName?: string } | undefined;
      const fileName = payload?.fileName ?? "uploaded-file.bin";
-      const requestUrl = new URL(route.request().url());
-      const appOrigin = requestUrl.origin;
-      const workspaceId = requestUrl.pathname.split("/").filter(Boolean)[3] ?? "playwright-mock";
-      const filePathSegments =
-        payload?.surveyId && payload?.questionId
-          ? ["surveys", payload.surveyId, "questions", payload.questionId]
-          : [];
+      const appOrigin = new URL(route.request().url()).origin;

      await route.fulfill({
        status: 200,
@@ -141,13 +126,7 @@ export const mockStorageUploads = async (page: Page): Promise<void> => {
            presignedFields: {
              key: fileName,
            },
-            fileUrl: getMockStorageFileUrl({
-              appOrigin,
-              fileName,
-              accessType: "private",
-              storageId: workspaceId,
-              filePathSegments,
-            }),
+            fileUrl: getMockStorageFileUrl(appOrigin, fileName, "private"),
            signingData: null,
            updatedFileName: fileName,
          },
@@ -169,7 +148,7 @@ export const mockStorageUploads = async (page: Page): Promise<void> => {
    });
  });

-  await page.route("**/storage/**", async (route) => {
+  await page.route(`**${MOCK_STORAGE_FILE_PATH}/**`, async (route) => {
    if (!["GET", "HEAD"].includes(route.request().method())) {
      await route.fallback();
      return;
@@ -1,7 +1,6 @@
 export interface TUploadFileConfig {
  allowedFileExtensions?: string[] | undefined;
  surveyId?: string | undefined;
-  questionId?: string | undefined;
 }

 export interface TUploadFileResponse {
@@ -259,7 +259,6 @@ export function FileUploadElement({
            {
              allowedFileExtensions: element.allowedFileExtensions,
              surveyId,
-              questionId: element.id,
            }
          );
          return { name: file.name, url: uploadedUrl };
@@ -183,45 +183,6 @@ describe("ApiClient", () => {
      expect(fileUrl).toBe("https://fake-file-url.com");
    });

-    test("includes surveyId and questionId in the upload signing request", async () => {
-      vi.mocked(global.fetch)
-        .mockResolvedValueOnce({
-          ok: true,
-          json: async () => ({
-            data: {
-              signedUrl: "https://fake-s3-url.com",
-              fileUrl: "/storage/ws-test/private/surveys/survey123/questions/question123/test.jpg",
-              presignedFields: { policy: "test" },
-              signingData: null,
-              updatedFileName: "test.jpg",
-            },
-          }),
-        } as unknown as Response)
-        .mockResolvedValueOnce({ ok: true } as unknown as Response);
-
-      await client.uploadFile(
-        {
-          base64: "data:image/jpeg;base64,abcd",
-          name: "test.jpg",
-          type: "image/jpeg",
-        },
-        {
-          allowedFileExtensions: ["jpg"],
-          surveyId: "survey123",
-          questionId: "question123",
-        }
-      );
-
-      const requestInit = vi.mocked(global.fetch).mock.calls[0][1] as RequestInit;
-      expect(JSON.parse(requestInit.body as string)).toEqual({
-        fileName: "test.jpg",
-        fileType: "image/jpeg",
-        allowedFileExtensions: ["jpg"],
-        surveyId: "survey123",
-        questionId: "question123",
-      });
-    });
-
    test("throws an error if file is invalid", async () => {
      await expect(() => client.uploadFile({ base64: "", name: "", type: "" } as any)).rejects.toThrow(
        "Invalid file object"
@@ -116,7 +116,7 @@ export class ApiClient {
      name: string;
      base64: string;
    },
-    { allowedFileExtensions, surveyId, questionId }: TUploadFileConfig | undefined = {}
+    { allowedFileExtensions, surveyId }: TUploadFileConfig | undefined = {}
  ): Promise<string> {
    if (!file.name || !file.type || !file.base64) {
      throw new Error(`Invalid file object`);
@@ -127,7 +127,6 @@ export class ApiClient {
      fileType: file.type,
      allowedFileExtensions,
      surveyId,
-      questionId,
    };

    const response = await fetch(`${this.appUrl}/api/v1/client/${this.workspaceId}/storage`, {
@@ -114,7 +114,6 @@ export const ZDeleteFileRequest = ZDownloadFileRequest;
 export const ZUploadFileConfig = z.object({
  allowedFileExtensions: z.array(z.string()).optional(),
  surveyId: z.string().optional(),
-  questionId: z.string().optional(),
 });

 export type TUploadFileConfig = z.infer<typeof ZUploadFileConfig>;
@@ -125,14 +124,6 @@ export const ZUploadPrivateFileRequest = z
    fileType: z.string().trim().min(1),
    allowedFileExtensions: z.array(ZAllowedFileExtension).optional(),
    surveyId: z.cuid2(),
-    questionId: z
-      .string()
-      .trim()
-      .min(1)
-      .regex(
-        /^[a-zA-Z0-9_-]+$/,
-        "Question id must contain only alphanumeric characters, hyphens, or underscores"
-      ),
    workspaceId: z.cuid2(),
  })
  .superRefine((data, ctx) => {
@@ -278,11 +278,13 @@ export const ZSurveyRecaptcha = z

 export type TSurveyRecaptcha = z.infer<typeof ZSurveyRecaptcha>;

-export const ZSurveyMetadata = z.object({
-  title: ZI18nString.optional(),
-  description: ZI18nString.optional(),
-  ogImage: ZStorageUrl.optional(),
-});
+export const ZSurveyMetadata = z
+  .object({
+    title: ZI18nString.optional(),
+    description: ZI18nString.optional(),
+    ogImage: ZStorageUrl.optional(),
+  })
+  .catchall(z.unknown());

 export type TSurveyMetadata = z.infer<typeof ZSurveyMetadata>;