Corezoid API
  • 21 Dec 2023
  • 3 Minutes to read
  • Contributors
  • Dark
    Light
  • PDF

Corezoid API

  • Dark
    Light
  • PDF

Article Summary

Expand your capabilities of working with Corezoid Actor Engine by using Corezoid API and Sync API.

Corezoid asynchronous API (Corezoid API reference) provides the capability to automate the creation and modification of tasks and processes. It allows you to perform various operations on objects such as creating, uploading, and restoring folders, State Diagrams, and Dashboards.

Corezoid synchronous API (Sync API) allows you to receive task-invoked process outputs.

These features empower you to dynamically manage your Corezoid environment. Additionally, you can work with "real-time" processes that can be adjusted based on incoming data and predefined business logic.

postman Use our collection of Corezoid API queries for Postman as an example

Corezoid API protocol

Corezoid API use prerequisites

Before using the Corezoid API, you need to create an API key and get an API login (authorization login) and a secret key.
You can these from the Corezoid menu by following the path:
Users & Groups -> Create -> API key -> enter name -> OK

create_api_key

You may want to create a pre-request script to be able to generate signatures for the API requests you send (via Postman, for example). For creating a pre-request script, you need to copy the {API_LOGIN} authorization login, and {SECRET} secret key (by clicking the icon to the right in your API keys list), and use the following URL:

https://api.corezoid.com/api/2/json/{API_LOGIN}/{TIMESTAMP}/{SIGNATURE}

Where:

  • {API_LOGIN} - authorization login of your API key;

  • {TIMESTAMP} - request time, a Unix timestamp (epoch time) by Greenwich (GMT+0). Requires an integer parameter;

  • {SIGNATURE} - concatenated string generated from the following parts:

hex( sha1({TIMESTAMP} + {SECRET} + {CONTENT} + {SECRET}) )
where:

  • {TIMESTAMP} - request time, a Unix timestamp (epoch time) by Greenwich (GMT+0). Requires an integer input;
  • hex() - converts binary data to hexadecimal form;
  • sha1() - standard hash-function SHA-1, must return binary data;
  • + - text string concatenation;
  • {SECRET} - the secret key for your API key;
  • {CONTENT} - request body.

Now you can use the following script for signing your requests:

var time = Math.floor(Date.now() / 1000);
var secret = pm.environment.get("SECRET");
var content = request.data;
var signature = CryptoJS.enc.Hex.stringify(CryptoJS.SHA1(time + secret + content + secret));
pm.environment.set("TIMESTAMP", time);
pm.environment.set("SIGNATURE", signature);

The entire API request is an http-body described as the {CONTENT} in the {SIGNATURE} formula. All text is expected to be encoded as UTF-8.

Sending an API request requires setting the following HTTP header:

Content-type: application/json; charset=utf8

Operations on another Company objects

API operations on objects of a company different from the one which user you are currently using are forbidden.
Sending an API request to perform an operation on an object in another company will result in the error: "Company of object do not matches companyId of request"

Example of node creation request and response in Corezoid API

The request body contains a list of operations (ops):

{
  "ops": [
    {
      "id": 1,
      "type": "create",
      "obj": "conv"
    },
    {
      "type": "modify",
      "obj": "node",
      "obj_id": "n1234"
    }
  ]
}
id optional parameter

The id parameter ("string" format) is optional and is used for identifying operations in the ops array. If not specified, the parameter is returned with an empty value ("id": "") in the response.

Response

{
  "request_proc": "ok",
  "ops": [
    {
      "id": 1,
      "obj": "conv",
      "obj_id": "1234",
      "proc": "ok"
    },
    {
      "id": "",
      "obj": "node",
      "obj_id": "n1234",
      "proc": "obj_id_not_found"
    }
  ]
}
ParameterValueDescription
request_proc"ok" in the case of a successful request, otherwise - errorglobal status of whole package processing
ops[]list of operations
ops[n].proc"ok" in the case of a successful request, otherwise - errorstatus for a separate operation

Examples of task adding and modification requests

When utilizing the Corezoid API, the most common operations involve creating and modifying tasks.
Please refer to our examples for asynchronous Corezoid API, as well as implementations in Erlang, Java, Python, and BASH, to carry out these tasks effectively.
To create or modify a task, you can also use our collection of Corezoid API queries for Postman.
To create a task using the synchronous API, refer to the example in this section.


Was this article helpful?