DataTrails

Asset-Events API

Asset based Events API Reference

DataTrails provides two mechanisms for persisting provenance metadata:

  1. Asset based Events (this API): 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-Events 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.

Note: You will need to create an Asset first in order to submit Events against it. The dependency on Assets is being deprecated. In a future release, Events will be created independently from Assets.

Asset Reference

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

  • Capture the Asset ID by which the events will be associated.
    (eg: ASSET_ID=01234567-890-1234-5678-901234567890)
    Find the ASSET_ID with Fetch All Assets

    ASSET_ID=<asset-id>
Note: DataTrails will be transitioning to an event centric design, removing the need to create and reference Assets to hold collections of Events.

Event Creation

  • Define the Event parameters:

    cat > /tmp/event.json <<EOF
{
  "operation": "Record",
  "behaviour": "RecordEvidence",
  "event_attributes": {
    "arc_display_type": "Safety Conformance",
    "Safety Rating": "90",
    "inspector": "Clouseau"
  }
}
EOF
Note: RecordEvidence is the primary, default behavior for creating Events.

  • Add the request to the Asset record by POSTing it to the resource:

    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": {
    "inspector": "Clouseau",
    "arc_display_type": "Safety Conformance",
    "Safety Rating": "90"
  },
  "asset_attributes": {},
  "operation": "Record",
  "behaviour": "RecordEvidence",
  "timestamp_declared": "2024-09-04T23:45:20Z",
  "timestamp_accepted": "2024-09-04T23:45:20Z",
  "timestamp_committed": "1970-01-01T00:00:00Z",
  "principal_declared": {
    "issuer": "https://app.datatrails.ai/appidpv1",
    "subject": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "display_name": "my-integration",
    "email": ""
  },
  "principal_accepted": {
    "issuer": "https://app.datatrails.ai/appidpv1",
    "subject": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "display_name": "my-integration",
    "email": ""
  },
  "confirmation_status": "PENDING",
  "transaction_id": "",
  "block_number": 0,
  "transaction_index": 0,
  "from": "",
  "tenant_identity": "",
  "merklelog_entry": {
    "commit": null,
    "confirm": null,
    "unequivocal": null
  }
}

  • To query the events jump to Fetch Specific Events by Identity

Document Profile Event Creation

There are two Document Profile Events that are available as part of the document lifecycle. These are to publish a new version and to withdraw the document from use.

Publish

  • Define the Event parameters:

    cat > /tmp/event.json <<EOF
{
  "behaviour": "RecordEvidence",
  "operation": "Record",
  "asset_attributes": {
    "document_hash_value":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "document_hash_alg":"sha256",
    "document_status": "Published",
    "document_version":"2"
  },
  "event_attributes": {
    "arc_description":"Publish version 2 of Test Document",
    "arc_display_type":"Publish",
    "document_version_authors": [
      {
        "display_name": "George",
        "email": "george@rainbow.tv"
      },
      {
        "display_name": "Zippy",
        "email": "zippy@rainbow.tv"
      },
      {
        "display_name": "Bungle",
        "email": "bungle@rainbow.tv"
      }
    ]
  }
}
EOF

  • Add the request to the Asset record by POSTing it to the resource:

    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/events/xxxxxxxx-xxxx",
    "asset_identity": "assets/xxxxxxxx-xxxx",
    "event_attributes": {
      "document_version_authors": [
        {
          "display_name": "George",
          "email": "george@rainbow.tv"
        },
        {
          "display_name": "Zippy",
          "email": "zippy@rainbow.tv"
        },
        {
          "display_name": "Bungle",
          "email": "bungle@rainbow.tv"
        }
      ],
      "arc_description": "Publish version 2 of Test Document",
      "arc_display_type": "Publish"
    },
    "asset_attributes": {
      "document_status": "Published",
      "document_version": "2",
      "document_hash_value": "xxxxxxxxxxxxxxxxxxxxx",
      "document_hash_alg": "sha256"
    },
    "operation": "Record",
    "behaviour": "RecordEvidence",
    "timestamp_declared": "2023-09-27T12:55:16Z",
    "timestamp_accepted": "2023-09-27T12:55:16Z",
    "timestamp_committed": "1970-01-01T00:00:00Z",
    "principal_declared": {
      "issuer": "https://app.datatrails.ai/appidpv1",
      "subject": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "display_name": "CustomIntegration",
      "email": ""
    },
    "principal_accepted": {
      "issuer": "https://app.datatrails.ai/appidpv1",
      "subject": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "display_name": "CustomIntegration",
      "email": ""
    },
    "confirmation_status": "PENDING",
    "transaction_id": "",
    "block_number": 0,
    "transaction_index": 0,
    "from": "",
    "tenant_identity": ""
}

Withdraw

  • Define the Event parameters:

    cat > /tmp/event.json <<EOF
{
  "behaviour": "RecordEvidence",
  "operation": "Record",
  "asset_attributes": {
    "document_status":"Withdrawn"
  },
  "event_attributes": {
    "arc_description":"Withdraw the Test Document",
    "arc_display_type":"Withdraw"
  }
}
EOF

  • Add the request to the Asset record by POSTing it to the resource:

    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": {
      "arc_description": "Withdraw the Test Document",
      "arc_display_type": "Withdraw"
    },
    "asset_attributes": {
      "document_status": "Withdrawn"
    },
    "operation": "Record",
    "behaviour": "RecordEvidence",
    "timestamp_declared": "2023-09-27T13:08:32Z",
    "timestamp_accepted": "2023-09-27T13:08:32Z",
    "timestamp_committed": "1970-01-01T00:00:00Z",
    "principal_declared": {
      "issuer": "https://app.datatrails.ai/appidpv1",
      "subject": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "display_name": "CustomIntegration",
      "email": ""
    },
    "principal_accepted": {
      "issuer": "https://app.datatrails.ai/appidpv1",
      "subject": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "display_name": "CustomIntegration",
      "email": ""
    },
    "confirmation_status": "PENDING",
    "transaction_id": "",
    "block_number": 0,
    "transaction_index": 0,
    "from": "",
    "tenant_identity": ""
}

Adding Attachments

The following assumes that an attachment has already been uploaded to DataTrails using the Blob API.

This attachment uuid is generically referred to as:

blobs/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Each attachment has an associated hash value and the name of the hash algorithm used that you can also get from the Blob API response.

  • After uploading the content, use the "arc_attribute_type": "arc_attachment" key-value pair within a dictionary of blob information to add the attachment to the Event.

    cat > /tmp/event.json <<EOF
{
  "operation": "Record",
  "behaviour": "RecordEvidence",
  "event_attributes": {
    "arc_display_type": "Safety Conformance",
    "arc_description": "Safety conformance approved for version 1.6. See attached conformance report",
    "arc_evidence": "DVA Conformance Report attached",
    "conformance_report": {
      "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": "safety_conformance.pdf",
      "arc_display_name": "Conformance Report"
    },
    "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": "photo.jpg",
      "arc_display_name": "arc_primary_image"
    }
  },
  "timestamp_declared": "2019-11-27T14:44:19Z",
  "principal_declared": {
    "issuer": "idp.synsation.io/1234",
    "subject": "phil.b",
    "email": "phil.b@synsation.io"
  }
}
EOF

  • Add the request to the Asset Record by POSTing it to the resource:

    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",
  "operation": "Record",
  "behaviour": "RecordEvidence",
  "event_attributes": {
    "arc_display_type": "Safety Conformance",
    "arc_description": "Safety conformance approved for version 1.6. See attached conformance report",
    "arc_evidence": "DVA Conformance Report attached",
    "conformance_report": {
      "arc_attribute_type": "arc_attachment",
      "arc_blob_hash_value": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "arc_blob_identity": "blobs/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "arc_blob_hash_alg": "SHA256",
      "arc_file_name": "safety_conformance.pdf",
      "arc_display_name": "Conformance Report",
    },
    "arc_primary_image": {
      "arc_attribute_type": "arc_attachment",
      "arc_blob_hash_value": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "arc_blob_identity": "blobs/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "arc_blob_hash_alg": "SHA256",
      "arc_file_name": "safety_conformance.pdf",
      "arc_display_name": "Conformance Report",
    },
  },
  "timestamp_accepted": "2019-11-27T15:13:21Z",
  "timestamp_declared": "2019-11-27T14:44:19Z",
  "timestamp_committed": "2019-11-27T15:15:02Z",
  "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": "COMMITTED",
  "block_number": 12,
  "transaction_index": 5,
  "transaction_id": "0x07569"
}

Event Record Retrieval

Event records in DataTrails are tokenized at creation time and referred to in all future API calls by a permanent unique identity of the form:

assets/$ASSET_ID/events/$EVENT_ID

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

Fetch All Events

  • To fetch all Event records, simply GET the Events resources:

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

Fetch Events for a Specific Asset

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

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

Fetch Specific Events by Identity

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

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

Fetch Event by Type

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

    curl -g -X GET \
    -H "@$HOME/.datatrails/bearer-token.txt" \
    "https://app.datatrails.ai/archivist/v2/assets/-/events?event_attributes.arc_display_type=Software%20Package%20Release&page_size=5" \
    | jq

Fetch Event by Asset Attribute

  • To fetch all Events of a specific Asset attribute, GET the Events resource and filter on asset_attributes at the Asset level:

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

Fetch Events by Filtering for Presence of a Field

  • To fetch all Events with a field set to any value, GET the Events resource and filter on most available fields. For example:

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

    Returns all Events which have arc_display_type that is not empty.

Fetch Events Which are Missing a Field

  • To fetch all Events with a field which is not set to any value, GET the Events resource and filter on most available fields. For example:

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

    Returns all Events which do not have arc_display_type or in which arc_display_type is empty.

Fetch Events by Minimum Confirmation Status

  • To fetch all Events with a specified confirmation status or higher, GET the Events resource and filter on minimum_trust.

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

  • To fetch all Events which have a confirmation_status level of COMMITTED, CONFIRMED or UNEQUIVOCAL.

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

    Returns all Events which have a confirmation_status level of CONFIRMED or UNEQUIVOCAL.

Events 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.
402Returned when the user’s quota of Assets for the given proof mechanism has been reached.
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 user either has not enabled blockchain storage orthe 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 an 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 Event public url

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 an 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 server’s 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 Asset public url

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.

← Assets API
Attachments API →