Cryptowerk Horizon™ API

Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.

Cryptowerk Horizon API (SealAPI) is a solution to verify the authenticity of data at massive scale using blockchains. With the help of Cryptowerk Horizon API you can prove the existence of a document or any other kind of data at a certain time without needing a trusted third party. This API supports high data volumes and reduces the cost of using a public blockchain. You never submit original data to Cryptowerk Horizon API, only hashes of data. This provides the highest possible security, efficiency, and ease of implementation.

Overview

Cryptowerk Horizon API writes hashes of data into the Bitcoin and Ethereum blockchain by default. Hashes will be submitted in the register call and the result contains a unique retrieval-ID. Cryptowerk bundles the collected hashes and creates a single super-hash. This super-hash is then written into the Bitcoin blockchain and Ethereum blockchain. After the super-hash has been stored in one or more blockchains, the retrieval-ID will be exchanged with a Seal. A Seal contains all information necessary to prove that the hashes registered are now part of the chosen blockchains.

The flows supported by this API are:

Hash(es) --> retrieval-ID --> Seal

The retrieval-ID for each hash can be found in the response JSON of a sucessful 'register' call.

There are two approaches to retrieve the actual Seal:

Polling

Call /verify in an interval and provide the retrievalID(s) and check for the return value. If you don't have the retrievalID, you can also use the hash originally registered. Note though that there could be duplicates returned. (Hashes are not unique)

Webhook and Callback

Specify a callback URL when registering hashes using /register. Once the Seal becomes available the Cryptowerk Horizon API will make a POST request to the URL given. The User-Agent header of the request identifies the Cryptowerk Server and is set to Cryptowerk Callback v1.

If the endpoint is unavailable, Cryptowerk will retry every 5 minutes for 12 hours total. After that period, if your HTTP endpoint did not get operational within that timeframe, you can still retrieve your seal(s) using the verify API call.

In addition to using http or https, you can also publish a message to MQTT.

Seals

A Seal contains the information required to prove that a document had been registered in a blockchain. I.e., among other things, it contains a (transaction) identifier in one or multiple blockchains, the hash of a document, the conclusive mathematical proof linking the document to the blockchain demonstrating the document's existence at registration time and it not having been tampered with, the time this document was submitted to the server and the time it was submitted to the blockchain.

API Credentials

Authentication is based on providing your API key and signing with the API secret. You can request an API key and secret in the Developer portal.

In the examples below, the API key and secret is transmitted as custom header X-API-Key. To create a valid value concatenate the API Key and secret separated by a space.

X-API-Key: V....o= A...DRM="

HttpURLConnection con = ...
con.addRequestProperty("X-API-Header", apiKey + " "+ apiSecret);

You can also transmit the information in query parameters as an alternative (see API docs below)

Base URLs:

• https://developers.cryptowerk.com/platform/API/v8

• https://developers.cryptowerk.com/platform/API/v7

• https://developers.cryptowerk.com/platform/API/v6

License: Proprietary license.

Authentication

• API Key (APIKeyHeader)
  • Parameter Name: X-API-Key, in: header. Concatenation of the API key and secret separated by a space.

Sealing

Operations related to sealing generic data items.

register

Code samples

# You can also use wget
curl -X POST https://developers.cryptowerk.com/platform/API/v8/register?hashes=1111111111111111111111111111111111111111111111111111111111111111%2C2222222222222222222222222222222222222222222222222222222222222222 \
  -H 'Accept: application/json' \
  -H 'X-API-Key: API_KEY'

URL obj = new URL("https://developers.cryptowerk.com/platform/API/v8/register?hashes=1111111111111111111111111111111111111111111111111111111111111111%2C2222222222222222222222222222222222222222222222222222222222222222");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "X-API-Key": []string{"API_KEY"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://developers.cryptowerk.com/platform/API/v8/register", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

const headers = {
  'Accept':'application/json',
  'X-API-Key':'API_KEY'
};

fetch('https://developers.cryptowerk.com/platform/API/v8/register?hashes=1111111111111111111111111111111111111111111111111111111111111111%2C2222222222222222222222222222222222222222222222222222222222222222',
{
  method: 'POST',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'X-API-Key' => 'API_KEY'
}

result = RestClient.post 'https://developers.cryptowerk.com/platform/API/v8/register',
  params: {
  'hashes' => 'string'
}, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json',
  'X-API-Key': 'API_KEY'
}

r = requests.post('https://developers.cryptowerk.com/platform/API/v8/register', params={
  'hashes': '1111111111111111111111111111111111111111111111111111111111111111,2222222222222222222222222222222222222222222222222222222222222222'
}, headers = headers)

print(r.json())

POST https://developers.cryptowerk.com/platform/API/v8/register?hashes=1111111111111111111111111111111111111111111111111111111111111111%2C2222222222222222222222222222222222222222222222222222222222222222 HTTP/1.1

Accept: application/json

POST /register

Register hashes

The register command posts a hash of a document or any data for registration on a blockchain. The blockchain entry can later be used as a mathematical proof for the existence of this data at the moment it was posted.

Parameters

Detailed descriptions

hashes: Comma separated hexadecimal representation of the hashes for the data to be registered for proof of existence.

lookupInfo: Here, you can provide your own information that later helps you in looking up your data where you want to put your seal. This can be any text string. For instance, you might have a row in your database that holds the data you want to seal. This row might have a primary key that identifies it. You can set this parameter to this primary key of yours. Later when a callback (see below) arrives or when you use the verify API call (see below), this lookupInfo is provided to you. Actually it's both in the seal itself and in the API response document. Since you know that this actually is a primary key, you can easily retrieve the database row and store the seal in a column of that row. This lookupInfo applies to all hashes provided.

lookupInfos: This parameter provides the same functionality as parameter 'lookupInfo'. However, you provide a potentially different lookupInfo for each hash as a list separated by comma.

callback: Callback specification for the registration events in the requested blockchains. You can have a callback initiated either to a URL or via an MQTT message. URL: Use 'http' as the protocol specifier, then either 'jsonplain' for a plain JSON object or 'jsonformenc' for a URL-formencoded JSON object. Then add the http or https URL to call. You can then add a format for the seal/stamp by adding a semicolon, 'stampFormat:' and either 'JSON' for JSON or 'STREAM' for a compressed binary format. Examples: http:jsonplain:https://some.site.com/5d5803df-0e8b-4779-80e8 or http:jsonformenc:http://another.com/14nv2 or http:jsonformenc:http://yetanotherwebhook.com/14nve;stampFormat:JSON

By default, query parameters that you include in the URL are stripped from it and instead included in the POST body. For 'jsonplain', a JSON attribute 'query' is added that includes the key/value pairs from the query. This is because it is generally discouraged to use query parameters, usually for a GET request, in a POST request. If, however, you insist to issue a POST request including query parameters, add 'keepQuery:true'. For instance: http:jsonplain:https://some.site.com/5d5803df-0e8b-4779-80e8?myparameter=somevalue;keepQuery:true

If you select a bulk seal in contrast to an individual seal, for the getseal API call you can choose to omit the hashes that you originally submitted from the bulk seal to save storage space and network bandwidth. The same effect can be achieved for a callback by appending the parameter ";hashSequenceKnown:true" to the callback specification. The payload of the callback will then not include the hashes themselves.

MQTT: Use 'mqtt' as the protocol specifier, then the endpoint for the message broker, a semicolon, the topic used for publishing, a semicolon, a JSON object template that might contain some id or reference for your internal use and is filled with the event in JSON format. Note that you cannot use a semicolon in the JSON template. Example: mqtt:tcp://mqttcc1.cryptowerk.com:1883;test/topic2;{myCustomId:'someid1'}

mode: Request a certain mode of operation resulting in different types of responses. individualSeal: Return individual seals, one seal per submitted hash. Since this will negatively impact performance when handling many hashes, this mode is discouraged in particular for larger numbers of hashes. bulkSeal: Return bulk seals, i.e. multiple hashes will be covered by an individual seal that optimizes both throughput, speed of operations on many hashes and/or seals, and storage requirements. Instead of requiring 1-2KB per seal for a single hash, a bulk seal requires just the hashes themselves and an additional 2KB independent of the number of hashes. The default for this parameter is determined by your account settings.

Enumerated Values

Example responses

200 Response

{
  "minSupportedAPIVersion": 8,
  "maxSupportedAPIVersion": 6,
  "documents": [
    {
      "retrievalId": "string"
    }
  ]
}

Responses

post__getseal

Code samples

# You can also use wget
curl -X POST https://developers.cryptowerk.com/platform/API/v8/getseal \
  -H 'Accept: application/json' \
  -H 'X-API-Key: API_KEY'

URL obj = new URL("https://developers.cryptowerk.com/platform/API/v8/getseal");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "X-API-Key": []string{"API_KEY"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://developers.cryptowerk.com/platform/API/v8/getseal", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

const headers = {
  'Accept':'application/json',
  'X-API-Key':'API_KEY'
};

fetch('https://developers.cryptowerk.com/platform/API/v8/getseal',
{
  method: 'POST',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'X-API-Key' => 'API_KEY'
}

result = RestClient.post 'https://developers.cryptowerk.com/platform/API/v8/getseal',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json',
  'X-API-Key': 'API_KEY'
}

r = requests.post('https://developers.cryptowerk.com/platform/API/v8/getseal', headers = headers)

print(r.json())

POST https://developers.cryptowerk.com/platform/API/v8/getseal HTTP/1.1

Accept: application/json

POST /getseal

Parameters

Detailed descriptions

retrievalId: This is the retrievalId that was returned in a previous 'register' call.

retrievalIds: Here you can specify more than one 'retrievalId' in order to check more than one previously submitted registration status.

hashSequenceKnown: If a bulk seal is requested, the "allHashes" member will be omitted. This saves both storage space for the seal and network bandwidth since "allHashes" is the only part of a bulk seal that depends on the number of hashes and could become large. However, this requires you to know the hashes or the data itself that you hashed (that's usually the case) and the sequence in which you submitted them (usually also true but depends on the way data or hashes are stored on your side).

Example responses

200 Response

{
  "minSupportedAPIVersion": 8,
  "maxSupportedAPIVersion": 6,
  "documents": [
    {
      "retrievalId": "string",
      "seal": {
        "documentInfo": {
          "submittedAt": 0
        },
        "version": 8,
        "isComplete": true,
        "proofs": [
          {
            "bundleMethod": "BALANCED_MERKLE_TREE",
            "operations": [
              {
                "opcode": "DOC_SHA256",
                "docHash": "181210f8f9c779c26da1d9b2075bde0127302ee0e3fca38c9a83f5b1dd8e5d3b"
              }
            ]
          }
        ],
        "name": "string",
        "submittedAt": 0,
        "contentType": "string",
        "hasBeenInsertedIntoAtLeastOneBlockchain": true,
        "hasBeenInsertedIntoAllRequestedBlockchains": true,
        "blockchainRegistrations": [
          {
            "blockChainId": "string",
            "insertedIntoBlockchainAt": 0,
            "blockChainDesc": {
              "instanceName": "string",
              "generalName": "string"
            },
            "bcExplorerUrls": [
              "string"
            ]
          }
        ]
      }
    }
  ]
}

Responses

Response Schema

Status Code 200

oneOf

xor

xor

xor

xor

xor

continued

Enumerated Values

post__verifyseal

Code samples

# You can also use wget
curl -X POST https://developers.cryptowerk.com/platform/API/v8/verifyseal?verifyDocHashes=string&seals=string \
  -H 'Accept: application/json' \
  -H 'X-API-Key: API_KEY'

URL obj = new URL("https://developers.cryptowerk.com/platform/API/v8/verifyseal?verifyDocHashes=string&seals=string");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "X-API-Key": []string{"API_KEY"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://developers.cryptowerk.com/platform/API/v8/verifyseal", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

const headers = {
  'Accept':'application/json',
  'X-API-Key':'API_KEY'
};

fetch('https://developers.cryptowerk.com/platform/API/v8/verifyseal?verifyDocHashes=string&seals=string',
{
  method: 'POST',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'X-API-Key' => 'API_KEY'
}

result = RestClient.post 'https://developers.cryptowerk.com/platform/API/v8/verifyseal',
  params: {
  'verifyDocHashes' => 'string',
'seals' => 'string'
}, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json',
  'X-API-Key': 'API_KEY'
}

r = requests.post('https://developers.cryptowerk.com/platform/API/v8/verifyseal', params={
  'verifyDocHashes': 'string',  'seals': 'string'
}, headers = headers)

print(r.json())

POST https://developers.cryptowerk.com/platform/API/v8/verifyseal?verifyDocHashes=string&seals=string HTTP/1.1

Accept: application/json

POST /verifyseal

Parameters

Detailed descriptions

verifyDocHashes: This call is used to verify a previously issued seal.

Note that instead you also can verify that yourself. We provide software in source code for that purpose. This ensures that you don't have to rely on us to be able to prove the existence of a registration to anyone. However, you might want to use this verification service for convenience. This parameter contains a comma-separated list of hex- or base64-encoded hashes of the document(s) you want to check against a previous registration. An example value would be: 1111111111111111111111111111111111111111111111111111111111111111, 2222222222222222222222222222222222222222222222222222222222222222

Example responses

200 Response

{
  "minSupportedAPIVersion": 8,
  "maxSupportedAPIVersion": 6,
  "documents": [
    {
      "retrievalId": "string",
      "seal": {
        "documentInfo": {
          "submittedAt": 0
        },
        "version": 8,
        "isComplete": true,
        "proofs": [
          {
            "bundleMethod": "BALANCED_MERKLE_TREE",
            "operations": [
              {
                "opcode": "DOC_SHA256",
                "docHash": "181210f8f9c779c26da1d9b2075bde0127302ee0e3fca38c9a83f5b1dd8e5d3b"
              }
            ]
          }
        ],
        "name": "string",
        "submittedAt": 0,
        "contentType": "string",
        "hasBeenInsertedIntoAtLeastOneBlockchain": true,
        "hasBeenInsertedIntoAllRequestedBlockchains": true,
        "blockchainRegistrations": [
          {
            "blockChainId": "string",
            "insertedIntoBlockchainAt": 0,
            "blockChainDesc": {
              "instanceName": "string",
              "generalName": "string"
            },
            "bcExplorerUrls": [
              "string"
            ]
          }
        ]
      }
    }
  ]
}

Responses

Response Schema

Status Code 200

oneOf

xor

xor

xor

xor

xor

continued

Enumerated Values

post__cancelAllCallbacks

Code samples

# You can also use wget
curl -X POST https://developers.cryptowerk.com/platform/API/v8/cancelAllCallbacks \
  -H 'X-API-Key: API_KEY'

URL obj = new URL("https://developers.cryptowerk.com/platform/API/v8/cancelAllCallbacks");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "X-API-Key": []string{"API_KEY"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://developers.cryptowerk.com/platform/API/v8/cancelAllCallbacks", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

const headers = {
  'X-API-Key':'API_KEY'
};

fetch('https://developers.cryptowerk.com/platform/API/v8/cancelAllCallbacks',
{
  method: 'POST',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'X-API-Key' => 'API_KEY'
}

result = RestClient.post 'https://developers.cryptowerk.com/platform/API/v8/cancelAllCallbacks',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'X-API-Key': 'API_KEY'
}

r = requests.post('https://developers.cryptowerk.com/platform/API/v8/cancelAllCallbacks', headers = headers)

print(r.json())

POST https://developers.cryptowerk.com/platform/API/v8/cancelAllCallbacks HTTP/1.1

POST /cancelAllCallbacks

Cancel all pending callbacks belonging to your account. This is mainly useful for debugging in case your provided callback endpoint is under development. Then it may be that it is either not reachable or that it returns error codes. Instead of continuing to retry to invoke the callback you can clear the pending callbacks.

Parameters

Responses

Schemas

Empty

{}

Empty Schema

Properties

None

Seal

{
  "bundleMethod": "BALANCED_MERKLE_TREE",
  "operations": [
    {
      "opcode": "DOC_SHA256",
      "docHash": "181210f8f9c779c26da1d9b2075bde0127302ee0e3fca38c9a83f5b1dd8e5d3b"
    }
  ]
}

Properties

oneOf

xor

xor

xor

xor

xor

Enumerated Values

Registration

{
  "minSupportedAPIVersion": 8,
  "maxSupportedAPIVersion": 6,
  "documents": [
    {
      "retrievalId": "string"
    }
  ]
}

Properties

Verification

{
  "minSupportedAPIVersion": 8,
  "maxSupportedAPIVersion": 6,
  "documents": [
    {
      "retrievalId": "string",
      "seal": {
        "documentInfo": {
          "submittedAt": 0
        },
        "version": 8,
        "isComplete": true,
        "proofs": [
          {
            "bundleMethod": "BALANCED_MERKLE_TREE",
            "operations": [
              {
                "opcode": "DOC_SHA256",
                "docHash": "181210f8f9c779c26da1d9b2075bde0127302ee0e3fca38c9a83f5b1dd8e5d3b"
              }
            ]
          }
        ],
        "name": "string",
        "submittedAt": 0,
        "contentType": "string",
        "hasBeenInsertedIntoAtLeastOneBlockchain": true,
        "hasBeenInsertedIntoAllRequestedBlockchains": true,
        "blockchainRegistrations": [
          {
            "blockChainId": "string",
            "insertedIntoBlockchainAt": 0,
            "blockChainDesc": {
              "instanceName": "string",
              "generalName": "string"
            },
            "bcExplorerUrls": [
              "string"
            ]
          }
        ]
      }
    }
  ]
}

Properties