# Lists

User list management for organizing and grouping followed accounts. Lists allow users to curate collections of accounts for easier content consumption. Lists can be public or private. Only the list owner can modify their lists. All endpoints require authentication.

## Get authenticated user's lists

 - [GET /api/v1/lists](https://docs.wellesley.social/openapi/lists/paths/~1api~1v1~1lists/get.md): Returns all lists created by the authenticated user for organizing followed accounts.

## Create a new list

 - [POST /api/v1/lists](https://docs.wellesley.social/openapi/lists/paths/~1api~1v1~1lists/post.md): Creates a new list for organizing followed accounts. Lists can be public or private.

## Update list properties

 - [PUT /api/v1/lists/{listId}](https://docs.wellesley.social/openapi/lists/paths/~1api~1v1~1lists~1%7Blistid%7D/put.md): Updates the name, privacy setting, or other properties of an existing list. Only the list owner can update it.

## Get list details by ID

 - [GET /api/v1/lists/{listId}](https://docs.wellesley.social/openapi/lists/paths/~1api~1v1~1lists~1%7Blistid%7D/get.md): Retrieves details of a specific list including its name, privacy setting, and metadata. Private lists can only be accessed by their owner.

## Delete a list

 - [DELETE /api/v1/lists/{listId}](https://docs.wellesley.social/openapi/lists/paths/~1api~1v1~1lists~1%7Blistid%7D/delete.md): Permanently deletes a list and removes all user associations. Only the list owner can delete it.

## Get users in a list

 - [GET /api/v1/lists/{listId}/users](https://docs.wellesley.social/openapi/lists/paths/~1api~1v1~1lists~1%7Blistid%7D~1users/get.md): Returns all users that have been added to a specific list. Private lists can only be accessed by their owner.

## Remove user from list

 - [DELETE /api/v1/lists/{listId}/users/{userId}](https://docs.wellesley.social/openapi/lists/paths/~1api~1v1~1lists~1%7Blistid%7D~1users~1%7Buserid%7D/delete.md): Removes a user from a list. Only the list owner can remove users.

## Add user to list

 - [POST /api/v1/lists/{listId}/users/{userId}](https://docs.wellesley.social/openapi/lists/paths/~1api~1v1~1lists~1%7Blistid%7D~1users~1%7Buserid%7D/post.md): Adds a user to a list for organization and filtering purposes. Only followed users can be added to lists. Only the list owner can add users.