> ## 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` |

<Info>
  Current client SDKs retrieve pinned posts. Pinning and unpinning are not exposed as public client SDK operations in this surface.
</Info>

## 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.

<CodeGroup>
  ```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();
  ```
</CodeGroup>

## Global Pinned Posts

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

<CodeGroup>
  ```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();
  ```
</CodeGroup>

## 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

<CardGroup cols={3}>
  <Card title="Query Posts" icon="filter" href="../retrieval/query-posts">
    Query regular feed posts.
  </Card>

  <Card title="Viewing Content" icon="eye" href="../retrieval/viewing-content">
    Render the pinned post object.
  </Card>

  <Card title="Post Review" icon="shield-check" href="./post-review">
    Approve or decline posts.
  </Card>
</CardGroup>


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