Documentation
Get reports. (1 day by default)
Supported search fields:
NOTE:
Report item has field "commit_id" which shows the LATEST commit for the whole device.
It is not related to the commit where actual config change was declared, and for which change this report is about.
NOTE:
By default search is limited to the last 24h. This doesn't apply if search contain report_id, bundle_commit_id or commit_sha_real fields
NOTE:
For the grouped reports report_id and log values are equal to the the newest record in the group (if default time sort is used - from newest to oldest).
For example: user created a commit with id: AAA for the NTP configuration, then user created some more commits: BBB - ssh settings, CCC - firewall.
When agent would report about the status of applying the NTP settings, it will use CCC as a commit_id, because CCC is the last (newest) commit which triggered configuration regeneration.
(we regenerate config for all devices, even if change was only for subgroup)
In order to get reports for the actual change from AAA commit use bundle_commit_id field. The value there is equal to the one of the changes in the AAA commit.
To get reports for all changes in commit - use commit_sha_real. For that we first find the changes which declared in the commit, and then collect reports for all changes in it.
- report_id - id of the report (exact match)
- bundle_commit_id - array of ids of the change (sha) (exact match)
- commit_sha_real - (!) return reports where bundle_commit_id field is equal to one of the items in the change array of commit. See note above about commit_id.
- pub_key_digest - array of the devices id (exact match)
- node_id - node_id (exact match by ancestors, incl. device itself)
- title - hostname or device name (substring)
- text - report text (substring)
- labels_include - config change type, array, for example: ["software_management", "ntp"]
- labels_exclude - config change type, array, for example: ["software_management", "ntp"]
- status - "new" or "read"
- severity - array, for example ["CRIT", "ERR"]. If not set - return all severities available. If empty array - nothing will be selected
- start_date - Start date UTC, format: YYYY-MM-DD hh:ii:ss (2019-03-18 10:35:48)
- end_date - End date UTC, format: YYYY-MM-DD hh:ii:ss (2019-03-18 10:35:48)
Supported sort fields:
- title - host title (alphabetical)
- device_name - device name with fallback to host title (alphabetical)
- pub_key_digest (alphabetical)
- severity (alphabetical)
- labels (alphabetical)
- ts (integer)
- reports_count (integer, only in group_mode=true)
- bundle_commit_id (alphabetical)
Parameters
Parameter |
Type |
Required? |
Format |
Description |
search |
json |
false |
|
Search conditions. Supported fields: ^see description on top |
sort_field |
string |
false |
|
Field to sort, ts by default |
sort_direction |
string |
false |
|
Sort direction, desc by default |
items_per_page |
integer |
false |
|
Maximum number of records in result, default 30, max 1000 |
offset |
integer |
false |
|
Offset, default 0 |
group_mode |
boolean |
false |
|
Group simmilar items (deduplication), default false |
Status Codes
Status Code |
Description |
200 |
|
400 |
- Returned if required parameters are not set correctly
|
401 |
- Returned when the user is not authenticated
|
403 |
- Returned if access denied
|
500 |
- Returned for internal server error
|