# Tags

Endpoints for managing hashtags, including following, featuring, and retrieving tag information

## Get list of featured tags

 - [GET /api/v1/tags/featured](https://docs.wellesley.social/openapi/tags/paths/~1api~1v1~1tags~1featured/get.md): Returns the featured (pinned) tags for the authenticated user or a specified user. For remote users, featured tags may be refreshed from their origin server if stale. Tags blocked by scope policy are filtered out. Requires authentication.

## Remove from featured tags by name

 - [DELETE /api/v1/tags/featured/{name}](https://docs.wellesley.social/openapi/tags/paths/~1api~1v1~1tags~1featured~1%7Bname%7D/delete.md): Removes a tag from the authenticated user's featured (pinned) tags and notifies followers via ActivityPub. Requires authentication.

## Feature tag by name

 - [POST /api/v1/tags/featured/{name}](https://docs.wellesley.social/openapi/tags/paths/~1api~1v1~1tags~1featured~1%7Bname%7D/post.md): Adds a tag to the authenticated user's featured (pinned) tags and notifies followers via ActivityPub. Tags blocked by scope policy cannot be featured. Requires authentication.

## Follow tag by name

 - [POST /api/v1/tags/follow/{name}](https://docs.wellesley.social/openapi/tags/paths/~1api~1v1~1tags~1follow~1%7Bname%7D/post.md): Subscribes the authenticated user to a tag within the specified scope, so posts with this tag appear in their feed. Tags blocked by scope policy cannot be followed. Requires authentication.

## Get list of followed tags

 - [GET /api/v1/tags/followed](https://docs.wellesley.social/openapi/tags/paths/~1api~1v1~1tags~1followed/get.md): Returns all tags the authenticated user is following within the specified scope. Tags blocked by scope policy are filtered out. Requires authentication.

## Overwrite black/whitelist

 - [PUT /api/v1/tags/list](https://docs.wellesley.social/openapi/tags/paths/~1api~1v1~1tags~1list/put.md): Bulk overwrite list entries for a scope

RBAC:
- requires ANY of Data.Manage, GroupData.Manage

## Add to black/whitelist

 - [PATCH /api/v1/tags/list](https://docs.wellesley.social/openapi/tags/paths/~1api~1v1~1tags~1list/patch.md): Add entries. For blacklist, soft flag toggles hard/soft.

RBAC:
- requires ANY of Data.Manage, GroupData.Manage

## Get black/whitelist for a scope

 - [GET /api/v1/tags/list](https://docs.wellesley.social/openapi/tags/paths/~1api~1v1~1tags~1list/get.md): Returns array of tag names in black/whitelist. 'soft' applies only to blacklist.

RBAC:
- requires ANY of Data.Read, GroupData.Manage

## Remove from black/whitelist

 - [DELETE /api/v1/tags/list](https://docs.wellesley.social/openapi/tags/paths/~1api~1v1~1tags~1list/delete.md): Remove entries. For blacklist, soft must be specified to remove from that list.

RBAC:
- requires ANY of Data.Manage, GroupData.Manage

## Set policy mode

 - [PUT /api/v1/tags/policy](https://docs.wellesley.social/openapi/tags/paths/~1api~1v1~1tags~1policy/put.md): Set scope policy to 'whitelist' or 'blacklist'.

RBAC:
- requires ANY of Data.Manage, GroupData.Manage

## Get policy mode

 - [GET /api/v1/tags/policy](https://docs.wellesley.social/openapi/tags/paths/~1api~1v1~1tags~1policy/get.md): Returns 'whitelist' or 'blacklist' for scope. Defaults to 'blacklist' if unset.

RBAC:
- requires ANY of Data.Read, GroupData.Manage

## Report a tag

 - [POST /api/v1/tags/report](https://docs.wellesley.social/openapi/tags/paths/~1api~1v1~1tags~1report/post.md): Creates a tag report in a scope. The tag name is normalized before storing. Requires authentication.

## List tag reports in a scope

 - [GET /api/v1/tags/reports](https://docs.wellesley.social/openapi/tags/paths/~1api~1v1~1tags~1reports/get.md): Returns all tag reports for the given scope. Requires Data.Read or GroupData.Manage permission.

RBAC:
- requires ANY of Data.Read, GroupData.Manage

## Search tags by prefix

 - [GET /api/v1/tags/search](https://docs.wellesley.social/openapi/tags/paths/~1api~1v1~1tags~1search/get.md): Returns tag names matching partial name. Scope is optional.

## Get trending tags for a scope

 - [GET /api/v1/tags/trending](https://docs.wellesley.social/openapi/tags/paths/~1api~1v1~1tags~1trending/get.md): Returns trending tags within the specified scope with optional sorting and pagination. Tags blocked by scope policy are filtered out. No authentication required.

## Unfollow tag by name

 - [POST /api/v1/tags/unfollow/{name}](https://docs.wellesley.social/openapi/tags/paths/~1api~1v1~1tags~1unfollow~1%7Bname%7D/post.md): Unsubscribes the authenticated user from a tag within the specified scope. Requires authentication.

## Get tag by name

 - [GET /api/v1/tags/{name}](https://docs.wellesley.social/openapi/tags/paths/~1api~1v1~1tags~1%7Bname%7D/get.md): Retrieves tag details including usage history. Tags blocked by scope policy (blacklist/whitelist) are not returned. No authentication required.