Events API (preview)

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

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.

Event Creation#

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

• Define the Event parameters and store in /tmp/event.json:

  cat > /tmp/event.json <<EOF
  {
    "trails": ["Safety Conformance", "Clouseau"],
    "attributes": {
      "arc_display_type": "Safety Conformance",
      "Safety Rating": "90",
      "inspector": "Clouseau"
    }
  }
  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/v1/events \
      | jq
  

• The response:

  {
    "identity": "events/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "attributes": {
      "inspector": "Clouseau",
      "arc_display_type": "Safety Conformance",
      "Safety Rating": "90"
    },
    "trails": [
      "Safety Conformance",
      "Clouseau"
    ],
    "origin_tenant": "tenant/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "created_by": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "created_at": 1736421833577,
    "confirmation_status": "STORED",
    "merklelog_commit": {
      "index": "0",
      "idtimestamp": ""
    }
  }
  

Event Record Retrieval#

Event records in DataTrails are assigned UUIDs at creation time and referred to in all future API calls by a their unique identity in the format: events/<event-id>

Note: The current preview limits fetching Events to the Event identity. Querying across event attributes and trails are coming in a future preview.

Fetch Events by Identity#

• Replace the <event-id> below, using the event-id from the created event above: "identity": "events/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx":

  EVENT_ID=<event-id>
  

• Query the /events API to retrieve the recorded event:

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

Events OpenAPI Docs#

{
  "attributes": {
    "fab": "baz",
    "foo": "bar"
  },
  "trails": [
    "bar",
    "boo"
  ]
}

{
  "attributes": {
    "fab": "baz",
    "foo": "bar"
  },
  "confirmation_status": "STORED",
  "created_at": 1730283341,
  "created_by": "members/77d373d6-c646-4ccc-b932-53b5d4d0ffda",
  "identity": "events/08838336-c357-460d-902a-3aba9528dd22",
  "origin_tenant": "tenant/47369fd0-c9da-4ea9-8f0a-d8a56787441b",
  "trails": [
    "bar",
    "boo"
  ]
}

{
  "attributes": {
    "fab": "baz",
    "foo": "bar"
  },
  "confirmation_status": "STORED",
  "created_at": 1730283341,
  "created_by": "members/77d373d6-c646-4ccc-b932-53b5d4d0ffda",
  "identity": "events/08838336-c357-460d-902a-3aba9528dd22",
  "origin_tenant": "tenant/47369fd0-c9da-4ea9-8f0a-d8a56787441b",
  "trails": [
    "bar",
    "boo"
  ]
}

Integrity Protecting Content#

Integrity protected content can be hashed within an Event using the Attachments API.