Assets API
Assets API Reference
Asset API Examples
Create the bearer_token and store in a file in a secure local directory with 0600 permissions.
Asset Record Creation
Define the asset parameters and store in /path/to/jsonfile
:
{
"attributes": {
"arc_attachments": [
{
"arc_attachment_identity": "blobs/1754b920-cf20-4d7e-9d36-9ed7d479744d",
"arc_display_name": "Picture from yesterday",
"arc_hash_alg": "sha256",
"arc_hash_value": "01ba4719c80b6fe911b091a7c05124b64eeece964e09c058ef8f9805daca546b"
}
],
"arc_firmware_version": "3.2.1",
"arc_home_location_identity": "locations/42054f10-9952-4c10-a082-9fd0d10295ae"
},
"behaviours": [
"RecordEvidence",
"Attachments"
],
"proof_mechanism": "SIMPLE_HASH",
"public": false
}
Create the asset:
curl -v -X POST \
-H "@$BEARER_TOKEN_FILE" \
-H "Content-type: application/json" \
-d "@/path/to/jsonfile" \
https://app.rkvst.io/archivist/v2/assets
The response is:
{
"at_time": "2019-11-27T14:44:19Z",
"attributes": {
"arc_attachments": [
{
"arc_attachment_identity": "blobs/1754b920-cf20-4d7e-9d36-9ed7d479744d",
"arc_display_name": "Picture from yesterday",
"arc_hash_alg": "sha256",
"arc_hash_value": "01ba4719c80b6fe911b091a7c05124b64eeece964e09c058ef8f9805daca546b"
}
],
"arc_firmware_version": "3.2.1",
"arc_home_location_identity": "locations/42054f10-9952-4c10-a082-9fd0d10295ae"
},
"behaviours": [
"RecordEvidence"
],
"confirmation_status": "PENDING",
"identity": "assets/add30235-1424-4fda-840a-d5ef82c4c96f",
"owner": "0x601f5A7D3e6dcB55e87bf2F17bC8A27AaCD3511",
"proof_mechanism": "SIMPLE_HASH",
"public": false,
"tenant_identity": "tenant/8e0b600c-8234-43e4-860c-e95bdcd695a9",
"tracked": "TRACKED"
}
Creating a Public Asset
Warning: Assets can only be made public at Asset Creation and cannot be made private afterwards.
In most cases it is appropriate to create a standard Asset. These Assets can only be shared externally using Access Policies as described in Sharing Assets with OBAC or the IAM Policies API Reference.
However it is also possible to create a Public Asset which can be shared with a read-only public url; similar to the link sharing you may have seen in file sharing services like Google Drive or DropBox.
Public Assets can be used for Public Attestation, where you may wish to publicly assert data you have published.
For example, the vulnerability reports against an OpenSource software package, or perhaps the maintenance records for a public building.
Creating a Public Asset just requires flipping the public
value in the above request to true
, from then on only the creating tenancy may update the asset and events on a Public Asset through their private, signed-in interface.
All Public Assets are then given a read-only public URL that can be retrieved using Fetch a Public Asset’s URL, any events added to that Public Asset will also get their own unique Public URL that can be retrieved with Fetch a Public Asset’s Event URL.
This link can be shared with anyone to give them read-only access to the asset or event without the need to sign in.
To interact with the unauthenticated Public Interface for a Public Asset see the Public Assets API Reference. To update the Assets and Events as the creating tenant on a Public Asset’s authenticated Private Interface you would still use the standard Assets and Events API as normal.
Asset Record Retrieval
Asset records in RKVST are tokenized at creation time and referred to in all API calls and smart contracts throughout the system by a unique identity of the form:
assets/12345678-90ab-cdef-1234-567890abcdef
If you do not know the asset’s identity you can fetch asset records using other information you do know.
Fetch All Assets
To fetch all asset records, simply GET
the assets resource:
curl -v -X GET \
-H "@$BEARER_TOKEN_FILE" \
https://app.rkvst.io/archivist/v2/assets
Fetch Specific Asset by Identity
If you know the unique identity of the Asset Record simply GET
the resource:
curl -v -X GET \
-H "@$BEARER_TOKEN_FILE" \
https://app.rkvst.io/archivist/v2/assets/6a951b62-0a26-4c22-a886-1082297b063b
Fetch Specific Asset at Given Point in Time by Identity
If you know the unique identity of an Asset Record and want to show its state at any given point in the past, simply GET
with following query parameter
curl -v -X GET \
-H "@$BEARER_TOKEN_FILE" \
https://app.rkvst.io/archivist/v2/assets/6a951b62-0a26-4c22-a886-1082297b063b?at_time=2021-01-13T12:34:21Z
This will return the Asset Record with the values it had on 2021-01-13T12:34:21Z
Fetch Assets by Name
To fetch all assets with a specific name, GET the assets resource and filter on arc_display_name
:
curl -g -v -X GET \
-H "@$BEARER_TOKEN_FILE" \
https://app.rkvst.io/archivist/v2/assets?attributes.arc_display_name=tcl.ccj.003
Fetch Assets by Type
To fetch all assets of a specific type, GET
the assets resource and filter on arc_display_type
:
curl -g -v -X GET \
-H "@$BEARER_TOKEN_FILE" \
https://app.rkvst.io/archivist/v2/assets?attributes.arc_display_type=Traffic%20light
Fetch Assets by Filtering for Presence of a Field
To fetch all assets with a field set to any value, GET
the assets resource and filter on most available fields. For example:
curl -g -v -X GET \
-H "@$BEARER_TOKEN_FILE" \
https://app.rkvst.io/archivist/v2/assets?attributes.arc_display_name=*
Returns all assets which have arc_display_name
that is not empty.
Fetch Assets Which are Missing a Field
To fetch all assets with a field which is not set to any value, GET
the assets resource and filter on most available fields. For example:
curl -g -v -X GET \
-H "@$BEARER_TOKEN_FILE" \
https://app.rkvst.io/archivist/v2/assets?attributes.arc_display_name!=*
Returns all assets which do not have arc_display_name
or in which arc_display_name
is empty.
Fetch a Public Asset’s URL
Fetch the Public URL of a Public Asset
curl -g -v -X GET \
-H "@$BEARER_TOKEN_FILE" \
https://app.rkvst.io/archivist/v2/assets/86b61c4b-030e-4c07-9400-463612e6cee4:publicurl
{
"publicurl":"https://app.rkvst.io/archivist/publicassets/86b61c4b-030e-4c07-9400-463612e6cee4"
}
Fetch a Public Asset’s Event URL
Fetch the Public URL of an Event on a Public Asset
curl -g -v -X GET \
-H "@$BEARER_TOKEN_FILE" \
https://app.rkvst.io/archivist/v2/assets/86b61c4b-030e-4c07-9400-463612e6cee4/events/7da272ad-19d5-4106-b4af-2980a84c2721:publicurl
{
"publicurl":"https://app.rkvst.io/archivist/publicassets/86b61c4b-030e-4c07-9400-463612e6cee4/events/7da272ad-19d5-4106-b4af-2980a84c2721"
}
Asset OpenAPI Docs
API for asset and event management.
get /archivist/v2/assets
List Archivist assets
Description: Retrieves a list of Archivist assets
{
"assets": [
{
"at_time": "2019-11-27T14:44:19Z",
"attributes": {
"arc_attachments": [
{
"arc_attachment_identity": "blobs/1754b920-cf20-4d7e-9d36-9ed7d479744d",
"arc_display_name": "Picture from yesterday",
"arc_hash_alg": "sha256",
"arc_hash_value": "01ba4719c80b6fe911b091a7c05124b64eeece964e09c058ef8f9805daca546b"
}
],
"arc_firmware_version": "3.2.1",
"arc_home_location_identity": "locations/42054f10-9952-4c10-a082-9fd0d10295ae"
},
"behaviours": [
"RecordEvidence"
],
"confirmation_status": "PENDING",
"identity": "assets/add30235-1424-4fda-840a-d5ef82c4c96f",
"owner": "0x601f5A7D3e6dcB55e87bf2F17bC8A27AaCD3511",
"proof_mechanism": "SIMPLE_HASH",
"public": false,
"tenant_identity": "tenant/8e0b600c-8234-43e4-860c-e95bdcd695a9",
"tracked": "TRACKED"
},
{
"at_time": "2019-11-27T14:44:19Z",
"attributes": {
"arc_attachments": [
{
"arc_attachment_identity": "blobs/2865ca31-d01f-5e6f-4621-de562470732e",
"arc_display_name": "Picture",
"arc_hash_alg": "sha256",
"arc_hash_value": "12bc4819d90b6fe911b091a7c05134b65edfce045e09b048caaa7916ecdd458c"
}
],
"arc_firmware_version": "3.2.1",
"arc_home_location_identity": "locations/53165a2c-6054-dd68-f093-a0e1e21304fd"
},
"behaviours": [
"RecordEvidence"
],
"confirmation_status": "PENDING",
"identity": "assets/cef61346-2453-5aeb-921c-e6fa93d5b032",
"owner": "0x601f5A7D3e6dcB55e87bf2F17bC8A27AaCD3511",
"proof_mechanism": "KHIPU",
"public": false,
"tenant_identity": "tenant/8e0b600c-8234-43e4-860c-e95bdcd695a9",
"tracked": "TRACKED"
}
],
"next_page_token": "abcd"
}
Response Parameter | Type | Description |
---|---|---|
assets | array | This describes Jitsuin Asset. |
next_page_token | string | Token to retrieve the next page of results or empty if there are none. |
Responses | Description |
---|---|
200 | A successful response. |
206 | The number of assets exceeds the servers limit. The approximate number of matching results is provided by the x-total-count header if the ‘x-request-total-count’ header on the request is set to ’true’. The exact limit is available in the content-range header. The value format is ‘items 0-LIMIT/TOTAL’. Note that x-total-count is always present for 200 and 206 responses. It is the servers best available approximation. Similarly, in any result set, you may get a few more than LIMIT items. |
401 | Returned when the user is not authenticated to the system. |
403 | Returned when the user is not authorized to list Assets. |
429 | Returned when a user exceeds their subscription’s rate limit for requests. |
default | An unexpected error response. |
post /archivist/v2/assets
Create an Archivist asset
Description: Creates an Archivist asset
{
"attributes": {
"arc_attachments": [
{
"arc_attachment_identity": "blobs/1754b920-cf20-4d7e-9d36-9ed7d479744d",
"arc_display_name": "Picture from yesterday",
"arc_hash_alg": "sha256",
"arc_hash_value": "01ba4719c80b6fe911b091a7c05124b64eeece964e09c058ef8f9805daca546b"
}
],
"arc_firmware_version": "3.2.1",
"arc_home_location_identity": "locations/42054f10-9952-4c10-a082-9fd0d10295ae"
},
"behaviours": [
"RecordEvidence",
"Attachments"
],
"proof_mechanism": "SIMPLE_HASH",
"public": false
}
Parameter | Type | Description |
---|---|---|
attributes | object | key value mapping of event attributes |
behaviours | array | list of behaviours enabled for this asset |
chain_id | string | chain id of the blockchain associated with this asset |
proof_mechanism | string | specify the mechanism used to provide evidential proof for Events on this Asset |
public | boolean | Public asset. A public asset and all its events are visible to the general public.Sharing to specific organisations is not available for public assets. |
storage_integrity | string | DEPRECATED use proof_mechanism |
{
"at_time": "2019-11-27T14:44:19Z",
"attributes": {
"arc_attachments": [
{
"arc_attachment_identity": "blobs/1754b920-cf20-4d7e-9d36-9ed7d479744d",
"arc_display_name": "Picture from yesterday",
"arc_hash_alg": "sha256",
"arc_hash_value": "01ba4719c80b6fe911b091a7c05124b64eeece964e09c058ef8f9805daca546b"
}
],
"arc_firmware_version": "3.2.1",
"arc_home_location_identity": "locations/42054f10-9952-4c10-a082-9fd0d10295ae"
},
"behaviours": [
"RecordEvidence"
],
"confirmation_status": "PENDING",
"identity": "assets/add30235-1424-4fda-840a-d5ef82c4c96f",
"owner": "0x601f5A7D3e6dcB55e87bf2F17bC8A27AaCD3511",
"proof_mechanism": "SIMPLE_HASH",
"public": false,
"tenant_identity": "tenant/8e0b600c-8234-43e4-860c-e95bdcd695a9",
"tracked": "TRACKED"
}
Response Parameter | Type | Description |
---|---|---|
at_time | string | indicates time the asset data is from |
attributes | object | key value mapping of asset properties |
behaviours | array | list of behaviours enabled for this asset |
chain_id | string | chain id of the blockchain associated with this asset |
confirmation_status | string | indicates if the asset has been succesfully committed to the blockchain |
identity | string | relative resource address assets/{UUID} |
owner | string | wallet address of the asset owner |
proof_mechanism | string | the mechanism used to provide evidential proof |
public | boolean | Public asset |
storage_integrity | string | DEPRECATED use proof_mechanism |
tenant_identity | string | Identity of the tenant the that created this asset |
tracked | string | indicates whether asset is still being tracked in the system |
Responses | Description |
---|---|
200 | A successful response. |
401 | Returned when the user is not authenticated to the system. |
402 | Returned when the user either has not enabled blockchain storage orthe number of assets would exceed the user’s quota |
403 | Returned when the user is not authorized to create an Asset. |
429 | Returned when a user exceeds their subscription’s rate limit for requests. |
default | An unexpected error response. |
get /archivist/v2/assets/{asset_uuid}/events/{uuid}
Retrieves Archivist event
Description: Retrieves a specific Archivist event
{
"asset_attributes": {
"arc_firmware_version": "3.2.1",
"arc_home_location_identity": "locations/42054f10-9952-4c10-a082-9fd0d10295ae"
},
"asset_identity": "assets/add30235-1424-4fda-840a-d5ef82c4c96f",
"behaviour": "RecordEvidence",
"block_number": 12,
"confirmation_status": "CONFIRMED",
"event_attributes": {
"arc_attachments": [
{
"arc_attachment_identity": "blobs/1754b920-cf20-4d7e-9d36-9ed7d479744d",
"arc_display_name": "Picture from yesterday",
"arc_hash_alg": "sha256",
"arc_hash_value": "01ba4719c80b6fe911b091a7c05124b64eeece964e09c058ef8f9805daca546b"
}
]
},
"identity": "assets/add30235-1424-4fda-840a-d5ef82c4c96f/events/11bf5b37-e0b8-42e0-8dcf-dc8c4aefc000",
"operation": "Record",
"principal_accepted": {
"issuer": "job.idp.server/1234",
"subject": "bob@job"
},
"principal_declared": {
"issuer": "job.idp.server/1234",
"subject": "bob@job"
},
"tenant_identity": "tenant/8e0b600c-8234-43e4-860c-e95bdcd695a9",
"timestamp_accepted": "2019-11-27T14:44:19Z",
"timestamp_committed": "2019-11-27T14:44:19Z",
"timestamp_declared": "2019-11-27T14:44:19Z",
"transaction_id": "0x07569",
"transaction_index": 5
}
Response Parameter | Type | Description |
---|---|---|
asset_attributes | object | key value mapping of asset attributes |
asset_identity | string | identity of a related asset resource assets/11bf5b37-e0b8-42e0-8dcf-dc8c4aefc000 |
behaviour | string | The behaviour used to create event. RecordEvidence |
block_number | string | number of block event was commited on |
confirmation_status | string | indicates if the event has been succesfully committed to the blockchain |
event_attributes | object | key value mapping of event attributes |
from | string | wallet address for the creator of this event |
identity | string | identity of a event resource |
operation | string | The operation represented by the event. Record |
principal_accepted | object | principal recorded by the server |
principal_declared | object | principal provided by the user |
tenant_identity | string | Identity of the tenant the that created this event |
timestamp_accepted | string | time of event as recorded by the server |
timestamp_committed | string | time of event as recorded on blockchain |
timestamp_declared | string | time of event as declared by the user |
transaction_id | string | hash of the transaction as a hex string 0x11bf5b37e0b842e08dcfdc8c4aefc000 |
transaction_index | string | index of event within commited block |
Responses | Description |
---|---|
200 | A successful response. |
401 | Returned when the user is not authenticated to the system. |
403 | Returned when the user is not authorized to view Event. |
404 | Returned when the event does not exist. |
429 | Returned when a user exceeds their subscription’s rate limit for requests. |
default | An unexpected error response. |
get /archivist/v2/assets/{asset_uuid}/events/{uuid}:publicurl
Retrieves the public url for a specific Archivist event.
Description: Retrieves the public url for a specific Archivist event.
{
"publicurl": "https://app.rkvst.io/archivist/publicassets/add30235-1424-4fda-840a-d5ef82c4c96f/events/11bf5b37-e0b8-42e0-8dcf-dc8c4aefc000"
}
Response Parameter | Type | Description |
---|---|---|
publicurl | string |
Responses | Description |
---|---|
200 | A successful response. |
401 | Returned when the user is not authenticated to the system. |
403 | Returned when the user is not authorized to view an Asset. |
404 | Returned when the asset with the id does not exist. |
429 | Returned when a user exceeds their subscription’s rate limit for requests. |
default | An unexpected error response. |
get /archivist/v2/assets/{uuid}
Retrieves a specific Archivist asset
Description: Retrieves a specific Archivist asset
{
"at_time": "2019-11-27T14:44:19Z",
"attributes": {
"arc_attachments": [
{
"arc_attachment_identity": "blobs/1754b920-cf20-4d7e-9d36-9ed7d479744d",
"arc_display_name": "Picture from yesterday",
"arc_hash_alg": "sha256",
"arc_hash_value": "01ba4719c80b6fe911b091a7c05124b64eeece964e09c058ef8f9805daca546b"
}
],
"arc_firmware_version": "3.2.1",
"arc_home_location_identity": "locations/42054f10-9952-4c10-a082-9fd0d10295ae"
},
"behaviours": [
"RecordEvidence"
],
"confirmation_status": "PENDING",
"identity": "assets/add30235-1424-4fda-840a-d5ef82c4c96f",
"owner": "0x601f5A7D3e6dcB55e87bf2F17bC8A27AaCD3511",
"proof_mechanism": "SIMPLE_HASH",
"public": false,
"tenant_identity": "tenant/8e0b600c-8234-43e4-860c-e95bdcd695a9",
"tracked": "TRACKED"
}
Response Parameter | Type | Description |
---|---|---|
at_time | string | indicates time the asset data is from |
attributes | object | key value mapping of asset properties |
behaviours | array | list of behaviours enabled for this asset |
chain_id | string | chain id of the blockchain associated with this asset |
confirmation_status | string | indicates if the asset has been succesfully committed to the blockchain |
identity | string | relative resource address assets/{UUID} |
owner | string | wallet address of the asset owner |
proof_mechanism | string | the mechanism used to provide evidential proof |
public | boolean | Public asset |
storage_integrity | string | DEPRECATED use proof_mechanism |
tenant_identity | string | Identity of the tenant the that created this asset |
tracked | string | indicates whether asset is still being tracked in the system |
Responses | Description |
---|---|
200 | A successful response. |
401 | Returned when the user is not authenticated to the system. |
403 | Returned when the user is not authorized to view an Asset. |
404 | Returned when the asset with the id does not exist. |
429 | Returned when a user exceeds their subscription’s rate limit for requests. |
default | An unexpected error response. |
get /archivist/v2/assets/{uuid}/events
List Archivist events
Description: Lists Archivist events
{
"events": [
{
"asset_attributes": {
"arc_firmware_version": "3.2.1",
"arc_home_location_identity": "locations/42054f10-9952-4c10-a082-9fd0d10295ae"
},
"asset_identity": "assets/add30235-1424-4fda-840a-d5ef82c4c96f",
"behaviour": "RecordEvidence",
"block_number": 12,
"confirmation_status": "CONFIRMED",
"event_attributes": {
"arc_attachments": [
{
"arc_attachment_identity": "blobs/1754b920-cf20-4d7e-9d36-9ed7d479744d",
"arc_display_name": "Picture from yesterday",
"arc_hash_alg": "sha256",
"arc_hash_value": "01ba4719c80b6fe911b091a7c05124b64eeece964e09c058ef8f9805daca546b"
}
]
},
"identity": "assets/add30235-1424-4fda-840a-d5ef82c4c96f/events/11bf5b37-e0b8-42e0-8dcf-dc8c4aefc000",
"operation": "Record",
"principal_accepted": {
"issuer": "job.idp.server/1234",
"subject": "bob@job"
},
"principal_declared": {
"issuer": "job.idp.server/1234",
"subject": "bob@job"
},
"tenant_identity": "tenant/8e0b600c-8234-43e4-860c-e95bdcd695a9",
"timestamp_accepted": "2019-11-27T14:44:19Z",
"timestamp_committed": "2019-11-27T14:44:19Z",
"timestamp_declared": "2019-11-27T14:44:19Z",
"transaction_id": "0x07569",
"transaction_index": 5
},
{
"asset_attributes": {
"arc_firmware_version": "3.2.1",
"arc_home_location_identity": "locations/42054f10-9952-4c10-a082-9fd0d10295ae"
},
"asset_identity": "assets/bf330235-1424-4fda-840a-d5ef82c4c96f",
"behaviour": "RecordEvidence",
"block_number": 13,
"confirmation_status": "CONFIRMED",
"event_attributes": {
"arc_attachments": [
{
"arc_attachment_identity": "blobs/1754b920-cf20-4d7e-9d36-9ed7d479744d",
"arc_display_name": "Picture",
"arc_hash_alg": "sha256",
"arc_hash_value": "01ba4719c80b6fe911b091a7c05124b64eeece964e09c058ef8f9805daca546b"
}
]
},
"identity": "assets/bf330235-1424-4fda-840a-d5ef82c4c96f/events/23c06c48-e0b8-42e0-8dcf-dc8c4fdad123",
"operation": "Record",
"principal_accepted": {
"issuer": "job.idp.server/1234",
"subject": "bob@job"
},
"principal_declared": {
"issuer": "job.idp.server/1234",
"subject": "bob@job"
},
"tenant_identity": "tenant/8e0b600c-8234-43e4-860c-e95bdcd695a9",
"timestamp_accepted": "2019-07-27T14:44:19Z",
"timestamp_committed": "2019-07-27T14:44:19Z",
"timestamp_declared": "2019-07-27T14:44:19Z",
"transaction_id": "0x12569",
"transaction_index": 6
}
],
"next_page_token": "abcd"
}
Response Parameter | Type | Description |
---|---|---|
events | array | This describes Jitsuin Event. |
next_page_token | string | Token to retrieve the next page of results or empty if there are none. |
Responses | Description |
---|---|
200 | A successful response. |
206 | The number of events exceeds the servers limit. The approximate number of matching results is provided by the x-total-count header, the exact limit is available in the content-range header. The value format is ‘items 0-LIMIT/TOTAL’. Note that x-total-count is always present for 200 and 206 responses. It is the servers best available approximation. Similarly, in any result set, you may get a few more than LIMIT items. |
401 | Returned when the user is not authenticated to the system. |
403 | Returned when the user is not authorized to list Events. |
429 | Returned when a user exceeds their subscription’s rate limit for requests. |
default | An unexpected error response. |
get /archivist/v2/assets/{uuid}:publicurl
Retrieves the public url for a specific Archivist asset.
Description: Retrieves the public url for a specific Archivist asset.
{
"publicurl": "https://app.rkvst.io/archivist/publicassets/add30235-1424-4fda-840a-d5ef82c4c96f"
}
Response Parameter | Type | Description |
---|---|---|
publicurl | string |
Responses | Description |
---|---|
200 | A successful response. |
401 | Returned when the user is not authenticated to the system. |
403 | Returned when the user is not authorized to view an Asset. |
404 | Returned when the asset with the id does not exist. |
429 | Returned when a user exceeds their subscription’s rate limit for requests. |
default | An unexpected error response. |
get /archivist/v2/assets:openapi
Get OpenAPI spec for Assets
Description: Get OpenAPI v2.0 spec for Assets
Responses | Description |
---|---|
200 | A successful response. |
401 | Returned when the user is not authenticated to the system. |
429 | Returned when a user exceeds their subscription’s rate limit for requests. |
default | An unexpected error response. |
get /archivist/v2/assets:openapi-ui
Get OpenAPI UI for Assets
Description: Get OpenAPI v2.0 UI for Assets
Responses | Description |
---|---|
200 | A successful response. |
401 | Returned when the user is not authenticated to the system. |
429 | Returned when a user exceeds their subscription’s rate limit for requests. |
default | An unexpected error response. |