> ## Documentation Index
> Fetch the complete documentation index at: https://learn.social.plus/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 | Description                                                             |
| ---------------------- | ----------------------- | -------- | ----------------------------------------------------------------------- |
| Community pinned posts | `communityId`           | Yes      | Community whose pinned posts should be retrieved.                       |
| Community pinned posts | `placement`             | No       | Placement such as default or announcement.                              |
| Community pinned posts | `sortBy`                | No       | Sort order where exposed by the target SDK.                             |
| Community pinned posts | `includeMixedStructure` | No       | Include mixed-structure posts where supported.                          |
| Global pinned posts    | `includeMixedStructure` | No       | Include mixed-structure posts in global pinned results where supported. |

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

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