> ## Documentation Index
> Fetch the complete documentation index at: https://social-b97141fb-feat-user-history-moderation-detail.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Pinned Posts

> Read community and global pinned posts through the public SDK live collection APIs.

Use pinned-post queries to display posts that were already pinned outside the client SDK. The SDK surfaces in this page are read-only retrieval APIs.

## Platform Support

| Platform | Community pinned posts | Global pinned posts | Placement values |
| - | - | - | - |
| TypeScript | `PostRepository.getPinnedPosts(...)` | `PostRepository.getGlobalPinnedPosts(...)` | String placement such as `default` or `announcement`; `null` fetches all community placements |
| iOS | `postRepository.getPinnedPosts(...)` | `postRepository.getGlobalPinnedPosts(...)` | `AmityPinPlacement.default.rawValue` or `AmityPinPlacement.announcement.rawValue` |
| Android | `postRepository.getPinnedPosts(...)` | `postRepository.getGlobalPinnedPosts(...)` | `AmityPinnedPost.PinPlacement.DEFAULT.value` or `ANNOUNCEMENT.value` |
| Flutter | `AmitySocialClient.newPostRepository().getPinnedPosts(...)` | `getGlobalPinnedPosts()` | String placement, or `PinPlacement.DEFAULT.value` / `ANNOUNCEMENT.value` |

> [!NOTE]
>
> Current client SDKs retrieve pinned posts. Pinning and unpinning are not exposed as public client SDK operations in this surface.

## Parameters

| Operation | Parameter | Required | Platforms | Description |
| - | - | - | - | - |
| Community pinned posts | `communityId` | Yes | All | Community whose pinned posts should be retrieved. |
| Community pinned posts | `placement` | No | All | Placement such as default or announcement. |
| Community pinned posts | `sortBy` | No | TypeScript, iOS | Sort order. Not accepted by the current Android call. Flutter exposes `sortByOptions`, but the request builder does not forward it — do not depend on it. |
| Community pinned posts | `includeMixedStructure` | No | TypeScript, iOS, Android | Include mixed-structure posts. Not exposed on the current Flutter public method. |
| Global pinned posts | `includeMixedStructure` | No | TypeScript, iOS, Android | Include mixed-structure posts in global pinned results. Not exposed on the current Flutter public method. |

## Community Pinned Posts

Query community pinned posts for a specific community and optional placement such as an announcement area.

```typescript TypeScript theme={null}
import { PostRepository } from "@amityco/ts-sdk";

const unsubscribe = PostRepository.getPinnedPosts(
  {
    communityId,
    placement: "announcement",
    sortBy: "lastPinned",
    includeMixedStructure: true,
  },
  ({ data: pinnedPosts, loading, error, onNextPage, hasNextPage }) => {
    if (loading) return;
    if (error) {
      handleError(error);
      return;
    }

    renderResults(pinnedPosts);

    if (hasNextPage) {
      onNextPage?.();
    }
  },
);
```

```swift iOS theme={null}
token = postRepository
    .getPinnedPosts(
        communityId: communityId,
        placement: AmityPinPlacement.announcement.rawValue,
        sortBy: .lastPinned,
        includeMixedStructure: true
    )
    .observe { collection, error in
        showSuccessMessage(collection.snapshots.count)
    }
```

```kotlin Android theme={null}
postRepository.getPinnedPosts(
    communityId = communityId,
    placement = AmityPinnedPost.PinPlacement.ANNOUNCEMENT.value,
    includeMixedStructure = true
)
    .subscribe(
        { pagingData -> showSuccessMessage(pagingData) },
        { error -> handleGeneralError(error) }
    )
```

```dart Flutter theme={null}
final pinnedPosts = AmitySocialClient.newPostRepository().getPinnedPosts(
  communityId: communityId,
  placement: 'announcement',
);

pinnedPosts.getStreamController().stream.listen((items) {
  final count = items.length;
});

await pinnedPosts.loadNext();
```

## Global Pinned Posts

Query global pinned posts when the product needs an app-wide featured-content surface.

```typescript TypeScript theme={null}
import { PostRepository } from "@amityco/ts-sdk";

const unsubscribe = PostRepository.getGlobalPinnedPosts(
  {
    includeMixedStructure: true,
  },
  ({ data: pinnedPosts, loading, error }) => {
    if (loading) return;
    if (error) {
      handleError(error);
      return;
    }

    renderResults(pinnedPosts);
  },
);
```

```swift iOS theme={null}
token = postRepository
    .getGlobalPinnedPosts(includeMixedStructure: true)
    .observe { collection, error in
        showSuccessMessage(collection.snapshots.count)
    }
```

```kotlin Android theme={null}
postRepository.getGlobalPinnedPosts(includeMixedStructure = true)
    .subscribe(
        { pinnedPosts -> showSuccessMessage(pinnedPosts.size) },
        { error -> handleGeneralError(error) }
    )
```

```dart Flutter theme={null}
final globalPinnedPosts =
    AmitySocialClient.newPostRepository().getGlobalPinnedPosts();

globalPinnedPosts.getStreamController().stream.listen((items) {
  final count = items.length;
});

await globalPinnedPosts.loadNext();
```

## Notes

* Use community pinned posts for a single community feed or announcement area.
* Use global pinned posts for app-wide featured content.
* TypeScript, iOS, and Android expose `includeMixedStructure`; the current Flutter public pinned-post methods do not expose that option.
* Flutter exposes a `sortByOptions` parameter on `getPinnedPosts`, but the current public request builder does not pass it into the request. Do not depend on custom sorting there.

## Pin / Feature Controls

Pinning, unpinning, featuring, and unfeaturing are performed from the **social.plus Console**, not from the client SDK. The client SDKs surface pinned and featured state as read-only.

* **Event posts** in the UIKit follow the same rule and go a step further — the pinned / featured badge renders but there is no in-app pin control in any role, including hosts and moderators. See [Event Posts](../creation/event-post) and the [Event UIKit doc](/uikit/components/social/event) for how the badge renders.
* **User-feed posts** can never be pinned regardless of role or Console state.
* **Global featuring** requires a public community — a post in a private community cannot be featured globally.

## Related Topics

> **[Query Posts](../retrieval/query-posts)**
>
> Query regular feed posts.

> **[Viewing Content](../retrieval/viewing-content)**
>
> Render the pinned post object.

> **[Post Review](./post-review)**
>
> Approve or decline posts.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.