Skip to content

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: https://eo883tj75azolos.m.pipedream.net

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

Method: POST

Header:

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


Example:
curl -X POST "https://eo883tj75azolos.m.pipedream.net" \
     -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": "https://numbersprotocol.io"}
         }'
  
Response:
{
    "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:

{% tabs %} {% tab title="Python" %} 

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 = "https://eo883tj75azolos.m.pipedream.net"
# Make the request
response = requests.post(url, headers=headers, json=data)

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

# Print the txHash
print(response_data["txHash"])

{% tab title="Javascript" %} 

// Replace YOUR_CAPTURE_TOKEN with your actual token
const headers = {
    "Content-Type": "application/json",
    "Authorization": `token ${YOUR_CAPTURE_TOKEN}`
};

// Replace YOUR_ASSET_CID with the actual asset to be committed
const data = {
  "author": "0x8212099e5aF75e555A3E63da77a99CcC9527aCC1",
  "encodingFormat": "image/jpeg",
  "assetCid": YOUR_ASSET_NID,
  "assetTimestampCreated": 1674556617,
  "assetCreator": "Example User",
  "assetSha256": "32ff5bc7ec494005c01df4a8da67f7ef5a95037de2f7863e3d463b4697447739",
  "abstract": "My first Web3.0 asset"
};

const url = "https://eo883tj75azolos.m.pipedream.net";

fetch(url, {
    method: "POST",
    headers: headers,
    body: JSON.stringify(data)
})
    .then(response => response.json())
    .then(responseData => {
        console.log(responseData.txHash);
    })
    .catch(error => {
        console.error("Error:", error);
    });
{% endtab %}

Note:

  • 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 must be a valid JSON object. assetSourceType field is determined by signature and service name associated with API key and the assetSourceType put in custom field will be ignored.
  • 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
  • Avalanche (cost: 2.5 NUM): https://eox7ryteolf6eh2.m.pipedream.net
  • NEAR (cost: 1 NUM): https://eof6acukpt2bka5.m.pipedream.net

Defining Provenance

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

FieldDescriptionLimitationSample Value
abstractAsset description or asset caption255 charactersMy first Web3.0 asset
assetCreatorCreator of the asset21 charactersAlice Wu
licenseNameAsset license chosen21 charactersBY-NC-ND
integrityCidThe metadata Cid IPFS Cidbafkreifkyltf4sfduwp5mghyxckq7invzjwl3pl4mksiorshr7lm2y2n2y
assetTimestampCreatedCreation timestampUnix timestamp1674556617
custom: usedByHow asset is usedURLhttps://www.ipcc.ch/2022/02/28/pr-wgii-ar6/
custom: generatedByAI model which generated the asset21 charactersDall-E

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.

Action

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