Skip to main content

IPFS

Effortlessly upload files and JSON metadata to the decentralized InterPlanetary File System. Enhance your applications with secure and censorship-resistant file storage. Let's get started!

Abstract

IPFS, which stands for the InterPlanetary File System, is a protocol and network designed to create a more efficient and decentralized way to store and share hypermedia and data on the internet. It was initially developed by Juan Benet and has gained popularity as a distributed file-sharing and storage system.

IPFS (InterPlanetary File System) uses Content Identifiers (CIDs) to uniquely identify content in its distributed network. CIDs are cryptographic hashes that represent the content of a file or any other data stored in IPFS. There are different CID versions, and as of my last knowledge update in September 2021, CID versions 0, 1, and 2 were commonly used.

  • CIDv1 (Content Identifier Version 1): CIDv1 is the most widely used version of CIDs in IPFS. It consists of a multibase prefix, a multicodec identifier, a multihash, and optional multicodec-specific parameters. This version allows for greater flexibility and extensibility when dealing with different content types and codecs.

  • CIDv2 (Content Identifier Version 2): CIDv2 is an evolution of CIDv1 and is designed to improve upon some of its limitations. It includes a few additional features, such as support for variable-length CID representations, which can be more efficient when dealing with large CIDs. CIDv2 also addresses some security concerns and introduces stricter serialization rules.

CIDv2 builds upon the principles of CIDv1 but aims to make CID handling more consistent and secure.

Storage endpoints

These endpoints help developers store both JSON or any type of file:

Upload file

This endpoint allows to upload a binary file to IPFS, which is usually used for uploading the visual representation for digital assets. The call that must be performed is:

POST https://ipfsapi-v2.vottun.tech/ipfs/v2/file/upload

With a form-data body that contains two fields.

Request

You must send a multipart/formdata including the following fields.

nametyperequireddescription
filenamestringyesThe name of the file. This name is used to store it at database
filefileyesthe file to be uploaded in multi-part format

Example

The following is a curl example to upload a file to IPFS:


curl --location 'https://ipfsapi-v2.vottun.tech/ipfs/v2/file/upload' \
--form 'filename="Amazing picture uploaded to ipfs"' \
--form 'file=@"./Pictures/ThisIsThePicture.jpg"'

Response

If the requests goes well, it will return a json with the url where the file can be reached

nametypedescriptionexample
hashstringThe url for ipfs uploaded assethttps://ipfsgw.vottun.tech/ipfs/bafybeifd..oe6m3dniq

Example

{
"hash": "https://ipfsgw.vottun.tech/ipfs/bafybeifd5tzmewtajswdp3q4kn52f5nxauovhiqth3m457ucmoe6m3dniq"
}

Http status

resulthttp status
The file has been upploaded succesfully to IPFS201
The request does not include the correct information as per format or content400
The customer is not authorized401
There is an error with any of the vottun dependencies or with the customer (in this case contact with Vottun)503

Upload metadata (JSON)

This endpoint allows to upload a JSON file to IPFS, which is usually used for the digital assets metadata. This assets have a standard format, which is the format expected in the body of the POST call. The call that must be performed is:

POST https://ipfsapi-v2.vottun.tech/ipfs/v2/file/metadata

Request

nametyperequireddescriptionexample
namestringyesThe name of the NFT. It will be used by Metamask and other NFT Marketplaces."Amazing picture"
imagestringyesThe absolute url to ipfs media file obtained with IPFS File Upload. It will be used by Metamask and other NFT Marketplaces."https://ipfsgw.vottun.tech/ipfs/bafybeifd..oe6m3dniq"
descriptionstringyesA description for the NFT. <It will be used by Metamask and other NFT Marketplaces."This is an amazing picture uploaded"
editionstringnoCan be used to set the edition of the asset as informational data"Gold Edition"
external_urlstringnoThis url is used by other marketplaces to show an url to an external page, the artist one, for example. It will be used by Metamask and other NFT Marketplaces."https://vottun.com/wp-content/uploads/2023/02/Vottun-WEB3-APIS-PLATFORM-INFRASTRUCTURE-1.jpg"
animation_urlstringnoThis url is used by other marketplaces to show an url to an animation like a video. Will show other NFT Marketplaces."https://youtu.be/bsNT3qWZjGo?si=I_ov3Lqx_j3LpGLc"
attributesarraynoThe attributes for the item. Will show in other NFT Marketplacessee below
attributes.trait_typestringyesThe name of the trait"Power"
attributes.valueanyyesThe value of the trait. If max value is informed, it should be a number, if not, can be any type255
attributes.max_valueintnoMax value this trait can reach.500
attributes.display_typestringnoOnly used for int values. It is shown in other NFT Marketplace to display the value."number" or "boost_percentage" or "boost_number"
dataJSONnoIt is a free and valid json to add custom data to the metadata"data": {"artist": "Vottun SL", "Quantity": 500}\

Example

{
"name": "Asset name",
"image": "https://ipfsgw-pre.vottun.tech/ipfs/bafybeiecqlec4m72dzcnlis3qhrajhnayqz25qcayomj3s6cgezn5jkaje",
"description": "Asset description",
"attributes":[
{
"trait_type": "Trait 1",
"value": 6
},
{
"trait_type": "Trait 2",
"value": 800
},
{
"trait_type": "Trait 2",
"value": 100
}
],
"data": {
"artist": "Vottun SL",
"Quantity": 500
}
}

Response

nametypedescriptionexample
IpfsHashstringThe url for ipfs uploaded assethttps://ipfsgw.vottun.tech/ipfs/bafybeifd..oe6m3dniq
PinSizeintthe content length of the uploaded metadata in bytes355
Timestampstringthe timestamp for the action"2023-10-05 16:35:18.211718646 +0000 UTC m=+24648.947925646"

Example


{
"IpfsHash": "https://ipfsgw.vottun.tech/ipfs/bafkreibiz4pff..l26ynl5jedh6fslyd3kcxlmpm3y",
"PinSize": 355,
"Timestamp": "2023-10-05 16:35:18.211718646 +0000 UTC m=+24648.947925646"
}

Http status

resulthttp status
The file has been upploaded succesfully to IPFS201
The request does not include the correct information as per format or content400
The customer is not authorized401
There is an error with any of the vottun dependencies or with the customer (in this case contact with Vottun)503