Skip to content

Other platforms via API

With the BotCity Insights API, you integrate Orchestrator data with other platforms.

The API provides the same data as the BotCity Insights Reports section.

API Reference

Your automation operation may involve other data platforms, whether applications developed by your company or provided by third parties.

With the BotCity Insights API, you consume the data reported by your automations and can display it in any dashboard visualization tool.

Getting started?

See the full API reference.

Looking for more examples?

See the practical examples with Power BI.

BASE URL
https://your-company.botcity.dev

Replace the base URL

The URL https://your-company.botcity.dev is only an example. In the requests on this page, replace it with your company's dedicated server URL, the same one you use to access the Orchestrator.

If you use the Community version, the base URL is https://developers.botcity.dev.

Authentication

The first step to use the BotCity Insights API is authentication.

The API uses an access token, sent in the header of all requests.

To get the token, make a request to the login route, sending the login and key values in the request body.

Where to find login and key

The login and key values are on the Dev. Environment page of your workspace in the Orchestrator.

Example

POST /api/v2/workspace/login

curl --location 'https://your-company.botcity.dev/api/v2/workspace/login' \
--header 'Content-Type: application/json' \
--data '{
    "login": "<WORKSPACE_LOGIN>",
    "key": "<WORKSPACE_KEY>"
}'
Response 
{
    "accessToken": "<YOUR_ACCESS_TOKEN>",
    "organizationLabel": "<YOUR_ORGANIZATION_LABEL>"
}

With the access token, you can make the other requests to consume the API data.

See below examples of how to consume report data with the BotCity Insights API.

Tasks

This route returns the data of the tasks executed in the Orchestrator, the same data as the Tasks report.

Make the request sending in the header the token and organization values obtained in the authentication step.

Parameters:

Name Description
page integer (optional)
Page number to return. Default value: 0
days integer (optional)
Number of days to consider in the search. Default value: 30

Example

GET /api/v1/insights/tasks

curl --location 'https://your-company.botcity.dev/api/v1/insights/tasks?page=0&days=30' \
--header 'token: <YOUR_ACCESS_TOKEN>' \
--header 'organization: <YOUR_ORGANIZATION_LABEL>'
Response 
{
    "content": [
        {
            "id": 17296058,
            "state": "START",
            "finishStatus": null,
            "activityLabel": "supplierHomologation",
            "repositoryLabel": "DEFAULT",
            "machineId": null,
            "dateLastModified": null,
            "dateCreation": "2024-02-09T20:02:40.032+00:00",
            "dateStartRunning": null,
            "processedItems": 0,
            "failedItems": 0,
            "totalItems": 0
        },
        ...
    ],
    "number": 0,
    "size": 20,
    "totalElements": 1,
    "pageable": {
        "pageNumber": 0,
        "pageSize": 20,
        "sort": {
            "sorted": false,
            "empty": true,
            "unsorted": true
        },
        "offset": 0,
        "paged": true,
        "unpaged": false
    },
    "last": false,
    "totalPages": 1,
    "sort": {
        "sorted": false,
        "empty": true,
        "unsorted": true
    },
    "first": true,
    "numberOfElements": 20,
    "empty": false
}

Automations

This route returns the data of the Orchestrator automations, the same data as the Automations report.

Make the request sending in the header the token and organization values obtained in the authentication step.

Parameters:

Name Description
page integer (optional)
Page number to return. Default value: 0
sort string,string (optional)
Sorting of results. Default value: label,asc.
Field options: label, date, repositoryLabel, taskCount, sumItems, sumItemsError.
Order options: asc, desc.
automation string (optional)
Automation label to search for
filterBy integer (optional)
Number of days to consider in the search. Default value: 30

Example

GET /api/v1/insights/automation

curl --location 'https://your-company.botcity.dev/api/v1/insights/automation?page=0&sort=label,asc&filterBy=30' \
--header 'token: <YOUR_ACCESS_TOKEN>' \
--header 'organization: <YOUR_ORGANIZATION_LABEL>'
Response 
{
    "content": [
        {
            "label": "supplierHomologation",
            "name": "Supplier Homologation",
            "machineId": null,
            "description": "Supplier Homologation Automation for SAP",
            "organizationLabel": "demo",
            "repositoryLabel": "DEFAULT",
            "date": "2024-02-23T23:00:02.513",
            "taskCount": 0,
            "sumItems": 0.0,
            "sumItemsError": 0.0,
            "sumItemsProcessed": 0.0,
            "uptimeRate": 0.0,
            "downtimeRate": 0.0,
            "successRate": 0.0,
            "roi": 0.0,
            "fte": 0.0,
            "savings": 0.0
        },
        ...
    ],
    "pageable": {
        "pageNumber": 0,
        "pageSize": 20,
        "sort": {
            "sorted": false,
            "empty": true,
            "unsorted": true
        },
        "offset": 0,
        "paged": true,
        "unpaged": false
    },
    "totalPages": 1,
    "totalElements": 1,
    "last": true,
    "size": 20,
    "number": 0,
    "sort": {
        "sorted": false,
        "empty": true,
        "unsorted": true
    },
    "numberOfElements": 20,
    "first": true,
    "empty": false
}

Runners

This route returns the data of the Orchestrator Runners, the same data as the Runners report.

Make the request sending in the header the token and organization values obtained in the authentication step.

Parameters:

Name Description
sort string,string (optional)
Sorting of results. Default value: tasks,desc.
Field options: _id, tasks, items, itemsErrorCount, utilizationRate.
Order options: asc, desc.
runner string (optional)
Runner identifier to search for
filterBy integer (optional)
Number of days to consider in the search. Default value: 30

Example

GET /api/v1/insights/runners

curl --location 'https://your-company.botcity.dev/api/v1/insights/runners?sort=tasks,desc&filterBy=30' \
--header 'token: <YOUR_ACCESS_TOKEN>' \
--header 'organization: <YOUR_ORGANIZATION_LABEL>'
Response 
[
    {
        "id": "vm01",
        "idMachine": "vm01",
        "log": "teste",
        "remoteAccess": "",
        "status": "created",
        "name": "vm01",
        "organization": "demo",
        "automations": [
            "supplierHomologation",
            ...
        ],
        "tasks": 0,
        "items": 0,
        "itemsErrorCount": 0,
        "utilizationRate": 0
    },
    ...
]