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.

💡

Tip: All endpoints require workspace id as a query parameter, you can find your workspace id on the workspace settings page (opens in a new tab)

Examples:

Listing notification history for your workspace:

$ TOKEN="<your token>"
$ WKSPCID="<your workspace id>"
 
$ curl -H "Authorization: Basic ${TOKEN}" -H "Content-type: application/json" "https://api.runreveal.com/notification-history/list?workspaceid=${WKSPCID}"

Listing notification history for a specific alert:

$ TOKEN="<your token>"
$ WKSPCID="<your workspace id>"
$ ALERTID="<your alert id>"
 
$ curl -H "Authorization: Basic ${TOKEN}" -H "Content-type: application/json" "https://api.runreveal.com/notification-history/list/${ALERTID}?workspaceid=${WKSPCID}"

Going from notification history entry to alert details

$ TOKEN="<your token>"
$ WKSPCID="<your workspace id>"
 
$ RESULT=$(curl -H "Authorization: Basic ${TOKEN}" -H "Content-type: application/json" "https://api.runreveal.com/notification-history/list?workspaceid=${WKSPCID}")
$ ALERTID=$(echo $RESULT | jq -r '.result.[0].alertID')
$ curl -H "Authorization: Basic ${TOKEN}" -H "Content-type: application/json" "https://api.runreveal.com/logs/query/v3?workspaceid=${WKSPCID}" --data-raw "{\"query\": \"SELECT * FROM detections WHERE scheduledRunID == '${ALERTID}'\"}"

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:

{
    "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:

Name	Description	Required
workspaceid	Your workspace ID	Yes
limit	Maximum results to return	No, default 100

Response:

{
    "success": bool,
    "result": List<Notification History Entry>
}

GET `/notification-history/list/{alertID}`