API

Energy SOAR exposes a REST API for integrating external tools, automating case management, and ingesting alerts from third-party systems. All endpoints accept and return JSON.

Examples in this guide use local addresses. For external access, replace http://127.0.0.1 with the server IP or hostname under HTTPS.

Base API Guide

Authentication

Most API calls require authentication. Credentials can be provided using a session cookie, an API key or directly using HTTP basic authentication (when enabled).

Using API key

Session cookie is suitable for browser authentication, not for a dedicated tool. The easiest solution if you want to write a tool that leverages Energy SOAR Base’s API is to use API key authentication. API keys can be generated using the Web interface of the product, under the user admin area. For example, to list cases, use the following curl command:

curl -H 'Authorization: Bearer ***API*KEY***' http://127.0.0.1:9000/base/api/case

Using basic authentication

Energy SOAR Base also supports basic authentication (disabled by default). You can enable it by adding auth.method.basic=true in the configuration file.

curl -u mylogin:mypassword http://127.0.0.1:9000/base/api/case

Alert

Model definition

Required attributes:

title (text) : title of the alert
description (text) : description of the alert
severity (number) : severity of the alert (1: low; 2: medium; 3: high; 4: critical) default=2
date (date) : date and time when the alert was raised default=now
tags (multi-string) : case tags default=empty
tlp (number) : TLP (0: white; 1: green; 2: amber; 3: red) default=2
pap (number) : PAP (0: white; 1: green; 2: amber; 3: red) default=2
type (string) : type of the alert (read only)
source (string) : source of the alert (read only)
sourceRef (string) : source reference of the alert (read only)
artifacts (multi-artifact) : artifact of the alert. It is a array of JSON object containing artifact attributes default=empty
follow (boolean) : if true, the alert becomes active when updated default=true

Optional attributes:

caseTemplate (string) : case template to use when a case is created from this alert. If the alert specifies a non-existent case template or doesn’t supply one, Energy SOAR Base will import the alert into a case using a case template that has the exact same name as the alert’s type if it exists. For example, if you raise an alert with a type value of splunk and you do not provide the caseTemplate attribute or supply a non-existent one (for example splink), Energy SOAR Base will import the alert using the case template called splunk if it exists. Otherwise, the alert will be imported using an empty case (i.e. from scratch).

Attributes generated by the backend:

status (AlertStatus) : computed status of the alert (New, Updated, Ignored, Imported). Derived from the read flag and whether the alert is linked to a case. Cannot be set directly.
lastSyncDate (date) : date of the last synchronization
case (string) : id of the case, if created

Alert ID is computed from type, source andsourceRef.

Alert Manipulation

Alert methods

HTTP Method	URI	Action
GET	/api/alert	List alerts
POST	/api/alert/_search	Find alerts
POST	/api/alert/_stats	Compute stats on alerts
POST	/api/alert	Create an alert
GET	/api/alert/:alertId	Get an alert
PATCH	/api/alert/:alertId	Update an alert
DELETE	/api/alert/:alertId	Delete an alert
POST	/api/alert/:alertId/markAsRead	Mark an alert as read
POST	/api/alert/:alertId/markAsUnread	Mark an alert as unread
POST	/api/alert/:alertId/createCase	Create a case from an alert
POST	/api/alert/:alertId/follow	Follow an alert
POST	/api/alert/:alertId/unfollow	Unfollow an alert
POST	/api/alert/:alertId/merge/:caseId	Merge an alert in a case)
POST	/api/alert/merge/_bulk	Merge several alerts in one case

Get an alert

An alert’s details can be retrieve using the url:

GET     /api/alert/:alertId

The alert ID is obtained by List alerts or Find alerts API.

If the parameter similarity is set to “1” or “true”, this API returns information on cases which have similar observables. With this feature, output will contain the similarCases attribute which list case details with:

artifactCount: number of observables in the original case
iocCount: number of observables marked as IOC in original case
similarArtifactCount: number of observables which are in alert and in case
similarIocCount: number of IOCs which are in alert and in case

warning IOCs are observables

Examples

Get alert without similarity data:

curl -H 'Authorization: Bearer ***API*KEY***' http://127.0.0.1:9000/base/api/alert/ce2c00f17132359cb3c50dfbb1901810

It returns:

{
    "_id": "ce2c00f17132359cb3c50dfbb1901810",
    "_type": "alert",
    "artifacts": [],
    "createdAt": 1495012062014,
    "createdBy": "myuser",
    "date": 1495012062016,
    "description": "N/A",
    "follow": true,
    "id": "ce2c00f17132359cb3c50dfbb1901810",
    "lastSyncDate": 1495012062016,
    "severity": 2,
    "source": "instance1",
    "sourceRef": "alert-ref",
    "status": "New",
    "title": "New Alert",
    "tlp": 2,
    "type": "external",
    "user": "myuser"
}

Get alert with similarity data:

curl -H 'Authorization: Bearer ***API*KEY***' http://127.0.0.1:9000/base/api/alert/ce2c00f17132359cb3c50dfbb1901810?similarity=1

It returns:

{
    "_id": "ce2c00f17132359cb3c50dfbb1901810",
    "_type": "alert",
    "artifacts": [],
    "createdAt": 1495012062014,
    "createdBy": "myuser",
    "date": 1495012062016,
    "description": "N/A",
    "follow": true,
    "id": "ce2c00f17132359cb3c50dfbb1901810",
    "lastSyncDate": 1495012062016,
    "severity": 2,
    "source": "instance1",
    "sourceRef": "alert-ref",
    "status": "New",
    "title": "New Alert",
    "tlp": 2,
    "type": "external",
    "user": "myuser",
    "similarCases": [
        {
            "_id": "AVwwrym-Rw5vhyJUfdJW",
            "artifactCount": 5,
            "endDate": null,
            "id": "AVwwrym-Rw5vhyJUfdJW",
            "iocCount": 1,
            "resolutionStatus": null,
            "severity": 1,
            "similarArtifactCount": 2,
            "similarIocCount": 1,
            "startDate": 1495465039000,
            "status": "Open",
            "tags": [
                "src:MISP"
            ],
            "caseId": 1405,
            "title": "TEST",
            "tlp": 2
        }
    ]
}

Create an alert

An alert can be created using the following url:

POST     /api/alert

Required case attributes (cf. models) must be provided.

If an alert with the same tuple type, source and sourceRef already exists, Energy SOAR Base will refuse to create it.

This call returns attributes of the created alert.

Examples

Creation of a simple alert:

curl -XPOST -H 'Authorization: Bearer ***API*KEY***' -H 'Content-Type: application/json' http://127.0.0.1:9000/base/api/alert -d '{
  "title": "New Alert",
  "description": "N/A",
  "type": "external",
  "source": "instance1",
  "sourceRef": "alert-ref"
}'

It returns:

{
    "_id": "ce2c00f17132359cb3c50dfbb1901810",
    "_type": "alert",
    "artifacts": [],
    "createdAt": 1495012062014,
    "createdBy": "myuser",
    "date": 1495012062016,
    "description": "N/A",
    "follow": true,
    "id": "ce2c00f17132359cb3c50dfbb1901810",
    "lastSyncDate": 1495012062016,
    "severity": 2,
    "source": "instance1",
    "sourceRef": "alert-ref",
    "status": "New",
    "title": "New Alert",
    "tlp": 2,
    "type": "external",
    "user": "myuser"
}

Creation of another alert:

curl -XPOST -H 'Authorization: Bearer ***API*KEY***' -H 'Content-Type: application/json' http://127.0.0.1:9000/base/api/alert -d '{
  "title": "Other alert",
  "description": "alert description",
  "type": "external",
  "source": "instance1",
  "sourceRef": "alert-ref",
  "severity": 3,
  "tlp": 3,
  "artifacts": [
    { "dataType": "ip", "data": "127.0.0.1", "message": "localhost" },
    { "dataType": "domain", "data": "energysoar.com", "tags": ["home", "file"] },
    { "dataType": "file", "data": "logo.svg;image/svg+xml;PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0idXRmLTgiPz4NCjwhLS0gR2VuZXJhdG9yOiBBZG9iZSBJbGx1c3RyYXRvciAxOC4wLjAsIFNWRyBFeHBvcnQgUGx1Zy1JbiAuIFNWRyBWZXJzaW9uOiA2LjAwIEJ1aWxkIDApICAtLT4NCjwhRE9DVFlQRSBzdmcgUFVCTElDICItLy9XM0MvL0RURCBTVkcgMS4xLy9FTiIgImh0dHA6Ly93d3cudzMub3JnL0dyYXBoaWNzL1NWRy8xLjEvRFREL3N2ZzExLmR0ZCI+DQo8c3ZnIHZlcnNpb249IjEuMSIgaWQ9IkxheWVyXzEiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIgeG1sbnM6eGxpbms9Imh0dHA6Ly93d3cudzMub3JnLzE5OTkveGxpbmsiIHg9IjBweCIgeT0iMHB4Ig0KCSB2aWV3Qm94PSIwIDAgNjI0IDIwMCIgZW5hYmxlLWJhY2tncm91bmQ9Im5ldyAwIDAgNjI0IDIwMCIgeG1sOnNwYWNlPSJwcmVzZXJ2ZSI+DQo8Zz4NCgk8Zz4NCgkJPHBhdGggZmlsbD0iIzE1MTYzMiIgZD0iTTE3Mi4yLDczdjY2LjRoLTIwLjdWNzNoLTI3LjRWNTQuOGg3NS41VjczSDE3Mi4yeiIvPg0KCQk8cGF0aCBmaWxsPSIjMTUxNjMyIiBkPSJNMjcyLjgsMTAwLjV2MzguOWgtMjAuMXYtMzQuNmMwLTcuNC00LjQtMTIuNS0xMS0xMi41Yy03LjgsMC0xMyw1LjQtMTMsMTcuN3YyOS40aC0yMC4yVjQ4LjVoMjAuMlY4Mg0KCQkJYzQuOS01LDExLjUtNy45LDE5LjYtNy45QzI2Myw3NC4xLDI3Mi44LDg0LjYsMjcyLjgsMTAwLjV6Ii8+DQoJCTxwYXRoIGZpbGw9IiMxNTE2MzIiIGQ9Ik0zNTYuMywxMTIuOGgtNDYuNGMxLjYsNy42LDYuOCwxMi4yLDEzLjYsMTIuMmM0LjcsMCwxMC4xLTEuMSwxMy41LTcuM2wxNy45LDMuNw0KCQkJYy01LjQsMTMuNC0xNi45LDE5LjgtMzEuNCwxOS44Yy0xOC4zLDAtMzMuNC0xMy41LTMzLjQtMzMuNmMwLTE5LjksMTUuMS0zMy42LDMzLjYtMzMuNmMxNy45LDAsMzIuMywxMi45LDMyLjcsMzMuNlYxMTIuOHoNCgkJCSBNMzEwLjMsMTAwLjVoMjYuMWMtMS45LTYuOC02LjktMTAtMTIuNy0xMEMzMTgsOTAuNSwzMTIuMiw5NCwzMTAuMywxMDAuNXoiLz4NCgkJPHBhdGggZmlsbD0iI0YzRDAyRiIgZD0iTTQ0NS41LDEzOS4zaC0yMC43di0zMy40aC0zNS42djMzLjRoLTIwLjhWNTQuOGgyMC44djMyLjloMzUuNlY1NC44aDIwLjdWMTM5LjN6Ii8+DQoJCTxwYXRoIGZpbGw9IiNGM0QwMkYiIGQ9Ik00NzguNiw1Ny4zYzAsNi40LTQuOSwxMS4yLTExLjcsMTEuMmMtNi44LDAtMTEuNi00LjgtMTEuNi0xMS4yYzAtNi4yLDQuOC0xMS41LDExLjYtMTEuNQ0KCQkJQzQ3My43LDQ1LjgsNDc4LjYsNTEuMSw0NzguNiw1Ny4zeiBNNDU2LjgsMTM5LjNWNzZoMjAuMnY2My4zSDQ1Ni44eiIvPg0KCQk8cGF0aCBmaWxsPSIjRjNEMDJGIiBkPSJNNTI4LjUsMTM5LjNoLTIwLjZsLTI2LjItNjMuNUg1MDNsMTUuMywzOS4xbDE1LjEtMzkuMWgyMS4zTDUyOC41LDEzOS4zeiIvPg0KCQk8cGF0aCBmaWxsPSIjRjNEMDJGIiBkPSJNNjE4LjMsMTEyLjhoLTQ2LjRjMS42LDcuNiw2LjgsMTIuMiwxMy42LDEyLjJjNC43LDAsMTAuMS0xLjEsMTMuNS03LjNsMTcuOSwzLjcNCgkJCWMtNS40LDEzLjQtMTYuOSwxOS44LTMxLjQsMTkuOGMtMTguMywwLTMzLjQtMTMuNS0zMy40LTMzLjZjMC0xOS45LDE1LjEtMzMuNiwzMy42LTMzLjZjMTcuOSwwLDMyLjMsMTIuOSwzMi43LDMzLjZWMTEyLjh6DQoJCQkgTTU3Mi4yLDEwMC41aDI2LjFjLTEuOS02LjgtNi45LTEwLTEyLjctMTBDNTc5LjksOTAuNSw1NzQuMSw5NCw1NzIuMiwxMDAuNXoiLz4NCgk8L2c+DQoJPGc+DQoJCTxnPg0KCQkJPHBhdGggZmlsbD0iI0YzRDAyRiIgZD0iTTU3LDcwLjNjNi42LDAsMTIuMiw2LjQsMTIuMiwxMS41YzAsNi4xLTEwLDYuNi0xMiw2LjZsMCwwYy0yLjIsMC0xMi0wLjMtMTItNi42DQoJCQkJQzQ0LjgsNzYuNyw1MC40LDcwLjMsNTcsNzAuM0w1Nyw3MC4zeiBNNDQuMSwxMzMuNmwyNS4yLDAuMWwyLjIsNS42bC0yOS42LTAuMUw0NC4xLDEzMy42eiBNNDcuNiwxMjUuNmwyLjItNS42bDE0LjIsMGwyLjIsNS42DQoJCQkJTDQ3LjYsMTI1LjZ6IE01MywxMTIuMWwzLjktOS41bDMuOSw5LjVMNTMsMTEyLjF6IE0yMy4zLDE0My42Yy0xLjcsMC0zLjItMC4zLTQuNi0xYy02LjEtMi43LTkuMy05LjgtNi41LTE1LjkNCgkJCQljNi45LTE2LjYsMjcuNy0yOC41LDM5LTMwLjJsLTcuNCwxOC4xbDAsMEwzOC4zLDEyOGwwLDBsLTMuNSw4LjFDMzIuNiwxNDAuNywyOC4yLDE0My42LDIzLjMsMTQzLjZMMjMuMywxNDMuNnogTTU2LjcsMTYxLjgNCgkJCQljLTguMSwwLTE0LjctNS45LTE3LjMtMTVsMzQuNywwLjFDNzEuNCwxNTYuMiw2NC44LDE2MS44LDU2LjcsMTYxLjhMNTYuNywxNjEuOHogTTk1LDE0Mi45Yy0xLjUsMC43LTMuMiwxLTQuNiwxDQoJCQkJYy00LjksMC05LjMtMy0xMS4yLTcuNmwtMy40LTguMWwwLDBsLTUuMS0xMi43YzAtMC41LTAuMi0xLTAuNS0xLjVsLTctMTcuNmMxMS4yLDIsMzIsMTQsMzguOCwzMC41DQoJCQkJQzEwNC4zLDEzMy4zLDEwMS4zLDE0MC40LDk1LDE0Mi45TDk1LDE0Mi45eiIvPg0KCQkJDQoJCQkJPGxpbmUgZmlsbD0ibm9uZSIgc3Ryb2tlPSIjRjNEMDJGIiBzdHJva2Utd2lkdGg9IjUuMjE0NiIgc3Ryb2tlLWxpbmVjYXA9InJvdW5kIiBzdHJva2UtbWl0ZXJsaW1pdD0iMTAiIHgxPSI0Ny44IiB5MT0iNjcuNSIgeDI9IjQzLjciIHkyPSI1OC45Ii8+DQoJCQkNCgkJCQk8bGluZSBmaWxsPSJub25lIiBzdHJva2U9IiNGM0QwMkYiIHN0cm9rZS13aWR0aD0iNS4yMTQ2IiBzdHJva2UtbGluZWNhcD0icm91bmQiIHN0cm9rZS1taXRlcmxpbWl0PSIxMCIgeDE9IjY2LjEiIHkxPSI2Ny41IiB4Mj0iNzAuMSIgeTI9IjU4LjkiLz4NCgkJPC9nPg0KCQkNCgkJCTxwb2x5bGluZSBmaWxsPSJub25lIiBzdHJva2U9IiNGM0QwMkYiIHN0cm9rZS13aWR0aD0iNS4yMTQ2IiBzdHJva2UtbGluZWNhcD0icm91bmQiIHN0cm9rZS1saW5lam9pbj0icm91bmQiIHN0cm9rZS1taXRlcmxpbWl0PSIxMCIgcG9pbnRzPSINCgkJCTk0LjgsMTAzLjUgMTA1LjUsODQuMiA4MS4xLDQyLjEgMzIuNyw0Mi4xIDguMyw4NC4yIDIwLDEwMy41IAkJIi8+DQoJPC9nPg0KPC9nPg0KPC9zdmc+DQo=", "message": "logo" }
  ],
  "caseTemplate": "external-alert"
}'

Merge an alert

An alert can be merge in a case using the URL:

POST     /api/alert/:alertId/merge/:caseId

Each observable of the alert will be added to the case if it doesn’t exist in the case. The description of the alert will be appended to the case’s description.

The HTTP response contains the updated case.

Example

Merge the alert ce2c00f17132359cb3c50dfbb1901810 in case AVXeF-pZmeHK_2HEYj2z:

curl -XPOST -H 'Authorization: Bearer ***API*KEY***' http://127.0.0.1:9000/base/api/alert/ce2c00f17132359cb3c50dfbb1901810/merge/AVXeF-pZmeHK_2HEYj2z

The call returns:

{
  "severity": 3,
  "createdBy": "myuser",
  "createdAt": 1488918582777,
  "caseId": 1,
  "title": "My first case",
  "startDate": 1488918582836,
  "owner": "myuser",
  "status": "Open",
  "description": "This case has been created by my custom script

  ### Merged with alert #10 my alert title

  This is my alert description",
  "user": "myuser",
  "tlp": 2,
  "flag": false,
  "id": "AVXeF-pZmeHK_2HEYj2z",
  "_id": "AVXeF-pZmeHK_2HEYj2z",
  "_type":"case"
}

Bulk merge alert

This API merge several alerts with one case:

POST     /api/alert/merge/_bulk

The observable of each alert listed in alertIds field will be imported into the case (identified by caseId field). The description of the case is not modified.

The HTTP response contains the case.

Example

Merge the alerts ce2c00f17132359cb3c50dfbb1901810 and a97148693200f731cfa5237ff2edf67b in case AVXeF-pZmeHK_2HEYj2z:

curl -XPOST -H 'Authorization: Bearer ***API*KEY***' -H 'Content-Type: application/json' http://127.0.0.1:9000/base/api/alert/merge/_bulk -d '{
  "caseId": "AVXeF-pZmeHK_2HEYj2z",
  "alertIds": ["ce2c00f17132359cb3c50dfbb1901810", "a97148693200f731cfa5237ff2edf67b"]
}'

The call returns:

{
  "severity": 3,
  "createdBy": "myuser",
  "createdAt": 1488918582777,
  "caseId": 1,
  "title": "My first case",
  "startDate": 1488918582836,
  "owner": "myuser",
  "status": "Open",
  "description": "This case has been created by my custom script",
  "user": "myuser",
  "tlp": 2,
  "flag": false,
  "id": "AVXeF-pZmeHK_2HEYj2z",
  "_id": "AVXeF-pZmeHK_2HEYj2z",
  "_type":"case"
}

Observable

Model definition

Required attributes:

data (string) : content of the observable (read only). An observable can’t contain data and attachment attributes
attachment (attachment) : observable file content (read-only). An observable can’t contain data and attachment attributes
dataType (enumeration) : type of the observable (read only)
message (text) : description of the observable in the context of the case
startDate (date) : date of the observable creation default=now
tlp (number) : TLP (0: white; 1: green; 2: amber; 3: red) default=2
ioc (boolean) : indicates if the observable is an IOC default=false
sighted (boolean) : indicates if the observable has been sighted default=false

Optional attributes:

tags (multi-string) : observable tags
ignoreSimilarity (boolean) : if true, this observable is excluded from similarity calculations

Observable manipulation

Observable methods

HTTP Method	URI	Action
POST	/api/case/artifact/_search	Find observables
POST	/api/case/artifact/_stats	Compute stats on observables
POST	/api/case/:caseId/artifact	Create an observable
GET	/api/case/artifact/:artifactId	Get an observable
DELETE	/api/case/artifact/:artifactId	Remove an observable
PATCH	/api/case/artifact/:artifactId	Update an observable
GET	/api/case/artifact/:artifactId/similar	Get list of similar observables
PATCH	/api/case/artifact/_bulk	Update observables in bulk

List Observables of a Case

Complete observable list of a case can be retrieved by performing a search:

POST     /api/case/artifact/_search

Parameters:

query: { "_parent": { "_type": "case", "_query": { "_id": "<<caseId>>" } } }
range: all

<<caseId>> must be replaced by case id (not the case number !)

Case

Model definition

Required attributes:

title (text) : title of the case
description (text) : description of the case
severity (number) : severity of the case (1: low; 2: medium; 3: high; 4: critical) default=2
startDate (date) : date and time of the begin of the case default=now
owner (string) : user to whom the case has been assigned default=use who create the case
flag (boolean) : flag of the case default=false
tlp (number) : TLP (0: white; 1: green; 2: amber; 3: red) default=2
pap (number) : PAP (0: white; 1: green; 2: amber; 3: red) default=2
tags (multi-string) : case tags default=empty

Optional attributes:

resolutionStatus (caseResolutionStatus) : resolution status of the case (Indeterminate, FalsePositive, TruePositive, Other or Duplicated)
impactStatus (caseImpactStatus) : impact status of the case (NoImpact, WithImpact or NotApplicable)
summary (text) : summary of the case, to be provided when closing a case
endDate (date) : resolution date
metrics (metrics) : list of metrics

Attributes generated by the backend:

status (caseStatus) : status of the case (Open, Resolved or Duplicated) default=Open
caseId (number) : Id of the case (auto-generated)
mergeInto (string) : ID of the case created by the merge
mergeFrom (multi-string) : IDs of the cases that were merged

Case Manipulation

Case methods

HTTP Method	URI	Action
GET	/api/case	List cases
POST	/api/case/_search	Find cases
PATCH	/api/case/_bulk	Update cases in bulk
POST	/api/case/_stats	Compute stats on cases
POST	/api/case	Create a case
GET	/api/case/:caseId	Get a case
PATCH	/api/case/:caseId	Update a case
DELETE	/api/case/:caseId	Remove a case
GET	/api/case/:caseId/links	Get list of cases linked to this case
POST	/api/case/:caseId1/_merge/:caseId2	Merge two cases

Create a Case

A case can be created using the following url :

POST     /api/case

Required case attributes (cf. models) must be provided.

This call returns attributes of the created case.

Examples

Creation of a simple case:

curl -XPOST -H 'Authorization: Bearer ***API*KEY***' -H 'Content-Type: application/json' http://127.0.0.1:9000/base/api/case -d '{
  "title": "My first case",
  "description": "This case has been created by my custom script"
}'

It returns:

{
  "severity": 3,
  "createdBy": "myuser",
  "createdAt": 1488918582777,
  "caseId": 1,
  "title": "My first case",
  "startDate": 1488918582836,
  "owner": "myuser",
  "status": "Open",
  "description": "This case has been created by my custom script",
  "user": "myuser",
  "tlp": 2,
  "flag": false,
  "id": "AVqqdpY2yQ6w1DNC8aDh",
  "_id": "AVqqdpY2yQ6w1DNC8aDh",
  "_type":"case"
}

Creation of another case:

curl -XPOST -H 'Authorization: Bearer ***API*KEY***' -H 'Content-Type: application/json' http://127.0.0.1:9000/base/api/case -d '{
  "title": "My second case",
  "description": "This case has been created by my custom script, its severity is high, tlp is red and it contains tags",
  "severity": 3,
  "tlp": 3,
  "tags": ["automatic", "creation"]
}'

Creating a case with Tasks & Customfields:

curl -XPOST -H 'Authorization: Bearer ***API*KEY***' -H 'Content-Type: application/json' http://127.0.0.1:9000/base/api/case -d '{
    "title": "My first case",
    "description": "This case has been created by my custom script",
    "tasks": [{
        "title": "mytask",
        "description": "description of my task"
    }],
    "customFields": {
        "cvss": {
            "number": 9,
        },
        "businessImpact": {
            "string": "HIGH"
        }
    }
}'

For the customFields object, the attribute names should correspond to the ExternalReference (cvss and businessImpact in the example above) not to the name of custom fields.

Log

Model definition

Required attributes:

message (text) : content of the Log
startDate (date) : date of the log submission default=now
status (logStatus) : status of the log (Ok or Deleted) default=Ok

Optional attributes:

attachment (attachment) : file attached to the log

Log manipulation

Log methods

HTTP Method	URI	Action
POST	/api/case/task/log/_search	Find logs
POST	/api/case/task/:taskId/log	Create a log
PATCH	/api/case/task/log/:logId	Update a log
DELETE	/api/case/task/log/:logId	Remove a log

Create a log

The URL used to create a task is:

POST /api/case/task/<<taskId>>/log

<<taskId>> must be replaced by task id

Required log attributes (cf. models) must be provided.

This call returns attributes of the created log.

Examples

Creation of a simple log in task AVqqeXc9yQ6w1DNC8aDj:

curl -XPOST -H 'Authorization: Bearer ***API*KEY***' -H 'Content-Type: application/json' http://127.0.0.1:9000/base/api/case/task/AVqqeXc9yQ6w1DNC8aDj/log -d '{
  "message": "Some message"
}'

It returns:

{
  "startDate": 1488919949497,
  "createdBy": "admin",
  "createdAt": 1488919949495,
  "user": "myuser",
  "message":"Some message",
  "status": "Ok",
  "id": "AVqqi3C-yQ6w1DNC8aDq",
  "_id": "AVqqi3C-yQ6w1DNC8aDq",
  "_type":"case_task_log"
}

If log contains an attachment, the request must be in multipart format:

curl -XPOST -H 'Authorization: Bearer ***API*KEY***' http://127.0.0.1:9000/base/api/case/task/AVqqeXc9yQ6w1DNC8aDj/log -F '_json={"message": "Screenshot of fake site"};type=application/json' -F 'attachment=@screenshot1.png;type=image/png'

It returns:

{
  "createdBy": "myuser",
  "message": "Screenshot of fake site",
  "createdAt": 1488920587391,
  "startDate": 1488920587394,
  "user": "myuser",
  "status": "Ok",
  "attachment": {
    "name": "screenshot1.png",
    "hashes": [
      "086541e99743c6752f5fd4931e256e6e8d5fc7afe47488fb9e0530c390d0ca65",
      "8b81e038ae0809488f20b5ec7dc91e488ef601e2",
      "c5883708f42a00c3ab1fba5bbb65786c"
    ],
    "size": 15296,
    "contentType": "image/png",
    "id": "086541e99743c6752f5fd4931e256e6e8d5fc7afe47488fb9e0530c390d0ca65"
  },
  "id": "AVqqlSy0yQ6w1DNC8aDx",
  "_id": "AVqqlSy0yQ6w1DNC8aDx",
  "_type": "case_task_log"
}

Task

Model definition

Required attributes:

title (text) : title of the task
status (taskStatus) : status of the task (Waiting, InProgress, Completed or Cancel) default=Waiting
flag (boolean) : flag of the task default=false

Optional attributes:

owner (string) : user who owns the task. This is automatically set to current user when status is set to InProgress
description (text) : task details
startDate (date) : date of the beginning of the task. This is automatically set when status is set to Open
endDate (date) : date of the end of the task. This is automatically set when status is set to Completed

Task manipulation

Task methods

HTTP Method	URI	Action
POST	/api/case/:caseId/task/_search	Find tasks in a case (deprecated)
POST	/api/case/task/_search	Find tasks
POST	/api/case/task/_stats	Compute stats on tasks
GET	/api/case/task/:taskId	Get a task
PATCH	/api/case/task/:taskId	Update a task
POST	/api/case/:caseId/task	Create a task)

Create a task

The URL used to create a task is:

POST /api/case/<<caseId>>/task

<<caseId>> must be replaced by case id (not the case number !)

Required task attributes (cf. models) must be provided.

This call returns attributes of the created task.

Examples

Creation of a simple task in case AVqqdpY2yQ6w1DNC8aDh:

curl -XPOST -H 'Authorization: Bearer ***API*KEY***' -H 'Content-Type: application/json' http://127.0.0.1:9000/base/api/case/AVqqdpY2yQ6w1DNC8aDh/task -d '{
  "title": "Do something"
}'

It returns:

{
  "createdAt": 1488918771513,
  "status": "Waiting",
  "createdBy": "myuser",
  "title": "Do something",
  "order": 0,
  "user": "myuser",
  "flag": false,
  "id":"AVqqeXc9yQ6w1DNC8aDj",
  "_id":"AVqqeXc9yQ6w1DNC8aDj",
  "_type":"case_task"
}

Creation of another task:

curl -XPOST -H 'Authorization: Bearer ***API*KEY***' -H 'Content-Type: application/json' http://127.0.0.1:9000/base/api/case/AVqqdpY2yQ6w1DNC8aDh/task -d '{
  "title": "Analyze the malware",
  "description": "The malware XXX is analyzed using sandbox ...",
  "owner": "Joe",
  "status": "InProgress"
}'

Energy SOAR Base Model Definition

Field Types

string : textual data (example “malware”).
text : textual data. The difference between string and text is in the way content can be searched.string is searchable as-is whereas text, words (token) are searchable, not the whole content (example “Ten users have received this ransomware”).
date : date and time using timestamps with milliseconds format.
boolean : true or false
number : numeric value
metrics : JSON object that contains only numbers

Field can be prefixed with multi- in order to indicate that multiple values can be provided.

Common Attributes

All entities share the following attributes:

createdBy (text) : login of the user who created the entity
createdAt (date) : date and time of the creation
updatedBy (text) : login of the user who last updated the entity
updatedAt (date) : date and time of the last update
user (text) : same value as createdBy (this field is deprecated) These attributes are handled by the back-end and can’t be directly updated.

Request formats

Energy SOAR Base accepts several parameter formats within a HTTP request. They can be used indifferently. Input data can be:

a query string
URL-encoded form
multi-part
JSON

Hence, the requests below are equivalent.

Query String

curl -XPOST 'http://127.0.0.1:9000/base/api/login?user=me&password=secret'

URL-encoded Form

curl -XPOST 'http://127.0.0.1:9000/base/api/login' -d user=me -d password=secret

JSON

curl -XPOST http://127.0.0.1:9000/base/api/login -H 'Content-Type: application/json' -d '{
  "user": "me",
  "password": "secret"
}'

Multi-part

curl -XPOST http://127.0.0.1:9000/base/api/login -F '_json=<-;type=application/json' << _EOF_
{
  "user": "me",
  "password": "secret"
}
_EOF_

Response Format

Energy SOAR Base outputs JSON data.

User

Model definition

Required attributes:

login / id (string) : login of the user
userName (text) : Full name of the user
roles (multi-userRole) : Array containing roles of the user (read, write or admin)
status (userStatus) : Ok or Locked default=Ok
preference (string) : JSON object containing user preference default={}

Optional attributes:

avatar (string) : avatar of user. It is an image encoded in base 64
password (string) : user password if local authentication is used

Attributes generated by the backend:

key (uuid) : API key to authenticate this user (deprecated)

User Manipulation

User methods

HTTP Method	URI	Action
GET	/api/logout	Logout
POST	/api/login	User login
GET	/api/user/current	Get current user
POST	/api/user/_search	Find user
POST	/api/user	Create a user
GET	/api/user/:userId	Get a user
DELETE	/api/user/:userId	Lock a user (sets status to Locked)
DELETE	/api/user/:userId/force	Delete a user permanently
PATCH	/api/user/:userId	Update user details
POST	/api/user/:userId/password/set	Set password
POST	/api/user/:userId/password/change	Change password

DELETE /api/user/:userId sets the user’s status to Locked and prevents login, but keeps all user data in the database. To permanently remove the user record, use DELETE /api/user/:userId/force.

Create a User

A user can be created using the following URL:

POST     /api/user

Required case attributes (cf. models) must be provided.

This call returns attributes of the created user.

This call is authenticated and requires admin role.

Examples

Creation of a user:

curl -XPOST -H 'Authorization: Bearer ***API*KEY***' -H 'Content-Type: application/json' http://127.0.0.1:9000/base/api/user -d '{
  "login": "georges",
  "name": "Georges Abitbol",
  "roles": ["read", "write"],
  "password": "La classe"
}'

It returns:

{
  "createdBy": "myuser",
  "name":"Georges Abitbol",
  "roles": ["read", "write" ],
  "_id": "georges",
  "user": "myuser",
  "createdAt": 1496561862924,
  "status": "Ok",
  "id": "georges",
  "_type": "user",
  "has-key":false
}

If external authentication is used (LDAP or AD) password field must not be provided.

EnergySOAR events webhook activation

EnergySOAR supports webhooks, but each one needs to be activated, or EnergySOAR needs to be restarted.

Methods

HTTP Method	URI	Action
PUT	/api/config/organisation/webhook/endpoint	Add new webhook
DELETE	/api/config/organisation/webhook/endpoint/$name	Delete existing webhook
POST	/api/config/organisation/webhook/endpoint/$name	Update existing webhook
GET	/api/config/organisation/webhook/endpoint/$name	Get webhook configuration
GET	/api/config/organisation/webhook/endpoint	Get webhook list

Example definition:

curl -u'socadmin:socadmin' -XPUT http://localhost:9000/base/api/config/organisation/webhook/endpoint \
    -H "Content-Type: application/json" \
    -d '{
        "name": "new_energysoar_base_webhook",
        "url": "http://localhost:5678/webhook/########-####-####-####-############/webhook",
        "version": 0,
        "wsConfig": {},
        "includedTheHiveOrganisations": ["*"],
        "excludedTheHiveOrganisations": [],
        "auth": {
            "type": "basic",
            "username": "admin",
            "password": "admin"
        }
     }'

To activate configuration add trigger types, and provide correct endpoint name

Important At this moment there is no POST method implemented. In order to add new value you need to manually get current config, append your config, and PUT all together as new value

curl -u "socadmin:socadmin" "http://127.0.0.1:9000/base/api/config/organisation/notification"

You should get something like this on fresh install:

{
  "path": "notification",
  "defaultValue": [],
  "value": [
    {
      "delegate": false,
      "trigger": {
        "name": "AnyEvent"
      },
      "notifier": {
        "name": "webhook",
        "endpoint": "n8n"
      }
    }
  ]
}

Copy all elements in value field, and overwrite this using PUT:

curl -XPUT -u "socadmin:socadmin" -H 'Content-type: application/json' "http://127.0.0.1:9000/base/api/config/organisation/notification" 
    -d '{
        "value": [
          {
            "delegate": false,
            "trigger": {
              "name": "AnyEvent"
            },
            "notifier": {
              "name": "webhook",
              "endpoint": "n8n"
            }
          },
          {
            "delegate": false,
            "trigger": { 
              "name": "AlertCreated"
            },
            "notifier": { 
              "name": "webhook",
              "endpoint": "new_energysoar_base_webhook" 
            }
          }
        ]
        }' 

Trigger types:

Event types
AnyEvent
FilteredEvent
ActionFinished
CaseCreated
CaseFlagged
CaseUpdated
CaseShared
CaseClosed
AlertClosed
AlertCreated
AlertImported
JobFinished
AlertObservableCreated
CaseObservableCreated
ObservableCreated
TaskClosed
TaskMandatory

Case Template

Case templates define a reusable structure for cases, including default severity, TLP, PAP, tags, tasks, and custom field values. Requires the manageCaseTemplate permission.

Methods

HTTP Method	URI	Action
GET	/api/case/template	List templates
POST	/api/case/template/_search	Search templates
POST	/api/case/template/_stats	Compute stats
POST	/api/case/template	Create a template
GET	/api/case/template/:caseTemplateId	Get a template
PATCH	/api/case/template/:caseTemplateId	Update a template
DELETE	/api/case/template/:caseTemplateId	Delete a template

Model

Required attributes:

name (string) : internal template identifier. Also accepted as the template name in the caseTemplate field of alert and case creation requests.
displayName (string) : name shown in the UI

Optional attributes:

titlePrefix (string) : prefix prepended to the case title when a case is created from this template
description (string) : template description
severity (number) : default severity (1: low; 2: medium; 3: high; 4: critical)
tags (multi-string) : default tags
flag (boolean) : default flag state default=false
tlp (number) : default TLP (0: white; 1: green; 2: amber; 3: red) default=2
pap (number) : default PAP (0: white; 1: green; 2: amber; 3: red) default=2
summary (string) : default case summary
user (string) : default assignee login
tasks (array) : predefined task list — each item is a task object with title, description, status, and flag
customFields (object) : default custom field values, keyed by the field’s reference (external reference)

Create a template

POST /api/case/template

Example

curl -XPOST -H 'Authorization: Bearer ***API*KEY***' -H 'Content-Type: application/json' http://127.0.0.1:9000/base/api/case/template -d '{
  "name": "phishing",
  "displayName": "Phishing Investigation",
  "titlePrefix": "[PHISH]",
  "severity": 2,
  "tlp": 2,
  "pap": 2,
  "tags": ["phishing", "email"],
  "tasks": [
    { "title": "Triage alert", "status": "Waiting" },
    { "title": "Collect headers", "status": "Waiting" },
    { "title": "Block sender", "status": "Waiting" }
  ],
  "customFields": {
    "cvss": { "number": 0 }
  }
}'

Returns the created template object.

Custom Field

Custom fields extend the data model of cases, alerts, and tasks with organisation-specific attributes. Requires the manageCustomField permission to create, update, or delete.

Methods

HTTP Method	URI	Action
GET	/api/customField	List custom fields
POST	/api/customFields/_search	Search custom fields
POST	/api/customField	Create a custom field
GET	/api/customField/:id	Get a custom field
PATCH	/api/customField/:id	Update a custom field
DELETE	/api/customField/:id	Delete a custom field
GET	/api/customFields/:id/use	Count entities using this field

Model

Required attributes:

name (string) : display name shown in the UI
reference (string) : machine-readable key used in API requests (the ExternalReference value). Read-only after creation.
type (string) : field type — one of string, boolean, integer, float, date

Optional attributes:

description (string) : field description
mandatory (boolean) : if true, the field must be filled before a case can be closed default=false
options (array) : allowed values; when set, the UI renders the field as a dropdown

Create a custom field

POST /api/customField

Example

curl -XPOST -H 'Authorization: Bearer ***API*KEY***' -H 'Content-Type: application/json' http://127.0.0.1:9000/base/api/customField -d '{
  "name": "CVSS Score",
  "reference": "cvss",
  "type": "float",
  "description": "CVSS v3.1 base score",
  "mandatory": false
}'

Returns the created custom field object.

Delete a custom field

By default, deletion is refused if any entity uses the field. Pass force=true to remove the field and all its values.

curl -XDELETE -H 'Authorization: Bearer ***API*KEY***' 'http://127.0.0.1:9000/base/api/customField/FIELD_ID?force=true'

Stream

The stream API provides a long-poll mechanism for receiving real-time audit events. Each authenticated session creates a stream identified by a streamId. Polling GET /api/stream/:streamId blocks until new events arrive or the request times out, then returns a JSON array of audit entries.

A response with HTTP status 220 signals that the session is about to expire. The client should warn the user and prompt for re-authentication.

Methods

HTTP Method	URI	Action
POST	/api/stream	Create a stream, returns the streamId
GET	/api/stream/:streamId	Poll for events
GET	/api/stream/status	Get session expiry status

Create a stream

POST /api/stream

Returns the streamId as a plain-text string.

curl -XPOST -H 'Authorization: Bearer ***API*KEY***' http://127.0.0.1:9000/base/api/stream

Poll for events

GET /api/stream/:streamId

Blocks until events are available. Returns a JSON array; each element is an audit event object. Returns an empty array if the poll timeout is reached with no events.

HTTP 220 instead of 200 indicates the session will expire soon. The response body is identical; the status code is the expiry signal.

curl -H 'Authorization: Bearer ***API*KEY***' http://127.0.0.1:9000/base/api/stream/STREAM_ID

Session status

GET /api/stream/status

Returns:

{
  "warning": false,
  "remaining": 3540000
}

remaining is in milliseconds. warning is true when expiry is imminent.

Action

Actions run responders from Energy SOAR Automation on Base entities (cases, alerts, tasks, observables, logs). Each action creates an async job in Automation and records the result when it completes.

Requires the manageAction permission and a configured Cortex integration.

Methods

HTTP Method	URI	Action
POST	/api/action	Run a responder on an entity
GET	/api/action	List actions
POST	/api/action/_search	Search actions
POST	/api/action/_stats	Compute stats on actions
GET	/api/action/:entityType/:entityId	Get actions for an entity

Action model

Attributes returned by the API:

responderId (string) : ID of the responder that was invoked
responderName (string) : name of the responder
objectType (string) : entity type the action ran on (case, alert, task, observable, log)
objectId (string) : ID of the entity
cortexId (string) : ID of the Automation instance that processed the action
status (string) : Waiting, InProgress, Success, Failure, or Deleted
startDate (date) : when the action started
tlp (number) : TLP of the entity at the time of execution

Run an action

POST /api/action

Request body:

objectType (string, required) : entity type — one of case, alert, task, observable, log
objectId (string, required) : ID of the entity
responderId (string, required) : ID of the responder in Automation
cortexId (string, required) : ID of the Automation instance
parameters (object, optional) : additional parameters passed to the responder

Example — run a responder on a case:

curl -XPOST -H 'Authorization: Bearer ***API*KEY***' -H 'Content-Type: application/json' http://127.0.0.1:9000/base/api/action -d '{
  "objectType": "case",
  "objectId": "AVqqdpY2yQ6w1DNC8aDh",
  "responderId": "Mailer_1_0_abc123",
  "cortexId": "local-cortex",
  "parameters": {}
}'

Returns the action object with its initial status of Waiting.

Get actions for an entity

GET /api/action/:entityType/:entityId

Example — list all actions run on case AVqqdpY2yQ6w1DNC8aDh:

curl -H 'Authorization: Bearer ***API*KEY***' http://127.0.0.1:9000/base/api/action/case/AVqqdpY2yQ6w1DNC8aDh

Organisation

Organisations are the multi-tenancy unit in Energy SOAR Base. Each user belongs to one organisation. Cases, alerts, and custom fields are scoped to an organisation. Linked organisations can share cases with each other.

Creating an organisation requires the manageOrganisation permission and the calling user must belong to the admin organisation.

Methods

HTTP Method	URI	Action
GET	/api/organisation	List visible organisations
POST	/api/organisation/_search	Search organisations
POST	/api/organisation	Create an organisation
GET	/api/organisation/:organisationId	Get an organisation
PATCH	/api/organisation/:organisationId	Update an organisation
PUT	/api/organisation/:organisationId1/link/:organisationId2	Link two organisations
PUT	/api/organisation/:organisationId/links	Set all links for an organisation (bulk)
GET	/api/organisation/:organisationId/links	List linked organisations
DELETE	/api/organisation/:organisationId1/link/:organisationId2	Remove a link between two organisations

Model

Required attributes:

name (string) : unique organisation identifier
description (string) : human-readable description

Both fields are updatable via PATCH.

Create an organisation

POST /api/organisation

Example

curl -XPOST -H 'Authorization: Bearer ***API*KEY***' -H 'Content-Type: application/json' http://127.0.0.1:9000/base/api/organisation -d '{
  "name": "soc-client-a",
  "description": "Client A SOC organisation"
}'

Returns the created organisation object with _id, id, name, and description.

Link organisations

Linking two organisations allows them to share cases with each other. The link is bidirectional once established.

PUT /api/organisation/:organisationId1/link/:organisationId2

To set multiple links at once, replacing the existing link list:

PUT /api/organisation/:organisationId/links

Request body:

{ "organisations": ["soc-client-b", "soc-client-c"] }

Share

Case sharing lets one organisation make a case visible to linked organisations, with access controlled by a profile. Tasks and observables can be included at share time or added individually later.

Requires the manageShare permission. You cannot remove your own organisation’s share or the initial owner share.

Methods

HTTP Method	URI	Action
POST	/api/case/:caseId/shares	Share a case with organisations
GET	/api/case/:caseId/shares	List shares for a case
DELETE	/api/case/:caseId/shares	Remove shares by organisation name
POST	/api/case/shares/_bulk	Share multiple cases at once
DELETE	/api/case/shares	Remove shares by share ID (bulk)
PATCH	/api/case/share/:shareId	Update the profile of a share
DELETE	/api/case/share/:shareId	Remove a share by ID
POST	/api/case/task/:taskId/shares	Share a task with organisations
GET	/api/case/:caseId/task/:taskId/shares	List shares for a task
DELETE	/api/task/:taskId/shares	Remove task shares
POST	/api/case/artifact/:observableId/shares	Share an observable with organisations
GET	/api/case/:caseId/observable/:observableId/shares	List shares for an observable
DELETE	/api/observable/:observableId/shares	Remove observable shares

Audit

The audit log records all create, update, and delete operations. Each entry links to the affected object and the request that caused the change.

Methods

HTTP Method	URI	Action
GET	/api/audit	List audit entries
POST	/api/audit/_search	Search audit entries
POST	/api/audit/_stats	Compute stats on audit entries
GET	/api/flow	Long-poll for new audit events

Audit entry model

Attributes returned by the API:

operation (string) : type of change — create, update, or delete
objectType (string) : entity type affected (case, alert, task, observable, log, etc.)
objectId (string) : ID of the affected entity
details (string) : JSON-encoded details of the change (fields changed and their new values)
startDate (date) : timestamp of the operation
requestId (string) : groups all audit entries produced by a single API request
rootId (string) : ID of the top-level context entity (e.g., the case containing a modified task)
base (boolean) : true for the primary audit entry of a request; false for secondary entries

Search audit entries

curl -XPOST -H 'Authorization: Bearer ***API*KEY***' -H 'Content-Type: application/json' http://127.0.0.1:9000/base/api/audit/_search -d '{
  "query": { "_field": "objectType", "_value": "case" },
  "range": "0-50",
  "sort": ["-startDate"]
}'

Live event feed

GET /api/flow long-polls for new audit events. The request blocks for up to 5 minutes. When events arrive the response returns immediately; if the timeout is reached, an empty array is returned.

Pass rootId to receive events scoped to a specific top-level entity:

curl -H 'Authorization: Bearer ***API*KEY***' 'http://127.0.0.1:9000/base/api/flow?rootId=AVqqdpY2yQ6w1DNC8aDh'

Without rootId (or with rootId=any), the feed returns events for all entities visible to the calling user.

Dashboard

Dashboards are configurable analytics views that users can create privately or share within their organisation.

Methods

HTTP Method	URI	Action
GET	/api/dashboard	List dashboards visible to the current user
POST	/api/dashboard/_search	Search dashboards
POST	/api/dashboard/_stats	Compute stats on dashboards
POST	/api/dashboard	Create a dashboard
GET	/api/dashboard/{id}	Get a dashboard by ID
PATCH	/api/dashboard/{id}	Update a dashboard
DELETE	/api/dashboard/{id}	Delete a dashboard

Model

title (string) : dashboard display name
description (string) : optional description
definition (string) : JSON-encoded widget configuration
status (string) : Private (visible only to the owner) or Shared (visible to the whole organisation)

Create a dashboard

curl -XPOST -H 'Authorization: Bearer ***API*KEY***' -H 'Content-Type: application/json' http://127.0.0.1:9000/base/api/dashboard -d '{
  "title": "Alert overview",
  "description": "Daily alert volume and severity breakdown",
  "definition": "{}",
  "status": "Private"
}'

A successful request returns HTTP 201 with the created dashboard object.

Profile

Profiles define the set of permissions granted to users assigned to an organisation. Managing profiles requires the manageProfile permission, which is available only in the admin organisation.

Methods

HTTP Method	URI	Action
GET	/api/profile	List profiles
POST	/api/profile/_search	Search profiles
POST	/api/profile/_stats	Compute stats on profiles
POST	/api/profile	Create a profile
GET	/api/profile/{id}	Get a profile by ID or name
PATCH	/api/profile/{id}	Update a profile
DELETE	/api/profile/{id}	Delete a profile

Model

name (string) : profile name
permissions (array of strings) : permissions granted to users assigned this profile

Create a profile

Requires the manageProfile permission.

curl -XPOST -H 'Authorization: Bearer ***API*KEY***' -H 'Content-Type: application/json' http://127.0.0.1:9000/base/api/profile -d '{
  "name": "analyst",
  "permissions": ["manageCase", "manageObservable", "manageTask", "manageAlert"]
}'

A successful request returns HTTP 201 with the created profile object.

Tag

Tags are labels attached to cases, observables, and alerts. They are created implicitly when set on an entity — there is no dedicated create endpoint. The tag API provides read access for search and autocomplete.

Methods

HTTP Method	URI	Action
GET	/api/tag	List tags visible to the current user
POST	/api/tag/_search	Search tags
POST	/api/tag/_stats	Compute stats on tags
GET	/api/tag/{id}	Get a tag by ID

Model

namespace (string) : taxonomy namespace (e.g., tlp, misp-galaxy); namespaces starting with _ are internal free-tag namespaces
predicate (string) : predicate within the namespace (e.g., WHITE, ransomware)
value (string, optional) : value qualifier
description (string, optional) : human-readable description
colour (string) : hex colour code used to render the tag label
text (string) : computed display name — namespace:predicate="value" for taxonomy tags; predicate="value" for free tags (namespace omitted when it starts with _)

Search tags

curl -XPOST -H 'Authorization: Bearer ***API*KEY***' -H 'Content-Type: application/json' http://127.0.0.1:9000/base/api/tag/_search -d '{
  "query": { "_field": "namespace", "_value": "tlp" },
  "range": "0-50"
}'

Observable Type

Observable types define the data types that can be attached to cases and alerts as observables (for example ip, domain, url, hash, or file). Managing observable types requires the manageObservableTemplate permission, which is available only in the admin organisation.

Methods

HTTP Method	URI	Action
GET	/api/observable/type	List observable types
POST	/api/observable/type/_search	Search observable types
POST	/api/observable/type/_stats	Compute stats on observable types
POST	/api/observable/type	Create an observable type
GET	/api/observable/type/{idOrName}	Get an observable type by ID or name
DELETE	/api/observable/type/{idOrName}	Delete an observable type

Model

name (string) : type identifier used in the observable dataType field (e.g., ip, domain)
isAttachment (boolean) : true for types that store a file attachment rather than a plain string value

Create an observable type

Requires the manageObservableTemplate permission.

curl -XPOST -H 'Authorization: Bearer ***API*KEY***' -H 'Content-Type: application/json' http://127.0.0.1:9000/base/api/observable/type -d '{
  "name": "bitcoin-address",
  "isAttachment": false
}'

A successful request returns HTTP 201 with the created observable type object.

Delete an observable type

Requires the manageObservableTemplate permission.

curl -XDELETE -H 'Authorization: Bearer ***API*KEY***' http://127.0.0.1:9000/base/api/observable/type/bitcoin-address

A successful request returns HTTP 204 (no content).

Status and Health

These two endpoints expose instance metadata and connector health. Neither requires authentication.

Methods

HTTP Method	URI	Action
GET	/api/status	Return version and configuration information
GET	/api/health	Return overall health status

Status

GET /api/status returns a JSON object with the following fields:

versions.Scalligraph (string) : ScalliGraph library version
versions.TheHive (string) : Energy SOAR backend version
versions.Play (string) : Play framework version
connectors (object) : map of connector names to their current status
config.protectDownloadsWith (string) : password used to protect attachment ZIP archives
config.authType (string or array) : configured authentication method(s)
config.capabilities (array of strings) : capabilities advertised by the auth provider
config.ssoAutoLogin (boolean) : whether SSO auto-login is enabled
config.pollingDuration (number) : stream long-poll timeout in milliseconds
config.freeTagDefaultColour (string) : default colour for free tags
schemaStatus (array) : schema migration status for each installed module
chatActive (boolean) : whether the Rocket.Chat integration is configured

curl http://127.0.0.1:9000/base/api/status

Health

GET /api/health returns a plain string: Ok, Warning, or Error.

Ok — database and all connectors are healthy
Warning — at least one connector reports a non-critical issue
Error — database or a connector is in error state

curl http://127.0.0.1:9000/base/api/health

Automation API Guide

Introduction

Energy SOAR Automation offers a REST API that can be leveraged by various applications and programs to interact with it. The following guide describe the Automation API to allow developers to interface the powerful observable analysis engine with other SIRPs (Security Incident Response Platforms) besides Energy SOAR Base, TIPs (Threat Intelligence Platforms), SIEMs or scripts. Please note that the Web UI of Energy SOAR Automation exclusively leverage the REST API to interact with the back-end.

All the exposed APIs share the same request & response formats and authentication strategies as described below.

There are also some transverse parameters supported by several calls, in addition to utility APIs.

To write a custom analyzer, see How to Write and Submit an Analyzer.

Request & Response Formats

Energy SOAR Automation accepts several parameter formats within a HTTP request. They can be used indifferently. Input data can be:

A query string
A URL-encoded form
A multi-part
JSON

Hence, the requests shown below are equivalent.

Query String

curl -XPOST 'https://127.0.0.1/automation/api/login?user=me&password=secret'

URL-encoded Form

curl -XPOST 'https://127.0.0.1/automation/api/login' -d user=me -d password=secret

JSON

curl -XPOST https://127.0.0.1/automation/api/login -H 'Content-Type: application/json' -d '{
  "user": "me",
  "password": "secret"
}'

Multi-part

curl -XPOST https://127.0.0.1/automation/api/login -F '_json=<-;type=application/json' << _EOF_
{
  "user": "me",
  "password": "secret"
}
_EOF_

Response Format

For each request submitted, Energy SOAR Automation will respond back with JSON data. For example, if the authentication request is successful, Energy SOAR Automation should return the following output:

{"id":"me","name":"me","roles":["read","analyze","orgadmin"]}

If not, Energy SOAR Automation should return an authentication error:

{"type":"AuthenticationError","message":"Authentication failure"}

Authentication

Most API calls require authentication. Credentials can be provided using a session cookie, an API key or directly using HTTP basic authentication (if this method is specifically enabled).

Session cookies are better suited for browser authentication. Hence, we recommend authenticating with API keys when calling the Energy SOAR Automation APIs.

Generating API Keys with an orgAdmin Account

API keys can be generated using the Web UI. To do so, connect using an orgAdmin account then click on Organization and then on the Create API Key button in the row corresponding to the user you intend to use for API authentication. Once the API key has been created, click on Reveal to display the API key then click on the copy to clipboard button if you wish to copy the key to your system’s clipboard.

If the user is not yet created, start by clicking on Add user to create it then follow the steps mentioned above.

Generating API Keys with a superAdmin Account

You can use a superAdmin account to achieve the same result as described above. Once authenticated, click on Users then on the Create API Key button in the row corresponding to the user you intend to use for API authentication. Please make sure the user is in the right organization by thoroughly reading its name, which is shown below the user name. Once the API key has been created, click on Reveal to display the API key then click on the copy to clipboard button if you wish to copy the key to your system’s clipboard.

Authenticating with an API Key

Once you have generated an API key you can use it, for example, to list the Energy SOAR Automation jobs thanks to the following curl command:

## Using API key
curl -H 'Authorization: Bearer **API_KEY**' https://127.0.0.1/automation/api/job

As you can see in the example above, we instructed curl to add the Authorization header to the request. The value of the header is Bearer: **API_KEY**. So if your API key is GPX20GUAQWwpqnhA6JpOwNGPMfWuxsX3, the curl command above would look like the following:

## Using API key
curl -H 'Authorization: Bearer GPX20GUAQWwpqnhA6JpOwNGPMfWuxsX3' https://127.0.0.1/automation/api/job

Using Basic Authentication

Energy SOAR Automation also supports basic authentication but it is disabled by default for security reasons. If you absolutely need to use it, you can enable it by adding auth.method.basic=true to the configuration file (/etc/cortex/application.conf by default). Once you do, restart the Energy SOAR Automation service. You can then, for example, list the Energy SOAR Automation jobs using the following curl command:

## Using basic authentication
curl -u mylogin:mypassword https://127.0.0.1/automation/api/job

Organization APIs

Energy SOAR Automation offers a set of APIs to create, update and list organizations.

Organization Model

An organization (org) is defined by the following attributes:

Attribute	Description	Type
`id`	Copy of the org's name (see next row)	readonly
`name`	Name	readonly
`status`	Status (`Active` or `Locked`)	writable
`description`	Description	writable
`createdAt`	Creation date	computed
`createdBy`	User who created the org	computed
`updatedAt`	Last update	computed
`updatedBy`	User who last updated the org	computed

Please note that id and name are essentially the same. Also, createdAt and updatedAt are in epoch.

List

It is possible to list all the organizations using the following API call, which requires the API key associated with a superAdmin account:

curl -H 'Authorization: Bearer **API_KEY**' 'https://127.0.0.1/automation/api/organization'

You can also search/filter organizations using the following query:

curl -H 'Authorization: Bearer **API_KEY**' -H 'Content-Type: application/json' 'https://127.0.0.1/automation/api/organization/_search' -d '{
  "query": {"status": "Active"}
}'

Both APIs supports the range and sort query parameters described in paging and sorting details.

Create

It is possible to create an organization using the following API call, which requires the API key associated with a superAdmin account:

curl -XPOST -H 'Authorization: Bearer **API_KEY**' -H 'Content-Type: application/json' 'https://127.0.0.1/automation/api/organization' -d '{
  "name": "demo",
  "description": "Demo organization",
  "status": "Active"
}'

Update

You can update an organization’s description and status (Active or Locked) using the following API call. This requires the API key associated with a superAdmin account:

curl -XPATCH -H 'Authorization: Bearer **API_KEY**' -H 'Content-Type: application/json' 'https://127.0.0.1/automation/api/organization/ORG_ID' -d '{
  "description": "New Demo organization",
}'

or

curl -XPATCH -H 'Authorization: Bearer **API_KEY**' -H 'Content-Type: application/json' 'https://127.0.0.1/automation/api/organization/ORG_ID' -d '{
  "status": "Active",
}'

Delete

Deleting an organization just marks it as Locked and doesn’t remove the associated data from the DB. To “delete” an organization, you can use the API call shown below. It requires the API key associated with a superAdmin account.

curl -XDELETE -H 'Authorization: Bearer **API_KEY**' 'https://127.0.0.1/automation/api/organization/ORG_ID'

Obtain Details

This API call returns the details of an organization as described in the Organization model section.

curl -H 'Authorization: Bearer **API_KEY**' 'https://127.0.0.1/automation/api/organization/ORG_ID'

Let’s assume that the organization we are seeking to obtain details about is called demo. The curl command would be:

curl -H 'Authorization: Bearer **API_KEY**' 'https://127.0.0.1/automation/api/organization/demo'

and it should return:

{
  "id": "demo",
  "name": "demo",
  "status": "Active",
  "description": "Demo organization",
  "createdAt": 1520258040437,
  "createdBy": "superadmin",
  "updatedBy": "superadmin",
  "updatedAt": 1522077420693
}

List Users

As mentioned above, you can use the API to return the list of all the users declared withing an organization. For that purpose, use the API call shown below with the API key of an orgAdmin or superAdmin account. It supports the range and sort query parameters declared in paging and sorting details.

curl -H 'Authorization: Bearer **API_KEY**' 'https://127.0.0.1/automation/api/organization/ORG_ID/user'

and should return a list of users.

If one wants to filter/search for some users (active ones for example), there is a search API to use as below:

curl -XPOST -H 'Authorization: Bearer **API_KEY**' -H 'Content-Type: application/json' 'https://127.0.0.1/automation/api/organization/ORG_ID/user/_search' -d '{
  "query": {}
}'

It also supports the range and sort query parameters declared in paging and sorting details.

List Enabled Analyzers

To list the analyzers that have been enabled within an organization, use the following API call with the API key of an orgAdmin user:

curl -H 'Authorization: Bearer **API_KEY**' 'https://127.0.0.1/automation/api/analyzer'

It should return a list of Analyzers.

Please note that this API call does not display analyzers that are disabled. It supports the range and sort query parameters declared in paging and sorting details.

User APIs

The following section describes the APIs that allow creating, updating and listing users within an organization.

User Model

A user is defined by the following attributes:

Attribute	Description	Type
`id`	ID/login	readonly
`name`	Name	writable
`roles`	Roles. Possible values are: `read`, `read,analyze`, `read,analyze,orgadmin` and `superadmin`	writable
`status`	Status (`Active` or `Locked`)	writable
`organization`	organization to which the user belongs (set upon account creation)	readonly
`createdAt`	Creation date	computed
`createdBy`	User who created the account	computed
`updatedAt`	Last update date	computed
`updatedBy`	User who last updated the account	computed
`hasKey`	true when the user has an API key	computed
`hasPassword`	true if the user has a password	computed

List All

This API call allows a superAdmin to list and search all the users of all defined organizations:

curl -H 'Authorization: Bearer **API_KEY**' 'https://127.0.0.1/automation/api/user'

This call supports the range and sort query parameters declared in paging and sorting details.

List Users within an Organization

This call is described in organization APIs.

Search

This API call allows a superAdmin to perform search on the user accounts created in a Energy SOAR Automation instance:

curl -XPOST -H 'Authorization: Bearer **API_KEY**' -H 'Content-Type: application/json' 'https://127.0.0.1/automation/api/user/_search' -d '{
  "query": {}
}'

This call supports the range and sort query parameters declared in paging and sorting details

Create

This API calls allows you to programmatically create user creation. If the call is made by a superAdmin user, the request must specify the organization to which the user belong in the organization field.

If the call is made by an orgAdmin user, the value of organization field must be the same as the user who makes the call: orgAdmin users are allowed to create users only in their organization.

curl -XPOST -H 'Authorization: Bearer **API_KEY**' -H 'Content-Type: application/json' 'https://127.0.0.1/automation/api/user' -d '{
  "name": "Demo org Admin",
  "roles": [
    "read",
    "analyze",
    "orgadmin"
  ],
  "organization": "demo",
  "login": "demo"
}'

If successful, the call returns a JSON object representing the created user as described above.

{
  "id": "demo",
  "organization": "demo",
  "name": "Demo org Admin",
  "roles": [
    "read",
    "analyze",
    "orgadmin"
  ],
  "status": "Ok",
  "createdAt": 1526050123286,
  "createdBy": "superadmin",
  "hasKey": false,
  "hasPassword": false
}

Update

This API call allows updating the writable attributed of a user account. It’s available to users with superAdmin or orgAdmin roles. Any user can also use it to update their own information (but obviously not their roles).

curl -XPATCH -H 'Authorization: Bearer **API_KEY**' -H 'Content-Type: application/json' 'https://127.0.0.1/automation/api/user/USER_LOGIN' -d '{
  "name": "John Doe",
  "roles": [
    "read",
    "analyze"
  ],
  "status": "Locked"
}'

It returns a JSON object representing the updated user as described above.

Get Details

This call returns the user details. It’s available to users with superAdmin roles and to users in the same organization. Every user can also use it to read their own details.

curl -H 'Authorization: Bearer **API_KEY**' 'https://127.0.0.1/automation/api/user/USER_LOGIN'

It returns a JSON object representing the user as described previously.

Set a Password

This call sets the user’s password. It’s available to users with superAdmin or orgAdmin roles. Please note that the request needs to be made using HTTPS with a valid certificate on the server’s end to prevent credential sniffing or other PITM (Person-In-The-Middle) attacks.

curl -XPOST -H 'Authorization: Bearer **API_KEY**' -H 'Content-Type: application/json' 'https://127.0.0.1/automation/api/user/USER_LOGIN/password/set' -d '{
  "password": "SOMEPASSWORD"
}'

If successful, the call returns 204 (success / no content).

Change a password

This call allows a given user to change only their own existing password. It is available to all users including superAdmin and orgAdmin ones. Please note that if a superAdmin or an orgAdmin needs to update the password of another user, they must use the /password/set call described in the previous subsection.

curl -XPOST -H 'Authorization: Bearer **API_KEY**' -H 'Content-Type: application/json' 'https://127.0.0.1/automation/api/user/USER_LOGIN/password/change' -d '{
  "currentPassword": "password",
  "password": "new-password"
}'

If successful, the call returns 204 (success / no content).

Set and Renew an API Key

This calls allows setting and renewing the API key of a user. It’s available to users with superAdmin or orgAdmin roles. Any user can also use it to renew their own API key. Again, the request needs to be made using HTTPS with a valid certificate on the server’s end to prevent credential sniffing or other PITM (Person-In-The-Middle) attacks. You know the drill ;-)

curl -XPOST -H 'Authorization: Bearer **API_KEY**' 'https://127.0.0.1/automation/api/user/USER_LOGIN/key/renew'

If successful, it returns the generated API key in a text/plainresponse.

Get an API Key

This calls allows getting a user’s API key. It’s available to users with superAdmin or orgAdmin roles. Any user can also use it to obtain their own API key.

curl -H 'Authorization: Bearer **API_KEY**' 'https://127.0.0.1/automation/api/user/USER_LOGIN/key'

If successful, the generated API key is returned in text/plainresponse

Revoke an API Key

This call allows revoking a user’s API key.

curl -XDELETE -H 'Authorization: Bearer **API_KEY**' 'https://127.0.0.1/automation/api/user/USER_LOGIN/key'

A successful request returns nothing (HTTP 200 OK).

Job APIs

The following section describes the APIs that allow manipulating jobs. Jobs are basically submissions made to analyzers and the resulting reports.

Job Model

A job is defined by the following attributes:

Attribute	Description	Type
`id`	Job ID	computed
`organization`	The organization to which the job belongs	readonly
`analyzerDefinitionId`	Analyzer definition name	readonly
`analyzerId`	Instance ID of the analyzer to which the job is associated	readonly
`organization`	Organization to which the user belongs (set upon account creation)	readonly
`analyzerName`	Name of the analyzer to which the job is associated	readonly
`dataType`	the datatype of the analyzed observable	readonly
`status`	Status of the job (`Waiting`, `InProgress`, `Success`, `Failure`, `Deleted`)	computed
`data`	Value of the analyzed observable (does not apply to `file` observables)	readonly
`attachment`	JSON object representing `file` observables (does not apply to non-`file` observables). It defines the`name`, `hashes`, `size`, `contentType` and `id` of the `file` observable	readonly
`parameters`	JSON object of key/value pairs set during job creation	readonly
`message`	A free text field to set additional text/context for a job	readonly
`tlp`	The TLP of the analyzed observable	readonly
`startDate`	Start date	computed
`endDate`	End date	computed
`createdAt`	Creation date. Please note that a job can be requested but not immediately honored. The actual time at which it is started is the value of `startDate`	computed
`createdBy`	User who created the job	computed
`updatedAt`	Last update date (only Energy SOAR Automation updates a job when it finishes)	computed
`updatedBy`	User who submitted the job and which identity is used by Energy SOAR Automation to update the job once it is finished	computed

List and Search

This call allows a user with read,analyze or orgAdmin role to list and search all the analysis jobs made by their organization.

If you want to list all the jobs:

curl -XPOST -H 'Authorization: Bearer **API_KEY**' 'https://127.0.0.1/automation/api/job/_search?range=all'

If you want to list 10 jobs:

curl -XPOST -H 'Authorization: Bearer **API_KEY**' 'https://127.0.0.1/automation/api/job/_search'

If you want to list 100 jobs:

curl -XPOST -H 'Authorization: Bearer **API_KEY**' 'https://127.0.0.1/automation/api/job/_search?range=0-100'

If you want to search jobs according to various criteria:

curl -XPOST -H 'Authorization: Bearer **API_KEY**' -H 'Content-Type: application/json' 'https://127.0.0.1/automation/api/job/_search' -d '{
  "query": {
    "_and": [
      {"status": "Success"},
      {"dataType": "ip"}
    ]
  }
}'

This call supports the range and sort query parameters declared in paging and sorting details

Get Details

This call allows a user with read,analyze or orgAdmin role to get the details of a job. It does not fetch the job report.

curl -H 'Authorization: Bearer **API_KEY**' 'https://127.0.0.1/automation/api/job/JOB_ID'

It returns a JSON response with the following structure:

{
  "id": "AWNei4vH3rJ8unegCPB9",
  "analyzerDefinitionId": "Abuse_Finder_2_0",
  "analyzerId": "220483fde9608c580fb6a2508ff3d2d3",
  "analyzerName": "Abuse_Finder_2_0",
  "status": "Success",
  "data": "8.8.8.8",
  "parameters": "{}",
  "tlp": 0,
  "message": "",
  "dataType": "ip",
  "organization": "demo",
  "startDate": 1526299593923,
  "endDate": 1526299597064,
  "date": 1526299593633,
  "createdAt": 1526299593633,
  "createdBy": "demo",
  "updatedAt": 1526299597066,
  "updatedBy": "demo"
}

Get Details and Report

This call allows a user with read,analyze or orgAdmin role to get the details of a job including its report.

curl -H 'Authorization: Bearer **API_KEY**' 'https://127.0.0.1/automation/api/job/JOB_ID/report'

It returns a JSON response with the structure below. If the job is not yet completed, the report field contains a string representing the job status:

{
  "id": "AWNei4vH3rJ8unegCPB9",
  "analyzerDefinitionId": "Abuse_Finder_2_0",
  "analyzerId": "220483fde9608c580fb6a2508ff3d2d3",
  "analyzerName": "Abuse_Finder_2_0",
  "status": "Success",
  "data": "8.8.8.8",
  "parameters": "{}",
  "tlp": 0,
  "message": "",
  "dataType": "ip",
  "organization": "demo",
  "startDate": 1526299593923,
  "endDate": 1526299597064,
  "date": 1526299593633,
  "createdAt": 1526299593633,
  "createdBy": "demo",
  "updatedAt": 1526299597066,
  "updatedBy": "demo",
  "report": {
    "summary": {
      "taxonomies": [
        {
          "predicate": "Address",
          "namespace": "Abuse_Finder",
          "value": "network-abuse@google.com",
          "level": "info"
        }
      ]
    },
    "full": {
      "abuse_finder": {
        "raw": "...",
        "abuse": [
          "network-abuse@google.com"
        ],
        "names": [
          "Google LLC",
          "Level 3 Parent, LLC"
        ],
        "value": "8.8.8.8"
      }
    },
    "success": true,
    "artifacts": []
  }
}

Wait and Get Job Report

This call is similar the one described above but allows the user to provide a timeout to wait for the report in case it is not available at the time the query was made:

curl -H 'Authorization: Bearer **API_KEY**' 'https://127.0.0.1/automation/api/job/JOB_ID/waitreport?atMost=1minute'

The atMost is a duration using the format Xhour, Xminute or Xsecond.

Get Artifacts

This call allows a user with read,analyze or orgAdmin role to get the extracted artifacts from a job if such extraction has been enabled in the corresponding analyzer configuration. Please note that extraction is imperfect and you might have inconsistent or incorrect data.

curl -H 'Authorization: Bearer **API_KEY**' 'https://127.0.0.1/automation/api/job/JOB_ID/artifacts'

It returns a JSON array with the following structure:

[
  {
    "dataType": "ip",
    "createdBy": "demo",
    "data": "8.8.8.8",
    "tlp": 0,
    "createdAt": 1525432900553,
    "id": "AWMq4tvLjidKq_asiwcl"
  }
]

Delete

This API allows a user with analyze or orgAdmin role to delete a job:

curl -XDELETE -H 'Authorization: Bearer **API_KEY**' 'https://127.0.0.1/automation/api/job/JOB_ID'

This marks the job as Deleted. However the job’s data is not removed from the database.

Analyzer APIs

The following section describes the APIs that allow manipulating analyzers.

Analyzer Model

An analyzer is defined by the following attributes:

Attribute	Description	Type
`id`	Analyzer ID once enabled within an organization	readonly
`analyzerDefinitionId`	Analyzer definition name	readonly
`name`	Name of the analyzer	readonly
`version`	Version of the analyzer	readonly
`description`	Description of the analyzer	readonly
`author`	Author of the analyzer	readonly
`url`	URL where the analyzer has been published	readonly
`license`	License of the analyzer	readonly
`dataTypeList`	Allowed datatypes	readonly
`baseConfig`	Base configuration name. This identifies the shared set of configuration with all the analyzer's flavors	readonly
`jobCache`	Report cache timeout in minutes, visible for `orgAdmin` users only	writable
`rate`	Numeric amount of analyzer calls authorized for the specified `rateUnit`, visible for `orgAdmin` users only	writable
`rateUnit`	Period of availability of the rate limite: `Day` or `Month`, visible for `orgAdmin` users only	writable
`configuration`	A JSON object where key/value pairs represent the config names, and their values. It includes the default properties `proxy_http`, `proxy_https`, `auto_extract_artifacts`, `check_tlp`, and `max_tlp`, visible for `orgAdmin` users only	writable
`createdBy`	User who enabled the analyzer	computed
`updatedAt`	Last update date	computed
`updatedBy`	User who last updated the analyzer	computed

Enable

This call allows a user with an orgAdmin role to enable an analyzer.

curl -XPOST -H 'Authorization: Bearer **API_KEY**' 'https://127.0.0.1/automation/api/organization/analyzer/:analyzerId' -d '{
  "name": "Censys_1_0",
  "configuration": {
    "uid": "XXXX",
    "key": "XXXXXXXXXXXXXXXXXXXX",
    "proxy_http": "http://proxy:9999",
    "proxy_https": "http://proxy:9999",
    "auto_extract_artifacts": false,
    "check_tlp": true,
    "max_tlp": 2
  },
  "rate": 1000,
  "rateUnit": "Day",
  "jobCache": 5
}'

List and Search

These calls allow a user with a analyze or orgAdmin role to list and search all the enabled analyzers within the organization.

curl -H 'Authorization: Bearer **API_KEY**' 'https://127.0.0.1/automation/api/analyzer'

or

curl -XPOST -H 'Authorization: Bearer **API_KEY**' -H 'Content-Type: application/json' 'https://127.0.0.1/automation/api/analyzer/_search' -d '{
  "query": {}
}'

Both calls supports the range and sort query parameters declared in paging and sorting details, and both return a JSON array of analyzer objects as described in Analyzer Model section.

If called by a user with only an analyzer role, the configuration attribute is not included on the JSON objects.

Get Details

This call allows a user with a analyze or orgAdmin role to get an analyzer’s details.

curl -H 'Authorization: Bearer **API_KEY**' 'https://127.0.0.1/automation/api/analyzer/ANALYZER_ID'

It returns a analyzer JSON object as described in Analyzer Model section.

If called by a user with only an analyzer role, the configuration attribute is not included on the JSON objects.

Get By Type

This call is mostly used by Energy SOAR Base and allows to quickly get the list of analyzers that can run on the given datatype. It requires an analyze or orgAdmin role.

curl -H 'Authorization: Bearer **API_KEY**' 'https://127.0.0.1/automation/api/analyzer/type/DATA_TYPE'

It returns a JSON array of analyzer objects as described in Analyzer Model section without the configuration attribute, which could contain sensitive data.

Update

This call allows an orgAdmin user to update the name, configuration and jobCache of an enabled analyzer.

curl -XPATCH -H 'Authorization: Bearer **API_KEY**' -H 'Content-Type: application/json' 'https://127.0.0.1/automation/api/analyzer/ANALYZER_ID' -d '{
  "configuration": {
    "key": "XXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "polling_interval": 60,
    "proxy_http": "http://localhost:8080",
    "proxy_https": "http://localhost:8080",
    "auto_extract_artifacts": true,
    "check_tlp": true,
    "max_tlp": 1
  },
  "name": "Shodan_Host_1_0",
  "rate": 1000,
  "rateUnit": "Day",
  "jobCache": null
}'

It returns a JSON object describing the analyzer as defined in Analyzer Model section.

Run

This API allows a user with a analyze or orgAdmin role to run analyzers on observables of different datatypes.

For file observables, the API call must be made as described below:

curl -XPOST -H 'Authorization: Bearer **API_KEY**' -H 'Content-Type: application/json' 'https://127.0.0.1/automation/api/analyzer/ANALYZER_ID/run' \
  -F 'attachment=@/path/to/observable-file' \
  -F '_json=<-;type=application/json' << _EOF_
  {
    "dataType":"file",
    "tlp":0
  }
_EOF_

for all the other types of observerables, the request is:

curl -XPOST -H 'Authorization: Bearer **API_KEY**' -H 'Content-Type: application/json' 'https://127.0.0.1/automation/api/analyzer/ANALYZER_ID/run' -d '{
  "data":"8.8.8.8",
  "dataType":"ip",
  "tlp":0,
  "message": "A message that can be accessed from the analyzer",
  "parameters": {
    "key1": "value1",
    "key2": "value2"
  }
}'

This call will fetch a similar job from the cache, and if it finds one, it returns it from the cache, based on the duration defined in jobCache attribute of the analyzer.

To force bypassing the cache, one can add the following query parameter: force=1

curl -XPOST -H 'Authorization: Bearer **API_KEY**' -H 'Content-Type: application/json' 'https://127.0.0.1/automation/api/analyzer/ANALYZER_ID/run?force=1' -d '{
  "data":"8.8.8.8",
  "dataType":"ip",
  "tlp":0,
  "message": "A message that can be accessed from the analyzer",
  "parameters": {
    "key1": "value1",
    "key2": "value2"
  }
}'

Disable

This API allows an orgAdmin to disable an existing analyzer in their organization and delete the corresponding configuration.

curl -XDELETE -H 'Authorization: Bearer **API_KEY**' 'https://127.0.0.1/automation/api/analyzer/ANALYZER_ID'

Responder APIs

The following section describes the APIs that allow manipulating responders. Responders act on Energy SOAR Base entities (cases, alerts, tasks, observables) and return an action report, as opposed to analyzers which operate on raw observable data.

Responder Model

A responder is defined by the following attributes:

Attribute	Description	Type
`id`	Responder ID once enabled within an organization	readonly
`responderDefinitionId`	Responder definition name	readonly
`name`	Name of the responder	readonly
`version`	Version of the responder	readonly
`description`	Description of the responder	readonly
`author`	Author of the responder	readonly
`url`	URL where the responder has been published	readonly
`license`	License of the responder	readonly
`dataTypeList`	Entity types the responder can act on (`case`, `alert`, `case_task`, `case_artifact`)	readonly
`baseConfig`	Base configuration name shared across all flavors of this responder	readonly
`maxTlp`	Maximum TLP level of the entity the responder will accept	writable
`maxPap`	Maximum PAP level of the entity the responder will accept	writable
`jobCache`	Report cache timeout in minutes, visible for `orgAdmin` users only	writable
`rate`	Numeric amount of responder calls authorized for the specified `rateUnit`, visible for `orgAdmin` users only	writable
`rateUnit`	Period of availability of the rate limit: `Day` or `Month`, visible for `orgAdmin` users only	writable
`configuration`	JSON object of key/value configuration pairs. Includes default properties `proxy_http`, `proxy_https`, `check_tlp`, `max_tlp`, `check_pap`, and `max_pap`. Visible for `orgAdmin` users only	writable
`createdBy`	User who enabled the responder	computed
`updatedAt`	Last update date	computed
`updatedBy`	User who last updated the responder	computed

Enable

This call allows a user with an orgAdmin role to enable a responder within their organization.

curl -XPOST -H 'Authorization: Bearer **API_KEY**' -H 'Content-Type: application/json' 'https://127.0.0.1/automation/api/organization/responder/RESPONDER_DEFINITION_ID' -d '{
  "name": "Mailer_1_0",
  "configuration": {
    "from": "noreply@example.com",
    "smtp_host": "smtp.example.com",
    "proxy_http": "",
    "proxy_https": "",
    "check_tlp": true,
    "max_tlp": 2,
    "check_pap": true,
    "max_pap": 2
  },
  "rate": 1000,
  "rateUnit": "Day",
  "jobCache": 0
}'

List and Search

These calls allow a user with a read or orgAdmin role to list and search all enabled responders within the organization.

curl -H 'Authorization: Bearer **API_KEY**' 'https://127.0.0.1/automation/api/responder'

or

curl -XPOST -H 'Authorization: Bearer **API_KEY**' -H 'Content-Type: application/json' 'https://127.0.0.1/automation/api/responder/_search' -d '{
  "query": {}
}'

Both calls support the range and sort query parameters described in paging and sorting details, and return a JSON array of responder objects as described in Responder Model.

If called by a user without an orgAdmin role, the configuration attribute is not included in the returned objects.

Get Details

This call allows a user with a read or orgAdmin role to get a responder’s details.

curl -H 'Authorization: Bearer **API_KEY**' 'https://127.0.0.1/automation/api/responder/RESPONDER_ID'

It returns a responder JSON object as described in Responder Model.

Get By Type

Returns the list of responders that can act on a given entity type. Requires a read or orgAdmin role.

curl -H 'Authorization: Bearer **API_KEY**' 'https://127.0.0.1/automation/api/responder/type/DATA_TYPE'

DATA_TYPE is one of: case, alert, case_task, case_artifact.

It returns a JSON array of responder objects without the configuration attribute.

Update

This call allows an orgAdmin user to update the name, configuration, jobCache, rate, rateUnit, maxTlp and maxPap of an enabled responder.

curl -XPATCH -H 'Authorization: Bearer **API_KEY**' -H 'Content-Type: application/json' 'https://127.0.0.1/automation/api/responder/RESPONDER_ID' -d '{
  "configuration": {
    "from": "alerts@example.com",
    "smtp_host": "smtp.example.com",
    "check_tlp": true,
    "max_tlp": 3,
    "check_pap": true,
    "max_pap": 3
  },
  "rate": 500,
  "rateUnit": "Month"
}'

It returns a JSON object describing the responder as defined in Responder Model.

Run

This API allows a user with a analyze or orgAdmin role to run a responder on an entity. The data field contains the full JSON object of the entity to act on, and dataType specifies the entity type.

curl -XPOST -H 'Authorization: Bearer **API_KEY**' -H 'Content-Type: application/json' 'https://127.0.0.1/automation/api/responder/RESPONDER_ID/run' -d '{
  "data": {
    "id": "AVqqdpY2yQ6w1DNC8aDh",
    "caseId": 42,
    "title": "Phishing campaign detected",
    "severity": 3,
    "status": "Open",
    "tlp": 2,
    "pap": 2
  },
  "dataType": "case",
  "tlp": 2,
  "pap": 2,
  "message": "Notify incident response team"
}'

The call returns a job object as described in the Job Model section.

Disable

This API allows an orgAdmin to disable an existing responder in their organization.

curl -XDELETE -H 'Authorization: Bearer **API_KEY**' 'https://127.0.0.1/automation/api/responder/RESPONDER_ID'

A successful request returns HTTP 204 (no content).

Miscellaneous APIs

Paging and Sorting

All the search API calls allow sorting and paging parameters, in addition to a query in the request’s body. These calls usually have URLs ending with the _search keyword but that’s not always the case.

The followings are query parameters:

range: all or x-y where x and y are numbers (ex: 0-10).
sort: you can provide multiple sort criteria such as: -createdAt or +status.

Example:

curl -XPOST -H 'Authorization: Bearer **API_KEY**' -H 'Content-Type: application/json' 'http://127.0.0.1/automation/api/organization/ORG_ID/user?range=0-10&sort=-createdAt&sort=+status' -d '{
  "query": {}
}'

API

Base API Guide

Authentication

Using API key

Using basic authentication

Alert

Model definition

Alert Manipulation

Alert methods

Get an alert

Create an alert

Merge an alert

Bulk merge alert

Observable

Model definition

Observable manipulation

Observable methods

List Observables of a Case

Case

Model definition

Case Manipulation

Case methods

Create a Case

Log

Model definition

Log manipulation

Log methods

Create a log

Task

Model definition

Task manipulation

Task methods

Create a task

Energy SOAR Base Model Definition

Field Types

Common Attributes

Request formats

Query String

URL-encoded Form

JSON

Multi-part

Response Format

User

Model definition

User Manipulation

User methods

Create a User

EnergySOAR events webhook activation

Methods

Trigger types:

Case Template

Methods

Model

Create a template

Custom Field

Methods

Model

Create a custom field

Delete a custom field

Stream

Methods

Create a stream

Poll for events

Session status

Action

Methods

Action model

Run an action

Get actions for an entity

Organisation

Methods

Model

Create an organisation

Link organisations

Share

Methods

Share a case

Share a task or observable individually

Audit

Methods