chore: update openapi example

Co-authored-by: pandeymangg <anshuman.pandey9999@gmail.com>

apps/web/app/api/v3/lib/response.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, test } from "vitest";
 import {
+  noContentResponse,
   problemBadRequest,
   problemForbidden,
   problemInternalError,
@@ -118,3 +119,13 @@ describe("successResponse", () => {
     expect(res.headers.get("Cache-Control")).toBe("private, max-age=60");
   });
 });
+
+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("");
+  });
+});

apps/web/app/api/v3/lib/response.ts

@@ -171,3 +171,18 @@ export function successResponse<T>(
     }
   );
 }
+
+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,
+  });
+}

apps/web/app/api/v3/surveys/[surveyId]/route.test.ts

@@ -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,
-        }),
-      })
-    );
-  });
-});

apps/web/app/api/v3/surveys/[surveyId]/route.ts

@@ -3,41 +3,173 @@ 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 {
+  noContentResponse,
+  problemBadRequest,
+  problemForbidden,
+  problemInternalError,
+  successResponse,
+} from "@/app/api/v3/lib/response";
+import {
+  V3SurveyLanguageError,
+  V3SurveyUnsupportedShapeError,
+  serializeV3SurveyResource,
+} from "@/app/api/v3/surveys/serializers";
 import { getSurvey } from "@/lib/survey/service";
 import { deleteSurvey } from "@/modules/survey/lib/surveys";
+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();
+
+async function getAuthorizedSurvey(params: {
+  surveyId: string;
+  authentication: Parameters<typeof requireV3WorkspaceAccess>[0];
+  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 };
+}
+
+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 getAuthorizedSurvey({
+        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 getAuthorizedSurvey({
+        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 +178,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");

apps/web/app/api/v3/surveys/language.test.ts

@@ -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",
+    });
+  });
+});

apps/web/app/api/v3/surveys/language.ts

@@ -0,0 +1,112 @@
+type TV3SurveyLanguageInput = {
+  code: string;
+  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`,
+  };
+}

apps/web/app/api/v3/surveys/serializers.test.ts

@@ -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"
+    );
+  });
+});

apps/web/app/api/v3/surveys/serializers.ts

@@ -1,13 +1,192 @@
-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 { normalizeV3SurveyLanguageTag, resolveV3SurveyLanguageCode } from "./language";
 
-export type TV3SurveyListItem = Omit<TSurvey, "singleUse">;
+export type TV3SurveyListItem = Omit<TSurveyListRecord, "singleUse">;
+const DEFAULT_V3_SURVEY_LANGUAGE = "en-US";
+
+type TV3SurveyLanguage = {
+  code: string;
+  default: boolean;
+  enabled: boolean;
+};
+
+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 getSurveyLanguages(survey: TInternalSurvey): 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: DEFAULT_V3_SURVEY_LANGUAGE, default: true, enabled: true }];
+  }
+
+  return languages;
+}
+
+function getDefaultLanguage(survey: TInternalSurvey): string {
+  const defaultLanguageCode = survey.languages?.find((surveyLanguage) => surveyLanguage.default)?.language
+    .code;
+  return defaultLanguageCode
+    ? (normalizeV3SurveyLanguageTag(defaultLanguageCode) ?? defaultLanguageCode)
+    : DEFAULT_V3_SURVEY_LANGUAGE;
+}
+
+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 = getDefaultLanguage(survey);
+  const languages = getSurveyLanguages(survey);
+  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,
+  };
+}

apps/web/modules/survey/list/hooks/use-delete-survey.test.ts

@@ -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() });

apps/web/modules/survey/list/lib/v3-surveys-client.test.ts

@@ -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",
+    });
+  });
+});

apps/web/modules/survey/list/lib/v3-surveys-client.ts

@@ -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;
 }

docs/api-v3-reference/openapi.yml

@@ -1,12 +1,11 @@
 # V3 API — Surveys (hand-maintained; not generated by generate-api-specs).
 # Implementation: apps/web/app/api/v3/surveys/route.ts and apps/web/app/api/v3/surveys/[surveyId]/route.ts
-# See apps/web/app/api/v3/README.md and docs/Survey-Server-Actions.md (Part III) for full context.
 
 openapi: 3.1.0
 info:
   title: Formbricks API v3
   description: |
-    **GET /api/v3/surveys** and **DELETE /api/v3/surveys/{surveyId}** — authenticate with **session cookie** or **`x-api-key`** (management key with access to the workspace).
+    **GET /api/v3/surveys**, **GET /api/v3/surveys/{surveyId}**, and **DELETE /api/v3/surveys/{surveyId}** — authenticate with **session cookie** or **`x-api-key`** (management key with access to the workspace).
 
     **Spec location:** `docs/api-v3-reference/openapi.yml` (alongside v2 at `docs/api-v2-reference/openapi.yml`).
 
@@ -34,7 +33,7 @@ info:
     The v3-backed survey overview page intentionally removes actions that are not yet exposed by this contract: `Created by` filtering, `Duplicate`, `Copy...`, `Preview`, and `Copy link`.
 
     **Next steps (out of scope for this spec)**
-    Additional v3 survey endpoints, optional ETag/304, field selection — see Survey-Server-Actions.md Part III.
+    Additional v3 survey write endpoints, optional ETag/304, field selection, and survey version history.
   version: 0.1.0
   x-implementation-notes:
     route: apps/web/app/api/v3/surveys/route.ts
@@ -198,6 +197,174 @@ paths:
         - sessionAuth: []
         - apiKeyAuth: []
   /api/v3/surveys/{surveyId}:
+    get:
+      operationId: getSurveyV3
+      summary: Retrieve a survey
+      description: |
+        Returns the public v3 survey management resource for one survey. By default, translatable
+        fields are returned as canonical multilingual maps keyed by real locale codes. Use `lang`
+        to filter those maps to one or more requested locale codes.
+      tags:
+        - V3 Surveys
+      parameters:
+        - in: path
+          name: surveyId
+          required: true
+          schema:
+            type: string
+            format: cuid2
+          description: Survey identifier.
+        - in: query
+          name: lang
+          required: false
+          style: form
+          explode: false
+          schema:
+            type: array
+            items:
+              type: string
+            examples:
+              - [de-DE]
+              - [de-DE, pt-PT]
+          description: |
+            Comma-separated locale code filter for translatable fields, for example `?lang=de-DE,pt-PT`.
+            The response shape stays stable: translatable fields are always maps keyed by locale code, never
+            strings. The parser is case-insensitive, accepts `_` or `-` separators, and normalizes to canonical
+            BCP 47 casing (`de_DE`, `DE-de` → `de-DE`). A language-only selector (`de`) resolves to the matching
+            configured survey language when exactly one exists; otherwise it returns `400`. Disabled-but-configured
+            languages are readable in the management API so unfinished translations can be completed. Aliases are
+            not accepted.
+      responses:
+        "200":
+          description: Survey retrieved successfully
+          headers:
+            X-Request-Id:
+              schema: { type: string }
+              description: Request correlation ID
+            Cache-Control:
+              schema: { type: string }
+              example: "private, no-store"
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [data]
+                properties:
+                  data:
+                    $ref: "#/components/schemas/SurveyResource"
+              examples:
+                canonical:
+                  summary: Canonical multilingual authoring resource
+                  value:
+                    data:
+                      id: clseedsurveycsat000000
+                      workspaceId: clseedworkspace000000000
+                      createdAt: "2026-05-18T09:24:54.014Z"
+                      updatedAt: "2026-05-18T09:24:54.014Z"
+                      name: CSAT Survey
+                      type: link
+                      status: inProgress
+                      metadata: {}
+                      defaultLanguage: en-US
+                      languages:
+                        - code: en-US
+                          default: true
+                          enabled: true
+                        - code: de-DE
+                          default: false
+                          enabled: false
+                      welcomeCard:
+                        enabled: false
+                      blocks:
+                        - id: e0tfwzqk63op37y14z95qq3k
+                          name: Main Block
+                          elements:
+                            - id: nzte4cm8836hgjw63pesziht
+                              type: rating
+                              range: 5
+                              scale: smiley
+                              headline:
+                                en-US: How satisfied are you with our product?
+                                de-DE: Wie zufrieden sind Sie mit unserem Produkt?
+                              required: true
+                      endings: []
+                      hiddenFields:
+                        enabled: false
+                      variables: []
+                filtered:
+                  summary: Language-filtered projection with ?lang=de-DE
+                  value:
+                    data:
+                      id: clseedsurveycsat000000
+                      workspaceId: clseedworkspace000000000
+                      createdAt: "2026-05-18T09:24:54.014Z"
+                      updatedAt: "2026-05-18T09:24:54.014Z"
+                      name: CSAT Survey
+                      type: link
+                      status: inProgress
+                      metadata: {}
+                      defaultLanguage: en-US
+                      languages:
+                        - code: en-US
+                          default: true
+                          enabled: true
+                        - code: de-DE
+                          default: false
+                          enabled: false
+                      welcomeCard:
+                        enabled: false
+                      blocks:
+                        - id: e0tfwzqk63op37y14z95qq3k
+                          name: Main Block
+                          elements:
+                            - id: nzte4cm8836hgjw63pesziht
+                              type: rating
+                              range: 5
+                              scale: smiley
+                              headline:
+                                de-DE: Wie zufrieden sind Sie mit unserem Produkt?
+                              required: true
+                      endings: []
+                      hiddenFields:
+                        enabled: false
+                      variables: []
+        "400":
+          description: Invalid survey id, unsupported query parameter, unknown language, or unsupported legacy survey shape
+          content:
+            application/problem+json:
+              schema:
+                $ref: "#/components/schemas/Problem"
+        "401":
+          description: Not authenticated (no valid session or API key)
+          content:
+            application/problem+json:
+              schema:
+                $ref: "#/components/schemas/Problem"
+        "403":
+          description: Forbidden — no access, or survey does not exist (404 not used; avoids existence leak)
+          content:
+            application/problem+json:
+              schema:
+                $ref: "#/components/schemas/Problem"
+        "429":
+          description: Rate limit exceeded
+          headers:
+            Retry-After:
+              schema: { type: integer }
+              description: Seconds until the current rate-limit window resets
+          content:
+            application/problem+json:
+              schema:
+                $ref: "#/components/schemas/Problem"
+        "500":
+          description: Internal Server Error
+          content:
+            application/problem+json:
+              schema:
+                $ref: "#/components/schemas/Problem"
+      security:
+        - sessionAuth: []
+        - apiKeyAuth: []
     delete:
       operationId: deleteSurveyV3
       summary: Delete a survey
@@ -213,7 +380,7 @@ paths:
             format: cuid2
           description: Survey identifier.
       responses:
-        "200":
+        "204":
           description: Survey deleted successfully
           headers:
             X-Request-Id:
@@ -222,10 +389,6 @@ paths:
             Cache-Control:
               schema: { type: string }
               example: "private, no-store"
-          content:
-            application/json:
-              schema:
-                $ref: "#/components/schemas/SurveyDeleteResponse"
         "400":
           description: Bad Request
           content:
@@ -304,15 +467,694 @@ components:
           properties:
             enabled: { type: boolean }
             isEncrypted: { type: boolean }
-    SurveyDeleteResponse:
+    TranslatableText:
+      allOf:
+        - $ref: "#/components/schemas/TranslatableTextMap"
+      description: |
+        Survey authoring text. `GET /api/v3/surveys/{surveyId}` always returns locale maps keyed by
+        real locale codes such as `en-US` and `de-DE`. Use `?lang=` to filter which locale keys are included.
+        The internal storage key `default` is never exposed by v3.
+      examples:
+        - en-US: What should we improve?
+          de-DE: Was sollten wir verbessern?
+    TranslatableTextMap:
       type: object
-      required: [data]
+      description: Canonical multilingual text map keyed by real locale codes.
+      propertyNames:
+        type: string
+        description: BCP 47 locale code, for example `en-US`, `de-DE`, or `pt-BR`.
+      additionalProperties:
+        type: string
+    SurveyLanguage:
+      type: object
+      description: |
+        Language configured for this survey. Aliases/display names are intentionally not exposed in v3.
+        Disabled languages can still be read by the management API so unfinished translations can be completed.
+      required: [code, default, enabled]
       properties:
-        data:
+        code:
+          type: string
+          description: Canonical locale code.
+          example: en-US
+        default:
+          type: boolean
+          description: Whether this is the default authoring language.
+        enabled:
+          type: boolean
+          description: Whether this language is enabled for respondent-facing delivery.
+    SurveyWelcomeCard:
+      type: object
+      description: Optional card shown before the first survey block.
+      required: [enabled]
+      properties:
+        enabled:
+          type: boolean
+        headline:
+          $ref: "#/components/schemas/TranslatableText"
+        subheader:
+          $ref: "#/components/schemas/TranslatableText"
+        buttonLabel:
+          $ref: "#/components/schemas/TranslatableText"
+        fileUrl:
+          type: string
+        videoUrl:
+          type: string
+        timeToFinish:
+          type: boolean
+        showResponseCount:
+          type: boolean
+      additionalProperties: true
+    SurveyHiddenFields:
+      type: object
+      description: |
+        Hidden fields, sometimes called embedded data in other survey products. Field ids are stable
+        public identifiers and may be referenced by logic, recall, quotas, integrations, and response data.
+        Use only letters, numbers, underscores, and hyphens; avoid spaces and reserved ids.
+      required: [enabled]
+      properties:
+        enabled:
+          type: boolean
+        fieldIds:
+          type: array
+          items:
+            type: string
+            pattern: "^[a-zA-Z0-9_-]+$"
+          uniqueItems: true
+      additionalProperties: false
+    SurveyVariable:
+      oneOf:
+        - $ref: "#/components/schemas/SurveyNumberVariable"
+        - $ref: "#/components/schemas/SurveyTextVariable"
+      description: |
+        Survey variable. Variable ids are stable references used by logic and calculation actions.
+        Variable names are human-readable labels and must be unique within the survey.
+    SurveyNumberVariable:
+      type: object
+      description: |
+        Number variable. Used by `calculate` logic actions with numeric operators such as `add`,
+        `subtract`, `multiply`, `divide`, or `assign`.
+      required: [id, name, type, value]
+      properties:
+        id:
+          type: string
+          format: cuid2
+          description: Stable variable id referenced from logic.
+        name:
+          type: string
+          pattern: "^[a-z0-9_]+$"
+          description: Unique variable name. Lowercase letters, numbers, and underscores only.
+        type:
+          type: string
+          enum: [number]
+        value:
+          type: number
+          description: Default numeric value.
+      additionalProperties: false
+    SurveyTextVariable:
+      type: object
+      description: |
+        Text variable. Used by `calculate` logic actions with text operators such as `assign` or `concat`.
+      required: [id, name, type, value]
+      properties:
+        id:
+          type: string
+          format: cuid2
+          description: Stable variable id referenced from logic.
+        name:
+          type: string
+          pattern: "^[a-z0-9_]+$"
+          description: Unique variable name. Lowercase letters, numbers, and underscores only.
+        type:
+          type: string
+          enum: [text]
+        value:
+          type: string
+          description: Default text value.
+      additionalProperties: false
+    SurveyEnding:
+      type: object
+      description: Ending reached after the last block or a jump action.
+      required: [id, type]
+      properties:
+        id:
+          type: string
+          format: cuid2
+          description: Stable ending id. `jumpToBlock.target` may point to this id.
+        type:
+          type: string
+          enum: [endScreen, redirectToUrl]
+        headline:
+          $ref: "#/components/schemas/TranslatableText"
+        subheader:
+          $ref: "#/components/schemas/TranslatableText"
+        buttonLabel:
+          $ref: "#/components/schemas/TranslatableText"
+        buttonLink:
+          type: string
+        imageUrl:
+          type: string
+        videoUrl:
+          type: string
+        url:
+          type: string
+          description: Redirect URL for `redirectToUrl` endings.
+        label:
+          type: string
+          description: Optional internal label for redirect endings.
+      additionalProperties: true
+    SurveyBlock:
+      type: object
+      description: |
+        Block-based survey section. Block ids are stable public identifiers. Logic and fallbacks can
+        jump to block ids or ending ids, so clients and agents should preserve ids unless intentionally
+        creating/deleting a block.
+      required: [id, name, elements]
+      properties:
+        id:
+          type: string
+          format: cuid2
+          description: Stable block id.
+        name:
+          type: string
+          minLength: 1
+        elements:
+          type: array
+          minItems: 1
+          items:
+            $ref: "#/components/schemas/SurveyElement"
+        logic:
+          type: array
+          items:
+            $ref: "#/components/schemas/SurveyBlockLogic"
+        logicFallback:
+          type: string
+          format: cuid2
+          description: Block or ending id used when no logic condition matches.
+        buttonLabel:
+          $ref: "#/components/schemas/TranslatableText"
+        backButtonLabel:
+          $ref: "#/components/schemas/TranslatableText"
+      additionalProperties: true
+    SurveyElement:
+      type: object
+      description: |
+        Survey element/question inside a block. Element ids are stable public identifiers used by
+        logic, recall strings, response data, quotas, integrations, and analysis. The schema lists
+        the fields used by all current element types; type-specific fields are present only when relevant.
+      required: [id, type, headline, required]
+      properties:
+        id:
+          type: string
+          pattern: "^[a-zA-Z0-9_-]+$"
+          description: Stable element id. Avoid spaces and reserved ids.
+        type:
+          type: string
+          enum:
+            - openText
+            - multipleChoiceSingle
+            - multipleChoiceMulti
+            - nps
+            - rating
+            - csat
+            - ces
+            - consent
+            - pictureSelection
+            - cta
+            - date
+            - fileUpload
+            - cal
+            - matrix
+            - address
+            - ranking
+            - contactInfo
+        headline:
+          $ref: "#/components/schemas/TranslatableText"
+        subheader:
+          $ref: "#/components/schemas/TranslatableText"
+        required:
+          type: boolean
+        imageUrl:
+          type: string
+        videoUrl:
+          type: string
+        isDraft:
+          type: boolean
+          description: Draft marker used by the editor and future update rules.
+        placeholder:
+          $ref: "#/components/schemas/TranslatableText"
+        longAnswer:
+          type: boolean
+          description: "`openText` only."
+        inputType:
+          type: string
+          enum: [text, email, url, number, phone]
+          description: "`openText` only."
+        charLimit:
           type: object
-          required: [id]
+          description: "`openText` character limit configuration."
           properties:
-            id: { type: string }
+            enabled:
+              type: boolean
+            min:
+              type: number
+            max:
+              type: number
+          additionalProperties: false
+        choices:
+          type: array
+          description: Choice list for multiple choice, ranking, and picture selection elements.
+          items:
+            oneOf:
+              - $ref: "#/components/schemas/SurveyChoice"
+              - $ref: "#/components/schemas/SurveyPictureChoice"
+        shuffleOption:
+          type: string
+          enum: [none, all, exceptLast, reverseOrderOccasionally, reverseOrderExceptLast]
+        displayType:
+          type: string
+          enum: [list, dropdown]
+          description: Multiple choice display style.
+        otherOptionPlaceholder:
+          $ref: "#/components/schemas/TranslatableText"
+        lowerLabel:
+          $ref: "#/components/schemas/TranslatableText"
+        upperLabel:
+          $ref: "#/components/schemas/TranslatableText"
+        isColorCodingEnabled:
+          type: boolean
+        scale:
+          type: string
+          enum: [number, smiley, star]
+          description: Rating, CSAT, CES, or NPS scale display.
+        range:
+          type: integer
+          enum: [3, 4, 5, 6, 7, 10]
+          description: Rating range. CSAT is always 5; CES is 5 or 7.
+        label:
+          $ref: "#/components/schemas/TranslatableText"
+          description: Consent checkbox label.
+        allowMulti:
+          type: boolean
+          description: "`pictureSelection` only."
+        buttonExternal:
+          type: boolean
+          description: "`cta` only."
+        buttonUrl:
+          type: string
+          description: "`cta` only."
+        ctaButtonLabel:
+          $ref: "#/components/schemas/TranslatableText"
+        html:
+          $ref: "#/components/schemas/TranslatableText"
+          description: "`date` helper copy."
+        format:
+          type: string
+          enum: [M-d-y, d-M-y, y-M-d]
+          description: "`date` only."
+        allowMultipleFiles:
+          type: boolean
+          description: "`fileUpload` only."
+        maxSizeInMB:
+          type: number
+          description: "`fileUpload` only."
+        allowedFileExtensions:
+          type: array
+          items:
+            type: string
+          description: "`fileUpload` only."
+        calUserName:
+          type: string
+          description: "`cal` only."
+        calHost:
+          type: string
+          description: "`cal` only."
+        rows:
+          type: array
+          description: Matrix rows.
+          items:
+            $ref: "#/components/schemas/SurveyChoice"
+        columns:
+          type: array
+          description: Matrix columns.
+          items:
+            $ref: "#/components/schemas/SurveyChoice"
+        addressLine1:
+          $ref: "#/components/schemas/SurveyToggleInputConfig"
+        addressLine2:
+          $ref: "#/components/schemas/SurveyToggleInputConfig"
+        city:
+          $ref: "#/components/schemas/SurveyToggleInputConfig"
+        state:
+          $ref: "#/components/schemas/SurveyToggleInputConfig"
+        zip:
+          $ref: "#/components/schemas/SurveyToggleInputConfig"
+        country:
+          $ref: "#/components/schemas/SurveyToggleInputConfig"
+        firstName:
+          $ref: "#/components/schemas/SurveyToggleInputConfig"
+        lastName:
+          $ref: "#/components/schemas/SurveyToggleInputConfig"
+        email:
+          $ref: "#/components/schemas/SurveyToggleInputConfig"
+        phone:
+          $ref: "#/components/schemas/SurveyToggleInputConfig"
+        company:
+          $ref: "#/components/schemas/SurveyToggleInputConfig"
+        validation:
+          $ref: "#/components/schemas/SurveyValidation"
+      additionalProperties: true
+    SurveyChoice:
+      type: object
+      required: [id, label]
+      properties:
+        id:
+          type: string
+          description: Stable choice id.
+        label:
+          $ref: "#/components/schemas/TranslatableText"
+      additionalProperties: false
+    SurveyPictureChoice:
+      type: object
+      required: [id, imageUrl]
+      properties:
+        id:
+          type: string
+          description: Stable picture choice id.
+        imageUrl:
+          type: string
+      additionalProperties: false
+    SurveyToggleInputConfig:
+      type: object
+      description: Field config for address and contact info elements.
+      required: [show, required, placeholder]
+      properties:
+        show:
+          type: boolean
+        required:
+          type: boolean
+        placeholder:
+          $ref: "#/components/schemas/TranslatableText"
+      additionalProperties: false
+    SurveyValidation:
+      type: object
+      description: Optional element-level validation rules.
+      required: [rules]
+      properties:
+        logic:
+          type: string
+          enum: [and, or]
+          default: and
+        rules:
+          type: array
+          items:
+            $ref: "#/components/schemas/SurveyValidationRule"
+      additionalProperties: false
+    SurveyValidationRule:
+      type: object
+      required: [id, type, params]
+      properties:
+        id:
+          type: string
+        type:
+          type: string
+          enum:
+            - minLength
+            - maxLength
+            - pattern
+            - email
+            - url
+            - phone
+            - equals
+            - doesNotEqual
+            - contains
+            - doesNotContain
+            - minValue
+            - maxValue
+            - isGreaterThan
+            - isLessThan
+            - minSelections
+            - maxSelections
+            - minRanked
+            - rankAll
+            - minRowsAnswered
+            - answerAllRows
+            - isLaterThan
+            - isEarlierThan
+            - isBetween
+            - isNotBetween
+            - fileExtensionIs
+            - fileExtensionIsNot
+        params:
+          type: object
+          additionalProperties: true
+        field:
+          type: string
+          enum:
+            [
+              addressLine1,
+              addressLine2,
+              city,
+              state,
+              zip,
+              country,
+              firstName,
+              lastName,
+              email,
+              phone,
+              company,
+            ]
+      additionalProperties: false
+    SurveyBlockLogic:
+      type: object
+      description: Conditional logic rule evaluated at block level.
+      required: [id, conditions, actions]
+      properties:
+        id:
+          type: string
+          format: cuid2
+        conditions:
+          $ref: "#/components/schemas/SurveyConditionGroup"
+        actions:
+          type: array
+          items:
+            $ref: "#/components/schemas/SurveyLogicAction"
+      additionalProperties: false
+    SurveyConditionGroup:
+      type: object
+      required: [id, connector, conditions]
+      properties:
+        id:
+          type: string
+          format: cuid2
+        connector:
+          type: string
+          enum: [and, or]
+        conditions:
+          type: array
+          items:
+            oneOf:
+              - $ref: "#/components/schemas/SurveyCondition"
+              - $ref: "#/components/schemas/SurveyConditionGroup"
+      additionalProperties: false
+    SurveyCondition:
+      type: object
+      description: |
+        Single condition. Operators such as `isSubmitted`, `isSkipped`, `isClicked`, `isAccepted`,
+        `isBooked`, `isSet`, and `isEmpty` do not use `rightOperand`; comparison operators do.
+      required: [id, leftOperand, operator]
+      properties:
+        id:
+          type: string
+          format: cuid2
+        leftOperand:
+          $ref: "#/components/schemas/SurveyDynamicReference"
+        operator:
+          type: string
+          enum:
+            - equals
+            - doesNotEqual
+            - contains
+            - doesNotContain
+            - startsWith
+            - doesNotStartWith
+            - endsWith
+            - doesNotEndWith
+            - isSubmitted
+            - isSkipped
+            - isGreaterThan
+            - isLessThan
+            - isGreaterThanOrEqual
+            - isLessThanOrEqual
+            - equalsOneOf
+            - includesAllOf
+            - includesOneOf
+            - doesNotIncludeOneOf
+            - doesNotIncludeAllOf
+            - isClicked
+            - isNotClicked
+            - isAccepted
+            - isBefore
+            - isAfter
+            - isBooked
+            - isPartiallySubmitted
+            - isCompletelySubmitted
+            - isSet
+            - isNotSet
+            - isEmpty
+            - isNotEmpty
+            - isAnyOf
+        rightOperand:
+          $ref: "#/components/schemas/SurveyLogicOperand"
+      additionalProperties: false
+    SurveyLogicOperand:
+      oneOf:
+        - type: object
+          required: [type, value]
+          properties:
+            type:
+              type: string
+              enum: [static]
+            value:
+              oneOf:
+                - type: string
+                - type: number
+                - type: array
+                  items:
+                    type: string
+          additionalProperties: false
+        - $ref: "#/components/schemas/SurveyDynamicReference"
+    SurveyDynamicReference:
+      type: object
+      description: Dynamic reference to another value in the survey document.
+      required: [type, value]
+      properties:
+        type:
+          type: string
+          enum: [element, variable, hiddenField]
+        value:
+          type: string
+          description: Element id, variable id, or hidden field id depending on `type`.
+        meta:
+          type: object
+          additionalProperties:
+            type: string
+      additionalProperties: false
+    SurveyLogicAction:
+      oneOf:
+        - $ref: "#/components/schemas/SurveyCalculateAction"
+        - $ref: "#/components/schemas/SurveyRequireAnswerAction"
+        - $ref: "#/components/schemas/SurveyJumpToBlockAction"
+      description: |
+        Logic action. Keep referenced ids stable: `calculate.variableId` points to a variable id,
+        `requireAnswer.target` points to an element id, and `jumpToBlock.target` points to a block id
+        or ending id.
+    SurveyCalculateAction:
+      type: object
+      description: Updates a survey variable when the logic rule matches.
+      required: [id, objective, variableId, operator, value]
+      properties:
+        id:
+          type: string
+          format: cuid2
+        objective:
+          type: string
+          enum: [calculate]
+        variableId:
+          type: string
+          format: cuid2
+          description: Variable id for `calculate`.
+        operator:
+          type: string
+          enum: [assign, concat, add, subtract, multiply, divide]
+        value:
+          $ref: "#/components/schemas/SurveyLogicOperand"
+      additionalProperties: false
+    SurveyRequireAnswerAction:
+      type: object
+      description: Requires an element/question to be answered before continuing.
+      required: [id, objective, target]
+      properties:
+        id:
+          type: string
+          format: cuid2
+        objective:
+          type: string
+          enum: [requireAnswer]
+        target:
+          type: string
+          description: Target element id.
+      additionalProperties: false
+    SurveyJumpToBlockAction:
+      type: object
+      description: Jumps to another block or ending when the logic rule matches.
+      required: [id, objective, target]
+      properties:
+        id:
+          type: string
+          format: cuid2
+        objective:
+          type: string
+          enum: [jumpToBlock]
+        target:
+          type: string
+          format: cuid2
+          description: Target block id or ending id.
+      additionalProperties: false
+    SurveyResource:
+      type: object
+      required:
+        - id
+        - workspaceId
+        - createdAt
+        - updatedAt
+        - name
+        - type
+        - status
+        - metadata
+        - defaultLanguage
+        - languages
+        - welcomeCard
+        - blocks
+        - endings
+        - hiddenFields
+        - variables
+      properties:
+        id: { type: string }
+        workspaceId: { type: string }
+        createdAt: { type: string, format: date-time }
+        updatedAt: { type: string, format: date-time }
+        name: { type: string }
+        type: { type: string, enum: [link, app, website, web] }
+        status:
+          type: string
+          enum: [draft, inProgress, paused, completed]
+        metadata:
+          type: object
+          nullable: true
+          additionalProperties: true
+        defaultLanguage:
+          type: string
+          description: Real locale code for the survey default language. The internal `default` translation key is never exposed.
+        languages:
+          type: array
+          items:
+            $ref: "#/components/schemas/SurveyLanguage"
+        welcomeCard:
+          $ref: "#/components/schemas/SurveyWelcomeCard"
+        blocks:
+          type: array
+          items:
+            $ref: "#/components/schemas/SurveyBlock"
+        endings:
+          type: array
+          items:
+            $ref: "#/components/schemas/SurveyEnding"
+        hiddenFields:
+          $ref: "#/components/schemas/SurveyHiddenFields"
+        variables:
+          type: array
+          items:
+            $ref: "#/components/schemas/SurveyVariable"
     Problem:
       type: object
       description: RFC 9457 Problem Details for HTTP APIs (`application/problem+json`). Responses typically include a machine-readable `code` field alongside `title`, `status`, `detail`, and `requestId`.