# Users

User profile management endpoints. Handles user creation, retrieval by ID or username, profile updates, deletion, and social graph queries (followers/following). Supports both authenticated and guest access with varying levels of detail. Guest users receive basic profile data; authenticated users can access relationship statuses and full profiles.

## Delete user

 - [DELETE /api/v1/users](https://docs.wellesley.social/openapi/users/paths/~1api~1v1~1users/delete.md): Deletes a user profile by ID. Requires authentication. Only users belonging to the authenticated account can be deleted. The deletion is audited.

## Create new user for the account

 - [POST /api/v1/users](https://docs.wellesley.social/openapi/users/paths/~1api~1v1~1users/post.md): Creates a new user profile under the authenticated account. Requires authentication. Required fields: username, displayName, applicationId. Reserved usernames and duplicates are rejected. Only admins can create admin users. Bot/Service actor types cannot be assigned during creation.

## Get user by username

 - [GET /api/v1/users](https://docs.wellesley.social/openapi/users/paths/~1api~1v1~1users/get.md): Retrieves a user profile by username. Supports both local usernames and federated usernames (user@domain format). Accessible to both authenticated and guest users. If the username was recently changed, returns a 302 redirect to the new username. Use the 'full' parameter to include extended profile data. Authenticated users can request relationship statuses.

## Get current user profile

 - [GET /api/v1/users/profile](https://docs.wellesley.social/openapi/users/paths/~1api~1v1~1users~1profile/get.md): Returns the full profile of the currently authenticated user, including summary, stats, fields, avatar, header, and all extended profile data. Requires authentication.

## Get list of username changes

 - [GET /api/v1/users/rename-history](https://docs.wellesley.social/openapi/users/paths/~1api~1v1~1users~1rename-history/get.md): Returns the username change history for the currently authenticated user, along with the maximum number of renames allowed. Requires authentication.

## Update user's profile

 - [PUT /api/v1/users/{userId}](https://docs.wellesley.social/openapi/users/paths/~1api~1v1~1users~1%7Buserid%7D/put.md): Updates the profile of the specified user. Requires authentication and the user must belong to the authenticated account. Updatable fields include: displayName, username, summary, avatarId, headerId, timezone, location, birthday, and channel settings. Username changes are audited and subject to a maximum rename limit. Cannot convert a regular user to a bot/Service actor type.

## Get user by userId

 - [GET /api/v1/users/{userId}](https://docs.wellesley.social/openapi/users/paths/~1api~1v1~1users~1%7Buserid%7D/get.md): Retrieves a user profile by their unique user ID. Accessible to both authenticated and guest users. Use 'full' parameter to include extended profile data (summary, stats, header, fields). Authenticated users can request relationship statuses (following, blocked, muted) between themselves and the target user. Returns 302 redirect if the user has been renamed.

## Trigger deep sync for a remote user

 - [POST /api/v1/users/{userId}/deep-sync](https://docs.wellesley.social/openapi/users/paths/~1api~1v1~1users~1%7Buserid%7D~1deep-sync/post.md): Triggers a deep sync of a remote user's outbox. Fetches all posts paginated from the user's outbox and saves them locally. Only works for remote users that the caller follows. Returns the current sync state.

## Users which follow the given account

 - [GET /api/v1/users/{userId}/followers](https://docs.wellesley.social/openapi/users/paths/~1api~1v1~1users~1%7Buserid%7D~1followers/get.md): Returns a paginated list of users who follow the specified user. Accessible to both authenticated and guest users. The list may be hidden if the user's privacy settings disable follower visibility, or if the viewer is blocked by the target user. The owner of the profile can always see their own followers. Supports search filtering by username, display name, or domain.

## Users which the given account follows

 - [GET /api/v1/users/{userId}/following](https://docs.wellesley.social/openapi/users/paths/~1api~1v1~1users~1%7Buserid%7D~1following/get.md): Returns a paginated list of users that the specified user follows. Accessible to both authenticated and guest users. The list may be hidden if the user's privacy settings disable follower visibility, or if the viewer is blocked by the target user. The owner of the profile can always see their own following list. Supports search filtering by username, display name, or domain.

## Update user avatar and header

 - [PUT /api/v1/users/{userId}/media](https://docs.wellesley.social/openapi/users/paths/~1api~1v1~1users~1%7Buserid%7D~1media/put.md): Updates the avatar and/or header images for the specified user. Requires authentication and the user must belong to the authenticated account. Pass upload IDs for the new avatar or header.