Skip to content

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:

image environment

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:

Activity label environment

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:

Task list params environment

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:

TaskId environment

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:

Automation label environment

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:

BotId environment

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:

LogId environment

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:

Days 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:

LogId environment

Send a GET request, and your log will be exported.

It is also possible to add the days parameter to your environment:

Days 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):

Format environment

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:

Machine Id environment

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.

Errors

With the BotCity Maestro errors route, you can list your workspace errors, access specific errors through id's, and also consume screenshots of errors generated on the platform.

Here is the schema errors.json. Download and import it as a Collection in your Postman to make the manipulation below.

Listing BotCity Maestro Errors

To list the errors generated in the BotCity Maestro, use the Route Get errors, send a request GET and the list of errors will be returned.

Collecting information from a specific error

You can also collect information from a specific error through your id, adding it to your environment as below:

Error Id environment

Use the Get error idroute, make a requisition GET, and the indicated error information will be returned.

Collecting screenshot of an error

Collecting a screenshot of an error in BotCity Maestro is very simple. Just set the parameter id of the error in your environment as below:

Error Id environment

Use the Get screenshot error route, make a requisition GET, and the error screenshot will be returned according to id indicated.