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.
| 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. |
| 404 | Returned when the underlying system can’t find the event. |
| 429 | Returned 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 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. |
| 404 | Returned when the underlying system can’t find the event. |
| 429 | Returned 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.
| 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. |
| 404 | Returned when the underlying system can’t find the asset. |
| 429 | Returned 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 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. |
| 404 | Returned when the underlying system can’t find the asset. |
| 429 | Returned when a user exceeds their subscription’s rate limit for requests. |
API for uploading and downloading attachments from public Assets.
get /archivist/v2/attachments/publicassets/{asset_uuid}/events/{event_uuid}/{uuid}
Downloads an event attachment from public asset.
Description: Downloads an event attachment, if the given attachment is present in the ‘arc_attachments’ event atttribute.
| Responses | Description |
|---|---|
| 200 | A successful response. |
| 400 | Returned when the request is badly formed. |
| 404 | Returned when the underlying system can’t find the event. |
get /archivist/v2/attachments/publicassets/{asset_uuid}/events/{event_uuid}/{uuid}/info
Retrieve metadata on an attachment from a public asset.
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 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. |
| 404 | Returned when the underlying system can’t find the event. |
get /archivist/v2/attachments/publicassets/{asset_uuid}/{uuid}
Downloads an public asset attachment.
Description: Downloads an asset attachment, if the given attachment is present in the ‘arc_attachments’ asset atttribute.
| Responses | Description |
|---|---|
| 200 | A successful response. |
| 400 | Returned when the request is badly formed. |
| 404 | Returned when the underlying system can’t find the asset. |
get /archivist/v2/attachments/publicassets/{asset_uuid}/{uuid}/info
Retrieve metadata on an attachment from a public asset.
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 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. |
| 404 | Returned when the underlying system can’t find the asset. |