RunReveal

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:
$ TOKEN="<your token>"
 
$ curl -H "Authorization: Basic ${TOKEN}" -H "Content-type: application/json" "https://api.runreveal.com/notification-history/list"
  • Listing notification history for a specific alert:
$ TOKEN="<your token>"
$ ALERTID="<your alert id>"
 
$ curl -H "Authorization: Basic ${TOKEN}" -H "Content-type: application/json" "https://api.runreveal.com/notification-history/list-by-alertid?alertID=${ALERTID}"
  • Going from notification history entry to alert details
$ TOKEN="<your token>"
 
$ RESULT=$(curl -H "Authorization: Basic ${TOKEN}" -H "Content-type: application/json" "https://api.runreveal.com/notification-history/list")
$ ALERTID=$(echo $RESULT | jq -r '.result.values[0].alertID')
$ curl -H "Authorization: Basic ${TOKEN}" -H "Content-type: application/json" "https://api.runreveal.com/logs/query/v3" --data-raw "{\"query\": \"SELECT * FROM detections WHERE scheduledRunID == '${ALERTID}'\"}"

Reference

Resources

Notification History Entry

Parameters:

NameTypeDescription
idstringAutogenerated ID
workspaceIDstringYour workspace ID
alertIDstringID of alert that fired this notification
detectionDisplayNamestringName of the detection that fired this notification
channelstringNotification channel, e.g. Jira, Linear, Slack, etc
statusstringStatus of notification ("sent", "successful", "error", or "retrying")
metamap<string, string>Metadata about a notification, including created linear or jira issues
createdAttimestampWhen the notification was created

Examples:

{
    "id": "2vuLtZJeKD5rzNUfONbZRo8ysDV",
    "workspaceID": "2vuJirrWU4zlZTxs4pfYPbmsLOI",
    "alertID": "2vuLstBUci790Qimp7tdqEIzNuF",
    "detectionDisplayName": "My Detection",
    "channel": "linear",
    "status": "success",
    "meta": {
        "linearIssue": "NOT-41",
        "linearLink": "https://linear.app/notification-testing/issue/NOT-41/runreveal-detection-alert"
    },
    "createdAt": "2025-04-18T15:30:27.529124Z"
}

{
    "id": "2vuLtQhMcGMTG7zqr99icIINmzf",
    "workspaceID": "2vuJirrWU4zlZTxs4pfYPbmsLOI",
    "alertID": "2vuLstBUci790Qimp7tdqEIzNuF",
    "detectionDisplayName": "My Detection",
    "channel": "jira",
    "status": "success",
    "meta": {
        "jiraIssue": "SMP-66",
        "jiraLink": "https://company.atlassian.net/browse/SMP-66"
    },
    "createdAt": "2025-04-18T15:30:26.320842Z"
}

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.

NameDescriptionRequired
searchFree-text searchNo
fromCreated-at lower bound, RFC3339No
toCreated-at upper bound, RFC3339No
statusSend outcome: sent, success, error, or retryingNo
channelDelivery channel type, for example email or slackNo
notificationNameNotification channel config nameNo
templateNameTemplate used to render the notificationNo
detectionDisplay name of the detection that firedNo
sortnewest or oldestNo
statusModeexclude negates statusNo
channelModeexclude negates channelNo
notificationNameModeexclude negates notificationNameNo
templateNameModeexclude negates templateNameNo
detectionModeexclude negates detectionNo
limitPage size. Default 50, maximum 100No
cursorPass the previous response's next value to read the following pageNo

Response. prev and next are omitted when there is no cursor.

{
    "success": true,
    "result": {
        "values": [],
        "prev": "<cursor for this page>",
        "next": "<cursor for the next page>"
    }
}

values is a list of notification history entries.

GET /notification-history/list-by-alertid?alertID=

Query Parameters:

NameDescriptionRequired
alertIDAlert to list notifications forYes

Response:

{
    "success": true,
    "result": {
        "values": []
    }
}

On this page