DataTrails

System API

System API Reference

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.

System API Examples

Create the bearer_token and store in a file in a secure local directory with 0600 permissions.

Querying Blockchain Status

The archivistnode endpoint reports on the status of the blockchain.

Query the endpoint:

curl -v -X GET \
    -H "@$HOME/.datatrails/bearer-token.txt" \
    https://app.datatrails.ai/archivist/v1/archivistnode

The response is:

{
    "identity": "quorum",
    "blockchain_nodes": [
        {
            "validator_pubkey": {
                "kty": "EC",
                "crv": "P-256K",
                "x": "VBKHictTWJC-3sqknXCb8MI4IxTc3c_My7lnem2C74E=",
                "y": "ItNeb5d-6vEHkvtUOcDYrEADxsZXeOCJm18pQWntenE=",
                "d": ""
            },
            "block_height": "38773",
            "connection_status": "REACHABLE"
            "genesis_hash":"0x1b526bd9c7f9bf7c43ba91ad07e5530eb7ceedf390396f9fbfeb68722e097e95",
            "state_root":"0x9606fc44a382938703678ac90581ab1260c9efd20ea8c7f90c87852bc982f3a7",
            "timestamp_committed": "2019-01-02T01:03:07Z",
            "timestamp_created": "2019-01-01T12:00:27Z",
            "syncing": null,
            "peers": [
                {
                    "validator_pubkey": {
                        "kty": "EC",
                        "crv": "P-256K",
                        "x": "o0uZ8ix5DE42srPCw1o22wYibkHGkvyCuLVqwcVAxb0=",
                        "y": "W43sUjWg-ociR2x3CcAlWeOqc6oDkYui1JLup1q-ojU=",
                        "d": ""
                    },
                    "connection_status": "REACHABLE"
                },
                {
                    "validator_pubkey": {
                        "kty": "EC",
                        "crv": "P-256K",
                        "x": "5HcU1PJgTe0LGyGxKFrIPFZWdTbxPySfi6bKxdQeO8A=",
                        "y": "dEpMURyTwEGzpgIgLdm4Csl1BgF6H39tb1Kf8wLLhVI=",
                        "d": ""
                    },
                    "connection_status": "REACHABLE"
                }
            ]
        }
    ]
}

System OpenAPI Docs

API to manage an archivist node.

get  /archivist/v1/archivistnode

Get information about an archivist node

Description: Returns the identified archivist node

{
  "blockchain_nodes": [
    {
      "block_height": "38773",
      "connection_status": "REACHABLE",
      "genesis_hash": "0x1b526bd9c7f9bf7c43ba91ad07e5530eb7ceedf390396f9fbfeb68722e097e95",
      "peers": [
        {
          "connection_status": "REACHABLE",
          "validator_pubkey": {
            "crv": "P-256K",
            "d": "",
            "kty": "EC",
            "x": "o0uZ8ix5DE42srPCw1o22wYibkHGkvyCuLVqwcVAxb0=",
            "y": "W43sUjWg-ociR2x3CcAlWeOqc6oDkYui1JLup1q-ojU="
          }
        },
        {
          "connection_status": "REACHABLE",
          "validator_pubkey": {
            "crv": "P-256K",
            "d": "",
            "kty": "EC",
            "x": "5HcU1PJgTe0LGyGxKFrIPFZWdTbxPySfi6bKxdQeO8A=",
            "y": "dEpMURyTwEGzpgIgLdm4Csl1BgF6H39tb1Kf8wLLhVI="
          }
        }
      ],
      "state_root": "0x9606fc44a382938703678ac90581ab1260c9efd20ea8c7f90c87852bc982f3a7",
      "syncing": null,
      "timestamp_committed": "2019-01-01T12:00:27Z",
      "timestamp_created": "2019-01-01T12:00:27Z",
      "validator_pubkey": {
        "crv": "P-256K",
        "d": "",
        "kty": "EC",
        "x": "VBKHictTWJC-3sqknXCb8MI4IxTc3c_My7lnem2C74E=",
        "y": "ItNeb5d-6vEHkvtUOcDYrEADxsZXeOCJm18pQWntenE="
      }
    }
  ],
  "identity": "quorum-0"
}
Response ParameterTypeDescription
blockchain_nodesarray
identitystringThe identity of the archivistnode blockchain
ResponsesDescription
200A successful response.
401Returned when the user is not authenticated to the system.
403Returned when the user is not authorized to read the archivist node’s information
404Returned when the identified archivist node does not exist
429Returned when a user exceeds their subscription’s rate limit for requests.

get  /archivist/v1/archivistnode/block

Get a block given a block hash or block number.

Description: Get a block given a block hash or block number

{
  "difficulty": "0x20000",
  "extraData": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAD4RDW4QfD3cYx...",
  "gasLimit": "0xb2d05e00",
  "gasUsed": "0xf426",
  "hash": "0x5c6726d7570046c6c4b20e97de1486877f293ba1e4d3b64c13b671354c2f8266",
  "logsBloom": "3078303030303030303030303030303030303030303030303030303030303030303...",
  "miner": "0x0000000000000000000000000000000000000000",
  "nonce": "307830303030303030303030303030303030",
  "number": "0x1a95f",
  "parentHash": "0x5fb3e35418f67379dbb2093d4886409ff8e530116628aee7c960e18f2fa9f40c",
  "receiptsRoot": "0x8bde93a8260d39fa79b76b8c5c7fe687669ba17c63928c4d8e55bc8fcfad04ee",
  "sha3Uncles": "0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347",
  "stateRoot": "0xb1bf30baaed044489b769f4bc557594f74e917b297b79ebe88102a856490cfc4",
  "timestamp": "0xf426",
  "transactionRoot": "0x5d912ec4fd96825fc58e75401d9834e94bf2fd8f01e50d6946831a60ec1c2040"
}
Response ParameterTypeDescription
difficultystringinteger of the difficulty for this block encoded as a hexadecimal
extraDatastringthe “extra data” field of this block
gasLimitstringthe maximum gas allowed in this block encoded as a hexadecimal
gasUsedstringthe total used gas by all transactions in this block encoded as a hexadecimal
hashstringthe block hash
logsBloomstringthe bloom filter for the logs of the block
minerstringthe address of the beneficiary to whom the mining rewards were given
noncestringhash of the generated proof of work
numberstringthe block number in hexidecimal
parentHashstringhash of the parent block
privateStateRootstringthe root of the final, node specific, private state trie of the block
receiptsRootstringthe root of the receipts trie of the block
sha3Unclesstringsha3 hash of the uncles data in the block
stateRootstringthe root of the final state trie of the block
timestampstringthe unix timestamp for when the block was collated
transactionRootstringthe root of the transaction trie of the block
ResponsesDescription
200A successful response.
401Returned when the user is not authenticated to the system.
403Returned when the user is not authorized to view the block.
404Returned when the asset with the id does not exist. or the event with the id does not exist
429Returned when a user exceeds their subscription’s rate limit for requests.

get  /archivist/v1/archivistnode:openapi

Get OpenAPI spec for Archivistnode

Description: Get OpenAPI v2.0 spec for Archivistnode

ResponsesDescription
200A successful response.
401Returned when the user is not authenticated to the system.
429Returned when a user exceeds their subscription’s rate limit for requests.

← Public Assets API
Tenancies API →