Skip to main content
API docs by Redocly

Bee API (8.2.1)

Download OpenAPI specification:Download

API endpoints for interacting with the Swarm network, supporting file operations, messaging, and node management

Browse the documentation at the Swarm Docs

ACT

Create a grantee list

header Parameters
swarm-postage-batch-id
required
object (SwarmPostageBatchId)

ID of Postage Batch that is used to upload data with

swarm-tag
object (SwarmTagParameter)

Associate upload with an existing Tag UID

swarm-pin
object (SwarmPinParameter)

Indicates whether the uploaded data should also be locally pinned on this node

swarm-deferred-upload
object (SwarmDeferredUpload)

Indicates whether the uploaded data should be sent to the network immediately or deferred. Default: deferred (true)

swarm-act-history-address
object (SwarmActHistoryAddress)

ACT history reference address

swarm-redundancy-level
object (SwarmRedundancyLevelParameter)

Add redundancy to the data being uploaded so that downloaders can download it with better UX. 0 value is default and does not add any redundancy to the file.

Request Body schema: application/json
required
grantees
Array of strings (PublicKey) [ items^[A-Fa-f0-9]{66}$ ]

Responses

Request samples

Content type
application/json
{
  • "grantees": [
    ]
}

Response samples

Content type
application/json
{
  • "ref": "36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f2d2810619d29b5dbefd5d74abce25d58b81b251baddb9c3871cf0d6967deaae2",
  • "historyref": "36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f2d2810619d29b5dbefd5d74abce25d58b81b251baddb9c3871cf0d6967deaae2"
}

Get the grantee list

path Parameters
address
required
string (SwarmEncryptedReference) ^[A-Fa-f0-9]{128}$
Example: 36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f2d2810619d29b5dbefd5d74abce25d58b81b251baddb9c3871cf0d6967deaae2

Grantee list reference

header Parameters
swarm-redundancy-level
object (SwarmRedundancyLevelParameter)

Add redundancy to the data being uploaded so that downloaders can download it with better UX. 0 value is default and does not add any redundancy to the file.

Responses

Response samples

Content type
application/json
[
  • "02ab7473879005929d10ce7d4f626412dad9fe56b0a6622038931d26bd79abf0a4"
]

Update the grantee list

Add or remove grantees from an existing grantee list

path Parameters
address
required
string (SwarmEncryptedReference) ^[A-Fa-f0-9]{128}$
Example: 36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f2d2810619d29b5dbefd5d74abce25d58b81b251baddb9c3871cf0d6967deaae2

Grantee list reference

header Parameters
swarm-act-history-address
required
object (SwarmActHistoryAddress)

ACT history reference address

swarm-postage-batch-id
required
object (SwarmPostageBatchId)

ID of Postage Batch that is used to upload data with

swarm-tag
object (SwarmTagParameter)

Associate upload with an existing Tag UID

swarm-pin
object (SwarmPinParameter)

Indicates whether the uploaded data should also be locally pinned on this node

swarm-deferred-upload
object (SwarmDeferredUpload)

Indicates whether the uploaded data should be sent to the network immediately or deferred. Default: deferred (true)

swarm-redundancy-level
object (SwarmRedundancyLevelParameter)

Add redundancy to the data being uploaded so that downloaders can download it with better UX. 0 value is default and does not add any redundancy to the file.

Request Body schema: application/json
required
add
Array of strings (PublicKey) [ items^[A-Fa-f0-9]{66}$ ]

List of grantees to add

revoke
Array of strings (PublicKey) [ items^[A-Fa-f0-9]{66}$ ]

List of grantees to revoke future access from

Responses

Request samples

Content type
application/json
{
  • "add": [
    ],
  • "revoke": [
    ]
}

Response samples

Content type
application/json
{
  • "ref": "36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f2d2810619d29b5dbefd5d74abce25d58b81b251baddb9c3871cf0d6967deaae2",
  • "historyref": "36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f2d2810619d29b5dbefd5d74abce25d58b81b251baddb9c3871cf0d6967deaae2"
}

Bytes

Upload data

header Parameters
swarm-postage-batch-id
required
string (SwarmAddress) ^[A-Fa-f0-9]{64}$
Example: 36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f

ID of Postage Batch that is used to upload data with

swarm-tag
integer (Uid)

Associate upload with an existing Tag UID

swarm-pin
boolean

Indicates whether the uploaded data should also be locally pinned on this node

swarm-deferred-upload
boolean
Default: true

Indicates whether the uploaded data should be sent to the network immediately or deferred. Default: deferred (true)

swarm-encrypt
boolean

Indicates whether the file should be encrypted

swarm-redundancy-level
integer
Enum: 0 1 2 3 4

Add redundancy to the data being uploaded so that downloaders can download it with better UX. 0 value is default and does not add any redundancy to the file.

swarm-act
boolean
Default: false

Determines if the uploaded data should be treated as ACT content

swarm-act-history-address
string (SwarmAddress) ^[A-Fa-f0-9]{64}$
Example: 36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f

ACT history reference address

Request Body schema: application/octet-stream
string <binary>

Responses

Response samples

Content type
application/json
{
  • "reference": "36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f"
}

Retrieve data by reference

path Parameters
required
SwarmAddress (string) or SwarmEncryptedReference (string) or DomainName (string) (SwarmReference)

Swarm address reference to content

header Parameters
swarm-cache
boolean
Default: true

Indicates whether downloaded data should be cached on the node. Default: cached (true)

swarm-redundancy-strategy
integer
Enum: 0 1 2 3

Specify the retrieval strategy for redundant data. Values represent: NONE (0), DATA (1), PROX (2), RACE (3). NONE: no prefetching. DATA: prefetch only data chunks. PROX: prefetch chunks near this node. RACE: prefetch all chunks and use the first n to arrive. Multiple strategies can be cascaded if fallback mode is enabled. Default: NONE > DATA > PROX > RACE

swarm-redundancy-fallback-mode
boolean

Specify if the retrieve strategies (chunk prefetching on redundant data) are used in a fallback cascade. The default is true.

swarm-redundancy-level
integer
Enum: 0 1 2 3 4

Add redundancy to the data being uploaded so that downloaders can download it with better UX. 0 value is default and does not add any redundancy to the file.

swarm-chunk-retrieval-timeout
string (Duration)
Example: 5.0018ms

Specify the timeout for chunk retrieval. The default is 30 seconds.

swarm-lookahead-buffer-size
integer

Override the lookahead buffer size used during retrieval, in bytes. When unset the node picks 8x or 16x the io.Copy default buffer (32 kB) depending on file size.

swarm-act-timestamp
integer <int64>

ACT history Unix timestamp

swarm-act-publisher
string (PublicKey) ^[A-Fa-f0-9]{66}$
Example: 02ab7473879005929d10ce7d4f626412dad9fe56b0a6622038931d26bd79abf0a4

ACT content publisher's public key

swarm-act-history-address
string (SwarmAddress) ^[A-Fa-f0-9]{64}$
Example: 36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f

ACT history reference address

Responses

Response samples

Content type
application/problem+json
{
  • "code": 0,
  • "message": "string",
  • "reasons": [
    ]
}

Retrieve headers containing the content type and length for the reference

Identical to GET on the same reference except that no content is sent, so Range and conditional request headers are honored the same way.

path Parameters
address
required
string (SwarmAddress) ^[A-Fa-f0-9]{64}$
Example: 36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f

Swarm address of chunk

header Parameters
swarm-cache
boolean
Default: true

Indicates whether downloaded data should be cached on the node. Default: cached (true)

swarm-redundancy-strategy
integer
Enum: 0 1 2 3

Specify the retrieval strategy for redundant data. Values represent: NONE (0), DATA (1), PROX (2), RACE (3). NONE: no prefetching. DATA: prefetch only data chunks. PROX: prefetch chunks near this node. RACE: prefetch all chunks and use the first n to arrive. Multiple strategies can be cascaded if fallback mode is enabled. Default: NONE > DATA > PROX > RACE

swarm-redundancy-fallback-mode
boolean

Specify if the retrieve strategies (chunk prefetching on redundant data) are used in a fallback cascade. The default is true.

swarm-redundancy-level
integer
Enum: 0 1 2 3 4

Add redundancy to the data being uploaded so that downloaders can download it with better UX. 0 value is default and does not add any redundancy to the file.

swarm-chunk-retrieval-timeout
string (Duration)
Example: 5.0018ms

Specify the timeout for chunk retrieval. The default is 30 seconds.

swarm-act-timestamp
integer <int64>

ACT history Unix timestamp

swarm-act-publisher
string (PublicKey) ^[A-Fa-f0-9]{66}$
Example: 02ab7473879005929d10ce7d4f626412dad9fe56b0a6622038931d26bd79abf0a4

ACT content publisher's public key

swarm-act-history-address
string (SwarmAddress) ^[A-Fa-f0-9]{64}$
Example: 36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f

ACT history reference address

Responses

Response samples

Content type
application/problem+json
{
  • "code": 0,
  • "message": "string",
  • "reasons": [
    ]
}

Chunk

Upload a chunk

header Parameters
swarm-tag
integer (Uid)

Associate upload with an existing Tag UID

swarm-postage-batch-id
object (SwarmPostageBatchId)

ID of Postage Batch that is used to upload data with

swarm-postage-stamp
string (HexString) ^([A-Fa-f0-9]+)$
Example: cf880b8eeac5093fa27b0825906c600685

Postage stamp for the corresponding chunk in the request.
It is required if Swarm-Postage-Batch-Id header is missing
It consists of: \

  • batch ID - 0:32 bytes \
  • postage index (bucket and bucket index) - 32:40 bytes \
  • timestamp - 40:48 bytes \
  • signature - 48:113 bytes
Request Body schema: application/octet-stream

Chunk binary data containing at least 8 bytes.

string <binary>

Responses

Response samples

Content type
application/json
{
  • "reference": "36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f"
}

Stream chunks for upload

Establishes a WebSocket connection for streaming chunks. Each uploaded chunk receives a binary acknowledgment (0). Chunks are sent as binary messages. When a tag is specified, chunks are stored locally and uploaded to the network after the stream closes. Without a tag, chunks are directly uploaded to the network as they arrive.

query Parameters
swarm-tag
integer (Uid)

Associate upload with an existing Tag UID (use when WebSocket client cannot set custom headers)

header Parameters
swarm-tag
integer (Uid)

Associate upload with an existing Tag UID

swarm-postage-batch-id
string (SwarmAddress) ^[A-Fa-f0-9]{64}$
Example: 36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f

ID of Postage Batch that is used to upload data with. Optional when chunks include pre-signed postage stamps.

Responses

Response samples

Content type
application/problem+json
{
  • "code": 0,
  • "message": "string",
  • "reasons": [
    ]
}

Retrieve a chunk

path Parameters
required
SwarmAddress (string) or SwarmEncryptedReference (string) or DomainName (string) (SwarmReference)

Swarm address of chunk

header Parameters
swarm-cache
object (SwarmCache)

Indicates whether downloaded data should be cached on the node. Default: cached (true)

swarm-act-timestamp
integer <int64>

ACT history Unix timestamp

swarm-act-publisher
string (PublicKey) ^[A-Fa-f0-9]{66}$
Example: 02ab7473879005929d10ce7d4f626412dad9fe56b0a6622038931d26bd79abf0a4

ACT content publisher's public key

swarm-act-history-address
string (SwarmAddress) ^[A-Fa-f0-9]{64}$
Example: 36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f

ACT history reference address

Responses

Response samples

Content type
application/problem+json
{
  • "code": 0,
  • "message": "string",
  • "reasons": [
    ]
}

Check if a chunk exists locally

path Parameters
address
required
string (SwarmAddress) ^[A-Fa-f0-9]{64}$
Example: 36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f

Swarm address of chunk

header Parameters
swarm-act-timestamp
integer <int64>

ACT history Unix timestamp

swarm-act-publisher
string (PublicKey) ^[A-Fa-f0-9]{66}$
Example: 02ab7473879005929d10ce7d4f626412dad9fe56b0a6622038931d26bd79abf0a4

ACT content publisher's public key

swarm-act-history-address
string (SwarmAddress) ^[A-Fa-f0-9]{64}$
Example: 36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f

ACT history reference address

Responses

Response samples

Content type
application/problem+json
{
  • "code": 0,
  • "message": "string",
  • "reasons": [
    ]
}

BZZ

Upload a file or collection of files

Upload single files or collections of files. For a single file, Content-Type is optional: when present it is stored as metadata as-is; when absent the server infers a type from the start of the body. To upload a collection, send a multipart request with files in the form data with appropriate headers. Tar files can be uploaded with the swarm-collection header to extract and upload the directory structure. Without the swarm-collection header, requests are treated as single file uploads. Multipart requests are always treated as collections; use the swarm-index-document header to specify a single file to serve.

query Parameters
name
string (FileName)

Filename when uploading single file

header Parameters
swarm-postage-batch-id
required
string (SwarmAddress) ^[A-Fa-f0-9]{64}$
Example: 36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f

ID of Postage Batch that is used to upload data with

swarm-tag
integer (Uid)

Associate upload with an existing Tag UID

swarm-pin
boolean

Indicates whether the uploaded data should also be locally pinned on this node

swarm-encrypt
boolean

Indicates whether the file should be encrypted

Content-Type
string

Single file: trimmed Content-Type is stored as-is or, if omitted or empty, inferred from the first bytes without validating against the body; tar (swarm-collection) and multipart collection uploads still need a full-body Content-Type (e.g. application/x-tar or multipart/form-data with boundary) so the request can be parsed.

swarm-collection
boolean

Upload file/files as a collection

swarm-index-document
string
Example: index.html

Default file to serve when a directory path is accessed

swarm-error-document
string
Example: error.html

Custom error document to return when a path is not found in the collection

swarm-deferred-upload
boolean
Default: true

Indicates whether the uploaded data should be sent to the network immediately or deferred. Default: deferred (true)

swarm-redundancy-level
integer
Enum: 0 1 2 3 4

Add redundancy to the data being uploaded so that downloaders can download it with better UX. 0 value is default and does not add any redundancy to the file.

swarm-act
boolean
Default: false

Determines if the uploaded data should be treated as ACT content

swarm-act-history-address
string (SwarmAddress) ^[A-Fa-f0-9]{64}$
Example: 36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f

ACT history reference address

Request Body schema:
file
Array of strings <binary> [ items <binary > ]

Responses

Response samples

Content type
application/json
{
  • "reference": "36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f"
}

Retrieve a file or index document from a collection

path Parameters
required
SwarmAddress (string) or SwarmEncryptedReference (string) or DomainName (string) (SwarmReference)

Swarm address of content

header Parameters
swarm-cache
boolean
Default: true

Indicates whether downloaded data should be cached on the node. Default: cached (true)

swarm-redundancy-strategy
integer
Enum: 0 1 2 3

Specify the retrieval strategy for redundant data. Values represent: NONE (0), DATA (1), PROX (2), RACE (3). NONE: no prefetching. DATA: prefetch only data chunks. PROX: prefetch chunks near this node. RACE: prefetch all chunks and use the first n to arrive. Multiple strategies can be cascaded if fallback mode is enabled. Default: NONE > DATA > PROX > RACE

swarm-redundancy-fallback-mode
boolean

Specify if the retrieve strategies (chunk prefetching on redundant data) are used in a fallback cascade. The default is true.

swarm-redundancy-level
integer
Enum: 0 1 2 3 4

Add redundancy to the data being uploaded so that downloaders can download it with better UX. 0 value is default and does not add any redundancy to the file.

swarm-chunk-retrieval-timeout
string (Duration)
Example: 5.0018ms

Specify the timeout for chunk retrieval. The default is 30 seconds.

swarm-lookahead-buffer-size
integer

Override the lookahead buffer size used during retrieval, in bytes. When unset the node picks 8x or 16x the io.Copy default buffer (32 kB) depending on file size.

swarm-act-timestamp
integer <int64>

ACT history Unix timestamp

swarm-act-publisher
string (PublicKey) ^[A-Fa-f0-9]{66}$
Example: 02ab7473879005929d10ce7d4f626412dad9fe56b0a6622038931d26bd79abf0a4

ACT content publisher's public key

swarm-act-history-address
string (SwarmAddress) ^[A-Fa-f0-9]{64}$
Example: 36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f

ACT history reference address

Responses

Response samples

Content type
application/problem+json
{
  • "code": 0,
  • "message": "string",
  • "reasons": [
    ]
}

Retrieve headers with content type and length for the reference

Identical to GET on the same reference except that no content is sent, so Range and conditional request headers are honored the same way.

path Parameters
address
required
string (SwarmAddress) ^[A-Fa-f0-9]{64}$
Example: 36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f

Swarm address of chunk

header Parameters
swarm-cache
boolean
Default: true

Indicates whether downloaded data should be cached on the node. Default: cached (true)

swarm-redundancy-strategy
integer
Enum: 0 1 2 3

Specify the retrieval strategy for redundant data. Values represent: NONE (0), DATA (1), PROX (2), RACE (3). NONE: no prefetching. DATA: prefetch only data chunks. PROX: prefetch chunks near this node. RACE: prefetch all chunks and use the first n to arrive. Multiple strategies can be cascaded if fallback mode is enabled. Default: NONE > DATA > PROX > RACE

swarm-redundancy-fallback-mode
boolean

Specify if the retrieve strategies (chunk prefetching on redundant data) are used in a fallback cascade. The default is true.

swarm-redundancy-level
integer
Enum: 0 1 2 3 4

Add redundancy to the data being uploaded so that downloaders can download it with better UX. 0 value is default and does not add any redundancy to the file.

swarm-chunk-retrieval-timeout
string (Duration)
Example: 5.0018ms

Specify the timeout for chunk retrieval. The default is 30 seconds.

swarm-act-timestamp
integer <int64>

ACT history Unix timestamp

swarm-act-publisher
string (PublicKey) ^[A-Fa-f0-9]{66}$
Example: 02ab7473879005929d10ce7d4f626412dad9fe56b0a6622038931d26bd79abf0a4

ACT content publisher's public key

swarm-act-history-address
string (SwarmAddress) ^[A-Fa-f0-9]{64}$
Example: 36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f

ACT history reference address

Responses

Response samples

Content type
application/problem+json
{
  • "code": 0,
  • "message": "string",
  • "reasons": [
    ]
}

Retrieve a file from a collection by path

path Parameters
required
SwarmAddress (string) or SwarmEncryptedReference (string) or DomainName (string) (SwarmReference)

Swarm address of content

path
required
string

Path to the file in the collection.

header Parameters
swarm-redundancy-strategy
integer
Enum: 0 1 2 3

Specify the retrieval strategy for redundant data. Values represent: NONE (0), DATA (1), PROX (2), RACE (3). NONE: no prefetching. DATA: prefetch only data chunks. PROX: prefetch chunks near this node. RACE: prefetch all chunks and use the first n to arrive. Multiple strategies can be cascaded if fallback mode is enabled. Default: NONE > DATA > PROX > RACE

swarm-redundancy-fallback-mode
boolean

Specify if the retrieve strategies (chunk prefetching on redundant data) are used in a fallback cascade. The default is true.

swarm-chunk-retrieval-timeout
string (Duration)
Example: 5.0018ms

Specify the timeout for chunk retrieval. The default is 30 seconds.

swarm-redundancy-level
integer
Enum: 0 1 2 3 4

Add redundancy to the data being uploaded so that downloaders can download it with better UX. 0 value is default and does not add any redundancy to the file.

swarm-cache
boolean
Default: true

Indicates whether downloaded data should be cached on the node. Default: cached (true)

swarm-lookahead-buffer-size
integer

Override the lookahead buffer size used during retrieval, in bytes. When unset the node picks 8x or 16x the io.Copy default buffer (32 kB) depending on file size.

Responses

Response samples

Content type
application/problem+json
{
  • "code": 0,
  • "message": "string",
  • "reasons": [
    ]
}

Tag

Get list of tags

query Parameters
offset
integer >= 0
Default: 0

The number of items to skip before starting to collect the result set.

limit
integer [ 1 .. 1000 ]
Default: 100

The numbers of items to return.

Responses

Response samples

Content type
application/json
{
  • "tags": [
    ]
}

Create Tag

Tags can be thought of as upload sessions which can be tracked using the tags endpoint. It will keep track of the chunks that are uploaded as part of the tag and will push them out to the network once a done split is called on the Tag. This happens internally if you use the Swarm-Deferred-Upload header.

Responses

Response samples

Content type
application/json
{
  • "uid": 0,
  • "address": "36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f",
  • "startedAt": "2020-06-11T11:26:42.6969797+02:00",
  • "split": 0,
  • "seen": 0,
  • "stored": 0,
  • "sent": 0,
  • "synced": 0
}

Get Tag information using Uid

path Parameters
id
required
integer (Uid)

Uid

Responses

Response samples

Content type
application/json
{
  • "uid": 0,
  • "address": "36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f",
  • "startedAt": "2020-06-11T11:26:42.6969797+02:00",
  • "split": 0,
  • "seen": 0,
  • "stored": 0,
  • "sent": 0,
  • "synced": 0
}

Delete Tag information using Uid

path Parameters
id
required
integer (Uid)

Uid

Responses

Response samples

Content type
application/problem+json
{
  • "code": 0,
  • "message": "string",
  • "reasons": [
    ]
}

Update Total Count and swarm hash for a tag of an input stream of unknown size using Uid

path Parameters
id
required
integer (Uid)

Uid

Request Body schema: application/json
optional

Can contain swarm hash to use for the tag

address
string (SwarmAddress) ^[A-Fa-f0-9]{64}$

Responses

Request samples

Content type
application/json
{
  • "address": "36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f"
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "code": 0
}

Pinning

Pin a root hash by reference

path Parameters
required
SwarmAddress (string) or SwarmEncryptedReference (string) (SwarmOnlyReference)

Swarm reference of the root hash

header Parameters
swarm-redundancy-level
object (SwarmRedundancyLevelParameter)

Add redundancy to the data being uploaded so that downloaders can download it with better UX. 0 value is default and does not add any redundancy to the file.

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "code": 0
}

Unpin a root hash by reference

path Parameters
required
SwarmAddress (string) or SwarmEncryptedReference (string) (SwarmOnlyReference)

Swarm reference of the root hash

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "code": 0
}

Get the pinning status of a root hash

path Parameters
required
SwarmAddress (string) or SwarmEncryptedReference (string) (SwarmOnlyReference)

Swarm reference of the root hash

Responses

Response samples

Content type
application/json
Example
"36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f"

Get the list of pinned root hash references

Responses

Response samples

Content type
application/json
{
  • "references": [
    ]
}

Validate pinned chunks integrity

Returns a stream of newline-delimited JSON objects (NDJSON), one per pinned reference checked. The response uses chunked transfer encoding; clients should parse each line as an independent PinIntegrityResponse object rather than buffering the body into a single JSON value.

query Parameters
SwarmAddress (string) or SwarmEncryptedReference (string) (SwarmOnlyReference)

Optional reference to check; if not provided, all pinned references are checked

Responses

Response samples

Content type
application/json
{
  • "reference": "36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f",
  • "total": 0,
  • "missing": 0,
  • "invalid": 0
}

Postal Service for Swarm

Send a message using the Postal Service for Swarm

path Parameters
topic
required
string (PssTopic)

Topic name

targets
required
string (PssTargets) ^[0-9a-fA-F]{1,6}(,[0-9a-fA-F]{1,6})*$

Target message address prefix. If multiple targets are specified, only one would be matched.

query Parameters
recipient
string (PssRecipient)

Recipient publickey

header Parameters
swarm-postage-batch-id
required
string (SwarmAddress) ^[A-Fa-f0-9]{64}$
Example: 36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f

ID of Postage Batch that is used to upload data with

Responses

Response samples

Content type
application/problem+json
{
  • "code": 0,
  • "message": "string",
  • "reasons": [
    ]
}

Subscribe to messages on a topic

path Parameters
topic
required
string (PssTopic)

Topic name

Responses

Response samples

Content type
application/problem+json
{
  • "code": 0,
  • "message": "string",
  • "reasons": [
    ]
}

GSOC

Subscribe to GSOC payloads

path Parameters
address
required
string (SwarmAddress) ^[A-Fa-f0-9]{64}$
Example: 36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f

Single Owner Chunk address (which may have multiple payloads)

query Parameters
swarm-soc-fields
string

Same as the swarm-soc-fields header, for clients that cannot set request headers (e.g. browser WebSocket). Takes precedence over the header when both are given.

swarm-cache-wrapped-chunk
boolean

Same as the swarm-cache-wrapped-chunk header, for clients that cannot set request headers (e.g. browser WebSocket). Takes precedence over the header when both are given.

header Parameters
swarm-soc-fields
string
Default: payload

Comma separated list of Single Owner Chunk fields to be serialized and channeled on every incoming GSOC message, in the given order. Allowed values are: address, recoveredPubKey, identifier, signature, wrappedAddress, span, payload. When omitted it defaults to "payload". In order to have random access on the response bytes define payload as the last field in the list since it has variable length.

swarm-cache-wrapped-chunk
boolean

Indicates whether the wrapped chunk of every incoming GSOC message should be cached locally so that it can be resolved through the bytes endpoint (useful when the single owner chunk wraps a root chunk larger than 4KB).

Responses

Response samples

Content type
application/problem+json
{
  • "code": 0,
  • "message": "string",
  • "reasons": [
    ]
}

Single owner chunk

Upload a Single Owner Chunk

path Parameters
owner
required
string (EthereumAddress) ^[A-Fa-f0-9]{40}$
Example: 36b7efd913ca4cf880b8eeac5093fa27b0825906

Ethereum address of the chunk owner

id
required
string (HexString) ^([A-Fa-f0-9]+)$
Example: cf880b8eeac5093fa27b0825906c600685

Unique identifier for the chunk

query Parameters
sig
required
string (HexString) ^([A-Fa-f0-9]+)$
Example: sig=cf880b8eeac5093fa27b0825906c600685

Signature

header Parameters
swarm-postage-batch-id
object (SwarmPostageBatchId)

ID of the postage batch to use. Either this or swarm-postage-stamp must be supplied.

swarm-postage-stamp
string (HexString) ^([A-Fa-f0-9]+)$
Example: cf880b8eeac5093fa27b0825906c600685

Postage stamp for the corresponding chunk in the request.
It is required if Swarm-Postage-Batch-Id header is missing
It consists of: \

  • batch ID - 0:32 bytes \
  • postage index (bucket and bucket index) - 32:40 bytes \
  • timestamp - 40:48 bytes \
  • signature - 48:113 bytes
swarm-tag
integer (Uid)

Associate upload with an existing Tag UID

swarm-pin
boolean

Indicates whether the uploaded data should also be locally pinned on this node

swarm-deferred-upload
boolean
Default: true

Indicates whether the uploaded data should be sent to the network immediately or deferred. Default: deferred (true)

Request Body schema: application/octet-stream
required

The SOC binary data, composed of the span (8 bytes) and up to 4KB of payload.

string <binary>

Responses

Response samples

Content type
application/json
{
  • "reference": "36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f"
}

Retrieve Single Owner Chunk data

path Parameters
owner
required
string (EthereumAddress) ^[A-Fa-f0-9]{40}$
Example: 36b7efd913ca4cf880b8eeac5093fa27b0825906

Ethereum address of the Owner of the SOC

id
required
string (HexString) ^([A-Fa-f0-9]+)$
Example: cf880b8eeac5093fa27b0825906c600685

Unique identifier for the chunk data

header Parameters
swarm-only-root-chunk
boolean

Returns only the root chunk of the content

swarm-cache
boolean
Default: true

Indicates whether downloaded data should be cached on the node. Default: cached (true)

swarm-redundancy-strategy
integer
Enum: 0 1 2 3

Specify the retrieval strategy for redundant data. Values represent: NONE (0), DATA (1), PROX (2), RACE (3). NONE: no prefetching. DATA: prefetch only data chunks. PROX: prefetch chunks near this node. RACE: prefetch all chunks and use the first n to arrive. Multiple strategies can be cascaded if fallback mode is enabled. Default: NONE > DATA > PROX > RACE

swarm-redundancy-fallback-mode
boolean

Specify if the retrieve strategies (chunk prefetching on redundant data) are used in a fallback cascade. The default is true.

swarm-chunk-retrieval-timeout
string (Duration)
Example: 5.0018ms

Specify the timeout for chunk retrieval. The default is 30 seconds.

Responses

Response samples

Content type
application/problem+json
{
  • "code": 0,
  • "message": "string",
  • "reasons": [
    ]
}

Feed

Create a feed root manifest

path Parameters
owner
required
string (EthereumAddress) ^[A-Fa-f0-9]{40}$
Example: 36b7efd913ca4cf880b8eeac5093fa27b0825906

Ethereum address of the feed owner

topic
required
string (HexString) ^([A-Fa-f0-9]+)$
Example: cf880b8eeac5093fa27b0825906c600685

Topic identifier for the feed

query Parameters
type
string (FeedType) ^(sequence|epoch)$

Feed indexing scheme (default: sequence)

header Parameters
swarm-postage-batch-id
required
string (SwarmAddress) ^[A-Fa-f0-9]{64}$
Example: 36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f

ID of Postage Batch that is used to upload data with

swarm-pin
boolean

Indicates whether the uploaded data should also be locally pinned on this node

swarm-act
boolean
Default: false

Determines if the uploaded data should be treated as ACT content

swarm-act-history-address
string (SwarmAddress) ^[A-Fa-f0-9]{64}$
Example: 36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f

ACT history reference address

swarm-redundancy-level
object (SwarmRedundancyLevelParameter)

Redundancy level for the feed manifest upload pipeline and ACT encryption

Responses

Response samples

Content type
application/json
{
  • "reference": "36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f"
}

Retrieve the latest feed update

path Parameters
owner
required
string (EthereumAddress) ^[A-Fa-f0-9]{40}$
Example: 36b7efd913ca4cf880b8eeac5093fa27b0825906

Ethereum address of the feed owner

topic
required
string (HexString) ^([A-Fa-f0-9]+)$
Example: cf880b8eeac5093fa27b0825906c600685

Topic identifier for the feed

query Parameters
at
integer

Timestamp of the update (default: now)

after
integer

Start index (default: 0)

type
string (FeedType) ^(sequence|epoch)$

Feed indexing scheme (default: sequence)

header Parameters
swarm-only-root-chunk
boolean

Returns only the root chunk of the content

swarm-cache
boolean
Default: true

Indicates whether downloaded data should be cached on the node. Default: cached (true)

swarm-redundancy-strategy
integer
Enum: 0 1 2 3

Specify the retrieval strategy for redundant data. Values represent: NONE (0), DATA (1), PROX (2), RACE (3). NONE: no prefetching. DATA: prefetch only data chunks. PROX: prefetch chunks near this node. RACE: prefetch all chunks and use the first n to arrive. Multiple strategies can be cascaded if fallback mode is enabled. Default: NONE > DATA > PROX > RACE

swarm-redundancy-fallback-mode
boolean

Specify if the retrieve strategies (chunk prefetching on redundant data) are used in a fallback cascade. The default is true.

swarm-chunk-retrieval-timeout
string (Duration)
Example: 5.0018ms

Specify the timeout for chunk retrieval. The default is 30 seconds.

Responses

Response samples

Content type
application/problem+json
{
  • "code": 0,
  • "message": "string",
  • "reasons": [
    ]
}

Stewardship

Check content availability

path Parameters
required
SwarmAddress (string) or SwarmEncryptedReference (string) or DomainName (string) (SwarmReference)

Root hash of content (can be of any type: collection, file, chunk)

header Parameters
swarm-redundancy-level
object (SwarmRedundancyLevelParameter)

Add redundancy to the data being uploaded so that downloaders can download it with better UX. 0 value is default and does not add any redundancy to the file.

Responses

Response samples

Content type
application/json
{
  • "isRetrievable": true
}

Re-upload content by reference

path Parameters
required
SwarmAddress (string) or SwarmEncryptedReference (string) or DomainName (string) (SwarmReference)

Re-uploads content for specified root hash (can be of any type: collection, file, chunk, etc.)

header Parameters
swarm-postage-batch-id
required
object (SwarmPostageBatchId)

Postage batch to use for re-upload. The chunks are re-stamped with this batch.

swarm-redundancy-level
object (SwarmRedundancyLevelParameter)

Add redundancy to the data being uploaded so that downloaders can download it with better UX. 0 value is default and does not add any redundancy to the file.

Responses

Response samples

Content type
application/problem+json
{
  • "code": 0,
  • "message": "string",
  • "reasons": [
    ]
}

Connectivity

Get overlay and underlay addresses of the node

Responses

Response samples

Content type
application/json
{
  • "overlay": "36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f",
  • "underlay": [
    ],
  • "ethereum": "36b7efd913ca4cf880b8eeac5093fa27b0825906",
  • "chain_address": "36b7efd913ca4cf880b8eeac5093fa27b0825906",
  • "publicKey": "02ab7473879005929d10ce7d4f626412dad9fe56b0a6622038931d26bd79abf0a4",
  • "pssPublicKey": "02ab7473879005929d10ce7d4f626412dad9fe56b0a6622038931d26bd79abf0a4"
}

Get a list of blocklisted peers

Responses

Response samples

Content type
application/json
{
  • "peers": [
    ]
}

Connect to a peer address

path Parameters
multi-address
required
string (MultiAddress)

Underlay address of peer

Responses

Response samples

Content type
application/json
{
  • "address": "36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f"
}

Get the list of connected peers

Responses

Response samples

Content type
application/json
{
  • "peers": [
    ]
}

Disconnect from a peer

path Parameters
address
required
string (SwarmAddress) ^[A-Fa-f0-9]{64}$
Example: 36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f

Swarm address of peer

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "code": 0
}

Ping a peer to measure latency

path Parameters
address
required
string (SwarmAddress) ^[A-Fa-f0-9]{64}$
Example: 36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f

Swarm address of peer

Responses

Response samples

Content type
application/json
{
  • "rtt": "5.0018ms"
}

Get the network topology

Responses

Response samples

Content type
application/json
{
  • "baseAddr": "36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f",
  • "population": 0,
  • "connected": 0,
  • "timestamp": "string",
  • "nnLowWatermark": 0,
  • "depth": 0,
  • "reachability": "Unknown",
  • "networkAvailability": "Unknown",
  • "bins": {
    }
}

Get the P2P welcome message

Responses

Response samples

Content type
application/json
{
  • "welcomeMessage": "string"
}

Set the P2P welcome message

Request Body schema: application/json
welcomeMessage
string

Responses

Request samples

Content type
application/json
{
  • "welcomeMessage": "string"
}

Response samples

Content type
application/json
{
  • "status": "ok",
  • "version": "string",
  • "apiVersion": "0.0.0"
}

Status

Get the overall health status of the node

Health Status will indicate node healthiness.

If node is unhealthy please check node logs for errors.

Responses

Response samples

Content type
application/json
{
  • "status": "ok",
  • "version": "string",
  • "apiVersion": "0.0.0"
}

Check if the node is ready to accept traffic

Responses

Response samples

Content type
application/problem+json
{
  • "code": 0,
  • "message": "string",
  • "reasons": [
    ]
}

Get the reserve state

Responses

Response samples

Content type
application/json
{
  • "radius": 0,
  • "storageRadius": 0,
  • "commitment": 0,
  • "reserveCapacityDoubling": 0
}

Get the chain state

Responses

Response samples

Content type
application/json
{
  • "chainTip": 0,
  • "block": 0,
  • "totalAmount": "1000000000000000000",
  • "currentPrice": "1000000000000000000",
  • "minimumValidityBlocks": 0
}

Get a snapshot of local storage debug info

Responses

Response samples

Content type
application/json
{
  • "Upload": {
    },
  • "Pinning": {
    },
  • "Cache": {
    },
  • "Reserve": {
    },
  • "ChunkStore": {
    }
}

Get node information

Responses

Response samples

Content type
application/json
{
  • "beeMode": "light",
  • "chequebookEnabled": true,
  • "swapEnabled": true
}

Balance

Get balances with all known peers

Responses

Response samples

Content type
application/json
{
  • "balances": [
    ]
}

Get the balance with a specific peer

path Parameters
peer
required
string (SwarmAddress) ^[A-Fa-f0-9]{64}$
Example: 36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f

Swarm address of peer

Responses

Response samples

Content type
application/json
{
  • "peer": "36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f",
  • "balance": "1000000000000000000",
  • "thresholdreceived": "1000000000000000000",
  • "thresholdgiven": "1000000000000000000"
}

Get past due consumption balances with all known peers

Responses

Response samples

Content type
application/json
{
  • "balances": [
    ]
}

Get past due consumption balance with a specific peer

path Parameters
peer
required
string (SwarmAddress) ^[A-Fa-f0-9]{64}$
Example: 36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f

Swarm address of peer

Responses

Response samples

Content type
application/json
{
  • "peer": "36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f",
  • "balance": "1000000000000000000",
  • "thresholdreceived": "1000000000000000000",
  • "thresholdgiven": "1000000000000000000"
}

Get accounting values for all known peers

Responses

Response samples

Content type
application/json
{
  • "peerData": {
    }
}

Chequebook

Get the chequebook contract address

Responses

Response samples

Content type
application/json
{
  • "chequebookAddress": "36b7efd913ca4cf880b8eeac5093fa27b0825906"
}

Get the balance of the chequebook

Responses

Response samples

Content type
application/json
{
  • "totalBalance": "1000000000000000000",
  • "availableBalance": "1000000000000000000"
}

Get the last cashout status for a peer

path Parameters
peer
required
string (SwarmAddress) ^[A-Fa-f0-9]{64}$
Example: 36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f

Swarm address of peer

Responses

Response samples

Content type
application/json
{
  • "peer": "36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f",
  • "lastCashedCheque": {
    },
  • "transactionHash": "0x780cb6a37d1946978087896e1e489c37e30fe3e329510fff8d97360f73529f5a",
  • "result": {
    },
  • "uncashedAmount": "1000000000000000000"
}

Cash out the last cheque for a peer

path Parameters
peer
required
string (SwarmAddress) ^[A-Fa-f0-9]{64}$
Example: 36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f

Swarm address of peer

header Parameters
gas-price
integer (GasPrice)

Gas price for transaction

gas-limit
integer (GasLimit) [ 0 .. 18446744073709552000 ]

Gas limit for transaction

Responses

Response samples

Content type
application/json
{
  • "transactionHash": "0x780cb6a37d1946978087896e1e489c37e30fe3e329510fff8d97360f73529f5a"
}

Get the last cheques for a peer

path Parameters
peer
required
string (SwarmAddress) ^[A-Fa-f0-9]{64}$
Example: 36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f

Swarm address of peer

Responses

Response samples

Content type
application/json
{
  • "peer": "36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f",
  • "lastreceived": {
    },
  • "lastsent": {
    }
}

Get the last cheques for all peers

Responses

Response samples

Content type
application/json
{
  • "lastcheques": [
    ]
}

Deposit tokens into the chequebook

query Parameters
amount
required
integer

Amount of tokens to deposit

header Parameters
gas-price
integer (GasPrice)

Gas price for transaction

Responses

Response samples

Content type
application/json
{
  • "transactionHash": "0x780cb6a37d1946978087896e1e489c37e30fe3e329510fff8d97360f73529f5a"
}

Withdraw tokens from the chequebook

query Parameters
amount
required
integer

Amount of tokens to withdraw

header Parameters
gas-price
integer (GasPrice)

Gas price for transaction

Responses

Response samples

Content type
application/json
{
  • "transactionHash": "0x780cb6a37d1946978087896e1e489c37e30fe3e329510fff8d97360f73529f5a"
}

Envelope

Create a postage stamp for a chunk

path Parameters
address
required
string (SwarmAddress) ^[A-Fa-f0-9]{64}$
Example: 36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f

Swarm address of the chunk to stamp

header Parameters
swarm-postage-batch-id
required
object (SwarmPostageBatchId)

ID of Postage Batch that is used to upload data with

Responses

Response samples

Content type
application/json
{
  • "issuer": "36b7efd913ca4cf880b8eeac5093fa27b0825906",
  • "index": "1a2b3c4d5e6f7a8b",
  • "timestamp": "1a2b3c4d5e6f7a8b",
  • "signature": "1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e"
}

Settlements

Get settlement amounts sent and received with a peer

path Parameters
peer
required
string (SwarmAddress) ^[A-Fa-f0-9]{64}$
Example: 36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f

Swarm address of peer

Responses

Response samples

Content type
application/json
{
  • "peer": "36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f",
  • "received": "1000000000000000000",
  • "sent": "1000000000000000000"
}

Get settlements with all known peers and totals

Responses

Response samples

Content type
application/json
{
  • "totalReceived": "1000000000000000000",
  • "totalSent": "1000000000000000000",
  • "settlements": [
    ]
}

Get time-based settlements with all known peers and totals

Responses

Response samples

Content type
application/json
{
  • "totalReceived": "1000000000000000000",
  • "totalSent": "1000000000000000000",
  • "settlements": [
    ]
}

Transaction

Get list of pending transactions

Responses

Response samples

Content type
application/json
{
  • "pendingTransactions": [
    ]
}

Retrieve transaction information

path Parameters
hash
required
string (TransactionHash) ^0x[A-Fa-f0-9]{64}$
Example: 0x780cb6a37d1946978087896e1e489c37e30fe3e329510fff8d97360f73529f5a

Hash of the transaction

Responses

Response samples

Content type
application/json
{
  • "transactionHash": "0x780cb6a37d1946978087896e1e489c37e30fe3e329510fff8d97360f73529f5a",
  • "to": "36b7efd913ca4cf880b8eeac5093fa27b0825906",
  • "nonce": 0,
  • "gasPrice": "1000000000000000000",
  • "gasLimit": 0,
  • "gasTipCap": "1000000000000000000",
  • "gasTipBoost": 0,
  • "gasFeeCap": "1000000000000000000",
  • "data": "string",
  • "created": "2020-06-11T11:26:42.6969797+02:00",
  • "description": "string",
  • "value": "1000000000000000000"
}

Rebroadcast a transaction

path Parameters
hash
required
string (TransactionHash) ^0x[A-Fa-f0-9]{64}$
Example: 0x780cb6a37d1946978087896e1e489c37e30fe3e329510fff8d97360f73529f5a

Hash of the transaction

Responses

Response samples

Content type
application/json
{
  • "transactionHash": "0x780cb6a37d1946978087896e1e489c37e30fe3e329510fff8d97360f73529f5a"
}

Cancel existing transaction

path Parameters
hash
required
string (TransactionHash) ^0x[A-Fa-f0-9]{64}$
Example: 0x780cb6a37d1946978087896e1e489c37e30fe3e329510fff8d97360f73529f5a

Hash of the transaction

header Parameters
gas-price
integer (GasPrice)

Gas price for transaction

Responses

Response samples

Content type
application/json
{
  • "transactionHash": "0x780cb6a37d1946978087896e1e489c37e30fe3e329510fff8d97360f73529f5a"
}

Postage Stamps

Get postage stamps for this node

Responses

Response samples

Content type
application/json
{
  • "stamps": [
    ]
}

Get an individual postage batch status

path Parameters
batch_id
required
string (BatchID) ^[A-Fa-f0-9]{64}$
Example: 36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f

Swarm address of the stamp

Responses

Response samples

Content type
application/json
Example
{
  • "batchID": "36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f",
  • "utilization": 0,
  • "utilizationRatio": 1,
  • "usable": true,
  • "label": "string",
  • "depth": 0,
  • "amount": "1000000000000000000",
  • "bucketDepth": 0,
  • "blockNumber": 0,
  • "immutableFlag": true,
  • "exists": true,
  • "batchTTL": 0
}

Update the label of an existing postage batch

path Parameters
batch_id
required
string (BatchID) ^[A-Fa-f0-9]{64}$
Example: 36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f

Swarm address of the stamp

Request Body schema: application/json
required
label
required
string

New label for the postage batch

Responses

Request samples

Content type
application/json
{
  • "label": "string"
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "code": 0
}

Get extended bucket data of a batch

path Parameters
batch_id
required
string (BatchID) ^[A-Fa-f0-9]{64}$
Example: 36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f

Swarm address of the stamp

Responses

Response samples

Content type
application/json
{
  • "depth": 0,
  • "bucketDepth": 0,
  • "bucketUpperBound": 0,
  • "buckets": [
    ]
}

Buy a new postage batch.

Be aware, this endpoint creates an on-chain transaction and transfers BZZ from the node's Ethereum account, directly affecting the wallet balance!

path Parameters
amount
required
string (BigInt)
Example: 1000000000000000000

Amount of BZZ added that the postage batch will have.

depth
required
integer

Batch depth (logarithm) specifying the maximum number of chunks this stamp can cover. Must be greater than the default bucket depth (16)

query Parameters
label
string

An optional label for this batch

header Parameters
immutable
boolean
gas-price
integer (GasPrice)

Gas price for transaction

gas-limit
integer (GasLimit) [ 0 .. 18446744073709552000 ]

Gas limit for transaction

Responses

Response samples

Content type
application/json
{
  • "batchID": "36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f",
  • "txHash": "0x780cb6a37d1946978087896e1e489c37e30fe3e329510fff8d97360f73529f5a"
}

Top up an existing postage batch.

Be aware, this endpoint creates an on-chain transaction and transfers BZZ from the node's Ethereum account, directly affecting the wallet balance!

path Parameters
batch_id
required
string (BatchID) ^[A-Fa-f0-9]{64}$
Example: 36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f

Batch ID to top up

amount
required
integer

Amount of BZZ per chunk to top up to an existing postage batch.

header Parameters
gas-price
integer (GasPrice)

Gas price for transaction

gas-limit
integer (GasLimit) [ 0 .. 18446744073709552000 ]

Gas limit for transaction

Responses

Response samples

Content type
application/json
{
  • "batchID": "36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f",
  • "txHash": "0x780cb6a37d1946978087896e1e489c37e30fe3e329510fff8d97360f73529f5a"
}

Dilute an existing postage batch.

Be aware, this endpoint creates an on-chain transaction and transfers BZZ from the node's Ethereum account, directly affecting the wallet balance!

path Parameters
batch_id
required
string (BatchID) ^[A-Fa-f0-9]{64}$
Example: 36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f

Batch ID to dilute

depth
required
integer

The new batch depth, which must be greater than the current depth

header Parameters
gas-price
integer (GasPrice)

Gas price for transaction

gas-limit
integer (GasLimit) [ 0 .. 18446744073709552000 ]

Gas limit for transaction

Responses

Response samples

Content type
application/json
{
  • "batchID": "36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f",
  • "txHash": "0x780cb6a37d1946978087896e1e489c37e30fe3e329510fff8d97360f73529f5a"
}

Get all globally available postage batches

Responses

Response samples

Content type
application/json
{
  • "batches": [
    ]
}

Get a single globally available postage batch by ID

path Parameters
batch_id
required
string (BatchID) ^[A-Fa-f0-9]{64}$
Example: 36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f

ID of the postage batch

Responses

Response samples

Content type
application/json
{
  • "batchID": "36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f",
  • "value": "1000000000000000000",
  • "start": 0,
  • "owner": "36b7efd913ca4cf880b8eeac5093fa27b0825906",
  • "depth": 0,
  • "bucketDepth": 0,
  • "immutable": true,
  • "batchTTL": 0
}

RChash

Get reserve commitment hash with sample proofs

path Parameters
depth
required
integer >= 0
Default: 0

The storage depth.

anchor1
required
string (HexString) ^([A-Fa-f0-9]+)$
Example: cf880b8eeac5093fa27b0825906c600685

The first anchor.

anchor2
required
string (HexString) ^([A-Fa-f0-9]+)$
Example: cf880b8eeac5093fa27b0825906c600685

The second anchor.

Responses

Response samples

Content type
application/json
{
  • "durationSeconds": 30.5,
  • "hash": "36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f",
  • "proofs": {
    }
}

RedistributionState

Get the node's redistribution game status

Responses

Response samples

Content type
application/json
{
  • "minimumGasFunds": "1000000000000000000",
  • "hasSufficientFunds": true,
  • "isFrozen": true,
  • "isFullySynced": true,
  • "isHealthy": true,
  • "enabled": true,
  • "hasCommittedThisRound": true,
  • "hasRevealedThisRound": true,
  • "phase": "string",
  • "round": 0,
  • "lastWonRound": 0,
  • "lastPlayedRound": 0,
  • "lastFrozenRound": 0,
  • "lastSelectedRound": 0,
  • "lastSampleDurationSeconds": 0,
  • "block": 0,
  • "reward": "1000000000000000000",
  • "fees": "1000000000000000000"
}

Enable or disable participation in new redistribution rounds

Controls whether the node will commit in a new redistribution round. Sampling still runs while disabled so that a later re-enable can commit in the following commit phase. Disabling does not abort an in-flight commit and does not skip reveal or claim for a round that already committed. Re-enabling during a commit phase that was already skipped does not retry that round. After a node restart participation is enabled again.

Request Body schema: application/json
required
enabled
required
boolean

Whether the node should commit in new redistribution rounds. Sampling still runs while disabled.

Responses

Request samples

Content type
application/json
{
  • "enabled": true
}

Response samples

Content type
application/json
{
  • "enabled": true
}

Wallet

Get wallet balance for BZZ and xDAI

Responses

Response samples

Content type
application/json
{
  • "bzzBalance": "1000000000000000000",
  • "nativeTokenBalance": "1000000000000000000",
  • "chainID": 0,
  • "chequebookContractAddress": "36b7efd913ca4cf880b8eeac5093fa27b0825906",
  • "walletAddress": "36b7efd913ca4cf880b8eeac5093fa27b0825906"
}

Withdraw BZZ or xDAI to a whitelisted address

path Parameters
coin
required
string (WithdrawCoin)
Enum: "bzz" "nativetoken"
query Parameters
amount
required
string (BigInt)
Example: amount=1000000000000000000

Numeric string representing an integer that may exceed Number.MAX_SAFE_INTEGER (2^53-1)

address
required
string (EthereumAddress) ^[A-Fa-f0-9]{40}$
Example: address=36b7efd913ca4cf880b8eeac5093fa27b0825906

Responses

Response samples

Content type
application/json
{
  • "transactionHash": "0x780cb6a37d1946978087896e1e489c37e30fe3e329510fff8d97360f73529f5a"
}

Staking

Get the withdrawable staked amount.

This endpoint fetches any amount that is possible to withdraw as surplus.

Responses

Response samples

Content type
application/json
{
  • "withdrawableAmount": "1000000000000000000"
}

Withdraw the extra withdrawable staked amount.

This endpoint withdraws any amount that is possible to withdraw as surplus.

header Parameters
gas-price
integer (GasPrice)

Gas price for transaction

gas-limit
integer (GasLimit) [ 0 .. 18446744073709552000 ]

Gas limit for transaction

Responses

Response samples

Content type
application/json
{
  • "txHash": "0x780cb6a37d1946978087896e1e489c37e30fe3e329510fff8d97360f73529f5a"
}

Deposit an amount for staking.

Be aware, this endpoint creates an on-chain transaction and transfers BZZ from the node's Ethereum account, directly affecting the wallet balance.

path Parameters
amount
required
string

Amount of BZZ added that will be deposited for staking.

header Parameters
gas-price
integer (GasPrice)

Gas price for transaction

gas-limit
integer (GasLimit) [ 0 .. 18446744073709552000 ]

Gas limit for transaction

Responses

Response samples

Content type
application/json
{
  • "txHash": "0x780cb6a37d1946978087896e1e489c37e30fe3e329510fff8d97360f73529f5a"
}

Get the staked amount.

This endpoint fetches the total staked amount and the minimum additional deposit from the blockchain. The first deposit is at least 10 BZZ times 2^height. Subsequent deposits are at least 1 PLUR, or more if the price oracle has increased since the last deposit.

Responses

Response samples

Content type
application/json
{
  • "stakedAmount": "1000000000000000000",
  • "minimumDeposit": "1000000000000000000"
}

Withdraw all previously staked amounts.

Be aware, this endpoint can only be called when the contract is paused and undergoing migration to a new contract.

header Parameters
gas-price
integer (GasPrice)

Gas price for transaction

gas-limit
integer (GasLimit) [ 0 .. 18446744073709552000 ]

Gas limit for transaction

Responses

Response samples

Content type
application/json
{
  • "txHash": "0x780cb6a37d1946978087896e1e489c37e30fe3e329510fff8d97360f73529f5a"
}

Logging

Get all available loggers.

Responses

Response samples

Content type
application/json
{
  • "tree": {
    },
  • "loggers": [
    ]
}

Get all available loggers that match the specified expression.

path Parameters
exp
required
string (LoggerExp) ^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[...
Example: b25lL25hbWU=

Regular expression or a subsystem that matches the logger(s).

Responses

Response samples

Content type
application/json
{
  • "tree": {
    },
  • "loggers": [
    ]
}

Set logger(s) verbosity level.

path Parameters
exp
required
string (LoggerExp) ^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[...
Example: b25lL25hbWU=

Regular expression or a subsystem that matches the logger(s).

verbosity
required
string
Enum: "none" "error" "warning" "info" "debug" "all"

Verbosity level to apply to the matching logger(s).

Responses

Response samples

Content type
application/problem+json
{
  • "code": 0,
  • "message": "string",
  • "reasons": [
    ]
}

Node Status

Get the current status snapshot of this node.

Responses

Response samples

Content type
application/json
{
  • "overlay": "36b7efd913ca4cf880b8eeac5093fa27b0825906c600685b6abdd6566e6cfe8f",
  • "proximity": 0,
  • "beeMode": "light",
  • "reserveSize": 0,
  • "reserveSizeWithinRadius": 0,
  • "pullsyncRate": 0,
  • "storageRadius": 0,
  • "connectedPeers": 0,
  • "neighborhoodSize": 0,
  • "requestFailed": true,
  • "batchCommitment": 0,
  • "isReachable": true,
  • "lastSyncedBlock": 0,
  • "committedDepth": 0,
  • "isWarmingUp": true
}

Get the current status snapshot of this node connected peers.

Responses

Response samples

Content type
application/json
{
  • "snapshots": [
    ]
}

Get the current neighborhoods status of this node.

Responses

Response samples

Content type
application/json
{
  • "neighborhoods": [
    ]
}