Maestro API Practical Examples - Postman¶
Attention
In this section, only some of the possible integrations with BotCity Maestro orchestrator are demonstrated, access the Full API to check all routes available for communication.
Postman¶
Postman is a powerful API development tool that simplifies API's test, development, and documentation process. It offers an intuitive interface and robust resources that allow you to interact with APIs and demonstrate their operation easily.
In this section, we will use Postman to exemplify some requests to the API routes from the BotCity Maestro orchestrator.
Postman Environment¶
To use API examples in Postman, we suggest you create an environment with BotCity Maestro authentication parameters, or if the request needs more parameters, you can also add them at this stage.
Example
Here is an example of an environment created in Postman:
Data table
| VARIABLE | TYPE | INITIAL VALUE | CURRENT VALUE |
|---|---|---|---|
| server | default | https://developers.botcity.dev | https://developers.botcity.dev |
| login | secret | ******* | ******* |
| key | secret | ******* | ******* |
| token | default | ||
| organization | default |
Attention
The parameters defined above are the basic and necessary parameters to make any request in BotCity Maestro. However, some routes require additional parameters that can also be added to your environment.
Tip
The values login andkey can be found on the Dev. Environment page of BotCity Maestro.
Info
The values token and organization will be automatically defined by the login route.
Note
For more information on how to create and manage an environment in Postman, go to this link.
With the environment properly created, follow the steps below, importing the available schemas as collections and linking your environment to them.
BotCity Maestro Authentication¶
Login¶
The login route plays a very important role; it authenticates to the BotCity Maestro API and generates an access token. Through this token, we will be able to make the requests below.
Here is the schema login.json from the login route. Download and import it as a Collection in your Postman, send a POST request and your access token will be generated.
Attention
This Schema also has an event that defines the values for the **token** and **organization** environment variables, which are necessary for authentication in BotCity Maestro, being passed in the header of every request.
Therefore, it is essential to execute the `Login - Workspace` request before starting any interaction with the Maestro API.
Info
All schemas available below have the Login schema in their respective files.
Tasks¶
BotCity Maestro task routes allow you to get and make various actions referring to the tasks. Below, we will demonstrate how to create a task , how to list tasks, and how to get detailed information from a single task.
Here is the schema tasks.json, Download and import it as a Collection in your Postman to make the manipulations below.
Creating tasks in the Maestro¶
To create tasks on BotCity Maestro is very simple, just set the activityLabel parameter on your environment as below:
Tip
The activityLabel parameter represents the label of the automation process created in Maestro.
Use the Create task route, send a POST request, and your task will be created on the platform.
Attention
The schema in question available has the value true defined in its Body for the key test. This way, the tasks created will be test tasks; if you want to create production tasks, change the value to false directly in your schema or edit it in the Body tab in your Postman.
Listing tasks from BotCity Maestro¶
To list the latest tasks created in BotCity Maestro, use the List tasks route, send a GET request, and your task list will be returned.
It is also possible to list tasks by defining some specificity as amount of results per page, which page you want to list the tasks, order by creation date, and also by the relative number of days to fetch data.
To list tasks with the parameters above, use the List tasks - Params route, define the size, page, sort and, days parameter on your environment as below:
Done that, send a GET request, and your task list will be returned according to the passed parameters.
Tip
For a quick test, you can set the values below for the parameters mentioned above:
| Key | Value | Description |
|---|---|---|
| size | 50 | Results per page |
| page | 0 | Page to Fetch |
| sort | dateCreation | Field to use for sorting |
| days | 7 | Relative number of days to fetch data |
Getting task information¶
To collect information from a single task in BotCity Maestro is very simple, define the taskId parameter on your environment as below:
Use the Get task route, make a GET request, and the task information will be returned according to the indicated taskId.
Automation¶
BotCity Maestro automation routes allow you to perform various actions. Below, we will show how to list automations from your workspace and also get detailed automation information that is available on the platform.
Here is the schema automations.json. Download and import it as a Collection in your Postman to make the manipulations below.
Listing Automations¶
To list automation in BotCity Maestro via the API, simply use the List automation route, send a GET request, and your workspace's automation list will be returned.
Getting automation data¶
It is also possible to collect information from a specific automation by defining the automationLabel parameter on your environment as below:
Use the Get automation route, make a GET request, and the automation information will be returned.
Robots¶
With BotCity Maestro robots routes, you can list robots from your workspace and collect detailed robot information implemented on the platform.
Here is the schema bots.json. Download and import it as a Collection in your Postman to make the manipulations below.
Listing all robots of your workspace¶
To list all the robots deployed on your BotCity Maestro workspace, just use the List bot route, send a GET request, and your workspace list of robots will be returned.
Getting robot information¶
It is also possible to collect information from a specific robot by setting the botId parameter on your environment as below:
Use the Get bot route, make a GET request, and the information from the indicated robot will be returned.
Log¶
With BotCity Maestro log routes, you can collect log entries from a particular log created on the platform and also export the generated logs, as we will show below.
Here is the schema logs.json. Download and import it as a Collection in your Postman to make the manipulations below.
Getting log entries generated in Maestro¶
To obtain BotCity Maestro log entries, set the logId parameter as below:
Use the Fetch entries log route, send a GET request, and log entries will be returned.
You can also add the days parameter to your environment:
So that only the log entries regarding the number of days defined are returned.
Exporting log¶
To export a BotCity Maestro log, simply use the Export log route, set the logId parameter on your environment as below:
Send a GET request, and your log will be exported.
It is also possible to add the days parameter to your environment:
So that only log entries referring to the defined number of days are returned.
In addition to the days parameter, you can also add the format parameter to define which file format you want to export your log (JSON, XLSX, or CSV):
Runner¶
The BotCity Maestro Runner/Machine routes allow you to collect and perform various actions. Below, we will show you how to collect detailed information from a Runner.
Here is the schema runners.json. Download and import it as a Collection in your Postman to make the manipulation below.
Getting information from a Runner¶
To collect information from a specific Runner in BotCity Maestro, just use the Get runner route and define the machineId parameter on your environment as below:
When sending a GET request, Runner information will be returned.
Schedules¶
BotCity Maestro scheduling routes allow you to collect and perform various actions. Below, we will show you how to list the active and inactive schedulings of your workspace.
Here is the schema schedules.json. Download and import it as a Collection in your Postman to make the manipulation below.
Listing BotCity Maestro Schedules¶
To list the scheduling created in the BotCity Maestro, just use the Get schedules route, send a GET request, and the list of schedules will be returned.