### Clone Repository and Install Dependencies

Source: https://github.com/fileverse/fileverse-storage-v2/blob/main/README.md

Instructions for cloning the Fileverse Storage V2 repository and installing its Node.js dependencies using npm.

```bash
git clone <repository-url>
cd fileverse-storage-v2
npm install
```

--------------------------------

### Build and Run Fileverse Storage V2

Source: https://github.com/fileverse/fileverse-storage-v2/blob/main/README.md

Commands to build the project for production and start the server, including options for running background jobs for file cleanup.

```bash
# Development
npm run dev
npm run dev:unpin-gate-cron
npm run dev:unpin-deleted-file-cron

# Production
npm run build
npm start
npm run start:unpin-gate-cron
npm run start:unpin-deleted-file-cron
```

--------------------------------

### GET /community/list

Source: https://context7.com/fileverse/fileverse-storage-v2/llms.txt

Lists community files with pagination and filtering options.

```APIDOC
## List Community Files

### Description
Lists community files with pagination, filtering by category, search, and favorites. Results are sorted by number of favorites.

### Method
GET

### Endpoint
/community/list

### Query Parameters
- **page** (integer) - Optional - The page number for pagination.
- **limit** (integer) - Optional - The number of items per page.
- **category** (string) - Optional - Filter by file category.
- **search** (string) - Optional - Search term for file titles.
- **onlyFavorites** (boolean) - Optional - Filter to show only favorited files.
- **publishedBy** (string) - Optional - Filter by publisher's address.

### Headers
- **Invoker** (string) - Required - The invoker address.

### Response
#### Success Response (200)
- **files** (array) - An array of community file objects.
  - **_id** (string) - The unique identifier of the file.
  - **publishedBy** (string) - The address of the publisher.
  - **thumbnailIPFSHash** (string) - The IPFS hash of the thumbnail.
  - **title** (string) - The title of the file.
  - **category** (string) - The category of the file.
  - **totalFavorites** (integer) - The total number of favorites.
  - **fileLink** (string) - The direct link to the file.
  - **timeStamp** (integer) - The timestamp of publication.
  - **isFavourite** (boolean) - Indicates if the file is favorited by the invoker.
- **pagination** (object) - Pagination details.
  - **currentPage** (integer) - The current page number.
  - **totalPages** (integer) - The total number of pages.
  - **totalFiles** (integer) - The total number of files.
  - **limit** (integer) - The items per page limit.
  - **hasMore** (boolean) - Indicates if there are more pages.
```

--------------------------------

### Fileverse Storage Configuration

Source: https://github.com/fileverse/fileverse-storage-v2/blob/main/README.md

Example `.env` file content showing required environment variables for database connection, IPFS provider credentials, server settings, and blockchain configuration.

```env
# Database
MONGODB_URI=your_mongodb_connection_string

# IPFS Providers
PINATA_API_KEY=your_pinata_api_key
PINATA_SECRET_API_KEY=your_pinata_secret_key
FILEBASE_ACCESS_KEY=your_filebase_access_key
FILEBASE_SECRET_KEY=your_filebase_secret_key
WEB3_STORAGE_TOKEN=your_web3_storage_token

# Server
PORT=3000
NODE_ENV=development

# Blockchain
DEFAULT_CHAIN_ID=1
```

--------------------------------

### GET /floppy/list

Source: https://context7.com/fileverse/fileverse-storage-v2/llms.txt

Lists all floppy tokens available for a contract, optionally filtered by identity commitment. This endpoint helps discover available storage tokens.

```APIDOC
## GET /floppy/list

### Description
List all floppy tokens available for a contract, optionally filtered by identity commitment. This endpoint helps discover available storage tokens.

### Method
GET

### Endpoint
/floppy/list

### Parameters
#### Query Parameters
- **identityCommitment** (string) - Optional - Filters the list by a specific identity commitment.

#### Headers
- **Authorization** (string) - Required - Bearer token for authentication.
- **Contract** (string) - Required - The contract address.
- **Invoker** (string) - Required - The address of the invoker.
- **Chain** (string) - Required - The chain ID.

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the list retrieval was successful.
- **floppy** (array of objects) - A list of available floppy tokens.
  - **shortCode** (string) - The short code of the floppy token.
  - **name** (string) - The name of the floppy token.
  - **diskSpace** (integer) - The amount of disk space offered by the token.
  - **description** (string) - A description of the floppy token.

#### Response Example
```json
{
  "success": true,
  "floppy": [
    {
      "shortCode": "FLOPPY123",
      "name": "Storage Boost",
      "diskSpace": 100000000,
      "description": "100MB extra storage"
    }
  ]
}
```
```

--------------------------------

### GET /floppy/get/{shortCode}

Source: https://context7.com/fileverse/fileverse-storage-v2/llms.txt

Retrieves detailed information about a specific floppy token using its short code. This endpoint provides comprehensive details for a given token.

```APIDOC
## GET /floppy/get/{shortCode}

### Description
Get details of a specific floppy token by its short code. This endpoint provides comprehensive details for a given token.

### Method
GET

### Endpoint
/floppy/get/{shortCode}

### Parameters
#### Path Parameters
- **shortCode** (string) - Required - The short code of the floppy token to retrieve.

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the details retrieval was successful.
- **data** (object) - Contains the details of the floppy token.
  - **shortCode** (string) - The short code of the floppy token.
  - **sgid** (string) - The Semaphore Group ID associated with the token.
  - **name** (string) - The name of the floppy token.
  - **description** (string) - A description of the floppy token.
  - **diskSpace** (integer) - The amount of disk space offered by the token.
  - **img** (string) - URL to an image representing the floppy token.

#### Response Example
```json
{
  "success": true,
  "data": {
    "shortCode": "FLOPPY123",
    "sgid": "semaphore-group-id",
    "name": "Storage Boost",
    "description": "100MB extra storage",
    "diskSpace": 100000000,
    "img": "https://..."
  }
}
```
```

--------------------------------

### Health Check Endpoint

Source: https://github.com/fileverse/fileverse-storage-v2/blob/main/README.md

Demonstrates how to perform a health check on the Fileverse Storage service using a simple HTTP GET request.

```bash
curl http://localhost:3000/ping
# Response: {"reply":"pong"}
```

--------------------------------

### GET /community/get/{dsheetId}

Source: https://context7.com/fileverse/fileverse-storage-v2/llms.txt

Retrieves a specific community file by its dSheet ID.

```APIDOC
## Get Community File

### Description
Retrieves a specific community file by its dSheet ID.

### Method
GET

### Endpoint
/community/get/{dsheetId}

### Path Parameters
- **dsheetId** (string) - Required - The dSheet ID of the file to retrieve.

### Headers
- **Contract** (string) - Required - The contract address.

### Response
#### Success Response (200)
- **_id** (string) - The unique identifier of the file.
- **publishedBy** (string) - The address of the publisher.
- **thumbnailIPFSHash** (string) - The IPFS hash of the thumbnail.
- **title** (string) - The title of the file.
- **category** (string) - The category of the file.
- **fileLink** (string) - The direct link to the file.
- **dsheetId** (string) - The dSheet ID of the file.
- **favoritedBy** (array) - An array of addresses that favorited the file.
- **timeStamp** (integer) - The timestamp of publication.
```

--------------------------------

### Get API Access Key (Shell)

Source: https://context7.com/fileverse/fileverse-storage-v2/llms.txt

Retrieves stored encrypted API access key materials using the hashed key ID. Returns the ID, encrypted key material, and encrypted application material, or a not found error if the ID does not exist.

```shell
curl -X GET http://localhost:3000/api-access/hashed-key-id
```

--------------------------------

### Get Specific Community File

Source: https://context7.com/fileverse/fileverse-storage-v2/llms.txt

Retrieves details of a specific community file using its dSheet ID. Requires the contract address.

```bash
curl -X GET http://localhost:3000/community/get/file-123 \
  -H "Contract: 0x1234567890abcdef1234567890abcdef12345678"
```

--------------------------------

### Get Floppy Token Details (Shell)

Source: https://context7.com/fileverse/fileverse-storage-v2/llms.txt

Retrieves detailed information about a specific floppy token using its short code. This endpoint does not require authentication or contract-specific headers. Returns the floppy token's details including its SGID, name, description, disk space, and image URL.

```shell
curl -X GET http://localhost:3000/floppy/get/FLOPPY123
```

--------------------------------

### Get Storage Usage

Source: https://context7.com/fileverse/fileverse-storage-v2/llms.txt

Fetches the current storage usage, total limits, and any extra storage allocated for one or more contract addresses. It supports querying multiple contracts by providing a comma-separated list of addresses. The response includes usage in bytes.

```bash
# Get storage usage (supports comma-separated contract addresses)
curl -X GET http://localhost:3000/limit/use \
  -H "Contract: 0x1234567890abcdef1234567890abcdef12345678,0xanothercontract..." \
  -H "Invoker: 0xabcdef1234567890abcdef1234567890abcdef12" \
  -H "Chain: 1"

# Response:
# {
#   "storageLimit": 200000000,
#   "extraStorage": 50000000,
#   "storageUse": 15000000,
#   "unit": "bytes",
#   "contractAddress": "0x1234567890abcdef1234567890abcdef12345678,0xanothercontract..."
# }
```

--------------------------------

### GET /api-access/{hashedKeyId}

Source: https://context7.com/fileverse/fileverse-storage-v2/llms.txt

Retrieves stored encrypted API access key materials by their hashed key ID. This endpoint allows fetching stored credentials.

```APIDOC
## GET /api-access/{hashedKeyId}

### Description
Retrieve stored encrypted API access key materials by hashed key ID. This endpoint allows fetching stored credentials.

### Method
GET

### Endpoint
/api-access/{hashedKeyId}

### Parameters
#### Path Parameters
- **hashedKeyId** (string) - Required - The hashed ID of the API access key to retrieve.

### Response
#### Success Response (200)
- **id** (string) - The identifier of the API access key.
- **encryptedKeyMaterial** (string) - The encrypted key material.
- **encryptedAppMaterial** (string) - The encrypted application-specific material.

#### Response Example
```json
{
  "id": "hashed-key-id",
  "encryptedKeyMaterial": "encrypted-key-data...",
  "encryptedAppMaterial": "encrypted-app-data..."
}
```

#### Error Response (404 Not Found)
- **code** (integer) - HTTP status code 404.
- **message** (string) - Error message indicating that the API access was not found.

#### Error Response Example
```json
{
  "code": 404,
  "message": "API access not found"
}
```
```

--------------------------------

### Get Storage Usage

Source: https://context7.com/fileverse/fileverse-storage-v2/llms.txt

Retrieves the current storage usage, limits, and extra storage details for one or more contract addresses. Supports both legacy and modern contract types.

```APIDOC
## GET /limit/use

### Description
Retrieves the current storage usage, storage limits, and any extra storage allocated for one or more contract addresses. This endpoint supports querying multiple contracts by providing a comma-separated list of addresses.

### Method
GET

### Endpoint
/limit/use

### Parameters
#### Headers
- **Contract** (string) - Required - One or more contract addresses (comma-separated) to check storage usage for.
- **Invoker** (string) - Required - The invoker's address.
- **Chain** (string) - Required - The chain ID.

### Request Example
```bash
curl -X GET http://localhost:3000/limit/use \
  -H "Contract: 0x1234567890abcdef1234567890abcdef12345678,0xanothercontract..." \
  -H "Invoker: 0xabcdef1234567890abcdef1234567890abcdef12" \
  -H "Chain: 1"
```

### Response
#### Success Response (200)
- **storageLimit** (integer) - The total storage limit across all queried contracts in bytes.
- **extraStorage** (integer) - The total amount of extra storage allocated across all queried contracts in bytes.
- **storageUse** (integer) - The total current storage usage across all queried contracts in bytes.
- **unit** (string) - The unit of measurement for storage values (e.g., 'bytes').
- **contractAddress** (string) - A comma-separated string of the contract addresses queried.

#### Response Example
```json
{
  "storageLimit": 200000000,
  "extraStorage": 50000000,
  "storageUse": 15000000,
  "unit": "bytes",
  "contractAddress": "0x1234567890abcdef1234567890abcdef12345678,0xanothercontract..."
}
```
```

--------------------------------

### GET /semaphore/group/{groupId}

Source: https://context7.com/fileverse/fileverse-storage-v2/llms.txt

Retrieves the members of a Semaphore group, which is utilized for privacy-preserving floppy token distribution. This endpoint allows querying group membership.

```APIDOC
## GET /semaphore/group/{groupId}

### Description
Retrieve members of a Semaphore group used for floppy token privacy. This endpoint allows querying group membership.

### Method
GET

### Endpoint
/semaphore/group/{groupId}

### Parameters
#### Path Parameters
- **groupId** (string) - Required - The ID of the Semaphore group whose members are to be retrieved.

### Response
#### Success Response (200)
- **groupMembers** (array of strings) - A list of commitments representing the members of the Semaphore group.

#### Response Example
```json
{
  "groupMembers": [
    "commitment1...",
    "commitment2...",
    "commitment3..."
  ]
}
```
```

--------------------------------

### Get Semaphore Group Members (Shell)

Source: https://context7.com/fileverse/fileverse-storage-v2/llms.txt

Retrieves the members (commitments) of a Semaphore group, which is used for privacy-preserving floppy token distribution. Requires the group ID. Returns a list of group member commitments.

```shell
curl -X GET http://localhost:3000/semaphore/group/12345
```

--------------------------------

### Publish File to Community Marketplace

Source: https://context7.com/fileverse/fileverse-storage-v2/llms.txt

Publishes a file to the community marketplace, making it discoverable by other users. Requires a valid file link from allowed origins and includes details like thumbnail, title, category, and user information.

```bash
curl -X POST http://localhost:3000/community/publish \
  -H "Content-Type: application/json" \
  -H "Contract: 0x1234567890abcdef1234567890abcdef12345678" \
  -H "Invoker: 0xabcdef1234567890abcdef1234567890abcdef12" \
  -d '{
    "publishedBy": "0xabcdef1234567890abcdef1234567890abcdef12",
    "thumbnailIPFSHash": "QmThumbnail...",
    "title": "My Shared Document",
    "category": "docs",
    "fileLink": "https://sheets.fileverse.io/0x1234.../file-123",
    "dsheetId": "file-123",
    "userHash": "user-hash-abc",
    "portalAddress": "0x1234567890abcdef1234567890abcdef12345678"
  }'
```

--------------------------------

### POST /community/publish

Source: https://context7.com/fileverse/fileverse-storage-v2/llms.txt

Publishes a file to the community marketplace. Requires file details and valid links.

```APIDOC
## Publish Community File

### Description
Publishes a file to the community marketplace for discovery by other users. Requires valid file link from allowed origins.

### Method
POST

### Endpoint
/community/publish

### Headers
- **Content-Type** (string) - Required - `application/json`
- **Contract** (string) - Required - The contract address.
- **Invoker** (string) - Required - The invoker address.

### Request Body
- **publishedBy** (string) - Required - The address of the publisher.
- **thumbnailIPFSHash** (string) - Required - The IPFS hash of the thumbnail.
- **title** (string) - Required - The title of the file.
- **category** (string) - Required - The category of the file.
- **fileLink** (string) - Required - The direct link to the file.
- **dsheetId** (string) - Required - The dSheet ID of the file.
- **userHash** (string) - Required - The user's hash.
- **portalAddress** (string) - Required - The portal address.

### Request Example
```json
{
  "publishedBy": "0xabcdef1234567890abcdef1234567890abcdef12",
  "thumbnailIPFSHash": "QmThumbnail...",
  "title": "My Shared Document",
  "category": "docs",
  "fileLink": "https://sheets.fileverse.io/0x1234.../file-123",
  "dsheetId": "file-123",
  "userHash": "user-hash-abc",
  "portalAddress": "0x1234567890abcdef1234567890abcdef12345678"
}
```

### Response
#### Success Response (200)
- **_id** (string) - The unique identifier of the published file.
- **publishedBy** (string) - The address of the publisher.
- **thumbnailIPFSHash** (string) - The IPFS hash of the thumbnail.
- **title** (string) - The title of the file.
- **category** (string) - The category of the file.
- **fileLink** (string) - The direct link to the file.
- **dsheetId** (string) - The dSheet ID of the file.
- **timeStamp** (integer) - The timestamp of publication.
```

--------------------------------

### List Community Files with Filters

Source: https://context7.com/fileverse/fileverse-storage-v2/llms.txt

Lists community files with support for pagination and filtering by category, search terms, and favorite status. Results are sorted by the number of favorites. Requires the invoker's address.

```bash
curl -X GET "http://localhost:3000/community/list?page=1&limit=10&category=docs&search=report&onlyFavorites=false&publishedBy=0xabcdef..." \
  -H "Invoker: 0xabcdef1234567890abcdef1234567890abcdef12"
```

--------------------------------

### List Floppy Tokens (Shell)

Source: https://context7.com/fileverse/fileverse-storage-v2/llms.txt

Lists all available floppy tokens for a given contract, optionally filtered by identity commitment. Requires UCAN token, contract address, invoker address, and chain ID. Returns a list of floppy tokens with their details.

```shell
curl -X GET "http://localhost:3000/floppy/list?identityCommitment=12345..." \
  -H "Authorization: Bearer <ucan_token>" \
  -H "Contract: 0x1234567890abcdef1234567890abcdef12345678" \
  -H "Invoker: 0xabcdef1234567890abcdef1234567890abcdef12" \
  -H "Chain: 1"
```

--------------------------------

### POST /floppy/claim

Source: https://context7.com/fileverse/fileverse-storage-v2/llms.txt

Claims a floppy storage token using a short code and identity commitment.

```APIDOC
## Claim Floppy

### Description
Claims a floppy storage token using a short code and identity commitment for Semaphore-based privacy.

### Method
POST

### Endpoint
/floppy/claim

### Headers
- **Authorization** (string) - Required - Bearer token (`Bearer <ucan_token>`)
- **Contract** (string) - Required - The contract address.
- **Invoker** (string) - Required - The invoker address.
- **Chain** (string) - Required - The chain ID.
- **Content-Type** (string) - Required - `application/json`

### Request Body
- **shortCode** (string) - Required - The short code for claiming the floppy token.
- **identityCommitment** (string) - Required - The identity commitment for Semaphore.

### Request Example
```json
{
  "shortCode": "FLOPPY123",
  "identityCommitment": "12345678901234567890..."
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the claim was successful.
- **data** (object) - Details of the claimed floppy token.
  - **shortCode** (string) - The short code used.
  - **sgid** (string) - The semaphore group ID.
  - **name** (string) - The name of the storage offer.
  - **diskSpace** (integer) - The amount of disk space granted.
```

--------------------------------

### Storage Management API Endpoints

Source: https://github.com/fileverse/fileverse-storage-v2/blob/main/README.md

Illustrates the HTTP requests for checking storage status, retrieving storage usage, and extending storage quotas.

```http
GET /limit/check
Contract: <contract_address>
Invoker: <invoker_address>
Chain: <chain_id>

GET /limit/use
Contract: <contract_address>
Invoker: <invoker_address>
Chain: <chain_id>

PUT /limit/extend
Contract: <contract_address>
Invoker: <invoker_address>
Chain: <chain_id>
```

--------------------------------

### POST /floppy/redeem

Source: https://context7.com/fileverse/fileverse-storage-v2/llms.txt

Redeems a claimed floppy token using a Semaphore zero-knowledge proof to add storage to a contract.

```APIDOC
## Redeem Floppy

### Description
Redeems a claimed floppy token using a Semaphore zero-knowledge proof to add storage to a contract.

### Method
POST

### Endpoint
/floppy/redeem

### Headers
- **Authorization** (string) - Required - Bearer token (`Bearer <ucan_token>`)
- **Contract** (string) - Required - The contract address.
- **Invoker** (string) - Required - The invoker address.
- **Chain** (string) - Required - The chain ID.
- **Content-Type** (string) - Required - `application/json`

### Request Body
- **shortCode** (string) - Required - The short code of the claimed floppy token.
- **proof** (object) - The Semaphore zero-knowledge proof.
  - **merkleRoot** (string) - The Merkle root of the group.
  - **nullifierHash** (string) - The nullifier hash.
  - **signal** (string) - The signal associated with the proof.
  - **externalNullifier** (string) - The external nullifier.
  - **solidityProof** (array) - The proof components for Solidity.
- **identityCommitment** (string) - Required - The identity commitment used during claim.

### Request Example
```json
{
  "shortCode": "FLOPPY123",
  "proof": {
    "merkleRoot": "0x...",
    "nullifierHash": "0x...",
    "signal": "storage-claim",
    "externalNullifier": "0x...",
    "solidityProof": ["0x...", "0x...", "0x...", "0x...", "0x...", "0x...", "0x...", "0x..."]
  },
  "identityCommitment": "12345678901234567890..."
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the redemption was successful.
- **message** (string) - A confirmation message.
```

--------------------------------

### Redeem Floppy Token with ZK Proof (Shell)

Source: https://context7.com/fileverse/fileverse-storage-v2/llms.txt

Redeems a floppy token using a Zero-Knowledge proof. Requires UCAN token, contract address, invoker address, chain ID, and proof details including merkle tree root, nullifier, and message. Returns success status and redeemed token details.

```shell
curl -X POST http://localhost:3000/floppy/redeem \
  -H "Authorization: Bearer <ucan_token>" \
  -H "Contract: 0x1234567890abcdef1234567890abcdef12345678" \
  -H "Invoker: 0xabcdef1234567890abcdef1234567890abcdef12" \
  -H "Chain: 1" \
  -H "Content-Type: application/json" \
  -d '{
    "shortCode": "FLOPPY123",
    "proof": {
      "merkleTreeDepth": 20,
      "merkleTreeRoot": "12345...",
      "nullifier": "67890...",
      "message": "redeem-storage",
      "scope": "floppy-redemption",
      "points": ["point1...", "point2...", "point3...", "point4..."]
    }
  }'
```

--------------------------------

### Storage Management API

Source: https://github.com/fileverse/fileverse-storage-v2/blob/main/README.md

Endpoints for checking storage status, usage, and extending storage quotas.

```APIDOC
## GET /limit/check

### Description
Checks the current storage status and limits for a given contract.

### Method
GET

### Endpoint
/limit/check

### Parameters
#### Headers
- **Contract** (string) - Required - Contract address
- **Invoker** (string) - Required - Invoker address
- **Chain** (string) - Required - Chain ID

### Response
#### Success Response (200)
- **status** (string) - Current storage status (e.g., 'ok', 'warning', 'exceeded')
- **used** (integer) - Storage used in bytes
- **limit** (integer) - Storage limit in bytes

#### Response Example
```json
{
  "status": "ok",
  "used": 512000,
  "limit": 1048576
}
```

## GET /limit/use

### Description
Retrieves the current storage usage details for a given contract.

### Method
GET

### Endpoint
/limit/use

### Parameters
#### Headers
- **Contract** (string) - Required - Contract address
- **Invoker** (string) - Required - Invoker address
- **Chain** (string) - Required - Chain ID

### Response
#### Success Response (200)
- **used** (integer) - Storage used in bytes
- **limit** (integer) - Storage limit in bytes

#### Response Example
```json
{
  "used": 512000,
  "limit": 1048576
}
```

## PUT /limit/extend

### Description
Extends the storage quota for a given contract.

### Method
PUT

### Endpoint
/limit/extend

### Parameters
#### Headers
- **Contract** (string) - Required - Contract address
- **Invoker** (string) - Required - Invoker address
- **Chain** (string) - Required - Chain ID

### Response
#### Success Response (200)
- **message** (string) - Confirmation message indicating storage extension
- **newLimit** (integer) - The new storage limit in bytes

#### Response Example
```json
{
  "message": "Storage limit extended successfully.",
  "newLimit": 2097152
}
```
```

--------------------------------

### Create Floppy Token Group (Shell)

Source: https://context7.com/fileverse/fileverse-storage-v2/llms.txt

Creates a Semaphore group for distributing floppy tokens with privacy-preserving membership. Requires UCAN token, contract address, invoker address, chain ID, and the floppy token's short code. Returns the generated group ID.

```shell
curl -X POST http://localhost:3000/floppy/group \
  -H "Authorization: Bearer <ucan_token>" \
  -H "Contract: 0x1234567890abcdef1234567890abcdef12345678" \
  -H "Invoker: 0xabcdef1234567890abcdef1234567890abcdef12" \
  -H "Chain: 1" \
  -H "Content-Type: application/json" \
  -d '{
    "shortCode": "FLOPPY123"
  }'
```

--------------------------------

### POST /floppy/group

Source: https://context7.com/fileverse/fileverse-storage-v2/llms.txt

Creates a Semaphore group for floppy token distribution, enabling privacy-preserving membership management. This is used to manage access to floppy tokens.

```APIDOC
## POST /floppy/group

### Description
Create a Semaphore group for floppy token distribution with privacy-preserving membership. This is used to manage access to floppy tokens.

### Method
POST

### Endpoint
/floppy/group

### Parameters
#### Headers
- **Authorization** (string) - Required - Bearer token for authentication.
- **Contract** (string) - Required - The contract address.
- **Invoker** (string) - Required - The address of the invoker.
- **Chain** (string) - Required - The chain ID.
- **Content-Type** (string) - Required - Must be `application/json`.

#### Request Body
- **shortCode** (string) - Required - The short code of the floppy token for which to create a group.

### Request Example
```json
{
  "shortCode": "FLOPPY123"
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the group creation was successful.
- **groupId** (string) - The ID of the newly created Semaphore group.

#### Response Example
```json
{
  "success": true,
  "groupId": "semaphore-group-id"
}
```
```

--------------------------------

### File Upload API Endpoints

Source: https://github.com/fileverse/fileverse-storage-v2/blob/main/README.md

Demonstrates the HTTP requests for uploading files, including authenticated uploads requiring UCAN tokens and public uploads.

```http
POST /upload/
Content-Type: multipart/form-data
Authorization: Bearer <ucan_token>
Contract: <contract_address>
Invoker: <invoker_address>
Chain: <chain_id>

file: <file_data>
appFileId: <optional_app_file_id>
sourceApp: <optional_source_app>
ipfsType: <optional_ipfs_type>
tags: <optional_tags_array>

POST /upload/public
Content-Type: multipart/form-data

file: <file_data>

POST /upload/comment
Content-Type: multipart/form-data

file: <file_data>
```

--------------------------------

### Community Files API

Source: https://github.com/fileverse/fileverse-storage-v2/blob/main/README.md

Endpoints for publishing, listing, retrieving, and managing favorite community files.

```APIDOC
## POST /community/publish

### Description
Publishes a file to the community marketplace.

### Method
POST

### Endpoint
/community/publish

### Parameters
#### Request Body
- **publishedBy** (string) - Required - The address of the publisher
- **thumbnailIPFSHash** (string) - Required - The IPFS hash of the thumbnail
- **title** (string) - Required - The title of the file
- **category** (string) - Required - The category of the file
- **fileLink** (string) - Required - The IPFS link to the file
- **dsheetId** (string) - Optional - The dSheet ID associated with the file
- **userHash** (string) - Optional - User-specific hash
- **portalAddress** (string) - Optional - Portal address

### Response
#### Success Response (200)
- **message** (string) - Confirmation message
- **fileId** (string) - The unique identifier of the published community file

#### Response Example
```json
{
  "message": "File published to community successfully.",
  "fileId": "comm_12345"
}
```

## GET /community/list

### Description
Lists community files with optional filtering and pagination.

### Method
GET

### Endpoint
/community/list

### Parameters
#### Query Parameters
- **page** (integer) - Optional - The page number for pagination (default: 1)
- **limit** (integer) - Optional - The number of items per page (default: 10)
- **category** (string) - Optional - Filter by category
- **search** (string) - Optional - Search keyword
- **onlyFavorites** (boolean) - Optional - Filter to show only favorite files (default: false)
- **publishedBy** (string) - Optional - Filter by publisher's address

### Response
#### Success Response (200)
- **files** (array) - An array of community file objects
  - **fileId** (string) - Unique identifier
  - **title** (string) - File title
  - **category** (string) - File category
  - **fileLink** (string) - IPFS link
  - **thumbnailIPFSHash** (string) - Thumbnail IPFS hash
  - **publishedBy** (string) - Publisher's address
  - **isFavorite** (boolean) - Whether the file is favorited by the current user

#### Response Example
```json
{
  "files": [
    {
      "fileId": "comm_12345",
      "title": "Example Document",
      "category": "docs",
      "fileLink": "ipfs://...",
      "thumbnailIPFSHash": "Qm...",
      "publishedBy": "0xabc...",
      "isFavorite": true
    }
  ]
}
```

## GET /community/:dsheetId

### Description
Retrieves details for a specific community file using its dSheet ID.

### Method
GET

### Endpoint
/community/:dsheetId

### Parameters
#### Path Parameters
- **dsheetId** (string) - Required - The dSheet ID of the community file
#### Headers
- **Contract** (string) - Optional - Contract address (may be used for authorization or context)

### Response
#### Success Response (200)
- **fileDetails** (object) - Object containing detailed information about the community file
  - **fileId** (string) - Unique identifier
  - **title** (string) - File title
  - **category** (string) - File category
  - **fileLink** (string) - IPFS link
  - **thumbnailIPFSHash** (string) - Thumbnail IPFS hash
  - **publishedBy** (string) - Publisher's address
  - **dsheetId** (string) - The dSheet ID
  - **userHash** (string) - User hash
  - **portalAddress** (string) - Portal address
  - **isFavorite** (boolean) - Whether the file is favorited by the current user

#### Response Example
```json
{
  "fileDetails": {
    "fileId": "comm_12345",
    "title": "Example Document",
    "category": "docs",
    "fileLink": "ipfs://...",
    "thumbnailIPFSHash": "Qm...",
    "publishedBy": "0xabc...",
    "dsheetId": "sheet_xyz",
    "userHash": "user_hash_123",
    "portalAddress": "0xportal...",
    "isFavorite": true
  }
}
```

## POST /community/favourite

### Description
Toggles the favorite status of a community file for the current user.

### Method
POST

### Endpoint
/community/favourite

### Parameters
#### Request Body
- **dsheetId** (string) - Required - The dSheet ID of the community file
- **isFavourite** (boolean) - Required - Set to true to favorite, false to unfavorite

### Response
#### Success Response (200)
- **message** (string) - Confirmation message

#### Response Example
```json
{
  "message": "File favorited successfully."
}
```
```

--------------------------------

### Community Files API Endpoints

Source: https://github.com/fileverse/fileverse-storage-v2/blob/main/README.md

Shows the HTTP requests for publishing, listing, retrieving, and managing favorite community files.

```http
POST /community/publish
Content-Type: application/json

{
  "publishedBy": "address",
  "thumbnailIPFSHash": "hash",
  "title": "file_title",
  "category": "category",
  "fileLink": "ipfs_link",
  "dsheetId": "sheet_id",
  "userHash": "user_hash",
  "portalAddress": "portal_address"
}

GET /community/list?page=1&limit=10&category=docs&search=keyword&onlyFavorites=false&publishedBy=address

GET /community/:dsheetId
Contract: <contract_address>

POST /community/favourite
Content-Type: application/json

{
  "dsheetId": "sheet_id",
  "isFavourite": true
}
```

--------------------------------

### User Management API

Source: https://github.com/fileverse/fileverse-storage-v2/blob/main/README.md

Endpoint for retrieving user addresses.

```APIDOC
## POST /users/address

### Description
Retrieves the user's address. This endpoint likely requires authentication context.

### Method
POST

### Endpoint
/users/address

### Parameters
(No explicit parameters listed, likely relies on authentication headers or session context)

### Response
#### Success Response (200)
- **address** (string) - The user's blockchain address

#### Response Example
```json
{
  "address": "0x123..."
}
```
```

--------------------------------

### PUT /limit/extend

Source: https://context7.com/fileverse/fileverse-storage-v2/llms.txt

Extends the storage limit for a given contract. Requires Contract and Invoker headers.

```APIDOC
## Extend storage for a contract

### Description
Extends the storage limit for a given contract. Requires Contract and Invoker headers.

### Method
PUT

### Endpoint
/limit/extend

### Headers
- **Contract** (string) - Required - The contract address.
- **Invoker** (string) - Required - The invoker address.
- **Chain** (string) - Required - The chain ID.

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.
- **message** (string) - A message confirming the storage extension.

#### Error Response (e.g., 400)
- **success** (boolean) - Indicates if the operation failed.
- **message** (string) - An error message describing the issue (e.g., "No extendable storage available").
```

--------------------------------

### Batch File Upload

Source: https://context7.com/fileverse/fileverse-storage-v2/llms.txt

Allows for the simultaneous upload of multiple files with UCAN authentication. It supports different file types (GATE, CONTENT, METADATA) identified by filename prefixes and requires contract and invoker details. Returns IPFS hashes for each uploaded file type.

```bash
# Batch upload multiple files
curl -X POST http://localhost:3000/upload/batch \
  -H "Authorization: Bearer <ucan_token>" \
  -H "Contract: 0x1234567890abcdef1234567890abcdef12345678" \
  -H "Invoker: 0xabcdef1234567890abcdef1234567890abcdef12" \
  -H "Chain: 1" \
  -F "files=@GATE_file.json" \
  -F "files=@CONTENT_document.pdf" \
  -F "files=@METADATA_info.json" \
  -F "appFileId=batch-123" \
  -F "sourceApp=dsheet"

# Response:
# {
#   "gateIpfsHash": "QmGate...",
#   "contentIpfsHash": "QmContent...",
#   "metadataIpfsHash": "QmMetadata..."
# }
```

--------------------------------

### POST /floppy/redeem

Source: https://context7.com/fileverse/fileverse-storage-v2/llms.txt

Redeems a floppy token using a ZK proof. This endpoint allows users to redeem storage space associated with a floppy token by providing a valid Zero-Knowledge proof.

```APIDOC
## POST /floppy/redeem

### Description
Redeems a floppy token with ZK proof. This endpoint allows users to redeem storage space associated with a floppy token by providing a valid Zero-Knowledge proof.

### Method
POST

### Endpoint
/floppy/redeem

### Parameters
#### Headers
- **Authorization** (string) - Required - Bearer token for authentication.
- **Contract** (string) - Required - The contract address associated with the floppy token.
- **Invoker** (string) - Required - The address of the invoker.
- **Chain** (string) - Required - The chain ID where the contract is deployed.
- **Content-Type** (string) - Required - Must be `application/json`.

#### Request Body
- **shortCode** (string) - Required - The short code of the floppy token to redeem.
- **proof** (object) - Required - The Zero-Knowledge proof details.
  - **merkleTreeDepth** (integer) - Required - The depth of the Merkle tree.
  - **merkleTreeRoot** (string) - Required - The root of the Merkle tree.
  - **nullifier** (string) - Required - The nullifier for the proof.
  - **message** (string) - Required - The message associated with the redemption.
  - **scope** (string) - Required - The scope of the redemption.
  - **points** (array of strings) - Required - The Merkle path points.

### Request Example
```json
{
  "shortCode": "FLOPPY123",
  "proof": {
    "merkleTreeDepth": 20,
    "merkleTreeRoot": "12345...",
    "nullifier": "67890...",
    "message": "redeem-storage",
    "scope": "floppy-redemption",
    "points": ["point1...", "point2...", "point3...", "point4..."]
  }
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the redemption was successful.
- **data** (object) - Contains details of the redeemed floppy token.
  - **shortCode** (string) - The short code of the redeemed floppy token.
  - **diskSpace** (integer) - The amount of disk space redeemed.
  - **redeemed** (boolean) - Indicates if the token has been redeemed.

#### Response Example
```json
{
  "success": true,
  "data": {
    "shortCode": "FLOPPY123",
    "diskSpace": 100000000,
    "redeemed": true
  }
}
```
```

--------------------------------

### Batch File Upload

Source: https://context7.com/fileverse/fileverse-storage-v2/llms.txt

Allows for the simultaneous upload of multiple files with UCAN authentication. It supports different file types (GATE, CONTENT, METADATA) identified by filename prefixes.

```APIDOC
## POST /upload/batch

### Description
Uploads multiple files in a single request, requiring UCAN authentication. This endpoint supports different file types (e.g., GATE, CONTENT, METADATA) which can be identified by filename patterns.

### Method
POST

### Endpoint
/upload/batch

### Parameters
#### Headers
- **Authorization** (string) - Required - Bearer token for UCAN authentication.
- **Contract** (string) - Required - The contract address associated with the upload.
- **Invoker** (string) - Required - The invoker's address.
- **Chain** (string) - Required - The chain ID.

#### Form Data
- **files** (array of files) - Required - Multiple files to upload. Can include files prefixed with GATE_, CONTENT_, or METADATA_.
- **appFileId** (string) - Optional - A unique identifier for the batch upload.
- **sourceApp** (string) - Optional - The name of the application originating the upload.

### Request Example
```bash
curl -X POST http://localhost:3000/upload/batch \
  -H "Authorization: Bearer <ucan_token>" \
  -H "Contract: 0x1234567890abcdef1234567890abcdef12345678" \
  -H "Invoker: 0xabcdef1234567890abcdef1234567890abcdef12" \
  -H "Chain: 1" \
  -F "files=@GATE_file.json" \
  -F "files=@CONTENT_document.pdf" \
  -F "files=@METADATA_info.json" \
  -F "appFileId=batch-123" \
  -F "sourceApp=dsheet"
```

### Response
#### Success Response (200)
- **gateIpfsHash** (string) - The IPFS hash for the GATE file, if uploaded.
- **contentIpfsHash** (string) - The IPFS hash for the CONTENT file, if uploaded.
- **metadataIpfsHash** (string) - The IPFS hash for the METADATA file, if uploaded.

#### Response Example
```json
{
  "gateIpfsHash": "QmGate...",
  "contentIpfsHash": "QmContent...",
  "metadataIpfsHash": "QmMetadata..."
}
```
```

--------------------------------

### POST /api-access/save

Source: https://context7.com/fileverse/fileverse-storage-v2/llms.txt

Saves encrypted API access key materials for secure key management. This endpoint is used to store sensitive API credentials.

```APIDOC
## POST /api-access/save

### Description
Store encrypted API access key materials for secure key management. This endpoint is used to store sensitive API credentials.

### Method
POST

### Endpoint
/api-access/save

### Parameters
#### Request Body
- **id** (string) - Required - A unique identifier for the API access key (e.g., a hashed key ID).
- **encryptedKeyMaterial** (string) - Required - The encrypted key material.
- **encryptedAppMaterial** (string) - Required - The encrypted application-specific material.

### Request Example
```json
{
  "id": "hashed-key-id",
  "encryptedKeyMaterial": "encrypted-key-data...",
  "encryptedAppMaterial": "encrypted-app-data..."
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the API access key was saved successfully.
- **id** (string) - The identifier of the saved API access key.

#### Response Example
```json
{
  "success": true,
  "id": "hashed-key-id"
}
```

#### Error Response (409 Conflict)
- **code** (integer) - HTTP status code 409.
- **message** (string) - Error message indicating that the key already exists.

#### Error Response Example
```json
{
  "code": 409,
  "message": "API access key with id hashed-key-id already exists"
}
```
```

--------------------------------

### File Management API

Source: https://github.com/fileverse/fileverse-storage-v2/blob/main/README.md

Endpoint for deleting files.

```APIDOC
## DELETE /file/:appFileId

### Description
Deletes a file associated with a specific application file ID.

### Method
DELETE

### Endpoint
/file/:appFileId

### Parameters
#### Path Parameters
- **appFileId** (string) - Required - The application-specific file identifier
#### Headers
- **Contract** (string) - Required - Contract address

### Response
#### Success Response (200)
- **message** (string) - Confirmation message indicating successful deletion

#### Response Example
```json
{
  "message": "File deleted successfully."
}
```
```