Merge pull request #10 from Flared/max/new-guide-tenant-events

Add new guide to fetch tenant events

docs/api-reference/v2/endpoints/activities/get-activities-.mdx → docs/api-reference/v2/endpoints/activities/get-activities.mdx

@@ -1,3 +1,4 @@
 ---
 openapi: firework-v2-openapi get /activities/{index}/{source}/{id}
+title: Retrieve Event
 ---

docs/guides/tenant-events-api-v4.mdx

@@ -0,0 +1,77 @@
+---
+title: 'List Events Within a Tenant'
+---
+
+Browsing events within a tenant is exposed through the
+[/events/tenant/_search <Icon icon="code" size={16} />](#)
+API.
+
+This guide explains how to use the tenant feed API perform a full export
+of all results.
+
+## Paging
+
+The tenant feed endpoint uses parameters that match the
+[Flare standard paging pattern <Icon icon="book" size={16} />](/concepts/paging).
+
+## Fetching new results in future executions
+
+It is possible to save the `next` in a database and use it to resume fetching new results in the future.
+However, it is important that future requests use **exactly** the same parameters for everything else but `next`.
+
+## Getting the full data of results
+
+For performance reasons, feed results only contain the bear minimum.
+To get the full data, an API call must be made per result to the [/activities/:index/:source/:id <Icon icon="code" size={16} />](/api-reference/v2/endpoints/activities/get-activities) endpoint.
+
+<AccordionGroup>
+
+<Accordion title="Python SDK Example">
+```python
+import os
+import time
+
+from flareio import FlareApiClient
+
+
+api_key: str | None = os.environ.get("FLARE_API_KEY")
+if not api_key:
+    raise Exception("Please provide an API key")
+
+api_client = FlareApiClient(api_key=api_key)
+
+last_from: str | None = None
+fetched_pages: int = 0
+
+for resp in api_client.scroll(
+    method="POST",
+    url="/firework/v4/events/tenant/_search",
+    json={
+        "from": last_from,
+    }
+):
+    # Rate limiting.
+    time.sleep(1)
+
+    resp_data: dict = resp.json()
+
+    fetched_pages += 1
+    num_results: int = len(resp_data["items"])
+    print(f"Fetched page {fetched_pages} with {num_results} results...")
+
+    # Save the last "next" value.
+    last_from = resp_data.get("next") or last_from
+
+    # Get the full data
+    for item in resp_data["items"]:
+        # Rate limiting.
+        time.sleep(1)
+
+        item_uid: str = item["metadata"]["uid"]
+        response = api_client.get(f"/firework/v2/activities/{item_uid}")
+        full_data = response.json()
+        print(f"Here is the full data of the event: {full_data}")
+```
+</Accordion>
+
+</AccordionGroup>

docs/mint.json

@@ -49,8 +49,8 @@
     }
   ],
   "topAnchor": {
-      "name": "API Documentation",
-      "icon": "code"
+    "name": "API Documentation",
+    "icon": "code"
   },
   "anchors": [
     {
@@ -164,7 +164,6 @@
             "api-reference/v2/endpoints/identifiers/put-assets",
             "api-reference/v3/endpoints/identifiers/get-identifiers-1",
             "api-reference/v2/endpoints/identifiers/delete-assets",
-
             "api-reference/v2/endpoints/identifiers/post-assets-toggle"
           ]
         },
@@ -180,6 +179,7 @@
         {
           "group": "Events",
           "pages": [
+            "api-reference/v2/endpoints/activities/get-activities",
             "api-reference/v2/endpoints/activities/get-activities--ai_assistance"
           ]
         },
@@ -199,7 +199,6 @@
             "api-reference/v2/endpoints/identifiers/post-assets-alerts",
             "api-reference/v2/endpoints/identifiers/put-assets-alerts",
             "api-reference/v2/endpoints/identifiers/delete-assets-alerts",
-
             "api-reference/v2/endpoints/identifiers/get-assetsgroups-alerts",
             "api-reference/v2/endpoints/identifiers/post-assetsgroups-alerts",
             "api-reference/v2/endpoints/identifiers/put-assetsgroups-alerts",
@@ -221,12 +220,9 @@
             "api-reference/v2/endpoints/organizations/post-organizations-members",
             "api-reference/v2/endpoints/organizations/get-organizations-members-1",
             "api-reference/v2/endpoints/organizations/put-organizations-members",
-
             "api-reference/v2/endpoints/organizations/post-organizations-members-enable",
             "api-reference/v2/endpoints/organizations/post-organizations-members-disable",
-
             "api-reference/v2/endpoints/organizations/get-organizations-members-tenants",
-
             "api-reference/v2/endpoints/organizations/post-organizations-members-permissions"
           ]
         },
@@ -257,7 +253,6 @@
             "api-reference/v2/endpoints/tenants/get-tenants",
             "api-reference/v2/endpoints/tenants/put-tenants",
             "api-reference/v2/endpoints/tenants/post-tenants-archive",
-
             "api-reference/v2/endpoints/tenants/get-tenants-users",
             "api-reference/v2/endpoints/tenants/post-tenants-users",
             "api-reference/v2/endpoints/tenants/delete-tenants-users"
@@ -272,4 +267,4 @@
     "github": "https://github.com/flared",
     "youtube": "https://www.youtube.com/@flarecybersecurity"
   }
-}
+}