diff --git a/pkg/models/message.go b/pkg/models/message.go
index ef51cfc18..48ca786db 100644
--- a/pkg/models/message.go
+++ b/pkg/models/message.go
@@ -19,5 +19,5 @@ package models
 // Message is a standard message
 type Message struct {
 	// A standard message.
-	Message string `json:"message"`
+	Message string `json:"message" readOnly:"true" doc:"A human-readable status message returned by the server."`
 }
diff --git a/pkg/routes/api/v2/avatar_upload.go b/pkg/routes/api/v2/avatar_upload.go
new file mode 100644
index 000000000..d085a8c70
--- /dev/null
+++ b/pkg/routes/api/v2/avatar_upload.go
@@ -0,0 +1,130 @@
+// Vikunja is a to-do list application to facilitate your life.
+// Copyright 2018-present Vikunja and contributors. All rights reserved.
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+package apiv2
+
+import (
+	"context"
+	"io"
+	"net/http"
+	"strings"
+
+	"code.vikunja.io/api/pkg/config"
+	"code.vikunja.io/api/pkg/db"
+	"code.vikunja.io/api/pkg/models"
+	"code.vikunja.io/api/pkg/modules/avatar"
+	"code.vikunja.io/api/pkg/modules/avatar/upload"
+	"code.vikunja.io/api/pkg/user"
+
+	"github.com/danielgtaylor/huma/v2"
+	"github.com/gabriel-vasile/mimetype"
+)
+
+// avatarUploadInput is the multipart/form-data request for the avatar upload.
+// Huma's MultipartFormFiles renders the "avatar" field as a binary file in the
+// generated OpenAPI spec; the file bytes are read from in.RawBody.Data().Avatar.
+type avatarUploadInput struct {
+	// contentType is intentionally permissive: the real, byte-level image
+	// check is done in the handler via mimetype.DetectReader (the same
+	// allow-list v1 uses), not via the client-declared part Content-Type.
+	// "image/*" here would make Huma reject on the declared header before the
+	// handler runs and trust a value the client controls.
+	RawBody huma.MultipartFormFiles[struct {
+		Avatar huma.FormFile `form:"avatar" contentType:"application/octet-stream" required:"true" doc:"The avatar image to upload. Must be an image; it is resized server-side and re-encoded as PNG."`
+	}]
+}
+
+// avatarUploadBody wraps the success message returned after an upload.
+type avatarUploadBody struct {
+	Body *models.Message
+}
+
+// RegisterAvatarRoutes wires the authenticated user's avatar upload onto the Huma API.
+func RegisterAvatarRoutes(api huma.API) {
+	tags := []string{"user"}
+
+	Register(api, huma.Operation{
+		OperationID: "user-avatar-upload",
+		Summary:     "Upload your avatar",
+		Description: "Uploads an image as the authenticated user's avatar and switches their avatar provider to \"upload\". The image is validated to be an image, resized server-side, and stored as PNG. Replaces any previously uploaded avatar (idempotent replace, hence PUT).",
+		Method:      http.MethodPut,
+		Path:        "/user/settings/avatar",
+		Tags:        tags,
+		// Avatars can be larger than Huma's 1 MB default body limit; allow up to
+		// the configured max file size so legitimate uploads aren't rejected before
+		// the handler runs. Echo's global BodyLimit middleware still caps the total.
+		// #nosec G115 - configured value won't exceed int64 max in practice.
+		MaxBodyBytes:  int64(config.GetMaxFileSizeInMBytes()) * 1024 * 1024,
+		DefaultStatus: http.StatusOK,
+	}, avatarUpload)
+}
+
+func avatarUpload(ctx context.Context, in *avatarUploadInput) (*avatarUploadBody, error) {
+	a, err := authFromCtx(ctx)
+	if err != nil {
+		return nil, err
+	}
+
+	// Only real users have avatars; a link share cannot upload one.
+	authUser, is := a.(*user.User)
+	if !is {
+		return nil, huma.Error403Forbidden("only users can upload an avatar")
+	}
+
+	s := db.NewSession()
+	defer s.Close()
+
+	// Re-fetch the full user so AvatarFileID/Provider are current (the auth
+	// user from the JWT claims is partial).
+	u, err := user.GetUserByID(s, authUser.ID)
+	if err != nil {
+		_ = s.Rollback()
+		return nil, translateDomainError(err)
+	}
+
+	src := in.RawBody.Data().Avatar
+	defer func() { _ = src.Close() }()
+
+	// Validate we're dealing with an image (same allow-list as v1's UploadAvatar).
+	mime, err := mimetype.DetectReader(src)
+	if err != nil {
+		_ = s.Rollback()
+		return nil, translateDomainError(err)
+	}
+	if !strings.HasPrefix(mime.String(), "image") {
+		_ = s.Rollback()
+		return nil, huma.Error400BadRequest("Uploaded file is no image.")
+	}
+	if _, err := src.Seek(0, io.SeekStart); err != nil {
+		_ = s.Rollback()
+		return nil, translateDomainError(err)
+	}
+
+	u.AvatarProvider = "upload"
+	if err := upload.StoreAvatarFile(s, u, src); err != nil {
+		_ = s.Rollback()
+		return nil, translateDomainError(err)
+	}
+
+	if err := s.Commit(); err != nil {
+		_ = s.Rollback()
+		return nil, translateDomainError(err)
+	}
+
+	avatar.FlushAllCaches(u)
+
+	return &avatarUploadBody{Body: &models.Message{Message: "Avatar was uploaded successfully."}}, nil
+}
diff --git a/pkg/webtests/huma_avatar_upload_test.go b/pkg/webtests/huma_avatar_upload_test.go
new file mode 100644
index 000000000..232057539
--- /dev/null
+++ b/pkg/webtests/huma_avatar_upload_test.go
@@ -0,0 +1,156 @@
+// Vikunja is a to-do list application to facilitate your life.
+// Copyright 2018-present Vikunja and contributors. All rights reserved.
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+package webtests
+
+import (
+	"bytes"
+	"encoding/json"
+	"image"
+	"image/color"
+	"image/png"
+	"mime/multipart"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"code.vikunja.io/api/pkg/db"
+	"code.vikunja.io/api/pkg/user"
+
+	"github.com/labstack/echo/v5"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// avatarUploadPath is the v2 endpoint under test.
+const avatarUploadPath = "/api/v2/user/settings/avatar"
+
+// pngBytes builds a small valid PNG so StoreAvatarFile can decode + resize it.
+func pngBytes(t *testing.T) []byte {
+	t.Helper()
+	img := image.NewRGBA(image.Rect(0, 0, 8, 8))
+	for x := 0; x < 8; x++ {
+		for y := 0; y < 8; y++ {
+			img.Set(x, y, color.RGBA{R: uint8(x * 16), G: uint8(y * 16), B: 100, A: 255})
+		}
+	}
+	buf := &bytes.Buffer{}
+	require.NoError(t, png.Encode(buf, img))
+	return buf.Bytes()
+}
+
+// multipartAvatarBody returns a multipart/form-data body with a single
+// "avatar" file field plus the matching Content-Type header (with boundary).
+func multipartAvatarBody(t *testing.T, fieldName, filename string, content []byte) (*bytes.Buffer, string) {
+	t.Helper()
+	buf := &bytes.Buffer{}
+	w := multipart.NewWriter(buf)
+	fw, err := w.CreateFormFile(fieldName, filename)
+	require.NoError(t, err)
+	_, err = fw.Write(content)
+	require.NoError(t, err)
+	require.NoError(t, w.Close())
+	return buf, w.FormDataContentType()
+}
+
+// uploadAvatarRequest dispatches a multipart avatar upload against a prepared echo.Echo.
+func uploadAvatarRequest(t *testing.T, e *echo.Echo, body *bytes.Buffer, contentType, token string) *httptest.ResponseRecorder {
+	t.Helper()
+	req := httptest.NewRequest(http.MethodPut, avatarUploadPath, body)
+	req.Header.Set("Content-Type", contentType)
+	if token != "" {
+		req.Header.Set("Authorization", "Bearer "+token)
+	}
+	rec := httptest.NewRecorder()
+	e.ServeHTTP(rec, req)
+	return rec
+}
+
+func TestAvatarUpload(t *testing.T) {
+	t.Run("Normal", func(t *testing.T) {
+		e, err := setupTestEnv()
+		require.NoError(t, err)
+		token := humaTokenFor(t, &testuser1)
+
+		body, contentType := multipartAvatarBody(t, "avatar", "avatar.png", pngBytes(t))
+		rec := uploadAvatarRequest(t, e, body, contentType, token)
+		require.Equal(t, http.StatusOK, rec.Code, "body: %s", rec.Body.String())
+		assert.Contains(t, rec.Body.String(), "uploaded successfully")
+
+		// The provider must be flipped to "upload" and an avatar file stored.
+		s := db.NewSession()
+		defer s.Close()
+		u, err := user.GetUserByID(s, testuser1.ID)
+		require.NoError(t, err)
+		assert.Equal(t, "upload", u.AvatarProvider)
+		assert.NotZero(t, u.AvatarFileID)
+	})
+
+	t.Run("Non-image rejected", func(t *testing.T) {
+		e, err := setupTestEnv()
+		require.NoError(t, err)
+		token := humaTokenFor(t, &testuser1)
+
+		body, contentType := multipartAvatarBody(t, "avatar", "not-an-image.txt", []byte("this is plain text, not an image"))
+		rec := uploadAvatarRequest(t, e, body, contentType, token)
+		require.Equal(t, http.StatusBadRequest, rec.Code, "body: %s", rec.Body.String())
+
+		// The provider must NOT have been changed.
+		s := db.NewSession()
+		defer s.Close()
+		u, err := user.GetUserByID(s, testuser1.ID)
+		require.NoError(t, err)
+		assert.NotEqual(t, "upload", u.AvatarProvider)
+	})
+
+	t.Run("Unauthenticated", func(t *testing.T) {
+		e, err := setupTestEnv()
+		require.NoError(t, err)
+
+		body, contentType := multipartAvatarBody(t, "avatar", "avatar.png", pngBytes(t))
+		rec := uploadAvatarRequest(t, e, body, contentType, "")
+		require.Equal(t, http.StatusUnauthorized, rec.Code, "body: %s", rec.Body.String())
+	})
+
+	t.Run("Renders as multipart in the OpenAPI spec", func(t *testing.T) {
+		e, err := setupTestEnv()
+		require.NoError(t, err)
+
+		req := httptest.NewRequest(http.MethodGet, "/api/v2/openapi.json", nil)
+		rec := httptest.NewRecorder()
+		e.ServeHTTP(rec, req)
+		require.Equal(t, http.StatusOK, rec.Code)
+
+		// Navigate the spec loosely: Huma can emit `type` as either a string
+		// or an array, so avoid binding it to a concrete Go type.
+		var spec map[string]any
+		require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &spec))
+
+		paths, _ := spec["paths"].(map[string]any)
+		op, _ := paths["/user/settings/avatar"].(map[string]any)
+		put, ok := op["put"].(map[string]any)
+		require.True(t, ok, "PUT /user/settings/avatar must be in the spec")
+		content, _ := put["requestBody"].(map[string]any)
+		contentMap, _ := content["content"].(map[string]any)
+		mp, ok := contentMap["multipart/form-data"].(map[string]any)
+		require.True(t, ok, "avatar upload must be modeled as multipart/form-data")
+		schema, _ := mp["schema"].(map[string]any)
+		props, _ := schema["properties"].(map[string]any)
+		avatarProp, ok := props["avatar"].(map[string]any)
+		require.True(t, ok, "the avatar field must appear in the multipart schema")
+		assert.Equal(t, "binary", avatarProp["format"], "avatar field must be a binary file in the spec")
+	})
+}