---
type: api
title: Uploads Endpoints
description: Admin-only multipart upload endpoints for site logos, category icons, and challenge files.
tags: [api, uploads, multipart, admin]
timestamp: 2026-07-22T13:05:30Z
---

# Endpoints

| Method | Path                                  | Auth  | Source                                                  |
|--------|---------------------------------------|-------|---------------------------------------------------------|
| `POST` | `/api/v1/uploads/logo`                | Admin | `backend/src/modules/uploads/uploads.controller.ts`     |
| `POST` | `/api/v1/uploads/category-icon`       | Admin | Same.                                                   |
| `POST` | `/api/v1/uploads/challenge-file`      | Admin | Same.                                                   |

# Guard chain

All handlers are gated by the controller-level `AdminGuard` and `admin` role.
The global authentication and CSRF protections also apply; clients must send a
valid admin session and the standard CSRF cookie/header pair.

# Behavior

* Each endpoint uses `FileInterceptor('file')` and parses a single multipart
  part named `file`.
* File size is validated against `UPLOAD_SIZE_LIMIT` through
  `parseUploadSizeLimit()` in `backend/src/common/utils/upload.ts`.
* Category icons are written under `UPLOAD_DIR/icons`; when `categoryId` is
  supplied, the image is cropped to a 128-by-128 PNG and exposed at
  `/uploads/icons/{categoryId}.png`.
* Challenge attachments are written under `UPLOAD_DIR/challenges` and exposed
  at `/uploads/challenges/{safeFilename}`.
* Site logos are decoded with Sharp and accepted only when their actual format
  is PNG, JPEG, GIF, or WebP. The multipart MIME type and filename extension
  are not trusted for validation.
* An accepted logo keeps its sanitized filename, is written directly under
  `UPLOAD_DIR`, and returns `{ publicUrl, originalFilename }`, with `publicUrl`
  in the form `/uploads/{safeFilename}`.
* A missing `file` part, an oversized upload, a corrupt image, or a decoded logo
  in another format returns `400 Bad Request`. Invalid logo payloads use the
  message `Logo must be a valid PNG, JPEG, GIF, or WebP image.` and are not
  persisted.

# Examples

1. Sign in as an administrator and navigate to `/admin/general`.
2. In the site-logo setting, choose a PNG, JPEG, GIF, or WebP image and save the
   general settings.
3. The client uploads the selected file to `POST /api/v1/uploads/logo` before
   saving the returned `/uploads/...` URL as the configured logo.
4. After a successful save, the uploaded image is available from its returned
   public URL and is used wherever the configured site logo is rendered.
5. Choosing a corrupt file, or a valid image in an unsupported format, leaves
   the file unstored and surfaces the upload validation failure to the user.

# Key files

| File | Responsibility |
|---|---|
| `backend/src/modules/uploads/uploads.controller.ts` | Registers upload routes, validates payloads, and persists files. |
| `backend/src/common/utils/upload.ts` | Parses size limits and sanitizes upload filenames. |
| `frontend/src/app/features/admin/general/admin-general.component.ts` | Provides the administrator-facing logo selection and settings workflow. |
| `tests/backend/uploads-logo.spec.ts` | Verifies accepted logo formats, spoofed/corrupt payload rejection, size limits, and persisted responses. |

# See also

- [Admin — General Settings](/guides/admin-general-settings.md)
- [REST API Overview](/api/rest-overview.md)
- [Backend Module Map](/architecture/backend-modules.md)