Threshold limit: 10 requests per min per user
Maximum API calls allowed within one minute.
Lock period: 5 minutes
Cooldown period applied after threshold exhaustion.
| Error Code | Description |
|---|---|
| extension_plan_limit_exceeded | Extension plan installation limit has been reached. |
| extension_install_restricted_non_marketplace | Organization policy restricts installing non-marketplace extensions. |
| extension_install_restricted | User is not allowed to install this extension. |
| operation_failed | General installation failure. |
scope to organization for org-wide install, or team with team_ids for team-scoped install.
content:
application/json:
schema:
$ref: '#/components/schemas/extensioninstall_V3'
examples:
install_organization:
summary: Install for entire organization
value:
scope: organization
install_team:
summary: Install for specific teams
value:
scope: team
team_ids:
- 1234567890
- 9876543210
required: true
responses:
'204':
description: Extension installed successfully. No response body.
'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.Extensions.CREATE
tags:
- Extensions
put:
summary: Upgrade an extension
operationId: update_extension
description: |
Upgrade an already-installed Cliq Extension to a newer version.
Threshold limit: 10 requests per min per user
Maximum API calls allowed within one minute.
Lock period: 10 minutes
Cooldown period applied after threshold exhaustion.
| Error Code | Description |
|---|---|
| extension_error_not_installed | Extension is not installed. |
| app_disabled_by_owner | Extension is disabled by owner/developer. |
| extension_disabled | Extension is disabled by organization admin. |
| extension_already_installed | Extension is already installed at organization scope. |
| extension_install_restricted | User is not allowed to upgrade this extension. |
| operation_failed | General upgrade failure. |
scope. Use organization to expand from team to org scope, or team to keep at team scope during version upgrade.
content:
application/json:
schema:
$ref: '#/components/schemas/extensionupgrade_V3'
examples:
upgrade_keep_team:
summary: Upgrade while keeping team scope
value:
scope: team
upgrade_to_organization:
summary: Upgrade and expand to organization scope
value:
scope: organization
required: true
responses:
'204':
description: Extension upgraded successfully. No response body.
'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.Extensions.UPDATE
tags:
- Extensions
/extensions/{EXTENSION_ID}/properties:
patch:
summary: Add or update extension properties
operationId: add_or_update_extension_proper
description: |
Add new or update existing configuration properties for an installed Extension. Extension properties are key-value pairs used to store extension-level settings (e.g. API keys, configuration flags) that are accessible to the extension's platform components. The `extension_key` parameter is required.
Threshold limit: 30 requests per min per user
Maximum API calls allowed within one minute.
Lock period: 5 minutes
Cooldown period applied after threshold exhaustion.
| Error Code | Description |
|---|---|
| extension_property_key_length_exceeded | Property key length exceeds the allowed limit. |
([a-z_]+), max 30 characters. Values accept any string - use them to store API keys, webhook URLs, region identifiers, feature flags, or any other runtime configuration your extension requires. Max 1000 characters per value. Maximum 10 properties total per extension.
content:
application/json:
schema:
$ref: '#/components/schemas/appproperties'
examples:
set_single:
summary: Set a single property
value:
properties:
api_key: my_secret_api_key_value
set_multiple:
summary: Set multiple properties
value:
properties:
api_key: my_secret_api_key_value
region: us-east
max_retries: '3'
required: true
responses:
'200':
description: Extension properties updated successfully. Returns only the properties that were added or updated in this request.
content:
application/json:
schema:
$ref: '#/components/schemas/ExtensionPropertiesUpdateResponse'
examples:
set_single:
summary: Single property set
value:
api_key: my_secret_api_key_value
set_multiple:
summary: Multiple properties set
value:
api_key: my_secret_api_key_value
region: us-east
max_retries: '3'
'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.Extensions.UPDATE
tags:
- Extensions
get:
summary: Get extension properties
operationId: get_extension_properties
description: |
Retrieve one or more application properties of an installed Extension.
Extension properties are values associated with the extension. They are quite similar to regular data properties, wherein you map a key of type string with a value string. The main purpose is to store data configurations for the extension. They can be added, retrieved for use and deleted and even the Organization admin does not have access to view these configurations. These properties should be created and updated during extension installation and used in the extension code. Cliq supports a maximum of 10 properties per extension.
Threshold limit: 30 requests per min per user
Maximum API calls allowed within one minute.
Lock period: 5 minutes
Cooldown period applied after threshold exhaustion.
| Error Code | Description |
|---|---|
| invalid_inputs | No valid property keys were supplied. |
([a-z_]+), max 30 characters per key. Maximum 10 keys per request.
required: true
- schema:
description: ''
$ref: '#/components/schemas/encryptedappkey_regex'
in: query
name: extension_key
description: Encrypted identifier for the Extension (Application). Generated when the extension is registered on the Cliq Developer Platform. Used as an authentication credential for all Extension API requests. Refer to EXTENSION_KEY in the Glossary page.
required: true
responses:
'200':
description: Extension properties returned successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/ExtensionPropertiesGetResponse'
'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.Extensions.READ
tags:
- Extensions
/extensions/{EXTENSION_ID}/properties/{EXTENSION_PROPERTY_KEY_NAME}:
get:
summary: Get a specific extension property
operationId: get_extension_property
description: |
Retrieve a single extension property of an installed extension.
Threshold limit: 30 requests per min per user
Maximum API calls allowed within one minute.
Lock period: 5 minutes
Cooldown period applied after threshold exhaustion.
| Error Code | Description |
|---|---|
| extension_property_invalid_key | Property key is invalid, empty, or does not exist. |
([a-z_]+), max 30 characters. To learn more, see EXTENSION_PROPERTY_KEY_NAME in the Glossary page.
required: true
- schema:
description: ''
$ref: '#/components/schemas/encryptedappkey_regex'
in: query
name: extension_key
description: Encrypted identifier for the Extension (Application). Generated when the extension is registered on the Cliq Developer Platform. Used as an authentication credential for all Extension API requests. Refer to EXTENSION_KEY in the Glossary page.
required: true
responses:
'200':
description: Extension property returned successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/ExtensionPropertySingleResponse'
'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:
- Extensions.READ
tags:
- Extensions
delete:
summary: Delete a specific extension property
operationId: delete_extension_property
description: |
Permanently delete a single extension property of an installed extension.
Threshold limit: 30 requests per min per user
Maximum API calls allowed within one minute.
Lock period: 5 minutes
Cooldown period applied after threshold exhaustion.
| Error Code | Description |
|---|---|
| extension_property_invalid_key | Property key is invalid or empty. |
([a-z_]+), max 30 characters. To learn more, see EXTENSION_PROPERTY_KEY_NAME in the Glossary page.
required: true
- schema:
description: ''
$ref: '#/components/schemas/encryptedappkey_regex'
in: query
name: extension_key
description: Encrypted identifier for the Extension (Application). Generated when the extension is registered on the Cliq Developer Platform. Used as an authentication credential for all Extension API requests. Refer to EXTENSION_KEY in the Glossary page.
required: true
responses:
'204':
description: Extension property deleted successfully. No response body.
'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:
- Extensions.UPDATE
tags:
- Extensions
components:
schemas:
ExtensionPropertySingleResponse:
type: object
description: Response returned when retrieving a single extension property.
properties:
api_key:
type: string
example: my_secret_api_key_value
example:
api_key: my_secret_api_key_value
ExtensionPropertiesGetResponse:
type: object
description: Response returned when retrieving multiple extension properties. Keys are property names; values are their current string values.
properties:
api_key:
type: string
example: my_secret_api_key_value
region:
type: string
example: us-east
max_retries:
type: string
example: '3'
example:
api_key: my_secret_api_key_value
region: us-east
max_retries: '3'
ExtensionPropertiesUpdateResponse:
type: object
description: Response returned after adding or updating extension properties. Contains only the key-value pairs that were submitted in the request.
additionalProperties:
type: string
example:
api_key: my_secret_api_key_value
longid_regex:
type: string
description: Numeric long integer identifier used to reference platform components such as Commands, Functions, Widgets, Message Actions, Schedulers, and Extensions.
extensioninstall_V3:
type: object
description: Payload for installing an extension.
required:
- scope
properties:
scope:
type: string
enum:
- organization
- team
description: |
Installlation scope for the extension.organization: Extension will be available to all users within the organization. Requires admin consent.team: Extension will be available only to users within specified teams. Requires admin consent for each team.team. Maximum of 4 team IDs allowed.
items:
type: integer
encryptedappkey_regex:
type: string
description: Encrypted application key (appkey or EXTENSION_KEY) issued to a bot or extension, used as an alternative to OAuth for webhook-style authentication.
extensionupgrade_V3:
type: object
description: Payload for upgrading an installed extension.
required:
- scope
properties:
scope:
type: string
enum:
- organization
- team
description: Upgrade scope for the extension.
appproperties:
type: object
description: Payload for setting extension properties.
required:
- properties
properties:
properties:
type: object
description: Map of extension property keys to values.
properties:
api_key:
type: string
example: my_secret_api_key_value
smallalphawithspl_regex:
type: string
description: Lowercase alphanumeric string with allowed special characters (hyphens and underscores) used as extension property keys.
securitySchemes:
Cliq_Auth:
type: oauth2
x-authorization-example: Bearer 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f
flows:
implicit:
authorizationUrl: ''
scopes:
ZohoCliq.Extensions.UPDATE: Update extension configurations, handlers, and properties; manage extension lifecycle.
ZohoCliq.Extensions.CREATE: Install Extensions (Applications) into an organisation or network scope.
ZohoCliq.Extensions.READ: Read extension configurations, handlers, properties, and execution logs.