openapi: 3.0.0
info:
  title: Files
  description: |
    Utilize the Files API to download or share files with any chat, channel, or bot you have access to.
  contact: {}
  version: 1.0.0
externalDocs:
  description: Find out more about Zoho Cliq APIs V2
  url: https://www.zoho.com/cliq/help/restapi/v2/
servers:
  - url: https://cliq.zoho.com/api/v2
    description: Zoho Cliq US DC
tags:
  - name: files
    description: Files Module
paths:
  /files/{FILE_ID}:
    get:
      summary: Get Files
      operationId: Get Files
      description: |
        Get files from any chat, channel or bot which you are a part of using its file ID. <br><br>  <p>
          <b>Threshold limit</b>: 20 requests per min per user<br>
          Number of API calls allowed within a minute.<br><br>
          <b>Lock period</b>: 10 minutes<br>Wait time before consecutive API requests.<br>
        </p>
      parameters:
        - name: FILE_ID
          in: path
          required: true
          description: |
            The unique identifier of the file.
            Note : You can retrieve the file id using the - Get messages endpoint To learn how to retrieve this ID, see <a href="/cliq/help/restapi/v2/glossary/#FILE_ID">FILE_ID</a> in the Glossary page.
          schema:
            type: string
      responses:
        '200':
          description: The request was successfully completed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/no-response'
        '400':
          description: Bad Request.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The request cannot be performed. Usually because of malformed parameter or missing parameter.
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Request was rejected because of invalid AuthToken.
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The user does not have enough permission or possibly not an user of the respective organization to access the resource.
        '404':
          description: Invalid URL.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The URL you've sent is wrong. It's possible that the resource you've requested has been moved to another URL.
        '405':
          description: Method Not Allowed.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The requested resource does not support the HTTP method used. For example, requesting List of all customers API with PUT as the HTTP method.
        '406':
          description: Not Acceptable.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The response has been received but the requested response type is not supported by the browser.
        '429':
          description: Too many requests.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Too many requests within a certain time frame.
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Cliq server encountered an error which prevents it from fulfilling the request.
      security:
        - Cliq_Auth:
            - ZohoCliq.Attachments.READ
      tags:
        - files
  /channelsbyname/{CHANNEL_UNIQUE_NAME}/files:
    post:
      summary: Share files to a channel
      operationId: Share files to a channel
      description: |
        Share files to a bot using the bot unique name. The content of the file should be of type multipart/form-data <br><br>  <p>
          <b>Threshold limit</b>: 20 requests per min per user<br>
          Number of API calls allowed within a minute.<br><br>
          <b>Lock period</b>: 10 minutes<br>Wait time before consecutive API requests.<br>
        </p>
      parameters:
        - name: CHANNEL_UNIQUE_NAME
          in: path
          required: true
          description: |
            The unique identifier of the channel in which the attachment needs to be shared To learn how to retrieve this ID, see <a href="/cliq/help/restapi/v2/glossary/#CHANNEL_UNIQUE_NAME">CHANNEL_UNIQUE_NAME</a> in the Glossary page.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/share-files-to-channel-request-body'
      responses:
        '200':
          description: The request was successfully completed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/no-response'
        '400':
          description: Bad Request.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The request cannot be performed. Usually because of malformed parameter or missing parameter.
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Request was rejected because of invalid AuthToken.
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The user does not have enough permission or possibly not an user of the respective organization to access the resource.
        '404':
          description: Invalid URL.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The URL you've sent is wrong. It's possible that the resource you've requested has been moved to another URL.
        '405':
          description: Method Not Allowed.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The requested resource does not support the HTTP method used. For example, requesting List of all customers API with PUT as the HTTP method.
        '406':
          description: Not Acceptable.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The response has been received but the requested response type is not supported by the browser.
        '429':
          description: Too many requests.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Too many requests within a certain time frame.
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Cliq server encountered an error which prevents it from fulfilling the request.
      security:
        - Cliq_Auth:
            - ZohoCliq.Webhooks.CREATE
      tags:
        - files
  /bots/{BOT_UNIQUE_NAME}/files:
    post:
      summary: Share files to a bot
      operationId: Share files to a bot
      description: |
        Share files to a bot using the bot unique name. The content of the file should be of type multipart/form-data. <br><br>  <p>
          <b>Threshold limit</b>: 20 requests per min per user<br>
          Number of API calls allowed within a minute.<br><br>
          <b>Lock period</b>: 10 minutes<br>Wait time before consecutive API requests.<br>
        </p>
      parameters:
        - name: BOT_UNIQUE_NAME
          in: path
          required: true
          description: |
            The unique identifier of the bot in which the attachment needs to be sent To learn how to retrieve this ID, see <a href="/cliq/help/restapi/v2/glossary/#BOT_UNIQUE_NAME">BOT_UNIQUE_NAME</a> in the Glossary page.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/share-files-to-bot-request-body'
      responses:
        '200':
          description: The request was successfully completed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/no-response'
        '400':
          description: Bad Request.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The request cannot be performed. Usually because of malformed parameter or missing parameter.
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Request was rejected because of invalid AuthToken.
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The user does not have enough permission or possibly not an user of the respective organization to access the resource.
        '404':
          description: Invalid URL.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The URL you've sent is wrong. It's possible that the resource you've requested has been moved to another URL.
        '405':
          description: Method Not Allowed.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The requested resource does not support the HTTP method used. For example, requesting List of all customers API with PUT as the HTTP method.
        '406':
          description: Not Acceptable.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The response has been received but the requested response type is not supported by the browser.
        '429':
          description: Too many requests.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Too many requests within a certain time frame.
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Cliq server encountered an error which prevents it from fulfilling the request.
      security:
        - Cliq_Auth:
            - ZohoCliq.Webhooks.CREATE
      tags:
        - files
  /chats/{CHAT_ID}/files:
    post:
      summary: Share files in a chat
      operationId: Share files in a chat
      description: |
        Share files in a chat using the Chat ID. The content of the file should be of type multipart/form-data <br><br>  <p>
          <b>Threshold limit</b>: 20 requests per min per user<br>
          Number of API calls allowed within a minute.<br><br>
          <b>Lock period</b>: 10 minutes<br>Wait time before consecutive API requests.<br>
        </p>
      parameters:
        - name: CHAT_ID
          in: path
          required: true
          description: |
            The unique identifier of the chat in which the attachment needs to be sent To learn how to retrieve this ID, see <a href="/cliq/help/restapi/v2/glossary/#CHAT_ID">CHAT_ID</a> in the Glossary page.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/share-files-to-chat-request-body'
      responses:
        '200':
          description: The request was successfully completed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/no-response'
        '400':
          description: Bad Request.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The request cannot be performed. Usually because of malformed parameter or missing parameter.
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Request was rejected because of invalid AuthToken.
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The user does not have enough permission or possibly not an user of the respective organization to access the resource.
        '404':
          description: Invalid URL.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The URL you've sent is wrong. It's possible that the resource you've requested has been moved to another URL.
        '405':
          description: Method Not Allowed.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The requested resource does not support the HTTP method used. For example, requesting List of all customers API with PUT as the HTTP method.
        '406':
          description: Not Acceptable.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The response has been received but the requested response type is not supported by the browser.
        '429':
          description: Too many requests.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Too many requests within a certain time frame.
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Cliq server encountered an error which prevents it from fulfilling the request.
      security:
        - Cliq_Auth:
            - ZohoCliq.Webhooks.CREATE
      tags:
        - files
  /buddies/{EMAIL_ID}/files:
    post:
      summary: Share files to a user
      operationId: Share files to a user
      description: |
        Share files to a user using their Email ID or User ID. The content of the file should be of type multipart/form-data <br><br>  <p>
          <b>Threshold limit</b>: 20 requests per min per user<br>
          Number of API calls allowed within a minute.<br><br>
          <b>Lock period</b>: 10 minutes<br>Wait time before consecutive API requests.<br>
        </p>
      parameters:
        - name: CHAT_ID
          in: path
          required: true
          description: |
            The unique identifier of the chat in which the attachment needs to be sent To learn how to retrieve this ID, see <a href="/cliq/help/restapi/v2/glossary/#CHAT_ID">CHAT_ID</a> in the Glossary page.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/share-files-to-channel-request-body'
      responses:
        '200':
          description: The request was successfully completed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/no-response'
        '400':
          description: Bad Request.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The request cannot be performed. Usually because of malformed parameter or missing parameter.
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Request was rejected because of invalid AuthToken.
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The user does not have enough permission or possibly not an user of the respective organization to access the resource.
        '404':
          description: Invalid URL.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The URL you've sent is wrong. It's possible that the resource you've requested has been moved to another URL.
        '405':
          description: Method Not Allowed.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The requested resource does not support the HTTP method used. For example, requesting List of all customers API with PUT as the HTTP method.
        '406':
          description: Not Acceptable.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The response has been received but the requested response type is not supported by the browser.
        '429':
          description: Too many requests.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Too many requests within a certain time frame.
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Cliq server encountered an error which prevents it from fulfilling the request.
      security:
        - Cliq_Auth:
            - ZohoCliq.Webhooks.CREATE
      tags:
        - files
components:
  schemas:
    no-response:
      type: object
      description: Represents a response indicating that the request was processed successfully but no content is returned.
      properties:
        Response Code:
          type: string
          description: HTTP status code indicating no content is returned.
          example: 204 No response
    share-files-to-channel-request-body:
      type: object
      description: Request body for sharing one or more files to a channel.
      required:
        - files
      properties:
        files:
          type: array
          description: |
            The file(s) to be shared.
            - File size limit per file: 50 MB
            - Maximum number of files that can be shared at a time: 10
          maxItems: 10
          items:
            type: string
            format: binary
            description: The binary content of a file to be shared.
        comments:
          type: array
          description: The comments to be added for each file.
          items:
            type: string
            description: A comment corresponding to a file.
        bot_unique_name:
          type: string
          description: Use this parameter to share a file in a channel as a bot. The bot must already be a participant in the channel.
        mark_as_read:
          type: boolean
          description: Marks the shared file as read for the user. Defaults to unread.
        bot_name:
          type: string
          description: To share the file with a custom name displayed as the sender.
        bot_image:
          type: string
          format: uri
          description: The URL of the image used as the sender's avatar or profile picture.
      example: |
        Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW

        ------WebKitFormBoundary7MA4YWxkTrZu0gW
        Content-Disposition: form-data; name="file"; filename="zylker-sales.pdf"
        Content-Type: application/pdf

        Content of zylker-sales.pdf

        ------WebKitFormBoundary7MA4YWxkTrZu0gW
        Content-Disposition: form-data; name="file"; filename="revenue-chart.jpg"
        Content-Type: image/jpeg

        Content of revenue-chart.jpg

        ------WebKitFormBoundary7MA4YWxkTrZu0gW
        Content-Disposition: form-data; name="comments"

        ["Annual Zylker Sales Report","Revenue Chart for Q3"]
        ------WebKitFormBoundary7MA4YWxkTrZu0gW--
    share-files-to-bot-request-body:
      type: object
      description: Request body for sharing files with a specific bot subscriber.
      required:
        - files
      properties:
        files:
          type: array
          description: |
            The file(s) to be shared.  
            - File size limit: 50 MB  
            - Maximum number of files that can be shared at a time: 10
          items:
            type: string
            format: binary
            description: The binary content of the file to be shared.
        comments:
          type: array
          description: The comments to be added for each file.
          items:
            type: string
            description: Comment associated with a file.
        user_id:
          type: string
          description: Use this parameter to share the file with a specific subscriber of the bot.
        bot_name:
          type: string
          description: To share the file with a custom name displayed as the sender.
        bot_image:
          type: string
          format: uri
          description: The URL of the image used as the sender's avatar or profile picture.
      example: |
        Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW

        ------WebKitFormBoundary7MA4YWxkTrZu0gW
        Content-Disposition: form-data; name="file"; filename="zylker-sales.pdf"
        Content-Type: application/pdf

        Content of zylker-sales.pdf

        ------WebKitFormBoundary7MA4YWxkTrZu0gW
        Content-Disposition: form-data; name="file"; filename="revenue-chart.jpg"
        Content-Type: image/jpeg

        Content of revenue-chart.jpg

        ------WebKitFormBoundary7MA4YWxkTrZu0gW
        Content-Disposition: form-data; name="comments"

        ["Annual Zylker Sales Report","Revenue Chart for Q3"]
        ------WebKitFormBoundary7MA4YWxkTrZu0gW--
    share-files-to-chat-request-body:
      type: object
      description: Request body for sharing files to a chat or direct conversation.
      required:
        - files
      properties:
        files:
          type: array
          description: |
            The file(s) to be shared.
            - Maximum file size per file: 50 MB
            - Maximum number of files that can be shared at a time: 10
          maxItems: 10
          items:
            type: string
            format: binary
            description: The binary content of a file to be shared.
        comments:
          type: array
          description: List of comments corresponding to each file being shared.
          items:
            type: string
            description: A comment corresponding to a file.
        mark_as_read:
          type: boolean
          description: Marks the shared file as read for the user. Defaults to unread.
        bot_name:
          type: string
          description: To share the file with a custom name displayed as the sender.
        bot_image:
          type: string
          format: uri
          description: The URL of the image to be used as the sender's avatar.
        bot_unique_name:
          type: string
          description: Unique name of the bot to share the files as. The bot must already be a participant in the chat.
      example: |
        Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW

        ------WebKitFormBoundary7MA4YWxkTrZu0gW
        Content-Disposition: form-data; name="file"; filename="zylker-sales.pdf"
        Content-Type: application/pdf

        Content of zylker-sales.pdf

        ------WebKitFormBoundary7MA4YWxkTrZu0gW
        Content-Disposition: form-data; name="file"; filename="revenue-chart.jpg"
        Content-Type: image/jpeg

        Content of revenue-chart.jpg

        ------WebKitFormBoundary7MA4YWxkTrZu0gW
        Content-Disposition: form-data; name="comments"

        ["Annual Zylker Sales Report","Revenue Chart for Q3"]
        ------WebKitFormBoundary7MA4YWxkTrZu0gW--
  securitySchemes:
    Cliq_Auth:
      type: oauth2
      x-authorization-example: Bearer 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f
      flows:
        implicit:
          authorizationUrl: https://accounts.zoho.com/oauth/v2/auth
          scopes:
            ZohoCliq.Attachments.READ: Read Attachments
            ZohoCliq.Webhooks.CREATE: Write and Modify Messages and Attachments
