Corezoid API

Expand your capabilities of working with Corezoid Actor Engine by using:

• Corezoid's asynchronous API (Corezoid API reference) enables the automation of creating and modifying tasks, processes, and operations on objects like creating, uploading, and restoring folders, State Diagrams, and Dashboards.
• Corezoid synchronous API (Sync API) enables the retrieval of task-invoked process outputs.

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

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

API protocol – use prerequisites

Before using the Corezoid API:

1. Create an API key.
2. Create a pre-request script.

Create API key

To create an API key and get an API login (authorization login) and a secret key, follow the path and see the video below:
Users & Groups -> Create -> API key -> enter name -> OK

Create pre-request script

To create a pre-request script to be able to generate signatures for the API requests you send (via Postman, for example):

1. 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}: Is an authorization login of your API key;

   • {TIMESTAMP}: Is request time, a Unix timestamp (epoch time) by Greenwich (GMT+0) that requires an integer parameter.

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

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

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

1. 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);
   

   Note: 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.

2. Send an API request with the following HTTP header:
   Content-type: application/json; charset=utf8

Example of sha256 algorithm use for signature verification

To specify the signature algorithm, use the conv-signature-algorithm header. Example for sha256:

--header 'conv-signature-algorithm: sha256'

Request example

curl --location 'https://www.corezoid.com/api/2/json/130140/{{TIMESTAMP}}/{{SIGNATURE}}' \
--header 'conv-signature-algorithm: sha256' \
--data '{
  "ops": [
    {
      "title": "New object 2",
      "description": "test description",
      "type": "modify",
      "obj": "conv",
      "obj_id": 1111111,
      "company_id": "i111111111"
    }
  ]
}'

Postman configuration example

1. Create an environment with TIMESTAMP, SIGNATURE, and SECRET_KEY (replace the SECRET_KEY with your secret key) variables.
2. Configure the request:

URL: https://www.corezoid.com/api/2/json/130140/{{TIMESTAMP}}/{{SIGNATURE}}
Method: POST
Header: conv-signature-algorithm: sha256
Request Body: versatile, with environment variables configuration

Postman pre-request script example

var time = Math.floor(Date.now() / 1000);

var secret = ("*********************");

var body = request.data;
var signature = CryptoJS.enc.Hex.stringify(
     CryptoJS.SHA256(time + secret + body + secret)
);

pm.environment.set("TIMESTAMP", time);
pm.environment.set("SIGNATURE", signature);

Example of node creation request and response

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

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

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"
    }
  ]
}

Examples of task adding and modification requests

When using the Corezoid API:

• The most common operations involve creating and modifying tasks. For more information, go to Examples of tasks creation and modification.
• To create or modify a task, use our collection of Corezoid API queries for Postman.
• To create a task using the synchronous API, go to Sync API.