Update IP Asset

Update an existing IP Asset

API scope required: nfts.update

This API is still under development. Contact support for early access.

Headers

X-API-KEY

string

required

API key required for authentication

Path Parameters

collectionId

string

required

customerFacingId

string

required

Body

application/json

Input schema for updating an existing IP asset on Story Protocol

reuploadLinkedFiles

boolean

default:true

Controls whether external files (like images) in the metadata should be reuploaded to decentralized storage (IPFS) (true) or referenced with their original URLs (false). Default is True.

Example:

true

ipAssetMetadata

object

New metadata containing information about the IP asset itself

Show child attributes

ipAssetMetadata.title

string

required

Title of the IP

ipAssetMetadata.creators

object[]

required

Information about the IP creators

IP creator metadata

Show child attributes

ipAssetMetadata.creators.name

string

required

ipAssetMetadata.creators.contributionPercent

number

required

Required range: 0 <= x <= 100

ipAssetMetadata.creators.email

string

The creator of the IP asset email

Example:

"[e-mail]"

ipAssetMetadata.creators.crossmintUserLocator

string

A internal locator for the creator of the IP asset, crossmint will automatically map this to the correct wallet address, not required if address is specified, is always required for the main creator(owner): Allowed formats:

<chain>:<address> or

email:<email_address>:<chain> or

userId:<userId>:<chain> or

twitter:<twitter_handle>:<chain>

see here for more info

Example:

[
  "email:[e-mail]:story-testnet",
  "twitter:creator:story",
  "userId:123:story-testnet",
  "0x742d35Cc6634C0532925a3b844Bc454e4438f44e:story"
]

ipAssetMetadata.creators.address

string

Wallet address of the IP creator. This field is optional only if a crossmint user locator is specified

Example:

"0x1234567890123456789012345678901234567890"

ipAssetMetadata.creators.description

string

ipAssetMetadata.creators.image

string

ipAssetMetadata.creators.socialMedia

object[]

Social media link for IP creator

Show child attributes

ipAssetMetadata.creators.socialMedia.platform

string

required

ipAssetMetadata.creators.socialMedia.url

string

required

ipAssetMetadata.creators.role

string

ipAssetMetadata.description

string

Description of the IP

ipAssetMetadata.createdAt

string

Creation date of the IP (ISO8601 or unix format)

ipAssetMetadata.relationships

object[]

The detailed relationship info with the IPA's direct parent asset, such as APPEARS_IN, FINETUNED_FROM, etc. See more examples https://docs.story.foundation/docs/ipa-metadata-standard#relationship-types

Show child attributes

ipAssetMetadata.relationships.type

string

required

ipAssetMetadata.relationships.parentIpId

string

required

Example:

[
  {
    "type": "FOLLOWS_FROM",
    "parentIpId": "0x123"
  }
]

ipAssetMetadata.media

object[]

Supporting media assets

IP media asset metadata

Show child attributes

ipAssetMetadata.media.name

string

required

ipAssetMetadata.media.url

string

required

ipAssetMetadata.media.mimeType

string

required

ipAssetMetadata.watermarkImage

string

A separate image with your watermark already applied. This way apps choosing to use it can render this version of the image (with watermark applied).

ipAssetMetadata.attributes

object[]

An array of key-value pairs that can be used for arbitrary mappings. Attribute type defined below.

Show child attributes

ipAssetMetadata.attributes.key

string

required

ipAssetMetadata.attributes.value

required

ipAssetMetadata.ipType

string

Type of the IP Asset, can be defined arbitrarily by the creator. I.e. "character", "chapter", "location", "items", "music", etc

ipAssetMetadata.tags

string[]

Any tags that can help surface this IPA

ipAssetMetadata.robotTerms

object

Allows you to set Do Not Train for a specific agent

Show child attributes

ipAssetMetadata.robotTerms.userAgent

string

required

ipAssetMetadata.robotTerms.allow

string

required

Example:

{
  "title": "Harry Potter and the Philosopher's Stone",
  "createdAt": "1997-06-26T00:00:00",
  "ipType": "literature",
  "creators": [
    {
      "name": "JK Rowling",
      "email": "[e-mail]",
      "crossmintUserLocator": "email:[e-mail]:story",
      "description": "Author",
      "contributionPercent": 80,
      "socialMedia": [
        {
          "platform": "Wikipedia",
          "url": "https://en.wikipedia.org/wiki/J._K._Rowling"
        }
      ]
    },
    {
      "name": "Thomas Taylor",
      "address": "0x1234567890123456789012345678901234567890",
      "description": "Illustrator",
      "contributionPercent": 15
    },
    {
      "name": "Bloomsbury Publishing",
      "email": "[e-mail]",
      "address": "0x1234567890123456789012345678901234567890",
      "description": "Publisher",
      "contributionPercent": 5,
      "socialMedia": [
        {
          "platform": "Website",
          "url": "https://www.bloomsbury.com/"
        }
      ]
    }
  ],
  "media": [
    {
      "name": "ePub",
      "url": "link_to_epub",
      "mimeType": "application/epub+zip"
    },
    {
      "name": "Book Summary PDF",
      "url": "link_to_book_summary_pdf",
      "mimeType": "application/pdf"
    }
  ],
  "attributes": [
    {
      "key": "ISBN",
      "value": "978-0-7475-3269-0"
    },
    { "key": "Genre", "value": "Fantasy" }
  ]
}

licenseConfig

object

Edit license config for the IP asset

Show child attributes

licenseConfig.licenseTermsId

string

required

The ID of the specific license terms to update.

Example:

"1"

licenseConfig.mintingFee

number

The new minting fee to be paid when minting license tokens. If not specified, the current minting fee will be kept

Example:

100

licenseConfig.commercialRevShare

number

The new commercial revenue share percentage (number between 0 and 100), It cannot be lower than the current commercial rev share, can only increase. If not specified, the current commercial rev share will be kept

Example:

50

licenseConfig.disabled

boolean

default:false

If true, the license terms will be disabled. Effectively removing future mints with this license.

Example:

false

Example:

{ "mintingFee": 100, "licenseTermsId": "1" }

Response

200 - application/json

IP Asset updated

Response schema for updating an existing IP asset on Story Protocol

id

string

required

The id of the IPAsset

Example:

"d290f1ee-6c54-4b01-90e6-d701748f0851"

actionId

string

required

The action id for the IPAsset creation

Example:

"d290f1ee-6c54-4b01-90e6-d701748f0851"

nftMetadata

object

required

Metadata for the NFT representation of this IP asset

Show child attributes

nftMetadata.name

string

required

nftMetadata.image

string

required

nftMetadata.description

string

required

Maximum length: 5000

nftMetadata.external_url

string

nftMetadata.animation_url

string

nftMetadata.attributes

object[]

Show child attributes

nftMetadata.attributes.trait_type

string

required

nftMetadata.attributes.value

required

nftMetadata.attributes.display_type

string

nftMetadata.uri

string

Example:

{
  "name": "Art #123",
  "description": "A unique story NFT",
  "image": "https://example.com/nft/123.png"
}

ipAssetMetadata

object

required

Metadata containing information about the IP asset itself

Show child attributes

ipAssetMetadata.title

string

required

Title of the IP

ipAssetMetadata.creators

object[]

required

Information about the IP creators

IP creator metadata

Show child attributes

ipAssetMetadata.creators.name

string

required

ipAssetMetadata.creators.contributionPercent

number

required

Required range: 0 <= x <= 100

ipAssetMetadata.creators.email

string

The creator of the IP asset email

Example:

"[e-mail]"

ipAssetMetadata.creators.crossmintUserLocator

string

A internal locator for the creator of the IP asset, crossmint will automatically map this to the correct wallet address, not required if address is specified, is always required for the main creator(owner): Allowed formats:

<chain>:<address> or

email:<email_address>:<chain> or

userId:<userId>:<chain> or

twitter:<twitter_handle>:<chain>

see here for more info

Example:

[
  "email:[e-mail]:story-testnet",
  "twitter:creator:story",
  "userId:123:story-testnet",
  "0x742d35Cc6634C0532925a3b844Bc454e4438f44e:story"
]

ipAssetMetadata.creators.address

string

Wallet address of the IP creator. This field is optional only if a crossmint user locator is specified

Example:

"0x1234567890123456789012345678901234567890"

ipAssetMetadata.creators.description

string

ipAssetMetadata.creators.image

string

ipAssetMetadata.creators.socialMedia

object[]

Social media link for IP creator

Show child attributes

ipAssetMetadata.creators.socialMedia.platform

string

required

ipAssetMetadata.creators.socialMedia.url

string

required

ipAssetMetadata.creators.role

string

ipAssetMetadata.description

string

Description of the IP

ipAssetMetadata.createdAt

string

Creation date of the IP (ISO8601 or unix format)

ipAssetMetadata.relationships

object[]

The detailed relationship info with the IPA's direct parent asset, such as APPEARS_IN, FINETUNED_FROM, etc. See more examples https://docs.story.foundation/docs/ipa-metadata-standard#relationship-types

Show child attributes

ipAssetMetadata.relationships.type

string

required

ipAssetMetadata.relationships.parentIpId

string

required

Example:

[
  {
    "type": "FOLLOWS_FROM",
    "parentIpId": "0x123"
  }
]

ipAssetMetadata.media

object[]

Supporting media assets

IP media asset metadata

Show child attributes

ipAssetMetadata.media.name

string

required

ipAssetMetadata.media.url

string

required

ipAssetMetadata.media.mimeType

string

required

ipAssetMetadata.watermarkImage

string

A separate image with your watermark already applied. This way apps choosing to use it can render this version of the image (with watermark applied).

ipAssetMetadata.attributes

object[]

An array of key-value pairs that can be used for arbitrary mappings. Attribute type defined below.

Show child attributes

ipAssetMetadata.attributes.key

string

required

ipAssetMetadata.attributes.value

required

ipAssetMetadata.ipType

string

Type of the IP Asset, can be defined arbitrarily by the creator. I.e. "character", "chapter", "location", "items", "music", etc

ipAssetMetadata.tags

string[]

Any tags that can help surface this IPA

ipAssetMetadata.robotTerms

object

Allows you to set Do Not Train for a specific agent

Show child attributes

ipAssetMetadata.robotTerms.userAgent

string

required

ipAssetMetadata.robotTerms.allow

string

required

Example:

{
  "title": "Harry Potter and the Philosopher's Stone",
  "createdAt": "1997-06-26T00:00:00",
  "ipType": "literature",
  "creators": [
    {
      "name": "JK Rowling",
      "email": "[e-mail]",
      "crossmintUserLocator": "email:[e-mail]:story",
      "description": "Author",
      "contributionPercent": 80,
      "socialMedia": [
        {
          "platform": "Wikipedia",
          "url": "https://en.wikipedia.org/wiki/J._K._Rowling"
        }
      ]
    },
    {
      "name": "Thomas Taylor",
      "address": "0x1234567890123456789012345678901234567890",
      "description": "Illustrator",
      "contributionPercent": 15
    },
    {
      "name": "Bloomsbury Publishing",
      "email": "[e-mail]",
      "address": "0x1234567890123456789012345678901234567890",
      "description": "Publisher",
      "contributionPercent": 5,
      "socialMedia": [
        {
          "platform": "Website",
          "url": "https://www.bloomsbury.com/"
        }
      ]
    }
  ],
  "media": [
    {
      "name": "ePub",
      "url": "link_to_epub",
      "mimeType": "application/epub+zip"
    },
    {
      "name": "Book Summary PDF",
      "url": "link_to_book_summary_pdf",
      "mimeType": "application/pdf"
    }
  ],
  "attributes": [
    {
      "key": "ISBN",
      "value": "978-0-7475-3269-0"
    },
    { "key": "Genre", "value": "Fantasy" }
  ]
}

onChain

object

required

• Option 1
• Option 2

Show child attributes

onChain.chain

string

required

The chain of the collection

Example:

"story-testnet"

onChain.contractAddress

string

required

The address of the collection on the chain

Example:

"0x123"

onChain.status

enum<string>

required

The status of the IP asset on the chain

Available options:

success

Example:

"success"

onChain.ipAssetId

string

required

The id of the IP asset on the chain. This ID is also the address of the IP Account that is bound to the IP Asset.

Example:

"d290f1ee-6c54-4b01-90e6-d701748f0851"

onChain.tokenId

string

required

The token id of the associatedNFT

Example:

"1"

onChain.txId

string

required

The transaction id of the IP asset creation on chain

Example:

"0x123"

onChain.owner

string

required

The owner of the IP asset

Example:

"0x123"

onChain.explorerLink

string

The explorer link of the ip asset

Example:

"https://explorer.story.foundation/ipa/0xAC6062FF53fa41e61Fe01B89B83d9dB96b5F9280"

licenseTerms

object[]

Licensing parameters for the IP asset, NOTE: For detailed and updated license terms, refer to the 'Get IP Asset License' endpoint

• Non-commercial Social Remixing License Terms
• Commercial Use License Terms
• Commercial Remix License Terms

License parameters

Show child attributes

licenseTerms.type

enum<string>

required

Available options:

non-commercial-social-remixing

licenseTerms.offChain

object

Additional license terms that are stored off-chain due to their descriptive nature

Show child attributes

licenseTerms.offChain.territory

string[]

Limit usage of the IP to certain regions and/or countries. By default, the IP can be used globally.

Example:

["United States", "European Union"]

licenseTerms.offChain.channelsOfDistribution

string[]

Restrict usage of the IP to certain media formats and channels of distribution. By default, the IP can be used across all possible channels.

Example:

[
  "television",
  "physical consumer products",
  "video games"
]

licenseTerms.offChain.attribution

object

If and how the original author should be credited for usage of the IP. By default, no credit is required.

Show child attributes

licenseTerms.offChain.attribution.required

boolean

required

licenseTerms.offChain.attribution.instructions

string

Example:

{
  "required": true,
  "instructions": "Please credit as: Original work by [Author Name]"
}

licenseTerms.offChain.contentStandards

string[]

Set content standards around use of the IP. By default, no standards apply.

Example:

[
  "No-Hate",
  "Suitable-for-All-Ages",
  "No-Drugs-or-Weapons"
]

licenseTerms.offChain.sublicensable

boolean

If true, derivative works can grant the same rights they received under this license to a 3rd party, without approval from the original licensor.

Example:

false

licenseTerms.offChain.aiLearningModels

boolean

Whether or not the IP can be used to develop AI learning models. By default, the IP cannot be used for such development.

Example:

false

licenseTerms.offChain.restrictionOnCrossPlatformUse

boolean

If true, limits licensing and creation of derivative works solely on the app on which the IP is made available.

Example:

false

licenseTerms.offChain.governingLaw

string

The laws of a certain jurisdiction by which this license abides. By default, this is California, USA.

Example:

"California, USA"

licenseTerms.offChain.alternativeDisputeResolution

object

Alternative dispute resolution mechanisms for handling disagreements

Show child attributes

licenseTerms.offChain.alternativeDisputeResolution.method

string

required

licenseTerms.offChain.alternativeDisputeResolution.details

string

required

Example:

{
  "method": "Arbitration",
  "details": "All disputes will be resolved through binding arbitration in accordance with..."
}

licenseTerms.offChain.additionalTerms

object[]

Additional license parameters or terms the licensor would like to specify

Show child attributes

licenseTerms.offChain.additionalTerms.term

string

required

licenseTerms.offChain.additionalTerms.description

string

required

Example:

[
  {
    "term": "Quality Control",
    "description": "All derivative works must maintain similar quality standards as the original work"
  }
]

Example:

{
  "territory": ["Global"],
  "channelsOfDistribution": ["All"],
  "attribution": {
    "required": true,
    "instructions": "Credit original creator in all derivative works"
  },
  "contentStandards": ["Suitable-for-All-Ages"],
  "sublicensable": false,
  "aiLearningModels": false,
  "restrictionOnCrossPlatformUse": false,
  "governingLaw": "California, USA"
}

licenseTerms.uri

string

License terms stored off-chain

Example:

"ipfs://<CID>"

Example:

[
  { "type": "non-commercial-social-remixing" }
]

derivData

object

Data for the parent IP asset and license terms (for derivative IP assets only)

Show child attributes

derivData.parentIpIds

any[]

required

The parent IP IDs of the derivative IP asset

Example:

["0x123"]

derivData.licenseTermsIds

number[]

required

The license terms IDs of the derivative IP asset

Example:

[1]

derivData.maxMintingFee

number

default:0

The max minting fee of the derivative IP asset

Example:

0

derivData.maxRevenueShare

number

default:100

The max revenue share of the derivative IP asset

Example:

100

derivData.maxRts

number

default:100000000

The max RTS of the derivative IP asset

Example:

10000

Example:

{
  "parentIpIds": ["0x123"],
  "licenseTermsIds": [1],
  "maxMintingFee": 0,
  "maxRevenueShare": 100,
  "maxRts": 10000000
}

licenseConfig

object

License configuration for the IP asset

Show child attributes

licenseConfig.licenseTermsId

string

required

The ID of the specific license terms to update.

Example:

"1"

licenseConfig.mintingFee

number

The new minting fee to be paid when minting license tokens. If not specified, the current minting fee will be kept

Example:

100

licenseConfig.commercialRevShare

number

The new commercial revenue share percentage (number between 0 and 100), It cannot be lower than the current commercial rev share, can only increase. If not specified, the current commercial rev share will be kept

Example:

50

licenseConfig.disabled

boolean

default:false

If true, the license terms will be disabled. Effectively removing future mints with this license.

Example:

false

Example:

{
  "mintingFee": 100,
  "licenseTermsId": "1",
  "disabled": false
}