NAV Navbar

Introduction

Base URL for the API

https://api.bluematador.com

Welcome to the Blue Matador API. The API allows you to interact with Blue Matador resources outside of the UI. All endpoints use standard HTTP verbs, authentication, and JSON for request and response bodies.

Authentication

An example of authenticating with Blue Matador

curl "api_endpoint_here"
  -H "Authorization: D6bSkilgbSVm8djsMcMkrcD4QbCJ0n35"

Make sure to replace D6bSkilgbSVm8djsMcMkrcD4QbCJ0n35 with your API key

All API endpoints are scoped to an account and require an API key for access. You can retrieve an API key for an account by visiting the in app page for API keys.

Once you have an API key, you can authenticate calls to Blue Matador by passing your API key as the value for the Authorization header:

Authorization: D6bSkilgbSVm8djsMcMkrcD4QbCJ0n35

Events

The Events API allows you to retrieve event related data from Blue Matador.

Get Events

Example Request

curl "https://api.bluematador.com/ma/api/accounts/a976a6af-cf87-4dd1-942f-b13a30be9351/events?start=2019-03-22T00:00:00Z&end=2019-03-23T00:00:00Z"

Example Response

[
  {
    // id of the event
    "id": "b97da6af-1f87-4cd1-992f-113a60be9358",
    // id of the account
    "accountId": "a976a6af-cf87-4dd1-942f-b13a30be9351",
    // event opened date
    "opened": "2019-03-22T15:07:08Z",
    // event close date (optional)
    “closed”: null,
    // enum of the type of event
    "eventType": "route53_zone_ns",
    // display string for type of event
    "typeText": "Route53 Zone NS Records",
    // display string for event summary
    "summaryText": "The configured NS records for the zone does not match the actual query response",
    // list of additional details about the event
    "detailTexts": [
      "ns-1408.awsdns-60.org.",
      "ns-1781.awsdns-18.co.uk.",
      "ns-31.awsdns-04.com.",
      "ns-792.awsdns-26.net."
    ],
    // anomaly, warning, alert
    "severity": "anomaly",
    // details about the resource affected by the event
    "source": {
      // identification data about the resource
      "ref": {
        "arn": "arn:aws:route53:::hostedzone/Z132S03H3a5QD",
        "refType": "aws_arn"
      }",
      // a label describing the type of resource
      "label": "Route53 Zone",
      // a text representation of the resource
      "text": "thedevcloud.com.",
      // a list of key-value pairs that further identify the resource
      "tags": [
        {
          "key": "AWS Account",
          "value": "blue-poc"
        },
        {
          "key": "Public",
          "value": "true"
        },
        {
          "key": "Zone ID",
          "value": "Z132S03H3a5QD"
        }
      ]
    },
    // links to event troubleshooting, AWS, and incident management
    "links": [
      {
        "linkType": "troubleshooting",
        "text": "Troubleshooting",
        "url": "https://app.bluematador.com/ur/troubleshooting/route53-hosted-zone#ns",
        "created": "2019-03-22T17:11:08.092Z"
      },
      {
        "linkType": "aws",
        "text": "AWS Console",
        "url": "https://app.bluematador.com/ur/awsLink?url=https%3A%2F%2Fconsole.aws.amazon.com%2Froute53%2Fhome%23resource-record-sets%3AZ152S03H3I5QD",
        "created": "2019-03-22T17:11:08.092Z"
      }
    ],
    // a list of projects the event belongs to
    "projects": [
      {
        "id": "6f0ac475-4594-4b86-87d7-7f8b0645126a",
        "accountId": "a976a6af-cf87-4dd1-942f-b13a30be9351",
        "created": "2019-02-19T17:41:05Z",
        "name": "Sandbox"
      }
    ],
    // whether the event was not sent to notification systems
    "muted": false,
    // whether the event should be hidden
    "hidden": false
  },
…
]

This endpoint retrieves Blue Matador events from an account within a time period

HTTP Request

GET https://api.bluematador.com/ma/api/accounts/<account_id>/events

Path Parameters

Name Type Description
account_id UUID the ID of the account to get events from

Query Parameters

Name Type Description
start ISO 8601 date the open time for the earliest events to retrieve
end ISO 8601 date the open time for the latest events to retrieve
project string (optional) only get events for a particular project

Graphs

Example Request

curl "https://api.bluematador.com/ma/api/accounts/a976a6af-cf87-4dd1-942f-b13a30be9351/counts"

Example Response

{
  // an object containing anomaly, warning, alert objects containing
  // the number of events in that severity opened that day
  "opened": {
    "warning": {
      "2019-03-01T00:00:00Z": 35,
      "2019-03-13T00:00:00Z": 43,
      "2019-03-06T00:00:00Z": 28,
      ...
    },
    "anomaly": {
      "2019-03-01T00:00:00Z": 52,
      "2019-03-13T00:00:00Z": 45,
      "2019-03-06T00:00:00Z": 33,
      ...
    },
    "alert": {
      "2019-03-01T00:00:00Z": 0,
      "2019-03-13T00:00:00Z": 1,
      "2019-03-06T00:00:00Z": 0,
      ...
    }
  },
  // an object containing anomaly, warning, alert objects containing
  // the number of events in that severity active that day
  "active": {
    "warning": {
      "2019-03-01T00:00:00Z": 45,
      "2019-03-13T00:00:00Z": 51,
      "2019-03-06T00:00:00Z": 35,
      ...
    },
    "anomaly": {
      "2019-03-01T00:00:00Z": 59,
      "2019-03-13T00:00:00Z": 52,
      "2019-03-06T00:00:00Z": 41,
      ...
    },
    "alert": {
      "2019-03-01T00:00:00Z": 12,
      "2019-03-13T00:00:00Z": 13,
      "2019-03-06T00:00:00Z": 12,
      ...
    }
  }
}

The Graphs API endpoint returns the counts of events opened and active for each day in the last 30 days for an account.

HTTP Request

GET https://api.bluematador.com/ma/api/accounts/<account_id>/counts

Path Parameters

Name Type Description
account_id UUID the ID of the account to get counts from

Query Parameters

Name Type Description
project string (optional) only get counts for a particular project

Integrations

The Integrations API allows you to interact with integrations. Integrations are the sources of data monitored by Blue Matador.

List Integrations

List Integrations Example

curl https://api.bluematador.com/zi/accounts/a976a6af-cf87-4dd1-942f-b13a30be9351/inbounds

Example Response

[
  {
    "accountId": "a976a6af-cf87-4dd1-942f-b13a30be9351",
    "id": "d37da6af-1f87-4cd1-992f-113a60be9358",
    "inboundType": "aws",
    "created": "2019-03-22T15:07:08Z",
    "enabled": true,
    "data": {
      "name": "Prod AWS",
      "accountId": "50484629850", // AWS account ID
      "keyType": "aws",
      // non-sensitive key parts only
      "keys": {
        "accessKeyId": "AKIAU6EBUO39S2JQAB03"
      },
      "status": {
        "lastSuccess": "2019-03-23T09:01:01Z",
        "lastError": null,
        "recentErrors": []
      },
    }
  },
  ...
]

Lists all integrations for an account.

HTTP Request

GET https://api.bluematador.com/zi/accounts/<account_id>/inbounds

Create AWS Integration

Create AWS Integration Example

curl -X POST  -H "Content-Type: application/json" \
  -d '{
    "name": "Prod AWS",
    "accessKeyId": "AKIAU6EBUO39S2JQAB03",
    "secretAccessKey": "Zx4xOm4ioTc0f3ylhGZkSSBp4P2M1KpcNlV2Uoe1"
  }' \
  "https://api.bluematador.com/zi/accounts/a976a6af-cf87-4dd1-942f-b13a30be9351/inbounds/aws"

Example Response

{
  "accountId": "a976a6af-cf87-4dd1-942f-b13a30be9351",
  "id": "d37da6af-1f87-4cd1-992f-113a60be9358",
  "inboundType": "aws",
  "created": "2019-03-22T15:07:08Z",
  "enabled": true,
  "data": {
    "name": "Prod AWS",
    "accountId": "50484629850", // AWS account ID
    "keyType": "aws",
    // non-sensitive key parts only
    "keys": {
      "accessKeyId": "AKIAU6EBUO39S2JQAB03"
    },
    "status": {
      "lastSuccess": null,
      "lastError": null,
      "recentErrors": []
    },
  }
}

This endpoint creates a new AWS integration.

HTTP Request

POST https://api.bluematador.com/zi/accounts/<account_id>/inbounds/aws

Path Parameters

Name Type Description
account_id UUID the ID of the account to create an integration for

Request Body

The AWS integration can authenticate with either IAM users or IAM roles, and the shape of your request payload determines which type of authentication will be used.

IAM User Authentication

Name Type Description
name string a name used to identify the new integration
accessKeyId string the Access Key ID of the IAM user to authenticate as
secretAccessKey string the secret for the access key

IAM Role Assumption

Name Type Descirption
name string a name used to identify the new integration
roleArn string the ARN for the IAM role to assume
externalId string a string used as the external ID when assuming the role

When using IAM Role authentication, the role must be set up to allow Blue Matador's AWS account as a trusted identity so that Blue Matador can use AssumeRole. Blue Matador's AWS Account ID is: 339597358577

Update AWS Integration

Update AWS Integration Example

curl -X PUT  -H "Content-Type: application/json" \
  -d '{
    "name": "Prod AWS",
    "accessKeyId": "AKIAU5EBCO39SDJQAB01",
    "secretAccessKey": "1x4xCm4ioTc0f3ylhGZtSSBp4P2M1npcNlV2Uoec"
  }' \
  "https://api.bluematador.com/zi/accounts/a976a6af-cf87-4dd1-942f-b13a30be9351/inbounds/aws/d37da6af-1f87-4cd1-992f-113a60be9358"

Example Response

{
  "accountId": "a976a6af-cf87-4dd1-942f-b13a30be9351",
  "id": "d37da6af-1f87-4cd1-992f-113a60be9358",
  "inboundType": "aws",
  "created": "2019-03-22T15:07:08Z",
  "enabled": true,
  "data": {
    "name": "Prod AWS",
    "accountId": "10384429840", // AWS account ID
    "keyType": "aws",
    // non-sensitive key parts only
    "keys": {
      "accessKeyId": "AKIAU5EBCO39SDJQAB01"
    },
    "status": {
      "lastSuccess": "2019-03-23T09:01:01Z",
      "lastError": null,
      "recentErrors": []
    },
  }
}

This endpoint updates an existing AWS integration.

HTTP Request

PUT https://api.bluematador.com/zi/accounts/<account_id>/inbounds/aws/<id>

Path Parameters

Name Type Description
account_id UUID the ID of the account that owns the integration
id UUID the id of the integration to update

Request Body

The AWS integration can authenticate with either IAM users or IAM roles, and the shape of your request payload determines which type of authentication will be used.

IAM User Authentication

If you are only updating the name of the integration, you can omit credentials.

Name Type Description
name string a name used to identify the new integration
accessKeyId string (optional) the Access Key ID of the IAM user to authenticate as
secretAccessKey string (optional) the secret for the access key

IAM Role Assumption

If you are only updating the name of the integration, you can omit credentials.

Name Type Description
name string a name used to identify the new integration
roleArn string (optional) the ARN for the IAM role to assume
externalId string (optional) a string used as the external ID when assuming the role

Create Azure Integration

Create Azure Integration Example

curl -X POST  -H "Content-Type: application/json" \
  -d '{
    "name": "Prod Azure Subscription",
    "subscriptionId": "c37da5a1-bf17-9cd0-092e-b13360be9355",
    "tenantId": "6678a6aa-cf84-6c11-d95f-517a60be0351",
    "applicationId": "16b8a699-468c-cc44-195d-a12a628e8352",
    "secret": "-5eF10S0Cu7[h?AAa4nscA?19?5c+2.Zs"
  }' \
  "https://api.bluematador.com/zi/accounts/a976a6af-cf87-4dd1-942f-b13a30be9351/inbounds/azure"

Example Response

{
  "accountId": "a976a6af-cf87-4dd1-942f-b13a30be9351",
  "id": "d37da6af-1f87-4cd1-992f-113a60be9358",
  "inboundType": "azure",
  "created": "2019-03-22T15:07:08Z",
  "enabled": true,
  "data": {
    "name": "Prod Azure Subscription",
    "subscriptionId": "c37da5a1-bf17-9cd0-092e-b13360be9355",
    "tenantId": "6678a6aa-cf84-6c11-d95f-517a60be0351",
    // non-sensitive key parts only
    "keys": {
      "applicationId": "16b8a699-468c-cc44-195d-a12a628e8352"
    },
    "status": {
      "lastSuccess": null,
      "lastError": null,
      "recentErrors": []
    },
  }
}

This endpoint creates a new Azure integration. Authentication for the Azure is handled through app registrations in active directory.

HTTP Request

POST https://api.bluematador.com/zi/accounts/<account_id>/inbounds/azure

Path Parameters

Name Type Description
account_id UUID the ID of the account to create an integration for

Request Body

Name Type Description
name string a name used to identify the new integration
subscriptionId uuid the ID of the subscription to be monitored
tenantId uuid the ID of the active directory containing the Blue Matador app registration
applicationId uuid the ID of the app registration
secret string the client secret

Update Azure Integration

Update Azure Integration Example

curl -X PUT  -H "Content-Type: application/json" \
  -d '{
    "name": "Prod Azure Subscription",
    "subscriptionId": "c37da5a1-bf17-9cd0-092e-b13360be9355",
    "tenantId": "6678a6aa-cf84-6c11-d95f-517a60be0351",
    "applicationId": "16b8a699-468c-cc44-195d-a12a628e8352",
    "secret": "-5eF10S0Cu7[h?AAa4nscA?19?5c+2.Zs"
  }' \
  "https://api.bluematador.com/zi/accounts/a976a6af-cf87-4dd1-942f-b13a30be9351/inbounds/azure/d37da6af-1f87-4cd1-992f-113a60be9358"

Example Response

{
  "accountId": "a976a6af-cf87-4dd1-942f-b13a30be9351",
  "id": "d37da6af-1f87-4cd1-992f-113a60be9358",
  "inboundType": "azure",
  "created": "2019-03-22T15:07:08Z",
  "enabled": true,
  "data": {
    "name": "Prod Azure Subscription",
    "subscriptionId": "c37da5a1-bf17-9cd0-092e-b13360be9355",
    "tenantId": "6678a6aa-cf84-6c11-d95f-517a60be0351",
    // non-sensitive key parts only
    "keys": {
      "applicationId": "16b8a699-468c-cc44-195d-a12a628e8352"
    },
    "status": {
      "lastSuccess": null,
      "lastError": null,
      "recentErrors": []
    },
  }
}

This endpoint updates an existing Azure integration.

HTTP Request

PUT https://api.bluematador.com/zi/accounts/<account_id>/inbounds/azure/<id>

Path Parameters

Name Type Description
account_id UUID the ID of the account that owns the integration
id UUID the id of the integration to update

Request Body

Name Type Description
name string a name used to identify the new integration
subscriptionId uuid (optional) the ID of the subscription to be monitored
tenantId uuid (optional) the ID of the active directory containing the Blue Matador app registration
applicationId uuid (optional) the ID of the app registration
secret string (optional) the client secret

Disable an Integration

Disable Integration Example

curl -X PUT "https://api.bluematador.com/zi/accounts/a976a6af-cf87-4dd1-942f-b13a30be9351/inbounds/d37da6af-1f87-4cd1-992f-113a60be9358/disable"

The endpoint returns 200 OK when successful

This endpoint allows you to disable an integration. Disabled integrations are not monitored by Blue Matador.

HTTP Request

PUT https://api.bluematador.com/zi/accounts/<account_id>/inbounds/<id>/disable

Path Parameters

Name Type Description
account_id UUID the ID of the account that owns the integration
id UUID the id of the integration to disable

Enable an Integration

Enable Integration Example

curl -X PUT "https://api.bluematador.com/zi/accounts/a976a6af-cf87-4dd1-942f-b13a30be9351/inbounds/d37da6af-1f87-4cd1-992f-113a60be9358/disable"

The endpoint returns 200 OK when successful

This endpoint allows you to re-enable an integration.

HTTP Request

PUT https://api.bluematador.com/zi/accounts/<account_id>/inbounds/<id>/enable

Path Parameters

Name Type Description
account_id UUID the ID of the account that owns the integration
id UUID the id of the integration to enable

Delete an Integration

Delete Integration Example

curl -X DELETE "https://api.bluematador.com/zi/accounts/a976a6af-cf87-4dd1-942f-b13a30be9351/inbounds/d37da6af-1f87-4cd1-992f-113a60be9358"

The endpoint returns 200 OK when successful

This endpoint allows you to delete an integration.

HTTP Request

DELETE https://api.bluematador.com/zi/accounts/<account_id>/inbounds/<id>

Path Parameters

Name Type Description
account_id UUID the ID of the account that owns the integration
id UUID the id of the integration to delete

Notifications

The Notifications API allows you to interact with notification methods. Events detected by Blue Matador are sent through these notification methods.

List Notifications

List Notification Example

curl https://api.bluematador.com/zi/accounts/a976a6af-cf87-4dd1-942f-b13a30be9351/outbounds

Example Response

[
  {
    "accountId": "a976a6af-cf87-4dd1-942f-b13a30be9351",
    "id": "086e5a82-3116-4257-8f6b-260ec3fef2cd",
    "created": "2019-03-22T15:07:08Z",
    "enabled": true,
    "data": {
      "status": {
        "lastSuccess": "2019-03-23T09:01:01Z",
        "lastError": null,
        "recentErrors": []
      },
      "severities": {
        "all": [
          "warning",
          "alert"
        ],
        "3833aa2a-de1c-4b48-8722-4ec79fb6c2e4": [
          "warning"
        ]
      },
      "email": "example@example.com"
    },
    "credentials": null,
    "outboundType": "email"
  },
  ...
]

Lists all notifications for an account. Notification objects differ based on their type.

HTTP Request

GET https://api.bluematador.com/zi/accounts/<account_id>/outbounds

Create an Email Notification

Create Email Notification Example

curl -X POST -H "Content-Type: application/json" \
  -d '{
    "email": "example@example.com",
    "severities": {
      "all": ["alert", "warning"],
    }
  }' \
  "https://api.bluematador.com/zi/accounts/a976a6af-cf87-4dd1-942f-b13a30be9351/outbounds/email"

Example Response

{
  "accountId": "a976a6af-cf87-4dd1-942f-b13a30be9351",
  "id": "686e5a82-3116-4257-8f6b-260ec3fef2cd",
  "created": "2019-03-22T15:07:08Z",
  "enabled": true,
  "data": {
    "status": {
      "lastSuccess": null,
      "lastError": null,
      "recentErrors": []
    },
    "severities": {
      "all": [
        "warning",
        "alert"
      ],
    },
    "email": "example@example.com"
  },
  "credentials": null,
  "outboundType": "email"
}

This endpoint creates a new email notification.

HTTP Request

POST https://api.bluematador.com/zi/accounts/<account_id>/outbounds/email

Path Parameters

Name Type Description
account_id UUID the ID of the account to create a notification for

Request Body

Name Type Description
email string the email address to send notifications to
severities Object a map of project to an array of the event types to notify on (read more)

Update an Email Notification

Update Email Notification Example

curl -X PUT -H "Content-Type: application/json" \
  -d '{
    "email": "example@example.com",
    "severities": {
      "all": ["alert", "warning"],
    }
  }' \
  "https://api.bluematador.com/zi/accounts/a976a6af-cf87-4dd1-942f-b13a30be9351/outbounds/email/686e5a82-3116-4257-8f6b-260ec3fef2cd"

Example Response

{
  "accountId": "a976a6af-cf87-4dd1-942f-b13a30be9351",
  "id": "686e5a82-3116-4257-8f6b-260ec3fef2cd",
  "created": "2019-03-22T15:07:08Z",
  "enabled": true,
  "data": {
    "status": {
      "lastSuccess": "2019-03-23T09:01:01Z",
      "lastError": null,
      "recentErrors": []
    },
    "severities": {
      "all": [
        "warning",
        "alert"
      ],
    },
    "email": "example@example.com"
  },
  "credentials": null,
  "outboundType": "email"
}

This endpoint updates an existing email notification.

HTTP Request

PUT https://api.bluematador.com/zi/accounts/<account_id>/outbounds/email/<id>

Path Parameters

Name Type Description
account_id UUID the ID of the account that owns the notification
id UUID the ID of the notification to update

Request Body

Name Type Description
email string the email address to send notifications to
severities Object a map of project to an array of the event types to notify on (read more)

Create a PagerDuty Notification

Create PagerDuty Notification Example

curl -X POST -H "Content-Type: application/json" \
  -d '{
    "name": "Prod PagerDuty",
    "severities": {
      "all": ["alert", "warning"],
    },
    "account": "example-pagerduty",
    "serviceName": "example Blue Matador",
    "serviceKey": "445cce5a3ad04113b4eb810c1b8cfd03"
  }' \
  "https://api.bluematador.com/zi/accounts/a976a6af-cf87-4dd1-942f-b13a30be9351/outbounds/pagerduty"

Example Response

{
  "accountId": "a976a6af-cf87-4dd1-942f-b13a30be9351",
  "id": "686e5a82-3116-4257-8f6b-260ec3fef2cd",
  "created": "2019-03-22T15:07:08Z",
  "enabled": true,
  "data": {
    "name": "Prod Pagerduty",
    "status": {
      "lastSuccess": null,
      "lastError": null,
      "recentErrors": []
    },
    "severities": {
      "all": [
        "warning",
        "alert"
      ],
    },
    "account": "example-pagerduty",
    "serviceName": "example Blue Matador"
  },
  "credentials": "<secret>",
  "outboundType": "pagerduty"
}

This endpoint creates a new PagerDuty notification.

HTTP Request

POST https://api.bluematador.com/zi/accounts/<account_id>/outbounds/pagerduty

Path Parameters

Name Type Description
account_id UUID the ID of the account to create a notification for

Request Body

Name Type Description
name string a name used to identify the new notification
severities Object a map of project to an array of the event types to notify on (read more)
account string the name of the PagerDuty account to notify
serviceName string the name of the PagerDuty service to notify
serviceSecret string the API key for the service

Update a PagerDuty Notification

Update PagerDuty Notification Example

curl -X PUT -H "Content-Type: application/json" \
  -d '{
    "name": "Prod PagerDuty",
    "severities": {
      "all": ["alert", "warning"],
    },
    "account": "example-pagerduty",
    "serviceName": "example Blue Matador"
  }' \
  "https://api.bluematador.com/zi/accounts/a976a6af-cf87-4dd1-942f-b13a30be9351/outbounds/pagerduty/686e5a82-3116-4257-8f6b-260ec3fef2cd"

Example Response

{
  "accountId": "a976a6af-cf87-4dd1-942f-b13a30be9351",
  "id": "686e5a82-3116-4257-8f6b-260ec3fef2cd",
  "created": "2019-03-22T15:07:08Z",
  "enabled": true,
  "data": {
    "name": "Prod Pagerduty",
    "status": {
      "lastSuccess": "2019-03-23T09:01:01Z",
      "lastError": null,
      "recentErrors": []
    },
    "severities": {
      "all": [
        "warning",
        "alert"
      ],
    },
    "account": "example-pagerduty",
    "serviceName": "example Blue Matador"
  },
  "credentials": "<secret>",
  "outboundType": "pagerduty"
}

This endpoint updates an existing PagerDuty notification.

HTTP Request

PUT https://api.bluematador.com/zi/accounts/<account_id>/outbounds/pagerduty/<id>

Path Parameters

Name Type Description
account_id UUID the ID of the account that owns the notification
id UUID the ID of the notification to update

Request Body

Name Type Description
name string a name used to identify the notification
severities Object a map of project to an array of the event types to notify on (read more)
account string the name of the PagerDuty account to notify
serviceName string the name of the PagerDuty service to notify
serviceSecret string (optional) the API key for the service

Create an Opsgenie Notification

Create Opsgenie Notification Example

curl -X POST -H "Content-Type: application/json" \
  -d '{
    "name": "Prod Opsgenie",
    "severities": {
      "all": ["alert", "warning"],
    },
    apikey: "a9e34f4c-c341-1546-b5ea-af1a33aeacf7"
  }' \
  "https://api.bluematador.com/zi/accounts/a976a6af-cf87-4dd1-942f-b13a30be9351/outbounds/opsgenie"

Example Response

{
  "accountId": "a976a6af-cf87-4dd1-942f-b13a30be9351",
  "id": "686e5a82-3116-4257-8f6b-260ec3fef2cd",
  "created": "2019-03-22T15:07:08Z",
  "enabled": true,
  "data": {
    "name": "OpsGenie Prod",
    "status": {
      "lastSuccess": null,
      "lastError": null,
      "recentErrors": []
    },
    "severities": {
      "all": []
    }
  },
  "credentials": "<secret>",
  "outboundType": "opsgenie"
}

This endpoint creates a new Opsgenie notification.

HTTP Request

POST https://api.bluematador.com/zi/accounts/<account_id>/outbounds/opsgenie

Path Parameters

Name Type Description
account_id UUID the ID of the account to create a notification for

Request Body

Name Type Description
name string a name used to identify the new notification
severities Object a map of project to an array of the event types to notify on (read more)
apikey string the apikey from the Opsgenie integration to use

Update an Opsgenie Notification

Update Opsgenie Notification Example

curl -X PUT -H "Content-Type: application/json" \
  -d '{
    "name": "Prod Opsgenie",
    "severities": {
      "all": ["alert", "warning"],
    }
  }' \
  "https://api.bluematador.com/zi/accounts/a976a6af-cf87-4dd1-942f-b13a30be9351/outbounds/opsgenie/686e5a82-3116-4257-8f6b-260ec3fef2cd"

Example Response

{
  "accountId": "a976a6af-cf87-4dd1-942f-b13a30be9351",
  "id": "686e5a82-3116-4257-8f6b-260ec3fef2cd",
  "created": "2019-03-22T15:07:08Z",
  "enabled": true,
  "data": {
    "name": "OpsGenie Prod",
    "status": {
      "lastSuccess": "2019-03-23T09:01:01Z",
      "lastError": null,
      "recentErrors": []
    },
    "severities": {
      "all": []
    }
  },
  "credentials": "<secret>",
  "outboundType": "opsgenie"
}

This endpoint updates an existing Opsgenie notification.

HTTP Request

PUT https://api.bluematador.com/zi/accounts/<account_id>/outbounds/opsgenie/<id>

Path Parameters

Name Type Description
account_id UUID the ID of the account that owns the notification
id UUID the ID of the notification to update

Request Body

Name Type Description
name string a name used to identify the notification
severities Object a map of project to an array of the event types to notify on (read more)
apikey string (optional) the apikey from the Opsgenie integration to use

Create an SNS Notification

Create SNS Notification Example

curl -X POST -H "Content-Type: application/json" \
  -d '{
    "name": "Prod SNS",
    "severities": {
      "all": ["alert", "warning"],
    },
    "topicArn": "arn:aws:sns:us-east-1:536714378879:oncall",
    "accessKeyId": "AKIAU6EBUO39S2JQAB03",
    "secretAccessKey": "Zx4xOm4ioTc0f3ylhGZkSSBp4P2M1KpcNlV2Uoe1"
  }' \
  "https://api.bluematador.com/zi/accounts/a976a6af-cf87-4dd1-942f-b13a30be9351/outbounds/sns"

Example Response

{
  "accountId": "a976a6af-cf87-4dd1-942f-b13a30be9351",
  "id": "686e5a82-3116-4257-8f6b-260ec3fef2cd",
  "created": "2019-03-22T15:07:08Z",
  "enabled": true,
  "data": {
    "name": "Prod SNS",
    "status": {
      "lastSuccess": null,
      "lastError": null,
      "recentErrors": []
    },
    "severities": {
      "all": [
        "alert",
        "warning"
      ]
    },
    "topicArn": "arn:aws:sns:us-east-1:536714378879:oncall",
    "accessKeyId": "AKIAU6EBUO39S2JQAB03"
  },
  "credentials": "<secret>",
  "outboundType": "sns"
}

This endpoint creates a new SNS notification.

HTTP Request

POST https://api.bluematador.com/zi/accounts/<account_id>/outbounds/sns

Path Parameters

Name Type Description
account_id UUID the ID of the account to create a notification for

Request Body

Name Type Description
name string a name used to identify the new notification
severities Object a map of project to an array of the event types to notify on (read more)
topicArn string the ARN of the SNS topic to send notifications to
accessKeyId string the Access Key ID of the IAM user to authenticate as
secretAccessKey string the secret for the access key

Update an SNS Notification

Update SNS Notification Example

curl -X PUT -H "Content-Type: application/json" \
  -d '{
    "name": "Prod SNS",
    "severities": {
      "all": ["alert", "warning"],
    },
    "topicArn": "arn:aws:sns:us-east-1:536714378879:oncall",
  }' \
  "https://api.bluematador.com/zi/accounts/a976a6af-cf87-4dd1-942f-b13a30be9351/outbounds/sns/686e5a82-3116-4257-8f6b-260ec3fef2cd"

Example Response

{
  "accountId": "a976a6af-cf87-4dd1-942f-b13a30be9351",
  "id": "686e5a82-3116-4257-8f6b-260ec3fef2cd",
  "created": "2019-03-22T15:07:08Z",
  "enabled": true,
  "data": {
    "name": "Prod SNS",
    "status": {
      "lastSuccess": "2019-03-23T09:01:01Z",
      "lastError": null,
      "recentErrors": []
    },
    "severities": {
      "all": [
        "alert",
        "warning"
      ]
    },
    "topicArn": "arn:aws:sns:us-east-1:536714378879:oncall",
    "accessKeyId": "AKIAU6EBUO39S2JQAB03"
  },
  "credentials": "<secret>",
  "outboundType": "sns"
}

This endpoint updates an existing SNS notification.

HTTP Request

PUT https://api.bluematador.com/zi/accounts/<account_id>/outbounds/sns/<id>

Path Parameters

Name Type Description
account_id UUID the ID of the account that owns the notification
id UUID the ID of the notification to update

Request Body

Name Type Description
name string a name used to identify the notification
severities Object a map of project to an array of the event types to notify on (read more)
topicArn string the ARN of the SNS topic to send notifications to
accessKeyId string (optional) the Access Key ID of the IAM user to authenticate as
secretAccessKey string (optional) the secret for the access key

Create a VictorOps Notification

Create VictorOps Notification Example

curl -X POST -H "Content-Type: application/json" \
  -d '{
    "name": "Prod VictorOps",
    "severities": {
      "all": ["alert", "warning"],
    },
    "integrationId": "29a7c0dd-8487-4248-9193-419fc43f03f8",
    "routingKey": "ops",
  }' \
  "https://api.bluematador.com/zi/accounts/a976a6af-cf87-4dd1-942f-b13a30be9351/outbounds/victorops"

Example Response


{
  "accountId": "a976a6af-cf87-4dd1-942f-b13a30be9351",
  "id": "686e5a82-3116-4257-8f6b-260ec3fef2cd",
  "created": "2019-03-22T15:07:08Z",
  "enabled": true,
  "data": {
    "name": "Prod VictorOps",
    "status": {
      "lastSuccess": null,
      "lastError": null,
      "recentErrors": []
    },
    "severities": {
      "all": [
        "alert",
        "warning"
      ]
    }
  },
  "credentials": "<secret>",
  "outboundType": "victorops"
}

This endpoint creates a new VictorOps notification.

HTTP Request

POST https://api.bluematador.com/zi/accounts/<account_id>/outbounds/victorops

Path Parameters

Name Type Description
account_id UUID the ID of the account to create a notification for

Request Body

Name Type Description
name string a name used to identify the new notification
severities Object a map of project to an array of the event types to notify on (read more)
integrationId string the ID of the VictorOps integration to send notifications to
routingKey string the routing key VictorOps should use

Update a VictorOps Notification

Update VictorOps Notification Example

curl -X PUT -H "Content-Type: application/json" \
  -d '{
    "name": "Prod VictorOps",
    "severities": {
      "all": ["alert", "warning"],
    },
  }' \
  "https://api.bluematador.com/zi/accounts/a976a6af-cf87-4dd1-942f-b13a30be9351/outbounds/victorops/686e5a82-3116-4257-8f6b-260ec3fef2cd"

Example Response


{
  "accountId": "a976a6af-cf87-4dd1-942f-b13a30be9351",
  "id": "686e5a82-3116-4257-8f6b-260ec3fef2cd",
  "created": "2019-03-22T15:07:08Z",
  "enabled": true,
  "data": {
    "name": "Prod VictorOps",
    "status": {
      "lastSuccess": "2019-03-23T09:01:01Z",
      "lastError": null,
      "recentErrors": []
    },
    "severities": {
      "all": [
        "alert",
        "warning"
      ]
    }
  },
  "credentials": "<secret>",
  "outboundType": "victorops"
}

This endpoint updates an existing VictorOps notification.

HTTP Request

PUT https://api.bluematador.com/zi/accounts/<account_id>/outbounds/victorops/<id>

Path Parameters

Name Type Description
account_id UUID the ID of the account that owns the notification
id UUID the ID of the notification to update

Request Body

Name Type Description
name string a name used to identify the notification
severities Object a map of project to an array of the event types to notify on (read more)
integrationId string (optional) the ID of the VictorOps integration to send notifications to
routingKey string (optional) the routing key VictorOps should use

Severities

{
  "all": ["alert"],
  "f651a7c4-9d49-4f23-8495-56d8a1d5e97c": ["alert", "warning", "anomaly"]
}

The severities map used when creating notifications allows you to control what types of events are sent to your notification methods. Blue Matador defines three levels of severity, Alert, Warning, and Anomaly. If you have set up projects, you can choose which severities you want on a project basis by providing the ID of your project mapped to the severities you'd like sent. For example, the following JSON:

Would result in all events from resources belonging to the project with the ID f651a7c4-9d49-4f23-8495-56d8a1d5e97c being sent to your notification method. All alerts would also be sent to the notification.

If you haven't set up projects, your object will only have the all key.

Disable a Notification

Disable Notification Example

curl -X PUT "https://api.bluematador.com/zi/accounts/a976a6af-cf87-4dd1-942f-b13a30be9351/outbounds/086e5a82-3116-4257-8f6b-260ec3fef2cd/disable"

The endpoint returns 200 OK when successful

This endpoint allows you to disable a notification. Disabled notifications will not be used by Blue Matador.

HTTP Request

PUT https://api.bluematador.com/zi/accounts/<account_id>/outbounds/<id>/disable

Path Parameters

Name Type Description
account_id UUID the ID of the account that owns the notification
id UUID the id of the notification to disable

Enable a Notification

Enable Notification Example

curl -X PUT "https://api.bluematador.com/zi/accounts/a976a6af-cf87-4dd1-942f-b13a30be9351/outbounds/086e5a82-3116-4257-8f6b-260ec3fef2cd/disable"

The endpoint returns 200 OK when successful

This endpoint allows you to re-enable a notification.

HTTP Request

PUT https://api.bluematador.com/zi/accounts/<account_id>/outbounds/<id>/enable

Path Parameters

Name Type Description
account_id UUID the ID of the account that owns the notification
id UUID the id of the notification to enable

Delete a Notification

Delete Notification Example

curl -X DELETE "https://api.bluematador.com/zi/accounts/a976a6af-cf87-4dd1-942f-b13a30be9351/outbounds/086e5a82-3116-4257-8f6b-260ec3fef2cd"

The endpoint returns 200 OK when successful

This endpoint allows you to delete a notification.

HTTP Request

DELETE https://api.bluematador.com/zi/accounts/<account_id>/outbounds/<id>

Path Parameters

Name Type Description
account_id UUID the ID of the account that owns the notification
id UUID the id of the notification to delete

Organizations

Organizations are a way of managing multiple Blue Matador accounts which each have their own integrations, notification methods, and events. When organizations is enabled, user permissions are managed for all accounts in the organization with a shared set of users.

Authentication

An example of authenticating with Blue Matador

curl "organization_api_endpoint_here"
  -H "Authorization: rha7sn5brxab4kh6a7hbe62q3jq1dpee7khpabcd"

Make sure to replace rha7sn5brxab4kh6a7hbe62q3jq1dpee7khpabcd with your organization key

All organization endpoints are authenticated using an Organization Key instead of an account API key. Simply pass the organization key in the Authorization header as shown:

List Accounts

List Accounts Example

curl https://api.bluematador.com/zi/organizations/40b59978-7e87-4129-aceb-cf9a98c36c62/accounts

Example Response: 200 OK

[
  {
    // The ID of this account
    "id": "a976a6af-cf87-4dd1-942f-b13a30be9351",
    "created": "2019-01-01T00:00:00Z",
    "data": {
      "stripeId": null,
      // The name given to this account
      "company": "Subsidiary 1",
      "disabled": false,
      "paid": false,
      "trialEnd": "2019-01-15T00:00:00Z",
      "assessment": null,
      "trialWalled": false,
      "projectSettings": {
        "enabled": false
      }
    },
    // The ID of the organization this account belongs to
    "organizationId": "40b59978-7e87-4129-aceb-cf9a98c36c62",
    // Extra data about the organization this account belongs to
    "organizationData": {
      "name": "Example Co.",
      "disabled": false,
      "stripeId": null,
      "paid": false,
      "trialEnd": "2019-01-15T00:00:00Z",
      "projectSettings": {
        "enabled": false
      }
    }
  },
  ...
]

Lists all accounts that belong to an organization

HTTP Request

GET https://api.bluematador.com/zi/organizations/<organization_id>/accounts

Path Parameters

Name Type Description
organization_id UUID the ID of your organization

Create Account

Create Account Example

curl -X POST -H "Content-Type: application/json" \
  -d '{"name": "Subsidiary 1"}' \
  "https://api.bluematador.com/zi/organizations/40b59978-7e87-4129-aceb-cf9a98c36c62/accounts"

Example Response: 200 OK

{
  // The newly created account object
  "account": {
    // The ID of this account
    "id": "a976a6af-cf87-4dd1-942f-b13a30be9351",
    "created": "2019-01-01T00:00:00Z",
    "data": {
      "stripeId": null,
      // The name given to this account
      "company": "Subsidiary 1",
      "disabled": false,
      "paid": false,
      "trialEnd": "2019-01-15T00:00:00Z",
      "assessment": null,
      "trialWalled": false,
      "projectSettings": {
        "enabled": false
      }
    },
    // The ID of the organization this account belongs to
    "organizationId": "40b59978-7e87-4129-aceb-cf9a98c36c62",
    // Extra data about the organization this account belongs to
    "organizationData": {
      "name": "Example Co.",
      "disabled": false,
      "stripeId": null,
      "paid": false,
      "trialEnd": "2019-01-15T00:00:00Z",
      "projectSettings": {
        "enabled": false
      }
    }
  },
  // The automatically created default API key for the account, so you can begin immediately calling the account-specific APIs
  "defaultApiKey": "D6bSkilgbSVm8djsMcMkrcD4QbCJ0n35"
}

Creates a new account for the organization.

HTTP Request

POST https://api.bluematador.com/zi/organizations/<organization_id>/accounts

Path Parameters

Name Type Description
organization_id UUID the ID of your organization

Request Body

Name Type Description
name string the display name for the account, will populate the company field in the account data

Delete Account

Delete Account Example

curl -X DELETE \
  "https://api.bluematador.com/zi/organizations/40b59978-7e87-4129-aceb-cf9a98c36c62/accounts/be9bba82-c394-431e-8d77-77cb242b138b"

Example Response: 200 OK

Deletes an account

HTTP Request

DELETE https://api.bluematador.com/zi/organizations/<organization_id>/accounts/<account_id>

Path Parameters

Name Type Description
organization_id UUID the ID of your organization
account_id UUID the ID of the account

List Users

List Users Example

curl https://api.bluematador.com/zi/organizations/40b59978-7e87-4129-aceb-cf9a98c36c62/users

Example Response: 200 OK

[
  {
    // The ID of the user
    "id": "dd0a2a8b-62f2-48b5-8039-75552ff0a477",
    "firstName": "John",
    "lastName": "Smith",
    "email": "johnsmith@example.com",
    "created": "2019-01-01T00:00:00Z",
    // The last time the user has logged in to Blue Matador
    "lastLogin": "2019-01-01T00:00:00Z",
    "deleted": null,
    "data": {
      "systemPermissions": [],
      "digestFrequency": "weekly",
      "lastDigest": null
    },
    "needsTour": true
  }
]

Lists all users that belong to an organization. The response from this endpoint includes only basic user information and does not show the user's permissions with any accounts or organization. To retrieve those details, use the Get User endpoint.

HTTP Request

GET https://api.bluematador.com/zi/organizations/<organization_id>/users

Path Parameters

Name Type Description
organization_id UUID the ID of your organization

Invite Users

Invite Users Example

curl -X POST -H "Content-Type: application/json" \
  -d '[{
    "email": "janedoe@example.com",
    "data": {
      "permissions": ["user"],
      "autoProvision": true,
      "autoProvisionPermissions": ["user"]
    }
  }]' \
  "https://api.bluematador.com/zi/organizations/40b59978-7e87-4129-aceb-cf9a98c36c62/users"

Example Response: 200 OK

(no body)

Example Response: 409 Conflict

{
  "error": "a user with this email already exists"
}

Sends an invitation to a user to join your organization. The user must then check their email and accept the invitation through the link in their email, which leads them through the process of setting up their name and password. Invitations cannot be accepted programmatically on behalf of a user.

HTTP Request

POST https://api.bluematador.com/zi/organizations/<organization_id>/users

Path Parameters

Name Type Description
organization_id UUID the ID of your organization

Request Body

Name Type Description
email string the user's email address
data object the user organization settings as described below

User Organization Settings

Name Type Description
permissions list a list of user organization permissions: user and/or admin
autoProvision boolean if set to true, the user will be provisioned onto all existing and future accounts in the organization
autoProvisionPermissions list a list of user account permissions: user and/or admin that the user is provisioned with when autoProvision is true

Get User

Get User Example

curl https://api.bluematador.com/zi/organizations/40b59978-7e87-4129-aceb-cf9a98c36c62/users/dd0a2a8b-62f2-48b5-8039-75552ff0a477

Example Response: 200 OK

[
  {
    // Basic user information
    "user": {
      // The ID of the user
      "id": "dd0a2a8b-62f2-48b5-8039-75552ff0a477",
      "firstName": "John",
      "lastName": "Smith",
      "email": "johnsmith@example.com",
      "created": "2019-01-01T00:00:00Z",
      // The last time the user has logged in to Blue Matador
      "lastLogin": "2019-01-01T00:00:00Z",
      "deleted": null,
      "data": {
        "systemPermissions": [],
        "digestFrequency": "weekly",
        "lastDigest": null
      },
      "needsTour": true
    },
    // An object describing this user's permissions and settings in the organization
    "userOrganization": {
      "userId": "dd0a2a8b-62f2-48b5-8039-75552ff0a477",
      "organizationId": "40b59978-7e87-4129-aceb-cf9a98c36c62",
      "data": {
        // Permissions the user has with the organization
        "permissions": [
          "user",
          "admin"
        ],
        // If true, the user is automatically provisioned onto new organization accounts
        "autoProvision": true,
        // If autoProvision is set, which permissions the user will have on new accounts
        "autoProvisionPermissions": [
          "user"
        ]
      },
      "created": "2019-01-01T00:00:00Z"
    },
    // An array of objects describing the user's permissions on each account they have permissions on
    "userAccounts": [
      {
        "userId": "dd0a2a8b-62f2-48b5-8039-75552ff0a477",
        "accountId": "a976a6af-cf87-4dd1-942f-b13a30be9351",
        "data": {
          // If true, this relationship was created as a result of auto provisioning
          "autoProvisioned": false,
          // The current permissions the user has on this account
          "permissions": [
            "user",
            "admin"
          ]
        },
        // The last time the user logged in to this account
        "lastLogin": null,
        "created": "2019-01-01T00:00:00Z"
      }
    ]
  }
]

Example Response: 404 Not Found

(no body)

Gets a user that belongs to an organization, that user's organization configuration, and their account configurations.

HTTP Request

GET https://api.bluematador.com/zi/organizations/<organization_id>/users/<user_id>

Path Parameters

Name Type Description
organization_id UUID the ID of your organization
user_id UUID the ID of the user

Update User

Update User Example

curl -X PUT -H "Content-Type: application/json" \
  -d '{
    "permissions": ["user"],
    "autoProvision": true,
    "autoProvisionPermissions": ["user"]
  }' \
  "https://api.bluematador.com/zi/organizations/40b59978-7e87-4129-aceb-cf9a98c36c62/users/dd0a2a8b-62f2-48b5-8039-75552ff0a477"

Example Response: 200 OK

(no body)

Updates a user's organization permissions.

HTTP Request

PUT https://api.bluematador.com/zi/organizations/<organization_id>/users/<user_id>

Path Parameters

Name Type Description
organization_id UUID the ID of your organization
user_id UUID the ID of the user

Request Body

Name Type Description
permissions list a list of user organization permissions: user and/or admin
autoProvision boolean if set to true, the user will be provisioned onto all existing and future accounts in the organization
autoProvisionPermissions list a list of user account permissions: user and/or admin that the user is provisioned with when autoProvision is true

Delete User

Delete User Example

curl -X DELETE "https://api.bluematador.com/zi/organizations/40b59978-7e87-4129-aceb-cf9a98c36c62/users/dd0a2a8b-62f2-48b5-8039-75552ff0a477"

Example Response: 200 OK

(no body)

Deletes a user from your organization. The user will also be deleted from all accounts in your organization that they had access to.

HTTP Request

DELETE https://api.bluematador.com/zi/organizations/<organization_id>/users/<user_id>

Path Parameters

Name Type Description
organization_id UUID the ID of your organization
user_id UUID the ID of the user

Set User Account

Set User Account Example

curl -X PUT -H "Content-Type: application/json" \
  -d '{
    "permissions": ["user", "admin"]
  }' \
  "https://api.bluematador.com/zi/organizations/40b59978-7e87-4129-aceb-cf9a98c36c62/users/dd0a2a8b-62f2-48b5-8039-75552ff0a477/accounts/a976a6af-cf87-4dd1-942f-b13a30be9351"

Example Response: 200 OK

(no body)

Sets a user's permissions with a specific account in your organization. To remove a user's access to an account in your organization, use the Delete User Account API.

HTTP Request

PUT https://api.bluematador.com/zi/organizations/<organization_id>/users/<user_id>/accounts/<account_id>

Path Parameters

Name Type Description
organization_id UUID the ID of your organization
user_id UUID the ID of the user
account_id UUID the ID of the account

Request Body

Name Type Description
permissions list a list of user account permissions: user and/or admin

Delete User Account

Delete User Account Example

curl -X DELETE "https://api.bluematador.com/zi/organizations/40b59978-7e87-4129-aceb-cf9a98c36c62/users/dd0a2a8b-62f2-48b5-8039-75552ff0a477/accounts/a976a6af-cf87-4dd1-942f-b13a30be9351"

Example Response: 200 OK

(no body)

Deletes a user's permissions with an account, completely removing all access to the account.

HTTP Request

DELETE https://api.bluematador.com/zi/organizations/<organization_id>/users/<user_id>/accounts/<account_id>

Path Parameters

Name Type Description
organization_id UUID the ID of your organization
user_id UUID the ID of the user
account_id UUID the ID of the account