Using The API
Authentication with the API is done using API tokens which you can generate in the UI. These tokens are scoped to specficic roles which are authorized to perform different sets of actions. For working with enrichments, you will want to create a token with either the admin role (which has full read/write/delete access) or the analyst role (which has read/edit permissions).
Once you have generated a token, you can use it by setting the Authorization header:
Authorization: Basic <TOKEN>
Making Requests
Requests can be made by appending the desired endpoint to the api base url (https://api.runreveal.com) and setting the appropriate
Authorization header. For POST endpoints, you should also set the appropriate Content-type header, application/json for all
enrichment endpoints.
Examples:
- Listing notification history for your workspace:
- Listing notification history for a specific alert:
- Going from notification history entry to alert details
Reference
Resources
Notification History Entry
Parameters:
| Name | Type | Description |
|---|---|---|
| id | string | Autogenerated ID |
| workspaceID | string | Your workspace ID |
| alertID | string | ID of alert that fired this notification |
| detectionDisplayName | string | Name of the detection that fired this notification |
| channel | string | Notification channel, e.g. Jira, Linear, Slack, etc |
| status | string | Status of notification ("sent", "successful", "error", or "retrying") |
| meta | map<string, string> | Metadata about a notification, including created linear or jira issues |
| createdAt | timestamp | When the notification was created |
Examples:
Endpoints
GET /notification-history/list
Query parameters. Repeat a list parameter to pass more than one value. Set a *Mode parameter to exclude to negate the matching filter.
| Name | Description | Required |
|---|---|---|
| search | Free-text search | No |
| from | Created-at lower bound, RFC3339 | No |
| to | Created-at upper bound, RFC3339 | No |
| status | Send outcome: sent, success, error, or retrying | No |
| channel | Delivery channel type, for example email or slack | No |
| notificationName | Notification channel config name | No |
| templateName | Template used to render the notification | No |
| detection | Display name of the detection that fired | No |
| sort | newest or oldest | No |
| statusMode | exclude negates status | No |
| channelMode | exclude negates channel | No |
| notificationNameMode | exclude negates notificationName | No |
| templateNameMode | exclude negates templateName | No |
| detectionMode | exclude negates detection | No |
| limit | Page size. Default 50, maximum 100 | No |
| cursor | Pass the previous response's next value to read the following page | No |
Response. prev and next are omitted when there is no cursor.
values is a list of notification history entries.
GET /notification-history/list-by-alertid?alertID=
Query Parameters:
| Name | Description | Required |
|---|---|---|
| alertID | Alert to list notifications for | Yes |
Response: