API Reference

HTTP

Name	Method	Descriptors
bzz	GET	Purpose	retrieve document at domain/some/path allowing domain to resolve via the Using ENS names
		Locator	bzz:/<domain_part>/<resource_path>
		Locator Parts	domain part: mandatory - ENS name or a valid swarm hash. path part: optional - a case insensitive path to match for in the manifest
		HTTP Codes	200; 300; 404; 500
		Responds with	The content stored at the resolved ENS entry (or the matched path) with the appropriate Content-Type as stored in the manifest
		Example
	POST	Purpose	post an application/x-tar or multipart/form-data (or any other Content-Type for that matter); create an appropriate manifest and retrieve the associated hash. if an existing manifest address is given with the according path to update - a copy of the manifest will be created with the updated entry and the hash of the new manifest will be returned
		Locator	bzz:/<manifest_hash?>/<resource_path?>/<encrypt?>
		Locator Parts	manifest hash - optional - an existing manifest address to update a resource included in the manifest. resource path - optional - which resource to update in the manifest. encrypt - optional flag to enable encryption
		HTTP Codes	200
		Responds with	a hash of a newly created manifest
		Example
	DELETE	Purpose	delete a resource from a manifest by unlinking it from the existing manifest
		Locator	bzz:/<domain>/<path>
		Locator Parts	domain part - mandatory - a valid ENS hash or a valid swarm manifest hash. path part - mandatory - a path to the resource to be removed from the manifest
		HTTP Codes	200; 404; 500
		Responds with	the hash of the new manifest which does not have component path
		Example
bzz-immutable	GET	Purpose	The same as the generic scheme but there is no ENS domain resolution. the domain part of the path needs to be a valid hash. This is also a read-only scheme but explicit in its integrity protection. A particular bzz-immutable url will always necessarily address the exact same fixed immutable content.
		Locator	bzz-immutable:/<hash>
		Locator Parts	hash part - a valid swarm hash that points to a manifest
		HTTP Codes	200; 404; 500
		Responds with	the resolved content at the specified address with a valid content-type as stored in the manifest
		Example	use bzz-hash to resolve the ens name into a hash then use it with immutable
bzz-raw	GET	Purpose	When responding to GET requests with the bzz-raw scheme swarm does not assume a manifest but just serves the asset addressed by the url directly. The content_type query parameter can be supplied to specify the mime type you are requesting otherwise content is served as an octet stream per default.
		Locator	bzz-raw:/<content_hash>?content_type=<mime>
		Locator Parts	content hash - mandatory - a valid swarm content hash. content type - optional - the mime type to serve the content as. defaults to application/octet-stream
		HTTP Codes	200; 404; 500
		Responds with
		Example	a pdf document (not the manifest wrapping it) resides at hash 6a182226… then the following url will properly serve it: GET http://localhost:8500/bzz-raw:/6a18222637cafb4ce692fa11df886a03e6d5e63432c53cbf7846970aa3e6fdf5?content_type=application/pdf
	POST	Purpose
		Locator
		Locator Parts
		HTTP Codes	200; 404; 500
		Responds with
		Example
bzz-list	GET	Purpose	Returns a list of all files contained in <manifest> under <path> grouped into common prefixes using / as a delimiter. If path is / - all files in manifest are returned. The response is a JSON-encoded object with common_prefixes string field and entries list field.
		Locator	bzz-list:/<domain>/<path>
		Locator Parts	domain part - mandatory - a valid ENS entry that points to a valid manifest hash or a valid manifest hash. path part - optional - path to look for inside the manifest
		HTTP Codes	200; 404; 500
		Responds with
		Example
bzz-hash	GET	Purpose	responds with the hash value of the raw content - the same content returned by requests with bzz-raw scheme. Hash of the manifest is also the hash stored in ENS so bzz-hash can be used for ENS domain resolution
		Locator	bzz-hash:/<domain>
		Locator Parts	domain part - mandatory. a valid ENS name
		HTTP Codes	200; 404; 500
		Responds with	text/plain
		Example
bzz-resource	POST	Purpose	Create or update a mutable resource
		Locator	bzz-resource:/<domain>/raw?/<frequency?>
		Locator Parts	domain part - mandatory. a valid ENS name. For creation of a resource a frequency must be included. If raw is specified, the data will be interpreted as raw (verbatim) data. Otherwise a valid (multi)hash will be expected.
		HTTP Codes	200; 400; 404; 500
		Responds with	application/octet-stream; application/json
		Example
bzz-resource	GET	Purpose	Retrieve a mutable resource
		Locator	bzz-resource:/<domain>/<period?>/<version?>
		Locator Parts	domain part - mandatory. a valid ENS name. If period is specified, the latest version of that period will be returned. If period and version is specified, that version of the specified period will be returned.
		HTTP Codes	200; 400; 404; 500
		Responds with	application/octet-stream; text/html
		Example

JavaScript

Swarm currently supports a Javascript API through a couple of packages:

swarm-js

swarm-js is available through NPM by issuing the following command:

npm install swarm-js

Note

Full documentation is available on the GitHub page.

swarmgw

swarmgw is available through NPM by issuing the following command:

npm install swarmgw

When installed globally, it can also be used directly from the CLI:

npm install -g swarmgw

Note

Full documentation is available on the GitHub page.

RPC

Swarm exposes an IPC API under the bzz namespace.

FUSE

swarmfs.mount(HASH|domain, mountpoint))

mounts swarm contents represented by a swarm hash or a ens domain name to the specified local directory. The local directory has to be writable and should be empty. Once this command is succesfull, you should see the contents in the local directory. The HASH is mounted in a rw mode, which means any change insie the directory will be automatically reflected in swarm. Ex: if you copy a file from somewhere else in to mountpoint, it is equvivalent of using a “swarm up <file>” command.

swarmfs.unmount(mountpoint)

This command unmounts the HASH|domain mounted in the specified mountpoint. If the device is busy, unmounting fails. In that case make sure you exit the process that is using the directory and try unmounting again.

swarmfs.listmounts()

For every active mount, this command display three things. The mountpoint, start HASH supplied and the latest HASH. Since the HASH is mounted in rw mode, when ever there is a change to the file system (adding file, removing file etc), a new HASH is computed. This hash is called the latest HASH.

PSS

pss methods are by default exposed via IPC. If websockets are activated on the node, they will also be available there if the pss module is explicitly specified.

All parameters are hex-encoded bytes or strings unless otherwise noted.

pss.getPublicKey()

Retrieves the public key of the node, in hex format

pss.baseAddr()

Retrieves the swarm overlay address of the node, in hex format

pss.stringToTopic(name)

Creates a deterministic 4 byte topic value from an input name, returned in hex format

pss.setPeerPublicKey(publickey, topic, address)

Register a peer’s public key. This is done once for every topic that will be used with the peer. Address can be anything from 0 to 32 bytes inclusive of the peer’s swarm address. The method has no return value.

pss.sendAsym(publickey, topic, message)

Encrypts the message using the provided public key, and signs it using the node’s private key. It then wraps it in an envelope containing the topic, and sends it to the network. The method has no return value.

pss.setSymmetricKey(symkey, topic, address, bool decryption)

Register a symmetric key shared with a peer. This is done once for every topic that will be used with the peer. Address can be anything from 0 to 32 bytes inclusive of the peer’s swarm overlay address. If the fourth parameter is false, the key will not be added to the list of symmetric keys used for decryption attempts. The method returns an id used to reference the symmetric key in consecutive calls.

pss.sendSym(symkeyid, topic, message)

Encrypts the message using the provided symmetric key, wraps it in an envelope containing the topic, and sends it to the network. The method has no return value.

pss.GetSymmetricAddressHint(topic, symkeyid)

Return the swarm address associated with the peer registered with the given symmetric key and topic combination. If a match is found it returns the address data in hex format.

pss.GetAsymmetricAddressHint(topic, publickey)

Return the swarm address associated with the peer registered with the given asymmetric key and topic combination. If a match is found it returns the address data in hex format.

Note

The following methods are used to control the optional pss handshake module. This is an advanced feature, and not required for sending and receiving messages using pss.

pss.addHandshake(topic)

Activate handshake functionality on the specified topic. The method has no return value.

pss.removeHandshake(topic)

Remove handshake functionality on the specified topic. The method has no return value.

pss.handshake(publickey, topic, bool block, bool flush)

Instantiate handshake with peer, refreshing symmetric encryption keys. If parameter 3 is false the handshake will happen asynchronously. If parameter 4 is true, it will force expiry of all existing keys. The method returns a list of symmetric key ids created by the handshake. If the handshake is asynchronous, however, returned array will be empty.

pss.getHandshakeKeys(publickey, topic, bool incoming, bool outgoing)

Returns the set of valid symmetric encryption keys for a specified peer and topic. If the incoming and outgoing parameters are set, the keys valid for the respective communcations directions are included.

pss.getHandshakeKeyCapacity(symkeyid)

Returns the number of messages (uint16) a symmetric handshake key is valid for.

pss.getHandshakePublicKey(symkeyid)

Returns the public key associated with the specified symmetric handshake key.

pss.releaseHandshakeKey(publickey, topic, symkeyid, bool instant)

Invalidate the specified symmetric handshake key. Normally, the key will be kept for a grace period to allow decryption of messages not yet received at the time of release. If the instant parameter is set, this grace period is omitted, and the key removed instantaneously. This method has no return value.