Attachment Updates

Signed-off-by: steve lasker <stevenlasker@hotmail.com>

Author: SteveLasker

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

@@ -141,7 +141,7 @@ In a future release, Events will be created independently from Assets.
 The DataTrails platform has reserved attributes starting with `arc_` to perform specific capabilities.
 See [Reserved Attributes](/glossary/reserved-attributes/) for more info.
 
-### Event Primary Image
+### Asset-Event Primary Image
 
 Asset-Events can use the [Blobs API](/developers/api-reference/blobs-api/) to associate a primary image in the DataTrails Application.
 

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

@@ -93,7 +93,7 @@ Additional YAML examples can be found in the articles in the [Overview](/platfor
   }
   ```
 
-### Assets With a Primary Image
+### Primary Image
 
 An Asset can have a primary image, displayed in the DataTrails Application.
 The image must first be uploaded with the [Blobs API](/developers/api-reference/blobs-api/), with the BLOB_ID, BLOB_HASH and BLOB_FILE captured for uploading the asset.

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

@@ -14,25 +14,22 @@ toc: true
 aliases: 
   - /docs/api-reference/attachments-api/
 ---
-{{< note >}}
-**Note:** This page is primarily intended for developers who will be writing applications that will use DataTrails for provenance.
-If you are looking for a simple way to test our API you might prefer our [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.io) section of the web UI.
+The Attachments API enables attaching and querying Binary Large OBjects (BLOBs) such as documents, process artifacts and images to Assets and Events.
 
-Additional YAML examples can be found in the articles in the [Overview](/platform/overview/introduction/) section.
+{{< note >}}
+Attachments apply to [Asset-Events](/developers/api-reference/asset-events-api/), and Asset-free [Events](/developers/api-reference/events-api/) (preview).
+There are subtle differences that are documented below.
 {{< /note >}}
 
-The Attachments API enables attaching and querying Binary Large OBjects (BLOBs) such as documents, process artifacts and images to Assets and Events.
-Events can also have a primary image associated with the event, providing feedback within the DataTrails application.
-
-The steps include:
+The steps to make an attachment include:
 
 1. Uploading content to the DataTrails [Blobs API](/developers/api-reference/blobs-api/).
 1. Attaching the blob to an [Asset](/developers/api-reference/assets-api/) or an [Event](/developers/api-reference/events-api/)
 1. Querying the Attachment, through an Asset or an Event
 
 ### Asset-Event Attachments
 
-Assets support attachments by creating an [Asset-Event](/developers/api-reference/asset-events-api/) with nested `arc_` [Reserved Attributes](/glossary/reserved-attributes/).
+Assets support attachments by creating an [Asset-Event](/developers/api-reference/asset-events-api/) with nested `arc_` [reserved attributes](/glossary/reserved-attributes/).
 
 - `"arc_attribute_type": "arc_attachment"`
 - `"arc_blob_identity": "blobs/b1234567-890b"`
@@ -41,7 +38,7 @@ Assets support attachments by creating an [Asset-Event](/developers/api-referenc
 - `"arc_file_name": "conformance.pdf"`
 - `"arc_display_name": "Conformance Report"`
 
-For example:
+Example of an Asset-event with two attachments:
 
 ```json
   {
@@ -71,36 +68,40 @@ For example:
   }
 ```
 
-The name of the parent attribute (`"conformance_report"`) can be any value, providing a means to name multiple attachments within a single event.
-The DataTrails platform evaluates `"arc_attribute_type": "arc_attachment"` to reference a DataTrails Blob based attachment.
+The name of the parent attribute (`"conformance_report"`) can be any value, providing a means to name multiple attachments within a single event, such as the additional `"security_report"` attachment.
 
-## Attachment API Examples
+The DataTrails platform evaluates `"arc_attribute_type": "arc_attachment"` to reference a DataTrails [Blob](/developers/api-reference/blobs-api/) based attachment.
+
+## Asset-Event Attachment API Examples
 
 - 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.
 
 - Upload the content of the Attachment using the [Blobs API](/developers/api-reference/blobs-api/).
 
-### Attachment Variables
+### Asset-Event Attachment Variables
 
 - To associate an existing Blob, set the `ASSET_ID`, `BLOB_ID`, `BLOB_HASH` value and `BLOB_FILE` from the [Blobs API](/developers/api-reference/blobs-api/):
 
   {{< note >}}
-  NOTE: The `ASSET_ID` dependency will be removed with [Non-asset based Events (preview)](/developers/api-reference/events-api/)
+  The `BLOB_HASH` is required, as it creates integrity protection between the content uploaded through the Blobs API, and the integrity protected reference of the Attachment.
+  Storing the hash in the attachment assures any tampering of the blob storage, including tampering within the DataTrails platform, would be evident.
+  
+  When retrieving the blob, the hash retrieved should be compared to the hash of the Attachment API to assure the content has not been tampered with.
   {{< /note >}}
 
   ```bash
   ASSET_ID=<asset-id>
   BLOB_ID=<blob-id>
-  BLOB_FILE=<file.ext>
   BLOB_HASH=<hash-value>
+  BLOB_FILE=conformance.pdf
   ```
 
   Example:
 
   ASSET_ID=assets/a1234567-890a  
   BLOB_ID=blobs/b1234567-890b  
-  BLOB_FILE=conformance.pdf  
   BLOB_HASH=h1234567h  
+  BLOB_FILE=conformance.pdf
 
 ### Create an Asset-Event Attachment
 
@@ -155,14 +156,16 @@ The DataTrails platform evaluates `"arc_attribute_type": "arc_attachment"` to re
         "arc_display_name": "Conformance Report"
       },
       "arc_display_type": "Safety Conformance"
-    }
+    },
+    "..."
+  }
   ```
 
 ### Retrieve a Specific Attachment on an Asset
 
 ```bash
 curl -H "@$HOME/.datatrails/bearer-token.txt" \
-    https://app.datatrails.ai/archivist/v2/attachments/assets/$ASSET_ID/$ATTACHMENT_ID
+    https://app.datatrails.ai/archivist/v2/attachments/$ASSET_ID/$ATTACHMENT_ID
 ```
 
 ### Retrieve a Specific Attachment on an Event

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

@@ -14,26 +14,20 @@ toc: true
 aliases: 
   - /docs/api-reference/blobs-api/
 ---
-{{< note >}}
-**Note:** This page is primarily intended for developers who will be writing applications that will use DataTrails for provenance.
-If you are looking for a simple way to test our API you might prefer our [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 >}}
-
-## Blob API Examples
-
-The Blobs API enables you to upload Binary Large OBjects (BLOBs) such as documents, process artifacts and images to attach to your evidence ledger.
+The Blobs API enables uploading Binary Large OBjects (BLOBs) such as documents, process artifacts and images, [attaching](/developers/api-reference/attachments-api/) them to [Assets](/developers/api-reference/assets-api/) and [Events (preview)](/developers/api-reference/events-api/).
 
 {{< note >}}
-**Note:** Blobs cannot be searched or listed as a collection in their own right: they must always be associated with an Asset or Event through an Attachment Attribute and can only be downloaded by users with appropriate access rights to that Attachment.
+**Note:** Blobs cannot be searched or listed as a collection using the blobs resource.
+BLobs must be associated with an Asset or Event through an Attachment Attribute and can only be downloaded by users with appropriate access rights to that Attachment.
 Take note of the Blob ID returned in the API response, it will be needed for use with Assets and Events.<br>
 For information on Attachments and how to implement them, please refer to [the Events API Reference](../events-api/#adding-attachments).
 {{< /note >}}
 
-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.
+## Blob API Examples
+
+- 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.
 
-### Sample Attachment
+### Reference a Sample File
 
 An attachment can be any type of file, from media files to code files.
 The sample uses Fyodor (cat.jpg), but the `BLOB_FILE` can be replaced with any content you desire:
@@ -53,7 +47,7 @@ The sample uses Fyodor (cat.jpg), but the `BLOB_FILE` can be replaced with any c
   BLOB_FILE=./cat.jpg
   ```
 
-- Upload the blob stored at /path/to/file:
+- Upload the blob:
 
   ```bash
   curl -X POST \
@@ -70,24 +64,24 @@ The sample uses Fyodor (cat.jpg), but the `BLOB_FILE` can be replaced with any c
   {
     "hash": {
       "alg": "SHA256",
-      "value": "h123456"
+      "value": "h1234567h"
     },
-    "identity": "blobs/b123467-8901",
+    "identity": "blobs/b123467-890b",
     "mime_type": "image/jpeg",
     "size": 21779,
-    "tenantid": "t1234567-8901-xxxx-xxxx-xxxxxxxxxxxx",
+    "tenantid": "t1234567-890t",
     "timestamp_accepted": "2025-01-27T23:45:29Z"
   }
   ```
 
 ### Retrieve a Blob
 
 - Capture the Blob identity from the above POST.  
-  Note, the `<blob-id>` combines `blobs/` and the ID  
-  example:`"identity": "blobs/b123467-8901"` becomes `BLOB_ID=blobs/b123467-8901`:
+  Note, the `<blob-id>` combines `blobs/` and the value.  
+  example:`"identity": "blobs/b123467-890b"` becomes `BLOB_ID=blobs/b123467-890b`:
 
   ```bash
-  BLOB_ID=<blob-id>
+  BLOB_ID=blobs/<blob-id>
   ```
 
 - Retrieve a specific Blob, downloading the `cat.jpg` file:
@@ -102,22 +96,9 @@ The sample uses Fyodor (cat.jpg), but the `BLOB_FILE` can be replaced with any c
 ### Finding Blobs
 
 The Blobs API does not support a discovery or query API that lists all possible blobs.
-Blobs are discovered through their usage within the DataTrails platform, such as the [Attachments API](/developers/api-reference/attachments-api/) or the primary image of an Asset or Event.
-Through the Attachments API, capture the value of the `"arc_blob_identity"`, nested below a named attribute with an `"arc_attribute_type": "arc_attachment"`:
-
-```json
-{
-  "event_attributes": {
-    "conformance_report": {
-      "arc_attribute_type": "arc_attachment",
-      "arc_blob_identity": "blobs/b123456-7890",
-      "arc_blob_hash_value": "h123456",
-      "arc_blob_hash_alg": "SHA256",
-      "arc_file_name": "Conformance.pdf"
-    }
-  }
-}
-```
+Blobs are discovered through their usage within the DataTrails platform, such as the [Attachments API](/developers/api-reference/attachments-api/) or the [Asset Primary Image](/developers/api-reference/assets-api/#primary-image), [Asset-event Primary Image](/developers/api-reference/asset-events-api/#asset-event-primary-image), or the [Event (preview) Primary Image](/developers/api-reference/events-api/#event-primary-image).
+
+Through the above APIs, capture the value of the `"arc_blob_identity"`, nested below a named attribute with an `"arc_attribute_type": "arc_attachment"`, then use the [Attachments API](/developers/api-reference/attachments-api/) to get metadata about the attachment.
 
 ## Blobs OpenAPI Docs