Get Started with the Alert Enrichment API

The Alert Enrichment API gives you programmatic control over how BigPanda adds context to your alerts. It covers three closely related jobs: managing alert tags, defining enrichment rules that calculate tag values, and uploading mapping tables that look up values from external data.

Because these jobs overlap, the API includes many endpoints with similar names across several versions. This guide orients you before you start. It explains how the underlying objects relate to one another, which group of endpoints handles each task, and the order to call them in when you set up enrichment for the first time.

If you are new to enrichment concepts, start with the Manage Alert Enrichment and Enrichment Maps documentation, then return here to work through the API.

Key Features

One model for every enrichment task - Manage tags, rule-based enrichment, and mapping enrichment through a single, consistent set of resources.

Rule-based and lookup-based enrichment - Calculate tag values with composition and extraction rules, or match incoming alerts against an uploaded table.

Asynchronous upload tracking - Track large mapping table uploads with Job objects so you can confirm success before sending live traffic.

Full lifecycle control - Create, retrieve, update, reorder, and delete every enrichment object as your infrastructure changes.

Before You Start

Every call to the Alert Enrichment API uses Bearer token authorization with a User API Key. Include the key in the request header, prefixed by the word Bearer:

Authorization: Bearer <your_user_api_key>

Most write endpoints are rate limited to 5 requests per second. Plan bulk operations accordingly.

Understand the Objects

Before choosing an endpoint, it helps to understand what you are creating and how the pieces connect.

BigPanda ingests raw events from your monitoring tools and normalizes them into key-value pairs called tags. Tags drive normalization, deduplication, correlation into incidents, incident enrichment, and automation. The Alert Enrichment API works with the following objects:

Alert tag - A named field on an alert, for example owner, priority, or data_center. A tag is a container. On its own it holds no values. It applies a value to an alert only when an enrichment item matches that alert.

Enrichment item (rule) - A rule that belongs to a single tag and defines both a value and the condition under which that value applies. There are two rule types:

Composition - Builds a value by combining other tag values in a template, for example https://mywiki.com/${host}/${check}.

Extraction - Pulls a value out of another tag using a regular expression.

Mapping enrichment schema - Defines the structure of a lookup table: which columns are lookup (query) columns used to match incoming alerts, which columns are result columns used to enrich them, and the override behavior for each result.

Mapping table (map) - The actual data, uploaded as comma-separated values (CSV), that populates the result values defined by a schema. Each schema has exactly one map.

Job - A tracking object created when you upload or update a mapping table. Because these uploads run asynchronously, you poll the Job to confirm the upload finished successfully.

How the objects relate

An alert tag holds one or more enrichment items. A mapping schema also enriches tags: each result column in the schema adds an enrichment item to the tag whose name matches that column. If no tag with that name exists yet, BigPanda creates one automatically.

Lookup columns are not added to alerts
Lookup (query) values must already exist in the raw event or an earlier tag. BigPanda uses them only to find a matching row. It adds only the result values to the alert.

Run order matters

BigPanda runs tags in the order they appear, and runs the items within each tag in order. When one rule depends on the value of another tag, the source tag must run first. For example, an extraction rule that reads from a host tag must run after host is set. Use the order endpoints described below to control this sequence.

Choose the Right Endpoints

The API groups enrichment endpoints into families. First-time users are often unsure which family to use because several cover overlapping tasks across different versions. Use the table below to pick the right group for your task.

Your task	Endpoint family	Base path
Create and manage tags, and manage the rules inside each tag together	Alert tags (tag-scoped)	`/resources/v2.1/enrichments-config/tags`
Manage individual rule-based enrichment items by their own ID	Alert enrichment items (item-scoped)	`/resources/v2.1/alert-enrichments`
Control the order that tags and rules run in	Enrichment order	`/resources/v2.1/enrichments-config` and `.../order`
Upload and maintain a lookup table (schema plus CSV)	Mapping enrichment	`/resources/v2.1/mapping-enrichment`
Use advanced mapping capabilities	Advanced mapping enrichment	`/resources/alert-enricher/schemas`

Tag-scoped versus item-scoped rule endpoints

Two families both manage rule-based enrichment, which is the most common source of confusion:

The tag-scoped family at /resources/v2.1/enrichments-config/tags treats the tag as the primary object. You create a tag and its rules together, and you address rules through their parent tag, for example POST /resources/v2.1/enrichments-config/tags/{alerttag_name}/enrichments.

The item-scoped family at /resources/v2.0/alert-enrichments treats each enrichment item as an independent object addressed by its own enrichment_id, for example PATCH /resources/v2.0/alert-enrichments/{enrichment_id}.

For new integrations, use the tag-scoped v2.1 endpoints. They map directly to how tags and rules appear in the BigPanda UI and keep a tag and its rules together in one place. Use the item-scoped v2.0 endpoints when you need to update or delete a single existing item by its ID.

Match versions within a workflow
Pick one family for a given task and stay in it. Mixing tag-scoped and item-scoped calls, or v2.0 and v2.1 mapping calls, on the same objects can produce confusing results.

Mapping enrichment versions

Mapping enrichment also appears in more than one place:

Mapping enrichment at /resources/v2.1/mapping-enrichment is the current model. You create a schema, then upload a CSV map to it, and track the upload with a Job.

Advanced mapping enrichment at /resources/alert-enricher/schemas unlocks additional capabilities but requires a manual migration. Its schemas conflict with previous enrichment schemas, so coordinate with your account team before you use it.

Advanced mapping enrichment requires migration
The advanced capabilities of the Alert Enricher conflict with previous alert enrichment schemas. Reach out to your account team and confirm your organization is ready before you call the /resources/alert-enricher/schemas endpoints.

Set Up Enrichment for the First Time

The following workflows walk through the two most common starting points: creating a rule-based tag, and uploading a mapping enrichment.

Create a rule-based enrichment tag

Use this workflow when you want BigPanda to calculate a tag value from data already on the alert, using a composition or extraction rule.

Create the tag with its rules. Send a POST request to /resources/v2.1/enrichments-config/tags. Give the tag a name that meets the tag naming requirements, and include the enrichment items in the request. Each item requires a config object, and composition and extraction items require different fields.

Confirm the tag. Send a GET request to /resources/v2.1/enrichments-config/tags/{alerttag_name} to verify the tag and its rules were created as expected.

Set the run order if the tag depends on another tag. If a rule reads from another tag, send a PUT request to /resources/v2.1/enrichments-config to place the source tag before this one, or to /resources/v2.1/enrichments-config/tags/{alerttag_name}/order to order the rules within the tag.

Test with sample alerts. Send test alerts through the Alerts API and confirm the tag is applied as expected. Resolve the test alerts when you finish.

Changes apply to new alerts only
BigPanda applies a new or updated enrichment tag to alerts that arrive after you save it. Existing alerts keep the values they already have.

Upload a mapping enrichment

Use this workflow when you want to enrich alerts by matching them against a table of values, for example matching an application name to its owner and runbook URL.

Define the schema. Send a POST request to /resources/v2.1/mapping-enrichment. For each column in your table, specify the name and whether it is a lookup (query) column or a result column, along with the override behavior. Copy the schema id from the response.

Upload the map data. Send a POST request to /resources/v2.1/mapping-enrichment/{mapschema_id}/map, using the id from the previous step. Send the data as CSV in the request body or as a CSV file. The columns must match the schema exactly. This starts an asynchronous job and returns a Job reference.

Confirm the upload finished. Send a GET request to /resources/v2.1/alert-enrichments-jobs/{job_id} and check the status until the upload completes successfully.

Test with sample alerts. Send matching test alerts through the Alerts API and confirm the result values are applied. Resolve the test alerts when you finish.

Include the analytics flag columns
To visualize enrichment rates accurately in Unified Analytics (UA), include the two enrichment flag columns in your CSV, as described in the Enrichment Maps documentation.

Maintain Enrichment Over Time

As your team and infrastructure change, update enrichment through the same families you created it with.

Update a rule-based tag - Send a PATCH request to /resources/v2.1/enrichments-config/tags/{alerttag_name} to change the tag, or to .../enrichments to change its rules. To edit a single item by its ID, send a PATCH request to /resources/v2.0/alert-enrichments/{enrichment_id}.

Replace a full mapping table - Repeat the upload step with a new CSV that uses the same column headers.

Change specific rows - Send a PATCH request to /resources/v2.1/mapping-enrichment/{mapschema_id}/map with the rows to add, update, or delete. Track the change with the returned Job.

Change a mapping structure - You cannot change a schema's columns in place. Deactivate the existing schema, then create a new one, starting again from the schema definition step.

Reorder tags or rules - Use the enrichment order endpoints. Reordering matters most when tags depend on one another.

Reordering and mapping reuploads
When you reupload a mapping table, its enrichment items revert to the created-first order. If you reordered mapping items in the UI, reapply that order, or arrange the columns in the CSV to match the run order you want.

Endpoint Reference by Task

The table below lists the primary endpoints for each enrichment task. For full request and response details, including required fields, see the API reference for each endpoint.

Task	Method and path
List all alert tags	`GET /resources/v2.1/enrichments-config/tags`
Create an alert tag	`POST /resources/v2.1/enrichments-config/tags`
Retrieve, update, or delete a tag	`GET`, `PATCH`, `DELETE /resources/v2.1/enrichments-config/tags/{alerttag_name}`
Create a rule in a tag	`POST /resources/v2.1/enrichments-config/tags/{alerttag_name}/enrichments`
Update or delete a rule in a tag	`PATCH`, `DELETE /resources/v2.1/enrichments-config/tags/{alerttag_name}/enrichments`
Manage a single rule by ID	`GET`, `PATCH`, `DELETE /resources/v2.1/alert-enrichments/{enrichment_id}`
Set the tag run order	`PUT /resources/v2.1/enrichments-config`
Set the rule order within a tag	`PUT /resources/v2.1/enrichments-config/tags/{alerttag_name}/order`
List or create a mapping schema	`GET`, `POST /resources/v2.1/mapping-enrichment`
Retrieve, update, or delete a schema	`GET`, `PATCH`, `DELETE /resources/v2.1/mapping-enrichment/{mapschema_id}`
Upload a mapping table (CSV)	`POST /resources/v2.1/mapping-enrichment/{mapschema_id}/map`
Change specific mapping rows	`PATCH /resources/v2.1/mapping-enrichment/{mapschema_id}/map`
Check a mapping upload job	`GET /resources/v2.1/alert-enrichments-jobs/{job_id}`
Manage advanced mapping schemas	`/resources/alert-enricher/schemas`

Get Started with the Alert Enrichment API

Key Features#

Before You Start#

Understand the Objects#

How the objects relate#

Run order matters#

Choose the Right Endpoints#

Tag-scoped versus item-scoped rule endpoints#

Mapping enrichment versions#

Set Up Enrichment for the First Time#

Create a rule-based enrichment tag#

Upload a mapping enrichment#

Maintain Enrichment Over Time#

Endpoint Reference by Task#