Upload Form Template Background Image (v1)

Method & Path

POST /api/v1/workspace/:workspaceId/forms/templates/:templateId/background-image

Actual path: /v1/workspace/:workspaceId/forms/templates/:templateId/background-image

Description

Upload an image to use as the background of the public form page for this template. The image is processed (resized, converted to WebP) and stored; the template's backgroundImageUrl is set and backgroundColor is cleared. Maximum file size 10 MB.

Authentication

Required: Workspace or Staff token.

Path Parameters

Parameter	Type	Required	Description
workspaceId	string	Yes	Workspace ID
templateId	string	Yes	Form template ID

Request Body

Content-Type: multipart/form-data

Field	Type	Required	Description
file	file	Yes	Image file (JPEG, PNG, WebP, GIF)

Response 201 Created

Returns the updated form template (same shape as GET template), including backgroundImageUrl and backgroundColor: null.

{
  "id": "...",
  "workspaceId": "...",
  "name": "استمارة رضا",
  "description": "...",
  "status": "active",
  "questions": [...],
  "aiPrompt": null,
  "backgroundImageUrl": "https://storage.googleapis.com/...",
  "backgroundColor": null,
  "createdAt": "...",
  "updatedAt": "..."
}

Common Errors

• 400: Bad request (e.g. missing file)
• 401: Unauthorized
• 404: Form template not found
• 422: Validation failed (file too large, invalid image type)
• 500: Server error