IndependentRecords

Write, read and verify independent records on the blockchain.

Write record

post

Write a record transaction to the blockchain.

The transaction will be published to the blockchain asynchronously. Use Get record status to find out when it has been confirmed.

Query parameters
encodestringRequired

Encode the record before registering on the blockchain. Available encoders depend upon your configuration options. Possible encoders include:

  • SHA256: Encode using SHA-2 256 *
  • Base64: Makes output human-readable
  • No specified encoder: the record is not encoded.

Note * A "salt" parameter may be specified in () brackets containing any of the following characters: ASCII letters and digits, "/", ":", "-" and "+" (URL encoded as "%2B"). The "salt" parameter will be prepended to the record before encoding.

Encoders may be combined using '|'.

Header parameters
x-api-keystringRequired

{your-API-key}

Body
string · byteOptional
Responses
200
The transaction has been published. The response is a JSON structure, containing the following details: - txId: the transaction Id which is required by subsequent commands and can also be used by external tools - encoding: array of encoding steps (omitted when encoders are not used), each element defines: - contentType: output content type - output: if content type is text, it will include up to 1024 characters of the output (omitted for binary content types)
post
POST /api/v1/records?encode=text HTTP/1.1
Host: {your-URL}
x-api-key: text
Content-Type: application/octet-stream
Accept: */*
Content-Length: 10

"Ynl0ZXM="
{
  "txId": "text",
  "encoding": [
    {
      "contentType": "text",
      "output": "text"
    }
  ]
}

Get record status

get

Get the current state of a record that was written to the blockchain. It takes a few minutes before any transaction is confirmed to be on the blockchain.

Path parameters
txIdstringRequired

The transaction id of the record to query. Using a value other than a id returned by write record produces undefined behavior.

Header parameters
x-api-keystringRequired

{your-API-key}

Responses
200
The transaction has been published. The response is an application/json structure containing: - confirmation: set if transaction has been included in a valid block - confirmedBlocks: Number of confirmations (blocks) at the time of request - blockHash: block hash if transaction has been included in a block - blockTimestamp: block header timestamp (set on a best-effort basis) - merkleProof: A JSON object as defined in TSC Merkle Proof (https://tsc.bsvblockchain.org/standards/merkle-proof-standardised-format/#JSONform)
get
GET /api/v1/records/{txId}/status HTTP/1.1
Host: {your-URL}
x-api-key: text
Accept: */*

{
  "confirmation": {
    "confirmedBlocks": 1,
    "blockHash": "text",
    "blockTimestamp": "2025-06-28T02:29:14.881Z",
    "merkleProof": {
      "index": 1,
      "txOrId": "text",
      "target": "text",
      "nodes": [
        "text"
      ],
      "targetType": "text",
      "proofType": "text",
      "composite": true
    }
  }
}

Get record content

get

Get the record content. It may not be confirmed on the blockchain yet. Get record status determines when the transaction is confirmed on the blockchain.

Path parameters
txIdstringRequired

The transaction Id of the record to fetch. Using a value other than a id returned by write record produces undefined behavior.

Header parameters
x-api-keystringRequired

{your-API-key}

Responses
200
The transaction has been published. The response contains the record as an application/octet-stream
get
GET /api/v1/records/{txId}/content HTTP/1.1
Host: {your-URL}
x-api-key: text
Accept: */*

No content

Get record headers

head

Obtain information about the record (i.e. length and type) in the HTTP headers.

Path parameters
txIdstringRequired

The transaction Id of the record to fetch. Using a value other than a transaction Id returned by write record produces undefined behavior.

Header parameters
x-api-keystringRequired

{your-API-key}

Responses
200
The transaction has been published. The response is empty; HTTP headers are set as follows: - Content-Type: application/octet-stream - Content-Length: actual size of the record as it would be returned by GET record
head
HEAD /api/v1/records/{txId}/content HTTP/1.1
Host: {your-URL}
x-api-key: text
Accept: */*

No content

Verify record

post

Verify whether the supplied record matches the published record. The response indicates whether the records match, mismatch or there is an error.

If this feature is not available in your configuration, please contact us for an upgrade.

Path parameters
txIdstringRequired

The transaction id of the record to verify. Using an id other than one returned by write record produces undefined behavior.

Query parameters
encodestringRequired

The same encode parameters as used to create the record. In the case of encoders used without a "salt" parameter, this can be omitted.

Header parameters
x-api-keystringRequired

{your-API-key}

Body
string · byteOptional
Responses
200
The transaction has been published. The Response is a JSON structure containing: - match: boolean indicating whether the supplied record matches the published record - confirmation: set if transaction has been included in a valid block (same as with get status endpoint) - confirmedBlocks: Number of confirmations (blocks) at the time of request - blockHash: block hash if transaction has been included in a block - blockTimestamp: block header timestamp (field is set on best-effort basis) - merkleProof: A JSON object as defined in TSC Merkle Proof (https://tsc.bsvblockchain.org/standards/merkle-proof-standardised-format/#JSONform)
post
POST /api/v1/records/{txId}/match?encode=text HTTP/1.1
Host: {your-URL}
x-api-key: text
Content-Type: application/octet-stream
Accept: */*
Content-Length: 10

"Ynl0ZXM="
{
  "match": true,
  "confirmation": {
    "confirmedBlocks": 1,
    "blockHash": "text",
    "blockTimestamp": "2025-06-28T02:29:14.881Z",
    "merkleProof": {
      "index": 1,
      "txOrId": "text",
      "target": "text",
      "nodes": [
        "text"
      ],
      "targetType": "text",
      "proofType": "text",
      "composite": true
    }
  }
}
PreviousAPI referenceNextLinkedRecords