Contents
- Operations
- Viewing a list of active lists on the correlator
- Import entries to an active list
- Searching alerts
- Closing alerts
- Searching assets
- Importing assets
- Deleting assets
- Searching events
- Viewing information about the cluster
- Resource search
- Loading resource file
- Viewing the contents of a resource file
- Importing resources
- Exporting resources
- Downloading the resource file
- Search for services
- Tenant search
- View token bearer information
- Dictionary updating in services
- Dictionary retrieval
Viewing a list of active lists on the correlator
GET /api/v1/activeLists
The target correlator must be running.
Access: administrator and analyst.
Query parameters
Name |
Data type |
Mandatory |
Description |
Value example |
correlatorID |
string |
Yes |
Correlator service ID |
00000000-0000-0000-0000-000000000000 |
Response
HTTP code: 200
Format: JSON
|
Possible errors
HTTP code |
Description |
message field value |
details field value |
400 |
Correlator service ID is not specified |
query parameter required |
correlatorID |
403 |
The user does not have the required role in the correlator tenant |
access denied |
|
404 |
The service with the specified identifier (correlatorID) was not found |
service not found |
|
406 |
The service with the specified ID (correlatorID) is not a correlator |
service is not correlator |
|
406 |
The correlator did not execute the first start |
service not paired |
|
406 |
The correlator tenant is disabled |
tenant disabled |
|
50x |
Failed to access the correlator API |
correlator API request failed |
variable |
500 |
Failed to decode the response body received from the correlator |
correlator response decode failed |
variable |
500 |
Any other internal errors |
variable |
variable |
Import entries to an active list
POST /api/v1/activeLists/import
The target correlator must be running.
Access: administrator and analyst.
Query parameters
Name |
Data type |
Mandatory |
Description |
Value example |
correlatorID |
string |
Yes |
Correlator service ID |
00000000-0000-0000-0000-000000000000 |
activeListID |
string |
If activeListName is not specified |
Active list ID |
00000000-0000-0000-0000-000000000000 |
activeListName |
string |
If activeListID is not specified |
Active list name |
Attackers |
format |
string |
Yes |
Format of imported entries |
csv, tsv, internal |
keyField |
string |
For the CSV and TSV formats only |
The name of the field in the header of the CSV or TSV file that will be used as the key field of the active list record. The values of this field must be unique |
ip |
clear |
bool |
No |
Clear the active list before importing. If the parameter is present in the URL query, then its value is assumed to be true. The values specified by the user are ignored. Example: /api/v1/activeLists/import?clear |
|
Request body
Format |
Contents |
csv |
The first line is the header, which lists the comma-separated fields. The rest of the lines are the values corresponding to the comma-separated fields in the header. The number of fields in each line must be the same. |
tsv |
The first line is the header, which lists the TAB-separated fields. The remaining lines are the values corresponding to the TAB-separated fields in the header. The number of fields in each line must be the same. |
internal |
Each line contains one individual JSON object. Data in the internal format can be received by exporting the contents of the active list from the correlator in the KUMA web console. |
Response
HTTP code: 204
Possible errors
HTTP code |
Description |
message field value |
details field value |
400 |
Correlator service ID is not specified |
query parameter required |
correlatorID |
400 |
Neither the activeListID parameter nor the activeListName parameter is specified |
one of query parameters required |
activeListID, activeListName |
400 |
The format parameter is not specified |
query parameter required |
format |
400 |
The format parameter is invalid |
invalid query parameter value |
format |
400 |
The keyField parameter is not specified |
query parameter required |
keyField |
400 |
The request body has a zero-length |
request body required |
|
400 |
The CSV or TSV file does not contain the field specified in the keyField parameter |
correlator API request failed |
line 1: header does not contain column <name> |
400 |
Request body parsing error |
correlator API request failed |
line <number>: <message> |
403 |
The user does not have the required role in the correlator tenant |
access denied |
|
404 |
The service with the specified identifier (correlatorID) was not found |
service not found |
|
404 |
No active list was found |
active list not found |
|
406 |
The service with the specified ID (correlatorID) is not a correlator |
service is not correlator |
|
406 |
The correlator did not execute the first start |
service not paired |
|
406 |
The correlator tenant is disabled |
tenant disabled |
|
406 |
A name search was conducted for the active list (activeListName), and more than one active list was found |
more than one matching active lists found |
|
50x |
Failed to access the correlator API |
correlator API request failed |
variable |
500 |
Failed to decode the response body received from the correlator |
correlator response decode failed |
variable |
500 |
Any other internal errors |
variable |
variable |
Searching alerts
GET /api/v1/alerts
Access: administrator, analyst, and operator.
Query parameters
Name |
Data type |
Mandatory |
Description |
Value example |
page |
number |
No |
Page number. Starts with 1. The page size is 250 entries. If the parameter is not specified, the default value is 1. |
1 |
id |
string |
No |
Alert ID. If the parameter is specified several times, then a list is generated and the logical OR operator is applied. |
00000000-0000-0000-0000-000000000000 |
TenantID |
string |
No |
Alert tenant ID. If the parameter is specified several times, then a list is generated and the logical OR operator is applied. If the user does not have the required role in the specified tenant, then this tenant is ignored. |
00000000-0000-0000-0000-000000000000 |
name |
string |
No |
Alert name. Case-insensitive regular expression (PCRE). |
alert |
timestampField |
string |
No |
The name of the alert field that is used to perform sorting (DESC) and search by period (from – to). lastSeen by default. |
lastSeen, firstSeen |
from |
string |
No |
Lower bound of the period in RFC3339 format. <timestampField> >= <from> |
2021-09-06T00:00:00Z (UTC) 2021-09-06T00:00:00.000Z (UTC, including milliseconds) 2021-09-06T00:00:00Z+00:00 (MSK) |
to |
string |
No |
Upper bound of the period in RFC3339 format. <timestampField> <= <to> |
2021-09-06T00:00:00Z (UTC) 2021-09-06T00:00:00.000Z (UTC, including milliseconds) 2021-09-06T00:00:00Z+00:00 (MSK) |
status |
string |
No |
Alert status. If the parameter is specified several times, then a list is generated and the logical OR operator is applied. |
new, assigned, escalated, closed |
withEvents |
bool |
No |
Include normalized KUMA events associated with found alerts in the response. If the parameter is present in the URL query, then its value is assumed to be true. The values specified by the user are ignored. Example: /api/v1/alerts?withEvents |
|
withAffected |
bool |
No |
Include information about the assets and accounts associated with the found alerts in the report. If the parameter is present in the URL query, then its value is assumed to be true. The values specified by the user are ignored. Example: /api/v1/alerts?withAffected |
|
Response
HTTP code: 200
Format: JSON
|
Possible errors
HTTP code |
Description |
message field value |
details field value |
400 |
Invalid value of the "page" parameter |
invalid query parameter value |
page |
400 |
Invalid value of the "status" parameter |
invalid status |
<status> |
400 |
Invalid value of the "timestampField" parameter |
invalid timestamp field |
|
400 |
Invalid value of the "from" parameter |
cannot parse from |
variable |
400 |
Invalid value of the "to" parameter |
cannot parse to |
variable |
400 |
The value of the "from" parameter is greater than the value of the "to" parameter |
from cannot be greater than to |
|
500 |
Any other internal errors |
variable |
variable |
Closing alerts
POST /api/v1/alerts/close
The target correlator must be running.
Access: administrator, analyst, and operator.
Request body
Format: JSON
Name |
Data type |
Mandatory |
Description |
Value example |
id |
string |
Yes |
Alert ID |
00000000-0000-0000-0000-000000000000 |
reason |
string |
Yes |
Reason for closing the alert |
responded, incorrect data, incorrect correlation rule |
Response
HTTP code: 204
Possible errors
HTTP code |
Description |
message field value |
details field value |
400 |
Alert ID is not specified |
id required |
|
400 |
The reason for closing the alert is not specified |
reason required |
|
400 |
Invalid value of the "reason" parameter |
invalid reason |
|
403 |
The user does not have the required role in the alert tenant |
access denied |
|
404 |
Alert not found |
alert not found |
|
406 |
Alert tenant disabled |
tenant disabled |
|
406 |
Alert already closed |
alert already closed |
|
500 |
Any other internal errors |
variable |
variable |
Searching assets
GET /api/v1/assets
Access: administrator, analyst, and operator.
Query parameters
Name |
Data type |
Mandatory |
Description |
Value example |
page |
number |
No |
Page number. Starts with 1. The page size is 250 entries. If the parameter is not specified, the default value is 1. |
1 |
id |
string |
No |
Asset ID. If the parameter is specified several times, then a list is generated and the logical OR operator is applied. |
00000000-0000-0000-0000-000000000000 |
TenantID |
string |
No |
Asset tenant ID. If the parameter is specified several times, then a list is generated and the logical OR operator is applied. If the user does not have the required role in the specified tenant, then this tenant is ignored. |
00000000-0000-0000-0000-000000000000 |
name |
string |
No |
Asset name. Case-insensitive regular expression (PCRE). |
asset ^My asset$ |
fqdn |
string |
No |
Asset FQDN. Case-insensitive regular expression (PCRE). |
^com$ |
ip |
string |
No |
Asset IP address. Case-insensitive regular expression (PCRE). |
10.10 ^192.168.1.2$ |
mac |
string |
No |
Asset MAC address. Case-insensitive regular expression (PCRE). |
^00:0a:95:9d:68:16$ |
Response
HTTP code: 200
Format: JSON
|
Possible errors
HTTP code |
Description |
message field value |
details field value |
400 |
Invalid value of the "page" parameter |
invalid query parameter value |
page |
500 |
Any other internal errors |
variable |
variable |
Importing assets
Details on identifying, creating, and updating assets
Assets are imported according to the asset data merging rules.
POST /api/v1/assets/import
Bulk creation or update of assets.
Access: administrator and analyst.
Request body
Format: JSON
|
Request mandatory fields
Name |
Data type |
Mandatory |
Description |
Value example |
TenantID |
string |
Yes |
Tenant ID |
00000000-0000-0000-0000-000000000000 |
assets |
[]Asset |
Yes |
Array of imported assets |
|
Asset mandatory fields
Name |
Data type |
Mandatory |
Description |
Value example |
fqdn |
string |
If the ipAddresses array is not specified |
Asset FQDN. It is recommended that you specify the FQDN and not just the host name. Priority indicator for asset identification. |
my-asset-1.example.com my-asset-1 |
ipAddresses |
[]string |
If FQDN is not specified |
Array of IP addresses for the asset. IPv4 or IPv6. The first element of the array is used as a secondary indicator for asset identification. |
["192.168.1.1", "192.168.2.2"] ["2001:0db8:85a3:0000:0000:8a2e:0370:7334"] |
Response
HTTP code: 200
Format: JSON
|
Possible errors
HTTP code |
Description |
message field value |
details field value |
400 |
Tenant ID is not specified |
tenantID required |
|
400 |
Attempt to import assets into the shared tenant |
import into shared tenant not allowed |
|
400 |
Not a single asset was specified in the request body |
at least one asset required |
|
400 |
None of the mandatory fields is specified |
one of fields required |
asset[<index>]: fqdn, ipAddresses |
400 |
Invalid FQDN |
invalid value |
asset[<index>].fqdn |
400 |
Invalid IP address |
invalid value |
asset[<index>].ipAddresses[<index>] |
400 |
IP address is repeated |
duplicated value |
asset[<index>].ipAddresses |
400 |
Invalid MAC address |
invalid value |
asset[<index>].macAddresses[<index>] |
400 |
MAC address is repeated |
duplicated value |
asset[<index>].macAddresses |
403 |
The user does not have the required role in the specified tenant |
access denied |
|
404 |
The specified tenant was not found |
tenant not found |
|
406 |
The specified tenant was disabled |
tenant disabled |
|
500 |
Any other internal errors |
variable |
variable |
Deleting assets
POST /api/v1/assets/delete
Access: administrator and analyst.
Request body
Format: JSON
Name |
Data type |
Mandatory |
Description |
Value example |
TenantID |
string |
Yes |
Tenant ID |
00000000-0000-0000-0000-000000000000 |
ids |
[]string |
If neither the ipAddresses array nor the FQDNs are specified |
List of asset IDs |
["00000000-0000-0000-0000-000000000000"] |
fqdns |
[]string |
If neither the ipAddresses array nor the IDs are specified |
Array of asset FQDNs |
["my-asset-1.example.com", "my-asset-1"] |
ipAddresses |
[]string |
If neither the IDs nor FQDNs are specified |
Array of main IP addresses of the asset. |
["192.168.1.1", "2001:0db8:85a3:0000:0000:8a2e:0370:7334"] |
Response
HTTP code: 200
Format: JSON
|
Possible errors
HTTP code |
Description |
message field value |
details field value |
400 |
Tenant ID is not specified |
tenantID required |
|
400 |
Attempt to delete an asset from the shared tenant |
delete from shared tenant not allowed |
|
400 |
None of the mandatory fields is specified |
one of fields required |
ids, fqdns, ipAddresses |
400 |
Invalid FQDN specified |
invalid value |
fqdns[<index>] |
400 |
Invalid IP address specified |
invalid value |
ipAddresses[<index>] |
403 |
The user does not have the required role in the specified tenant |
access denied |
|
404 |
The specified tenant was not found |
tenant not found |
|
406 |
The specified tenant was disabled |
tenant disabled |
|
500 |
Any other internal errors |
variable |
variable |
Searching events
POST /api/v1/events
Access: administrator, analyst, and operator.
Request body
Format: JSON
Request
Name |
Data type |
Mandatory |
Description |
Value example |
period |
Period |
Yes |
Search period |
|
sql |
string |
Yes |
SQL query |
SELECT * FROM events WHERE Type = 3 ORDER BY Timestamp DESC LIMIT 1000 SELECT sum(BytesOut) as TotalBytesSent, SourceAddress FROM events WHERE DeviceVendor = 'netflow' GROUP BY SourceAddress LIMIT 1000 SELECT count(Timestamp) as TotalEvents FROM events LIMIT 1 |
ClusterID |
string |
No, if the cluster is the only one |
Storage cluster ID. You can find it by requesting a list of services with kind = storage. The cluster ID will be in the resourceID field. |
00000000-0000-0000-0000-000000000000 |
rawTimestamps |
bool |
No |
Display timestamps in their current format—Milliseconds since EPOCH. False by default. |
true or false |
emptyFields |
bool |
No |
Display empty fields for normalized events. False by default. |
true or false |
Period
Name |
Data type |
Mandatory |
Description |
Value example |
from |
string |
Yes |
Lower bound of the period in RFC3339 format. Timestamp >= <from> |
2021-09-06T00:00:00Z (UTC) 2021-09-06T00:00:00.000Z (UTC, including milliseconds) 2021-09-06T00:00:00Z+00:00 (MSK) |
to |
string |
Yes |
Upper bound of the period in RFC3339 format. Timestamp <= <to> |
2021-09-06T00:00:00Z (UTC) 2021-09-06T00:00:00.000Z (UTC, including milliseconds) 2021-09-06T00:00:00Z+00:00 (MSK) |
Response
HTTP code: 200
Format: JSON
Result of executing the SQL query
Possible errors
HTTP code |
Description |
message field value |
details field value |
|---|---|---|---|
400 |
The lower bounds of the range is not specified |
period.from required |
|
400 |
The lower bounds of the range is in an unsupported format |
cannot parse period.from |
variable |
400 |
The lower bounds of the range is equal to zero |
period.from cannot be 0 |
|
400 |
The upper bounds of the range is not specified |
period.to required |
|
400 |
The upper bounds of the range is in an unsupported format |
cannot parse period.to |
variable |
400 |
The upper bounds of the range is equal to zero |
period.to cannot be 0 |
|
400 |
The lower bounds of the range is greater than the upper bounds |
period.from cannot be greater than period.to |
|
400 |
Invalid SQL query |
invalid sql |
variable |
400 |
An invalid table appears in the SQL query |
the only valid table is `events` |
|
400 |
The SQL query lacks a LIMIT |
sql: LIMIT required |
|
400 |
The LIMIT in the SQL query exceeds the maximum (1000) |
sql: maximum LIMIT is 1000 |
|
404 |
Storage cluster not found |
cluster not found |
|
406 |
The clusterID parameter was not specified, and many clusters were registered in KUMA |
multiple clusters found, please provide clusterID |
|
500 |
No available cluster nodes |
no nodes available |
|
50x |
Any other internal errors |
event search failed |
variable |
Viewing information about the cluster
GET /api/v1/events/clusters
Access: administrator, analyst, and operator.
The main tenant clusters are accessible to all users.
Query parameters (URL Query)
Name |
Data type |
Mandatory |
Description |
Value example |
|---|---|---|---|---|
page |
number |
No |
Page number. Starts with 1. The page size is 250 entries. If the parameter is not specified, the default value is 1. |
1 |
id |
string |
No |
Cluster ID. If the parameter is specified several times, then a list is generated and the logical OR operator is applied |
00000000-0000-0000-0000-000000000000 |
TenantID |
string |
No |
Tenant ID. If the parameter is specified several times, then a list is generated and the logical OR operator is applied. If the user does not have the required role in the specified tenant, then this tenant is ignored. |
00000000-0000-0000-0000-000000000000 |
name |
string |
No |
Cluster name. Case-insensitive regular expression (PCRE). |
cluster |
Response
HTTP code: 200
Format: JSON
|
Possible errors
HTTP code |
Description |
message field value |
details field value |
|---|---|---|---|
400 |
Invalid value of the "page" parameter |
invalid query parameter value |
page |
500 |
Any other internal errors |
variable |
variable |
Resource search
GET /api/v1/resources
Access: administrator, analyst, and operator.
Query parameters (URL Query)
Name |
Data type |
Mandatory |
Description |
Value example |
page |
number |
No |
Page number. Starts with 1. The page size is 250 entries. If the parameter is not specified, the default value is 1. |
1 |
id |
string |
No |
Resource ID. If the parameter is specified several times, then a list is generated and the logical OR operator is applied. |
00000000-0000-0000-0000-000000000000 |
TenantID |
string |
No |
Resource tenant ID. If the parameter is specified several times, then a list is generated and the logical OR operator is applied. If the user does not have the required role in the specified tenant, then this tenant is ignored. |
00000000-0000-0000-0000-000000000000 |
name |
string |
No |
Resource name. Case-insensitive regular expression (PCRE). |
resource |
kind |
string |
No |
Resource type. If the parameter is specified several times, then a list is generated and the logical OR operator is applied |
collector, correlator, storage, activeList, aggregationRule, connector, correlationRule, dictionary, enrichmentRule, destination, filter, normalizer, responseRule, search, agent, proxy, secret |
Response
HTTP code: 200
Format: JSON
|
Possible errors
HTTP code |
Description |
message field value |
details field value |
400 |
Invalid value of the "page" parameter |
invalid query parameter value |
page |
400 |
Invalid value of the "kind" parameter |
invalid kind |
<kind> |
500 |
Any other internal errors |
variable |
variable |
Loading resource file
POST /api/v1/resources/upload
Access: administrator and analyst.
Request body
Encrypted contents of the resource file in binary format.
Response
HTTP code: 200
Format: JSON
File ID. It should be specified in the body of requests for viewing the contents of the file and for importing resources.
|
Possible errors
HTTP code |
Description |
message field value |
details field value |
400 |
The file size exceeds the maximum allowable (64 MB) |
maximum file size is 64 MB |
|
403 |
The user does not have the required roles in any of the tenants |
access denied |
|
500 |
Any other internal errors |
variable |
variable |
Viewing the contents of a resource file
POST /api/v1/resources/toc
Access: administrator, analyst, and operator.
Request body
Format: JSON
Name |
Data type |
Mandatory |
Description |
Value example |
fileID |
string |
Yes |
The file ID obtained as a result of loading the resource file. |
00000000-0000-0000-0000-000000000000 |
password |
string |
Yes |
Resource file password. |
SomePassword!88 |
Response
HTTP code: 200
Format: JSON
File version, list of resources, categories, and folders.
The ID of the retrieved resources must be used when importing.
|
Importing resources
POST /api/v1/resources/import
Access: administrator and analyst.
Request body
Name |
Data type |
Mandatory |
Description |
Value example |
|
fileID |
string |
Yes |
The file ID obtained as a result of loading the resource file. |
00000000-0000-0000-0000-000000000000 |
|
password |
string |
Yes |
Resource file password. |
SomePassword!88 |
|
TenantID |
string |
Yes |
ID of the target tenant |
00000000-0000-0000-0000-000000000000 |
|
actions |
map[string]uint8 |
Yes |
Mapping of the resource ID to the action that must be taken in relation to it. |
0—do not import (used when resolving conflicts) 1—import (should initially be assigned to each resource) 2—replace (used when resolving conflicts)
|
Response
HTTP code |
Body |
|
204 |
|
|
409 |
The imported resources conflict with the existing ones by ID. In this case, you need to repeat the import operation while specifying the following actions for these resources: 0—do not import 2—replace
|
Exporting resources
POST /api/v1/resources/export
Access: administrator and analyst.
Request body
Format: JSON
Name |
Data type |
Mandatory |
Description |
Value example |
ids |
[]string |
Yes |
Resource IDs to be exported |
["00000000-0000-0000-0000-000000000000"] |
password |
string |
Yes |
Exported resource file password |
SomePassword!88 |
TenantID |
string |
Yes |
ID of the tenant that owns the exported resources |
00000000-0000-0000-0000-000000000000 |
Response
HTTP code: 200
Format: JSON
ID of the file with the exported resources. It should be used in a request to download the resource file.
|
Downloading the resource file
GET /api/v1/resources/download/<id>
Here "id" is the file ID obtained as a result of executing a resource export request.
Access: administrator and analyst.
Response
HTTP code: 200
Encrypted contents of the resource file in binary format.
Possible errors
HTTP code |
Description |
message field value |
details field value |
400 |
File ID not specified |
route parameter required |
id |
400 |
The file ID is not a valid UUID |
id is not a valid UUID |
|
403 |
The user does not have the required roles in any of the tenants |
access denied |
|
404 |
File not found |
file not found |
|
406 |
The file is a directory |
not regular file |
|
500 |
Any other internal errors |
variable |
variable |
Search for services
GET /api/v1/services
Access: administrator and analyst.
Query parameters (URL Query)
Name |
Data type |
Mandatory |
Description |
Value example |
page |
number |
No |
Page number. Starts with 1. The page size is 250 entries. If the parameter is not specified, the default value is 1. |
1 |
id |
string |
No |
Service ID. If the parameter is specified several times, then a list is generated and the logical OR operator is applied. |
00000000-0000-0000-0000-000000000000 |
TenantID |
string |
No |
Service tenant ID. If the parameter is specified several times, then a list is generated and the logical OR operator is applied. If the user does not have the required role in the specified tenant, then this tenant is ignored. |
00000000-0000-0000-0000-000000000000 |
name |
string |
No |
Service name. Case-insensitive regular expression (PCRE). |
service |
kind |
string |
No |
Service type. If the parameter is specified several times, then a list is generated and the logical OR operator is applied. |
collector, correlator, storage, agent |
fqdn |
string |
No |
Service FQDN. Case-insensitive regular expression (PCRE). |
hostname ^hostname.example.com$ |
paired |
bool |
No |
Display only those services that executed the first start. If the parameter is present in the URL query, then its value is assumed to be true. The values specified by the user are ignored. Example: /api/v1/services?paired |
|
Response
HTTP code: 200
Format: JSON
|
Possible errors
HTTP code |
Description |
message field value |
details field value |
400 |
Invalid value of the "page" parameter |
invalid query parameter value |
page |
400 |
Invalid value of the "kind" parameter |
invalid kind |
<kind> |
500 |
Any other internal errors |
variable |
variable |
Tenant search
GET /api/v1/tenants
Only tenants available to the user are displayed.
Access: administrator and analyst.
Query parameters (URL Query)
Name |
Data type |
Mandatory |
Description |
Value example |
page |
number |
No |
Page number. Starts with 1. The page size is 250 entries. If the parameter is not specified, the default value is 1. |
1 |
id |
string |
No |
Tenant ID. If the parameter is specified several times, then a list is generated and the logical OR operator is applied. |
00000000-0000-0000-0000-000000000000 |
name |
string |
No |
Tenant name. Case-insensitive regular expression (PCRE). |
tenant |
main |
bool |
No |
Only display the main tenant. If the parameter is present in the URL query, then its value is assumed to be true. The values specified by the user are ignored. Example: /api/v1/tenants?main |
|
Response
HTTP code: 200
Format: JSON
|
Possible errors
HTTP code |
Description |
message field value |
details field value |
400 |
Invalid value of the "page" parameter |
invalid query parameter value |
page |
500 |
Any other internal errors |
variable |
variable |
View token bearer information
GET /api/v1/users/whoami
Response
HTTP code: 200
Format: JSON
|
Dictionary updating in services
POST /api/v1/dictionaries/update
You can update only dictionaries in dictionary resources of the table type.
Access: administrator and analyst.
Query parameters (URL Query)
Name |
Data type |
Mandatory |
Description |
Value example |
collectorID |
string |
No |
IDs of the collectors in which the dictionary will be updated. You can specify multiple values, in which case the dictionary will be updated in each of the services. |
00000000-0000-0000-0000-000000000000 |
correlatorID |
string |
No |
IDs of the correlators in which the dictionary will be updated. You can specify multiple values, in which case the dictionary will be updated in each of the services. |
00000000-0000-0000-0000-000000000000 |
dictionaryID |
string |
Yes |
ID of the dictionary that will be updated. |
00000000-0000-0000-0000-000000000000 |
If an update in one of the services ends with an error, this does not interrupt updates in the other services.
Request body
Multipart field name |
Data type |
Mandatory |
Description |
Value example |
file |
CSV file |
Yes |
The request contains a CSV file. Data of the existing dictionary is being replaced with data from this file. The first line of the CSV file containing the column names must not be changed. |
key columns,column1,column2 key1,k1col1,k1col2 key2,k2col1,k2col2 |
Response
HTTP code: 200
Format: JSON
type Response struct { ServicesFailedToUpdate []UpdateError `json:"servicesFailedToUpdate"` } type UpdateError struct { ID string `json:"id"` Err error `json:"err"` } |
Returns only errors for services in which the dictionaries have not been updated.
Possible errors
HTTP code |
Description |
message field value |
details field value |
400 |
Invalid request body |
request body decode failed |
Error |
400 |
Null count of dictionary lines |
request body required |
|
400 |
Dictionary ID not specified |
invalid value |
dictionaryID |
400 |
Incorrect value of dictionary line |
invalid value |
rows or rows[i] |
400 |
Dictionary with the specified ID has an invalid type (not table) |
can only update table dictionary |
|
400 |
Attempt to change dictionary columns |
columns must not change with update |
|
403 |
No access to requested resource |
access denied |
|
404 |
Service not found |
service not found |
|
404 |
Dictionary not found |
dictionary not found |
Service ID |
500 |
Any other internal errors |
variable |
variable |
Dictionary retrieval
GET /api/v1/dictionaries
You can get only dictionaries in dictionary resources of the table type.
Access: administrator and analyst.
Query parameters (URL Query)
Name |
Data type |
Mandatory |
Description |
Value example |
dictionaryID |
string |
Yes |
ID of the dictionary that will be received |
00000000-0000-0000-0000-000000000000 |
Response
HTTP code: 200
Format: text/plain; charset=utf-8
A CSV file is returned with the dictionary data in the response body.
Page top