LinkedRecords

Create, read, update, delete and verify publicly linked records on the blockchain.

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

Create linked record

post

Create a linked record transaction.

The transaction will be published to the blockchain asynchronously. Use Get linked 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 a text, it will include up to 1024 characters of the output (omitted for other content types) - update_token: URL encoded JSON Structure containing: - key alias - key derivation path - locking script - output value
post
POST /api/v1/linkedrecords?encode=text HTTP/1.1
Host: {your-URL}
x-api-key: text
Content-Type: application/octet-stream
Accept: */*
Content-Length: 10

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

Update linked record

post

Update the supplied linked record by linking it to a new linked record transaction.

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

Path parameters
txIdstringRequired

The transaction id of the linked record to update.

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 '|'.

updateTokenstringOptional

Optional, if specified it must be the updateToken returned from the creation of the supplied linked record.

Header parameters
x-api-keystringRequired

{your-API-key}

Body
string · byteOptional
Responses
200
The transaction has been published. The response is a JSON structure. It contains 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 a text, it will include up to 1024 characters of the output (omitted for other content types) - update_token: URL encoded(base64) JSON Structure containing: - key alias - key derivation path - locking script - output value
post
POST /api/v1/linkedrecords/{txId}/update?encode=text HTTP/1.1
Host: {your-URL}
x-api-key: text
Content-Type: application/octet-stream
Accept: */*
Content-Length: 10

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

Delete linked record

post

Delete/Terminate/Finalise the supplied linked record by linking it to a new empty transaction.

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

Path parameters
txIdstringRequired

The transaction id of the linked record to delete

Query parameters
updateTokenstringOptional

Optional, if specified it must be the updateToken returned from the creation of the supplied linked record.

Header parameters
x-api-keystringRequired

{your-API-key}

Responses
200
The transaction has been published.
post
POST /api/v1/linkedrecords/{txId}/delete HTTP/1.1
Host: {your-URL}
x-api-key: text
Accept: */*

{
  "txId": "text"
}

Get linked record status

get

Get the current state of a linked 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 linked record to query. Using a value other than one returned by the LinkedRecords methods 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 (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) - updatable: true if published and linked record can be updated
get
GET /api/v1/linkedrecords/{txId}/status HTTP/1.1
Host: {your-URL}
x-api-key: text
Accept: */*

{
  "confirmation": {
    "confirmedBlocks": 1,
    "blockHash": "text",
    "blockTimestamp": "2025-07-18T17:38:33.219Z",
    "merkleProof": {
      "index": 1,
      "txOrId": "text",
      "target": "text",
      "nodes": [
        "text"
      ],
      "targetType": "text",
      "proofType": "text",
      "composite": true
    }
  },
  "updatable": true
}

Get linked record

get

Get the linked record. It may not be confirmed on the blockchain yet.

Get linked record status determines when the transaction is confirmed on the blockchain.

Path parameters
txIdstringRequired

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

Header parameters
x-api-keystringRequired

{your-API-key}

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

No content

Get linked record headers

head

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

Path parameters
txIdstringRequired

The transaction Id of the linked record to fetch. Using a value other than a transaction Id returned by the LinkedRecords methods 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 linked record
head
HEAD /api/v1/linkedrecords/{txId}/content HTTP/1.1
Host: {your-URL}
x-api-key: text
Accept: */*

No content

Verify linked record

post

Verify whether the supplied link record matches the published link 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 query. Using a value other than a id returned by the LinkedRecords methods has undefined behavior.

Query parameters
encodestringRequired

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

prevTxIdstringOptional

The Id of previous linked record which the record referred to by txId updates or deletes. This parameter must be omitted when verifying create record.

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 content matches the published transaction - 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/linkedrecords/{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-07-18T17:38:33.219Z",
    "merkleProof": {
      "index": 1,
      "txOrId": "text",
      "target": "text",
      "nodes": [
        "text"
      ],
      "targetType": "text",
      "proofType": "text",
      "composite": true
    }
  }
}

Navigate linked records

get

Get a list of linked record transaction ids, which can be used in the GET and VERIFY commands.

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

Path parameters
txIdstringRequired

The transaction id to navigate from. Using a value other than one returned by the LinkedRecords methods produces undefined behavior.

Query parameters
linksinteger · int32Required

The direction and maximum number of links to emit. Positive numbers produce later links, negative number produce earlier links.

Header parameters
x-api-keystringRequired

{your-API-key}

Responses
200
The response is an application/json structure containing: - txIds: an array of up to the requested number of transaction ids in the requested direction. Can be empty. - endOfLinks: true if the last record in the array is the end of the linked records in the requested direction. - maxLinksRequestable: present when the links requested exceeds the maximum allowed value.
get
GET /api/v1/linkedrecords/{txId}/navigate?links=1 HTTP/1.1
Host: {your-URL}
x-api-key: text
Accept: */*

{
  "txIds": [
    "text"
  ],
  "endOfLinks": true,
  "maxLinksRequestable": 1
}
PreviousIndependentRecordsNextModels