openapi: 3.0.0
info:
  title: Custom Themes
  description: The Custom Themes API lets organisation admins create, retrieve, update, and delete custom color themes, and map those themes to teams for a consistent branded experience across clients. These APIs are accessible to organisation admins only.
  contact: {}
  version: 1.0.0
externalDocs:
  description: Find out more about Zoho Cliq APIs
  url: https://www.zoho.com/cliq/help/restapi/v2/
servers:
  - url: https://cliq.zoho.com/api/v2
    description: Zoho Cliq US DC
tags:
  - name: customthemes
    description: Custom Themes Module
paths:
  /themes:
    get:
      summary: Get all themes
      operationId: getAllThemes
      description: |
        Returns all custom themes configured for the organisation.
        Each theme includes platform-specific colors, mapped team IDs, and its activation status.
        <br><br>
        <p>
          <b>OAuth Scope</b>: ZohoCliq.Organisation.READ<br>
        </p>
      responses:
        '200':
          description: A list of custom themes was retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/get-all-themes-response'
              example:
                my_custom_theme:
                  web_theme:
                    primary_color: '#FF5733'
                  ios_theme:
                    primary_color: '#FF5733'
                  android_theme:
                    primary_color: '#FF5733'
                  criteria:
                    team_ids: 30000000078001,30000000078002
                    selected: true
                ocean_blue:
                  web_theme:
                    primary_color: '#0077B6'
                  ios_theme:
                    primary_color: '#0077B6'
                  android_theme:
                    primary_color: '#023E8A'
                  criteria:
                    team_ids: ''
                    selected: false
        '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.
        '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.Organisation.READ
      tags:
        - customthemes
    post:
      summary: Create custom theme
      operationId: createCustomTheme
      description: |
        Creates a new custom theme for the organisation.
        Optionally map the theme to one or more teams and mark it as selected.
        <br><br>
        <p>
          <b>OAuth Scope</b>: ZohoCliq.Organisation.CREATE<br>
        </p>
      requestBody:
        description: Creates a custom theme. Provide `name` and platform color values without the `#` prefix - the server prepends it automatically. Optionally map <a href="/cliq/help/restapi/v2/glossary/#TEAM_ID"><code>team_ids</code></a> and set `selected`.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/create-theme-request'
            example:
              name: ocean_blue
              web_color: 0077B6
              ios_color: 0077B6
              android_color: 023E8A
              team_ids:
                - 30000000078001
                - 30000000078002
              selected: true
      responses:
        '200':
          description: The custom theme was created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/theme-value-hash-response'
              example:
                web_theme:
                  primary_color: '#0077B6'
                ios_theme:
                  primary_color: '#0077B6'
                android_theme:
                  primary_color: '#023E8A'
                criteria:
                  team_ids: 30000000078001,30000000078002
                  selected: true
        '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.
        '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.Organisation.CREATE
      tags:
        - customthemes
  /themes/{theme_name}:
    get:
      summary: Get specific theme
      operationId: getTheme
      description: |
        Returns a single custom theme by its unique `theme_name`.
        <br><br>
        <p>
          <b>OAuth Scope</b>: ZohoCliq.Organisation.READ<br>
        </p>
      parameters:
        - name: theme_name
          in: path
          required: true
          schema:
            type: string
            pattern: ^[A-Za-z0-9_]+$
          example: THEME_NAME
          description: Alphanumeric name of the theme (underscores allowed) To learn how to retrieve this ID, see <a href="/cliq/help/restapi/v2/glossary/#theme_name">theme_name</a> in the Glossary page.
      responses:
        '200':
          description: The requested custom theme was retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/get-single-theme-response'
              example:
                my_custom_theme:
                  web_theme:
                    primary_color: '#FF5733'
                  ios_theme:
                    primary_color: '#FF5733'
                  android_theme:
                    primary_color: '#FF5733'
                  criteria:
                    team_ids: '30000000078001'
                    selected: true
        '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.
        '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.Organisation.READ
      tags:
        - customthemes
    put:
      summary: Update custom theme
      operationId: updateCustomTheme
      description: |
        Updates color settings, team mapping, or selection status for an existing theme.
        Send only the fields that must be changed.
        <br><br>
        <p>
          <b>OAuth Scope</b>: ZohoCliq.Organisation.UPDATE<br>
        </p>
      parameters:
        - name: theme_name
          in: path
          required: true
          schema:
            type: string
            pattern: ^[A-Za-z0-9_]+$
          example: THEME_NAME
          description: Alphanumeric name of the theme (underscores allowed) To learn how to retrieve this ID, see <a href="/cliq/help/restapi/v2/glossary/#theme_name">theme_name</a> in the Glossary page.
      requestBody:
        description: Updates an existing custom theme. Send only fields that need to change. Provide color values without the `#` prefix - the server prepends it automatically.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/update-theme-request'
            example:
              web_color: 0077B6
              ios_color: 0077B6
              android_color: 023E8A
              team_ids:
                - 30000000078001
              selected: true
      responses:
        '200':
          description: The custom theme was updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/theme-value-hash-response'
              example:
                web_theme:
                  primary_color: '#0077B6'
                ios_theme:
                  primary_color: '#0077B6'
                android_theme:
                  primary_color: '#023E8A'
                criteria:
                  team_ids: '30000000078001'
                  selected: true
        '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.
        '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.Organisation.UPDATE
      tags:
        - customthemes
    delete:
      summary: Delete custom theme
      operationId: deleteCustomTheme
      description: |
        Deletes a custom theme from the organisation by `theme_name`.
        <br><br>
        <p>
          <b>OAuth Scope</b>: ZohoCliq.Organisation.DELETE<br>
        </p>
      parameters:
        - name: theme_name
          in: path
          required: true
          schema:
            type: string
            pattern: ^[A-Za-z0-9_]+$
          example: THEME_NAME
          description: Alphanumeric name of the theme (underscores allowed) To learn how to retrieve this ID, see <a href="/cliq/help/restapi/v2/glossary/#theme_name">theme_name</a> in the Glossary page.
      responses:
        '204':
          description: No Content. The custom theme was deleted successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NoResponse'
        '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.
        '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.Organisation.DELETE
      tags:
        - customthemes
components:
  schemas:
    NoResponse:
      type: object
      description: Response envelope for successful operations with no payload.
      properties:
        status:
          type: string
          example: success
        message:
          type: string
          example: Operation completed successfully.
    theme-value-hash-response:
      type: object
      description: The stored value_hash returned after creating or updating a theme.
      properties:
        web_theme:
          type: object
          properties:
            primary_color:
              type: string
              description: The web primary color (server-prepended `#` included).
              example: '#0077B6'
        ios_theme:
          type: object
          properties:
            primary_color:
              type: string
              description: The iOS primary color (server-prepended `#` included).
              example: '#0077B6'
        android_theme:
          type: object
          properties:
            primary_color:
              type: string
              description: The Android primary color (server-prepended `#` included).
              example: '#023E8A'
        criteria:
          type: object
          properties:
            team_ids:
              type: string
              description: Comma-separated string of mapped team IDs. To retrieve team IDs, use the <a href="/cliq/help/restapi/v2/teams/#list-all-teams">List all teams</a> API.
              example: 30000000078001,30000000078002
            selected:
              type: boolean
              description: Whether this theme is currently active.
              example: true
    get-all-themes-response:
      type: object
      description: Object keyed by theme_name, each value is a theme value_hash.
      properties: {}
      additionalProperties:
        $ref: '#/components/schemas/theme-value-hash-response'
    get-single-theme-response:
      type: object
      description: Object keyed by the requested theme_name, containing the theme value_hash.
      properties: {}
      additionalProperties:
        $ref: '#/components/schemas/theme-value-hash-response'
    create-theme-request:
      type: object
      description: Request payload for creating a custom theme. Provide color values without the `#` prefix - the server prepends it automatically.
      required:
        - name
        - web_color
        - ios_color
        - android_color
      properties:
        name:
          type: string
          maxLength: 30
          description: Name of the theme (alphanumeric + underscores, max 30 chars).
          example: ocean_blue
        web_color:
          type: string
          description: Background colour for the web client (hex value without the `#` prefix - the server prepends it).
          example: 0077B6
        ios_color:
          type: string
          description: Background colour for the iOS client (hex value without the `#` prefix - the server prepends it).
          example: 0077B6
        android_color:
          type: string
          description: Background colour for the Android client (hex value without the `#` prefix - the server prepends it).
          example: 023E8A
        team_ids:
          type: array
          maxItems: 20
          description: Team IDs to be mapped to this theme. To retrieve team IDs, use the <a href="/cliq/help/restapi/v2/teams/#list-all-teams">List all teams</a> API.
          items:
            type: integer
            format: int64
          example:
            - 30000000078001
            - 30000000078002
        selected:
          type: boolean
          description: Set to true to make this theme the active theme.
          example: true
    update-theme-request:
      type: object
      description: Request payload for updating a custom theme. Only include fields that should change. Provide color values without the `#` prefix - the server prepends it automatically.
      properties:
        web_color:
          type: string
          description: Updated background colour for the web client (hex value without the `#` prefix - the server prepends it).
          example: 0077B6
        ios_color:
          type: string
          description: Updated background colour for the iOS client (hex value without the `#` prefix - the server prepends it).
          example: 0077B6
        android_color:
          type: string
          description: Updated background colour for the Android client (hex value without the `#` prefix - the server prepends it).
          example: 023E8A
        team_ids:
          type: array
          maxItems: 20
          description: Updated team IDs to be mapped to this theme. To retrieve team IDs, use the <a href="/cliq/help/restapi/v2/teams/#list-all-teams">List all teams</a> API.
          items:
            type: integer
            format: int64
          example:
            - 30000000078001
        selected:
          type: boolean
          description: Set to true to make this theme the active theme.
          example: true
  securitySchemes:
    Cliq_Auth:
      type: oauth2
      x-authorization-example: Bearer 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f
      flows:
        implicit:
          authorizationUrl: https://accounts.zoho.com/oauth/v2/auth
          scopes:
            ZohoCliq.Organisation.READ: Read organisation settings
            ZohoCliq.Organisation.CREATE: Create organisation resources
            ZohoCliq.Organisation.UPDATE: Update organisation settings
            ZohoCliq.Organisation.DELETE: Delete organisation resources
