Assets API

Assets API Reference

DataTrails provides two mechanisms for persisting provenance metadata:

  1. Asset based Events: where a series of Events are grounded to a specific Asset.
  2. Asset-free Events (preview) : where events can be correlated across pre-defined Trails.

The Asset-free Events implementation is the future focus of the DataTrails platform providing the capabilities of Asset based events, with broader flexibility, performance and scalability. Asset-free Events are currently in preview, inviting early developer feedback.

The transition to Asset-free Events involves removing the dependency to anchoring Events in an Asset and shifting from mutable Asset Attributes to immutable Event Attributes. To minimize the impact, prior to switching to Asset-free Events, it is recommended to use Event Attributes, rather than Asset Attributes.

Note: For more information on Assets and Asset creation, visit Core Concepts and the Creating an Asset guide.

Asset API Examples

Note: If you are looking for a simple way to test DataTrails APIs you might prefer the Postman collection, the YAML runner or the Developers section of the web UI.

Additional YAML examples can be found in the articles in the Overview section.

Asset Record Creation

  • Create the bearer_token and store in a file in a secure local directory with 0600 permissions.

  • Define the asset:

    cat > /tmp/asset.json <<EOF
    {
      "behaviours": ["RecordEvidence"],
      "attributes": {
        "arc_display_type": "Cat",
        "arc_display_name": "My Cat",
        "weight": "3.6kg"
      },
      "public": false
    }
    EOF
    
  • Create the Asset:

    curl -X POST \
        -H "@$HOME/.datatrails/bearer-token.txt" \
        -H "Content-type: application/json" \
        -d "@/tmp/asset.json" \
        https://app.datatrails.ai/archivist/v2/assets \
        | jq
    

    The response:

    {
      "identity": "assets/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "behaviours": [
        "RecordEvidence",
        "AssetCreator",
        "Builtin"
      ],
      "attributes": {
        "arc_display_type": "Cat",
        "arc_display_name": "My Cat",
        "weight": "3.6kg"
      },
      "confirmation_status": "PENDING",
      "tracked": "TRACKED",
      "owner": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "at_time": "2024-09-04T23:35:13Z",
      "proof_mechanism": "MERKLE_LOG",
      "chain_id": "xxxxxxxxxx",
      "public": false,
      "tenant_identity": "tenant/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    }
    

Assets With a Primary Image

An Asset can have a primary image, displayed in the DataTrails Application. The image must first be uploaded with the Blobs API, with the BLOB_ID, BLOB_HASH and BLOB_FILE captured for uploading the asset.

  • Define the asset parameters, with the image information from the uploaded Blob:

    BLOB_ID=<blob-id>
    BLOB_FILE=file.jpg
    BLOB_HASH=<hash>
    
    cat > /tmp/asset.json <<EOF
    {
      "behaviours": ["RecordEvidence"],
      "attributes": {
        "arc_display_type": "Cat",
        "arc_display_name": "My Cat",
        "weight": "3.6kg",
        "arc_primary_image": {
          "arc_attribute_type": "arc_attachment",
          "arc_blob_identity": "blobs/$BLOB_ID",
          "arc_blob_hash_alg": "SHA256",
          "arc_blob_hash_value": "$BLOB_HASH",
          "arc_display_name": "arc_primary_image",
          "arc_file_name": "cat.jpeg"
        }
      },
      "public": false
    }
    EOF
    
  • Create the Asset With a Primary Image:

    curl -X POST \
        -H "@$HOME/.datatrails/bearer-token.txt" \
        -H "Content-type: application/json" \
        -d "@/tmp/asset.json" \
        https://app.datatrails.ai/archivist/v2/assets \
        | jq
    

    The response:

    {
      "identity": "assets/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "behaviours": [
        "RecordEvidence",
        "AssetCreator",
        "Builtin"
      ],
      "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": "yyyyyyyyyy",
      "at_time": "2025-01-28T21:58:34Z",
      "proof_mechanism": "MERKLE_LOG",
      "chain_id": "123456",
      "public": false,
      "tenant_identity": "tenant/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    }
    

Creating a Public Asset

Warning: Assets can only be made public at Asset creation and cannot be made private afterwards.

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 or the IAM Policies API Reference.

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.

All Public Assets are then given a read-only public URL that can be retrieved using Fetch a Public Asset’s 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.

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. 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, which allows you to trace the lifecycle of a document.

  • Define the asset:

    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":"xxxxxxxxxxxxxxxxxxxx",
            "document_hash_alg":"sha256",
            "document_version":"1",
            "document_status":"Published",
            "some_custom_attribute":"anything you like"
        },
        "behaviours": [
            "Builtin",
            "RecordEvidence"
        ],
        "public": true
    }
    EOF
    
    Note: Document Profile Assets must be set to public to be compatible with Instaproof verification.
  • Create the Asset:

    curl -X POST \
        -H "@$HOME/.datatrails/bearer-token.txt" \
        -H "Content-type: application/json" \
        -d "@/tmp/asset.json" \
        https://app.datatrails.ai/archivist/v2/assets \
        | jq
    

    The response is:

    {
        "identity": "assets/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "behaviours": [
            "Builtin",
            "RecordEvidence"
        ],
        "attributes": {
            "arc_profile": "Document",
            "document_version": "1",
            "some_custom_attribute": "anything you like",
            "document_status": "Published",
            "arc_description": "Test Document",
            "arc_display_type": "Marketing glossy",
            "document_hash_value": "xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
            "arc_display_name": "Test Document Profile Asset",
            "document_hash_alg": "sha256"
        },
        "confirmation_status": "STORED",
        "tracked": "TRACKED",
        "owner": "",
        "at_time": "2023-09-27T11:32:22Z",
        "chain_id": "8275868384",
        "public": false,
        "tenant_identity": ""
    }
    

Asset Record Retrieval

Asset records in DataTrails are tokenized at creation time and referred to in all API calls and smart contracts throughout the system by a unique identity of the form:

assets/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

If you do not know the Asset’s identity you can fetch Asset records using other information you do know.

Fetch All Assets

  • To fetch all Asset records, GET the Assets resource:

    curl -X GET \
        -H "@$HOME/.datatrails/bearer-token.txt" \
        https://app.datatrails.ai/archivist/v2/assets?page_size=5 \
        | jq
    

Fetch Specific Asset by Identity

  • If you know the unique identity of the Asset record GET the resource:

    curl -X GET \
        -H "@$HOME/.datatrails/bearer-token.txt" \
        https://app.datatrails.ai/archivist/v2/assets/$ASSET_ID \
        | jq
    

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:

    curl -X GET \
        -H "@$HOME/.datatrails/bearer-token.txt" \
        "https://app.datatrails.ai/archivist/v2/assets/$ASSET_ID?at_time=2021-01-13T12:34:21Z" \
        | jq
    

    This will return the Asset record with the values it had on 2021-01-13T12:34:21Z.

Fetch Assets by Name

  • To fetch all Assets with a specific name, GET the Assets resource and filter on arc_display_name:

    curl -g -X GET \
        -H "@$HOME/.datatrails/bearer-token.txt" \
        "https://app.datatrails.ai/archivist/v2/assets?attributes.arc_display_name=tcl.ccj.003" \
        | jq
    

Fetch Assets by Type

  • To fetch all Assets of a specific type, GET the Assets resource and filter on arc_display_type:

    curl -g -X GET \
        -H "@$HOME/.datatrails/bearer-token.txt" \
        "https://app.datatrails.ai/archivist/v2/assets?attributes.arc_display_type=Traffic%20light" \
        | jq
    

Fetch Assets by Proof Mechanism

  • To fetch all Assets that use a specific Proof Mechanism, GET the Assets resource and filter on proof_mechanism:

    curl -g -X GET \
        -H "@$HOME/.datatrails/bearer-token.txt" \
        "https://app.datatrails.ai/archivist/v2/assets?proof_mechanism=MERKLE_LOG&page_size=5" \
        | jq
    

Fetch Events Ordered for SIMPLEHASHV1 Schema

  • To fetch Simple Hash Events in the order needed for the SIMPLEHASHV1 schema, GET the Assets resource, specifying a specific Asset ID or using assets/-/events to fetch Events for all Assets:

    curl -g -X GET \
        -H "@$HOME/.datatrails/bearer-token.txt" \
        "https://app.datatrails.ai/archivist/v2/assets/-/events?order_by=SIMPLEHASHV1&page_size=5" \
        | jq
    

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.

    curl -g -X GET \
        -H "@$HOME/.datatrails/bearer-token.txt" \
        "https://app.datatrails.ai/archivist/v2/assets?attributes.arc_display_name=*&page_size=5" \
        | jq
    

    Returns all Assets which have arc_display_name that is not empty.

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.

    curl -g -X GET \
        -H "@$HOME/.datatrails/bearer-token.txt" \
        "https://app.datatrails.ai/archivist/v2/assets?attributes.arc_display_name!=*&page_size=5" \
        | jq
    

    Returns all Assets which do not have arc_display_name or in which arc_display_name is empty.

Fetch a Public Asset’s URL

  • Fetch the Public URL of a Public Asset:

    curl -g -X GET \
        -H "@$HOME/.datatrails/bearer-token.txt" \
        https://app.datatrails.ai/archivist/v2/assets/$ASSET_ID:publicurl \
        | jq
    

    The response:

    {
      "publicurl":"https://app.datatrails.ai/archivist/publicassets/xxxxxxxx"
    }
    

Fetch a Public Asset’s Event URL

  • Fetch the Public URL of an Event on a Public Asset:

    curl -g -X GET \
        -H "@$HOME/.datatrails/bearer-token.txt" \
        https://app.datatrails.ai/archivist/v2/assets/$ASSET_ID/events/$EVENT_ID:publicurl \
        | jq
    

    The response:

    {
      "publicurl":"https://app.datatrails.ai/archivist/publicassets/xxxx/events/xxxx"
    }
    

Tracking and Untracking Assets

While deleting Assets is not possible, it is possible to hide them from default searches so that old or obsolete records don’t crowd out the tenant estate or show up in partner tenancies when they shouldn’t.

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.

  • Define the Event attributes:

    cat > /tmp/event.json <<EOF
    {
      "operation": "StopTracking",
      "behaviour": "Builtin"
    }
    EOF
    
  • Untrack the Asset:

    curl -X POST \
        -H "@$HOME/.datatrails/bearer-token.txt" \
        -H "Content-type: application/json" \
        -d "@/tmp/event.json" \
        https://app.datatrails.ai/archivist/v2/assets/$ASSET_ID/events \
        | jq
    

    The response:

    {
      "identity": "assets/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/events/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "asset_identity": "assets/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "event_attributes": {},
      "asset_attributes": {},
      "operation": "StopTracking",
      "behaviour": "Builtin",
      "timestamp_declared": "2023-02-23T19:55:44Z",
      "timestamp_accepted": "2023-02-23T19:55:44Z",
      "timestamp_committed": "1970-01-01T00:00:00Z",
      "principal_declared": {
        "issuer": "idp.synsation.io/1234",
        "subject": "phil.b",
        "email": "phil.b@synsation.io"
      },
      "principal_accepted": {
        "issuer": "job.idp.server/1234",
        "subject": "bob@job"
      },
      "confirmation_status": "STORED",
      "transaction_id": "",
      "block_number": 0,
      "transaction_index": 0,
      "from": "",
      "tenant_identity": ""
    }
    

(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.

  • Define the Event attributes:

    cat > /tmp/event.json <<EOF
    {
      "operation": "StartTracking",
      "behaviour": "Builtin"
    }
    EOF
    
  • Track the Asset:

    curl -X POST \
        -H "@$HOME/.datatrails/bearer-token.txt" \
        -H "Content-type: application/json" \
        -d "@/tmp/event.json" \
        https://app.datatrails.ai/archivist/v2/assets/$ASSET_ID/events \
        | jq
    

    The response:

    {
      "identity": "assets/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/events/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "asset_identity": "assets/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "event_attributes": {},
      "asset_attributes": {},
      "operation": "StartTracking",
      "behaviour": "Builtin",
      "timestamp_declared": "2023-02-23T19:55:44Z",
      "timestamp_accepted": "2023-02-23T19:55:44Z",
      "timestamp_committed": "1970-01-01T00:00:00Z",
      "principal_declared": {
        "issuer": "idp.synsation.io/1234",
        "subject": "phil.b",
        "email": "phil.b@synsation.io"
      },
      "principal_accepted": {
        "issuer": "job.idp.server/1234",
        "subject": "bob@job"
      },
      "confirmation_status": "PENDING",
      "transaction_id": "",
      "block_number": 0,
      "transaction_index": 0,
      "from": "",
      "tenant_identity": ""
    }
    

Asset OpenAPI Docs

API for asset and event management.

get  /archivist/v2/assets

List Assets

Description: Retrieves a list of Assets

{
  "assets": [
    {
      "at_time": "2019-11-27T14:44:19Z",
      "attributes": {
        "arc_display_name": "My Garden Fence",
        "arc_display_type": "Garden Fence",
        "colour": "Plain wood"
      },
      "behaviours": [
        "RecordEvidence"
      ],
      "confirmation_status": "PENDING",
      "identity": "assets/add30235-1424-4fda-840a-d5ef82c4c96f",
      "owner": "0x601f5A7D3e6dcB55e87bf2F17bC8A27AaCD3511",
      "proof_mechanism": "MERKLE_LOG",
      "public": false,
      "tenant_identity": "tenant/8e0b600c-8234-43e4-860c-e95bdcd695a9",
      "tracked": "TRACKED"
    },
    {
      "at_time": "2019-11-27T14:44:19Z",
      "attributes": {
        "arc_display_name": "My IoT Device",
        "arc_display_type": "IoT Device",
        "arc_firmware_version": "3.2.1"
      },
      "behaviours": [
        "RecordEvidence"
      ],
      "confirmation_status": "PENDING",
      "identity": "assets/cef61346-2453-5aeb-921c-e6fa93d5b032",
      "owner": "0x601f5A7D3e6dcB55e87bf2F17bC8A27AaCD3511",
      "proof_mechanism": "MERKLE_LOG",
      "public": false,
      "tenant_identity": "tenant/8e0b600c-8234-43e4-860c-e95bdcd695a9",
      "tracked": "TRACKED"
    }
  ],
  "next_page_token": "abcd"
}
Response ParameterTypeDescription
assetsarrayThis describes an Asset.
next_page_tokenstringToken to retrieve the next page of results or empty if there are none.
ResponsesDescription
200A successful response.
206The number of assets exceeds the servers limit. The approximate number of matching results is provided by the x-total-count header if the ‘x-request-total-count’ header on the request is set to ’true’. The exact limit is available in the content-range header. The value format is ‘items 0-LIMIT/TOTAL’. Note that x-total-count is always present for 200 and 206 responses. It is the servers best available approximation. Similarly, in any result set, you may get a few more than LIMIT items.
401Returned when the user is not authenticated to the system.
403Returned when the user is not authorized to list Assets.
429Returned when a user exceeds their subscription’s rate limit for requests.

post  /archivist/v2/assets

Create an Asset

Description: Creates an Asset

{
  "attributes": {
    "arc_display_name": "My Garden Fence",
    "arc_display_type": "Garden Fence",
    "colour": "Plain wood"
  },
  "behaviours": [
    "RecordEvidence"
  ],
  "proof_mechanism": "MERKLE_LOG",
  "public": false
}
ParameterTypeDescription
attributesobjectkey value mapping of event attributes
behavioursarraylist of behaviours enabled for this asset
chain_idstringchain id of the blockchain associated with this asset
proof_mechanismstringspecify the mechanism used to provide evidential proof for Events on this Asset
publicbooleanPublic asset. A public asset and all its events are visible to the general public.Sharing to specific organisations is not available for public assets.

{
  "at_time": "2019-11-27T14:44:19Z",
  "attributes": {
    "arc_display_name": "My Garden Fence",
    "arc_display_type": "Garden Fence",
    "colour": "Plain wood"
  },
  "behaviours": [
    "RecordEvidence"
  ],
  "confirmation_status": "PENDING",
  "identity": "assets/add30235-1424-4fda-840a-d5ef82c4c96f",
  "owner": "0x601f5A7D3e6dcB55e87bf2F17bC8A27AaCD3511",
  "proof_mechanism": "MERKLE_LOG",
  "public": false,
  "tenant_identity": "tenant/8e0b600c-8234-43e4-860c-e95bdcd695a9",
  "tracked": "TRACKED"
}
Response ParameterTypeDescription
at_timestringindicates time the asset data is from
attributesobjectkey value mapping of asset properties
behavioursarraylist of behaviours enabled for this asset
chain_idstringchain id of the blockchain associated with this asset
confirmation_statusstringindicates if the asset has been succesfully committed to the blockchain
identitystringrelative resource address assets/{UUID}
ownerstringwallet address of the asset owner
proof_mechanismstringthe mechanism used to provide evidential proof
publicbooleanPublic asset
tenant_identitystringIdentity of the tenant the that created this asset
trackedstringindicates whether asset is still being tracked in the system
ResponsesDescription
200A successful response.
401Returned when the user is not authenticated to the system.
402Returned when the number of assets would exceed the user’s quota
403Returned when the user is not authorized to create an Asset.
429Returned when a user exceeds their subscription’s rate limit for requests.

get  /archivist/v2/assets/{asset_uuid}/events/{uuid}

Retrieves Event

Description: Retrieves a specific Event

{
  "asset_attributes": {
    "colour": "Midnight Blue"
  },
  "asset_identity": "assets/add30235-1424-4fda-840a-d5ef82c4c96f",
  "behaviour": "RecordEvidence",
  "block_number": 12,
  "confirmation_status": "CONFIRMED",
  "event_attributes": {
    "arc_description": "Painted the fence",
    "arc_display_type": "Paint"
  },
  "identity": "assets/add30235-1424-4fda-840a-d5ef82c4c96f/events/11bf5b37-e0b8-42e0-8dcf-dc8c4aefc000",
  "operation": "Record",
  "principal_accepted": {
    "issuer": "job.idp.server/1234",
    "subject": "bob@job"
  },
  "principal_declared": {
    "issuer": "job.idp.server/1234",
    "subject": "bob@job"
  },
  "tenant_identity": "tenant/8e0b600c-8234-43e4-860c-e95bdcd695a9",
  "timestamp_accepted": "2019-11-27T14:44:19Z",
  "timestamp_committed": "2019-11-27T14:44:19Z",
  "timestamp_declared": "2019-11-27T14:44:19Z",
  "transaction_id": "0x07569",
  "transaction_index": 5
}
Response ParameterTypeDescription
asset_attributesobjectkey value mapping of asset attributes
asset_identitystringidentity of a related asset resource assets/11bf5b37-e0b8-42e0-8dcf-dc8c4aefc000
behaviourstringThe behaviour used to create event. RecordEvidence
block_numberstringnumber of block event was commited on
confirmation_statusstringindicates if the event has been succesfully committed to the blockchain
event_attributesobjectkey value mapping of event attributes
fromstringwallet address for the creator of this event
identitystringidentity of a event resource
merklelog_entryobjectverifiable merkle mmr log entry details
operationstringThe operation represented by the event. Record
principal_acceptedobjectprincipal recorded by the server
principal_declaredobjectprincipal provided by the user
tenant_identitystringIdentity of the tenant the that created this event
timestamp_acceptedstringtime of event as recorded by the server
timestamp_committedstringtime of event as recorded in verifiable storage
timestamp_declaredstringtime of event as declared by the user
transaction_idstringhash of the transaction as a hex string 0x11bf5b37e0b842e08dcfdc8c4aefc000
transaction_indexstringindex of event within commited block
ResponsesDescription
200A successful response.
401Returned when the user is not authenticated to the system.
403Returned when the user is not authorized to view Event.
404Returned when the event does not exist.
429Returned when a user exceeds their subscription’s rate limit for requests.

get  /archivist/v2/assets/{asset_uuid}/events/{uuid}:publicurl

Retrieves the public url for a specific Event.

Description: Retrieves the public url for a specific Event.

{
  "publicurl": "https://app.datatrails.ai/archivist/v2/publicassets/add30235-1424-4fda-840a-d5ef82c4c96f/events/11bf5b37-e0b8-42e0-8dcf-dc8c4aefc000"
}
Response ParameterTypeDescription
publicurlstring
ResponsesDescription
200A successful response.
401Returned when the user is not authenticated to the system.
403Returned when the user is not authorized to view an Asset.
404Returned when the asset with the id does not exist.
429Returned when a user exceeds their subscription’s rate limit for requests.

get  /archivist/v2/assets/{uuid}

Retrieves a specific Asset

Description: Retrieves a specific Asset

{
  "at_time": "2019-11-27T14:44:19Z",
  "attributes": {
    "arc_display_name": "My Garden Fence",
    "arc_display_type": "Garden Fence",
    "colour": "Plain wood"
  },
  "behaviours": [
    "RecordEvidence"
  ],
  "confirmation_status": "PENDING",
  "identity": "assets/add30235-1424-4fda-840a-d5ef82c4c96f",
  "owner": "0x601f5A7D3e6dcB55e87bf2F17bC8A27AaCD3511",
  "proof_mechanism": "MERKLE_LOG",
  "public": false,
  "tenant_identity": "tenant/8e0b600c-8234-43e4-860c-e95bdcd695a9",
  "tracked": "TRACKED"
}
Response ParameterTypeDescription
at_timestringindicates time the asset data is from
attributesobjectkey value mapping of asset properties
behavioursarraylist of behaviours enabled for this asset
chain_idstringchain id of the blockchain associated with this asset
confirmation_statusstringindicates if the asset has been succesfully committed to the blockchain
identitystringrelative resource address assets/{UUID}
ownerstringwallet address of the asset owner
proof_mechanismstringthe mechanism used to provide evidential proof
publicbooleanPublic asset
tenant_identitystringIdentity of the tenant the that created this asset
trackedstringindicates whether asset is still being tracked in the system
ResponsesDescription
200A successful response.
401Returned when the user is not authenticated to the system.
403Returned when the user is not authorized to view an Asset.
404Returned when the asset with the id does not exist.
429Returned when a user exceeds their subscription’s rate limit for requests.

get  /archivist/v2/assets/{uuid}/events

List Events

Description: Lists Events

{
  "events": [
    {
      "asset_attributes": {
        "colour": "Midnight Blue"
      },
      "asset_identity": "assets/add30235-1424-4fda-840a-d5ef82c4c96f",
      "behaviour": "RecordEvidence",
      "block_number": 12,
      "confirmation_status": "CONFIRMED",
      "event_attributes": {
        "arc_description": "Painted the fence",
        "arc_display_type": "Paint"
      },
      "identity": "assets/add30235-1424-4fda-840a-d5ef82c4c96f/events/11bf5b37-e0b8-42e0-8dcf-dc8c4aefc000",
      "operation": "Record",
      "principal_accepted": {
        "issuer": "job.idp.server/1234",
        "subject": "bob@job"
      },
      "principal_declared": {
        "issuer": "job.idp.server/1234",
        "subject": "bob@job"
      },
      "tenant_identity": "tenant/8e0b600c-8234-43e4-860c-e95bdcd695a9",
      "timestamp_accepted": "2019-11-27T14:44:19Z",
      "timestamp_committed": "2019-11-27T14:44:19Z",
      "timestamp_declared": "2019-11-27T14:44:19Z",
      "transaction_id": "0x07569",
      "transaction_index": 5
    },
    {
      "asset_attributes": {
        "arc_firmware_version": "3.2.1"
      },
      "asset_identity": "assets/bf330235-1424-4fda-840a-d5ef82c4c96f",
      "behaviour": "RecordEvidence",
      "block_number": 13,
      "confirmation_status": "CONFIRMED",
      "event_attributes": {
        "arc_display_type": "Update Firmware"
      },
      "identity": "assets/bf330235-1424-4fda-840a-d5ef82c4c96f/events/23c06c48-e0b8-42e0-8dcf-dc8c4fdad123",
      "operation": "Record",
      "principal_accepted": {
        "issuer": "job.idp.server/1234",
        "subject": "bob@job"
      },
      "principal_declared": {
        "issuer": "job.idp.server/1234",
        "subject": "bob@job"
      },
      "tenant_identity": "tenant/8e0b600c-8234-43e4-860c-e95bdcd695a9",
      "timestamp_accepted": "2019-07-27T14:44:19Z",
      "timestamp_committed": "2019-07-27T14:44:19Z",
      "timestamp_declared": "2019-07-27T14:44:19Z",
      "transaction_id": "0x12569",
      "transaction_index": 6
    }
  ],
  "next_page_token": "abcd"
}
Response ParameterTypeDescription
eventsarrayThis describes an Event.
next_page_tokenstringToken to retrieve the next page of results or empty if there are none.
ResponsesDescription
200A successful response.
206The number of events exceeds the servers limit. The approximate number of matching results is provided by the x-total-count header, the exact limit is available in the content-range header. The value format is ‘items 0-LIMIT/TOTAL’. Note that x-total-count is always present for 200 and 206 responses. It is the servers best available approximation. Similarly, in any result set, you may get a few more than LIMIT items.
401Returned when the user is not authenticated to the system.
403Returned when the user is not authorized to list Events.
429Returned when a user exceeds their subscription’s rate limit for requests.

post  /archivist/v2/assets/{uuid}/events

Creates an Event

Description: Creates an Event

{
  "asset_attributes": {
    "colour": "Midnight Blue"
  },
  "behaviour": "RecordEvidence",
  "event_attributes": {
    "arc_description": "Painted the fence",
    "arc_display_type": "Paint"
  },
  "operation": "Record"
}
ParameterTypeDescription
asset_attributesobjectkey value mapping of asset attributes
behaviourstring
event_attributesobjectkey value mapping of event attributes
operationstring
principal_declared
timestamp_declaredstringtime of event as declared by the user

{
  "asset_attributes": {
    "colour": "Midnight Blue"
  },
  "asset_identity": "assets/add30235-1424-4fda-840a-d5ef82c4c96f",
  "behaviour": "RecordEvidence",
  "block_number": 12,
  "confirmation_status": "CONFIRMED",
  "event_attributes": {
    "arc_description": "Painted the fence",
    "arc_display_type": "Paint"
  },
  "identity": "assets/add30235-1424-4fda-840a-d5ef82c4c96f/events/11bf5b37-e0b8-42e0-8dcf-dc8c4aefc000",
  "operation": "Record",
  "principal_accepted": {
    "issuer": "job.idp.server/1234",
    "subject": "bob@job"
  },
  "principal_declared": {
    "issuer": "job.idp.server/1234",
    "subject": "bob@job"
  },
  "tenant_identity": "tenant/8e0b600c-8234-43e4-860c-e95bdcd695a9",
  "timestamp_accepted": "2019-11-27T14:44:19Z",
  "timestamp_committed": "2019-11-27T14:44:19Z",
  "timestamp_declared": "2019-11-27T14:44:19Z",
  "transaction_id": "0x07569",
  "transaction_index": 5
}
Response ParameterTypeDescription
asset_attributesobjectkey value mapping of asset attributes
asset_identitystringidentity of a related asset resource assets/11bf5b37-e0b8-42e0-8dcf-dc8c4aefc000
behaviourstringThe behaviour used to create event. RecordEvidence
block_numberstringnumber of block event was commited on
confirmation_statusstringindicates if the event has been succesfully committed to the blockchain
event_attributesobjectkey value mapping of event attributes
fromstringwallet address for the creator of this event
identitystringidentity of a event resource
merklelog_entryobjectverifiable merkle mmr log entry details
operationstringThe operation represented by the event. Record
principal_acceptedobjectprincipal recorded by the server
principal_declaredobjectprincipal provided by the user
tenant_identitystringIdentity of the tenant the that created this event
timestamp_acceptedstringtime of event as recorded by the server
timestamp_committedstringtime of event as recorded in verifiable storage
timestamp_declaredstringtime of event as declared by the user
transaction_idstringhash of the transaction as a hex string 0x11bf5b37e0b842e08dcfdc8c4aefc000
transaction_indexstringindex of event within commited block
ResponsesDescription
200A successful response.
401Returned when the user is not authenticated to the system.
402Returned when the user’s quota of Events has been reached.
429Returned when a user exceeds their subscription’s rate limit for requests.

get  /archivist/v2/assets/{uuid}:publicurl

Retrieves the public url for a specific Asset.

Description: Retrieves the public url for a specific Asset.

{
  "publicurl": "https://app.datatrails.ai/archivist/v2/publicassets/add30235-1424-4fda-840a-d5ef82c4c96f"
}
Response ParameterTypeDescription
publicurlstring
ResponsesDescription
200A successful response.
401Returned when the user is not authenticated to the system.
403Returned when the user is not authorized to view an Asset.
404Returned when the asset with the id does not exist.
429Returned when a user exceeds their subscription’s rate limit for requests.