Playbook APIs

What Are Bolster Playbook APIs?

Bolster Playbook APIs are the API translations of the output of a Bolster Playbook. Every time a configured Bolster Playbook runs and has results, the results are published in Bolster’s cloud temporarily for 72 hours (as well as sent to any connector destinations the customer has configured for the playbook). If a customer would like to interact with the data results via API, instead of receiving the data directly in a JSON/CSV output, the Playbook API is available for this use case.

Each time a playbook runs, it creates a new file with a unique history ID (assuming there are new results).
In order to receive the results via API:

1. Run the History API command to return the History IDs of any configured playbooks.
   
   The most recent History ID will be located at the top of the results just beneath the “name” field of the Playbook.
2. Identify that ID to see the results in the next step.
3. Use the Results API to return all configured data fields for that specific ID, as pictured.

Available Playbook APIs

Bolster offers the following APIs to enable integration of playbook results with other apps and tools:

• History API
• Results API
• Latest-Results API

Before You Start

The API Key required for using the playbook APIs is displayed in your Profile Information page.

History API

POST /api/neo/v1/playbook

Description

The History API returns a list of playbooks and the history for each run of a given playbook. Each run has its own set of results, given new information present for that run.

Sample Request

curl -X POST -H 'Content-Type: application/json' 
-d '{"apiKey": "API_KEY"}' 
https://developers.bolster.ai/api/neo/v1/playbook

Sample Response

{
  "schedules": [
    {
      "id": 1234,
      "name": "Sample Playbook",
      "history": [
        {
          "id": 7890,
          "resultCount": 3,
          "status": "COMPLETE",
          "createdTs": "2022-07-11T21:36:44.047Z",
          "updatedTs": "2022-07-11T21:36:45.445Z"
        },
        {
          "id": 5678,
          "resultCount": 7,
          "status": "COMPLETE",
          "createdTs": "2022-01-11T20:58:56.824Z",
          "updatedTs": "2022-01-11T20:58:59.324Z"
        }
      ]
    }
  ]
}

In this example:

• The “Sample Playbook” playbook has ID 1234.
• Two runs of the “Sample Playbook” playbook are listed with IDs of 7890 and 5678.

Results API

POST /api/neo/v1/playbook/download

Description

The Results API returns the data for the results set identified by the supplied history ID.

Note: Playbook results expire and will no longer be available for download after 7 days.

Sample Request

curl -X POST -H 'Content-Type: application/json' 
-d '{"apiKey": "API_KEY", "historyId": 7890}' 
https://developers.bolster.ai/api/neo/v1/playbook/download

where:

• API_KEY is the API Key from your Profile Information page.
• historyId is the playbook history ID returned by the History API.

Sample Response

[
    {
        "Original Disposition": "phish",
        "First Seen": "2022-07-11T17:29:53.021Z",
        "Source URL": "https://bankofbolster.com/html/fish.html",
        "Hosting Provider": "eName Technology Co., Ltd.",
        "Takedown Requests": 0,
        "Logo Detected": false,
        "IP Address": "172.31.4.243",
        "Registration Date": "2016-11-03T18:10:19.000Z",
        "Category": "banking",
        "MX Records": false
    },
    {
        "Original Disposition": "scam",
        "First Seen": "2022-07-11T17:29:53.021Z",
        "Source URL": "https://zxcvasdfqwer.com/html/slam.html",
        "Hosting Provider": "GoDaddy.com, LLC",
        "Takedown Requests": 0,
        "Logo Detected": true,
        "IP Address": "172.31.4.243",
        "Registration Date": "2012-04-24T06:59:34.000Z",
        "Category": "gift_card",
        "MX Records": false
    },
    {
        "Original Disposition": "phish",
        "First Seen": "2022-07-11T17:29:53.021Z",
        "Source URL": "https://zxcvasdfqwer.com/html/slam.html#1639004277187",
        "Hosting Provider": "OVH",
        "Takedown Requests": 0,
        "Logo Detected": true,
        "IP Address": "172.31.4.243",
        "Registration Date": "2012-04-24T06:59:34.000Z",
        "Category": "unknown",
        "MX Records": false
    }
]

Latest-Results API

POST /api/neo/v1/playbook/download-latest

Description

The Latest-Results API returns only the data returned by the most recent run of the identified playbook.

Sample Request

curl -X POST -H 'Content-Type: application/json' 
-d '{"apiKey": "API_KEY", "playbookId": 7890}' 
https://developers.bolster.ai/api/neo/v1/playbook/download-latest

where:

• API_KEY is the API Key from your Profile Information page.
• playbookId is the identifier for the Bolster playbook of interest as it appears in the Automation page.

Sample Response

[
    {
        "Source URL": "http://bolbolbank.com/",
        "IP Address": "56.21.177.26",
        "Current Disposition": "suspicious",
        "Category": "directory_listing",
        "Registrant": "Domains By Proxy, LLC",
        "MX Records": false,
        "Tags": [
            "Top Priority"
        ]
    }
]