IPFS HTTP API

IPFS HTTP API based Python functions to interact with IPFS

IPFSApi

 IPFSApi (gateway_type='local', timeout=10, **kwargs)

Initialize self. See help(type(self)) for accurate signature.

	Type	Default	Details
gateway_type	str	local	Gateway to use - `public`, `infura`, `local`
timeout	int	10
kwargs

Choosing your gateway

By default, the IPFSApi uses the local node.

api = IPFSApi()

Changed to local node

To change to infura or public use the change_gateway_type method

Infura needs authorization, you can use the make_infura_auth to make the auth in required type. And when using the chage_gateway_type pass auth as the second variable in the tuple. For public and local, you can pass None as the second variable.

api.change_gateway_type = 'infura', auth

api.change_gateway_type = 'public', None

api.change_gateway_type = 'local', None

UnixFS

add_items

only available on local and infura nodes

IPFSApi.add_items

 IPFSApi.add_items (filepath:Union[str,List[str]], directory:bool=False,
                    wrap_with_directory:bool=False,
                    chunker:str='size-262144', pin:bool=True,
                    hash_:str='sha2-256', progress:str='true',
                    silent:str='false', cid_version:int=0, **kwargs)

add file/directory to ipfs

	Type	Default	Details
filepath	typing.Union[str, typing.List[str]]		Path to the file/directory to be added to IPFS
directory	bool	False	Is filepath a directory
wrap_with_directory	bool	False	True if path is a directory
chunker	str	size-262144	Chunking algorithm, size-[bytes], rabin-[min]-[avg]-[max] or buzhash
pin	bool	True	Pin this object when adding
hash_	str	sha2-256	Hash function to use. Implies CIDv1 if not sha2-256
progress	str	true	Stream progress data
silent	str	false	Write no output
cid_version	int	0	CID version
kwargs

Using local IPFS Node

Important: This requires a local IPFS Node to be run. Set up your local node using info here.

Note: Full list of available params on add function can be found here

Upload a file

response, jsonobject = api.add_items(filepath="../README.md"); jsonobject

Upload multiple files

response, jsonobject = api.add_items(filepath=["../README.md", 'output/test.txt']); jsonobject

You can view the added file on ipfs.io

To view any CID on ipfs.io https://ipfs.io/ipfs/CID

Upload multiple file wrapped in a directory

response, jsonobject = api.add_items(filepath=["../README.md", 'output/test.txt'], wrap_with_directory='true'); jsonobject

Upload a directory

response, jsonobject = api.add_items(filepath='output', directory=True); jsonobject[-4:]

Using infura.io gateway

This works without a local IPFS node running but requires registration. You can register here

api.change_gateway_type = 'infura', auth

response, jsonobject = api.add_items("../README.md"); jsonobject

response, jsonobject = api.add_items(filepath='output', directory=True); jsonobject[-4:]

You can view the added file on infura.io

To view any CID on infura https://ipfs.infura.io/ipfs/CID

ls_items

only available on local and public nodes. ls not implemented on infura

IPFSApi.ls_items

 IPFSApi.ls_items (cid:str, resolve_type:bool=True, size:bool=True,
                   **kwargs)

List directory contents for Unix filesystem objects

	Type	Default	Details
cid	str		The path to the IPFS object(s) to list links from
resolve_type	bool	True	Resolve linked objects to find out their types
size	bool	True	Resolve linked objects to find out their file size
kwargs

api.change_gateway_type = 'local'

response, content = api.ls_items('QmeyTiqrD6oo4eQXbAt7hZn3ASzpcP3Kvb1rc9qznEowEw'); content

api.change_gateway_type = 'public'

response, content = api.ls_items('QmeyTiqrD6oo4eQXbAt7hZn3ASzpcP3Kvb1rc9qznEowEw'); content

cat_items

IPFSApi.cat_items

 IPFSApi.cat_items (cid:str, **kwargs)

Show IPFS object data

	Type	Details
cid	str	The path to the IPFS object(s) to be output
kwargs

When given a file CID

api.change_gateway_type = 'local'

response, content = api.cat_items(cid='QmUfwG4P6EA5xbD3De5bS7XKcBion8ReQj7m9ZjxaPvq3B'); content

When given a directory CID (this will throw an error)

response, content = api.cat_items(cid='QmeyTiqrD6oo4eQXbAt7hZn3ASzpcP3Kvb1rc9qznEowEw'); content

api.change_gateway_type = 'public'

response, content = api.cat_items(cid='QmUfwG4P6EA5xbD3De5bS7XKcBion8ReQj7m9ZjxaPvq3B'); content

api.change_gateway_type = 'infura'

response, content = api.cat_items(cid='QmUfwG4P6EA5xbD3De5bS7XKcBion8ReQj7m9ZjxaPvq3B'); content

get_items

response, content = api.get_items(cid='QmUfwG4P6EA5xbD3De5bS7XKcBion8ReQj7m9ZjxaPvq3B'); content

How to download a directory from IPFS

only available on local and public

DownloadDir

 DownloadDir (gateway_type:str, root_cid:str, output_fol:str)

Download a IPFS directory to your local disk

	Type	Details
gateway_type	str	Gateway to use - works on local and public
root_cid	str	Root CID of the directory
output_fol	str	Path to save in your local disk

download = DownloadDir('local', 'QmWJvSt7QGY2yhr9mrfAm76vRvxXA5ygB4zd2SmfD43vtX', 'output2')

download.download()

download.full_structure

DAGs

IPFSApi.dag_get

 IPFSApi.dag_get (cid:str, output_codec:str='dag-json')

Get a DAG node from IPFS.

	Type	Default	Details
cid	str		The path to the IPFS DAG node
output_codec	str	dag-json

IPFSApi.dag_export

 IPFSApi.dag_export (cid:str, **kwargs)

Streams the selected DAG as a .car stream on stdout.

	Type	Details
cid	str	The path to the IPFS DAG node
kwargs

IPFSApi.dag_stat

 IPFSApi.dag_stat (cid:str, **kwargs)

Gets stats for a DAG.

	Type	Details
cid	str	The path to the IPFS DAG node
kwargs

Making use of DAGs

Let’s take a look at the DAG structure of the folder we uploaded earlier

response, content = api.dag_get('QmeyTiqrD6oo4eQXbAt7hZn3ASzpcP3Kvb1rc9qznEowEw'); content

dag_get method returns a dict with data and links. data is not exciting for a directory. Under the links, we can see files/directories that are in the uploaded directory.

Let’s see the number of files/directories in the links

len(content['Links'])

Let’s take a look at the first link

content['Links'][0]

Local Pinning

Pin an IPFS object locally

More info on this can be found here

IPFSApi.pin_add

 IPFSApi.pin_add (cid:str, recursive:str='true')

Pin objects to local storage.

	Type	Default	Details
cid	str		Path to IPFS object(s) to be pinned
recursive	str	true	Recursively pin the object linked to by the specified object(s)

IPFSApi.pin_ls

 IPFSApi.pin_ls (type_:str='all', **kwargs)

List objects pinned to local storage.

	Type	Default	Details
type_	str	all	The type of pinned keys to list. Can be “direct”, “indirect”, “recursive”, or “all”
kwargs

IPFSApi.pin_rm

 IPFSApi.pin_rm (cid:str, recursive:str='true', **kwargs)

List objects pinned to local storage.

	Type	Default	Details
cid	str		Path to object(s) to be unpinned
recursive	str	true	Recursively unpin the object linked to by the specified object(s)
kwargs

response, content = api.pin_add('QmUfwG4P6EA5xbD3De5bS7XKcBion8ReQj7m9ZjxaPvq3B'); content

Let’s list all the items pinned locally.

response, content = api.pin_ls(); len(content[0]['Keys'])

list(content[0]['Keys'].keys())[:10]

The item we added above is also part of it.

content[0]['Keys']['QmUfwG4P6EA5xbD3De5bS7XKcBion8ReQj7m9ZjxaPvq3B']

What does the Type : recursive means? - Direct pins - Single block and no others in relation to it. - Recursive pins - Given block and all of its children. - Indirect pins - the result of a given block’s parent being pinned recursively.

response, content = api.pin_rm('QmUfwG4P6EA5xbD3De5bS7XKcBion8ReQj7m9ZjxaPvq3B'); response.status_code

Remote Pinning Service

IPFSApi.rspin_add

 IPFSApi.rspin_add (service_name:str, service_edpt:str, service_key:str)

Pin object to remote pinning service.

	Type	Details
service_name	str	Name of the remote pinning service to use
service_edpt	str	Service endpoint
service_key	str	Service key

IPFSApi.rspin_ls

 IPFSApi.rspin_ls (**kwargs)

List remote pinning services.

IPFSApi.rspin_rm

 IPFSApi.rspin_rm (service_name:str)

Remove remote pinning service.

	Type	Details
service_name	str	Name of pinning service to remove

Work with remote pinning service

More info on this can be found here and here

Adding your Pinata to your IPFS node 1. Create an account with Pinata 2. use rspin_add method to add the service

os.environ["pinata_api_secret"] = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySW5mb3JtYXRpb24iOnsiaWQiOiJhZDkxMTQ3Yy0yMmE5LTQ1MjgtODk2OS05ZTdjMjAwNzE2ZjAiLCJlbWFpbCI6Im1hcnNoYXRoQGdtYWlsLmNvbSIsImVtYWlsX3ZlcmlmaWVkIjp0cnVlLCJwaW5fcG9saWN5Ijp7InJlZ2lvbnMiOlt7ImlkIjoiRlJBMSIsImRlc2lyZWRSZXBsaWNhdGlvbkNvdW50IjoxfV0sInZlcnNpb24iOjF9LCJtZmFfZW5hYmxlZCI6ZmFsc2V9LCJhdXRoZW50aWNhdGlvblR5cGUiOiJzY29wZWRLZXkiLCJzY29wZWRLZXlLZXkiOiIxMjc4NDQ5OGY3YzI0ZjczNDBjMiIsInNjb3BlZEtleVNlY3JldCI6ImQyYmNlZjFlODVlZjgyOTcwNGE0ZTk4NGRmYjc3ZWE0MDhlY2NkODk1MjMxMzI2YjVlMmZlZDQxMTBhZmQyMGEiLCJpYXQiOjE2NTM5Njk0MDN9.Fa055BjXNmERyl_ZAA9NJscdt0HqbiX0ByY8pU5uLNY'

Note: For pinata the service_key is also called JWT

image.png

res, content = api.rspin_add('pinata', 'https://api.pinata.cloud/psa', os.environ['pinata_api_secret']);res.status_code

Let’s list the pinned services to see if we successfully added pinata

Pinata has been added

response, content = api.rspin_ls(); content

Remote Pinning

IPFSApi.rpin_add

 IPFSApi.rpin_add (cid:str, service:str, background:str='false', **kwargs)

Pin object to remote pinning service.

	Type	Default	Details
cid	str		Path to IPFS object(s) to be pinned
service	str		Name of the remote pinning service to use
background	str	false	Add to the queue on the remote service and return immediately (does not wait for pinned status)
kwargs

IPFSApi.rpin_ls

 IPFSApi.rpin_ls (service:str, **kwargs)

List objects pinned to remote pinning service.

	Type	Details
service	str	Name of the remote pinning service to use
kwargs

IPFSApi.rpin_rm

 IPFSApi.rpin_rm (service:str, **kwargs)

Remove pins from remote pinning service.

	Type	Details
service	str	Name of the remote pinning service to use
kwargs

Let’s add a new file to IPFS and pin it to pinata.

response, content = api.add_items(filepath='output/test.txt'); content

response, content = api.rpin_add('QmTT8vwdbnP9Ls8bSY1LMyW4a8bEwTYZa5izEoJMBtTPfb', 'pinata'); response.status_code

As can ber seen, we have successfully added the file to pinata

response, content = api.rpin_ls('pinata'); content

Block

IPFSApi.block_get

 IPFSApi.block_get (cid:str)

Get a raw IPFS block.

	Type	Details
cid	str	The base58 multihash of an existing block to get

IPFSApi.block_put

 IPFSApi.block_put (filepath:str, mhtype:str='sha2-256', mhlen:int=-1,
                    pin:str=False, **kwargs)

Store input as an IPFS block.

	Type	Default	Details
filepath	str		Path to file
mhtype	str	sha2-256	multihash hash function.
mhlen	int	-1	Multihash hash length
pin	str	False	pin added blocks recursively
kwargs

IPFSApi.block_rm

 IPFSApi.block_rm (cid:str, force:str='false', quiet:str='false')

Remove IPFS block(s).

	Type	Default	Details
cid	str		Bash58 encoded multihash of block(s) to remove
force	str	false	Ignore nonexistent blocks.
quiet	str	false	Write minimal output.

IPFSApi.block_stat

 IPFSApi.block_stat (cid:str)

Print information of a raw IPFS block.

	Type	Details
cid	str	Bash58 encoded multihash of block(s) to remove

Work with blocks

To explore the blocks modeule, let’s add a large file

response, content = api.add_items('output/adult_data.csv'); content

As you can see from below, adding it results in blocks and we are given the root CID

We can take a look at the CIDs of different block like below

response, content = api.ls_items('QmZnxARhJWsCbTxiAzoRhnxHgMtoEkNJNS8DGLCBEMvm4V');content

blocks = content[0]["Objects"][0]["Links"]

print(f'Number of blocks: {len(blocks)}')

Here, we can see the three blocks of the total 16 blocks.

blocks[:3]

Let’s read whats in the first and second block

response, content = api.cat_items(blocks[0]['Hash'])

print(response.text[:100]); len(response.text)

response, content = api.cat_items(blocks[1]['Hash'])

print(response.text[:100]); len(response.text)

We can also read using the cat method under the blocks module in which case if block is an intermediate block it will only print the raw binary data.

response, content = api.block_get(blocks[0]['Hash'])

response.text[:300]

Add a block

response, content = api.block_put('../README.md'); content

Get stat on a block

response, content = api.block_stat('bafkreicb2n4nhac6nwsviqe2ik4pt22ukewf7zfz2j2aof2au3a2qgi3oa'); content

Remove a block

response, content = api.block_rm('bafkreicb2n4nhac6nwsviqe2ik4pt22ukewf7zfz2j2aof2au3a2qgi3oa'); response.status_code

Mutable File System (files)

IPFSApi.mfs_chcid

 IPFSApi.mfs_chcid (path:str='/', cid_version:int=0, **kwargs)

Change the CID version or hash function of the root node of a given path.

	Type	Default	Details
path	str	/	Path to change
cid_version	int	0	Cid version to use
kwargs

IPFSApi.mfs_cp

 IPFSApi.mfs_cp (source_path:str, dest_path:str, **kwargs)

Add references to IPFS files and directories in MFS (or copy within MFS).

	Type	Details
source_path	str	Source IPFS or MFS path to copy
dest_path	str	Destination within MFS
kwargs

IPFSApi.mfs_flush

 IPFSApi.mfs_flush (path:str='/')

Flush a given path’s data to disk

	Type	Default	Details
path	str	/	Path to flush

IPFSApi.mfs_ls

 IPFSApi.mfs_ls (path:str='/', **kwargs)

List directories in the local mutable namespace.

	Type	Default	Details
path	str	/	Path to show listing for
kwargs

IPFSApi.mfs_mkdir

 IPFSApi.mfs_mkdir (path:str, **kwargs)

Make directories.

	Type	Details
path	str	Path to dir to make
kwargs

IPFSApi.mfs_mv

 IPFSApi.mfs_mv (source_path:str, dest_path:str)

Move files.

	Type	Details
source_path	str	Source file to move
dest_path	str	Destination path for file to be moved to

IPFSApi.mfs_read

 IPFSApi.mfs_read (path, **kwargs)

Read a file in a given MFS.

	Details
path	Path to file to be read
kwargs

IPFSApi.mfs_rm

 IPFSApi.mfs_rm (path, **kwargs)

Read a file in a given MFS.

	Details
path	File to remove
kwargs

IPFSApi.mfs_stat

 IPFSApi.mfs_stat (path, **kwargs)

Display file status.

	Details
path	Path to node to stat
kwargs

IPFSApi.mfs_write

 IPFSApi.mfs_write (path, filepath, create=True, **kwargs)

Display file status.

	Type	Default	Details
path			Path to write to
filepath			File to add
create	bool	True	Create the file if it does not exist
kwargs

Working with MFS

Making a directory

response, content = api.mfs_mkdir('/test'); response.status_code