Catalyst API offers a wide range of functionalities that enable an application developer to work with the Catalyst
components remotely in their application. You can build and manage your Catalyst application using the APIs, as well as perform remote operations on it, similar to working with it using the Catalyst web console.
For example, you can perform operations such as inserting data in a table in the Data Store, obtaining details of a folder in the File Store, or executing a function using the respective APIs.
Catalyst implements REST API standards, and supports HTTP requests and responses for accessing its resources. Catalyst resources are exposed through their endpoint URLs, and the HTTP clients can access these endpoints using their specific
APIs.
Catalyst implements the following basic REST API principles:
The endpoint URL of each instance of a Catalyst resource is unique.
The HTTP method in the request dictates the operation to be performed on the resource.
Additional payload information is passed as parameters in the request. They contain the details of the operation to be
performed.
Note:You can implement Catalyst functionalities in your application using the SDK provided for each programming environment. Catalyst SDKs provide better convenience and ease in your application building process, and enable you to perform all Catalyst operations that you can perform while working with the API. Refer to the SDK help documentations of the supported programming environments in Catalyst: Java SDK, NodeJS SDK, Web SDK, Android SDK, iOS SDK, Flutter SDK.
Prerequisites
Before you begin working with Catalyst API, you must ensure that the following prerequisites are satisfied:
A valid Zoho user account: Ensure that you have a valid Zoho login email address and password.
You can sign up for a Zoho account here.
An authentication token: You must obtain a valid OAuth
access_token to access Catalyst API.
The help pages in OAuth 2.0 Authentication section will guide you in the process of understanding and obtaining authentication tokens.
However, only certain operations are accessible for the users in the App User role, i.e., the end users of a Catalyst application with a Catalyst user authentication. The end user can only perform operations related to accessing specific application data, and not operations that modify the application. Each API help page will provide you with information on the execution permissions defined for it.
Note:
If you want to execute Catalyst operations without generating any authentication tokens, you can use Catalyst SDK
instead
Catalyst currently does not support a separate API authentication process for end users of Catalyst applications. If
you implement Catalyst SDK in your application code, the authentication is automatically handled as an App
Administrator authentication. To use Catalyst API independently, you must follow the steps described in th OAuth 2.0 Authentication section to generate OAuth authentication tokens.
Multi-DC Support
Overview
Catalyst is currently hosted in five data centers. The base API URI to access all Catalyst APIs and the Zoho Accounts
Server URI will be different based on the data center you are accessing Catalyst from.
You must use the appropriate domain based on your location while sending an API request in Catalyst. This prevents
conflicts with your browser and enables a smooth integration with your current session.
The five data centers and their respective base API URIs supported by Catalyst for all APIs are:
US (USA): https://api.catalyst.zoho.com
EU (Europe): https://api.catalyst.zoho.eu
IN (India): https://api.catalyst.zoho.in
AU (Australia): https://api.catalyst.zoho.au
CA (Canada): https://api.catalyst.zohocloud.ca
The corresponding Zoho Accounts Server URI for the five data centers that you must use while implementing OAuth 2.0 authentication are:
US:https://accounts.zoho.com
EU:https://accounts.zoho.eu
IN:https://accounts.zoho.in
AU:https://accounts.zoho.au
CA:https://accounts.zohocloud.ca
Usage
You must ensure you perform the following actions to make use of Catalyst’s multi-DC support:
You must use the appropriate Zoho Accounts Server URI in all the steps while implementing OAuth 2.0 authentication,
such as while making an authorization request to generate the grant token, access token, or refresh token.
A response with the grant token will be returned after redirecting to the redirect URI, which will contain a location parameter as shown below:
This location parameter specifies the domain of your account. In this case, the location is returned as eu.
* You can enable multi-DC support after you register your client in Zoho's API console. This lets you provide access to your application to users of a specific domain alone. For example, you can disable access to your application for the IN users and enable it for the other users. Refer to Register a New Client section for details.
* As mentioned earlier, you must use the appropriate base API URI while sending an API request. For example, to fetch all rows in a table in your Data Store, you must execute the following request URL for the EU data center:
`https://api.catalyst.zoho.eu/baas/v1/project/{project_id}/table/{tableIdentifier}/row`
Multi-Org Support
Overview
Catalyst allows you to create and manage multiple organizations within your Catalyst account. A unique Org ID will be generated for every organization you create. You can create individual projects in each organization and also assign access permissions to people contributing to the project.
You can only have one organization in your account as the default one. The organization marked as default will be logged in automatically when you sign in to your Catalyst account every time.
While you execute an API from Catalyst, it will be executed for the default organization automatically. For instance, when you pass the project ID in your API request, Catalyst will automatically look for a project with the same ID in your default organization. However, you can execute an API for other organizations that are not the default by exclusively passing the unique Org ID of those organizations in your requests.
Usage
You can pass the Org ID as a header in an API request to access a project in that organization in this format:
Sample API Header Format
copy
-H CATALYST-ORG: 15090237
You can check a complete sample request from the Request Format section.
Request Format
Request Methods
Catalyst API follows the REST standards and supports the following HTTP methods for client requests for the described
purposes:
GET : To fetch records from a Catalyst resource
POST : To insert new records in a Catalyst resource
PUT : To update existing records in a Catalyst resource
DELETE : To delete existing records in a Catalyst resource
You must specify the request method for the operation while executing a Catalyst API request.
Request URL
The API requests are sent in the CURL format. A typical request URL is of the format:
Note: The base API URL will be the following for the other data centers:
EU:https://api.catalyst.zoho.eu
IN:https://api.catalyst.zoho.in
AU:https://api.catalyst.zoho.au
CA:https://api.catalyst.zohocloud.ca
The common parameters passed in the request URL include the
Project ID of the Catalyst project and the resource ID of the specific resource instance that is being accessed.
Request Headers
Mandatory header passed in the cURL request includes the following:
Authorization header: OAuth token i.e., the access_token
Recommended headers passed in the cURL request can include the following:
Content-Type: A REST API standard that indicates the original media type of the resource passed. It is highly recommended to pass this header when the API requests include JSON payload or form data, for example.
Optional headers passed in the cURL request can include the following:
Org ID: The Org ID of an organization that is not the default. You can obtain the Org ID from the multi-org portal in the Catalyst console.
Note: If you do not pass an Org ID in your request explicitly, the API will be executed for the default organization.
Environment: The environmental header to specify the environment the request must be executed for. You can indicate if the API request should be executed for the development or production environment of the project.
Note: If the project has been deployed to the production environment, then by default the API request will be executed for production, unless you specifically point to development using this header. If the project is not available in production, all API requests will be executed in the development environment automatically.
Request Body
Based on the purpose of the request, you can pass additional data in the body of the request in an API call, such as the column name and value for updating the column of a table, or the folder name for creating a folder.
The particulars of the request to be sent, such as the headers and JSON attributes to be passed in the request, are specified in each API help page for the specific request.
All Catalyst API responses will be in the JSON format. The response is sent after a request is processed by the Catalyst
server.
A typical response contains the status of the request processing, which can be success or
failure, and a set of data based on the request made. For example, if the request was made to
delete a record in a resource, the data will contain the details of the record that was deleted. The response details of
each API are specified in its help page in detail.
If the request was not processed successfully, the response will contain an appropriate error code to specify the error
that occurred. The next section contains the error codes recognized by Catalyst and their descriptions.
When the server encounters an error while processing a client request, it sends an appropriate HTTP Status Code in the
response back to the client. The following errors are recognized by Catalyst:
HTTP Status Code
Error Code
Description
403
API_LIMIT_REACHED
You have reached the upper limits for API calls in your account. Upgrade your license plan.
409
CONFLICT
Contradicts with the existing value. Try giving another value.
409
DUPLICATE_ENTRY
The email ID you have entered already exists. Please provide a different email ID.
409
DUPLICATE_ENTRY
The domain name already exists. Please provide a different value.
409
DUPLICATE_OPERATION
The requested operation is already under progress. Please wait until it is completed.
409
DUPLICATE_VALUE
The value you have entered already exists. Please provide a different value.
500
EMAIL_ERROR
Email sending process failed. Try again after some time.
410
EXPIRED
The requested resource has expired. Please try creating it again.
410
EXPIRED_LOG
The response log you are trying to download is expired.
202
FUNCTION_ERROR
Encountered an internal server error.
500
INTERNAL_SERVER_ERROR
Encountered an internal server error.
403
INVALID_CONTENT
The given input is not in an acceptable format.
404
INVALID_ID
The resource ID you have provided does not exist.
400
INVALID_INPUT
The table name you have provided does not exist.
400
INVALID_INPUT
The column name you have provided does not exist.
400
INVALID_INPUT
The foreign key you have provided doesn't match with the ROWID of the parent table.
400
INVALID_INPUT
The input you have provided is not valid.
404
INVALID_NAME
The email ID you have provided does not exist.
404
INVALID_NAME
The table name you have provided does not exist.
403
INVALID_OPERATION
The requested operation is invalid.
405
INVALID_REQUEST_METHOD
The requested method is not accepted.
400
MISMATCH
The value provided does not match with the expected one.
400
MISSING_FUNCTION
The function ID you have provided does not exists.
400
MISSING_VALUE
The expected input is missing.
401
NO_ACCESS
You don't have privileges to perform this action
204
NO_CONTENT_AVAILABLE
The request returned an empty response.
401
UNAUTHORISED
You are not authorized to perform this action.
403
VERIFICATION_NEEDED
Your email address needs to be verified.
400
ZCQL_QUERY_ERROR
The format of your query is invalid.
429
TOO_MANY_REQUESTS
Concurrency limits reached for function, web client, or a Catalyst component execution.
OAuth 2.0 Authentication
Overview
OAuth 2.0 is an industry-standard protocol for authentication and authorization. The framework enables a host of third-party client applications to gain secure and delegated access to protected resources in Zoho through APIs.
Some common characteristics of OAuth 2.0 are:
Clients are not required to support password authentication or store user credentials. API calls can be made to access
resources without having to provide user credentials for each call.
Clients will only have access to resources authenticated by the user.
Users can revoke the client’s delegated access at any time.
OAuth2.0 access tokens expire after a set time, which provides strong security.
Terminology
Before you learn about the steps involved in implementing OAuth 2.0, you must understand the following terms related to
OAuth 2.0 in the Catalyst context:
Key Words
Description
Protected Resource
A Catalyst resource such as Cache, Cron, Table, or Folder
Resource Server
The Catalyst server that hosts the Catalyst protected resources
Client
An application that sends requests to the resource server to access the protected resources on behalf of the end-user
client_id
The unique key generated for a registered client
client_secret
The secret value generated for a specific registered client's client_id. When you register your Catalyst application in the Zoho API Console, a client_id and client_secret will be generated for it.
Authentication Server
The Catalyst authorization server that provides the necessary credentials to a client, such as the access_tokenor refresh_token
Grant Token orcode
Catalyst authorization server generates a temporary token and sends it to the client via the browser. The client will send this code back to the authorization server to obtain the access and refresh tokens.
access_token
A temporary token that is sent to the resource server to access the protected resources of the user. Clients use the access_token to make requests to the associated application using the APIs. Each access_token will be valid for a set time period and can only be used to perform operations described in the scope.
refresh_token
A token that can be used to obtain new access tokens. This token has an unlimited lifetime until it is revoked by the end-user.
Scopes
Scopes control the type of resources that the client application can access. Each token is usually created with selected scopes for better security. For example, you can generate an access_token with a scope to only read the data in the Data Store or File Store.The standard format to define a scope is scope=service_name.scope_name.operation_type. The next section lists the scopes available in Catalyst.
The first step towards obtaining an OAuth authentication token is to register your application with Zoho’s API console
and obtain your client_id and client_secret.
To register your application, visit the Zoho API Console and click Get Started.
2. Select a client type for your application. You can refer to Zoho’s OAuth documentation for more details.
Note: You can choose the Self Client type to test the client-server handling for your application, or if your application does not have a domain. You need not provide any details for this type. You can only create one Self Client client for your user account.
Provide the required details to register your application for the client type you chose.
* Client Name: The name of your application you want to register with Zoho
* Homepage URL: The URL of your client's homepage
* Authorized Redirect URIs: A valid URL of your application that Zoho Accounts redirects you to with the grant token after a successful authentication
4. Click Create.
After the registration is successful, Zoho will provide you a set of OAuth 2.0 credentials: the client_id and client_secret, which are known to both Zoho and your application.
Note: You must not share the client_id and client_secret anywhere. Ensure that you keep these credentials safe.
Enable Multi DC for the Client
As mentioned in the Multi-DC Support section, you can enable multi-DC support for your client from the Settings tab in the API console after you register it. This is available for all client types, except the Self Client type as it is used only for testing.
This feature lets you provide access to your application to users of a specific domain alone. As mentioned earlier, Catalyst is currently available in the EU, AU, IN, and CA domains. So you can enable or disable access to your application for specific DC users if you need.
To access the multi-DC configurations for your client:
Open your client from the API console and click Settings.
2. Enable or disable the client access for the data centers you need. You can only avail the data centers that Catalyst supports.
When you enable a DC, the console will generate a different client_secret for them by default. You can access it by clicking Show Code for the respective DC. The client_id will remain the same for all DCs.
You can choose to have the same client_secret for all DCs by checking the Use the same OAuth credentials for all data centers checkbox. You must then click OK in the confirmation pop-up.
You can again unselect the checkbox to have a different client_secret, and confirm the action similarly.
Step 2: Generate Grant Token
After you generate the client_id and client_secret, you must generate a Grant Token or code for your application.
Note: Generating a Grant Token is a one-time process, provided you generate the access_token and refresh_token within the time the Grant Token is valid for.
For Self Client Applications
If you previously selected the Self Client type, you must generate the Grant Token (code) in
the following way:
After registering your application, select Self Client from the Applications list in the
API console and click Generate Code.
2. Enter a valid scope. You can check the list of scopes available in Catalyst from this section.
3. Choose a time duration from the dropdown list. The Grant Token generated in this step will expire after this time period.
Note: If the Grant Token is about to expire, you must generate a refresh_token before it expires, as described in the next step.
Enter a description for the scope.
Click Generate.
The API console will display the generated Grant Token or code value for your Self Client application.
For Other Applications
If you previously selected client types other than the Self Client type, you must generate the Grant Token using a redirect method:
Send a request to the following URI with the params given below, to generate the Grant Token (code):
https://accounts.zoho.com/oauth/v2/auth?
Note: You must access the respective domains for the other data centers:
EU:https://accounts.zoho.eu/
AU:https://accounts.zoho.au/
IN:https://accounts.zoho.in/
CA:https://accounts.zohocloud.ca/
Parameter
Description
scope*
The scope the Grant Token is to be generated for. You can provide multiple scopes by separating them using commas. You can check the list of scopes available in Catalyst from [this section](/en/api/oauth2/scopes/#Scopes).
client_id*
The Client ID that was generated during the client registration
state
An opaque string that is round-tripped in the protocol, i.e., whatever value you provide here will be passed back to you
response_type*
code(Provide this literal string as the value)
redirect_uri*
One of the Authorized Redirect URIs you provided while registering the client in the previous step. You must not provide an unregistered redirect URI.
access_type
The allowed values are offline and online. The online access_type only provides the Access Token for your application, which is valid for one hour. The offline access_type provides an Access Token as well as a Refresh Token for your application. The default value is considered to be online.
prompt
Consent (Provide this literal string as the value) Prompts for user consent every time your app tries to access user credentials. If you don't specify this parameter, the user will only be prompted for credentials the first time your app requests access.
Note:
Fields marked with * are mandatory.
You can pass the parameters in the body of your request as form-data, for increased security.
If you send the prompt parameter in this request, a user consent page will open. After you click Accept, Zoho will redirect you to the redirect_uri with the Grant Token in the code parameter. Save the code value for the next steps.
Based on your login details, the system automatically detects your domain and uses the domain-specific authentication URL to generate the Grant Token. The state parameter is also passed in the URL. If you click Reject, the browser redirects to the redirect URI with the parameter error=access_denied.
Note: This code is only valid for 60 seconds. You must complete the next step within this time.
Step 3: Generate Access Token and Refresh Token
Request Execution
After you obtain the Grant Token, send a POST request to the following URL with the params given
below to generate the access_token:
https://accounts.zoho.com/oauth/v2/token?
Note: You must access the respective domains for the other data centers:
EU:https://accounts.zoho.eu/
AU:https://accounts.zoho.au/
IN:https://accounts.zoho.in/
CA:https://accounts.zohocloud.ca/
Parameter
Description
code*
The Grant Token or the value of code obtained in the previous step.
client_id*
The Client ID that was generated during the client registration
client_secret*
The Client Secret that was generated during the client registration
grant_type*
authorization_code (Provide this literal string
as the value)
redirect_uri
One of the Authorized Redirect URIs you provided while registering the
client in the previous step. You must not provide an unregistered
redirect URI.
scope
The scope the access_token is to be generated
for. You can provide multiple scopes by separating them using commas. You
can check the list of scopes available in Catalyst from [this
section](/en/api/oauth2/scopes/).
state
An opaque string that is round-tripped in the protocol. In other words,
whatever value you provide here will be passed back to you.
Note:
Fields marked with * are mandatory.
You can pass the parameters in the body of your request as form-data, for increased security.
The access_token will expire after the time period (in seconds) mentioned in the
expires_in parameter.
However, the refresh_token is permanent and can be used to regenerate a new
access_token if the current one expires.
You can use the domain specified in api_domain in your requests to make API calls to Catalyst.
The “Bearer” value in the token_type indicates this is an
access_token.
This completes the authentication process. Once you obtain the access_token for your
application, you can use it in the authorization header of your HTTP requests to access Catalyst APIs. You can refer to the Request Format section for an example.
Note: Each time a re-consent page is accepted, a new refresh_token is generated. You can generate a maximum of 20 refresh tokens per user, and 5 refresh tokens in a minute. If this limit is crossed, the first refresh_token is automatically deleted to accommodate the latest one. This is done irrespective of whether the first one is in use or not.
The Project APIs enable you to create, update, delete, and obtain details of a Catalyst project. You can perform these actions from the Catalyst console as well. Catalyst CLI also enables you to create a project remotely and initialize resources in it.
Create a New Project
Description
This API enables you to create a new Catalyst project in your Catalyst account. You must pass the required project name in the request.
Note: You can create upto 50 projects in your account in the development environment. You can request Catalyst for an increase in this limit by contacting our support at support@zohocatalyst.com. We will address each request on a case-by-case basis. There are no upper limits for project creation in the production environment.
Unique name of the project Max Size: 50 characters
Response Details
The response will contain the details of the project that was created including the project domain details such as the project_domain_id and project_domain_name, and the details of the user such as their email_id and user_id.
This API enables you to fetch the details of a specific project that the Catalyst user, such as the developer or a collaborator, logged in currently has created from their Catalyst account. The project is referred to by its project_id. The project details fetched are of the same Catalyst account the API is being executed from.
The response will contain the details of the project including the project domain details such as the project_domain_id and project_domain_name, and the details of the user that created it, such as their email_id and user_id.
This API enables you to fetch the details of all the projects in the remote console of the Catalyst user, such as the developer or a collaborator, logged in currently. The project details fetched are of the same Catalyst account the API is being executed from.
Request Details
Request URL
GET
{api-domain}/baas/v1/project
copy
api-domain
URL
The DC-specific domain to access Catalyst API
Request Headers
Authorization: Zoho-oauthtoken {oauth_token}
Optional Headers
CATALYST-ORG: {org_id}
Environment: Development
Scope
ZOHOCATALYST.projects.Read
Response Details
The response will contain the details of all the projects the user created in their remote console, including the project domain details such as the project_domain_id and project_domain_name, and the details of the user that created it, such as their email_id and user_id of each project.
Catalyst Functions enable you to build custom functionalities in your application, and seamlessly integrate it with other Catalyst components to provide a powerful backend for it. You can automate tasks, perform memory-intensive computations, or integrate with third-party services using functions.
Catalyst offers support to develop server-side functions in Java, Node.js and Python programming environments.
Note: You can create six types of functions in Catalyst: Basic I/O, Advanced I/O, Cron, Event, Integration, and Browser Logic functions. However, you can only execute Basic I/O functions using this API.
Execute a Function
Description
This API enables you to execute a Basic I/O function by referring to its unique function ID. Basic I/O functions are used to perform basic input and output operations, computations, and simple HTTP operations.
Input parameters can passed to the function in the API request either as a query string or in the request body. A query string is preferred over the request body to pass the function parameters in. The response will contain the function output.
Note: This operation can also be executed with Catalyst user authentication permissions using Catalyst SDKs. Refer to the Catalyst API Prerequisites section for details.
Response Details
The response contains the output of the processed function. A Basic I/O function returns response in the JSON format. The key output contains the output generated by the function you execute.
Catalyst Circuits enable you to systematically define and organize a sequence of tasks to be carried out automatically in Catalyst. You can orchestrate tasks and automate workflows, and additionally include conditions, data, and paths in the workflow, to define a repeatable pattern of activities that achieves a business outcome using Circuits.
Catalyst offers support for automating the execution of Basic I/O functions of your application using a circuit.
Note: Circuits is currently not available to Catalyst users accessing from the EU, AU, IN, or CA data centers.
Execute a Circuit
Description
This API enables you to execute a Catalyst circuit configured in the console by referring to its unique Circuit ID. You can pass the input to the circuit in the request JSON as described below.
Note: The circuit input is not mandatory. You can skip the input or pass it based on your circuit’s purpose and logic.
Response Details
The response contains the result and the details of the executed circuit, such as the circuit_name, the start_time and end_time of the execution, the instance_id, along with the details of the input that was passed to the circuit and the output generated from the circuit’s execution.
Catalyst Authentication features enable you to add end-users to your Catalyst serverless applications, configure their user accounts and roles, and manage user sign-in and authentication of your application.
Add a New User
Description
This API enables you to add a new end-user to the Catalyst application for a specific platform. When the user has signed up, unique identification values such as ZUID, userID are created for them.
Note: You will be able to add only 25 users in your application in the development environment. After you deploy your application to production, you can include any number of end-users in it.
The URL to be redirected to, after the user signs up for the application Max Size: 200
user_detailsjsonmandatory
The JSON that contains the details of the user
first_namestringmandatory
First name of the user Max Size: 100
last_namestringoptional
Last name of the user Max Size: 100
email_idstringmandatory
Email address of the user
Response Details
The response will contain the details of the user added in the data key, including the metadata and identification values such as zaid, user_id, and org_id that were generated.
This API enables you to add a new end-user to an existing organization without creating a new organization for them. This can be done by providing the ZAAID of the organization that the user must be added to. The organization of a user cannot be changed later, once it is associated with their account.
When the user has signed up, unique identification values such as ZUID and User ID are created for them.
The URL to be redirected to, after the user signs up for the application Max Size: 200
user_detailsjsonmandatory
The JSON that contains the details of the user
first_namestringoptional
First name of the user Max Size: 100
last_namestringmandatory
Last name of the user Max Size: 100
email_idstringmandatory
Email address of the user
ZAAIDstringmandatory
Unique identification of the organization that the user belongs to
Response Details
The response will contain the details of the user added in the data key, including the metadata and identification values such as zaid, user_id, and org_id that were generated.
Note: This operation can also be executed with Catalyst user authentication permissions using Catalyst SDKs. However, the user can only obtain their own user details. Refer to the Catalyst API Prerequisites section for details.
Response Details
The response will contain the details of the current user including their identification values such as zaid, user_id, email_id, and their role details.
The response will contain the details of the specific user including their identification values such as zuid, user_id, email_id, and their role details.
This API enables you to fetch the details of all Catalyst applications users of a particular application through Pagination. Pagination allows you to retrieve the user list in pages through an iteration of API calls.
For example, if you require user records to be fetched in batches of 200 as individual pages, you must include a start and an end parameter in your request. You can set the start index as 0 using the start parameter, and specify the maximum number of users to be fetched as 200 using the end parameter. To fetch the next set of user records, you can execute another API call by setting the start index as 200, and specifying the number of user records in that page using the end parameter accordingly.
Number of user records to return in a single page through pagination
Request Headers
Authorization: Zoho-oauthtoken {oauth_token}
Optional Headers
CATALYST-ORG: {org_id}
Environment: Development
Scope
ZohoCatalyst.projects.users.READ
Response Details
The response will contain the details of all application users including their identification values such as zuid, user_id, email_id, and their role details.
The unique User ID of the user generated by Catalyst
Request Headers
Authorization: Zoho-oauthtoken {oauth_token}
Optional Headers
CATALYST-ORG: {org_id}
Environment: Development
Scope
ZohoCatalyst.projects.users.DELETE
Note: This operation can also be executed with Catalyst user authentication permissions using Catalyst SDKs. However, the user can only obtain their own user details. Refer to the Catalyst API Prerequisites section for details.
Response Details
The response will contain the details of the deleted user including their identification values such as zaid, user_id, email_id, and their role details.
This API enables you to reset the password of a user of your Catalyst application. When this API is called, an email will be sent to the user’s email address with a password reset link. The user can configure a new password for your application and save it, upon clicking the link.
A Catalyst application user can log out from their current active session in the application using this API request. Catalyst will not send any response back for this API request.
Catalyst Data Store is a cloud-based relational database management system which stores the persistent data of your application in the form of tables.
Data Store APIs enable you to insert and manage records in the tables of your project’s Data Store, obtain table and column details, and even perform bulk read and bulk write actions. However, you can create a table and its schema only from the Catalyst console.
Insert a New Row In a Table
Description
This API enables you to insert a new row of data or a record in a table in the Data Store, by referring to the table’s unique ID or name.
You must pass the column names and their corresponding values for the record in a JSON array in the request as described below.
Note:
The table and the columns in it must already be created. You can create a table and the columns for it from the console.
You will be able to insert upto 5000 records in each table per project in the development environment. You can create upto 25,000 records overall in each project in the development environment. There are no upper limits for record creation in the production environment.
Note: This operation can also be executed with Catalyst user authentication permissions using Catalyst SDKs. Refer to the Catalyst API Prerequisites section for details.
Request JSON Array
You must send the column names and their corresponding values in a JSON array like this:
where column_name is the name of a unique column in the table, and column_value is its corresponding value in the record.
Note: You must send at least one column name and value pair to insert in the record.
Response Details
The response will contain the metadata of the row that was created such as its ROWID and CREATEDTIME, and the column key names and values that were inserted.
This API enables you to fetch all the rows from a particular table in the Data Store. You can refer to the table by its ID or name. The API incorporates pagination for fetching all rows. Pagination allows you to retrieve the records in pages through an iteration of API calls.
For example, if you require the rows to be fetched in batches of 100 as individual pages, you must include a max_rows parameter in your request, that specifies the maximum rows to be fetched in each page as 100.
Additionally, every API response will contain a token that you can pass in the next API call, to fetch the next page of rows. This token authorizes the subsequent fetching of data. You must pass the token string obtained in the response of the previous API call through the next_token parameter in the request. You need not pass the next_token parameter for the first API call. You can execute an API call for each iteration in this manner and fetch all rows in pages.
(not required for the first API call) The token value obtained from the previous API call to be passed for fetching the next set of rows through pagination
max_rows
Numerical
(optional) The maximum number of rows that must be returned in a single page through pagination. The API will return 200 rows in a single page by default if this value is not specified.
Request Headers
Authorization: Zoho-oauthtoken {oauth_token}
Optional Headers
CATALYST-ORG: {org_id}
Environment: Development
Scope
ZohoCatalyst.tables.rows.READ
Note: This operation can also be executed with Catalyst user authentication permissions using Catalyst SDKs. Refer to the Catalyst API Prerequisites section for details.
Response Details
The response will return the rows that are fetched through the API call in pages based on the max_rows value you specify. If there are rows available more than the requested count or the max_rows count, the response will also contain the token that you must pass to fetch the next set of rows as next_token. If there are no more records to be fetched, the response will not contain a token.
This API enables you to update a particular row in a table in the Catalyst Data Store, by referring to its table ID or the table name. You must send the data to be updated in the record in the request JSON as described below.
Note: This operation can also be executed with Catalyst user authentication permissions using Catalyst SDKs. Refer to the Catalyst API Prerequisites section for details.
Request JSON Format
You must send the names of the columns and their corresponding values to be updated in the request, along with the ROWID of the record, as a JSON Array like this:
copy
{
“column1_name”: “column1_value”,
“column2_name”: “column2_value”,
“column3_name”: “column3_value”,
.
.
“ROWID”:{row_id of the record}
}
Request JSON Properties
column_namestringmandatory
Specifies the column name of the specified table
column_valuestringmandatory
Specifies the value for the column
ROWIDbigintmandatory
The ROWID of the record to be updated
Response Details
The response will contain the metadata of the row that was updated such as its ROWID and CREATEDTIME, and the updated column key names and values.
This API enables you to delete a particular record or a row of a table in the Data Store, by referring to the table’s unique ID or name. The row is referred by its ROWID.
Note: This operation can also be executed with Catalyst user authentication permissions using Catalyst SDKs. Refer to the Catalyst API Prerequisites section for details.
Response Details
The response will contain the metadata of the row that was deleted such as its ROWID and CREATEDTIME, and the column key names and values in the row.
The response will return the metadata of the table which will include the table details such as the table_id and table_name, and the metadata of all the columns in it such as the column_id, column_name, and data_type of each column.
The response will return the metadata of all the tables which will include the table details such as the table_id and table_name of each table, and the details of the user that last modified the tables.
This API enables you to retrieve the metadata of a specific column in a table in the Data Store. The table is referred by its unique ID or name, and the column is referred by the column ID.
This API enables you to truncate a specific table in the Data Store, by referring to the table’s unique ID or name.
The truncate operation deletes all the records in the table, while retaining its schema. The columns of the table and the table’s metadata will still be available, after the operation has ended.
You will receive notifications in your Catalyst console about the updates of the operation.
{
"status": "success",
"data": "The table will be truncated Shortly. Kindly Check Notification bar for updates"
}
Bulk Read Records
The Bulk Read operation can read thousands of records from a specific table in the Data Store and generate a CSV file containing the results of the read operation, if the job is successful. This data-intense operation can be performed in a single API execution.
Catalyst supports three APIs for the bulk read operation: a Create Bulk Read API, a Check Bulk Read Status API to check the status of the job execution manually, and a Download Bulk Read Result API to download the results. You can also configure a callback URL to enable the automatic posting of the job status responses in it.
This API triggers the bulk read operation to obtain the records from the table in the Data Store, that match the criteria you specify in the input JSON. The table is referred to using its unique table ID or the table name.
The input for the Bulk Read API request must be sent in a JSON format. The request parameters are explained below.
table_identifierstringmandatory
The unique ID of the table or the table name. You can obtain the table ID from Data Store or from the URL when the table is opened in the console.
queryjsonoptional
The section where you can define the conditions and criteria for the bulk read job
pagenumericaloptional
The CSV file generated as the result of the bulk read process contains two hundred thousand/two lakh records in one page.
Page value ‘1’ indicates that the first two hundred thousand records matching your query will get exported. You can fetch subsequent records by increasing the page value.
For example, if you want to fetch records from the range 2,00,001 to 4,00,000, then you must specify the page value as ‘2’.
Default value: 1
select_columnsarrayoptional
Specific columns in the records that need to be fetched from the table. If you do not specify the columns, all columns will be selected and fetched.
You can include multiple columns in an array. Refer to the sample request code window.
criteriajsonoptional
A set of conditions based on which the records will be fetched
The operator that will bind the criteria groups together.
Supported Operators: AND, OR
If you define two or more criteria groups, you can use the AND or the OR operator in your request. For example, you can specify a criteria like “column1 equal value 1 AND column2 contains value 2” in the format specified in the previous section.
Note: You will not be able to use combinations of both the operators in a single API request. You can either use AND or OR in one request.
groupjsonmandatory (if specifying criteria)
You can include upto 25 criteria sets in this section. The example shows 3 criteria sets.
Note: You can include only one overall group with one group operator in a single API request.
You can specify multiple values for in and not_in comparators, separated by commas.
Catalyst supports only the equal comparator for an encrypted column. You will not be able to use other comparators as the criteria for an encrypted column.
valuestringmandatory (if specifying criteria)
The value for the specific column in the record that you require to be defined as a criteria
callbackjsonoptional
The section where you can define the properties of the callback URL, where automatic JSON responses of the job statuses will be sent to
urlstringmandatory (if specifying callback)
The URL where the automatic responses will be sent to using the HTTP POST method, each time the job status changes. Information about the job details will be contained in the body of the JSON response.
If you don’t configure a callback URL, you must manually check the status of the job processing when you need, using the Check Bulk Read Status API.
headersstringoptional
Headers that you require to be passed in the JSON response to the callback URL.
You must specify the headers as: { "{header_name_1}" : “{header_value_1}”, "{header_name_2}" : “{header_value_2}” }
and so on. Refer to the sample request code.
paramsstringoptional
Parameters that you require to be appended to the callback URL
You must specify the parameters as: { "{param_name_1}" : “{param_value_1}”, "{param_name_2}" : “{param_value_2}” }
and so on. Refer to the sample request code.
Response Details
There are three job processing states which will generate three different responses:
In-Progress: When you execute the API, Catalyst will immediately and automatically send you a response indicating that the job execution is in progress. If you have configured a callback URL in the request, the response will also be posted to the URL in the format you defined.
The response will contain a job_id parameter which you can use to check the status of the job execution for subsequent responses, if you have not configured a callback URL.
Success: The success state response will contain a download URL, where you can download a CSV file that contains the records matching your query. If you have not configured a callback URL, this response will not be sent by Catalyst automatically.
Failed: The failed state response will contain a description of the error occurred and the details. If you have not configured a callback URL, this response will not be sent by Catalyst automatically.
You can execute this API to manually check the status of the bulk read job that you initiated previously.
If you had not configured a callback URL in your JSON request, you must check the job status yourself by executing this API. You must use the job_id that is sent to you in the automatic in-progress response when you initiate the bulk read operation, to check the job status subsequently.
The unique ID of the job that was sent in the initial in-progress status response after the Bulk Read API was executed
Request Headers
Authorization: Zoho-oauthtoken {oauth_token}
Optional Headers
CATALYST-ORG: {org_id}
Environment: Development
Scope
ZohoCatalyst.tables.bulk.READ
Response Details
The JSON response for the success state will contain the details of the executed job, along with a download URL where you can download a CSV file that will contain a list of records matching your bulk read job query.
The JSON response for the failed state will contain the details of the executed job, along with a description of the error the occurred in the job processing, and its details, such as the rows that were skipped from being read and the reasons.
You can execute this API to download the result of a successful bulk read job that you initiated. This URL will also be sent in JSON response for the success state.
The downloaded CSV result file will contain a list of all the records matching your bulk read job query.
Note: The download URL will be valid for 1 day after its generation. The link will expire after that time period, and you will not be able to obtain the CSV result file containing the job details.
The Bulk Write operation can fetch thousands of records from a CSV file uploaded in the File Store and insert them in a specific table in the Data Store. This data-intense operation can be performed in a single API execution.
After the bulk write operation has executed successfully, a CSV report file containing the details of the job execution will be generated at a download URL.
Catalyst supports three APIs for the bulk write operation: a Create Bulk Write API, a Check Bulk Write Status API to check the status of the job execution manually, and a Download Bulk Write Result API to download the results. You can also configure a callback URL to enable automatic posting of the job status responses in it.
This API triggers the bulk write operation to obtain the records from a CSV file in the File Store and export them to a table in the Data Store, based on the criteria you specify in the input JSON. The CSV file is referred to using its File ID in the File Store, and the table is referred to using its unique table ID or the table name.
Note:
You must upload the CSV file containing the data in the File Store, before you begin executing this operation.
The CSV file’s first row must be the header row i.e., the column names must be present as the header row.
The CSV file must contain data in the format that adheres to CSV file standards. If the file is not in the standard format, the data written to the table might be corrupted.
You can insert 5000 records in each table per project in the development environment using this API. If the CSV file contains records more than that, the first 5000 records will be written to the table. The others will be skipped in the development environment. There are no table limits for insertion in the production environment. However, the Bulk Write API can insert upto 100000 records in a single API call from a CSV file even in the production environment. If you require more records to be written, you can do so in batches of 100000 records by sending multiple Bulk Write API requests accordingly.
There are three operations that can be performed using this API:
Insert: Inserts new rows of data into the table from the CSV file
Update: Updates existing rows of data in the table. The records are identified either using a unique column in the table, or using their ROWIDs generated in the Data Store.
Upsert: Enables both insert and update operations at the same time. If the record already exists, the row is updated. If the record does not exist, a new row with the data is inserted.
The unique column using which the records are identified.
For example, if you specify a unique column called ‘EmployeeID’ as the find_by value, Catalyst will search the records in the Data Store table using the EmployeeID value. For the update operation, Catalyst will update the rows that match the EmployeeID from the CSV file. For the upsert operation, Catalyst will update existing rows, and insert new rows if there are no records with matching EmployeeID values.
Update: This can be a column with unique values as configured in the Data Store, or the ROWID generated by Catalyst for the records.
Upsert: You can only specify a column with unique values as configured in the Data Store. You will not be able to specify the ROWID as the find_by value. This is because, upsert will insert new rows if matching ones are not found, and the ROWID values will not be available for rows not existing in the Data Store.
Insert: If you specify a find_by column for an insert operation, any records matching the column values from the CSV file will be skipped and not inserted into the Data Store table. This is because, insert cannot update if a given record already exists.
fk_mappingjsonoptional
Foreign key mapping for the columns that are primary keys in other tables. This is specified if any columns imported from the CSV file should be configured as foreign keys.
You must map foreign keys in the following format: { “local_column” : “local_column_name_1”, “reference_column” : “reference_column_name_1” }
where local_column is the name of the column in the table where the bulk write operation is processed, and reference_column is the name of the column in the table in which it is a primary key.
Refer to the sample request code.
callbackjsonoptional
The section where you can define the properties of the callback URL, where automatic JSON responses of the job statuses will be sent to.
urlstringmandatory (if specifying callback)
The URL where the automatic responses will be sent to using the HTTP POST method, each time the job status changes. Information about the job details will be contained in the body of the JSON response.
If you don’t configure a callback URL, you must manually check the status of the job processing when you need, using the Check Bulk Write Status API.
headersstringoptional
Headers that you require to be passed in the JSON response to the callback URL
You must specify the headers as: { "{header_name_1}" : “{header_value_1}”, "{header_name_2}" : “{header_value_2}” }
and so on. Refer to the sample request code.
paramsstringoptional
Parameters that you require to be appended to the callback URL
You must specify the parameters as: { "{param_name_1}" : “{param_value_1}”, "{param_name_2}" : “{param_value_2}” }
and so on. Refer to the sample request code.
Response Details
There are three job processing states which will generate three different responses:
In-Progress: When you execute the API, Catalyst will immediately and automatically send you a response indicating that the job execution is in progress. If you have configured a callback URL in the request, the response will also be posted to the URL in the format you defined.
The response will contain a job_id parameter which you can use to check the status of the job execution for subsequent responses, if you have not configured a callback URL.
Success: The success state response will contain a download URL, where you can download a CSV report file that contains the details of the job execution. It will list all the records that were skipped from being written along with the reasons. If you have not configured a callback URL, this response will not be sent by Catalyst automatically.
Failed: The failed state response will contain a description of the error that occurred and the details. If you have not configured a callback URL, this response will not be sent by Catalyst automatically.
You can execute this API to manually check the status of the bulk write job that you initiated previously.
If you had not configured a callback URL in your JSON request, you must check the job status yourself by executing this API. You must use the job_id that is sent to you in the automatic in-progress response when you initiated the bulk write operation, to check the job status subsequently.
The unique ID of the job that was sent in the initial [in-progress status response](/en/api/introduction/overview-and-prerequisites/#response-details) after the Bulk Write API was executed
Request Headers
Authorization: Zoho-oauthtoken {oauth_token}
Optional Headers
CATALYST-ORG: {org_id}
Environment: Development
Scope
ZohoCatalyst.tables.bulk.CREATE
Response Details
The JSON response for the success state will contain the details of the executed job, along with a download URL, where you can download a CSV report file that will contain the details of the job execution. It will list all the records that were skipped from being written along with the reasons.
The JSON response for the failed state will contain the details of the executed job, along with a description of the error occurred in the job processing, and its details.
You can execute this API to download the result of a successful bulk write job that you initiated. This URL will also be sent in JSON response for the success state.
The downloaded CSV file will contain the details of the job execution. It will list all the records that were skipped from being written along with the reasons.
Note: The download URL will be valid for 1 day after its generation. The link will expire after that time period, and you will not be able to obtain the CSV result file containing the job details.
The unique ID of the job that was sent in the initial [in-progress status response](/en/api/introduction/overview-and-prerequisites/#response-details) after the Bulk Write API was executed
Request Headers
Authorization: Zoho-oauthtoken {oauth_token}
Optional Headers
CATALYST-ORG: {org_id}
Environment: Development
Scope
ZohoCatalyst.tables.bulk.CREATE
Response Details
The bulk write result file will be automatically downloaded to the configured directory in your system after you execute this API.
File format: ZIP file containing the CSV result file
Sample result file showing the details of a bulk write job:
This API enables you to delete records or rows of data in bulk from a specific table in the Data Store. The table is referred by its unique ID or name.
The bulk delete operation can delete a maximum of 200 rows in a single API call. You can choose the rows to be deleted by passing the unique ROWIDs of those rows as params in the request URL, as shown in the sample request.
You must include at least one ROWID, and can include upto 200 ROWIDs, in the request.
The Row IDs of the records to be deleted as params. Multiple Row IDs must be separated by commas. The parameter key name must be ids
Request Headers
Authorization: Zoho-oauthtoken {oauth_token}
Optional Headers
CATALYST-ORG: {org_id}
Environment: Development
Scope
ZohoCatalyst.tables.rows.DELETE
Response Details
The response contains the data of all the rows that were deleted through the operation, including their metadata like theROWID and CREATEDTIME, and the column key names and values in each row.
Catalyst NoSQL is a fully managed non-relational, NoSQL data storage feature that enables you to store the semi-structured, unstructured, and disparate data of your applications. Catalyst supports document-type data storage in the key-value pair based JSON format.
The Catalyst NoSQL APIs enable you to perform CRUD operations on your NoSQL tables. You can insert, update, delete, or fetch items, as well as execute queries on a table or a table’s index.
Insert Item
Description
This API enables you to insert a new item in a NoSQL table in your project. The table is referred to by its unique ID or name.
You can insert an item with or without specifying any conditions by passing the data in the Custom JSON format.
Note: The table must already be created. You can create a NoSQL table from the console.
Note: This operation can also be executed with Catalyst user authentication permissions using Catalyst SDKs. Refer to the Catalyst API Prerequisites section for details.
Request JSON Properties
itemjsonmandatory
Contains the main data to be inserted in the table. The item must be inserted in the Custom JSON format. Specify the partition key, if the table was configured with a simple primary key. Specify both the partition key and sort key, if the table was configured with a composite primary key.
conditionjsonoptional
The existing data of the table is retrieved and evaluated against this condition. The items are inserted only if the evaluation is true. If there is no existing data, the conditions are ignored and the items are inserted. There are three ways to initialize a condition:
functionsjsonmandatory (if specifying condition)
The two built-in functions are: attribute_exist, which can be used to check for the presence of an attribute, and attribute_type, which can be used to check if the given attribute name belongs to the given type.
operator, attribute, valuejsonoptional
To perform direct comparison operations. Supported operators: contains, not_contains, begins_with, ends_with, in, not_in, between, not_between, equals, not_equals, greater_than, less_than, greater_equal, less_equal.
group, group operatorjsonoptional
To combine two or more conditions. Supported group operators: and, or.
negatejsonoptional
To negate the result of the conditions.
Response Details
The response will return the status of the insert operation, as well as the details of the item inserted such as the table_name, partition_key and sort_key, if configured.
Note: This operation can also be executed with Catalyst user authentication permissions using Catalyst SDKs. Refer to the Catalyst API Prerequisites section for details.
Request JSON Properties
keysjsonmandatory
Denotes the partition key and sort key of the table.
update_attributesjsonmandatory
Denotes the attribute to be updated along with its value. The update can be of two types: PUT (to add a new attribute within the item) and DELETE (to remove an attribute from the item). The attribute_path indicates the path within the item where the actual operation is to be done. The value to be updated can be of two types:
update_valuejsonmandatory
The actual value to be updated.
update_functionjsonoptional
There are four functions that can be used: if_not_exists - Checks the existence of the attribute and declares a value if it is not present.
append_list - Appends data to a list
add - Adds a value along with existing value or add an element in a set
reduction - Sub-traces a value from existing value or remove an element in a set.
conditionjsonoptional
The existing data of the table is retrieved and evaluated against this condition. The items are inserted only if the evaluation is true. If there is no existing data, the conditions are ignored and the items are inserted. There are three ways to initialize a condition:
functionsjsonmandatory (if specifying condition)
The two built-in functions are: attribute_exist, which can be used to check for the presence of an attribute, and attribute_type, which can be used to check if the given attribute name belongs to the given type.
operator, attribute, valuejsonoptional
To perform direct comparison operations. Supported operators: contains, not_contains, begins_with, ends_with, in, not_in, between, not_between, equals, not_equals, greater_than, less_than, greater_equal, less_equal.
group, group operatorjsonoptional
To combine two or more conditions. Supported group operators: and, or.
negatejsonoptional
To negate the result of the conditions.
Response Details
The response will return the status of the insert operation, as well as the details of the item updated such as the table_name, partition_key and sort_key, if configured.
Note: This operation can also be executed with Catalyst user authentication permissions using Catalyst SDKs. Refer to the Catalyst API Prerequisites section for details.
Request JSON Properties
keysjsonmandatory
Denotes the partition key and sort key of the table.
required_attributesjsonoptional
List of attributes to be returned.
consistent_readjsonoptional
Declares if the read has to be done from master or slave. If set to false, it is queried from the slave. Accepted values: true, false.
Response Details
The response will return the status of the fetch operation, as well as the items that are fetched. Either all the attributes or specified attributes of the items will be fetched.
Note: This operation can also be executed with Catalyst user authentication permissions using Catalyst SDKs. Refer to the Catalyst API Prerequisites section for details.
Request JSON Properties
itemjsonmandatory
Contains the main data to be inserted in the table. The item must be inserted in the Custom JSON format. Specify the partition key, if the table was configured with a simple primary key. Specify both the partition key and sort key, if the table was configured with a composite primary key.
conditionjsonoptional
The existing data of the table is retrieved and evaluated against this condition. The items are inserted only if the evaluation is true. If there is no existing data, the conditions are ignored and the items are inserted. There are three ways to initialize a condition:
functionsjsonmandatory (if specifying condition)
The two built-in functions are: attribute_exist, which can be used to check for the presence of an attribute, and attribute_type, which can be used to check if the given attribute name belongs to the given type.
operator, attribute, valuejsonoptional
To perform direct comparison operations. Supported operators: contains, not_contains, begins_with, ends_with, in, not_in, between, not_between, equals, not_equals, greater_than, less_than, greater_equal, less_equal.
group, group operatorjsonoptional
To combine two or more conditions. Supported group operators: and, or.
negatejsonoptional
To negate the result of the conditions.
Response Details
The response will return the status of the insert operation, as well as the details of the item inserted such as the table_name, partition_key and sort_key, if configured.
Note: This operation can also be executed with Catalyst user authentication permissions using Catalyst SDKs. Refer to the Catalyst API Prerequisites section for details.
Request JSON Properties
key_conditionjsonmandatory
Contains the condition in the format similar to the CRUD operations of items. Only the partition key and sort key conditions can be given. Partition key can only have the “equals” operator. The condition can be partition key = value, or a group with partition key equals condition and the sort key condition. Refer to the full list of supported operators.
required_attributesjsonoptional
List of attributes to be returned.
consistent_readjsonoptional
Declares if the read has to be done from master or slave. If set to false, it is queried from the slave. Accepted values: true, false.
other_conditionjsonoptional
These are conditions that are applied over the retrieved data. The response is sent after these conditions are applied.
forwardScanjsonoptional
This is used to indicate if the query has to be done in ascending or descending order.
startKeyjsonoptional
This is used for pagination purposes to fetch the next set of data items.
additional_sort_keyjsonoptional
This is used to indicate if the query is made against the table with additional sort keya. This contains the additional sort key attribute names.
limitjsonoptional
This indicates the maximum count of items that should be returned.
Response Details
The response will return the status of the query operation, as well as the items that are fetched according to the conditions set in the query.
Note: This operation can also be executed with Catalyst user authentication permissions using Catalyst SDKs. Refer to the Catalyst API Prerequisites section for details.
Request JSON Properties
key_conditionjsonmandatory
Contains the condition in the format similar to the CRUD operations of items. Only the partition key and sort key conditions can be given. Partition key can only have the “equals” operator. The condition can be partition key = value, or a group with partition key equals condition and the sort key condition. Refer to the full list of supported operators.
required_attributesjsonoptional
List of attributes to be returned.
consistent_readjsonoptional
Declares if the read has to be done from master or slave. If set to false, it is queried from the slave. Accepted values: true, false.
other_conditionjsonoptional
These are conditions that are applied over the retrieved data. The response is sent after these conditions are applied.
forwardScanjsonoptional
This is used to indicate if the query has to be done in ascending or descending order.
startKeyjsonoptional
This is used for pagination purposes to fetch the next set of data items.
additional_sort_keyjsonoptional
This is used to indicate if the query is made against the table with additional sort keya. This contains the additional sort key attribute names.
limitjsonoptional
This indicates the maximum count of items that should be returned.
Response Details
The response will return the status of the query operation, as well as the items that are fetched according to the conditions set in the query.
Stratus is Catalyst’s robust cloud storage solution. With a simple upload action, you can store your data of any type as Objects in containers called Buckets.
Get All Buckets
Description
This API allows you to get all available details of all buckets present in Stratus.
The response will return the metadata and details of all the buckets including its bucket_name, and the details of the user who created and last modified the bucket.
The response will return the metadata and details of the particular bucket including its bucket_name, and the details of the user who created and last modified the bucket.
This API allows you to get a specfic object stored in a bucket. The Bucket is referred by it unique bucket name, and the required object is referred using its name.
If Versionning is enabled, then the required object can also be referred to using its uniquye version ID.
This API allows you to get all the versions of the object stored in a bucket. The Bucket is referred by it unique bucket name, and the required object is referred using its name.
This API allows you to check if a particular object is stored in a bucket. The Bucket is referred by it unique bucket name, and the required object is referred using its name.
If Versionning is enabled, then the required object can also be referred to using its uniquye version ID.
This is an ID generated by Stratus when Versioning is enabled. You can use version_id to refer to the required object.
Request Headers
Authorization: Zoho-oauthtoken {oauth_token}
Optional Headers
CATALYST-ORG: {org_id}
Environment: Development
Scope
ZohoCatalyst.buckets.objects.READ
Response Details
On successful execution, the response will contain the 200 status code, to indicate the object is present in the bucket. If the object is incorrect or not present in the bucket, you will get a 404 status code as your response.
This API allows you to download the required object stored in a bucket. The Bucket is referred by it unique bucket name, and the required object is referred using its name.
Request Details
Request URL
GET
{bucket_name}.zohostratus.com/{key}
copy
The above domain name will change with respect to the data center:
DC
Domain Name
US
zohostratus.com
EU
zohostratus.eu
IN
zohostratus.in
AU
zohostratus.com.au
CA
zohostratus.ca
SA
zohostratus.sa
JP
zohostratus.jp
Note:
If the API is used in the development environment, then the domain will be structured in this manner: https://<bucket_name>-development.zohostratus.com
It is advisable to collect the bucket URL from the console.
The name of the object that needs to be downloaded
Query Parameters
version_idStringoptional
This is an ID generated by Stratus when Versioning is enabled. You can use version_id to refer to the required object.
Request Headers
Authorization: Zoho-oauthtoken {oauth_token}
Optional Headers
Range: To download a specific byte range of an object
retrieve-meta: To retrieve the metadata of the object | Possible Values: True/False | Default Value: False
Scope
Stratus.fileop.READ
Query Params to Override Responses
The following query parameters can be added to modify responses and get the required response. These are all optional parameters. The override will only work if the request is successful.
responseContentTypeStringoptional
Sets the Content-Type header of the response. Only standard IANA defined content types can be used.
responseContentLanguageStringoptional
Sets the Content-Language header of the response
responseContentDispositionStringoptional
Sets the Content-Disposition header of the response. The parameter value should be in this format: attachment; filename=“name” Example: attachment; filename=“logo.svg”
responseCacheControlStringoptional
Sets the Cache-Control header of the response. Example: public,max-age=3600,no-transform
Response Details
On successful execution, the response will contain the object will be downloaded and the success message will be displayed.
Possible Failure Responses
404 due to object/bucket not found:
Failure Response
copy
{
"status": 404,
"code": "key_not_found",
"message": "no such key is associated with any object in the bucket"
}
View more
403 Unauthorzied. When you do not have the required permissions to perform the download operation
This API allows you to upload the required objectto a bucket. The Bucket is referred by it unique bucket name, and the required object is referred using its name.
Request Details
Request URL
PUT
{bucket_name}.zohostratus.com/{key}
copy
The above domain name will change with respect to the data center:
DC
Domain Name
US
zohostratus.com
EU
zohostratus.eu
IN
zohostratus.in
AU
zohostratus.com.au
CA
zohostratus.ca
SA
zohostratus.sa
JP
zohostratus.jp
Note: If the API is used in the development environment, then the domain will be structured in this manner: https://<bucket_name>-development.zohostratus.com
Note: The following points need to be kept in mind when providing value for key:
Maximum length of the key (including path name and object name) should be supported to 255 characters only.
key cannot contain the following characters including space: double quote, both angular brackets, hashtag, backward slash and pipe symbol.
Query Parameters
version_idStringoptional
This is an ID generated by Stratus when Versioning is enabled. You can use version_id to refer to the required object.
Request Headers
Authorization: Zoho-oauthtoken {oauth_token}
Optional Headers
content-type: application/json
content-length: Raw length of the object being uploaded in bytes.
compress: Whether to compress the object while storing. By default, compression is always done.
cache-control: Use this header to specify the browser caching policies.
overwrite: Specify whether you are required to overwrite a source. This is supported only for the objects of non-versioned buckets.
expires-after: This is an option you can use to set Time-to-Live (TTL) in seconds for an object. Value should be greater than or equal to 60 seconds.
x-user-meta:{1stKey}={1stValue};{2ndKey}={2ndValue};..{NthKey}={NthValue};:Metadata for the object. Each key-value pair is separated by semi-colons are provided as given in the previous column. 2047 characters is the maximum permitted length for this header.
Scope
Stratus.fileop.CREATE
Response Details
On successful execution, the response will contain the success message, and the object will be uploaded.
Possible Failure Responses
404 due to object/bucket not found:
Failure Response
copy
{
"status": 404,
"code": "bucket_not_found",
"message": "no such bucket exists"
}
View more
403 Unauthorzied. When you do not have the required permissions to perform the upload operation
This API allows you to copy the required object stored in a bucket. The Bucket is referred by it unique bucket name, and the required object is referred using its name.
Will contain the complete name of the required object.
destinationStringmandatory
Will contain the location of where the object has to be copied to.
Request Headers
Authorization: Zoho-oauthtoken {oauth_token}
Optional Headers
CATALYST-ORG: {org_id}
Environment: Development
Scope
ZohoCatalyst.buckets.objects.CREATE
Response Details
On successful execution, the response will contain the name of the copied object, the location of where it is copied to, and the success message confirming the copy action.
This API allows you to rename the required object stored in a bucket. The Bucket is referred by it unique bucket name, and the required object is referred using its name.
Note: The following characters including space are not supported when you create a path or an object: double quote, both angular brackets, hashtag, backward slash and pipe symbol.
This API allows you to add metadata for the required object stored in a bucket. The Bucket is referred by it unique bucket name, and the required object is referred using its name.
Note:
You can use alphanumeric, underscores, or whitespace characters, as well as hyphens, to write your metadata. No other special character is allowed other than the once mentioned.
You can fetch the metadata of an object using the HEAD request method. In the response, the metadata will be listed in the key ‘x-user-meta’.
The maximum size limit of characters allowed for the overall metadata is 2047 characters. The character count used to determine the size limit also includes the colon “:” special character used to define the key value pair.
This API allows you to extract a zipped object stored in a bucket. The Bucket is referred by it unique bucket name, and the required object is referred using its name.
Will contain the complete name of the required zipped object.
destinationStringmandatory
Will contain the complete name of the destination path in the bucket where the extracted objects need to be stored.
Request Headers
Authorization: Zoho-oauthtoken {oauth_token}
Optional Headers
CATALYST-ORG: {org_id}
Environment: Development
Scope
ZohoCatalyst.buckets.objects.CREATE
Response Details
On successful execution, the response will contain the name of the zipped object, the complete path name that has stored the extracted objects, and the success message confirming the extract action.
This API allows you to get the status of an extract operation that is being performed on a zipped object stored in a bucket. The Bucket is referred by it unique bucket name, and the required object is referred using its name.
The value will be returned in the response while executing the Extract Zipped Object API. This id will allow you refer to the required extraction process.
This API allows you to get presigned urls. Presigned URLs are secure URLs that authenticated users can share to their non-authenticated users. This URL will provide non-authenticated users with temporary authorization to access objects. Once the link is expired, you need to the sign the required URL again using this API.
Note: There are different request methods for upload action and download action.
2. Select a client type for your application.
* Client Name: The name of your application you want to register with Zoho
* Homepage URL: The URL of your client's homepage
* Authorized Redirect URIs: A valid URL of your application that Zoho Accounts redirects you to with the grant token after a successful authentication
4. Click Create.
2. Enable or disable the client access for the data centers you need. You can only avail the data centers that Catalyst supports.
2. Enter a valid scope. You can check the list of scopes available in Catalyst from this section.
3. Choose a time duration from the dropdown list. The Grant Token generated in this step will expire after this time period.
