{ "openapi": "3.0.1", "info": { "title": "nChainEvent API", "version": "v1" }, "x-hideTryItPanel": true, "paths": { "{your-URL}/api/v1/records": { "post": { "tags": ["IndependentRecords"], "summary": "Write record", "description": "Write a record transaction to the blockchain.\r\n\r\nThe transaction will be published to the blockchain asynchronously. Use Get linked record status to find out when it has been confirmed.", "parameters": [ { "name": "x-api-key", "in": "header", "description": "{your-API-key}", "required": true, "schema": { "type": "string" } }, { "name": "encode", "in": "query", "description": "Encode the record before registering on the blockchain.\r\nAvailable encoders depend upon your configuration options.\r\nPossible encoders include:\r\n - SHA256: Encode using SHA-2 256 *\r\n - Base64: Makes output human-readable\r\n - No specified encoder: the record is not encoded.\r\n\r\nNote * 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.\r\n\r\nEncoders may be combined using '|'. Example: SHA256(23:59:59.123)|Base64\r\n", "schema": { "type": "string" } } ], "requestBody": { "description": "Record to be included in the transaction output as an application/octet-stream", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "byte" } } } }, "responses": { "200": { "description": "The transaction has been published.\r\nThe response is a JSON structure, containing the following details:\r\n - txId: the transaction Id which is required by subsequent commands and can also be used by external tools\r\n - encoding: array of encoding steps (omitted when encoders are not used), each element defines:\r\n - contentType: output content type\r\n - output: if content type is text, it will include up to 1024 characters of the output (omitted for binary content types)", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/RecordCreate" } }, "application/json": { "schema": { "$ref": "#/components/schemas/RecordCreate" } }, "text/json": { "schema": { "$ref": "#/components/schemas/RecordCreate" } } } }, "400": { "description": "Invalid request.\r\nResponse is a JSON structure conforming to https://tools.ietf.org/html/rfc7807. It contains the following details:\r\n - errorCode: which can be one of:\r\n - CONTENT_LENGTH_LIMIT_EXCEEDED: Request body was bigger than configured limit for this service\r\n - CONTENT_BAD_ENCODER: Request was using encoder that is not allowed for this service instance\r\n - CONTENT_ENCODER_ARGUMENT_MISSING: Request was using encoder with missing argument that is not allowed for this service instance\r\n - ENCODE_PARAM_INVALID: Encode parameter does not resolve to a valid encoding specification", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "An internal error occurred. Retry later.\r\nThe Response is a JSON structure conforming to https://tools.ietf.org/html/rfc7807", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "{your-URL}/api/v1/records/{txId}/status": { "get": { "tags": ["IndependentRecords"], "summary": "Get record status", "description": "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.", "parameters": [ { "name": "x-api-key", "in": "header", "description": "{your-API-key}", "required": true, "schema": { "type": "string" } }, { "name": "txId", "in": "path", "description": "The transaction id of the record to query.\r\nUsing a value other than a id returned by write record produces undefined behavior.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The transaction has been published.\r\nThe response is an application/json structure containing:\r\n -\tconfirmation: set if transaction has been included in a valid block\r\n - confirmedBlocks: Number of confirmations (blocks) at the time of request\r\n - blockHash: block hash if transaction has been included in a block\r\n - blockTimestamp: block header timestamp (set on a best-effort basis)\r\n - merkleProof: A JSON object as defined in TSC Merkle Proof (https://tsc.bsvblockchain.org/standards/merkle-proof-standardised-format/#JSONform)", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/RecordStatus" } }, "application/json": { "schema": { "$ref": "#/components/schemas/RecordStatus" } }, "text/json": { "schema": { "$ref": "#/components/schemas/RecordStatus" } } } }, "400": { "description": "Invalid request.\r\nThe response is a JSON structure conforming to https://tools.ietf.org/html/rfc7807.\r\nIt contains the following details:\r\n - errorCode: which can be one of:\r\n - TX_ID_PARAM_INVALID: Provided transaction id parameter is not a valid blockchain transaction id", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "The transaction cannot be read from the blockchain.\r\nIt could either still be in the process of publishing or the blockchain has rejected it.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "An internal error occurred. Retry later.\r\nThe Response is a JSON structure conforming to https://tools.ietf.org/html/rfc7807", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "{your-URL}/api/v1/records/{txId}/content": { "get": { "tags": ["IndependentRecords"], "summary": "Get record content", "description": "Get the record content. It may not be confirmed on the blockchain yet.\r\nGet record status determines when the transaction is confirmed on the blockchain.", "parameters": [ { "name": "x-api-key", "in": "header", "description": "{your-API-key}", "required": true, "schema": { "type": "string" } }, { "name": "txId", "in": "path", "description": "The transaction Id of the record to fetch.\r\nUsing a value other than a id returned by write record produces undefined behavior.", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid request. The response is in JSON structure conforming to https://tools.ietf.org/html/rfc7807.\r\nIt contains an error code and description of the error.\r\n - 'errorCode' can be one of:\r\n - TX_ID_PARAM_INVALID: Provided transaction id parameter is not a valid blockchain transaction id\r\n - TX_NOT_AN_EVENT_TRANSACTION: Transaction is not an nChain Event record transaction\r\n - TX_CONTENT_TYPE_NOT_SUPPORTED: Transaction is not supported by this nChain Event version", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "The transaction cannot be read from the blockchain.\r\nIt could either still be in the process of publishing or the blockchain has rejected it.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "An internal error occurred. Retry later.\r\nThe Response is a JSON conforming to https://tools.ietf.org/html/rfc7807", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "200": { "description": "The transaction has been published.\r\nThe response contains the record as an application/octet-stream" } } }, "head": { "tags": ["IndependentRecords"], "summary": "Get record headers", "description": "Obtain information about the record (i.e. length and type) in the HTTP headers.", "parameters": [ { "name": "x-api-key", "in": "header", "description": "{your-API-key}", "required": true, "schema": { "type": "string" } }, { "name": "txId", "in": "path", "description": "The transaction Id of the record to fetch.\r\nUsing a value other than a transaction Id returned by write record produces undefined behavior.", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid request." }, "404": { "description": "The transaction cannot be read from the blockchain.\r\nIt could either still be in the process of publishing or the blockchain has rejected it." }, "500": { "description": "An internal error occurred. Retry later." }, "200": { "description": "The transaction has been published.\r\nThe response is empty; HTTP headers are set as follows:\r\n - Content-Type: application/octet-stream\r\n - Content-Length: actual size of the record as it would be returned by GET record" } } } }, "{your-URL}/api/v1/records/{txId}/match": { "post": { "tags": ["IndependentRecords"], "summary": "Verify record", "description": "Verify whether the supplied record matches the published record.\r\nThe response indicates whether the records match, mismatch or there is an error.", "parameters": [ { "name": "x-api-key", "in": "header", "description": "{your-API-key}", "required": true, "schema": { "type": "string" } }, { "name": "txId", "in": "path", "description": "The transaction id of the record to verify.\r\nUsing an id other than one returned by write record produces undefined behavior.", "required": true, "schema": { "type": "string" } }, { "name": "encode", "in": "query", "description": "The same encode parameters as used to create the record.\r\nIn the case of encoders used without a \"salt\" parameter, this can be omitted.", "schema": { "type": "string" } } ], "requestBody": { "description": "Record to be matched against the published record", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "byte" } } } }, "responses": { "200": { "description": "The transaction has been published.\r\nThe Response is a JSON structure containing:\r\n - match: boolean indicating whether the supplied record matches the published record\r\n -\tconfirmation: set if transaction has been included in a valid block (same as with get status endpoint)\r\n - confirmedBlocks: Number of confirmations (blocks) at the time of request\r\n - blockHash: block hash if transaction has been included in a block\r\n - blockTimestamp: block header timestamp (field is set on best-effort basis)\r\n - merkleProof: A JSON object as defined in TSC Merkle Proof (https://tsc.bsvblockchain.org/standards/merkle-proof-standardised-format/#JSONform)", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/RecordMatch" } }, "application/json": { "schema": { "$ref": "#/components/schemas/RecordMatch" } }, "text/json": { "schema": { "$ref": "#/components/schemas/RecordMatch" } } } }, "400": { "description": "Invalid request. The response is a JSON structure conforming to https://tools.ietf.org/html/rfc7807.\r\nIt contains an error code and description of the error.\r\n - errorCode can be one of:\r\n - TX_ID_PARAM_INVALID: Provided transaction id parameter is not a valid blockchain transaction id\r\n - TX_NOT_AN_EVENT_TRANSACTION: Provided transaction hash is not an nChain Event record transaction", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "The transaction cannot be read from the blockchain.\r\nIt could either still be in the process of publishing or the blockchain has rejected it.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "An internal error occurred. Retry later.\r\nThe Response is a JSON structure conforming to https://tools.ietf.org/html/rfc7807", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "{your-URL}/api/v1/linkedrecords": { "post": { "tags": ["LinkedRecords"], "summary": "Create linked record", "description": "Create a linked record transaction.\r\n\r\nThe transaction will be published to the blockchain asynchronously. Use Get linked record status to find out when it has been confirmed.", "parameters": [ { "name": "x-api-key", "in": "header", "description": "{your-API-key}", "required": true, "schema": { "type": "string" } }, { "name": "encode", "in": "query", "description": "Encode the record before registering on the blockchain.\r\nAvailable encoders depend upon your configuration options.\r\nPossible encoders include:\r\n - SHA256: Encode using SHA-2 256 *\r\n - Base64: Makes output human-readable\r\n - No specified encoder: the record is not encoded.\r\n\r\nNote * 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.\r\n\r\nEncoders may be combined using '|'. Example: SHA256(23:59:59.123)|Base64\r\n", "schema": { "type": "string" } } ], "requestBody": { "description": "Record to be included in the transaction output as an application/octet-stream", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "byte" } } } }, "responses": { "200": { "description": "The transaction has been published.\r\nThe response is a JSON structure, containing the following details:\r\n - txId: the transaction Id which is required by subsequent commands and can also be used by external tools\r\n - encoding: array of encoding steps (omitted when encoders are not used), each element defines:\r\n - contentType: output content type\r\n - output: if content type is a text, it will include up to 1024 characters of the output (omitted for other content types)\r\n - update_token: URL encoded JSON Structure containing:\r\n - key alias\r\n - key derivation path\r\n - locking script\r\n - output value", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/LinkedRecords" } }, "application/json": { "schema": { "$ref": "#/components/schemas/LinkedRecords" } }, "text/json": { "schema": { "$ref": "#/components/schemas/LinkedRecords" } } } }, "400": { "description": "Invalid request.\r\nThe response is a JSON structure conforming to https://tools.ietf.org/html/rfc7807. It contains the following details:\r\n - errorCode: which can be one of:\r\n - CONTENT_LENGTH_LIMIT_EXCEEDED: Request body was bigger than configured limit for this service\r\n - CONTENT_BAD_ENCODER: Request was using encoder that is not allowed for this service instance\r\n - CONTENT_ENCODER_ARGUMENT_MISSING: Request was using encoder with missing argument that is not allowed for this service instance\r\n - ENCODE_PARAM_INVALID: Encode parameter does not resolve to a valid encoding specification", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "An internal error occurred. Retry later.\r\nThe response is a JSON structure conforming to https://tools.ietf.org/html/rfc7807", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "{your-URL}/api/v1/linkedrecords/{txId}/update": { "post": { "tags": ["LinkedRecords"], "summary": "Update linked record", "description": "Update the supplied linked record by linking it to a new linked record transaction.\r\n\r\nThe transaction will be published to the blockchain asynchronously. Use Get linked record status to find out when it has been confirmed.", "parameters": [ { "name": "x-api-key", "in": "header", "description": "{your-API-key}", "required": true, "schema": { "type": "string" } }, { "name": "txId", "in": "path", "description": "The transaction id of the linked record to update.", "required": true, "schema": { "type": "string" } }, { "name": "updateToken", "in": "query", "description": "Optional, if specified it must be the updateToken returned from the creation of the supplied linked record.", "schema": { "type": "string" } }, { "name": "encode", "in": "query", "description": "Encode the record before registering on the blockchain.\r\nAvailable encoders depend upon your configuration options.\r\nPossible encoders include:\r\n - SHA256: Encode using SHA-2 256 *\r\n - Base64: Makes output human-readable\r\n - No specified encoder: the record is not encoded.\r\n\r\nNote * 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.\r\n\r\nEncoders may be combined using '|'. Example: SHA256(23:59:59.123)|Base64\r\n", "schema": { "type": "string" } } ], "requestBody": { "description": "Record to be included in the transaction output as an application/octet-stream", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "byte" } } } }, "responses": { "200": { "description": "The transaction has been published.\r\nThe response is a JSON structure. It contains the following details:\r\n - txId: the transaction Id which is required by subsequent commands and can also be used by external tools\r\n - encoding: array of encoding steps (omitted when encoders are not used), each element defines:\r\n - contentType: output content type\r\n - output: if content type is a text, it will include up to 1024 characters of the output (omitted for other content types)\r\n - update_token: URL encoded(base64) JSON Structure containing:\r\n - key alias\r\n - key derivation path\r\n - locking script\r\n - output value", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/LinkedRecords" } }, "application/json": { "schema": { "$ref": "#/components/schemas/LinkedRecords" } }, "text/json": { "schema": { "$ref": "#/components/schemas/LinkedRecords" } } } }, "400": { "description": "Invalid request.\r\nThe Response is a JSON structure conforming to https://tools.ietf.org/html/rfc7807. It contains the following details:\r\n - errorCode: which can be one of:\r\n - CONTENT_LENGTH_LIMIT_EXCEEDED: Request body was bigger than configured limit for this service\r\n - CONTENT_BAD_ENCODER: Request was using encoder that is not allowed for this service instance\r\n - CONTENT_ENCODER_ARGUMENT_MISSING: Request was using encoder with missing argument that is not allowed for this service instance\r\n - ENCODE_PARAM_INVALID: Encode parameter does not resolve to a valid encoding specification\r\n - TX_HASH_PARM_INVALID: Provided transaction hash parameter is not a valid blockchain transaction hash\r\n - TX_NOT_AN_EVENT_TRANSACTION: Provided transaction hash is not nChain Event data transaction. This error cannot occur if updateToken is specified as there is no need to fetch the transaction in order to get information about chain output to use.Actual acceptance by the miner will probably still fail.\r\n - TX_NOT_LINKABLE: Transaction is not linkable\r\n - UPDATE_TOKEN_PARAM_INVALID: update_token request parameter is set to invalid value", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "An internal error occurred. Retry later.\r\nThe Response is a JSON structure conforming to https://tools.ietf.org/html/rfc7807", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "The transaction cannot be read from the blockchain. It could either still be in the process of publishing or the blockchain has rejected it. \r\nThis error cannot occur if updateToken is specified as there is no need to fetch the transaction in order to get information about the output link to use.\r\nActual acceptance by the blockchain can still fail for the same reasons that fetching would fail." } } } }, "{your-URL}/api/v1/linkedrecords/{txId}/delete": { "post": { "tags": ["LinkedRecords"], "summary": "Delete linked record", "description": "Delete/Terminate/Finalise the supplied linked record by linking it to a new empty transaction.\r\n\r\nThe transaction will be published to the blockchain asynchronously. Use Get linked record status to find out when it has been confirmed.", "parameters": [ { "name": "x-api-key", "in": "header", "description": "{your-API-key}", "required": true, "schema": { "type": "string" } }, { "name": "txId", "in": "path", "description": "The transaction id of the linked record to delete", "required": true, "schema": { "type": "string" } }, { "name": "updateToken", "in": "query", "description": "Optional, if specified it must be the updateToken returned from the creation of the supplied linked record.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The transaction published.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/DeleteLinkedRecord" } }, "application/json": { "schema": { "$ref": "#/components/schemas/DeleteLinkedRecord" } }, "text/json": { "schema": { "$ref": "#/components/schemas/DeleteLinkedRecord" } } } }, "400": { "description": "Invalid request.\r\nThe Response is a JSON structure conforming to https://tools.ietf.org/html/rfc7807. It contains the following details:\r\n - errorCode: which can be one of:\r\n - CONTENT_LENGTH_LIMIT_EXCEEDED: Request body was bigger than configured limit for this service\r\n - TX_HASH_PARM_INVALID: Provided transaction hash parameter is not a valid blockchain transaction hash \r\n - TX_NOT_AN_EVENT_TRANSACTION: Provided transaction hash is not an nChain Event record transaction. This error cannot occur if updateToken is specified as there is no need to fetch the transaction in order to get information about the output link to use.Actual acceptance by the blockchain will probably still fail.\r\n - TX_NOT_LINKABLE: Transaction is not linkable\r\n - UPDATE_TOKEN_PARAM_INVALID: updatable request parameter is set to invalid value", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "An internal error occurred. Retry later.\r\nThe Response is a JSON structure conforming to https://tools.ietf.org/html/rfc7807", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "The transaction cannot be read from the blockchain. It could either still be in the process of publishing or the blockchain has rejected it. \r\nThis error cannot occur if updateToken is specified as there is no need to fetch the transaction in order to get information about the output link to use.\r\nActual acceptance by the blockchain can still fail for the same reasons that fetching would fail." } } } }, "{your-URL}/api/v1/linkedrecords/{txId}/status": { "get": { "tags": ["LinkedRecords"], "summary": "Get linked record status", "description": "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.", "parameters": [ { "name": "x-api-key", "in": "header", "description": "{your-API-key}", "required": true, "schema": { "type": "string" } }, { "name": "txId", "in": "path", "description": "The transaction id of the linked record to query.\r\nUsing a value other than one returned by the LinkedRecords methods produces undefined behavior.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The transaction has been published. The response is an application/json structure containing: \r\n -\tconfirmation: set if transaction has been included in a valid block\r\n - confirmedBlocks: Number of confirmations (blocks) at the time of request\r\n - blockHash: block hash if transaction has been included in a block\r\n - blockTimestamp: block header timestamp (field is set on best-effort basis)\r\n - merkleProof: A JSON object as defined in TSC Merkle Proof (https://tsc.bsvblockchain.org/standards/merkle-proof-standardised-format/#JSONform)\r\n - updatable: true if published and linked record can be updated", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/LinkedRecordStatus" } }, "application/json": { "schema": { "$ref": "#/components/schemas/LinkedRecordStatus" } }, "text/json": { "schema": { "$ref": "#/components/schemas/LinkedRecordStatus" } } } }, "400": { "description": "Invalid request.\r\nThe Response is a JSON structure conforming to https://tools.ietf.org/html/rfc7807. It contains an error code and description of the error.\r\nIt contains the following details:\r\n - errorCode: which can be one of:\r\n - TX_ID_PARAM_INVALID: Provided transaction id parameter is not a valid blockchain transaction id", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "The transaction cannot be read from the blockchain.\r\nIt could either still be in the process of publishing or the blockchain has rejected it.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "An internal error occurred. Retry later.\r\nThe Response is a JSON structure conforming to https://tools.ietf.org/html/rfc7807", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }, "{your-URL}/api/v1/linkedrecords/{txId}/content": { "get": { "tags": ["LinkedRecords"], "summary": "Get linked record", "description": "Get the linked record. It may not be confirmed on the blockchain yet.\r\n\r\nGet linked record status determines when the transaction is confirmed on the blockchain.", "parameters": [ { "name": "x-api-key", "in": "header", "description": "{your-API-key}", "required": true, "schema": { "type": "string" } }, { "name": "txId", "in": "path", "description": "The transaction Id of the linked record to fetch.\r\nUsing a value other than a transaction Id returned by the LinkedRecords methods produces undefined behavior.", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid request. The response is in JSON structure conforming to https://tools.ietf.org/html/rfc7807.\r\nIt contains an error code and description of the error.\r\n - 'errorCode' can be one of:\r\n - TX_ID_PARAM_INVALID: Provided transaction id parameter is not a valid blockchain transaction id\r\n - TX_CONTENT_TYPE_NOT_SUPPORTED: Transaction is not supported by this nChain Event version\r\n - TX_INCORRECT_EVENT_TRANSACTION_TYPE: Incorrect transaction type used to get the record", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "The transaction cannot be read from the blockchain.\r\nIt could either still be in the process of publishing or the blockchain has rejected it.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "An internal error occurred. Retry later.\r\nThe Response is a JSON conforming to https://tools.ietf.org/html/rfc7807", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "200": { "description": "The transaction has been published.\r\nThe response contains the linked record as an application/octet-stream" } } }, "head": { "tags": ["LinkedRecords"], "summary": "Get linked record headers", "description": "Obtain information about the linked record (i.e. length and type) in the HTTP headers.", "parameters": [ { "name": "x-api-key", "in": "header", "description": "{your-API-key}", "required": true, "schema": { "type": "string" } }, { "name": "txId", "in": "path", "description": "The transaction Id of the linked record to fetch.\r\nUsing a value other than a transaction Id returned by the LinkedRecords methods produces undefined behavior.", "required": true, "schema": { "type": "string" } } ], "responses": { "400": { "description": "Invalid request." }, "404": { "description": "The transaction cannot be read from the blockchain.\r\nIt could either still be in the process of publishing or the blockchain has rejected it." }, "500": { "description": "An internal error occurred. Retry later." }, "200": { "description": "The transaction has been published.\r\nThe response is empty; HTTP headers are set as follows:\r\n - Content-Type: application/octet-stream\r\n - Content-Length: actual size of the record as it would be returned by GET linked record" } } } }, "{your-URL}/api/v1/linkedrecords/{txId}/match": { "post": { "tags": ["LinkedRecords"], "summary": "Verify linked record", "description": "Verify whether the supplied link record matches the published link record.\r\nThe response indicates whether the records match, mismatch or there is an error.", "parameters": [ { "name": "x-api-key", "in": "header", "description": "{your-API-key}", "required": true, "schema": { "type": "string" } }, { "name": "txId", "in": "path", "description": "The transaction id of the record to query.\r\nUsing a value other than a id returned by the LinkedRecords methods has undefined behavior.", "required": true, "schema": { "type": "string" } }, { "name": "prevTxId", "in": "query", "description": "The Id of previous linked record which the record referred to by txId updates or deletes.\r\nThis parameter must be omitted when verifying create record.", "schema": { "type": "string" } }, { "name": "encode", "in": "query", "description": "The same encode parameters as used to create or update the record.\r\nIn the case of encoders used without a \"salt\" parameter, this can be omitted.", "schema": { "type": "string" } } ], "requestBody": { "description": "Data to be matched against the transaction content as an application/octet-stream", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "byte" } } } }, "responses": { "200": { "description": "The transaction has been published.\r\nThe response is a JSON structure containing:\r\n - match: boolean indicating whether the supplied content matches the published transaction\r\n -\tconfirmation: set if transaction has been included in a valid block (same as with get status endpoint)\r\n - confirmedBlocks: Number of confirmations (blocks) at the time of request\r\n - blockHash: block hash if transaction has been included in a block\r\n - blockTimestamp: block header timestamp (field is set on best-effort basis)\r\n - merkleProof: A JSON object as defined in TSC Merkle Proof (https://tsc.bsvblockchain.org/standards/merkle-proof-standardised-format/#JSONform)", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/RecordMatch" } }, "application/json": { "schema": { "$ref": "#/components/schemas/RecordMatch" } }, "text/json": { "schema": { "$ref": "#/components/schemas/RecordMatch" } } } }, "400": { "description": "Invalid request. Response is a JSON structure conforming to https://tools.ietf.org/html/rfc7807.\r\nIt contains an error code and description of the error.\r\n - errorCode can be one of:\r\n - TX_ID_PARAM_INVALID: Provided transaction id parameter is not a valid blockchain transaction id\r\n - TX_NOT_AN_EVENT_TRANSACTION: Provided transaction hash is not nChain Event data transaction", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "404": { "description": "The transaction cannot be read from the blockchain.\r\nIt could either still be in the process of publishing or the miner has rejected it.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "500": { "description": "An internal error occurred. Retry later.\r\nThe response is a JSON structure conforming to https://tools.ietf.org/html/rfc7807", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "text/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } } }, "components": { "schemas": { "Confirmation": { "type": "object", "properties": { "confirmedBlocks": { "type": "integer", "format": "int64" }, "blockHash": { "type": "string", "nullable": true }, "blockTimestamp": { "type": "string", "format": "date-time", "nullable": true }, "merkleProof": { "$ref": "#/components/schemas/MerkleProof" } }, "additionalProperties": false }, "DeleteLinkedRecord": { "type": "object", "properties": { "txId": { "type": "string", "nullable": true } }, "additionalProperties": false }, "LinkedRecords": { "type": "object", "properties": { "txId": { "type": "string", "nullable": true }, "updateToken": { "type": "string", "nullable": true }, "fingerprint": { "type": "string", "format": "byte", "nullable": true } }, "additionalProperties": false }, "LinkedRecordStatus": { "type": "object", "properties": { "confirmation": { "$ref": "#/components/schemas/Confirmation" }, "updatable": { "type": "boolean" } }, "additionalProperties": false }, "MerkleProof": { "type": "object", "properties": { "index": { "type": "integer", "format": "int64" }, "txOrId": { "type": "string", "nullable": true }, "target": { "type": "string", "nullable": true }, "nodes": { "type": "array", "items": { "type": "string" }, "nullable": true }, "targetType": { "type": "string", "nullable": true }, "proofType": { "type": "string", "nullable": true }, "composite": { "type": "boolean", "nullable": true } }, "additionalProperties": false }, "ProblemDetails": { "type": "object", "properties": { "type": { "type": "string", "nullable": true }, "title": { "type": "string", "nullable": true }, "status": { "type": "integer", "format": "int32", "nullable": true }, "detail": { "type": "string", "nullable": true }, "instance": { "type": "string", "nullable": true } }, "additionalProperties": {} }, "RecordCreate": { "type": "object", "properties": { "txId": { "type": "string", "nullable": true }, "fingerprint": { "type": "string", "format": "byte", "nullable": true } }, "additionalProperties": false }, "RecordMatch": { "type": "object", "properties": { "match": { "type": "boolean" }, "confirmation": { "$ref": "#/components/schemas/Confirmation" } }, "additionalProperties": false }, "RecordStatus": { "type": "object", "properties": { "confirmation": { "$ref": "#/components/schemas/Confirmation" } }, "additionalProperties": false } } }, "tags": [ { "name": "IndependentRecords", "description": "Write, read and verify independent records on the blockchain." }, { "name": "LinkedRecords", "description": "Create, read, update, delete and verify publicly linked records on the blockchain." } ] }