More blob and primary image formatting

Signed-off-by: steve lasker <[email protected]>

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

@@ -40,7 +40,7 @@ Additional YAML examples can be found in the articles in the [Overview](/platfor
 ### Asset Record 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.
-- Define the asset parameters, stored in `/tmp/asset.json`:
+- Define the asset:
 
   ```bash
   cat > /tmp/asset.json <<EOF
@@ -63,7 +63,8 @@ Additional YAML examples can be found in the articles in the [Overview](/platfor
       -H "@$HOME/.datatrails/bearer-token.txt" \
       -H "Content-type: application/json" \
       -d "@/tmp/asset.json" \
-      https://app.datatrails.ai/archivist/v2/assets
+      https://app.datatrails.ai/archivist/v2/assets \
+      | jq
   ```
 
   The response:
@@ -100,9 +101,9 @@ The image must first be uploaded with the [Blobs API](/developers/api-reference/
 - Define the asset parameters, with the image information from the uploaded Blob:
 
   ```bash
-  BLOB_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+  BLOB_ID=<blob-id>
   BLOB_FILE=file.jpg
-  BLOB_HASH=xxxxxxxxxxxxxxx
+  BLOB_HASH=<hash>
   ```
 
   ```bash
@@ -115,13 +116,14 @@ The image must first be uploaded with the [Blobs API](/developers/api-reference/
       "weight": "3.6kg",
       "arc_primary_image": {
         "arc_attribute_type": "arc_attachment",
-        "arc_blob_hash_value": "$BLOB_HASH",
         "arc_blob_identity": "blobs/$BLOB_ID",
         "arc_blob_hash_alg": "SHA256",
-        "arc_file_name": "$BLOB_FILE"
-      },
+        "arc_blob_hash_value": "$BLOB_HASH",
+        "arc_display_name": "arc_primary_image",
+        "arc_file_name": "cat.jpeg"
+      }
+    },
     "public": false
-    }
   }
   EOF
   ```
@@ -149,15 +151,23 @@ The image must first be uploaded with the [Blobs API](/developers/api-reference/
     ],
     "attributes": {
       "arc_display_type": "Cat",
+      "arc_primary_image": {
+        "arc_attribute_type": "arc_attachment",
+        "arc_blob_identity": "blobs/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+        "arc_blob_hash_alg": "SHA256",
+        "arc_blob_hash_value": "xxxxxxxxxxxx",
+        "arc_display_name": "arc_primary_image",
+        "arc_file_name": "cat.jpeg"
+      },
       "arc_display_name": "My Cat",
       "weight": "3.6kg"
     },
     "confirmation_status": "PENDING",
     "tracked": "TRACKED",
-    "owner": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
-    "at_time": "2024-09-04T23:35:13Z",
+    "owner": "yyyyyyyyyy",
+    "at_time": "2025-01-28T21:58:34Z",
     "proof_mechanism": "MERKLE_LOG",
-    "chain_id": "xxxxxxxxxx",
+    "chain_id": "123456",
     "public": false,
     "tenant_identity": "tenant/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
   }
@@ -169,36 +179,40 @@ The image must first be uploaded with the [Blobs API](/developers/api-reference/
 **Warning**: Assets can only be made public at Asset creation and cannot be made private afterwards.
 {{< /warning >}}
 
-In most cases it is appropriate to create a standard Asset. These Assets can only be shared externally using Access Policies as described in [Sharing Assets with OBAC](/platform/administration/sharing-access-outside-your-tenant/) or the [IAM Policies API Reference](../iam-policies-api/).
+In most cases it is appropriate to create a standard Asset.
+These Assets can only be shared externally using Access Policies as described in [Sharing Assets with OBAC](/platform/administration/sharing-access-outside-your-tenant/) or the [IAM Policies API Reference](../iam-policies-api/).
 
 However, it is also possible to create a Public Asset which can be shared with a read-only public url; similar to the link sharing you may have seen in file sharing services like Google Drive or DropBox.
 
 Public Assets can be used for Public Attestation, where you may wish to publicly assert data you have published.
 
 For example, the vulnerability reports against an OpenSource software package, or perhaps the maintenance records for a public building.
 
-Creating a Public Asset just requires flipping the `public` value in the above request to `true`. From then on, **only** the creating Tenancy may update the Asset and Events on a Public Asset through their private, signed-in interface.
+Creating a Public Asset just requires flipping the `public` value in the above request to `true`.
+From then on, **only** the creating Tenancy may update the Asset and Events on a Public Asset through their private, signed-in interface.
 
 All Public Assets are then given a read-only public URL that can be retrieved using [Fetch a Public Asset's URL](./#fetch-a-public-assets-url), any Events added to that Public Asset will also get their own unique Public URL that can be retrieved with [Fetch a Public Asset's Event URL](./#fetch-a-public-assets-event-url).
 
 This link can be shared with anyone to give them read-only access to the Asset or Event without the need to sign in.
 
-To interact with the unauthenticated Public Interface for a Public Asset see the [Public Assets API Reference](../public-assets-api/). To update the Assets and Events as the creating Tenant on a Public Asset's authenticated Private Interface, you would still use the standard Assets and Events API as normal.
+To interact with the unauthenticated Public Interface for a Public Asset see the [Public Assets API Reference](../public-assets-api/).
+To update the Assets and Events as the creating Tenant on a Public Asset's authenticated Private Interface, you would still use the standard Assets and Events API as normal.
 
 #### Creating a Document Profile Asset
 
 This class of Asset conforms to the [Document Profile Developer Pattern](/developers/developer-patterns/document-profile/), which allows you to trace the lifecycle of a document.
 
-- Define the asset parameters and store in `/path/to/jsonfile`:
+- Define the asset:
 
-  ```json
+  ```bash
+  cat > /tmp/asset.json <<EOF
   {
       "attributes": {
           "arc_description":"Test Document",
           "arc_display_type":"Marketing glossy",
           "arc_display_name":"Test Document Profile Asset",
           "arc_profile":"Document",
-          "document_hash_value":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
+          "document_hash_value":"xxxxxxxxxxxxxxxxxxxx",
           "document_hash_alg":"sha256",
           "document_version":"1",
           "document_status":"Published",
@@ -207,8 +221,10 @@ This class of Asset conforms to the [Document Profile Developer Pattern](/develo
       "behaviours": [
           "Builtin",
           "RecordEvidence"
-      ]
+      ],
+      "public": true
   }
+  EOF
   ```
 
   {{< note >}}
@@ -219,10 +235,11 @@ This class of Asset conforms to the [Document Profile Developer Pattern](/develo
 
   ```bash
   curl -X POST \
-      -H "@datatrails-bearer.txt" \
+      -H "@$HOME/.datatrails/bearer-token.txt" \
       -H "Content-type: application/json" \
-      -d "@/path/to/jsonfile" \
-      https://app.datatrails.ai/archivist/v2/assets
+      -d "@/tmp/asset.json" \
+      https://app.datatrails.ai/archivist/v2/assets \
+      | jq
   ```
 
   The response is:
@@ -241,7 +258,7 @@ This class of Asset conforms to the [Document Profile Developer Pattern](/develo
           "document_status": "Published",
           "arc_description": "Test Document",
           "arc_display_type": "Marketing glossy",
-          "document_hash_value": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
+          "document_hash_value": "xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
           "arc_display_name": "Test Document Profile Asset",
           "document_hash_alg": "sha256"
       },
@@ -280,19 +297,21 @@ If you do not know the Asset’s identity you can fetch Asset records using othe
 - If you know the unique identity of the Asset record `GET` the resource:
 
   ```bash
+  ASSET_ID=<asset-id>
   curl -X GET \
       -H "@$HOME/.datatrails/bearer-token.txt" \
-      https://app.datatrails.ai/archivist/v2/assets/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+      https://app.datatrails.ai/archivist/v2/assets/$ASSET_ID
   ```
 
 #### Fetch Specific Asset at Given Point in Time by Identity
 
 - If you know the unique identity of an Asset record and want to show its state at any given point in the past, simply `GET` with the following query parameter:
 
   ```bash
+  ASSET_ID=<asset-id>
   curl -X GET \
       -H "@$HOME/.datatrails/bearer-token.txt" \
-      "https://app.datatrails.ai/archivist/v2/assets/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx?at_time=2021-01-13T12:34:21Z"
+      "https://app.datatrails.ai/archivist/v2/assets/$ASSET_ID?at_time=2021-01-13T12:34:21Z"
   ```
 
   This will return the Asset record with the values it had on `2021-01-13T12:34:21Z`.
@@ -339,7 +358,7 @@ If you do not know the Asset’s identity you can fetch Asset records using othe
 
 #### Fetch Assets by Filtering for Presence of a Field
 
-- To fetch all Assets with a field set to any value, `GET` the Assets resource and filter on most available fields. For example:
+- To fetch all Assets with a field set to any value, `GET` the Assets resource and filter on most available fields.
 
   ```bash
   curl -g -X GET \
@@ -351,7 +370,7 @@ If you do not know the Asset’s identity you can fetch Asset records using othe
 
 #### Fetch Assets Which are Missing a Field
 
-- To fetch all Assets with a field which is not set to any value, `GET` the Assets resource and filter on most available fields. For example:
+- To fetch all Assets with a field which is not set to any value, `GET` the Assets resource and filter on most available fields.
 
   ```bash
   curl -g -X GET \
@@ -402,7 +421,8 @@ While deleting Assets is not possible, it is possible to hide them from default
 
 #### Untracking an Asset
 
-Untracking is actually an Event in the Asset lifecycle, so it is necessary to know the Asset identity and POST to it directly. Here we assume we are working with an Asset with identity `assets/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`.
+Untracking is actually an Event in the Asset lifecycle, so it is necessary to know the Asset identity and POST to it directly.
+Here we assume we are working with an Asset with identity `assets/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`.
 
 - Define the Event parameters and store in `/path/to/jsonfile`:
 
@@ -456,7 +476,8 @@ Untracking is actually an Event in the Asset lifecycle, so it is necessary to kn
 
 #### (Re-)Tracking an Asset
 
-It is possible to reverse an untracking Event by tracking the Asset again, assuming you know the Asset identity. Here we assume we are working with an Asset with identity `assets/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`.
+It is possible to reverse an untracking Event by tracking the Asset again, assuming you know the Asset identity.
+Here we assume we are working with an Asset with identity `assets/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`.
 
 - Define the Event parameters and store in `/path/to/jsonfile`:
 

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

@@ -35,20 +35,28 @@ Create the [bearer_token](/developers/developer-patterns/getting-access-tokens-u
 
 ### Upload a Blob
 
+- Download a file, or select another file for upload:
+
+  ```bash
+  curl https://app.datatrails.ai/archivist/v2/attachments/publicassets/208c5282-750e-4302-86f8-eb751de89005/events/4161673f-efa4-4391-bf06-347edd53024e/dae5a430-7d2e-4b88-b753-c09bdcc48c33 \
+    -o cat.jpg
+  ```
+
 - Identify the file to upload:
 
   ```bash
-  BLOB=./myfile.jpg
+  BLOB_FILE=./cat.jpg
   ```
 
 - Upload the blob stored at /path/to/file:
 
   ```bash
-  curl -v -X POST \
+  curl -X POST \
       -H "@$HOME/.datatrails/bearer-token.txt" \
       -H "content_type=image/jpg" \
-      -F "file=@$BLOB" \
-      https://app.datatrails.ai/archivist/v1/blobs
+      -F "file=@$BLOB_FILE" \
+      https://app.datatrails.ai/archivist/v1/blobs \
+      | jq
   ```
 
   The response:
@@ -72,37 +80,21 @@ Create the [bearer_token](/developers/developer-patterns/getting-access-tokens-u
 
 ### Retrieve a Blob
 
-- Retrieve a specific Blob:
+- Capture the Blob identity from the above POST:
 
   ```bash
-  curl -v \
-      -H "@$HOME/.datatrails/bearer-token.txt" \
-      -H "content_type=image/jpg" \
-      --output "/path/to/file" \
-      https://app.datatrails.ai/archivist/v1/blobs/$BLOB_ID
+  BLOB_ID=<blob-id>
   ```
 
-  The response is:
+- Retrieve a specific Blob, downloading the `cat.jpg` file:
 
-  ```json
-  {
-    "hash": {
-      "alg": "SHA256",
-      "value": "xxxxxxxxxxxxxxxxxxxxxxx"  },
-    "identity": "blobs/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
-    "issuer": "local",
-    "mime_type": "image/jpeg",
-    "size": 81254,
-    "subject": "[email protected]",
-    "tenantid": "tenant/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
-    "timestamp_accepted": "2023-02-06T16:04:31Z",
-    "scanned_status": "NOT_SCANNED",
-    "scanned_bad_reason": "",
-    "scanned_timestamp": ""
-  }
+  ```bash
+  curl -H "@$HOME/.datatrails/bearer-token.txt" \
+      -H "content_type=image/jpg" \
+      --output "$BLOB_FILE" \
+      https://app.datatrails.ai/archivist/v1/blobs/$BLOB_ID
   ```
 
-
 ## Blobs OpenAPI Docs
 
 {{< openapi url="https://raw.githubusercontent.com/datatrails/datatrails-openapi/master/doc/blobsv1.swagger.json" >}}

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

@@ -113,7 +113,7 @@ 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/archivst/v1/events/$EVENT_ID" | jq
+      "https://app.datatrails.ai/archivist/v1/events/$EVENT_ID" | jq
   ```
 
 ## Events OpenAPI Docs