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:

{
    "behaviours": ["RecordEvidence", "Attachments"],
    "attributes": {
        "arc_firmware_version": "1.0",
        "arc_serial_number": "vtl-x4-07",
        "arc_display_name": "tcl.ppj.003",
        "arc_description": "Traffic flow control light at A603 North East",
        "arc_home_location_identity": "locations/115340cf-f39e-4d43-a2ee-8017d672c6c6",
        "arc_display_type": "Traffic light with violation camera",
        "some_custom_attribute": "value",
        "arc_attachments": [
            {
                "arc_display_name": "arc_primary_image",
                "arc_attachment_identity": "blobs/87b1a84c-1c6f-442b-923e-a97516f4d275",
                "arc_hash_alg": "SHA256",
                "arc_hash_value": "246c316e2cd6971ce5c83a3e61f9880fa6e2f14ae2976ee03500eb282fd03a60"
            }
        ]
    }
}

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:

{
    "identity": "assets/3f5be24f-fd1b-40e2-af35-ec7c14c74d53",
    "behaviours": [
        "RecordEvidence",
        "Attachments"
    ],
    "attributes": {
        "arc_serial_number": "vtl-x4-07",
        "arc_display_name": "tcl.ppj.003",
        "arc_description": "Traffic flow control light at A603 North East",
        "arc_home_location_identity": "locations/115340cf-f39e-4d43-a2ee-8017d672c6c6",
        "arc_display_type": "Traffic light with violation camera",
        "arc_firmware_version": "1.0",
        "some_custom_attribute": "value",
        "arc_attachments": [
            {
                "arc_display_name": "arc_primary_image",
                "arc_attachment_identity": "blobs/87b1a84c-1c6f-442b-923e-a97516f4d275",
                "arc_hash_alg": "SHA256",
                "arc_hash_value": "246c316e2cd6971ce5c83a3e61f9880fa6e2f14ae2976ee03500eb282fd03a60"
            }
        ]
    },
    "confirmation_status": "PENDING",
    "tracked": "TRACKED"
}

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.

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",
      "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",
      "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.
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"
}

Parameter	Type	Description
attributes	object	key value mapping of event attributes
behaviours	array	list of behaviours enabled for this asset
proof_mechanism	string	specify the mechanism used to provide evidential proof for Events on this Asset
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",
  "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
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
storage_integrity	string	DEPRECATED use proof_mechanism
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 create an Asset.
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"
  },
  "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
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.
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",
  "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
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
storage_integrity	string	DEPRECATED use proof_mechanism
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.
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"
      },
      "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"
      },
      "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.
default	An unexpected error response.

Edit this page on GitHub

Assets API

Asset API Examples#

Asset Record Creation#

Asset Record Retrieval#

Fetch All Assets#

Fetch Specific Asset by Identity#

Fetch Specific Asset at Given Point in Time by Identity#

Fetch Assets by Name#

Fetch Assets by Type#

Fetch Assets by Filtering for Presence of a Field#

Fetch Assets Which are Missing a Field#

Asset OpenAPI Docs#

get /archivist/v2/assets

get /archivist/v2/assets

List Archivist assets

Example Response

post /archivist/v2/assets

post /archivist/v2/assets

Create an Archivist asset

Example Request

Example Response

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

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

Retrieves Archivist event

Example Response

get /archivist/v2/assets/{uuid}

get /archivist/v2/assets/{uuid}

Retrieves a specific Archivist asset

Example Response

get /archivist/v2/assets/{uuid}/events

get /archivist/v2/assets/{uuid}/events

List Archivist events

Example Response

Asset API Examples

Asset Record Creation

Asset Record Retrieval

Fetch All Assets

Fetch Specific Asset by Identity

Fetch Specific Asset at Given Point in Time by Identity

Fetch Assets by Name

Fetch Assets by Type

Fetch Assets by Filtering for Presence of a Field

Fetch Assets Which are Missing a Field

Asset OpenAPI Docs