Asset-Events API

Asset based Events API Reference

DataTrails provides two mechanisms for persisting provenance metadata:

Asset based Events (this API): where a series of Events are grounded to a specific Asset.
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/$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

DataTrails Reserved Attributes

The DataTrails platform has reserved attributes starting with arc_ to perform specific capabilities. See Reserved Attributes for more info.

Asset-Event Primary Image

Asset-Events can use the Blobs API to associate a primary image in the DataTrails Application.

Primary Image Variables

To associate an existing Blob, set the BLOB_ID, BLOB_HASH value and BLOB_FILE from the Blobs API:
NOTE: The ASSET_ID dependency will be removed with Non-asset based Events (preview)
```
ASSET_ID=<asset-id>
BLOB_ID=<blob-id>
BLOB_FILE=<file.ext>
BLOB_HASH=<hash-value>
```
Example:
ASSET_ID=assets/a1234567-890a
BLOB_ID=blobs/b1234567-890b
BLOB_FILE=conformance.pdf
BLOB_HASH=h1234567hh

Associate a Blob as the Event Primary Image:

cat > /tmp/event.json <<EOF
{
  "operation": "Record",
  "behaviour": "RecordEvidence",
  "event_attributes": {
    "arc_primary_image": {
      "arc_attribute_type": "arc_attachment",
      "arc_display_name": "arc_primary_image",
      "arc_blob_identity": "$BLOB_ID",
      "arc_blob_hash_alg": "SHA256",
      "arc_blob_hash_value": "$BLOB_HASH",
      "arc_file_name": "$BLOB_FILE"
    }
  }
}
EOF

POST the Event Primary Image:

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

Adding Attachments

To associate an Attachment with an Asset-Event, see the Attachments API

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/$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/$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": ""
}

Asset Event Record Retrieval

Asset 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/a1234567-890a/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 Asset Events

To fetch all Asset 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 Asset 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/$ASSET_ID/events?page_size=5" \
    | jq

Fetch Specific Asset 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/$ASSET_ID/events/$EVENT_ID" \
    | jq

Fetch Asset Event by Type

To fetch all Asset 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 Asset Event by Asset Attribute

To fetch all Asset 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 Asset Events by Filtering for Presence of an Attribute

To fetch all Asset Events with an Attribute set to any value, GET the Asset-Events resource and filter on most available attributes.

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 Asset Events Which are Missing a Field

To fetch all Asset Events with a field which is not set to any value, GET the Events resource and filter on most available fields.
```
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 Asset Events which do not have arc_display_type or in which arc_display_type is empty.

Fetch Asset Events by Minimum Confirmation Status

To fetch all Asset 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 Asset 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 Asset 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 Parameter	Type	Description
assets	array	This describes an Asset.
next_page_token	string	Token to retrieve the next page of results or empty if there are none.

Responses	Description
200	A successful response.
206	The 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.
401	Returned when the user is not authenticated to the system.
403	Returned when the user is not authorized to list Assets.
429	Returned 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
}

Parameter	Type	Description
attributes	object	key value mapping of event attributes
behaviours	array	list of behaviours enabled for this asset
chain_id	string	chain id of the blockchain associated with this asset
proof_mechanism	string	specify the mechanism used to provide evidential proof for Events on this Asset
public	boolean	Public 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 Parameter	Type	Description
at_time	string	indicates time the asset data is from
attributes	object	key value mapping of asset properties
behaviours	array	list of behaviours enabled for this asset
chain_id	string	chain id of the blockchain associated with this asset
confirmation_status	string	indicates if the asset has been succesfully committed to the blockchain
identity	string	relative resource address `assets/{UUID}`
owner	string	wallet address of the asset owner
proof_mechanism	string	the mechanism used to provide evidential proof
public	boolean	Public asset
tenant_identity	string	Identity of the tenant the that created this asset
tracked	string	indicates whether asset is still being tracked in the system

Responses	Description
200	A successful response.
401	Returned when the user is not authenticated to the system.
402	Returned when the number of assets would exceed the user’s quota
403	Returned when the user is not authorized to create an Asset.
429	Returned 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 Parameter	Type	Description
asset_attributes	object	key value mapping of asset attributes
asset_identity	string	identity of a related asset resource `assets/11bf5b37-e0b8-42e0-8dcf-dc8c4aefc000`
behaviour	string	The behaviour used to create event. `RecordEvidence`
block_number	string	number of block event was commited on
confirmation_status	string	indicates if the event has been succesfully committed to the blockchain
event_attributes	object	key value mapping of event attributes
from	string	wallet address for the creator of this event
identity	string	identity of a event resource
merklelog_entry	object	verifiable merkle mmr log entry details
operation	string	The operation represented by the event. `Record`
principal_accepted	object	principal recorded by the server
principal_declared	object	principal provided by the user
tenant_identity	string	Identity of the tenant the that created this event
timestamp_accepted	string	time of event as recorded by the server
timestamp_committed	string	time of event as recorded in verifiable storage
timestamp_declared	string	time of event as declared by the user
transaction_id	string	hash of the transaction as a hex string `0x11bf5b37e0b842e08dcfdc8c4aefc000`
transaction_index	string	index of event within commited block

Responses	Description
200	A successful response.
401	Returned when the user is not authenticated to the system.
403	Returned when the user is not authorized to view Event.
404	Returned when the event does not exist.
429	Returned 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 Parameter	Type	Description
publicurl	string

Responses	Description
200	A successful response.
401	Returned when the user is not authenticated to the system.
403	Returned when the user is not authorized to view an Asset.
404	Returned when the asset with the id does not exist.
429	Returned 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 Parameter	Type	Description
at_time	string	indicates time the asset data is from
attributes	object	key value mapping of asset properties
behaviours	array	list of behaviours enabled for this asset
chain_id	string	chain id of the blockchain associated with this asset
confirmation_status	string	indicates if the asset has been succesfully committed to the blockchain
identity	string	relative resource address `assets/{UUID}`
owner	string	wallet address of the asset owner
proof_mechanism	string	the mechanism used to provide evidential proof
public	boolean	Public asset
tenant_identity	string	Identity of the tenant the that created this asset
tracked	string	indicates whether asset is still being tracked in the system

Responses	Description
200	A successful response.
401	Returned when the user is not authenticated to the system.
403	Returned when the user is not authorized to view an Asset.
404	Returned when the asset with the id does not exist.
429	Returned 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 Parameter	Type	Description
events	array	This describes an Event.
next_page_token	string	Token to retrieve the next page of results or empty if there are none.

Responses	Description
200	A successful response.
206	The 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.
401	Returned when the user is not authenticated to the system.
403	Returned when the user is not authorized to list Events.
429	Returned 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"
}

Parameter	Type	Description
asset_attributes	object	key value mapping of asset attributes
behaviour	string
event_attributes	object	key value mapping of event attributes
operation	string
principal_declared
timestamp_declared	string	time 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 Parameter	Type	Description
asset_attributes	object	key value mapping of asset attributes
asset_identity	string	identity of a related asset resource `assets/11bf5b37-e0b8-42e0-8dcf-dc8c4aefc000`
behaviour	string	The behaviour used to create event. `RecordEvidence`
block_number	string	number of block event was commited on
confirmation_status	string	indicates if the event has been succesfully committed to the blockchain
event_attributes	object	key value mapping of event attributes
from	string	wallet address for the creator of this event
identity	string	identity of a event resource
merklelog_entry	object	verifiable merkle mmr log entry details
operation	string	The operation represented by the event. `Record`
principal_accepted	object	principal recorded by the server
principal_declared	object	principal provided by the user
tenant_identity	string	Identity of the tenant the that created this event
timestamp_accepted	string	time of event as recorded by the server
timestamp_committed	string	time of event as recorded in verifiable storage
timestamp_declared	string	time of event as declared by the user
transaction_id	string	hash of the transaction as a hex string `0x11bf5b37e0b842e08dcfdc8c4aefc000`
transaction_index	string	index of event within commited block

Responses	Description
200	A successful response.
401	Returned when the user is not authenticated to the system.
402	Returned when the user’s quota of Events has been reached.
429	Returned 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 Parameter	Type	Description
publicurl	string

Responses	Description
200	A successful response.
401	Returned when the user is not authenticated to the system.
403	Returned when the user is not authorized to view an Asset.
404	Returned when the asset with the id does not exist.
429	Returned when a user exceeds their subscription’s rate limit for requests.

Asset-Events API

Asset-Events API Examples#

Asset Reference#

Event Creation#

DataTrails Reserved Attributes#

Asset-Event Primary Image#

Primary Image Variables#

Adding Attachments#

Document Profile Event Creation#

Publish#

Withdraw#

Asset Event Record Retrieval#

Fetch All Asset Events#

Fetch Asset Events for a Specific Asset#

Fetch Specific Asset Events by Identity#

Fetch Asset Event by Type#

Fetch Asset Event by Asset Attribute#

Fetch Asset Events by Filtering for Presence of an Attribute#

Fetch Asset Events Which are Missing a Field#

Fetch Asset Events by Minimum Confirmation Status#

Events OpenAPI Docs#

get /archivist/v2/assets

get /archivist/v2/assets

List Assets

Example Response

post /archivist/v2/assets

post /archivist/v2/assets

Create an Asset

Example Request

Example Response

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

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

Retrieves Event

Example Response

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

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

Retrieves the public url for a specific Event.

Example Response

get /archivist/v2/assets/{uuid}

get /archivist/v2/assets/{uuid}

Retrieves a specific Asset

Example Response

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

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

List Events

Example Response

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

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

Creates an Event

Example Request

Example Response

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

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

Retrieves the public url for a specific Asset.

Example Response

Asset-Events API Examples

Asset Reference

Event Creation

DataTrails Reserved Attributes

Asset-Event Primary Image

Primary Image Variables

Adding Attachments

Document Profile Event Creation

Publish

Withdraw

Asset Event Record Retrieval

Fetch All Asset Events

Fetch Asset Events for a Specific Asset

Fetch Specific Asset Events by Identity

Fetch Asset Event by Type

Fetch Asset Event by Asset Attribute

Fetch Asset Events by Filtering for Presence of an Attribute

Fetch Asset Events Which are Missing a Field

Fetch Asset Events by Minimum Confirmation Status

Events OpenAPI Docs