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
200A successful response.
206The 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.
401Returned when the user is not authenticated to the system.
403Returned when the user is not authorized to list Assets.
defaultAn 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
200A successful response.
401Returned when the user is not authenticated to the system.
403Returned when the user is not authorized to create an Asset.
defaultAn 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
200A successful response.
401Returned when the user is not authenticated to the system.
403Returned when the user is not authorized to view Event.
404Returned when the event does not exist.
defaultAn 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
200A successful response.
401Returned when the user is not authenticated to the system.
403Returned when the user is not authorized to view an Asset.
404Returned when the asset with the id does not exist.
defaultAn 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
200A successful response.
206The 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.
401Returned when the user is not authenticated to the system.
403Returned when the user is not authorized to list Events.
defaultAn unexpected error response.

Edit this page on GitHub