Update docs with events /search endpoint (#988)

* AB#10424 update docs with events /search endpoint
* spelling and formatting
* Complete formatting and examples for baseline filtering and paging of events
Co-authored-by: steve lasker <[email protected]>
Signed-off-by: steve lasker <[email protected]>

Author: wp0pw

content/developers/api-reference/events-api/index.md

@@ -31,12 +31,6 @@ To minimize the impact, prior to switching to Asset-free Events, it is recommend
 
 ## Events API Examples
 
-{{< note >}}
-**Note:** If you are looking for a simple way to test DataTrails APIs you might prefer the [Postman collection](https://www.postman.com/datatrails-inc/workspace/datatrails-public/overview), the [YAML runner](/developers/yaml-reference/story-runner-components/) or the [Developers](https://app.datatrails.ai) section of the web UI.
-
-Additional YAML examples can be found in the articles in the [Overview](/platform/overview/introduction/) section.
-{{< /note >}}
-
 ### Event Creation
 
 - Create the [bearer_token](/developers/developer-patterns/getting-access-tokens-using-app-registrations) and store in a file in a secure local directory with 0600 permissions.
@@ -157,14 +151,11 @@ To associate an Attachment with an Event, see the [Attachments API](/developers/
 
 Event records in DataTrails are assigned UUIDs at creation time and referred to in all future API calls by a their unique identity in the format: `events/<event-id>`
 
-{{< note >}}
-**Note:** The current preview limits fetching Events to the Event identity.
-Querying across event attributes and trails are coming in a future preview.
-{{< /note >}}
+## Fetch Events by Identity
 
-#### Fetch Events by Identity
-
-- Replace the `<event-id>` below, using the event-id from the created event above: `"identity": "events/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"`:
+- Replace the `<event-id>` below, using the event-id from the created event above.  
+  `"identity": "events/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"`:  
+  Note, "`events/`" must be included as it's part of the resource name:
 
   ```bash
   EVENT_ID=<event-id>
@@ -175,13 +166,124 @@ Querying across event attributes and trails are coming in a future preview.
   ```bash
   curl -X GET \
       -H "@$HOME/.datatrails/bearer-token.txt" \
-      "https://app.datatrails.ai/archivist/v1/events/$EVENT_ID" | jq
+      "https://app.datatrails.ai/archivist/v1/$EVENT_ID" | jq
   ```
 
-## Events OpenAPI Docs
+## Filtering and Paging Events
 
-{{< openapi url="https://raw.githubusercontent.com/datatrails/datatrails-openapi/main/doc/events.swagger.json" >}}
+- To fetch multiple events, use a search document, posting to the `/events/search` endpoint  
+  Search document has following form:
+
+  ```bash
+  cat > /tmp/search.json <<EOF
+  {
+    "filter": "",
+    "top": 20,
+    "skip": 0
+  }
+  EOF
+  ```
+
+  where:  
+  `filter` = attribute name/value pairs  
+  `top` = number of results to return (max. 50) and  
+  `skip` = how many results to skip over before returning set of results
+
+  {{< note >}}
+  **Note:** The current preview does not support filtering of Events.
+  Filtering across event attributes and trails are coming in a future preview.
+  {{< /note >}}
+
+  - Post `search.json` to the `/search` endpoint:
+
+    ```bash
+    curl -X POST \
+        -H "@$HOME/.datatrails/bearer-token.txt" \
+        -d "@/tmp/search.json" \
+        "https://app.datatrails.ai/archivist/v1/events/search" \
+        | jq
+    ```
+
+  - The response will include a list of events matching above criteria:
+
+    ```json
+    {
+      "events": [
+        {
+          "identity": "events/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+          "attributes": {
+            "inspector": "Clouseau",
+            "arc_display_type": "Safety Conformance",
+            "Safety Rating": "90"
+          },
+          "trails": [
+            "Safety Conformance",
+            "Clouseau"
+          ],
+          "origin_tenant": "tenant/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+          "created_by": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+          "created_at": 1736421833577,
+          "confirmation_status": "STORED",
+          "merklelog_commit": {
+            "index": "0",
+            "idtimestamp": ""
+          }
+        },
+        {
+          "identity": "events/yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy",
+          "attributes": {
+            "inspector": "Clouseau",
+            "arc_display_type": "Safety Conformance",
+            "Safety Rating": "99"
+          },
+          "trails": [
+            "Safety Conformance",
+            "Clouseau"
+          ],
+          "origin_tenant": "tenant/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+          "created_by": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+          "created_at": 1736421873579,
+          "confirmation_status": "STORED",
+          "merklelog_commit": {
+            "index": "0",
+            "idtimestamp": ""
+          }
+        }
+      ]
+    }
+    ```
+
+  ### Fetch Paged Results
+
+  Use `top` and `skip` alongside `x-total-count` response header to navigate results.
+  If sum of `skip` and number of results in response is less than the count of all results (`x-total-count` in the response header) there are more results to retrieve.
+  To get the next set of results, re-issue the `/search` request with `skip` increased by number of results in current response.
+
+  If `x-total-count` response header has value greater than 2 (as indicated by value of `top` in `search.json`) modify `search.json` to the following:
+
+  ```bash
+  cat > /tmp/search.json <<EOF
+  {
+    "filter": "",
+    "top": 2,
+    "skip": 2
+  EOF
+  ```
+
+  - Post to the `/events/search/` endpoint to retrieve another page of results, repeating this process until `skip` + number or results in the response is equal to `x-total-count`.
+
+    ```bash
+    curl -X POST \
+        -H "@$HOME/.datatrails/bearer-token.txt" \
+        -d /tmp/search.json \
+        "https://app.datatrails.ai/archivist/v1/events/search" \
+        | jq
+    ```
 
 ## Integrity Protecting Content
 
 Integrity protected content can be hashed within an Event using the [Attachments API](/developers/api-reference/attachments-api/).
+
+## Events OpenAPI Docs
+
+{{< openapi url="https://raw.githubusercontent.com/datatrails/datatrails-openapi/main/doc/events.swagger.json" >}}