Working with the model management API

Overview

Check the list of available endpoints and methods in the Aggregation task API:

Endpoints and methods	Description
GET `/models/{name}`^{see below}	Get detailed information about a model.
PUT `/models/{name}`^{see below}	Replace the data of an existing model.
POST `/models/{name}`^{see below}	Create a new model.
DELETE `/models/{name}` ^{see below}	Delete a model.
PATCH `/models/{name}` ^{see below}	Update an existing model.
GET `/models/{name}` ^{see below}	List the available models in the current domain.
GET `/images/{name}` ^{see below}	Get the binary image of a model.

Endpoints and methods

GET `/models/{name}`

Get information about all the aggregation tasks in a domain.

In order to work with Model Management you need to activate Machine Learning permissions in your role. Go to Administration → Roles → Permissions → Machine Learning and activate the view and manage permissions in Models.

Learn more about roles and permissions in Role permissions.

Request

Path parameters

Add the following path parameters as part of the endpoint:

Parameter	Type	Description
`domain` ^required	`string`	Enter the domain of the aggregation tasks you want to get information about.

Query string parameters

Query string parameters are optionally added after the path parameters, preceded by a question mark (?) and separated by an ampersand (&)

Parameter	Type	Description
`skipCache`	`boolean`	If it is `true`, skips the cache that contains the status of the aggregation tasks and force the system to tell you where to find them. Default value is `false`.
`status`	`string`	Execution status of the aggregation tasks. Available values are: `RUNNING` `STOPPED` `DELETED` `ERROR` `PARTIAL_STOPPED` `PENDING_CREATE` `PENDING_START` `PENDING_STOP` `PENDING_UPDATE` `PENDING_REBUILD` `PENDING_DELETE` `PENDING_RESUME` `PENDING_EXTEND`
`id`	`string`	If you want to get details about a specific aggregation task only, enter its ID here. How can I get the ID of an aggregation task? To get the ID of an aggregation task, log in to the Devo platform and go to Administration → Data management, locate your aggregation task in the table, click the ellipsis button in its row and select View details. You can copy the internal ID in the details shown in the window that appears. Learn more about this in Aggregation tasks.
`fromDate`	`integer`	Timestamp from when the aggregation tasks to be returned were created. Format is a timestamp in milliseconds, for example `1652400000000`
`name`	`string`	If you want to get details about a specific aggregation task only, you can enter its name.
`ownerEmail`	`string`	Email of the aggregation tasks' owner.
`negated`	`boolean`	Set this to `true` to negate all other parameters. Default value is `false`.

Example

Find below a request example in cURL language. In this case, we are requesting all the aggregation tasks with status STOPPED created in the given domain. Learn how to authorize your request in this article.

curl -H "standAloneToken:YOUR_TOKEN" -X GET "https://api-us.devo.com/aggregations/v2/aggrtasks/myDomain?status=STOPPED"

Response

Code	Description
200	Successful response. List of aggregation tasks retrieved. [ { "id": "cc_myDomain:nQEbd480", "name": "test1", "delay": 0, "domainName": "myDomain", "ownerEmail": "john.smith@devo.com", "jobs": [ { "grain": "1m", "status": "STOPPED", "from": 1652400000000, "to": 1652432340000 }, { "grain": "5m", "status": "STOPPED", "from": 1652400000000, "to": 1652400000000 }, { "grain": "1h", "status": "STOPPED", "from": 1652400000000, "to": 1652400000000 } ], "creationDate": 1652432342000, "updateDate": 1652432342000, "status": "STOPPED", "statusData": "INCOMPLETE", "fromDate": 1652400000000 }, { "id": "cc_myDomain:oYckc691", "name": "test2", "delay": 0, "domainName": "myDomain", "ownerEmail": "john.smith@devo.com", "jobs": [ { "grain": "1m", "status": "STOPPED", "from": 1652400000000, "to": 1652436480000 }, { "grain": "5m", "status": "STOPPED", "from": 1652400000000, "to": 1652436300000 }, { "grain": "1h", "status": "STOPPED", "from": 1652400000000, "to": 1652436000000 } ], "creationDate": 1652436468000, "updateDate": 1652436468000, "status": "STOPPED", "statusData": "INCOMPLETE", "fromDate": 1652400000000 } ]
400	Error in request
401	Unauthorized error.
403	Forbidden request.
404	Not found.
405	Method not allowed.
500	Server error and Java exception.

PUT `/models/{name}`

Get information about a specific aggregation task in a given domain.

In order to work with Model Management you need to activate Machine Learning permissions in your role. Go to Administration → Roles → Permissions → Machine Learning and active the view and manage permissions in Models.

Learn more about roles and permissions in Role permissions.

Request

Path parameters

Add the following path parameters as part of the endpoint:

Parameter	Type	Description
`domain` ^required	`string`	Enter the domain of the aggregation task you want to get information about.
`aggrId` ^required	`string`	Enter the ID of the aggregation task you want to get information about. How can I get the ID of an aggregation task? To get the ID of an aggregation task, log in to the Devo platform and go to Administration → Data management, locate your aggregation task in the table, click the ellipsis button in its row and select View details. You can copy the internal ID in the details shown in the window that appears. Learn more about this in Aggregation tasks.

Query string parameters

Query string parameters are optionally added after the path parameters, preceded by a question mark (?) and separated by an ampersand (&)

Parameter

Type

Description

skipCache

boolean

If it is true, skips the cache that contains the status of the aggregation task and force the system to tell you where to find it.

Default value is false.

Example

Find below a request example in cURL language. In this case, we are requesting details about the aggregation task with ID cc_myDomain:abcDE123 created in the domain called myDomain. Also, we want to skip the cache about its status. Learn how to authorize your request in this article.

curl -H "standAloneToken:YOUR_TOKEN" -X GET "https://api-us.devo.com/aggregations/v2/aggrtasks/myDomain/cc_myDomain:abcDE123?skipCache=true"

Response

Code	Description
200	Successful response. aggregation task details retrieved. { "id": "cc_myDomain:abcDE123", "name": "Test", "table": "demo.ecommerce.data`1234`.`345`", "wheres": [ "eq(client, \"myDomain\")" ], "delay": 0, "query": { "linq": "from demo.ecommerce.data`1234`.`345` where eq(client, \"myDomain\") group every 60000 by level, type, message, client" }, "domainName": "myDomain", "ownerEmail": "john.smith@devo.com", "jobs": [ { "grain": "1m", "status": "STOPPED", "from": 1652400000000, "to": 1652432040000 }, { "grain": "5m", "status": "STOPPED", "from": 1652400000000, "to": 1652400000000 }, { "grain": "1h", "status": "STOPPED", "from": 1652400000000, "to": 1652400000000 } ], "creationDate": 1652432055000, "updateDate": 1652432055000, "status": "STOPPED", "statusData": "INCOMPLETE", "fromDate": 1652400000000 }
400	Error in request
401	Unauthorized error.
403	Forbidden request.
404	Not found.
405	Method not allowed.
500	Server error and Java exception.

POST `/models/{name}`

Get the measures of an aggregation task.

In order to work with Model Management you need to activate Machine Learning permissions in your role. Go to Administration → Roles → Permissions → Machine Learning and activate the view and manage permissions in Models.

Learn more about roles and permissions in Role permissions.

Request

Path parameters

Add the following path parameters as part of the endpoint:

Parameter	Type	Parameter
`domain` ^required	`string`	Enter the domain of the aggregation task you want to get information about.
`aggrId` ^required	`string`	Enter the ID of the aggregation task you want to get information about. How can I get the ID of an aggregation task? To get the ID of an aggregation task, log in to the Devo platform and go to Administration → Data management, locate your aggregation task in the table, click the ellipsis button in its row and select View details. You can copy the internal ID in the details shown in the window that appears. Learn more about this in Aggregation tasks.

Example

Find below a request example in cURL language. In this case, we are requesting the measures of the aggregation task with ID cc_myDomain:abcDE123 created in the domain called myDomain. Also, we want to skip the cache about its status. Learn how to authorize your request in this article.

curl -H "standAloneToken:YOUR_TOKEN" -X GET "https://api-us.devo.com/aggregations/v2/aggrtasks/myDomain/cc_myDomain:abcDE123/measures"

Response

Code	Description
200	Successful response. In this example, the task is calculating three aggregations: `count()` `avg(responseTime)` `sum(responseTime)` { "responseTime": [ "avg", "sum" ], "count": [] }
400	Error in request
401	Unauthorized error.
403	Forbidden request.
404	Not found.
405	Method not allowed.
500	Server error and Java exception.

DELETE `/models/{name}`

Create a new aggregation task.

In order to work with Model Management you need to activate Machine Learning permissions in your role. Go to Administration → Roles → Permissions → Machine Learning and activate the view and manage permissions in Models.

Learn more about roles and permissions in Role permissions.

Request

Path parameters

Add the following path parameters as part of the endpoint:

Parameter	Type	Description
`domain` ^required	`string`	Enter the domain where you want to create the aggregation task.

Request body

The request JSON body must include an object with the following key-value pairs:

Parameter	Type	Description
`name` ^required	`string`	Aggregation task's name, which must be unique in the domain.
`query` ^required	`object`	An object that contains three parameters: `LINQ` - Base query of the aggregation task, written in LINQ syntax. `timezone` - Timezone of the aggregation task query, in the following format: `Europe/Madrid` `locale` - Locale of the aggregation task query, in the following format: `en`
`fromDate` ^required	`string`	Date from which the aggregation task searches to calculate the aggregated data. Valid format is `dd/mm/yyyy`
`description`	`string`	Brief description of the aggregation task.
`delay`	`integer`	Maximum acceptable time difference between the current time and the last event displayed. You can indicate it in seconds (`1s`), minutes (`1m`), hours (`1h`) and days (`1d`). Default value is `0`
`minGrain`	`string`	Minimum granularity of the aggregation task. Available values are: `AUTO` - Calculate best aggregation according to the given query. `1m` - Aggregate every minute. `5m` - Aggregate every 5 minutes. `30m` - Aggregate every 30 minutes.

Example

Find below a request example in cURL language. In this case, we are creating a new aggregation task in the domain called myDomain. Learn how to authorize your request in this article.

curl --location -g 'https://api-us.devo.com/aggregations/v2/aggrtasks/myDomain' --header 'standAloneToken:YOUR_TOKEN' --header 'Content-Type: application/json' --data '{
    "name": "MyNewAggTask",
    "description": "This is a test aggregation task",
    "fromDate": "06/02/2023",
    "minGrain": "30m",
    "query": {
        "timeZone": "Europe/Madrid",
        "locale": "es",
        "linq": "from siem.logtrust.web.activity group every 5m by username every 5m select avg(responseTime) as responseTime"
    }    
}'

Response

Code	Description
200	Successful response. Aggregation task created. { "id": "cc_myDomain:abcDE123", "name": "MyNewAggTask", "table": "siem.logtrust.web.activity", "wheres": [ "eq(client, \"myDomain\")" ], "delay": 0, "query": { "linq": "from siem.logtrust.web.activity where eq(client, \"integrations_factory\") group every 60000 by username, client select sumf(responseTime) as responseTime_sumf", "timeZone": "Europe/Madrid", "locale": "es" }, "description": "my new aggregation task", "domainName": "myDomain", "ownerEmail": "john.smith@devo.com", "creationDate": 1677087818714, "updateDate": 1677087818714, "status": "PENDING_CREATE", "statusData": null, "fromDate": 0 }
400	Error in request
401	Unauthorized error.
403	Forbidden request.
404	Not found.
405	Method not allowed.
500	Server error and Java exception.

PATCH `/models/{name}`

Update a specific aggregation task.

In order to work with Model Management you need to activate Machine Learning permissions in your role. Go to Administration → Roles → Permissions → Machine Learning and activate the view and manage permissions in Models.

Learn more about roles and permissions in Role permissions.

Request

Path parameters

Add the following path parameters as part of the endpoint:

Parameter	Type	Description
`domain` ^required	`string`	Enter the domain of the aggregation task that you want to update.
`aggrId` ^required	`string`	Enter the ID of the aggregation task that you want to update. How can I get the ID of an aggregation task? To get the ID of an aggregation task, log in to the Devo platform and go to Administration → Data management, locate your aggregation task in the table, click the ellipsis button in its row and select View details. You can copy the internal ID in the details shown in the window that appears. Learn more about this in Aggregation tasks.

Request body

The request JSON body must include an object with the following key-value pairs:

Parameter	Type	Description
`query`	`object`	An object that contains three parameters: `LINQ` - Base query of the aggregation task, written in LINQ syntax. `timezone` - Timezone of the aggregation task query, in the following format: `Europe/Madrid` `locale` - Locale of the aggregation task query, in the following format: `en`
`description`	`string`	Brief description of the aggregation task.
`delay`	`integer`	Maximum acceptable time difference between the current time and the last event displayed. You can indicate it in seconds (`1s`), minutes (`1m`), hours (`1h`) and days (`1d`). Default value is `0`
`minGrain`	`string`	Minimum granularity of the aggregation task. Available values are: `AUTO` - Calculate best aggregation according to the given query. `1m` - Aggregate every minute. `5m` - Aggregate every 5 minutes. `30m` - Aggregate every 30 minutes.

Example

Find below a request example in cURL language. In this case, we are updating an aggregation task with ID cc_myDomain:abcDE123 in the domain called myDomain. Learn how to authorize your request in this article.

curl --location --request PUT 'https://api-us.devo.com/aggregations/v2/aggrtasks/myDomain/cc_myDomain:abcDE123' --header 'standAloneToken:YOUR_TOKEN' --header 'Content-Type: application/json' --data '{
    "description": "Aggregation task updated",
    "minGrain": "5m",
    "query": {
        "timeZone": "Europe/Madrid",
        "locale": "es",
        "linq": "from siem.logtrust.web.activity group every 10m by username every 5m select avg(responseTime) as responseTime"
    }    
}'

Response

Code	Description
200	Aggregation task successfully updated. { "id": "cc_myDomain:abcDE123", "name": "MyNewAggTask", "table": "siem.logtrust.web.activity", "wheres": [ "eq(client, \"myDomain\")" ], "delay": 0, "query": { "linq": "from siem.logtrust.web.activity where eq(client, \"integrations_factory\") group every 60000 by username, client select sumf(responseTime) as responseTime_sumf", "timeZone": "Europe/Madrid", "locale": "es" }, "description": "Aggregation task updated", "domainName": "myDomain", "ownerEmail": "john.smith@devo.com", "creationDate": 1677087818714, "updateDate": 1677087818714, "status": "PENDING_CREATE", "statusData": null, "fromDate": 0 }
400	Error in request
401	Unauthorized error.
403	Forbidden request.
404	Not found.
405	Method not allowed.
500	Server error and Java exception.

GET `/models/{name}`

Stop an aggregation task.

In order to work with Model Management you need to activate Machine Learning permissions in your role. Go to Administration → Roles → Permissions → Machine Learning and activate the view and manage permissions in Models.

Learn more about roles and permissions in Role permissions.

Request

Path parameters

Add the following path parameters as part of the endpoint:

Parameter	Type	Description
`domain` ^required	`string`	Enter the domain of the aggregation task that you want to stop.
`aggrId` ^required	`string`	Enter the ID of the aggregation task that you want to stop. How can I get the ID of an aggregation task? To get the ID of an aggregation task, log in to the Devo platform and go to Administration → Data management, locate your aggregation task in the table, click the ellipsis button in its row and select View details. You can copy the internal ID in the details shown in the window that appears. Learn more about this in Aggregation tasks.

Example

Find below a request example in cURL language. In this case, we want to stop the aggregation task with ID cc_myDomain:abcDE123 in the domain called myDomain. Learn how to authorize your request in this article.

curl -H "standAloneToken:YOUR_TOKEN" -X PUT "https://api-us.devo.com/aggregations/v2/aggrtasks/myDomain/cc_myDomain:abcDE123/stop"

Response

Code	Description
200	Aggregation task stopped. true
400	Error in request
401	Unauthorized error.
403	Forbidden request.
404	Not found.
405	Method not allowed.
500	Server error and Java exception.

GET `/images/{name}`

Start a new task and add aggregated data from a specific date.

In order to work with Model Management you need to activate Machine Learning permissions in your role. Go to Administration → Roles → Permissions → Machine Learning and activate the view and manage permissions in Models.

Learn more about roles and permissions in Role permissions.

Request

Path parameters

Add the following path parameters as part of the endpoint:

Parameter	Type	Description
`domain` ^required	`string`	Enter the domain where you want the aggregation task to be.
`aggrId` ^required	`string`	Enter the ID of the aggregation task that you want to start. How can I get the ID of an aggregation task? To get the ID of an aggregation task, log in to the Devo platform and go to Administration → Data management, locate your aggregation task in the table, click the ellipsis button in its row and select View details. You can copy the internal ID in the details shown in the window that appears. Learn more about this in Aggregation tasks.

Query string parameters

Query string parameters are optionally added after the path parameters, preceded by a question mark (?) and separated by an ampersand (&)

Parameter	Type	Description
`from` ^required	`integer`	Timestamp from when the aggregation task will be started. Format is a timestamp in milliseconds, for example `1652400000000`

Example

Find below a request example in cURL language. In this case, we want to start the aggregation task with ID cc_myDomain:abcDE123 in the domain called myDomain from a specific date indicated in the timestamp added to the URL. Learn how to authorize your request in this article.

curl -H "standAloneToken:YOUR_TOKEN" -X PUT "https://api-us.devo.com/aggregations/v2/aggrtasks/myDomain/cc_myDomain:abcDE123/start?from=1652400000000"

Response

Code	Description
200	Aggregation task started. true
400	Error in request
401	Unauthorized error.
403	Forbidden request.
404	Not found.
405	Method not allowed.
500	Server error and Java exception.

Working with the model management API

Overview

Endpoints and methods

GET /models/{name}

Query string parameters

PUT /models/{name}

Query string parameters

POST /models/{name}

DELETE /models/{name}

Path parameters

PATCH /models/{name}

GET /models/{name}

GET /images/{name}

Query string parameters

GET `/models/{name}`

PUT `/models/{name}`

POST `/models/{name}`

DELETE `/models/{name}`

PATCH `/models/{name}`

GET `/models/{name}`

GET `/images/{name}`