Commit via API

Before performing commits, the initial registration should have been performed in order to make sure the accessibility of the content file from the decentralized web.

Creating commits via API is the simplest way to preserve the asset history. Here is an example of how you can use the curl command to make a POST request using your Capture Token and the Nid of the asset you want to commit. If you do not already have a Capture Token yet, please follow the instruction provided to create one. The Utilities and Scripts page shows more examples of how to create commits via API.

If you opt to use the API for committing, the committer will be the wallet of the Numbers Protocol, 0x51130dB91B91377A24d6Ebeb2a5fC02748b53ce1. However, if you prefer to have a custom committer, you can commit via nit module. This flexibility allows you to tailor your commit process to best suit your needs.

The author will still be your Capture Wallet. Anyone can trust that you created the Asset Tree by verifying the Asset Tree sha256 checksum and signature, which will result in your Capture Wallet address being displayed as the verification result.

The Numbers API is a pay-as-you-go system, which means you only pay for the API calls you make. This is a cost-effective way to use the API and it allows you to control your expenses. Make sure to top up and ensure sufficient funds in your wallet in the form of Credits or NUM to cover the cost. Payment for services is processed using NUM; if you want to know how much it costs in USD, you can check CoinGecko or CoinMarketCap.

API Endpoint:

Cost: 0.1 NUM per API call + Gas (~0.004 NUM per transaction)

Method: POST


Authorization: token $YOUR_CAPTURE_TOKEN (required)
Content-Type: application/json

Request Body (required):
encodingFormat (string): MIME type of the asset being committed
assetCid (string): Nid of the asset being committed
assetTimestampCreated (integer): Timestamp of when the asset was created
assetCreator (string): Name of the creator of the asset 
assetSha256 (string): sha256 of the asset being committed

Request Body (optional):
testnet (bool): true to commit on Testnet
author (string): Ethereum address of the author of the commit
licenseName (string): Name of the license of the asset
licenseDocument (string): Document of the license of the asset
custom (string): Custom metadata in JSON format (optional)
nftContractAddress (string): Ethereum address of the NFT contract of the asset
nftChainID (integer): Chain ID of the NFT contract
nftTokenID (string): Token ID of the NFT
commitMessage (string): The description of this commit
action (string): The action performed. More details see below.
abstract (string): asset description or caption
headline (string, optional) Headline or the title of the content file

curl -X POST "" \
     -H "Content-Type: application/json" \
     -H "Authorization: token YOUR_CAPTURE_TOKEN" \
     -d '{
              "encodingFormat": "image/jpeg",
              "assetCid": ASSET_Nid,
              "assetTimestampCreated": 1674556617,
              "assetCreator": "Example User",
              "assetSha256": "32ff5bc7ec494005c01df4a8da67f7ef5a95037de2f7863e3d463b4697447739",
              "abstract": "My first Web3.0 asset",
              "testnet": true,
              "commitMessage": "My first commit"
              "custom": {"usedBy": ""}
    "txHash": string, //transaction hash of the commit
    "assetCid": string, //asset Nid
    "assetTreeCid": string, //assetTree Nid
    "explorer": string  //network explorer

200: Asset has been committed successfully
400: Bad Request
401: Unauthorized
403: Forbidden
500: Internal Server Error

The request body follows the spec of AssetTree. More examples can be found below:

import requests
import json

# replace YOUT_CAPTURE_TOKEN with your actual token
headers = {
    "Content-Type": "application/json",
    "Authorization": "token " + YOUT_CAPTURE_TOKEN
# replace YOUR_ASSET_NID with the actual asset to be committed
data = {
  "author": "0x8212099e5aF75e555A3E63da77a99CcC9527aCC1",
  "encodingFormat": "image/jpeg",
  "assetCid": YOUR_ASSET_NID,
  "assetTimestampCreated": 1674556617,
  "assetCreator": "Example User",
  "assetSha256": "32ff5bc7ec494005c01df4a8da67f7ef5a95037de2f7863e3d463b4697447739",
  "abstract": "My first Web3.0 asset",
  "commitMessage": "My first commit"

url = ""
# Make the request
response =, headers=headers, json=data)

# Get the response in json format
response_data = json.loads(response.text)

# Print the txHash


  • All fields are in string format except for assetTimestampCreated and nftChainID which are in integer format and testnet in boolean format.

  • If licenseName or licenseDocument are not provided, both will be set to null, i.e. no license is specified.

  • custom field should be in JSON format.

  • If author is not provided, it will be set to the Integrity Wallet of the user who calls the API .

  • The API endpoints for other blockchains

Defining Provenance

The following table lists the key fields of the API which define the asset information.

FieldDescriptionLimitationSample Value


Asset description or asset caption

255 characters

My first Web3.0 asset


Creator of the asset

21 characters

Alice Wu


Asset license chosen

21 characters


The metadata Cid




Creation timestamp

Unix timestamp


custom: usedBy

How asset is used


custom: generatedBy

AI model which generated the asset

21 characters


Attaching More Metadata

If you have more metadata or provenance data that needs to be associated with the asset, you may create an IPFS metadata file and send the Cid in the integrityCid field. More metadata fields can be found on this page. You can also visit here to see the metadata example.


An action, in the context of Numbers system, is the Cid or Nid (Numbers ID) that points to the profile of an action performed to an asset. By providing the right action, one can track and record all updares performed to an asset, providing transparency and accountability.

The default action of this API is action-commit, more pre-defined actions can be found here. You may also use nit to define your custom action.

API To Commit To Other Blockchain

Last updated