Add matching policies endpoints

docs/api-reference/v4/endpoints/assign-policy.mdx

@@ -0,0 +1,3 @@
+---
+openapi: post /firework/v4/matching_policies/{policy_uuid}/assignments
+---

docs/api-reference/v4/endpoints/create-matching-policy.mdx

@@ -0,0 +1,3 @@
+---
+openapi: post /firework/v4/matching_policies
+---

docs/api-reference/v4/endpoints/delete-matching-policy.mdx

@@ -0,0 +1,3 @@
+---
+openapi: delete /firework/v4/matching_policies/{policy_uuid}
+---

docs/api-reference/v4/endpoints/get-matching-policy.mdx

@@ -0,0 +1,3 @@
+---
+openapi: get /firework/v4/matching_policies/{policy_uuid}
+---

docs/api-reference/v4/endpoints/list-matching-policies-by-identifier-id.mdx

@@ -0,0 +1,3 @@
+---
+openapi: get /firework/v4/matching_policies/by_identifier_id/{identifier_id}
+---

docs/api-reference/v4/endpoints/list-matching-policies.mdx

@@ -0,0 +1,3 @@
+---
+openapi: get /firework/v4/matching_policies
+---

docs/api-reference/v4/endpoints/list-policy-assignments.mdx

@@ -0,0 +1,3 @@
+---
+openapi: get /firework/v4/matching_policies/{policy_uuid}/assignments
+---

docs/api-reference/v4/endpoints/unassign-policy.mdx

@@ -0,0 +1,3 @@
+---
+openapi: delete /firework/v4/matching_policies/{policy_uuid}/assignments
+---

docs/api-reference/v4/endpoints/update-matching-policy.mdx

@@ -0,0 +1,3 @@
+---
+openapi: put /firework/v4/matching_policies/{policy_uuid}
+---

docs/changelog/overview.mdx

@@ -12,6 +12,18 @@ This page lists changes to Flare's API.
 Release notes for the Flare Platform can be found on the [product documentation website](https://docs.flare.io/releases).
 </Note>
 
+<Update label="2026-04" description="API - April 2026">
+  Added new endpoints to manage [Matching Policies <Icon icon="code" size={16} />](/api-reference/v4/endpoints/list-matching-policies).
+
+  This is useful for customers who want precise control over which events appear in an Identifier’s feed, either by including or excluding events based on keywords, or by scoping results with a specific search query.
+
+  The guide
+  [Create And Assign Matching Policies to Identifiers <Icon icon="book" size={16} />](/guides/create-identifiers-with-matching-policies)
+  was added with an example usage.
+
+  <Icon icon="warning" size={16} /> This deprecates the use of the `blacklist` parameter (Ignored Terms) in Identifiers.
+</Update>
+
 <Update label="2026-03" description="API - March 2026">
   Added new value for the `include` parameter in the [Global Search Credentials Endpoint <Icon icon="code" size={16} />](/api-reference/v4/endpoints/credentials-global-search).
 

docs/docs.json

@@ -53,7 +53,8 @@
               "guides/cookie-monitoring",
               "guides/ioc-feeds",
               "guides/threat-flow-report",
-              "guides/update-identifiers"
+              "guides/update-identifiers",
+              "guides/create-identifiers-with-matching-policies"
             ]
           }
         ]
@@ -156,6 +157,20 @@
                   "api-reference/v4/endpoints/create-action-for-identifier-recommendations"
                 ]
               },
+              {
+                "group": "Matching Policies",
+                "pages": [
+                  "api-reference/v4/endpoints/list-matching-policies",
+                  "api-reference/v4/endpoints/list-matching-policies-by-identifier-id",
+                  "api-reference/v4/endpoints/create-matching-policy",
+                  "api-reference/v4/endpoints/update-matching-policy",
+                  "api-reference/v4/endpoints/get-matching-policy",
+                  "api-reference/v4/endpoints/delete-matching-policy",
+                  "api-reference/v4/endpoints/list-policy-assignments",
+                  "api-reference/v4/endpoints/assign-policy",
+                  "api-reference/v4/endpoints/unassign-policy"
+                ]
+              },
               {
                 "group": "Alerts",
                 "pages": [

docs/guides/create-identifiers-with-matching-policies.mdx

@@ -0,0 +1,95 @@
+---
+title: 'Create And Assign Matching Policies to Identifiers'
+---
+Identifiers (domains, keywords, identities, and other types) and Matching Policies (excluded_keywords, lucene_query and other types) can be created, updated and listed via the Management API.
+
+Matching Policies are useful for customers who want precise control over which events appear in an Identifier’s feed, either by including or excluding events based on keywords, or by scoping results with a specific search query.
+
+This guide covers how to create an identifier and apply a matching policy to it. 
+
+## Steps
+<Steps>
+
+  <Step title="Create an identifier">
+    Use the
+    [Create Identifier <Icon icon="code" size={16} />](/api-reference/v2/endpoints/identifiers/post-fireworkv2assets)
+    endpoint to create an identifier. Apply filters to narrow down results to specific identifiers you want to match.
+  </Step>
+
+  <Step title="Create a matching policy">
+    Use the
+    [Create Matching Policy <Icon icon="code" size={16} />](/api-reference/v4/endpoints/create-matching-policy)
+    endpoint to create a matching policy to precisely control which events should appear in the identifier's feed.
+  </Step>
+
+  <Step title="Assign the matching policy to the identifier">
+    Use the
+    [Assign Policy <Icon icon="code" size={16} />](/api-reference/v4/endpoints/assign-policy)
+    endpoint to assign the matching policy to the identifier.
+  </Step>
+
+</Steps>
+
+## End-to-end examples
+
+<AccordionGroup>
+
+<Accordion title="Python SDK Example">
+```python
+from flareio import FlareApiClient
+from flareio.ratelimit import Limiter
+
+
+api_client = FlareApiClient.from_env()
+
+limiter_default = Limiter.from_seconds(0.25)
+
+# 1. Create an Identifier
+identifier_resp = api_client.post(
+    "/firework/v2/assets/",
+    json={
+        "name": "scatterholt.com",
+        "type": "domain",
+        "search_types": [
+            "forum_post",
+        ],
+        "data": {"type": "domain", "fqdn": "scatterholt.com"},
+        "risks": [1, 2, 3, 4, 5],
+    },
+)
+
+identifier = identifier_resp.json()["asset"]
+identifier_id = identifier["id"]
+
+# Rate limiting (default).
+limiter_default.tick()
+
+# 2. Create a Matching Policy
+matching_policy_resp = api_client.post(
+    "/firework/v4/matching_policies",
+    json={
+        "name": "Terms to ignore",
+        "type": "EXCLUDED_KEYWORDS",
+        "value": {"keywords": ["term1", "term2", "term3"]},
+    },
+)
+matching_policy = matching_policy_resp.json()
+matching_policy_name = matching_policy["name"]
+matching_policy_uuid = matching_policy["uuid"]
+
+# Rate limiting (default).
+limiter_default.tick()
+
+# 3. Assign the matching policy to the identifier
+api_client.post(
+    f"/firework/v4/matching_policies/{matching_policy_uuid}/assignments",
+    json={"identifier_ids": [identifier_id], "clean_past_events": False},
+)
+
+print(
+    f"Created identifier {identifier_id} with matching policy '{matching_policy_name}' assigned to it"
+)
+```
+</Accordion>
+
+</AccordionGroup>