Skip to main content

Alert Enrichment V2.1

Use the Alert Enrichment API to define alert tags that help users understand incidents more quickly and enrich BigPanda functionality, including correlation patterns and maintenance plans.

Read more about how alerts are contextualized and the potential correlation and automation possibilities of alert enrichment in the Alert Intelligence documentation.

Mapping enrichment UI

Mapping Enrichments can be managed right in the BigPanda UI. Read more in the Enrichment Maps documentation.

Update existing processes

If you have previously configured API management of Alert Enrichment using the V1 or V2.0 API, you can update those processes.

No additional steps are necessary to configure a new API call using the V2.1 API.

Tag limitations

To maintain quality of service, BigPanda limits the number of alert tags and enrichment items available. Each organization can have:

  • 1000 alert tags

  • 500 enrichment items per alert tag

  • 20,000 alert enrichment items total

  • 200 mapping enrichment results tags

If more alert tags or enrichment items are needed, we recommend exploring normalization options to help streamline your alert data and improve incident quality.

Alert Enrichment 2.1

Authentication

All BigPanda APIs require Bearer Token Authorization in the call headers.

This API uses the User API Key type of Authorization token.

BigPanda recommends adding Authentication headers only in the secure tool you use to make API calls.

Example 1. Create alert tag
curl --request POST \
     --url https://api.bigpanda.io/resources/v2.1/enrichments-config/tags/ \
     --header 'Authorization: Bearer <User API Key>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
     "name": "tag_name",
     "active": true,
     "description": "description",
     "enrichments": [
      {
        "type": "extraction",
        "active": true,
        "when": {
       		 "IN": [
       			 "source_system",
       			 [
       			 {
       			 "type": "regex",
       			 "value": "*"
      		  }
    		    ]
    	    ]
     },
        "config": {
            "source": "host",
            "destination": "tag_name",
            "regex": "(.*)"
        },
        "note": "note"
    },
    {
        "type": "composition",
        "active": true,
        "when": {
       		 "IN": [
       			 "source_system",
       			 [
       			 {
       			 "type": "regex",
       			 "value": "*"
      		  }
    		    ]
    	    ]
        },
        "config": {
          "source": "nagios",
          "destination": "tag_name",
          "value": "val-${host6666}\"
        },
        "note": "wiki.com"
    }
  ]
}
'
curl --request POST \
     --url https://eu-api.bigpanda.io/resources/v2.1/enrichments-config/tags/ \
     --header 'Authorization: Bearer <User API Key>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
     "name": "tag_name",
     "active": true,
     "description": "description",
     "enrichments": [
      {
        "type": "extraction",
        "active": true,
        "when": {
       		 "IN": [
       			 "source_system",
       			 [
       			 {
       			 "type": "regex",
       			 "value": "*"
      		  }
    		    ]
    	    ]
     },
        "config": {
            "source": "host",
            "destination": "tag_name",
            "regex": "(.*)"
        },
        "note": "note"
    },
    {
        "type": "composition",
        "active": true,
        "when": {
       		 "IN": [
       			 "source_system",
       			 [
       			 {
       			 "type": "regex",
       			 "value": "*"
      		  }
    		    ]
    	    ]
        },
        "config": {
          "source": "nagios",
          "destination": "tag_name",
          "value": "val-${host6666}\"
        },
        "note": "wiki.com"
    }
  ]
}
'


Example 2. Retrieve all alert tags
curl --request GET \
     --url https://api.bigpanda.io/resources/v2.1/enrichments-config/tags \
     --header 'Authorization: Bearer <User API Key>' \
     --header 'accept: application/json'
curl --request GET \
     --url https://eu-api.bigpanda.io/resources/v2.1/enrichments-config/tags \
     --header 'Authorization: Bearer <User API Key>' \
     --header 'accept: application/json'


Example 3. Retrieve an alert tag
curl --request GET \
     --url https://api.bigpanda.io/resources/v2.1/enrichments-config/tags/{TAG_NAME}
     --header 'Authorization: Bearer <User API Key>' \
     --header 'accept: application/json'
curl --request GET \
     --url https://eu-api.bigpanda.io/resources/v2.1/enrichments-config/tags/{TAG_NAME}
     --header 'Authorization: Bearer <User API Key>' \
     --header 'accept: application/json'


Example 4. Update tag data
curl --request PATCH \
     --url https://api.bigpanda.io/resources/v2.1/enrichments-config/tags/{tag_name} \
     --header 'Authorization: Bearer <User API Key>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
     "active": true,
     "description": "the text of the description"
}
'
curl --request PATCH \
     --url https://eu-api.bigpanda.io/resources/v2.1/enrichments-config/tags/{tag_name} \
     --header 'Authorization: Bearer <User API Key>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
     "active": true,
     "description": "the text of the description"
}
'


Example 5. Delete tag
curl --request DELETE \
     --url https://api.bigpanda.io/resources/v2.1/enrichments-config/tags/{TAG_NAME}
     --header 'Authorization: Bearer <User API Key>' \
     --header 'accept: application/json'
curl --request DELETE \
     --url https://eu-api.bigpanda.io/resources/v2.1/enrichments-config/tags/{TAG_NAME}
     --header 'Authorization: Bearer <User API Key>' \
     --header 'accept: application/json'


Example 6. Update alert tag order
curl --request PUT \
     --url https://api.bigpanda.io/resources/v2.1/enrichments-config \
     --header 'Authorization: Bearer <User API Key>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
     "alert_tags_order": [
          "host",
          "application",
          "check"
     ]
}
'
curl --request PUT \
     --url https://eu-api.bigpanda.io/resources/v2.1/enrichments-config \
     --header 'Authorization: Bearer <User API Key>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
     "alert_tags_order": [
          "host",
          "application",
          "check"
     ]
}
'


Example 7. Update enrichment order for an alert tag
curl --request PUT \
     --url https://api.bigpanda.io/resources/v2.1/enrichments-config/tags/{tag_name}/order \
     --header 'Authorization: Bearer <User API Key>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
     "enrichment_order": [
          "b6a7e384-ad82-4db4-b83b-9c87fabaf555",
          "b6a7e384-ad82-4db4-b83b-9c87fa8a1555"
     ]
}'
curl --request PUT \
     --url https://eu-api.bigpanda.io/resources/v2.1/enrichments-config/tags/{tag_name}/order \
     --header 'Authorization: Bearer <User API Key>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
     "enrichment_order": [
          "b6a7e384-ad82-4db4-b83b-9c87fabaf555",
          "b6a7e384-ad82-4db4-b83b-9c87fa8a1555"
     ]
}'


Example 8. Create enrichment item
curl --request POST \
     --url https://api.bigpanda.io/resources/v2.1/enrichments-config/tags/{tag_name}/enrichments \
     --header 'Authorization: Bearer <User API Key>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
     "enrichments": [
      {
        "type": "extraction",
        "active": true,
        "when": {
       		 "IN": [
       			 "source_system",
       			 [
       			 {
       			 "type": "regex",
       			 "value": "*"
      		  }
    		    ]
    	    ]
        },
        "config": {
          "source": "host",
          "destination": "tag_name",
          "regex": "(.*)"
          },
        "note": "note"
    },
    {
        "type": "composition",
        "active": true,
        "when":
        {
        "IN": [
        		"host",
            [
            "prod-api-1",
            "prod-api-2"
            ]
            ]
            },
        "config": {
          "source": "nagios",
          "destination": "tag_name",
          "value": "val-${host6666}\"
          },
        "note": "wiki.com"
    }
  ]
}
'
curl --request POST \
     --url https://eu-api.bigpanda.io/resources/v2.1/enrichments-config/tags/{tag_name}/enrichments \
     --header 'Authorization: Bearer <User API Key>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
     "enrichments": [
      {
        "type": "extraction",
        "active": true,
        "when": {
       		 "IN": [
       			 "source_system",
       			 [
       			 {
       			 "type": "regex",
       			 "value": "*"
      		  }
    		    ]
    	    ]
        },
        "config": {
          "source": "host",
          "destination": "tag_name",
          "regex": "(.*)"
          },
        "note": "note"
    },
    {
        "type": "composition",
        "active": true,
        "when":
        {
        "IN": [
        		"host",
            [
            "prod-api-1",
            "prod-api-2"
            ]
            ]
            },
        "config": {
          "source": "nagios",
          "destination": "tag_name",
          "value": "val-${host6666}\"
          },
        "note": "wiki.com"
    }
  ]
}
'


Example 9. Update enrichment item
curl --request PATCH \
     --url https://api.bigpanda.io/resources/v2.1/enrichments-config/tags/{tag_name}/enrichments \
     --header 'Authorization: Bearer <User API Key>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
     "enrichments": [
      {
        "type": "extraction",
        "active": true,
        "id" : "93a1649e-144c-4d7a-a2ce-bf6839647555",
        "when": {
       		 "IN": [
       			 "source_system",
       			 [
       			 {
       			 "type": "regex",
       			 "value": "*"
      		  }
    		    ]
    	    ]
        },
        "config": {
          "source": "host",
          "destination": "tag_name",
          "regex": "(.*)"
          },
        "note": "note"
    },
    {
        "type": "composition",
        "active": true,
        "id" : "5551649e-144c-4d7a-a2ce-bf6839647555",
        "when":
        {
        "IN": [
        		"host",
            [
            "prod-api-1",
            "prod-api-2"
            ]
            ]
            },
        "config": {
          "source": "nagios",
          "destination": "tag_name",
          "value": "val-${host6666}\"
          },
        "note": "wiki.com"
    }
  ]
}
'
curl --request PATCH \
     --url https://eu-api.bigpanda.io/resources/v2.1/enrichments-config/tags/{tag_name}/enrichments \
     --header 'Authorization: Bearer <User API Key>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
     "enrichments": [
      {
        "type": "extraction",
        "active": true,
        "id" : "93a1649e-144c-4d7a-a2ce-bf6839647555",
        "when": {
       		 "IN": [
       			 "source_system",
       			 [
       			 {
       			 "type": "regex",
       			 "value": "*"
      		  }
    		    ]
    	    ]
        },
        "config": {
          "source": "host",
          "destination": "tag_name",
          "regex": "(.*)"
          },
        "note": "note"
    },
    {
        "type": "composition",
        "active": true,
        "id" : "5551649e-144c-4d7a-a2ce-bf6839647555",
        "when":
        {
        "IN": [
        		"host",
            [
            "prod-api-1",
            "prod-api-2"
            ]
            ]
            },
        "config": {
          "source": "nagios",
          "destination": "tag_name",
          "value": "val-${host6666}\"
          },
        "note": "wiki.com"
    }
  ]
}
'


Example 10. Delete enrichment item
curl --request DELETE \
     --url https://api.bigpanda.io/resources/v2.1/enrichments-config/tags/{tag_name}/enrichments \
     --header 'Authorization: Bearer <User API Key>' \
     --header 'accept: application/json'
     --body'
     {
   "enrichments_ids": ["7c35c343-1029-4ebb-b555-99632738e555", "530c12ef-e358-555a-86c1-c3f6df88555"]
}'
curl --request DELETE \
     --url https://eu-api.bigpanda.io/resources/v2.1/enrichments-config/tags/{tag_name}/enrichments \
     --header 'Authorization: Bearer <User API Key>' \
     --header 'accept: application/json'
     --body'
     {
   "enrichments_ids": ["7c35c343-1029-4ebb-b5b1-99632738e555", "530c12ef-e358-4f1a-86c1-c3f6df88555"]
}'


Example 11. Create mapping enrichment schema
curl --request POST \
     --url https://api.bigpanda.io/resources/v2.1/mapping-enrichment \
     --header 'Authorization: Bearer <User API Key>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
    "config": {
        "fields": [
            {
                "title": "app",
                "type": "result_tag",
                "tag_name": "app",
                "override_existing": true
            },
            {
                "title": "workgroup",
                "type": "query_tag",
                "tag_name": "workgroup",
                "override_existing": false
            }
        ],
        "name": "cmdb_application",
        "case_insensitive": true,
        "note": "Testing",
        "id_generation_function": "use_md5"
        },
    "type": "mapping",
    "active": true,
    "when": {
       		 "IN": [
       			 "source_system",
       			 [
       			 {
       			 "type": "regex",
       			 "value": "*"
      		  }
    		    ]
    	    ]
        }
}
'
curl --request POST \
     --url https://eu-api.bigpanda.io/resources/v2.1/mapping-enrichment \
     --header 'Authorization: Bearer <User API Key>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
    "config": {
        "fields": [
            {
                "title": "app",
                "type": "result_tag",
                "tag_name": "app",
                "override_existing": true
            },
            {
                "title": "workgroup",
                "type": "query_tag",
                "tag_name": "workgroup",
                "override_existing": false
            }
        ],
        "name": "cmdb_application",
        "case_insensitive": true,
        "note": "Testing",
        "id_generation_function": "use_md5"
    },
    "type": "mapping",
    "active": true,
    "when": {
       		 "IN": [
       			 "source_system",
       			 [
       			 {
       			 "type": "regex",
       			 "value": "*"
      		  }
    		    ]
    	    ]
        }
}
'


Example 12. Retrieve mapping enrichment schema
curl --request GET \
     --url https://api.bigpanda.io/resources/v2.1/mapping-enrichment/{mapping_enrichment_id} \
     --header 'Authorization: Bearer <User API key>' \
     --header 'accept: application/json'
curl --request GET \
     --url https://eu-api.bigpanda.io/resources/v2.1/mapping-enrichment/{mapping_enrichment_id} \
     --header 'Authorization: Bearer <User API Key>' \
     --header 'accept: application/json'


Example 13. Retrieve all mapping enrichment schemas
curl --request GET \
     --url https://api.bigpanda.io/resources/v2.1/mapping-enrichment \
     --header 'Authorization: Bearer <User API Key>' \
     --header 'accept: application/json'
curl --request GET \
     --url https://eu-api.bigpanda.io/resources/v2.1/mapping-enrichment \
     --header 'Authorization: Bearer <User API Key>' \
     --header 'accept: application/json'


Example 14. Update mapping enrichment schema
curl --request PATCH \
     --url https://api.bigpanda.io/resources/v2.1/mapping-enrichment/{mapping_enrichment_id} \
     --header 'Authorization: Bearer <User API Key>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
   "active": true,
   "when": {},
   "note": ""
}`
curl --request PATCH \
     --url https://eu-api.bigpanda.io/resources/v2.1/mapping-enrichment/{mapping_enrichment_id} \
     --header 'Authorization: Bearer <User API Key>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
   "active": true,
   "when": {},
   "note": ""
}`


Example 15. Delete mapping enrichment schema
curl --request DELETE \
     --url https://api.bigpanda.io/resources/v2.1/mapping-enrichment/{mapping_enrichment_id} \
     --header 'Authorization: Bearer <User API Key>' \
     --header 'accept: application/json'
curl --request DELETE \
     --url https://eu-api.bigpanda.io/resources/v2.1/mapping-enrichment/{mapping_enrichment_id} \
     --header 'Authorization: Bearer <User API Key>' \
     --header 'accept: application/json'


Example 16. Create enrichment map table using csv
curl --request POST \
     --url https://api.bigpanda.io/resources/v2.1/mapping-enrichment/{mapping_enrichment_id}/map \
     --header 'Authorization: Bearer <User API Key>' \
     --header 'Content-Type: text/csv; charset=utf8' \
     --data-binary @synthetic_monitor_playbook.csv
curl --request POST \
     --url https://eu-api.bigpanda.io/resources/v2.1/mapping-enrichment/{mapping_enrichment_id}/map \
     --header 'Authorization: Bearer <User API Key>' \
     --header 'Content-Type: text/csv; charset=utf8' \
     --data-binary @synthetic_monitor_playbook.csv


Example 17. Create enrichment map row
curl --request PATCH \
     --url https://api.bigpanda.io/resources/v2.1/mapping-enrichment/{mapping_enrichment_id}/map \
     --header 'Authorization: Bearer <User API Key>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
     "op": "create",
     "value": {
	     	"application": "centdb"
     }
}
'
curl --request PATCH \
     --url https://eu-api.bigpanda.io/resources/v2.1/mapping-enrichment/{mapping_enrichment_id}/map \
     --header 'Authorization: Bearer <User API Key>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
     "op": "create",
     "value": {
	     	"application": "centdb"
     }
}
'


Example 18. Update enrichment map row
curl --request PATCH \
     --url https://api.bigpanda.io/resources/v2.1/mapping-enrichment/{mapping_enrichment_id}/map \
     --header 'Authorization: Bearer <User API Key>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
     "op": "update",
     "value": {
	     	"application": "centodds"
     }
}
'
curl --request PATCH \
     --url https://eu-api.bigpanda.io/resources/v2.1/mapping-enrichment/{mapping_enrichment_id}/map \
     --header 'Authorization: Bearer <User API Key>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
     "op": "update",
     "value": {
	     	"application": "centodds"
     }
}
'


Example 19. Delete enrichment map row
curl --request PATCH \
     --url https://api.bigpanda.io/resources/v2.1/mapping-enrichment/{mapping_enrichment_id}/map \
     --header 'Authorization: Bearer <User API Key>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
     "op": "delete",
     "value": {
	     	"application": "centdb"
     }
}
'
curl --request PATCH \
     --url https://eu-api.bigpanda.io/resources/v2.1/mapping-enrichment/{mapping_enrichment_id}/map \
     --header 'Authorization: Bearer <User API Key>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
     "op": "delete",
     "value": {
	     	"application": "centdb"
     }
}
'


Example 20. Retrieve enrichment map table
curl --request GET \
     --url 'https://api.bigpanda.io/resources/v2.1/mapping-enrichment/{mapping_enrichment_id}/map?page=1&per_page=20' \
     --header 'Authorization: Bearer <User API Key>' \
     --header 'accept: application/json'
curl --request GET \
     --url 'https://eu-api.bigpanda.io/resources/v2.1/mapping-enrichment/{mapping_enrichment_id}/map?page=1&per_page=20' \
     --header 'Authorization: Bearer <User API Key>' \
     --header 'accept: application/json'


Example 21. Retrieve enrichment map upload job status
curl --request GET \
     --url https://api.bigpanda.io/resources/v2.1/alert-enrichments-jobs/{job_id} \
     --header 'Authorization: Bearer <User API Key>' \
     --header 'accept: application/json'
curl --request GET \
     --url https://eu-api.bigpanda.io/resources/v2.1/alert-enrichments-jobs/{job_id} \
     --header 'Authorization: Bearer <User API Key>' \
     --header 'accept: application/json'


Migrating existing workflows to Alert Enrichment 2.1

The Alert Enrichments V2.1 API allows you to programmatically create custom tags and enrichment items that add contextual information to alerts. It supports the mapping enrichment technique, which creates alert custom tags by looking up values in a data mapping table.

Use the Alert Enrichment V2.1 API to define alert tags and enrichment maps to add vital context to ongoing alerts.

Read more about how alerts are contextualized and the potential correlation and automation possibilities of alert enrichment in the Alert Intelligence documentation.

Mandatory migration

All customers will need to move to the V2.1 API. The Enrichment V1 and V2.0 API will be deprecated in the future.

API Improvements

  • Improved composition and extraction enrichment item functionality and features

  • Alert tags can now be duplicated, marked inactive, and have a description

  • Mapping tables now automatically enrich existing alert tags

  • Mapping enrichment items can be reordered on a per-tag basis

  • Enabling future audit-log functionality

  • Bulk operations now available for enrichment items

In order to leverage these improved capabilities, your organization will need to migrate your analytics into the new tool and data set.

Preparing for migration

Migrating to the Alert Enrichment V2.1 API is a simple, seamless process. **During the initial migration phase**, you will have access to the V2.0 API as well as the new V2.1.

Before beginning migration, review all manual and automated processes that leverage the existing Alert Enrichment APIs. This includes any mapping enrichment APIs leveraging the V1.0 and V2.0 Enrichment API.

Simple migration

If you are only using the Alert Enrichment V1 API to manage mapping enrichments, the migration process will require only a few steps:

1. Change the endpoint name attached to Mapping Enrichment calls to the new `/v2.1/mapping-enrichment/` endpoint

2. Validate payload format matches the new requirements

3. Test an enrichment map to ensure it is uploading correctly

4. (Optional) If choosing to implement API management of composition and extraction tags, use the new V2.1 endpoints and JSON payload formats.

Complex migration

If you are using the Enrichment V2.0 API to manage composition and extraction enrichments, the migration process will require a few additional updates:

1. Change the endpoint name attached to all enrichment calls to the new endpoints:

/v2.0/alert-enrichments (mapping type) --> /v2.1/mapping-enrichment

/v2.0/alert-enrichments (non-mapping type) --> /v2.1/enrichments-config/tags/<TAG_NAME>/enrichments

2. Validate payload format matches the new requirements

The object payload for Tag Rules or Enrichment Items is changing from a single object to an array of objects. Composition and extraction enrichments will be nested within the enrichment array.

curl Enrichment Items Array Format
{
    "name": "tag_name", 
    "active": true,
    "description": "", 
    "enrichments": [    
     {
       "type": "extraction",
       "active": true,
       "when": {},
       "config": {
           "source": "host",
           "destination": "tag_name",
           "regex": "(.*)",
           "template": null 
       },
       "note": null
   },
   {
       "type": "composition", 
       "active": true,
       "when": {},
       "config": {
           "destination": "tag_name",
           "value": "val-${host6666}"
       },
       "note": "wiki.com"
   }
 ]
}

3. Test each enrichment and call type to ensure it is functioning correctlyThe [Alert Enrichments V2.1 API](https://docs.bigpanda.io/reference/alert-enrichment-v2-1-api) allows you to programmatically create custom tags and enrichment items that add contextual information to alerts. It supports the mapping enrichment technique, which creates alert custom tags by looking up values in a data mapping table.

In this section: