Skip to content

Update Asset Metadata via Commits

Overview

Updating asset metadata allows you to modify information associated with a registered asset on the blockchain. This is useful for correcting information, adding new details, or updating metadata as the asset evolves over time. Each update creates a new commit in the asset's history, maintaining a complete audit trail of all changes.

The update process uses the Numbers Storage Backend API to perform partial updates on existing assets using the PATCH method.

Prerequisites

Before updating asset metadata, ensure you have:

  1. Capture Token: You'll need a valid Capture Token for authentication
  2. Existing Asset: The asset must already be registered in the Capture system
  3. Asset Nid: The Numbers Identifier of the asset you want to update

If you don't have a Capture Token yet, please follow the instructions to create one.

Updating Asset Metadata

PATCH https://api.numbersprotocol.io/api/v3/assets/{asset_nid}/

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

Headers

Name Type Description
Authorization* String

Example

token YOUR_CAPTURE_TOKEN
Content-Type String multipart/form-data

Path Parameters

Name Type Description
asset_nid* String The Numbers Identifier of the asset to update

Request Body

The request body should contain the fields you want to update. All fields are optional:

Name Type Description
caption String Update the brief description of the asset
headline String Update the title of the asset (maximum 25 characters)
nit_commit_custom Object Update custom fields in the Asset Tree
commit_message String Custom message for this commit

Response Codes

200: Success

The asset metadata was successfully updated.

400: Bad Request

Invalid request data or insufficient funds for the transaction.

401: Unauthorized

Invalid or missing authentication token.

403: Forbidden

You don't have permission to update this asset (not the owner).

404: Not Found

The specified asset Nid does not exist or you don't have permission to access it.

Example Usage

Update Caption and Headline

Update the caption and headline of an existing asset:

curl -X PATCH 'https://api.numbersprotocol.io/api/v3/assets/bafybeie23hdjuurtc5n77vbhjx6mmrmjo3lyzmtks4eki5ibwpqjoeb3eq/' \
     -H "Authorization: token YOUR_CAPTURE_TOKEN" \
     -F 'caption=Updated description of the asset' \
     -F 'headline=New Title'

Response

{
    "id": "bafybeie23hdjuurtc5n77vbhjx6mmrmjo3lyzmtks4eki5ibwpqjoeb3eq",
    "asset_file_name": "demo.jpg",
    "asset_file_mime_type": "image/jpeg",
    "caption": "Updated description of the asset",
    "headline": "New Title",
    "updated_at": "2024-01-15T10:30:00Z"
}

Update Custom Metadata

Add or update custom fields in the Asset Tree:

curl -X PATCH 'https://api.numbersprotocol.io/api/v3/assets/bafybeie23hdjuurtc5n77vbhjx6mmrmjo3lyzmtks4eki5ibwpqjoeb3eq/' \
     -H "Authorization: token YOUR_CAPTURE_TOKEN" \
     -F 'nit_commit_custom={"tags": "Photography"}'

Response

{
    "id": "bafybeie23hdjuurtc5n77vbhjx6mmrmjo3lyzmtks4eki5ibwpqjoeb3eq",
    "asset_file_name": "demo.jpg",
    "asset_file_mime_type": "image/jpeg",
    "caption": "Updated description of the asset",
    "headline": "New Title",
    "nit_commit_custom": {
        "tags": "Photography"
    },
    "updated_at": "2024-01-15T10:35:00Z"
}

Common Use Cases

Correcting Information

If you discover errors in the original metadata, you can update specific fields without affecting other data:

curl -X PATCH 'https://api.numbersprotocol.io/api/v3/assets/YOUR_ASSET_NID/' \
     -H "Authorization: token YOUR_CAPTURE_TOKEN" \
     -F 'caption=Corrected description'

Updating License of usage

Update the license of an asset to use:

curl -X PATCH 'https://api.numbersprotocol.io/api/v3/assets/YOUR_ASSET_NID/' \
     -H "Authorization: token YOUR_CAPTURE_TOKEN" \
     -F 'nit_commit_custom={"license": {"name": "CC BY-NC-ND", "document": "https://creativecommons.org/licenses/by-nc-nd/2.0/"}}'

Adding Contextual Information

As assets are used, you may want to add additional context:

curl -X PATCH 'https://api.numbersprotocol.io/api/v3/assets/YOUR_ASSET_NID/' \
     -H "Authorization: token YOUR_CAPTURE_TOKEN" \
     -F 'nit_commit_custom={"usedBy": "https://numbersprotocol.io"}'

Error Handling

Common errors include:

  • 400: Insufficient funds (asset_commit_insufficient_fund) - Top up your wallet
  • 401: Invalid authentication token - Check your Capture Token
  • 403: Permission denied (asset_write_permission_denied) - You must own the asset to update it
  • 404: Asset not found (resource_not_found) - Verify the asset Nid is correct

All errors follow this format: 

{
  "error": {
    "type": "error_code",
    "message": "Error description",
    "details": "Additional details (optional)"
  },
  "status_code": 400
}

Important Notes

  1. Partial Updates: The PATCH method performs partial updates, meaning only the fields you specify will be modified. Other fields remain unchanged.

  2. Commit History: Each update creates a new commit in the asset's blockchain history. You can view all commits using the Read Asset History endpoint.

  3. Immutable History: While you can update metadata, the previous versions remain in the asset's history, providing a complete audit trail.

  4. Field Validation: Some fields have validation rules (e.g., headline length limit). Ensure your data meets these requirements.

  5. Authentication: Always use your Capture Token in the Authorization header. Never share your token publicly.

Pricing

The Capture API uses a pay-as-you-go pricing model:

  • API Call: 0.1 NUM per update request
  • Gas Fee: Approximately 0.079 NUM per blockchain transaction

Make sure to top up your wallet with sufficient NUM or Credits. To check current NUM prices in USD, visit CoinGecko or CoinMarketCap.