Add matching policies endpoints (#210)

jacob-denis-flare · web-flow · commit 2fbfbe6799db · 2026-04-10T13:07:32.000-04:00
* docs(api): add documentation for new `matching_policies` endpoints

* docs(changelog): update for new `matching_policies` endpoints

* docs(guide): add `create-identifier-with-matching-policies`

* docs(changelog): update for new `create-identifier-with-matching-policies` guide

* docs(guide): update `create-identifiers-with-matching-policies` sdk example

* docs(guide): better description for `create-identifiers-with-matching-policies`

* docs(api): add missing description for `clean_past_events`

* docs(changelog): update warning message

* docs(snippets): add `beta-endpoint`

* docs(api): use beta snippet in `get-event`

* docs(api): make `matching_policies` beta

* docs(snippet): fix `beta-endpoint`

* docs(api): update `get-matching-policy` title
diff --git a/docs/api-reference/spec/firework-v4-openapi.json b/docs/api-reference/spec/firework-v4-openapi.json
diff --git a/docs/api-reference/v4/endpoints/assign-policy.mdx b/docs/api-reference/v4/endpoints/assign-policy.mdx
@@ -0,0 +1,8 @@
+---
+title: "Assign Policy (Beta)"
+openapi: post /firework/v4/matching_policies/{policy_uuid}/assignments
+---
+
+import BetaEndpoint from '/snippets/beta-endpoint.mdx'
+
+<BetaEndpoint name="Assign Policy" />
diff --git a/docs/api-reference/v4/endpoints/create-matching-policy.mdx b/docs/api-reference/v4/endpoints/create-matching-policy.mdx
@@ -0,0 +1,8 @@
+---
+title: "Create Matching Policy (Beta)"
+openapi: post /firework/v4/matching_policies
+---
+
+import BetaEndpoint from '/snippets/beta-endpoint.mdx'
+
+<BetaEndpoint name="Create Matching Policy" />
diff --git a/docs/api-reference/v4/endpoints/delete-matching-policy.mdx b/docs/api-reference/v4/endpoints/delete-matching-policy.mdx
@@ -0,0 +1,8 @@
+---
+title: "Delete Matching Policy (Beta)"
+openapi: delete /firework/v4/matching_policies/{policy_uuid}
+---
+
+import BetaEndpoint from '/snippets/beta-endpoint.mdx'
+
+<BetaEndpoint name="Delete Matching Policy" />
diff --git a/docs/api-reference/v4/endpoints/get-event.mdx b/docs/api-reference/v4/endpoints/get-event.mdx
@@ -4,11 +4,10 @@ openapi: firework-v4-openapi get /firework/v4/events/
 ---
 
 import EventResponses from '/snippets/event_model_examples/events_overview.mdx'
+import BetaEndpoint from '/snippets/beta-endpoint.mdx'
 
 <Panel>
   <EventResponses />
 </Panel>
 
-<Note>
-The Retrieve Event V2 endpoint is still in beta and is subject to change.
-</Note>
+<BetaEndpoint name="Retrieve Event V2" />
diff --git a/docs/api-reference/v4/endpoints/get-matching-policy.mdx b/docs/api-reference/v4/endpoints/get-matching-policy.mdx
@@ -0,0 +1,8 @@
+---
+title: "Retrieve Matching Policy (Beta)"
+openapi: get /firework/v4/matching_policies/{policy_uuid}
+---
+
+import BetaEndpoint from '/snippets/beta-endpoint.mdx'
+
+<BetaEndpoint name="Retrieve Matching Policy" />
diff --git a/docs/api-reference/v4/endpoints/list-matching-policies-by-identifier-id.mdx b/docs/api-reference/v4/endpoints/list-matching-policies-by-identifier-id.mdx
@@ -0,0 +1,8 @@
+---
+title: "List Matching Policies By Identifier Id (Beta)"
+openapi: get /firework/v4/matching_policies/by_identifier_id/{identifier_id}
+---
+
+import BetaEndpoint from '/snippets/beta-endpoint.mdx'
+
+<BetaEndpoint name="List Matching Policies By Identifier Id" />
diff --git a/docs/api-reference/v4/endpoints/list-matching-policies.mdx b/docs/api-reference/v4/endpoints/list-matching-policies.mdx
@@ -0,0 +1,8 @@
+---
+title: "List Matching Policies (Beta)"
+openapi: get /firework/v4/matching_policies
+---
+
+import BetaEndpoint from '/snippets/beta-endpoint.mdx'
+
+<BetaEndpoint name="List Matching Policies" />
diff --git a/docs/api-reference/v4/endpoints/list-policy-assignments.mdx b/docs/api-reference/v4/endpoints/list-policy-assignments.mdx
@@ -0,0 +1,8 @@
+---
+title: "List Policy Assignments (Beta)"
+openapi: get /firework/v4/matching_policies/{policy_uuid}/assignments
+---
+
+import BetaEndpoint from '/snippets/beta-endpoint.mdx'
+
+<BetaEndpoint name="List Policy Assignments" />
diff --git a/docs/api-reference/v4/endpoints/unassign-policy.mdx b/docs/api-reference/v4/endpoints/unassign-policy.mdx
@@ -0,0 +1,8 @@
+---
+title: "Unassign Policy (Beta)"
+openapi: delete /firework/v4/matching_policies/{policy_uuid}/assignments
+---
+
+import BetaEndpoint from '/snippets/beta-endpoint.mdx'
+
+<BetaEndpoint name="Unassign Policy" />
diff --git a/docs/api-reference/v4/endpoints/update-matching-policy.mdx b/docs/api-reference/v4/endpoints/update-matching-policy.mdx
@@ -0,0 +1,8 @@
+---
+title: "Update Matching Policy (Beta)"
+openapi: put /firework/v4/matching_policies/{policy_uuid}
+---
+
+import BetaEndpoint from '/snippets/beta-endpoint.mdx'
+
+<BetaEndpoint name="Update Matching Policy" />
diff --git a/docs/changelog/overview.mdx b/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. It will continue to work, but could be removed in the future.
+</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).
 
diff --git a/docs/docs.json b/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": [
diff --git a/docs/guides/create-identifiers-with-matching-policies.mdx b/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>
diff --git a/docs/snippets/beta-endpoint.mdx b/docs/snippets/beta-endpoint.mdx
@@ -0,0 +1,3 @@
+<Note>
+  The {name} endpoint is still in beta and is subject to change.
+</Note>
