Zoho Cliq Stars API

openapi: 3.2.0
info:
  title: Stars API
  description: The Stars API allows users to organize and prioritize messages by marking them with specific star types.
  contact: {}
  version: 3.0.0
servers:
- url: https://cliq.zoho.com/api/v3
  description: Zoho Cliq US DC
tags:
- name: Stars
paths:
  /stars:
    post:
      summary: Star a Message or Update Star Type
      operationId: star_a_message
      description: 'Stars a message with a specific star type. This enables users to categorize messages for easier retrieval and workflow management. Each message can have only one active star type at a time.


        If the message is already starred, this operation updates the existing star type to the newly specified type and hence no separate update call is needed.

        When the star type is updated, the response includes star_information.old_star_type indicating the previous star type.


        OAuth Scope: Messages


        Threshold limit: 50 requests per min


        Number of API calls allowed within a minute.


        Lock period: 5 minutes

        Wait time before consecutive API requests after exceeding the threshold.


        !

        Possible Error Codes

        Click to expand


        Error Code

        Description


        input_invalid

        Missing or invalid input parameters.


        chat_not_found

        The specified chat does not exist or cannot be accessed.


        operation_failed

        The operation could not be completed due to a server-side issue.


        Error Response Format


        When an error occurs, the API returns a JSON response in this format:


        {"message": "A human-readable description of the error.", "code": "error_code"}


        where code is the error identifier (as listed above) and message is a human-readable explanation of what went wrong.'
      requestBody:
        description: Provide the chat ID, message ID, and the star type to categorize the message. To update an existing star type, send the same fields with the new star type - the API will automatically update it.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StarMessageRequest'
            examples:
              star_a_message:
                summary: Star a message
                value:
                  chat_id: CT_1894736520184930172_847291635
                  message_id: '1746000123456789001'
                  star_type: important
              update_star_type:
                summary: Update star type of an already-starred message
                value:
                  chat_id: CT_1894736520184930172_847291635
                  message_id: '1746000123456789001'
                  star_type: follow_up
      responses:
        '200':
          description: Message starred successfully. If the message was already starred, the star type has been updated and the previous type is returned in `star_information.old_star_type`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StarMessageResponse'
              examples:
                star_a_message:
                  summary: Message starred for the first time
                  value:
                    type: text
                    id: '1746000123456789001'
                    time: '2026-04-30T10:00:00Z'
                    sender:
                      id: '1234567890'
                      name: Alice Johnson
                    content:
                      text: Please review the Q2 report before Friday.
                    is_pinned: false
                    star_information:
                      star_type: important
                      starred_message_time: '2026-04-30T10:15:30Z'
                    chat_information:
                      chat_id: CT_1894736520184930172_847291635
                      chat_type: chat
                      title: Alice Johnson
                      joined: true
                update_star_type:
                  summary: Star type updated - old_star_type shows the previous type
                  value:
                    type: text
                    id: '1746000123456789001'
                    time: '2026-04-30T10:00:00Z'
                    sender:
                      id: '1234567890'
                      name: Alice Johnson
                    content:
                      text: Please review the Q2 report before Friday.
                    is_pinned: false
                    star_information:
                      star_type: follow_up
                      starred_message_time: '2026-04-30T10:15:30Z'
                      old_star_type: important
                    chat_information:
                      chat_id: CT_1894736520184930172_847291635
                      chat_type: chat
                      title: Alice Johnson
                      joined: true
        '400':
          description: Bad Request. Missing or invalid parameters submitted.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 1012
                  message:
                    type: string
                    example: input_invalid
              example:
                code: 1012
                message: input_invalid
        '401':
          description: Unauthorized. Request was rejected due to invalid authentication token.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Request was rejected because of invalid AuthToken.
        '403':
          description: Forbidden. User does not have sufficient permissions to access this resource.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The user does not have enough permission or possibly not a user of the respective organization to access the resource.
        '404':
          description: Not Found. The specified message or chat does not exist or user cannot access it.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 11016
                  message:
                    type: string
                    example: chat_not_found
              examples:
                chat_not_found:
                  value:
                    code: 11016
                    message: chat_not_found
                  summary: Chat does not exist or user cannot access it
        '429':
          description: Too Many Requests. Rate limit exceeded.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Too many requests within a certain time frame.
        '500':
          description: Internal Server Error. Unexpected error during star operation.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 1011
                  message:
                    type: string
                    example: operation_failed
              example:
                code: 1011
                message: operation_failed
      security:
      - Cliq_Auth:
        - ZohoCliq.Messages.CREATE
      tags:
      - Stars
    get:
      summary: List starred messages
      operationId: list_starred_messages
      description: 'Retrieves the authenticated user''s starred messages with support for advanced filtering, cursor-based pagination, and incremental synchronization.


        This endpoint allows you to filter starred messages by chat, star type, and time range. Use pagination tokens to navigate through large result sets efficiently.


        OAuth Scope: Messages


        Threshold limit: 30 requests per min


        Number of API calls allowed within a minute.


        Lock period: 5 minutes

        Wait time before consecutive API requests after exceeding the threshold.


        !

        Possible Error Codes

        Click to expand


        Error Code

        Description


        input_invalid

        Invalid filter inputs were provided.


        chat_access_denied

        You are not authorized to access one or more requested chats.


        operation_failed

        The operation could not be completed due to a server-side issue.


        Error Response Format


        When an error occurs, the API returns a JSON response in this format:


        {"message": "A human-readable description of the error.", "code": "error_code"}


        where code is the error identifier (as listed above) and message is a human-readable explanation of what went wrong.'
      parameters:
      - name: chat_id
        in: query
        required: false
        description: 'Filter starred messages to only include those from a specific chat. Provide the chat ID in the format "2000000012345_2000000067890". If omitted, starred messages from all chats will be included.

          '
        schema:
          type: string
          example: '2000000012345_2000000067890'
      - name: star_type
        in: query
        required: false
        description: "Filter starred messages by a specific star type.\n  <br><br>\n  <b>Allowed values:</b><br>\n  <ul>\n    <li><code>important</code>: Mark messages that require special attention or contain critical information.</li>\n    <li><code>to_do</code>: Flag messages representing tasks or action items that need to be completed.</li>\n    <li><code>note</code>: Save messages for future reference or as reminders of important information.</li>\n    <li><code>manager</code>: Highlight messages related to managerial communications or approvals.</li>\n    <li><code>follow_up</code>: Identify messages that require follow-up actions or responses.</li>\n    <li><code>all</code>: Retrieve all starred messages regardless of star type.</li>\n  </ul>\n"
        schema:
          type: string
          enum:
          - important
          - to_do
          - note
          - manager
          - follow_up
          - all
          example: important
      - name: from_time
        in: query
        required: false
        description: '<ul>

          <li>Lower bound timestamp for message time.</li>

          <li>Accepts epoch milliseconds (for example, <code>1704067200000</code>) or <a href="https://en.wikipedia.org/wiki/ISO_8601">ISO 8601</a> datetime strings (for example, <code>2024-01-01T00:00:00Z</code>).</li>

          <li>Only messages starred after this time will be included in the results.</li>

          <li>If omitted, there is no lower time limit on the messages returned.</li>

          </ul>

          '
        schema:
          type: string
          example: '1704067200000'
      - name: to_time
        in: query
        required: false
        description: '<ul>

          <li>Upper bound timestamp for message time.</li>

          <li>Accepts epoch milliseconds (for example, <code>1735689599999</code>) or <a href="https://en.wikipedia.org/wiki/ISO_8601">ISO 8601</a> datetime strings (for example, <code>2024-12-31T23:59:59Z</code>).</li>

          <li>Only messages starred before this time will be included in the results.</li>

          <li>If omitted, there is no upper time limit on the messages returned.</li>

          </ul>

          '
        schema:
          type: string
          example: '1735689599999'
      - name: limit
        in: query
        required: false
        description: 'Maximum number of starred messages to return in the response.<br>

          <b>Maximum limit</b>:50<br>

          <b>Default</b>:50<br>

          If the total number of starred messages exceeds this limit, a pagination token will be included in the response to retrieve the next page of results.

          '
        schema:
          type: integer
          minimum: 1
          maximum: 50
          default: 50
          example: 25
      - name: next_token
        in: query
        required: false
        description: "Opaque pagination token to retrieve the next page of results.\n<ul>\n  <li>This token is provided in the response when there are more results available than can fit in a single response.</li>\n  <li>To retrieve the next page, include this token in the subsequent request without modifying it.</li>\n  <li>The token is base64-encoded.</li>\n  <li>If omitted, the first page of results will be returned.</li>\n</ul>\n"
        schema:
          type: string
          example: ey5MDUzODAwMDAwMDAxMjM0NSIsInRpbWVzdGFtcCI6MTcxNDkyMDQwMDAwMH0=
      - name: sync_token
        in: query
        required: false
        description: "Synchronization token for incremental updates.\n<ul>\n  <li>This token is returned in the response to help clients sync local state.</li>\n  <li>When provided in a request, only starred message changes after that sync point are returned.</li>\n  <li>If omitted, results are returned based on the other filters.</li>\n  <li><b>Format</b>: base64 token.</li>\n  <li><b>Maximum length</b>: 200 characters.</li>\n</ul>\n"
        schema:
          type: string
          maxLength: 200
          example: 911083u18u3811834u
      responses:
        '200':
          description: Starred messages retrieved successfully.
          content:
            application/json:
              examples:
                starred_messages:
                  summary: List of starred messages with next_token
                  value:
                    star_messages:
                    - type: text
                      id: '1746000123456789001'
                      time: '2026-04-30T10:00:00Z'
                      sender:
                        id: '1234567890'
                        name: Alice Johnson
                      content:
                        text: Please review the Q2 report before Friday.
                      is_pinned: false
                      star_information:
                        star_type: important
                        starred_message_time: '2026-04-30T10:15:30Z'
                      chat_information:
                        chat_id: chid_abcdef123456
                        chat_type: chat
                        title: Alice Johnson
                        joined: true
                    - type: file
                      id: '1746000987654321002'
                      time: '2026-04-30T09:40:00Z'
                      sender:
                        id: '9876543210'
                        name: Bob Smith
                      content:
                        file_name: Q2_Report_Final.pdf
                        file_size: 204800
                        file_url: https://cliq.zoho.com/file/download?id=enc_file_id_xyz
                      is_pinned: false
                      star_information:
                        star_type: to_do
                        starred_message_time: '2026-04-30T09:45:00Z'
                      chat_information:
                        chat_id: chid_channel_org_001
                        chat_type: channel
                        title: Engineering Announcements
                        display_name: Engineering Announcements
                        joined: true
                    next_token: eyJsYXN0U3RhcnJlZFRpbWUiOiIxNzQ1OTkwMDAwMDAwIiwibGltaXQiOjJ9
              schema:
                type: object
                properties:
                  type:
                    type: string
                    example: star_messages
                  next_token:
                    type: string
                    description: Opaque base64-encoded pagination token for the next page. Omitted if no more pages exist.
                    example: asdhfqjdbnajdndjnadj
                  sync_token:
                    type: string
                    description: Synchronization token for incremental updates.
                    example: 911083u18u3811834u
                  data:
                    type: array
                    description: Array of starred messages in V3 message hash format.
                    items:
                      type: object
                      properties:
                        star_information:
                          type: object
                          properties:
                            star_type:
                              type: string
                              example: important
                            starred_message_time:
                              type: string
                              format: date-time
                              example: '2026-03-25T10:30:00.000Z'
                            file_permission:
                              type: object
                              properties:
                                cross_org_policy:
                                  type: boolean
                                  example: true
                                file_scope:
                                  type: string
                                  example: '60005678901'
                        chat_information:
                          type: object
                          properties:
                            chat_id:
                              type: string
                              example: '2000000012345_2000000067890'
                            chat_type:
                              type: string
                              example: direct
                            title:
                              type: string
                              example: John Doe
                            display_name:
                              type: string
                              example: John Doe
                            joined:
                              type: boolean
                              example: true
                            receiver:
                              type: string
                              example: '2000000012345'
        '400':
          description: Bad Request. Query parameter validation failed.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 1012
                  message:
                    type: string
                    example: input_invalid
        '401':
          description: Unauthorized. Request was rejected due to invalid authentication token.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Request was rejected because of invalid AuthToken.
        '403':
          description: Forbidden. User is not a participant of the specified chat.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 430002
                  message:
                    type: string
                    example: chat_access_denied
              example:
                code: 430002
                message: chat_access_denied
        '429':
          description: Too Many Requests. Rate limit exceeded.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Too many requests within a certain time frame.
        '500':
          description: Internal Server Error. Unexpected error occurred during retrieval.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 1011
                  message:
                    type: string
                    example: operation_failed
      security:
      - Cliq_Auth:
        - ZohoCliq.Messages.READ
      tags:
      - Stars
  /stars/{MESSAGE_ID}:
    delete:
      summary: Unstar a Message
      operationId: unstar_a_message
      description: 'Removes the star from a specified message. This operation permanently deletes the star record for the authenticated user.


        If the message is not currently starred by the user, an error will be returned.


        OAuth Scope: Messages


        Threshold limit: 50 requests per min


        Number of API calls allowed within a minute.


        Lock period: 5 minutes

        Wait time before consecutive API requests after exceeding the threshold.


        !

        Possible Error Codes

        Click to expand


        Error Code

        Description


        input_invalid

        Missing or invalid message identifier.


        star_not_found

        The message is not currently starred for the user.


        operation_failed

        The operation could not be completed due to a server-side issue.


        Error Response Format


        When an error occurs, the API returns a JSON response in this format:


        {"message": "A human-readable description of the error.", "code": "error_code"}


        where code is the error identifier (as listed above) and message is a human-readable explanation of what went wrong.'
      parameters:
      - name: MESSAGE_ID
        in: path
        required: true
        description: 'The unique identifier of the message to be unstarred.<br>

          Use the <a href="/cliq/help/restapi/v3/stars/#list-starred-messages">Retrieve Starred Messages</a> endpoint to get the message IDs of starred messages.

          '
        schema:
          type: string
        example: MESSAGE_ID
      responses:
        '204':
          description: Message unstarred successfully. No content returned.
        '400':
          description: Bad Request. Missing or invalid message ID.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 1012
                  message:
                    type: string
                    example: input_invalid
              example:
                code: 1012
                message: input_invalid
        '401':
          description: Unauthorized. Request was rejected due to invalid authentication token.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Request was rejected because of invalid AuthToken.
        '403':
          description: Forbidden. User does not have sufficient permissions to access this resource.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The user does not have enough permission or possibly not a user of the respective organization to access the resource.
        '404':
          description: Not Found. Star record not found for the current user.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 8004
                  message:
                    type: string
                    example: star_not_found
              example:
                code: 8004
                message: star_not_found
        '429':
          description: Too Many Requests. Rate limit exceeded.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Too many requests within a certain time frame.
        '500':
          description: Internal Server Error. Unexpected error during unstar operation.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 1011
                  message:
                    type: string
                    example: operation_failed
              example:
                code: 1011
                message: operation_failed
      security:
      - Cliq_Auth:
        - ZohoCliq.Messages.DELETE
      tags:
      - Stars
components:
  schemas:
    ChatInformation:
      type: object
      description: Information about the chat containing the starred message.
      properties:
        chat_id:
          type: string
          description: The unique identifier of the chat.
          example: '2000000012345_2000000067890'
        chat_type:
          type: string
          description: The type of chat (e.g., direct, channel, group).
          example: direct
        title:
          type: string
          description: The title of the chat.
          example: John Doe
        display_name:
          type: string
          description: The display name shown for the chat.
          example: John Doe
        joined:
          type: boolean
          description: Indicates if the user has joined the chat.
          example: true
        receiver:
          type: string
          description: The user ID of the message receiver (for direct chats).
          example: '2000000012345'
    StarMessageResponse:
      type: object
      properties:
        type:
          type: string
          example: text
        id:
          type: string
          description: The unique identifier of the message.
          example: '1746000123456789001'
        time:
          type: string
          format: date-time
          description: The timestamp when the message was sent (<a href="https://en.wikipedia.org/wiki/ISO_8601">ISO 8601</a> format).
          example: '2026-04-30T10:00:00Z'
        sender:
          type: object
          properties:
            id:
              type: string
              example: '1234567890'
            name:
              type: string
              example: Alice Johnson
        content:
          type: object
          properties:
            text:
              type: string
              example: Please review the Q2 report before Friday.
        is_pinned:
          type: boolean
          example: false
        star_information:
          $ref: '#/components/schemas/StarInformation'
        chat_information:
          $ref: '#/components/schemas/ChatInformation'
      example:
        type: text
        id: '1746000123456789001'
        time: '2026-04-30T10:00:00Z'
        sender:
          id: '1234567890'
          name: Alice Johnson
        content:
          text: Please review the Q2 report before Friday.
        is_pinned: false
        star_information:
          star_type: important
          starred_message_time: '2026-04-30T10:15:30Z'
        chat_information:
          chat_id: CT_1894736520184930172_847291635
          chat_type: chat
          title: Alice Johnson
          joined: true
    StarMessageRequest:
      type: object
      required:
      - chat_id
      - message_id
      - star_type
      properties:
        chat_id:
          type: string
          description: The unique identifier of the chat containing the message to be starred.
          example: CT_1894736520184930172_847291635
        message_id:
          type: string
          description: The unique identifier of the message to be starred.
          example: '1746000123456789001'
        star_type:
          type: string
          description: "The category of the star to apply to the message. This determines how the message will be organized and retrieved in starred messages lists.\n<br><br>\n<b>Allowed values:</b><br>\n<ul>\n  <li><code>important</code>: Mark messages that require special attention or contain critical information.</li>\n  <li><code>to_do</code>: Flag messages representing tasks or action items that need to be completed.</li>\n  <li><code>note</code>: Save messages for future reference or as reminders of important information.</li>\n  <li><code>manager</code>: Highlight messages related to managerial communications or approvals.</li>\n  <li><code>follow_up</code>: Identify messages that require follow-up actions or responses.</li>\n</ul>\n"
          enum:
          - important
          - to_do
          - note
          - manager
          - follow_up
          example: important
    StarInformation:
      type: object
      description: Information about the star applied to a message.
      properties:
        star_type:
          type: string
          description: The category of the star.
          enum:
          - important
          - to_do
          - note
          - manager
          - follow_up
          example: important
        old_star_type:
          type: string
          description: The previous star type if the message was already starred (returned only on updates).
          example: note
        starred_message_time:
          type: string
          format: date-time
          description: The timestamp when the message was starred (<a href="https://en.wikipedia.org/wiki/ISO_8601">ISO 8601</a> format).
          example: '2026-03-25T10:30:00.000Z'
        file_permission:
          type: object
          description: File permissions associated with the starred message (if applicable).
          properties:
            cross_org_policy:
              type: boolean
              description: Indicates if cross-organization access is allowed.
              example: true
            file_scope:
              type: string
              description: The scope identifier for file access.
              example: '60005678901'
  securitySchemes:
    Cliq_Auth:
      type: oauth2
      x-authorization-example: Bearer 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f
      flows:
        authorizationCode:
          authorizationUrl: https://accounts.zoho.com/oauth/v2/auth
          tokenUrl: https://accounts.zoho.com/oauth/v2/token
          scopes:
            ZohoCliq.Messages.CREATE: Create messages and star messages
            ZohoCliq.Messages.READ: Read messages and starred messages
            ZohoCliq.Messages.UPDATE: Update messages and star types
            ZohoCliq.Messages.DELETE: Delete messages and unstar messages
externalDocs:
  description: Find out more about Zoho Cliq APIs V3
  url: https://www.zoho.com/cliq/help/restapi/v3/