DataTrails

Blobs API

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

Blob API Examples

The Blobs API enables you to upload Binary Large OBjects (BLOBs) such as documents, process artifacts and images to attach to your evidence ledger.

Note: Blobs cannot be searched or listed as a collection in their own right: they must always be associated with an Asset or Event through an Attachment Attribute and can only be downloaded by users with appropriate access rights to that Attachment. Take note of the Blob ID returned in the API response, it will be needed for use with Assets and Events.
For information on Attachments and how to implement them, please refer to the Events API Reference.

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

Upload a Blob

Upload the blob stored at /path/to/file:

curl -v -X POST \
    -H "@$HOME/.datatrails/bearer-token.txt" \
    -H "content_type=image/jpg" \
    -F "file=@/path/to/file" \
    https://app.datatrails.ai/archivist/v1/blobs

The response is:

{
  "hash": {
    "alg": "SHA256",
    "value": "xxxxxxxxxxxxxxxxxxxxxxx"  },
  "identity": "blobs/<blob-id>",
  "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": ""
}

Retrieve a Blob

Retrieve a specific Blob:

curl -v \
    -H "@$HOME/.datatrails/bearer-token.txt" \
    -H "content_type=image/jpg" \
    --output "/path/to/file" \
    https://app.datatrails.ai/archivist/v1/blobs/08838336-c357-460d-902a-3aba9528dd22

The response is:

{
  "hash": {
    "alg": "SHA256",
    "value": "xxxxxxxxxxxxxxxxxxxxxxx"  },
  "identity": "blobs/<blob-id>",
  "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": ""
}

Blobs OpenAPI Docs

API for uploading and downloading blobs.

post  /archivist/v1/blobs

Upload.

Description: Uploads a blob.

{
  "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.
402Returned when the number of blobs would exceed the user’s quota or the size of the blob exceeds the user’s allocation.
403Returned when the user is not authorized to create a blob.
429Returned when a user exceeds their subscription’s rate limit for requests.
500Returned when the underlying system returns an error.

get  /archivist/v1/blobs/{uuid}

Download.

Description: Downloads a blob.

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.
429Returned when a user exceeds their subscription’s rate limit for requests.
500Returned when the underlying system returns an error.

get  /archivist/v1/blobs/{uuid}/info

Retrieve blob metadata.

Description: Returns metadata information on a blob.

{
  "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.
429Returned when a user exceeds their subscription’s rate limit for requests.
500Returned when the underlying system returns an error.

← Attachments API
Compliance API →