# Pins

Endpoints for managing `Pins` (top-level posts) and `Highlights` (pinned replies). Top-level pins are shown first in the profile scope and are limited by admin setting `Maximum number of pinned posts`. Replies can be pinned as highlights under their root post. Pin and unpin actions are federated via ActivityPub.

## List pins and highlights

 - [GET /api/v1/posts/pins](https://docs.wellesley.social/openapi/pins/paths/~1api~1v1~1posts~1pins/get.md): Returns pinned post IDs ordered by pin time (newest first). By default returns only top-level Pins (postOnly=true). Set postOnly=false to include reply Highlights as well. When ownerId is provided, returns pins for that scope owner after access checks.

## Unpin post or remove highlight

 - [DELETE /api/v1/posts/pins/{postId}](https://docs.wellesley.social/openapi/pins/paths/~1api~1v1~1posts~1pins~1%7Bpostid%7D/delete.md): Removes a previously pinned post. For root posts, removes a top-level Pin; for replies, removes a Highlight. In personal scope, only the root post author can manage pins/highlights; in groups, owner/admin roles can manage them. The action is federated via ActivityPub Remove.

## Pin post or highlight reply

 - [POST /api/v1/posts/pins/{postId}](https://docs.wellesley.social/openapi/pins/paths/~1api~1v1~1posts~1pins~1%7Bpostid%7D/post.md): Pins the specified post. For a root post, this creates a top-level Pin in the profile/scope. For a reply, this creates a Highlight under the root post. In personal scope, only the root post author can manage pins/highlights; in groups, owner/admin roles can manage them. Reposts and direct posts cannot be pinned. Top-level pin count is limited by admin settings (Maximum number of pinned posts). The action is federated via ActivityPub Add.