# Leveraging the Bee API for Custom Swarm Application Development

> Explore the Bee API for custom Swarm application development. Store, retrieve, and manage immutable data on Swarm with this powerful RESTful HTTP interface. Learn more now

- Repository: [Ethersphere/awesome-swarm](https://github.com/ethersphere/awesome-swarm)
- Tags: how-to-guide
- Published: 2026-03-01

---

**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`](https://github.com/ethersphere/awesome-swarm/blob/main/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:

```javascript
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:

```javascript
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:

```javascript
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:

```javascript
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:

```javascript
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`](https://github.com/ethersphere/awesome-swarm/blob/main/README.md) | Main entry point; lists projects, links to Bee API docs, and provides context for the ecosystem. | [README.md](https://github.com/ethersphere/awesome-swarm/blob/master/README.md) |
| [`CONTRIBUTING.md`](https://github.com/ethersphere/awesome-swarm/blob/main/CONTRIBUTING.md) | Guidelines for adding new resources or improving the list; useful for extending the knowledge base. | [CONTRIBUTING.md](https://github.com/ethersphere/awesome-swarm/blob/master/CONTRIBUTING.md) |

Line 102 of [`README.md`](https://github.com/ethersphere/awesome-swarm/blob/main/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`](https://github.com/ethersphere/awesome-swarm/blob/main/README.md) (specifically line 102) links to official API documentation, while [`CONTRIBUTING.md`](https://github.com/ethersphere/awesome-swarm/blob/main/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.