Numbers Protocol
Search
⌃K

Commit via API

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 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.025 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
​
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:
Python
Javascript
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"])
// 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);
});
​
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 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 .

Defining Provenance

The following table lists the key fields of the API which define the asset information.
Field
Description
Limitation
Sample Value
abstract
Asset description or asset caption
255 characters
My first Web3.0 asset
assetCreator
Creator of the asset
21 characters
Alice Wu
licenseName
Asset license chosen
21 characters
​BY-NC-ND​
integrityCid
The metadata Cid
IPFS Cid
bafkreifkyltf4sfduwp5mghyxckq7invzjwl3pl4mksiorshr7lm2y2n2y
assetTimestampCreated
Creation timestamp
Unix timestamp
1674556617
custom: usedBy
How asset is used
URL
custom: generatedBy
AI model which generated the asset
21 characters
Dall-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.