Attachments API

Attachments API Reference

Note: This page is primarily intended for developers who will be writing applications that will use DataTrails for provenance. If you are looking for a simple way to test our API you might prefer our 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.

Attachment API Examples

The Attachments API enables you to query Binary Large OBjects (BLOBs) such as documents, process artifacts and images that are attached to your evidence ledger. For details of how to actually attach these BLOBs to Events and Assets, see the the Events API Reference.

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

Retrieve a Specific Attachment on an Asset

curl -v \
    -H "@$HOME/.datatrails/bearer-token.txt" \
    https://app.datatrails.ai/archivist/v2/attachments/assets/c04d5ecf-02e0-4be2-a014-ffbbf0e8ddeb/08838336-c357-460d-902a-3aba9528dd22

Retrieve a Specific Attachment on an Event

curl -v \
    -H "@$HOME/.datatrails/bearer-token.txt" \
    https://app.datatrails.ai/archivist/v2/attachments/assets/c04d5ecf-02e0-4be2-a014-ffbbf0e8ddeb/events/de834094-f6c3-4e38-9b37-8c61dea312c9/08838336-c357-460d-902a-3aba9528dd22

Retrieve Information About a Specific Attachment

It’s also possible to retrieve information about specific attachment using this API.

This information includes the scanned_status of the attachment. Attachment scanning happens each day.

To do so, simply issue a request as above with the suffix /info.

curl -v \
    -H "@$HOME/.datatrails/bearer-token.txt" \
    https://app.datatrails.ai/archivist/v2/attachments/assets/c04d5ecf-02e0-4be2-a014-ffbbf0e8ddeb/08838336-c357-460d-902a-3aba9528dd22/info

The response will include basic information about the attachment:

{
  "hash": {
    "alg": "SHA256",
    "value": "75debbfc7a4d988f2321dfb158fe65c62dabe50d4d7b6efb961e83be43a8aa77"  },
  "identity": "attachments/08838336-c357-460d-902a-3aba9528dd22",
  "issuer": "local",
  "mime_type": "image/jpeg",
  "size": 81254,
  "subject": "user@datatrails.ai",
  "tenantid": "tenant/<tenant-id>",
  "timestamp_accepted": "2023-02-06T16:04:31Z",
  "scanned_status": "NOT_SCANNED",
  "scanned_bad_reason": "",
  "scanned_timestamp": ""
}

Attachment OpenAPI Docs

API for uploading and downloading attachments.

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

Downloads an event attachment.

Description: Downloads an event attachment, if the given attachment is present in the ‘arc_attachments’ event atttribute.

ResponsesDescription
200A successful response.
400Returned when the request is badly formed.
401Returned when the user is not authenticated to the system.
403Returned when the user is not authorized to get the blob.
404Returned when the underlying system can’t find the event.
429Returned when a user exceeds their subscription’s rate limit for requests.

get  /archivist/v2/attachments/assets/{asset_uuid}/events/{event_uuid}/{uuid}/info

Retrieve metadata on an attachment.

Description: Retrieve metadata on an attachment, if the given attachment is present in the ‘arc_attachments’ event atttribute.

{
  "hash": {
    "alg": "SHA256",
    "value": "xxxxxxxxxxxxxxxxxxxxxxx"
  },
  "identity": "blobs/08838336-c357-460d-902a-3aba9528dd22",
  "issuer": "xxxx@example.com",
  "mime_type": "image/jpeg",
  "scanned_bad_reason": "",
  "scanned_status": "SCANNED_OK",
  "scanned_timestamp": "2019-11-07T15:31:49Z",
  "size": 31424,
  "subject": "user-xxxx@example.com",
  "tenantid": "tenant/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "timestamp_accepted": "2019-11-07T15:31:49Z"
}
Response ParameterTypeDescription
hashblob hash.
identitystringblob identity.
issuerstringprincipal issuer.
mime_typestringhttp mime type.
scanned_bad_reasonstringif scanned as SCANNED_BAD contains a hint of scan result.
scanned_statusstringstatus of scan.
scanned_timestampstringdate and time when the attachments has been scanned.
sizeintegersize of the blob.
subjectstringprincipal subject.
tenantidstringidentity of the tenant the blob belongs to.
timestamp_acceptedstringdate and time when the request has been received.
ResponsesDescription
200A successful response.
400Returned when the request is badly formed.
401Returned when the user is not authenticated to the system.
403Returned when the user is not authorized to get the blob metadata.
404Returned when the underlying system can’t find the event.
429Returned when a user exceeds their subscription’s rate limit for requests.

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

Downloads an asset attachment.

Description: Downloads an asset attachment, if the given attachment is present in the ‘arc_attachments’ asset atttribute.

ResponsesDescription
200A successful response.
400Returned when the request is badly formed.
401Returned when the user is not authenticated to the system.
403Returned when the user is not authorized to get the blob.
404Returned when the underlying system can’t find the asset.
429Returned when a user exceeds their subscription’s rate limit for requests.

get  /archivist/v2/attachments/assets/{asset_uuid}/{uuid}/info

Retrieve metadata on an attachment.

Description: Retrieve metadata on an attachment, if the given attachment is present in the ‘arc_attachments’ asset atttribute.

{
  "hash": {
    "alg": "SHA256",
    "value": "xxxxxxxxxxxxxxxxxxxxxxx"
  },
  "identity": "blobs/08838336-c357-460d-902a-3aba9528dd22",
  "issuer": "xxxx@example.com",
  "mime_type": "image/jpeg",
  "scanned_bad_reason": "",
  "scanned_status": "SCANNED_OK",
  "scanned_timestamp": "2019-11-07T15:31:49Z",
  "size": 31424,
  "subject": "user-xxxx@example.com",
  "tenantid": "tenant/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "timestamp_accepted": "2019-11-07T15:31:49Z"
}
Response ParameterTypeDescription
hashblob hash.
identitystringblob identity.
issuerstringprincipal issuer.
mime_typestringhttp mime type.
scanned_bad_reasonstringif scanned as SCANNED_BAD contains a hint of scan result.
scanned_statusstringstatus of scan.
scanned_timestampstringdate and time when the attachments has been scanned.
sizeintegersize of the blob.
subjectstringprincipal subject.
tenantidstringidentity of the tenant the blob belongs to.
timestamp_acceptedstringdate and time when the request has been received.
ResponsesDescription
200A successful response.
400Returned when the request is badly formed.
401Returned when the user is not authenticated to the system.
403Returned when the user is not authorized to get the blob metadata.
404Returned when the underlying system can’t find the asset.
429Returned when a user exceeds their subscription’s rate limit for requests.