Leveraging the Bee API for Custom Swarm Application Development

The Bee API exposes a RESTful HTTP interface on http://localhost:1633 that enables developers to store, retrieve, and manage immutable data directly on the Swarm decentralized storage network.

The ethersphere/awesome-swarm repository serves as the canonical resource hub for developers leveraging the Bee API for custom Swarm application development. This guide examines the architectural layers, implementation patterns, and production-ready code examples required to build performant decentralized applications on the Swarm network.

Understanding the Bee API Architecture

The Bee ecosystem consists of four interconnected layers that abstract the complexity of decentralized storage into accessible developer interfaces.

Bee Node (Client)

The Bee Node is the core client software that runs the Swarm protocol stack. Implemented in Go, it handles content addressing, data chunking, encryption, and cross-network replication. When running locally, the node exposes the API on port 1633 and serves as the gateway between your application and the decentralized storage layer.

RESTful API Endpoints

The Bee API provides versioned HTTP endpoints that map directly to internal Bee services. Key endpoint groups include:

• /files – High-level file upload and download operations
• /chunks – Low-level access to individual 4KB data chunks
• /feeds – Append-only logs for mutable data structures
• /pins – Local data retention management

The complete endpoint reference is documented at line 102 of the repository's README.md file, linking to the official Bee API Reference.

Bee-JS Library Abstraction

Bee-JS is the official JavaScript/TypeScript wrapper that abstracts raw HTTP calls into idiomatic methods. According to the ethersphere/awesome-swarm documentation, this library is the recommended integration path for Node.js and browser environments. It provides high-level functions such as uploadFile(), downloadFile(), and createFeed(), handling request serialization, error handling, and response parsing automatically.

Mantaray Manifest

The Mantaray Manifest is a low-level binary format that Swarm uses to represent directory trees and routing structures. When building applications requiring fine-grained control over content routing or custom pinning strategies, developers utilize libraries like mantaray-js or mantaray-py to construct or decode these manifests manually.

Typical Development Workflow

Building applications on Swarm follows a predictable five-step pattern:

1. Provision a Bee node using Docker, native binary, or Kubernetes deployment. Ensure the node is funded with xBZZ (Swarm's native token) for postage stamps.
2. Instantiate the Bee-JS client by pointing it to the node's API endpoint (http://localhost:1633 by default).
3. Upload data using uploadFile() or uploadDirectory() methods. The operation returns a Swarm reference (a cryptographic hash prefixed with bafy... or similar).
4. Persist the reference in your application's state layer—whether that's a smart contract, a Swarm feed, or an off-chain database.
5. Retrieve data by invoking downloadFile() with the stored reference, enabling immutable content delivery.

Because Swarm employs content addressing, any modification generates a new reference, providing inherent versioning and integrity guarantees without additional infrastructure.

Key Advantages of the Bee API

Feature	Benefit
Content addressing	Data integrity is cryptographically guaranteed; references are deterministic hashes of the content.
Built-in redundancy	Bee automatically replicates chunks across the network using the DISC (Distributed Immutable Store of Chunks) protocol.
Feed support	Append-only logs enable mutable state on immutable infrastructure, perfect for social feeds or update streams.
Pinning API	Nodes can persist specific content locally via /pins endpoints, ensuring availability for critical data.
Extensible architecture	Low-level access to chunks and manifests allows custom routing logic and advanced storage patterns.

Practical Bee API Implementation Examples

The following examples demonstrate common operations using the Bee-JS library against a local node running at http://localhost:1633.

Uploading Single Files

Use the uploadFile() method to store individual files and retrieve their Swarm reference:

import { Bee } from '@ethersphere/bee-js'

const bee = new Bee('http://localhost:1633')
const file = new File(['Hello Swarm!'], 'hello.txt', { type: 'text/plain' })

async function upload() {
  const hash = await bee.uploadFile(file)
  console.log('Swarm reference:', hash.reference)   // e.g. bafy...
}
upload()

Downloading Content

Retrieve immutable data using the downloadFile() method with a valid reference:

async function download(ref) {
  const download = await bee.downloadFile(ref)
  const text = await download.text()
  console.log('File content:', text)                // "Hello Swarm!"
}
download('bafy...')   // use the reference printed above

Uploading Directory Structures

For static websites or multi-file datasets, use uploadDirectory() to create a Mantaray manifest automatically:

import { uploadDirectory } from '@ethersphere/bee-js'

async function uploadDir() {
  const dir = {
    'index.html': new File(['<h1>Swarm</h1>'], 'index.html', { type: 'text/html' }),
    'style.css':  new File(['body { font-family: sans-serif; }'], 'style.css')
  }
  const hash = await uploadDirectory(bee, dir)
  console.log('Directory reference:', hash.reference)
}
uploadDir()

Creating and Writing to Feeds

Feeds provide mutable pointers to immutable data. Use makeFeedWriter() to create append-only logs:

import { makeFeedWriter } from '@ethersphere/bee-js'

async function writeFeed() {
  const writer = await makeFeedWriter(bee, 'my-feed', 'my-topic')
  const payload = new Uint8Array(Buffer.from('first entry'))
  await writer.upload(payload)
}
writeFeed()

Pinning Data for Local Retention

Ensure critical data remains available on your node using the pin() method:

async function pin(ref) {
  await bee.pin(ref)               // instruct the node to retain the data
  console.log('Pinned', ref)
}
pin('bafy...')

Essential Repository Resources

The ethersphere/awesome-swarm repository provides critical navigation files for developers:

File	Role	Direct Link
README.md	Main entry point; lists projects, links to Bee API docs, and provides context for the ecosystem.	README.md
CONTRIBUTING.md	Guidelines for adding new resources or improving the list; useful for extending the knowledge base.	CONTRIBUTING.md

Line 102 of README.md specifically links to the official Bee API Reference, which documents the complete endpoint specification for the ethersphere/bee implementation.

Summary

• The Bee API exposes a RESTful interface on port 1633 that serves as the primary gateway for Swarm decentralized storage operations.
• Bee-JS provides the recommended abstraction layer, offering idiomatic methods like uploadFile(), downloadFile(), and makeFeedWriter() that handle HTTP serialization automatically.
• Content addressing ensures data integrity through cryptographic hashing, while the Mantaray Manifest format enables complex directory structures and custom routing logic.
• The ethersphere/awesome-swarm repository's README.md (specifically line 102) links to official API documentation, while CONTRIBUTING.md provides guidelines for ecosystem participation.

Frequently Asked Questions

How do I connect to a Bee node using the Bee-JS library?

Instantiate the Bee class with your node's API endpoint URL, typically http://localhost:1633 for local development. The constructor accepts the base URL and optional configuration for request timeouts or authentication headers if your node requires them.

What is the difference between uploading files and chunks in the Bee API?

The /files endpoint (accessed via uploadFile()) handles high-level file storage with automatic content-type detection and manifest creation, while the /chunks endpoint provides low-level access to the 4KB data chunks that form Swarm's underlying storage layer. Most applications should use the file API unless implementing custom chunking logic or direct DISC protocol interactions.

How do I ensure my data remains available on the Swarm network?

Use the pinning feature via the pin() method or /pins endpoint to instruct your local node to retain specific data indefinitely. For network-wide persistence, ensure your data is sufficiently stamped with postage stamps (xBZZ) to incentivize storage by other nodes, and monitor the redundancy status through the node's status endpoints.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}