Event API Reference
V.1.5 API
V.1.5 API
  • About
  • Version History
  • API reference
    • IndependentRecords
    • LinkedRecords
    • Models
Powered by GitBook
On this page
  1. API reference

IndependentRecords

PreviousAPI referenceNextLinkedRecords

Write, read and verify independent records on the blockchain.

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
400
Invalid request. The response is in JSON structure conforming to https://tools.ietf.org/html/rfc7807. It contains an error code and description of the error. - 'errorCode' can be one of: - TX_ID_PARAM_INVALID: Provided transaction id parameter is not a valid blockchain transaction id - NOT_AN_EVENT_TRANSACTION: Transaction is not an Event record transaction - TX_CONTENT_TYPE_NOT_SUPPORTED: Transaction is not supported by this Event version
404
The transaction cannot be read from the blockchain. It could either still be in the process of publishing or the blockchain has rejected it.
500
An internal error occurred. Retry later. The Response is a JSON conforming to https://tools.ietf.org/html/rfc7807
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
400
Invalid request.
404
The transaction cannot be read from the blockchain. It could either still be in the process of publishing or the blockchain has rejected it.
500
An internal error occurred. Retry later.
head
HEAD /api/v1/records/{txId}/content HTTP/1.1
Host: {your-URL}
x-api-key: text
Accept: */*

No content
  • POSTWrite record
  • GETGet record status
  • GETGet record content
  • HEADGet record headers
  • POSTVerify record

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)
400
Invalid request. The response is a JSON structure conforming to https://tools.ietf.org/html/rfc7807. It contains the following details: - errorCode: which can be one of: - TX_ID_PARAM_INVALID: Provided transaction id parameter is not a valid blockchain transaction id
404
The transaction cannot be read from the blockchain. It could either still be in the process of publishing or the blockchain has rejected it.
500
An internal error occurred. Retry later. The Response is a JSON structure conforming to https://tools.ietf.org/html/rfc7807
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-02T13:26:28.736Z",
    "merkleProof": {
      "index": 1,
      "txOrId": "text",
      "target": "text",
      "nodes": [
        "text"
      ],
      "targetType": "text",
      "proofType": "text",
      "composite": true
    }
  }
}

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)
400
Invalid request. Response is a JSON structure conforming to https://tools.ietf.org/html/rfc7807. It contains the following details: - errorCode: which can be one of: - CONTENT_LENGTH_LIMIT_EXCEEDED: Request body is bigger than the configured limit - ENCODER_SHA256_MISSING: Request was missing an encoder required for this configuration - ENCODER_ARGUMENT_MISSING: Request is missing an argument that is required for this configuration - ENCODE_PARAM_INVALID: Encode parameter does not resolve to a valid encoding specification
500
An internal error occurred. Retry later. The Response is a JSON structure conforming to https://tools.ietf.org/html/rfc7807
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"
    }
  ]
}

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)
400
Invalid request. The response is a JSON structure conforming to https://tools.ietf.org/html/rfc7807. It contains an error code and description of the error. - errorCode can be one of: - TX_ID_PARAM_INVALID: Provided transaction id parameter is not a valid blockchain transaction id - NOT_AN_EVENT_TRANSACTION: Provided transaction hash is not an Event record transaction
404
The transaction cannot be read from the blockchain. It could either still be in the process of publishing or the blockchain has rejected it.
500
An internal error occurred. Retry later. The Response is a JSON structure conforming to https://tools.ietf.org/html/rfc7807
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-02T13:26:28.736Z",
    "merkleProof": {
      "index": 1,
      "txOrId": "text",
      "target": "text",
      "nodes": [
        "text"
      ],
      "targetType": "text",
      "proofType": "text",
      "composite": true
    }
  }
}