Mapping Enrichment

Mapping enrichment lets you upload a CSV table that maps tag values to enrichment results. When an incoming alert matches a value in a query column, BigPanda writes the corresponding result column value to the alert.

Verify configuration
Advanced mapping fields such as groups conflict with previous alert enrichment versions. Contact your account team and confirm your account version before using enrichment routes.

How BigPanda mapping works

Mapping enrichment has two parts:

Mapping schema: Defines how BigPanda reads the table — the schema name, the run order, which columns are lookups, which columns are results, and how result columns are grouped.

Mapping table: The CSV data that populates tag values. Each row must supply a value for every column in the schema.

Each column is a query_tag (matched against the incoming alert) or a result_tag (written to the alert when a row matches). You also have an optional groups attribute on a result_tag, which lets you combine multiple columns into a single enrichment rule.

Groups and multiple query columns

The groups attribute is what makes a result tag depend on more than one column. Each group lists the columns to cluster, the order the group runs in, and how matched values combine. BigPanda evaluates groups in order and applies the first group whose columns all match.

Add groups to any result_tag that should resolve from a combination of columns. A result tag without groups behaves like a standard mapping result.

Group attributes

Attribute	Type	Description
`fields`	array	The columns to group together. Each object sets `type` to `group_tag` and `tag_name` to the column name, which must match the uploaded map exactly.
`order`	integer	Where the group runs in the evaluation order. The first group whose columns all match supplies the tag value.
`name`	string	The name of the group.
`method`	string	How values within the group combine. Use `first_match` for a single matched value, or `union` for an array of values.

A grouped result tag pairs the tag with one or more groups:

{
  "type": "result_tag",
  "tag_name": "email",
  "groups": [
    {
      "fields": [
        { "type": "group_tag", "tag_name": "alert_group" },
        { "type": "group_tag", "tag_name": "ticket_active" }
      ],
      "order": 1,
      "name": "alert_group_ticket_active",
      "method": "union"
    },
    {
      "fields": [
        { "type": "group_tag", "tag_name": "alert_group" }
      ],
      "order": 2,
      "name": "alert_group",
      "method": "first_match"
    }
  ]
}

An ungrouped result tag omits the attribute:

{
  "type": "result_tag",
  "tag_name": "email"
}

Before you start

All Alert Enricher routes require User API Key authorization. Pass the key in the Authorization header as Bearer <your_user_api_key>.

The base URL for US instances is https://api.bigpanda.io. The base URL for EU instances is https://eu-api.bigpanda.io.

Your role needs the Alert Enrichment permission to use the API. See the Roles Management guide.

Every map row must include a tag or group value for every column in the schema.

Schema and rule routes are rate-limited to 5 requests per second.

Tag limits apply
Each organization is capped at 1,000 alert tags, 500 enrichment items per alert tag, 20,000 alert enrichment items total, and 200 mapping enrichment result tags per map.

Endpoint reference

All routes require User API Key authorization.

Schema routes

Supported methods: POST, GET, PUT, DELETE. Rate limit: 5 requests per second.

Method	Route	Purpose
`POST`	`/resources/alert-enricher/schemas`	Create an advanced mapping schema
`GET`	`/resources/alert-enricher/schemas`	List all advanced mapping schemas
`GET`	`/resources/alert-enricher/schemas/<schema_id>`	Retrieve one advanced mapping schema
`PUT`	`/resources/alert-enricher/schemas/<schema_id>`	Update an advanced mapping schema
`DELETE`	`/resources/alert-enricher/schemas/<schema_id>`	Delete an advanced mapping schema

Map (rule) routes

Supported methods: POST, GET, PATCH, PUT, DELETE. Rate limit: 5 requests per second.

Method	Route	Purpose
`POST`	`/resources/alert-enricher/schemas/<schema_id>/rules`	Upload the map table as CSV. Creates a new table or replaces the existing one.
`GET`	`/resources/alert-enricher/schemas/<schema_id>/rules`	Retrieve map rows (paginated)
`PATCH`	`/resources/alert-enricher/schemas/<schema_id>/rules/<row_id>`	Update a single row
`PUT`	`/resources/alert-enricher/schemas/<schema_id>/rules`	Add or update rows in bulk
`DELETE`	`/resources/alert-enricher/schemas/<schema_id>/rules/<row_id>`	Delete a single row
`GET`	`/resources/alert-enricher/jobs/<job_id>`	Check the status of an upload or update job

Step 1: Define the advanced mapping schema

Create the schema that describes your table. For each column, set type to query_tag or result_tag and name the BigPanda tag it reads from or writes to. Add groups to any result tag that resolves from multiple columns.

Send a POST request to /resources/alert-enricher/schemas:

Schema fields

Field	Type	Description
`type`	string	Set to `advanced_mapping` for an advanced mapping schema.
`execution_order`	string	Where this schema runs relative to other enrichment.
`name`	string	The schema name.
`config.fields`	array	One object per column.
`config.fields[].type`	string	`query_tag` to match incoming alerts, or `result_tag` to enrich them.
`config.fields[].tag_name`	string	The BigPanda tag the column reads from or writes to.
`config.fields[].groups`	array	Optional. On a `result_tag`, clusters columns into grouped rules. See Group attributes.

Copy the id value from the response body. You use it as <schema_id> to upload and maintain the table.

Step 2: Upload the mapping table

Advanced mapping uses the same map structure as basic mapping enrichment. Upload the table as a CSV file that follows the schema you defined in Step 1 and uses the same column headers.

Send a POST request to /resources/alert-enricher/schemas/<schema_id>/rules with a text/csv body:

The request starts an asynchronous job and returns a job object. Copy the job identifier to check the status in Step 3.

End the payload with an empty new line
The CSV payload must end with an empty new line, and there must be no spaces before the closing quotation marks on the last line.

For CSV formatting rules and analytics flag columns, see the Best Practices for Mapping Enrichment documentation.

Step 3: Verify the job

Confirm the upload finished before relying on the map.

Send a GET request to /resources/alert-enricher/jobs/<job_id>.

Confirm the response status shows the job completed successfully.

(Recommended) Send test alerts through the Alert API to confirm the enrichment works as expected.

Resolve any test alerts as needed.

Step 4: Maintain the mapping table

How you update a map depends on what you need to change.

Replace the entire table

To replace all rows but keep the same structure, repeat Step 2. The new upload overwrites the existing table.

Update a single row

To change one row, send a PATCH request to /resources/alert-enricher/schemas/<schema_id>/rules/<row_id> with the row data as JSON. This is the most efficient way to edit a single row.

Add or update rows in bulk

To add or update several rows at once, send a PUT request to /resources/alert-enricher/schemas/<schema_id>/rules with a JSON list of rows. Every row must include an id. To insert a new row, generate a new UUID for its id.

Delete a row

To remove one row, send a DELETE request to /resources/alert-enricher/schemas/<schema_id>/rules/<row_id>.

Retrieve rows

To read rows, send a GET request to /resources/alert-enricher/schemas/<schema_id>/rules. Filter by row with the rule_ids query parameter, and page with page and per_page:

/resources/alert-enricher/schemas/<schema_id>/rules?rule_ids=<row_id>,<row_id>&page=1&per_page=5

Pass multiple row IDs as a comma-separated list. The maximum page size is 100.

URL-encode comma-separated lists
Some API tools require you to URL-encode query lists separated by commas. BigPanda parses the encoded URL automatically.

Each row change starts an asynchronous job. Verify it with Step 3.

Upgrade basic mapping to advanced mapping

Converting a basic mapping schema to advanced mapping changes both the call parameters and the rule structure. Validate the new schema before you remove the old one.

Identify the mapping schemas to replace, and determine the downstream effects on their tags.

Create a new advanced mapping schema with the groups structure.

Upload a new map to the Alert Enricher rules endpoint.

Validate enrichment on live alerts before deleting the old mapping schemas.

Best practices

Keep query columns minimal and specific so matches stay predictable.

Order groups from most specific to least specific, so the narrowest match wins first.

Use union when a match should collect every value, and first_match when it should resolve to one.

Test with sample alerts after every upload or row change before relying on the map in production.

Use a separate schema per logical data source rather than overloading one map.

Available resources and actions

v2.1 Routes

v2.0 Routes

Create Advanced Mapping Schema — POST /resources/alert-enricher/schemas

Retrieve All Advanced Mapping Schemas — GET /resources/alert-enricher/schemas

Retrieve Advanced Mapping Schema — GET /resources/alert-enricher/schemas/{schema_id}

Update Advanced Mapping Schema — PUT /resources/alert-enricher/schemas/{schema_id}

Delete Advanced Mapping Schema — DELETE /resources/alert-enricher/schemas/{schema_id}

Create Mapping Enrichment Table — POST /resources/alert-enricher/schemas/{schema_id}/rules

Create or Update Map Rows — PUT /resources/alert-enricher/schemas/{schema_id}/rules

Retrieve Map Rows — GET /resources/alert-enricher/schemas/{schema_id}/rules

Update Mapping Enrichment Row — PATCH /resources/alert-enricher/schemas/{schema_id}/rules/{row_id}

Delete Map Rows — DELETE /resources/alert-enricher/schemas/{schema_id}/rules

Delete Mapping Enrichment Row — DELETE /resources/alert-enricher/schemas/{schema_id}/rules/{row_id}

Retrieve Upload Job Status — GET /resources/alert-enricher/jobs/{job_id}

How BigPanda mapping works#

Groups and multiple query columns#

Group attributes#

Before you start#

Endpoint reference#

Schema routes#

Map (rule) routes#

Step 1: Define the advanced mapping schema#

Schema fields#

Step 2: Upload the mapping table#

Step 3: Verify the job#

Step 4: Maintain the mapping table#

Replace the entire table#

Update a single row#

Add or update rows in bulk#

Delete a row#

Retrieve rows#

Upgrade basic mapping to advanced mapping#

Best practices#

Available resources and actions#