# Uploads

Endpoints for uploading, retrieving, and managing media files. The upload flow is two-step: first create an upload via POST to get an upload URL, then PUT the actual file content to that URL. Most endpoints require authentication. Class-level @RBACAuthorize requires authentication by default; public endpoints use @PermitAll.

## Create a new upload entry

 - [POST /api/v1/uploads](https://docs.wellesley.social/openapi/uploads/paths/~1api~1v1~1uploads/post.md): Creates a new upload record and returns an upload URL where the file content should be PUT. This is the first step of the two-step upload flow. Requires authentication.

## List uploads attached to an entity

 - [GET /api/v1/uploads/attached/{entityId}](https://docs.wellesley.social/openapi/uploads/paths/~1api~1v1~1uploads~1attached~1%7Bentityid%7D/get.md): Returns all uploads attached to the specified entity (post, event, etc.). Requires authentication.

## Batch delete multiple uploads

 - [POST /api/v1/uploads/batch](https://docs.wellesley.social/openapi/uploads/paths/~1api~1v1~1uploads~1batch/post.md): Deletes multiple uploads at once. All uploads must belong to the authenticated user and the batch size must be between 1 and 20. Requires authentication.

## List uploads by tags

 - [POST /api/v1/uploads/list](https://docs.wellesley.social/openapi/uploads/paths/~1api~1v1~1uploads~1list/post.md): Returns uploads matching the specified tag criteria from the request body. Only the authenticated user's uploads are returned. Requires authentication.

## List all uploads by owner

 - [GET /api/v1/uploads/owner/{ownerId}](https://docs.wellesley.social/openapi/uploads/paths/~1api~1v1~1uploads~1owner~1%7Bownerid%7D/get.md): Returns all uploads (standalone and attached) owned by the specified entity. Requires authentication.

## List standalone uploads by owner

 - [GET /api/v1/uploads/owner/{ownerId}/standalone](https://docs.wellesley.social/openapi/uploads/paths/~1api~1v1~1uploads~1owner~1%7Bownerid%7D~1standalone/get.md): Returns uploads owned by the specified entity that are not attached to any entity. Requires authentication.

## Search uploads

 - [GET /api/v1/uploads/search](https://docs.wellesley.social/openapi/uploads/paths/~1api~1v1~1uploads~1search/get.md): Searches the authenticated user's uploads with optional filtering by upload type (image, video, etc.) and tag (Post, Avatar, Header, etc.). Returns paginated results. Requires authentication.

## Find usages of uploads

 - [GET /api/v1/uploads/usages](https://docs.wellesley.social/openapi/uploads/paths/~1api~1v1~1uploads~1usages/get.md): Returns where the specified uploads are used, including posts, avatars, and headers. Accepts a comma-separated list of upload IDs. Requires authentication.

## Get upload by ID

 - [GET /api/v1/uploads/{id}](https://docs.wellesley.social/openapi/uploads/paths/~1api~1v1~1uploads~1%7Bid%7D/get.md): Retrieves upload metadata and file information for a specific upload. Only the upload owner can access their uploads. Requires authentication.

## Delete upload by ID

 - [DELETE /api/v1/uploads/{id}](https://docs.wellesley.social/openapi/uploads/paths/~1api~1v1~1uploads~1%7Bid%7D/delete.md): Permanently deletes an upload and its associated files. Only the upload owner can delete their uploads. Requires authentication.

## Replace upload metadata

 - [POST /api/v1/uploads/{id}/meta](https://docs.wellesley.social/openapi/uploads/paths/~1api~1v1~1uploads~1%7Bid%7D~1meta/post.md): Completely replaces the upload's metadata with the provided data, removing any existing metadata not included in the request. Only the upload owner can modify metadata. Requires authentication.

## Partially update upload metadata

 - [PUT /api/v1/uploads/{id}/meta](https://docs.wellesley.social/openapi/uploads/paths/~1api~1v1~1uploads~1%7Bid%7D~1meta/put.md): Merges the provided metadata fields into the upload's existing metadata, preserving fields not included in the request. Only the upload owner can modify metadata. Requires authentication.

## Update upload privacy settings

 - [POST /api/v1/uploads/{id}/privacy](https://docs.wellesley.social/openapi/uploads/paths/~1api~1v1~1uploads~1%7Bid%7D~1privacy/post.md): Sets the privacy level and allowed users for an upload. This replaces the existing privacy settings entirely. Only the upload owner can modify privacy. Requires authentication.

## Replace upload tags

 - [POST /api/v1/uploads/{id}/tags](https://docs.wellesley.social/openapi/uploads/paths/~1api~1v1~1uploads~1%7Bid%7D~1tags/post.md): Completely replaces the upload's tags with the provided set, removing any existing tags not in the request. Tags categorize uploads (e.g., Post, Avatar, Header, Emoji). Only the upload owner can modify tags. Requires authentication.

## Add tags to upload

 - [PUT /api/v1/uploads/{id}/tags](https://docs.wellesley.social/openapi/uploads/paths/~1api~1v1~1uploads~1%7Bid%7D~1tags/put.md): Adds the provided tags to the upload's existing tag set without removing any existing tags. Only the upload owner can modify tags. Requires authentication.

## Change video thumbnail

 - [POST /api/v1/uploads/{id}/thumbnail](https://docs.wellesley.social/openapi/uploads/paths/~1api~1v1~1uploads~1%7Bid%7D~1thumbnail/post.md): Updates the thumbnail/preview image for a video upload by extracting a frame at the specified timestamp (in seconds). Only applicable to video uploads. Only the upload owner can change thumbnails. Requires authentication.

## Update standalone upload owner

 - [PUT /api/v1/uploads/{uploadId}/owner](https://docs.wellesley.social/openapi/uploads/paths/~1api~1v1~1uploads~1%7Buploadid%7D~1owner/put.md): Change the owner of a standalone upload. Only works for uploads not yet attached to any entity. Requires authentication.