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/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 Parameter | Type | Description |
---|---|---|
hash | blob hash. | |
identity | string | blob identity. |
issuer | string | principal issuer. |
mime_type | string | http mime type. |
scanned_bad_reason | string | if scanned as SCANNED_BAD contains a hint of scan result. |
scanned_status | string | status of scan. |
scanned_timestamp | string | date and time when the attachments has been scanned. |
size | integer | size of the blob. |
subject | string | principal subject. |
tenantid | string | identity of the tenant the blob belongs to. |
timestamp_accepted | string | date and time when the request has been received. |
Responses | Description |
---|---|
200 | A successful response. |
400 | Returned when the request is badly formed. |
401 | Returned when the user is not authenticated to the system. |
402 | Returned when the number of blobs would exceed the user’s quota or the size of the blob exceeds the user’s allocation. |
403 | Returned when the user is not authorized to create a blob. |
429 | Returned when a user exceeds their subscription’s rate limit for requests. |
500 | Returned when the underlying system returns an error. |
get /archivist/v1/blobs/archivist/v1/blobs/{uuid}
Download.
Description: Downloads a blob.
Responses | Description |
---|---|
200 | A successful response. |
400 | Returned when the request is badly formed. |
401 | Returned when the user is not authenticated to the system. |
403 | Returned when the user is not authorized to get the blob. |
429 | Returned when a user exceeds their subscription’s rate limit for requests. |
500 | Returned when the underlying system returns an error. |
get /archivist/v1/blobs/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 Parameter | Type | Description |
---|---|---|
hash | blob hash. | |
identity | string | blob identity. |
issuer | string | principal issuer. |
mime_type | string | http mime type. |
scanned_bad_reason | string | if scanned as SCANNED_BAD contains a hint of scan result. |
scanned_status | string | status of scan. |
scanned_timestamp | string | date and time when the attachments has been scanned. |
size | integer | size of the blob. |
subject | string | principal subject. |
tenantid | string | identity of the tenant the blob belongs to. |
timestamp_accepted | string | date and time when the request has been received. |
Responses | Description |
---|---|
200 | A successful response. |
400 | Returned when the request is badly formed. |
401 | Returned when the user is not authenticated to the system. |
403 | Returned when the user is not authorized to get the blob metadata. |
429 | Returned when a user exceeds their subscription’s rate limit for requests. |
500 | Returned when the underlying system returns an error. |