> ## Documentation Index > Fetch the complete documentation index at: https://cometchat-22654f5b-docs-restapi-chatapi-eng-38785.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. > Replace the full CometChat global pinned conversation list with REST API - the conversations pinned at the top for every end user. # Replace global pinned conversations For the complete error reference, see [Error Guide](/articles/error-guide). ## OpenAPI ````yaml put /conversations/pinned openapi: 3.0.0 info: title: Chat APIs description: Manage messages, users, groups for a particular app using our Chat API. version: '3.0' servers: - url: https://{appId}.api-{region}.cometchat.io/v3 variables: appId: default: appId description: (Required) App ID region: enum: - us - eu - in default: us description: Select Region security: [] tags: - name: API Keys description: The API keys are used to authorise the APIs - name: Roles description: The roles are used to give user access rights - name: Users description: The REST collection for users. - name: Auth Tokens description: The auth tokens are used to login end users using client SDKs. - name: Blocked Users description: The REST collections for blocked users. - name: Friends description: List,add and remove friends by passing UID in path variables - name: Groups description: The REST collections for groups. - name: Banned Users description: Ban and Unban user by passing other UID in path variables. - name: Group Members description: The REST collections for group members. - name: Messages description: The REST collections for messages. - name: Conversations description: The REST collections for conversations. - name: Restrict Features description: Allows Restricting Features - name: Metrics description: Allows accessing Data Metrics - name: Triggers description: Allows adding triggers to a webhook. - name: Webhooks description: Allows accessing Webhooks. - name: Notifications description: Allows configuring Notifications core. - name: Moderation description: The REST collections for Moderations. paths: /conversations/pinned: put: tags: - Conversations summary: Replace global pinned conversations description: >- Replaces the whole global pinned conversation list - the conversations pinned at the top for every end user. The array is the desired final state and order - entries that are absent get unpinned, new entries get pinned, and array order becomes display order. Send an empty array to clear the list. operationId: replace-app-pinned-conversations requestBody: required: true content: application/json: schema: required: - pinnedConversations properties: pinnedConversations: description: >- The conversations to pin at the top for every end user, in the order they should appear. Each entry names either a user (uid) or a group (guid). Entries left out of the array are unpinned. Send an empty array to clear the list. Repeated entries are kept once, at their first position. type: array items: properties: uid: description: UID of the user, for a one-to-one conversation. type: string guid: description: GUID of the group, for a group conversation. type: string type: object example: - guid: supergroup - uid: superhero2 type: object responses: '200': description: The new global pinned conversation list, in display order content: application/json: schema: properties: data: type: array items: $ref: '#/components/schemas/conversationSchema' type: object example: data: - conversationId: supergroup conversationType: group pinnedBy: app_system pinnedAt: 1700210300 - conversationId: superhero1_user_superhero2 conversationType: user pinnedBy: app_system pinnedAt: 1700210299 '400': description: >- The global list exceeds its cap, or an entry names neither a uid nor a guid content: application/json: schema: type: object example: error: code: ERR_SYSTEM_PINNED_CONVERSATIONS_LIMIT_EXCEEDED message: >- The number of pinned conversations exceeds the allowed limit of 5. security: - apiKey: [] components: schemas: conversationSchema: description: Response data properties: conversationId: type: string conversationType: type: string unreadMessageCount: type: string createdAt: type: integer updatedAt: type: integer lastMessage: properties: id: type: string conversationId: type: string sender: type: string receiverType: type: string receiver: type: string category: type: string type: type: string data: type: object allOf: - properties: action: type: string type: object - $ref: '#/components/schemas/objectEntitySchema' sentAt: type: integer updatedAt: type: integer receipts: properties: data: type: array items: {} type: object type: object conversationWith: type: object pinnedBy: description: >- UID of the user who pinned the conversation, or app_system for a global pin. Left out of the response when the conversation is not pinned. type: string pinnedAt: description: >- When the conversation was pinned, in seconds. Left out of the response when the conversation is not pinned. type: integer type: object objectEntitySchema: properties: entities: properties: by: properties: entity: properties: uid: type: string name: type: string role: type: string status: type: string createdAt: type: integer type: object entityType: type: string type: object for: properties: entity: properties: guid: type: string icon: type: string name: type: string type: type: string owner: type: string createdAt: type: integer updatedAt: type: integer updatedBy: type: integer description: type: integer membersCount: type: integer conversationId: type: integer type: object entityType: type: string type: object 'on': properties: entity: properties: uid: type: string link: type: string name: type: string role: type: string avatar: type: string status: type: string createdAt: type: integer updatedAt: type: integer conversationId: type: string type: object entityType: type: string type: object type: object type: object securitySchemes: apiKey: type: apiKey description: API Key with fullAccess scope(i.e. Rest API Key from the Dashboard). name: apikey in: header ````