7. API reference

7.1. 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  

7.2. JavaScript

Swarm currently supports a Javascript API through a few packages:

7.2.1. erebos

erebos is available through NPM by issuing the following command:

npm install @erebos/swarm-browser # browser only
npm install @erebos/swarm-node # node only
npm install @erebos/swarm # universal

Note

Full documentation is available on the documentation website.

7.2.2. 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.

7.2.3. 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.

7.3. RPC

Swarm exposes an IPC API under the bzz namespace.

7.3.1. 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.

7.3.2. 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.